develop

Phase 4 of the Forge pipeline. The Lead Developer executes the approved execution plan. Lane decomposition should already exist from Phase 3 (Plan); this phase turns that plan into implemented, reviewed, and merged code. Each developer/publisher works in an isolated git worktree — physical file-system separation, not just branches. All code goes through a 3-tier PR-based review pipeline with code-rules enforcement. The first merged PR becomes the "living standard" that all subsequent PRs must match. Lane orchestration is runtime-backed: `.forge/runtime.json` stores the lane graph, owners, statuses, active worktrees, handoff notes, and review/merge/rebase signals. Common Forge paths should update that runtime automatically through the standard helpers, but the process remains human-led and review-gated; it is not an autonomous merge bot. This is harness engineering, not progress narration: once implementation begins, the harness should keep pushing until the approved scope is merged and handed to QA, unless an actual external blocker or customer-owned ambiguity prevents completion.

<Use_When>

• Automatically invoked after Phase 3 (plan) completes
• state.json phase=4 / phase_id="develop" </Use_When>

<Core_Rules>

1. Every developer works in their own git worktree (physical isolation)
2. No Evidence, No Code — developers must verify via fact-checker before writing
3. Code that violates code-rules.md = REJECTED
4. Code inconsistent with already-merged code = REJECTED
5. First merged PR becomes the "living standard"
6. Developers load ONLY: spec subset + relevant contracts + code-rules.md (minimal context)
7. Every created worktree/task must have a runtime lane record before dispatch
8. Handoff notes are required before review or reassignment
9. Explicit review, merge, and rebase states must be reflected in runtime
10. Zero merge debt before new scope — approved or merge-ready lanes must be landed before starting more implementation work unless a blocker is explicitly recorded
11. Finish before handoff — if the current scope can be completed now, complete it now. Session handoff notes preserve continuity; they do not justify stopping early </Core_Rules>

<Hybrid_Dispatch> Forge uses a 3-layer dispatch model. AgentRecommendation from scripts/lib/forge-state.mjs classifies agents automatically into the appropriate layer. Choose the lightest layer that meets the need.

Layer 0 — Prompt Switch (in-conversation): Lead-dev operates in the main conversation, not as a separate subagent. Claude switches to the lead-dev role by loading agents/lead-dev.md context. Use for: task splitting, lane-graph management, code review, merge decisions. No isolation needed — the lead works on the main branch.

Layer 1 — Team (iterative collaboration): When multiple agents need multi-turn back-and-forth (e.g., Developer ↔ Lead review cycles), use TeamCreate + SendMessage. Use for: review rounds, design discussions, cross-lane coordination. Context is preserved across rounds — no re-dispatch needed.

Layer 2 — Isolated Subagent (parallel execution): Developers and fact-checkers dispatch with Agent tool using isolation: "worktree" or subagent_type: "forge:developer" / "forge:fact-checker". Use for: module implementation, technical verification. Each agent gets its own worktree and minimal context. </Hybrid_Dispatch>

<Progressive_Disclosure>

• Load references/review-pipeline.md when you need the full review tiers or worktree rules.
• Load references/lane-runtime.md when you need the standard runtime helper commands and lane graph rules. </Progressive_Disclosure>

-1. **Analysis freshness check** - Read analysis metadata — if saved analysis is stale or missing for an existing-code path, route to `forge:analyze` first.

0. Handoff Interview — Implementation Intake (tier-aware, see references/handoff-interview.md) a. Lead Developer reads plan, tasks, architecture, contracts, code-rules, components, tokens. b. At the top of each .forge/tasks/{lane}.md brief (or plan.md for cross-lane issues), Lead records any blockers that prevent dispatch (ambiguous lane boundaries, missing contracts, unclear dependency order, unknown test strategy) and any consequential assumptions. Free-form bullets, no structured Q template. Convert non-consequential uncertainty into fact-check tasks or QA checks, not questions. c. For each blocker, Lead pings the owner directly via SendMessage (CTO for architecture/contract, Designer for UX, PM for spec intent). No CEO triage hop. d. At full tier only, additionally write .forge/handoff-interviews/develop.md (phase gate enforces this). e. Blockers resolved → dispatch begins. The task briefs are the understanding record; no separate statement, no two-party sign-off for no-blocker cases.

1. Lead Developer reads:

   • .forge/plan.md
   • .forge/tasks/*.md
   • .forge/design/architecture.md
   • .forge/contracts/*.ts
   • .forge/code-rules.md

2. Dispatch Analyst (forge:analyst) for impact analysis when the saved planning analysis is stale or incomplete:

   • Analyst uses codebase-memory-mcp (search_graph, trace_call_path, get_architecture) to map existing module boundaries and dependencies
   • Output: impact report showing which existing code will be affected by each planned lane
   • Lead uses this to validate the existing lane graph before dispatch
   • Skip if project is greenfield (no existing codebase to analyze)

3. Lead validates the planning output before dispatch:

   • every active lane has scope
   • every lane has a linked task brief
   • dependencies reflect the execution order from .forge/plan.md
   • no lane is so broad that it will lose coherence in one implementation pass

   If the plan needs refinement:

   • update .forge/plan.md
   • refine lane records in runtime.json
   • update the affected .forge/tasks/{lane}.md

4. For each ready lane, Lead creates a worktree and confirms ownership:

   • Create worktree: node scripts/forge-worktree.mjs create --lane {id} --branch forge/{id}
   • Ensure runtime lane record points at the worktree path
   • Assign owner after the worktree exists: node scripts/forge-lane-runtime.mjs assign-owner --lane {module} --owner {agent}

5. Lead dispatches agents per execution batch: Use the execution order already defined in .forge/plan.md / runtime dependencies.

   For each batch, dispatch all lanes simultaneously:

   Agent(
     subagent_type="forge:developer",  // or "forge:publisher" for UI lanes
     isolation="worktree",
     run_in_background=true,
     prompt="Implement lane {id}: {title}. Follow .forge/code-rules.md and .forge/contracts/."
   )
   

   The subagent-start hook automatically injects lane-scoped context:

   • Lane scope (file patterns to work on)
   • Lane dependencies (what this depends on)
   • Model hint (sonnet for implementation, opus for review)
   • Task file content (up to 2000 chars)

   Wait for each batch to complete before starting the next batch. If the task contains separable UI/API/state/test surfaces, split it so compatible lanes run in parallel. If the task is truly single-scope, keep one lane and drive it to completion instead of manufacturing coordination overhead. If any lane in the batch reaches review_state=approved, merge_state=ready, or merge_state=queued, stop opening more implementation scope and land that lane first. Merge debt is a control-tower blocker, not background work for later. Batches with dependencies must run sequentially; lanes within a batch run in parallel.

6. Lead monitors completion:

   node scripts/forge-lane-runtime.mjs summarize-lanes --json
   

   • When all lanes in a batch are merged/done → start next batch
   • If a lane is blocked for 3+ iterations → escalate to CEO
   • When ALL lanes are merged → transition to Phase 5 (QA)

   Context budget (see references/context-budget.md):

   • T0 (mandatory): tasks/{module}.md, contracts/{relevant}.ts, code-rules.md
   • T1 (relevant): living standard reference (patterns from first merged PR)
   • T2 (on-demand): architecture.md (module boundaries section only)
   • EXCLUDED: full spec, other modules' tasks, design docs, other worktrees

7. Each developer implements their module: a. Read assigned task definition (.forge/tasks/{module}.md) b. Read relevant contracts (.forge/contracts/) c. Read code-rules.md d. Fact-check any uncertain technical claims before coding e. Update lane status to in_progress f. Implement the module g. Run tests locally in the worktree h. Write a handoff note before review: node scripts/forge-lane-runtime.mjs write-handoff --lane {module} --note "{verification summary}" i. Update lane status to in_review j. If review requests changes, or the lane needs merge/rebase follow-up, reflect that state in runtime immediately instead of leaving it implicit in chat. k. Create PR when all local tests pass

8. PR Review Pipeline (3 tiers):

   Teams-based review (recommended for multi-turn feedback):

   • Create a review team: TeamCreate(team_name="forge-review-{module}")
   • Add Developer and Lead as team members
   • Tier 2 review via SendMessage: Lead -> Developer: "Please align to fetchUser()" (specific correction) Developer -> Lead: "Fixed, please re-review" Lead -> Developer: "LGTM" -> merge
   • Benefits: context preserved across review rounds, no re-dispatch needed
   • Handoff notes still required in forge-lane-runtime.mjs (audit trail)

   Sequential review (fallback — ALL tiers must approve):

   Tier 1 — Automated Checks (instant):

   • Lint passes
   • TypeScript typecheck passes
   • All tests pass
   • No secrets or credentials in diff -> Fail = instant reject, developer fixes and resubmits

   Tier 2 — Lead Developer Review:

   • code-rules.md compliance (naming, patterns, structure)
   • Consistency with already-merged code
   • Contract implementation correctness
   • No scope creep (only touches files in task definition) -> Violate = reject with specific instructions: "Developer B uses fetchUser() but you used getUser(). Please align to fetchUser()"

   Tier 3 — CTO Review (architecture):

   • Module fits the overall architecture
   • No hidden coupling or circular dependencies
   • Performance and scalability concerns
   • Only invoked if Lead flags architectural concerns -> Reject = CTO provides redesign guidance

   All tiers approve -> mark the lane review-approved / merge-ready in runtime, then merge to main:

   node scripts/forge-lane-runtime.mjs mark-review-state --lane {module} --state approved --note "Lead/CTO review approved"
   node scripts/forge-lane-runtime.mjs mark-merge-state --lane {module} --state ready --note "Ready to merge after review approval"
   

   Leaving approved lanes unmerged creates merge debt and weakens the living standard for later lanes.

9. After each merge, update the lane record, then rebase all other active worktrees:

   IMPORTANT — commit-based merge only (no diff/patch): NEVER use git diff | git apply or git format-patch to integrate lane work. Uncommitted worktree changes applied via text patches lose git's 3-way merge capability and break when multiple lanes touch the same file. Always use the commit → merge → rebase pipeline below.

   Preferred — automated merge-lane command (commits + merges + rebases in one step):

   node scripts/forge-worktree.mjs merge-lane --lane {module}
   node scripts/forge-lane-runtime.mjs update-lane-status --lane {module} --status merged --note "Merged to main"
   node scripts/forge-lane-runtime.mjs update-lane-status --lane {module} --status done --note "Worktree cleaned up"
   

   merge-lane automatically: (a) commits any uncommitted changes, (b) merges the lane branch into main with --no-ff, (c) rebases all remaining active worktrees onto main.

   Fallback — manual steps (if merge-lane hits an edge case):

   cd .forge/worktrees/{module} && git add -A && git commit -m "feat: {module} implementation"
   git checkout main && git merge forge/{module} --no-ff
   cd .forge/worktrees/{other-module} && git rebase main
   

   Pre-merge check — before starting the merge sequence, verify all worktrees are committed:

   node scripts/forge-worktree.mjs pre-merge
   

   • Do not accumulate multiple approved lanes for a later mega-merge. The moment a lane is approved or merge-ready, land it, rebase the remaining worktrees, and only then continue the next batch.
   • If rebase conflicts: developer resolves in their worktree
   • If conflict is architectural: escalate to Lead
   • If a lane is waiting on rebase, mark that in runtime so status/continue can surface it as an active control-tower signal.

10. Repeat steps 7-9 until all PRs are merged

    • Use node scripts/forge-lane-runtime.mjs summarize-lanes to review the lane graph and blocked lanes
    • Update the session handoff only as a safety checkpoint for host interruption or context-risk recovery
    • Do not surface "continue later" language while completion is still achievable in the current run
    • The only proactive checkpoint exception is when the active agent context is so expanded that continuing would likely cause guesswork or hallucination; in that case, write a precise checkpoint, narrow the next step, and resume with fresh context

11. Cleanup worktrees: node scripts/forge-worktree.mjs remove --lane {module} (for each completed module)

12. Update state.json: phase=5, phase_name="qa"

    • Update company runtime for QA: node scripts/forge-lane-runtime.mjs set-company-gate --gate qa --gate-owner qa --delivery-state in_progress
    • Update session handoff toward QA: node scripts/forge-lane-runtime.mjs write-session-handoff --summary "{what remains to verify}" --next-goal "Run QA and classify blockers" --next-owner qa

13. Create git tag: forge/v1-dev

14. Transition to Phase 5 (forge:qa)

<Worktree_Management> Create worktree: node scripts/forge-worktree.mjs create --lane {module} --branch forge/{module}

List active worktrees: node scripts/forge-worktree.mjs list

Rebase worktree after merge: cd .forge/worktrees/{module} && git rebase main

Remove worktree after merge: node scripts/forge-worktree.mjs remove --lane {module}

Prune stale worktrees: node scripts/forge-worktree.mjs prune </Worktree_Management>

<Lane_Runtime> Lane graph summary: node scripts/forge-lane-runtime.mjs summarize-lanes

Assign lane owner: node scripts/forge-lane-runtime.mjs assign-owner --lane {module} --owner {agent}

Update lane status: node scripts/forge-lane-runtime.mjs update-lane-status --lane {module} --status in_progress --note "{status note}"

Write handoff note: node scripts/forge-lane-runtime.mjs write-handoff --lane {module} --note "{handoff summary}"

Review and merge states:

• Keep in_review, blocked, merged, and done current in runtime as the lane moves through review and integration.
• Use runtime notes to capture rebase blockers, reviewer requests, and merge completion. </Lane_Runtime>

<PR_Review_Checklist> Tier 1 — Automated: [ ] Lint: no warnings, no errors [ ] TypeScript: tsc --noEmit passes [ ] Tests: all test suites pass [ ] Secrets: no API keys, tokens, or credentials in diff [ ] Build: project builds successfully

Tier 2 — Lead Developer: [ ] Naming conventions match code-rules.md [ ] File structure matches code-rules.md [ ] Import patterns match code-rules.md [ ] Error handling matches code-rules.md [ ] Consistent with already-merged PRs (the living standard) [ ] Only touches files within assigned task scope [ ] Implements all required interface contracts [ ] No TODO/FIXME/HACK comments left unresolved

Tier 3 — CTO (when flagged): [ ] Module boundaries respected [ ] No circular dependencies introduced [ ] No hidden coupling between modules [ ] Performance implications acceptable [ ] Scalability concerns addressed </PR_Review_Checklist>

<Code_Consistency_Rule> The FIRST merged PR sets the living standard for the entire project.

All subsequent PRs must match:

• Naming: if PR #1 uses fetchUser(), everyone uses fetchUser(), not getUser()
• Patterns: if PR #1 uses try/catch with custom errors, everyone follows
• Structure: if PR #1 puts hooks in /hooks, everyone puts hooks in /hooks
• Imports: if PR #1 uses absolute imports, everyone uses absolute imports
• Types: if PR #1 exports interfaces from /types, everyone does the same

When inconsistency is found, Lead rejects with explicit correction: "The already-merged code uses {pattern}. Please align to this standard:

• Before: {developer's code}
• After: {corrected code}" </Code_Consistency_Rule>

<State_Changes>

• Creates: .forge/runtime.json lane records for each active lane
• Creates: .forge/worktrees/{module}/ (git worktrees, one per task)
• Updates: .forge/tasks/{module}.md (task definitions refined from the planning phase when needed)
• Updates: state.json (phase=5, phase_name="qa")
• Updates: .forge/runtime.json (qa gate + QA session handoff)
• Creates: git tag forge/v1-dev
• Removes: all worktrees after completion </State_Changes>

<Tool_Usage>

• Layer 0: Load agents/lead-dev.md context for task splitting, review, merge decisions
• Layer 1: TeamCreate + SendMessage for iterative Developer <-> Lead review cycles
• Layer 2: Agent tool with subagent_type="forge:developer", isolation="worktree" (parallel, one per module)
• Layer 2: Agent tool with subagent_type="forge:publisher", isolation="worktree" (parallel, for UI modules)
• Layer 2: Agent tool with subagent_type="forge:analyst" for codebase impact analysis
• Layer 2: Agent tool with subagent_type="forge:fact-checker" for technical verification
• Prefer active parallel lanes whenever scopes are independent. Under-using isolated agents on separable work is a harness failure, not a style choice
• Agent tool: dispatch forge:cto for Tier 3 reviews
• Bash tool: git rebase, git tag
• CLI helper: node scripts/forge-worktree.mjs for worktree create/list/remove/prune (manual worktree path)
• CLI helper: node scripts/forge-lane-runtime.mjs for lane graph, owner, status, and handoff updates
• Write tool: create .forge/tasks/{module}.md from templates/task.md
• Read tool: load contracts, code-rules.md, architecture
• Edit tool: update .forge/state.json and .forge/runtime.json </Tool_Usage>

<Failure_Modes_To_Avoid>

• Dispatching lanes before blockers in the handoff artifact are resolved
• Requiring a separate understanding statement or two-party sign-off when no blockers were recorded (obsolete ceremony — the task briefs are the record)
• Developers modifying files outside their worktree scope
• Skipping any tier of code review
• Merging without all 3 tiers approving
• Failing to register a lane in .forge/runtime.json before dispatch
• Leaving lane status stale after ownership, review, or merge changes
• Sending work to review without a handoff note in runtime
• Reassigning a lane without a handoff note in runtime
• Not rebasing other worktrees after a merge
• Leaving orphan worktrees after Phase 4 completes
• Developers loading full project context instead of minimal subset
• Not enforcing code-rules.md on every PR
• Allowing inconsistent patterns between merged PRs
• Letting merge/rebase state drift out of sync with runtime
• Treating helper-backed runtime updates as optional instead of mandatory on the common path
• Starting Phase 5 before all worktrees are cleaned up
• Not creating the forge/v1-dev tag before transition </Failure_Modes_To_Avoid>

<Auto_Chain> When development completes (all lanes merged, worktrees cleaned, forge/v1-dev tag created):

1. Update state.json: phase_id → "qa"
2. IMMEDIATELY invoke Skill: forge:qa Do NOT stop, summarize, or ask the user. State clearly that implementation is complete and move directly to QA. </Auto_Chain>