Help us improve
Share bugs, ideas, or general feedback.
From forge
Automates per-task implementation cycles with steps for reading specs, preparing workspace, implementing, testing, reviewing, and committing.
npx claudepluginhub lucasduys/forge --plugin forgeHow this skill is triggered — by the user, by Claude, or both
Slash command
/forge:executingThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
This skill guides the per-task implementation cycle during `/forge execute`. For each task in the frontier, you follow a structured workflow: read the spec, implement, test, review, commit, and update state. The Stop hook drives task-to-task progression; this skill handles the work within a single task.
Orchestrates task execution with git worktree isolation, TDD implementation, validation loop, and merge for phrases like 'execute task N' or 'implement TASK-NNN'.
Executes scope-aware implementation with TDD and quality gates, scaling from inline plans for small changes to full multi-task workflows for larger work.
Executes tasks from TASK_N.md files or free-form descriptions, auto-generating missing scope, success criteria, and verification plans via /generate-tasks before implementation.
Share bugs, ideas, or general feedback.
This skill guides the per-task implementation cycle during /forge execute. For each task in the frontier, you follow a structured workflow: read the spec, implement, test, review, commit, and update state. The Stop hook drives task-to-task progression; this skill handles the work within a single task.
You will receive:
T003: Registration endpoint + tests).forge/specs/spec-auth.md)quick, standard, or thorough.forge/capabilities.json (optional, informs tool choices).forge/config.json (which repo to work in, conventions to follow)Read current state from .forge/state.md — check what task you are on, what is already done, any in-flight work or key decisions from prior tasks.
Read the frontier from .forge/plans/{spec}-frontier.md — find your current task, understand its dependencies, and what comes after.
Read the spec from .forge/specs/spec-{domain}.md — find the R-numbered requirements and acceptance criteria that this task must satisfy. Identify the exact checkboxes you need to check off.
Read capabilities from .forge/capabilities.json if it exists — check for available MCP servers (Context7 for docs, Playwright for E2E, MongoDB for data inspection) and skills (TDD, systematic debugging, code review).
Cited-docs pass (forge-self-fixes R009). Before moving to Step 2, list every external document the spec references and read each one. Run:
node scripts/forge-tools.cjs list-cited-docs --spec .forge/specs/spec-{domain}.md --repo-root .
The CLI returns a JSON array of { line, path } for absolute, home-relative, and sibling-repo paths. For each returned path, use Read to open the document before writing any implementation code. If a path does not resolve, log a warning to state.md decisions and continue — do NOT fabricate values that were supposed to come from the cited doc. This closes the gap from the 2026-04-21 forge-landing run where the executor fabricated benchmark numbers instead of reading the source doc the spec had cited.
Multi-repo: If the task has a repo: tag, cd into the correct repo directory (from .forge/config.json repos). Read that repo's CLAUDE.md or coding conventions file first.
Single-repo: Stay in the current directory. Read CLAUDE.md if it exists.
Conventions: Note the project's coding style, naming conventions, import patterns, test framework, and commit message format. Follow them exactly.
UI-task detection (forge-self-fixes R003). Run the classifier to decide whether this task needs the design-skill routing:
node scripts/forge-tools.cjs task-classify \
--task-id T00N \
--spec .forge/specs/spec-{domain}.md \
--capabilities .forge/capabilities.json
The output shape is { ui:boolean, brand:string|null, reasons:[...] }. If ui is true you MUST, before writing any component code in Step 3:
Skill("frontend-design") once for general design-quality guidance, ANDbrand is non-null, also invoke the brand-specific skill: Skill("brand-guidelines") for Anthropic, or reference the awesome-design-md catalog for other named brands.DESIGN.md exists at repo root, read it first and cite specific tokens in your component code rather than picking tokens from memory.This is the execution-side counterpart to the R002 DESIGN.md gate in the brainstorming skill. The brainstorm skill wrote the tokens; the executor reads them. The 2026-04-21 forge-landing regression was an executor that wrote an "Anthropic-aesthetic" landing page without either step, so the tokens shipped as approximations. This block closes that loop.
The implementation approach depends on the depth level and available capabilities:
// TODO or throw new Error('not implemented').After implementation, run the test suite:
.forge/state.md with task_status: debugging and describe the failure. The stop hook will switch to systematic DEBUG mode.After tests pass, update .forge/state.md:
task_status: testing in the frontmatter.The stop hook reads this state and decides the next action:
quick: skip review, proceed to commit.standard or thorough: the stop hook will feed a review prompt.When the stop hook feeds a review prompt, review the implementation:
If issues are found:
Once the task passes tests and review (or review is skipped for quick depth):
feat: add user registration endpoint (T003, R001)After committing:
Update the task registry (.forge/task-status.json) — this is the authoritative source for task completion. Either:
node <plugin-root>/scripts/forge-tools.cjs mark-complete --forge-dir .forge --task T003 --commit abc1234.forge/task-status.json to set the task's status to "complete" with the commit hash.Set task_status: complete in .forge/state.md frontmatter.
Move the task from "In-Flight Work" to "What's Done" with the commit hash:
## What's Done
- T003: Registration endpoint + tests (complete, committed abc1234)
Clear the "In-Flight Work" section.
Update "What's Next" to reflect remaining tasks.
Increment iteration in the frontmatter.
The stop hook will then pick up the updated state and either:
Each task moves through these states, tracked in .forge/state.md frontmatter as task_status:
pending → implementing → testing → reviewing → complete
↑ ↓
└── fixing ──┘
↓
debugging (circuit breaker)
↓
blocked (needs human)
When .forge/config.json defines multiple repos:
repo: tag in the frontier.path from the repo config (relative to the .forge/ location).cross_repo_rules.api_first is true, backend tasks are completed before frontend tasks that depend on them. The frontier already enforces this ordering.If .forge/capabilities.json lists available tools, use them when relevant:
| Capability | When to Use |
|---|---|
| Context7 MCP | Look up library/framework documentation when implementing unfamiliar APIs |
| Playwright MCP | Run E2E tests for frontend tasks, verify UI behavior |
| MongoDB MCP | Inspect database state during debugging, verify data operations |
| TDD skill | Enforce test-first workflow (activated automatically for thorough depth) |
| Systematic debugging | Use the 4-phase debugging protocol when in DEBUG mode |
| Code review plugin | Enhance the review step with structured review output |
Do not fail if a capability is listed but unavailable at runtime — fall back to manual approaches.
When the stop hook detects multiple unblocked tasks in the same tier, it will instruct you to dispatch them in parallel:
Agent tool with isolation: "worktree"..forge/state.md and .forge/task-status.json with the results from each agent.This only applies when the stop hook explicitly instructs parallel execution. Do not attempt parallel dispatch on your own — let the hook decide based on the frontier tier structure.
.forge/task-status.json after completing a task. This is the programmatic source of truth for task completion — more reliable than markdown parsing..forge/state.md for human-readable progress and context preservation across session resets.