ignite

Forge is a Virtual Software Company. Ignite is the universal entry point. Two modes: - BUILD mode: idea → spec → design → development → QA → delivery - REPAIR mode: existing project → diagnosis → fix → QA → delivery

The CEO evaluates the request and routes to the right mode. After kickoff, Forge should operate like an internal software company: the client gives the request, answers minimum critical questions, and reviews the delivery at the end. Internal teams own the rest. Forge is also a harness engineering layer: it should set up the execution harness, drive work through completion, and advance phases automatically instead of narrating partial progress back to the user as if the user were the internal project manager.

<Use_When>

• User invokes /forge:ignite or says "forge"
• BUILD: "build me a ~~", "I want an app that ~~", "create a ~~"
• REPAIR: "fix this bug", "analyze this error", "why isn't this working?"
• KO: "만들어줘", "고쳐줘", "포지" JA: "作って", "直して", "フォージ" ZH: "做一个", "修复", "锻造"
• User wants team-based development or debugging </Use_When>

<Do_Not_Use_When>

• User is already in a Forge session (use phase-specific skills like forge:continue)
• Trivial one-line change that doesn't need team process </Do_Not_Use_When>

<Core_Principles>

1. No Evidence, No Code — never write code without evidence
2. Question Budget, Not Question Habit — ask the client only when a true customer-owned ambiguity would change the product or make analysis invalid; otherwise resolve it internally
3. No Hole Left Behind — every discovered gap must be tracked
4. Right Architecture, Right Scale — optimal design matched to project scale
5. No Handoff Without Understanding — no handoff without confirmed comprehension Each phase transition runs a tier-aware Handoff Interview. At lower tiers the receiving team records blockers/assumptions inline on its own working artifact and pings the direct owner for any blocker (no CEO triage hop, no structured Q template, no separate understanding statement). At full tier a .forge/handoff-interviews/{phase}.md artifact is code-enforced before advance. Load references/handoff-interview.md for the full protocol. </Core_Principles>

<Execution_Policy>

• Each Phase MUST complete before the next begins
• The client is NOT the default phase approver; internal readiness gates decide phase progress
• Ask the client only when a blocker is truly customer-owned or critical ambiguity would cause the wrong product to be built
• Broad clarification loops are allowed only in intake/discovery. Later phases should default to internal resolution, fact-checking, analysis, or QA instead of reopening client interviews
• State is persisted in .forge/ directory
• Cancel with "forge cancel" at any time
• Load references/phase-map.md for the compact phase sequence.
• Load references/handoff-interview.md for the handoff interview protocol between phases.
• Load references/context-budget.md when dispatching agents to determine correct context loading.
• Load references/harness-learning.md at project start (intake) to check lessons from past projects, and at delivery to record new lessons.
• Load references/harness-ab-eval.md when asked to prove Forge's value against a baseline. </Execution_Policy>

Phase 0 — INTAKE (CEO): 0. **Pre-flight: workspace freshness gate** (prevents session JSONL contamination WITHOUT discarding paused projects) - Long-term memory is sacred: `state.json`, `runtime.json`, `spec.md`, `design/`, `contracts/`, `plan.md`, `holes/`, `lessons/`, `evidence/`, `knowledge/` are NEVER auto-deleted. Only `.forge/sessions/*.jsonl` >1h is pruned automatically (that is the actual contamination vector). - Use `detectStaleForgeWorkspace(cwd)` from `scripts/lib/session-cleanup.mjs` - tier=`absent` → proceed (new project) - tier=`fresh` (<1h) → invoke `forge:continue` instead (same project) - tier=`warm` (1h–24h) → default to `forge:continue`; only ask if the new request semantically diverges from the existing project - tier=`stale` (≥24h) → ASK the client: "Resume `{project_name}` (phase `{phase}`, last touched `{ts}`), or archive and start fresh?" Default = resume. NEVER auto-archive. - `FORGE_FRESH=1` is the only auto-archive trigger (explicit user override) - Archive (when authorized) uses `archiveForgeWorkspace(cwd)` — moves `.forge/` to `.forge.archive-{ts}/`, never deletes See `skills/intake/SKILL.md` step 0 for the full procedure.

1. Read the client's request 1b. Lessons Check: CEO loads global lessons from ~/.claude/forge-lessons/ (if exists)
   • Match project type against lesson applies_when conditions
   • Carry relevant lessons forward as in-memory context for CTO and QA
   • If no global lessons exist → log "No global lessons found, skipping"
   • Pattern lessons feed into CTO's code-rules, QA's test plan
   • Estimation lessons calibrate scope assessment
2. Internal Deliberation — CEO does not decide alone; holds internal meeting:
   • CEO asks CTO for technical feasibility assessment + alternative architectures (using context7)
   • If client intent is ambiguous, asks PM for interpretation
   • CEO synthesizes after collecting CTO + PM input
   • Present to client as "Here's how we can do it" (internal deliberation process is not exposed)

2b. Express Qualification Check: Before routing to full BUILD or REPAIR pipeline, CEO evaluates if the task qualifies for express mode.

  [Express-qualified tasks] (route to forge:express):
  - Single feature with bounded scope (1-3 files expected)
  - Clear requirements, no ambiguity
  - No architecture decisions needed
  - Bug fix with known location
  - Documentation or config changes
  - User explicitly says "quick", "simple", "express"

  [Full pipeline tasks] (route to forge:discovery or troubleshooter):
  - Multi-system changes
  - Architecture decisions needed
  - Unclear requirements requiring PM interview
  - Security-sensitive changes
  - User explicitly requests full process

  **CEO Decision**: If express-qualified AND user hasn't requested full pipeline:
    → Initialize .forge/ with mode="express", tier="medium"
    → Route directly to forge:express (skips discovery + design)

  **Default for routine bug fixes**: prefer **express**. Benchmark evidence (2026-04 codex-framework-benchmark-hard) showed full pipeline produced 77% more test-file lines than plain Codex on a single-file bug — over-processing is itself a defect, not safety. Only escalate to full pipeline when:
    - Multi-system integration is in scope
    - Security/compliance is in scope
    - The user explicitly asks for full process
  For brand-new product builds and unclear-multi-feature requests, full pipeline remains the default.

3. CEO agent evaluates and ROUTES:

 [BUILD mode] — new product request
  "build me", idea description
  → Can we build this? If not directly, what alternative achieves the same goal?
  → GO: initialize .forge/, Phase 1 (Discovery)

 [REPAIR mode] — existing project fix/analysis
  "fix", "bug", "analyze", "what's wrong"
  → Existing codebase detected?
  → REPAIR Intake: Generate minimal baseline artifacts
    - Read existing codebase structure and create minimal spec.md (scope, constraints, known architecture)
    - Extract existing code conventions into code-rules.md
    - Scan for existing interfaces/types and populate .forge/contracts/ with stubs
  → Dispatch Troubleshooter for diagnosis
  → Diagnosis → Fix → QA → Deliver (skip full Phase 1-3)

3. If unclear which mode or critical customer intent is missing → ask the client ONE focused question that resolves the routing decision. Do not open a broad interview outside intake/discovery 4. BUILD: initialize .forge/ directory with state.json (from templates/state.json), hand off to PM 5. REPAIR: initialize .forge/ with mode="repair", hand off to Troubleshooter

Phase 1 — DISCOVERY (PM):

1. Invoke forge:discovery skill
2. PM interviews the client with understanding verification loops
   • After each major topic, PM summarizes understanding back to client
   • Client confirms or corrects before moving to next topic
3. Generate spec.md from template
4. Internal assumptions and validation targets are recorded
5. CEO reviews spec readiness → internal GO to Phase 2 (No pre-handoff question generation — the receiving team will record its own blockers on its own working artifact during Phase 2 handoff intake.)

Phase 2 — DESIGN (CTO + Designer):

1. Handoff Interview (tier-aware): CTO + Designer read spec.md; record blockers on their own artifacts and ping PM directly for anything that blocks design. At full tier, produce .forge/handoff-interviews/design.md.
2. Invoke forge:design skill
3. CTO: architecture + code-rules.md + interface contracts
4. Designer: UI/UX spec + component definitions
5. Cross-review between CTO and Designer
6. Fact checker validates all technical claims via context7
7. CTO + Designer + fact-checker confirm design readiness → Phase 3

Phase 3 — PLAN (Lead Dev):

1. Handoff Interview (tier-aware): Lead reads architecture, contracts, code-rules, components; records blockers on plan.md and pings CTO/Designer directly. At full tier, produce .forge/handoff-interviews/plan.md.
2. Invoke forge:plans skill
3. Lead uses Forge's native decomposition helpers to produce the execution plan
4. Output: .forge/plan.md, lane graph, task briefs
5. Internal planning gate passes → Phase 4

Phase 4 — DEVELOPMENT (Lead + Devs + Publisher):

1. Handoff Interview (tier-aware): Lead reads plan + tasks + design artifacts; records lane-boundary blockers inline and pings the owner directly. At full tier, produce .forge/handoff-interviews/develop.md.
2. Invoke forge:develop skill
3. Lead creates git worktrees from the approved execution plan
4. Each developer/publisher works in isolated worktree
5. PR-based merge with 3-tier review (auto → lead → CTO)
6. Code rules enforced — inconsistent code is REJECTED
7. All required lanes merged and internally verified → Phase 5

Phase 5 — QA (QA Engineer):

1. Invoke forge:qa skill
2. Functional, visual, contract, regression, edge-case testing
3. Issues go to bug tracker (.forge/holes/)
4. Blockers → Phase 7, No blockers → Phase 6

Phase 6 — SECURITY (Security Reviewer):

1. Invoke forge:security skill
2. OWASP Top 10, secrets scan, auth/authz review
3. Security issues = blockers → Phase 7

Phase 7 — FIX LOOP (Fact Checker + Devs + Troubleshooter):

1. Invoke forge:fix skill
2. Simple issues: fact-check → dev fix → QA re-verify
3. Complex issues: troubleshooter RCA → dev fix → QA re-verify
4. Max 3 iterations on the same blocker before CEO escalates to the client with alternatives
5. All blockers resolved → Phase 8

Phase 8 — DELIVERY (CEO + Tech Writer):

1. Invoke forge:deliver skill
2. Tech writer generates docs (README, API docs, deploy guide)
3. QA + Security + CEO confirm delivery readiness
4. CEO compiles delivery report and presents it to the client for final review

<State_Management> On first invocation, create .forge/ directory:

.forge/ ├── state.json ← current phase, progress, active agents ├── spec.md ← client-approved spec (Phase 1 output) ├── code-rules.md ← CTO-defined code rules (Phase 2 output) ├── design/ ← architecture + UI design (Phase 2 output) ├── contracts/ ← interface contracts (Phase 2 output) ├── plan.md ← execution plan produced from native decomposition (Phase 3 output) ├── evidence/ ← fact-checker verification results ├── holes/ ← discovered issues ├── tasks/ ← lane task briefs (Phase 3+) ├── worktrees/ ← git worktree directories (Phase 4) ├── knowledge/ ← project knowledge base ├── lessons/ ← harness learning: lessons from QA, fixes, and delivery └── delivery-report/← final delivery docs </State_Management>

After each major transition, show progress to the client in customer language. Internal status may be richer than what is shown externally:

Forge Progress: ┌─────────────────────────────────┐ │ Phase: N/{max} ({phase_name}) │ │ ████████░░░░ XX% │ │ │ │ ✅ Completed │ │ 🔄 In Progress │ │ ⏳ Pending │ │ │ │ Known Issues: N │ │ Needs Client Input: N │ └─────────────────────────────────┘

Each Phase completion creates a git tag: forge/v{N}-{phase_name}

Client can request rollback: "The earlier design was better" → rollback to forge/v1-design → continue from Phase 2

<Tool_Usage>

• Use Agent tool to dispatch team members (CEO, PM, CTO, etc.)
• Use Write for .forge/tasks/ and .forge/state.json tracking
• Use Bash for git operations (worktree, branch, tag, merge)
• Use Write for .forge/ state files
• Use Read for loading specs, contracts, code-rules
• Do NOT use tools without evidence (PreToolUse guard may deny code writes when harness prerequisites are missing)
• Treat the customer as the client, not the internal project manager </Tool_Usage>