mgratzer/forge/forge-implement

Implement a Change

Implement a feature or fix following project standards.

Input

Primary input ($ARGUMENTS): an Issue number/URL, a plan file path, or free-text description. Optional: -- <additional context> for execution guidance.

Unattended mode: --unattended skips plan approval and proceeds without confirmation prompts. When no person can answer (the prompt says another session or a scheduler started the run, or AskUserQuestion is unavailable or goes unanswered), run unattended even without the flag and say so in your first message.

Process

Step 1: Understand the Work

Report implementing via status-reporting. Determine the input type and extract requirements. Detect the Issue tracker provider (see issue-operations).

• Issue — fetch using the project's Issue tracker (see issue-operations). Parse title, requirements, acceptance criteria, labels, sub-issues, comments. Add labels if missing. When the Issue has sub-issues, treat each as a separate task and close them as you complete them.
• Plan file — extract goals, requirements, constraints, acceptance criteria.
• Free-text — parse scope and constraints.

Ask for clarification when requirements are too vague or dependencies too incomplete to plan confidently; in unattended mode, proceed on explicitly stated assumptions instead.

For an Issue, check open work before planning, following open-work. When a prerequisite is unmet or an open PR is already for this Issue, name each one and its state, and ask via AskUserQuestion whether to proceed. In unattended mode: stop and report needs-human with them. Keep the other open PRs' files for the plan.

Step 2: Plan Approach

Identify durable architectural decisions — data model, API contracts, and module boundaries that absorb change instead of exposing internals (see deep-modules).

For complex work, delegate codebase research to a sub-agent for unbiased answers:

Research (delegate)

Write 3–7 factual questions about existing systems, patterns, and integration points. Each asks how something works today; if a reader could guess the goal from it, rewrite it. Pass the Issue's pointers to what already exists (file paths, packages, library docs) verbatim, never links to the Issue, a PR, or a spec of the change. Delegate to a forge-scout sub-agent that receives only the questions and pointers. If no sub-agent support, read the role file and answer each question following its rules.

Inputs provided to sub-agent: Role: forge-scout, the research questions, the pointers, codebase access. Expected output: One factual answer per question, with file paths and code references.

Prefer a cheap fast model for scout work when the runtime supports per-task model choice.

From the research, create a plan:

• Durable decisions
• Structure outline — vertical phases, each spanning all affected layers they need and ending with a verification step. Phase 1 proves the happy path end to end; later phases add one axis of complexity at a time. When a text view shows a phase's target shape better than words, include it (see visuals).
• Files to create or modify
• Open PRs these files conflict with (see open-work), each with what it shares; the PR's Notes repeat them
• Scope boundaries (what will NOT change)

Present the plan via AskUserQuestion. Get user confirmation before coding. In unattended mode: skip AskUserQuestion and proceed. When the user changes the Plan after approving it, record each change as a revision (see pr-body); a design they reject goes through design-rounds first.

Step 3: Create Feature Branch

git fetch origin
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@')
git rev-list --count origin/$DEFAULT_BRANCH..HEAD   # 0 on a non-default branch → a worktree tool prepared it; stay on it

Otherwise branch off the fetched default branch without switching to it — this also works inside a worktree, where the default branch is checked out elsewhere:

git checkout --no-track -b <TYPE>/<ISSUE_NUMBER>-<BRIEF_DESCRIPTION> origin/$DEFAULT_BRANCH

When working from a plan file or free-text (no Issue number), use a descriptive slug: <TYPE>/<BRIEF_DESCRIPTION>.

Step 4: Implement

Read AGENTS.md first. Follow project conventions strictly.

Execute the work in vertical phases following phase-execution: pre-flight validation before the first phase, code and tests together within each phase, and a phase gate — tests pass, no new lint/type failures, one committed logical change — before the next.

Note each deviation from the Step 2 Plan and why as it happens; the PR states each one.

Step 5: Audit Pattern Consistency

If you changed a pattern (error handling, component structure, API convention), grep for every other file using the old pattern and update them too — audit the pattern shape, not just a literal string. See pattern-audit.

Step 6: Update Documentation

Update docs/*.md and AGENTS.md if behavior or conventions changed.

Step 7: Run Final Quality Gate

Run all project quality checks (discover from AGENTS.md, project docs, or repository scripts):

• [ ] Lint — no violations
• [ ] Format — no violations
• [ ] Type check — no errors
• [ ] All tests pass
• [ ] Test coverage ≥ 90% for new/modified code — run the project's coverage tool. If coverage tooling is not configured, flag this to the user and offer to set it up.

Fix issues and commit fixes.

Step 8: Exercise the Change

Run the app and use the changed path once, plus one failure case, following exercise. Fix what it finds, with a test, before opening the PR.

Step 9: Push and Create PR

git push -u origin <BRANCH_NAME>

Create the PR with a conventional commit title and the body from pr-body. The why comes from the linked Issue's problem statement, or the commit history when none is linked; in unattended mode, the assumptions you proceeded on go under Notes. An unattended run on a HITL Issue, or one with no recorded execution mode, lists its judgment calls there too. Close the Issue when one exists.

Pass the body on stdin via a quoted heredoc — an inline --body "..." mangles multi-line text, backticks, and quotes:

gh pr create --title "<TYPE>(<SCOPE>): <DESCRIPTION>" --body-file - <<'PR_EOF'
<PR body>
PR_EOF

Step 10: Summarize

Report: branch name, PR link, commits made, files changed, tests added, docs updated, exercise outcome, the Try it line from ## Exercised, deferred items.

Guidelines

• Explore before coding — research the codebase before committing to an approach
• Ask when unsure — better to clarify than implement wrong; unattended runs state their assumptions and proceed
• Don't scope creep — implement what was asked, nothing more

Related Skills

After implementing: Use forge-reflect to self-review before requesting review. Single invocation: Use forge-ship to implement and review in one step.

Example Usage

/forge-implement 123
/forge-implement 123 -- keep the diff minimal and prefer existing UI patterns
/forge-implement --unattended 123
/forge-implement docs/roadmap.md
/forge-implement add a dark mode toggle to the settings page