source: .forge/guides/forge-harness-faq.md · generated — edit the markdown, not this file

Forge Harness FAQ

Common questions about working in this harness, answered for the team. A companion to the authoritative docs, not a replacement — where this FAQ and the harness’s own rules disagree, the rules win: .claude/CLAUDE.md, the path-scoped rules in .claude/rules/, the full methodology in ../forge-harness-framework.md, and the day-to-day ../team-guide.md are the live contract. Add new Q&A as the team learns.

Contents

Discovery & gates

  1. How is the PRD structured, and how do I resolve an open question?
  2. Where do decisions get recorded?
  3. How does design / UI context enter the harness?
  4. What is the gate order, and why does it matter?
  5. What if a hook silently skips on my machine?

Implementation 6. How is work sequenced across phases? 7. What is the flow from a decomposed stub to a shipped feature? 8. What should I check hardest at the human gates? 9. Which Claude model and effort should I run? 10. When should I start a fresh Claude session? 11. Can I work on features in different delivery phases at once?


1. How is the PRD structured, and how do I resolve an open question?

The PRD is split across three files (the “trichotomy”):

  • project-prd.md — the live contract: problem, scope, in-scope features, NFRs, risks. This is the file you edit for contract changes.
  • project-prd-signals.md — open (⏳) and partial (◐) open questions only. Never add an open question to project-prd.md — the guard-prd-shape.sh hook blocks it.
  • project-prd-history.md — append-only audit trail of resolved open questions and revisions.

When an open question is answered, four writes happen together:

  1. Fold the answer into the PRD body (or add an Architecture Decision row if it is architectural).
  2. Move the row from signals to history.
  3. Append a ### Rev N revision entry.
  4. Update every other statement of the old answer (git grep it).

Don’t skip step 3 — the Resolved in: Rev N pointer must reference a real revision. Full procedure: ../../.claude/rules/prd.md.

2. Where do decisions get recorded?

Raw inputs (meeting notes, research, inventories) live under .forge/discovery/. Once a decision is settled, cascade it to every artifact that depends on it — and a decision cascades fully, or not at all. An architectural decision goes in the Architecture Decisions (DO NOT REVERSE) table in .claude/CLAUDE.md; the why is one line there with a pointer to the long rationale (which lives once, in architecture.md, .forge/engagement-log.md, or the PRD history). Design intent goes in .forge/design/architecture.md. The one-sentence-rule / rationale-lives-once discipline is in .claude/CLAUDE.md § Compounding Engineering.

3. How does design / UI context enter the harness?

This project has a design reference — the client-approved prototype and the design-system spec — so UI work is held to it. The design system is ../design/ui/design-system.md (semantic tokens, components, screen conventions); the browsable prototypes are under .forge/design/prototypes/ (double-click, no server). A user-facing spec cites the design-system spec and the prototype in its ## Input Sources and states observable visual acceptance criteria (name the token / layout / state). A UI plan’s ## UI / Design Adherence section names the tokens, components and screen layouts the work item conforms to. The spec is authoritative over the prototype on any conflict.

4. What is the gate order, and why does it matter?

Spec approved → Plan approved → Implement → Check → Review → Ship → Reflect. No implementation starts without an approved spec and an approved plan — jumping to code before the plan is locked is the classic mistake, because a wrong plan produces wrong code that review can’t cheaply fix. Reviews run through /forge-spec-review and /forge-plan-review (a sub-agent audit, then explicit human approval). The guard-spec-approval and guard-plan-approval hooks block a status flip to approved that lacks the review annotation, so the order can’t be quietly bypassed.

5. What if a hook silently skips on my machine?

The tracker-reading hooks need yq; most others parse stdin with jq. If a tool is missing, those hooks fail open (skip rather than block), which can silently disable gate-state injection and some guards. Install them — macOS: brew install yq jq; Windows: download yq/jq and add them to your PATH. A missing-yq session prints a warning at start. The per-hook detail is in ../../.claude/hooks/README.md.

6. How is work sequenced across phases?

.forge/features.md and tracker.yaml are the source of truth. blocked_by drives execution order — a feature is workable the moment its blockers are done. Delivery phases (delivery_phase) are the stakeholder-facing narrative layered on top, not an execution lock. Critical-path substrates that many features depend on (auth/roles, the account and lead substrates) go earliest. The dependency graph is also the work-division plan across the developers.

7. What is the flow from a decomposed stub to a shipped feature?

/forge-decompose (Gate 3) created one stub spec per feature and populated the tracker — stubs are placeholders, not authored specs. To take one from stub to shipped, run the front door:

/forge-deliver <ticket>

It sequences the whole pipeline — authors the spec, reviews it, decomposes into waves, writes the plans, implements, runs the tests, opens the wave PRs, and reflects — pausing at the human gates. Do not hand-run the per-phase skills; /forge-deliver orders them. See forge-deliver-explained.md for the full walkthrough and forge-deliver-cheatsheet.md for the one-page version.

8. What should I check hardest at the human gates?

The spec and the plan — that’s where review effort pays off most. For a spec: every requirement has a matching acceptance criterion, scope boundaries (in and out) are explicit, and open questions are resolved or tracked. For a plan: the approach matches the spec, subtasks are ordered and small enough to be session boundaries, and ## Test Approach names the right tier (T1/T2/T3/T-E2E). Never flip a status to approved by hand — run /forge-spec-review / /forge-plan-review. At merge, a wave PR needs green CI; no approval is currently required.

9. Which Claude model and effort should I run?

The one set in ../team-guide.md § Choosing a Claude model and effort. It applies to every session, and every sub-agent inherits the driver’s model and effort, so there is nothing to choose per task beyond the effort step-up that section describes. The reasoning is in lessons L-053 and L-064; for current model facts consult the claude-api skill rather than memory.

10. When should I start a fresh Claude session?

Start a fresh session at two kinds of boundary:

  • between subtasks, once the working context is mostly output the next step does not need;
  • between workflow phases (spec → plan, plan → implement).

At each one, the session files what the next one needs in the harness docs (the tracker notes, the plan, the spec) and gives you a short opening prompt, usually just the command. Within /forge-deliver you rarely need more: Stage 0 re-derives all state from tracker.yaml and disk, so you just re-invoke /forge-deliver <ticket>. Avoid continuing implementation from a long discovery/exploration session — start fresh before building.

11. Can I work on features in different delivery phases at once?

Yes. delivery_phase is a stakeholder narrative layer, not an execution lock — actual sequencing is blocked_by. A feature can start as soon as its blockers are done, regardless of phase. But advancing a feature into implementation while its phase is still locked is an ASK FIRST action (surface it and record it in notes). The phase vocabulary and invariants are in ../../.claude/rules/tracker.md § Delivery Phase Rules.


Source. The authoritative harness docs listed at the top. This FAQ is a companion; on any disagreement, they win.

Generated from .forge/guides/forge-harness-faq.md by .claude/lib/render-docs-html.js. Markdown is canonical.