forge-cc 0.1.0

package/skills/forge-go.md

@@ -0,0 +1,332 @@
+# /forge:go — Execute Milestones with Wave-Based Agent Teams
+
+Execute the next milestone from your PRD with wave-based agent teams, self-healing verification, and automatic state management. Run one milestone at a time (default) or chain all remaining milestones with `--auto`.
+
+## Instructions
+
+Follow these steps exactly. The execution engine at `src/go/executor.ts` provides the programmatic logic — this skill drives the agent orchestration.
+
+### Step 1 — Orient
+
+Read project state files to determine current position:
+
+```
+Read these files in parallel:
+- CLAUDE.md
+- .planning/STATE.md
+- .planning/ROADMAP.md
+```
+
+From STATE.md, extract:
+- **Current milestone number** (from `**Milestone:**` field)
+- **Branch** (from `**Branch:**` field)
+- **Active PRD path** (from `**Active PRD:**` field)
+
+From ROADMAP.md, find the next milestone with status "Pending". If STATE.md says the current milestone is complete, advance to the next pending one.
+
+If no active PRD exists:
+
+> No active PRD found. Run `/forge:spec` first to create a PRD with milestones.
+
+If all milestones are complete:
+
+> All milestones complete! Create a PR with `gh pr create` or run `/forge:spec` to start a new project.
+
+### Step 2 — Pre-flight Checks
+
+Verify the execution environment is ready:
+
+1. **Branch check:** Confirm you are on the correct feature branch (from STATE.md). If on `main`/`master`, warn and abort:
+
+   > You're on the main branch. Switch to your feature branch first: `git checkout {branch}`
+
+2. **Milestone exists:** Read ONLY the current milestone section from the PRD (progressive disclosure — NOT the full PRD). Use the executor's `readCurrentMilestone()` approach — match `### Milestone N:` header and extract until the next milestone header.
+
+3. **Not already complete:** Check ROADMAP.md to confirm this milestone is not already marked complete. If it is, advance to the next pending milestone.
+
+4. **Clean state:** Run `git status` to check for uncommitted changes. If dirty, warn:
+
+   > You have uncommitted changes. Commit or stash them before running /forge:go.
+
+Print the pre-flight summary:
+
+```
+## Pre-flight Check
+
+- Branch: feat/forge-build (OK)
+- Milestone: 4 — Execution Engine (go) (Pending)
+- PRD: .planning/prds/forge-build.md (found)
+- Working tree: clean
+
+Ready to execute Milestone 4.
+```
+
+### Step 3 — Execute Waves
+
+Parse the milestone section from the PRD. Each milestone contains waves with agent definitions:
+
+```
+**Wave N (M agents parallel):**
+1. **agent-name**: task description
+   - Creates: file1, file2
+   - Modifies: file3
+```
+
+For each wave, in order:
+
+#### 3a. Build Agent Prompts
+
+For each agent in the wave, construct a prompt that includes:
+
+1. **Agent identity:** "You are **{agent-name}** working on Milestone {N}: {name}."
+2. **Milestone goal:** The `**Goal:**` line from the milestone section.
+3. **Agent task:** The specific task description from the wave definition.
+4. **Files to create/modify:** The explicit file list from the agent's definition.
+5. **Existing code context:** Read the actual contents of files the agent depends on (imports, types, utilities). **Inline the actual code** — never reference files by path alone. This is critical for agents that run in isolated contexts.
+6. **Lessons:** Read `tasks/lessons.md` and include all active lessons.
+7. **Rules:**
+   - Use ES module imports with `.js` extension in import paths
+   - Stage only your files (never `git add .` or `git add -A`)
+   - Run `npx tsc --noEmit` after creating files to verify compilation
+   - Do NOT commit — the orchestrator handles commits
+
+#### 3b. Spawn Agents in Parallel
+
+Use the Task tool to spawn all agents in the current wave simultaneously:
+
+```
+For each agent in the wave, use the Task tool with:
+- The constructed prompt as the task description
+- subagent_type appropriate for the work (typically a full-capability agent)
+```
+
+Wait for ALL agents in the wave to complete before moving to the next step.
+
+#### 3c. Restage Files at Wave Boundary
+
+**IMPORTANT:** Parallel agents can disrupt each other's git index. After all agents in a wave complete, restage all files:
+
+```bash
+git add {all files from this wave's agents}
+```
+
+This is a learned lesson — always restage at wave boundaries.
+
+#### 3d. Run Verification
+
+After each wave completes, run forge verification:
+
+```bash
+npx tsc --noEmit
+```
+
+If the project has additional verification configured (tests, lint), also run:
+
+```bash
+npx forge verify
+```
+
+If verification **passes**: print a wave completion summary and proceed to the next wave.
+
+```
+## Wave {N} Complete
+
+- agent-1: OK (created file1.ts, file2.ts)
+- agent-2: OK (modified file3.ts)
+- Verification: PASSED
+
+Proceeding to Wave {N+1}...
+```
+
+If verification **fails**: proceed to Step 4 (self-healing loop).
+
+### Step 4 — Self-Healing Verify Loop
+
+When verification fails after a wave:
+
+1. Parse the verification errors into structured feedback. Include:
+   - Gate name (types, lint, tests)
+   - Error messages with file paths and line numbers
+   - Remediation hints if available
+
+2. Spawn a **fix agent** with a prompt that includes:
+   - The specific errors to fix
+   - The files that need modification
+   - The original task context
+   - "Fix ONLY the errors listed. Do not refactor or add features."
+
+3. After the fix agent completes, restage files and re-run verification.
+
+4. Repeat up to `maxIterations` (default: 5, configurable via `.forge.json`).
+
+5. If max iterations reached without passing:
+
+   ```
+   ## Verification Failed After {N} Iterations
+
+   ### Remaining Errors:
+   - types: src/go/executor.ts:42 — Type 'string' is not assignable to type 'number'
+   - lint: src/go/executor.ts:55 — Unused variable 'foo'
+
+   The self-healing loop could not resolve all errors.
+   Please fix the remaining issues manually, then run `/forge:go` again.
+   ```
+
+   **Stop execution.** Do not proceed to the next wave or milestone.
+
+### Step 5 — Commit
+
+After ALL waves pass verification:
+
+1. Stage all files created/modified across all waves:
+
+   ```bash
+   git add {all files from all waves}
+   ```
+
+2. Commit with a structured message:
+
+   ```bash
+   git commit -m "feat: {Milestone Name} (Milestone {N})"
+   ```
+
+3. Push to the remote branch:
+
+   ```bash
+   git push origin {branch}
+   ```
+
+### Step 6 — Update State
+
+Update project state files:
+
+1. **STATE.md:** Update the milestone progress table — mark the completed milestone's status as `Complete ({date})`. If there is a next milestone, update the `**Milestone:**` line to point to it. Update `**Last Session:**` to today's date.
+
+2. **ROADMAP.md:** Update the milestone table row to `Complete ({date})`.
+
+3. **Session memory:** Write session state for the current branch using the writer module's pattern.
+
+4. Commit the state updates:
+
+   ```bash
+   git add .planning/STATE.md .planning/ROADMAP.md
+   git commit -m "docs: mark Milestone {N} complete, update session state"
+   git push origin {branch}
+   ```
+
+### Step 7 — Linear Sync (If Configured)
+
+If the project has a `linearProject` configured in `.forge.json` or the PRD:
+
+1. Transition issues for the completed milestone to appropriate state:
+   - If this was the **last milestone**: move issues to "In Review"
+   - Otherwise: keep issues as-is (they were set to "In Progress" at start)
+
+2. If this is the **last milestone**, also:
+   - Transition the project to "In Review"
+   - Create a PR (see Step 8)
+
+If Linear is not configured, skip this step silently.
+
+### Step 8 — Route Next
+
+After milestone completion, determine the next action:
+
+#### If this is NOT the last milestone:
+
+```
+## Milestone {N} Complete
+
+**{Milestone Name}** completed successfully.
+
+- Files created: {count}
+- Files modified: {count}
+- Verification: PASSED
+- Branch: {branch} (pushed)
+
+**Next:** Run `/clear` to reset context, then `/forge:go` for Milestone {N+1}: {Next Milestone Name}.
+```
+
+#### If this IS the last milestone:
+
+Create a pull request:
+
+```bash
+gh pr create --title "feat: {Project Name}" --body "$(cat <<'EOF'
+## Summary
+{Brief description from PRD overview}
+
+## Milestones Completed
+- [x] Milestone 1: {name}
+- [x] Milestone 2: {name}
+...
+
+## Verification
+All milestones passed forge verification (types, lint, tests).
+
+---
+Generated by forge-cc
+EOF
+)"
+```
+
+Then print:
+
+```
+## All Milestones Complete!
+
+**PR created:** {PR URL}
+
+- {N} milestones completed
+- {total files} files created/modified
+- All verification gates passed
+
+The PR is ready for review.
+```
+
+### Auto Mode (`--auto`)
+
+When invoked with `--auto` (e.g., `/forge:go --auto`), chain all remaining milestones with context resets between each.
+
+After each milestone completes (Step 5-7):
+
+1. Print the completion summary for the milestone.
+2. Print instructions for the context reset:
+
+   ```
+   ## Context Reset for Milestone {N+1}
+
+   Milestone {N} is complete and committed. Starting fresh context for the next milestone.
+
+   To continue autonomously, start a new session and run:
+   > /forge:go --auto
+
+   The new session will read STATE.md (just updated) and pick up at Milestone {N+1}.
+   ```
+
+**IMPORTANT:** Auto mode does NOT continue in the same context window. Each milestone gets a fresh context (the Ralph Loop pattern). The `--auto` flag simply means "after completing this milestone, print the instructions for continuing" rather than "execute everything in one session."
+
+This prevents context rot — each milestone starts with clean context reading CLAUDE.md + STATE.md + current milestone section only (~20% of context window).
+
+### Step 9 — Linear Issue Start (On Milestone Begin)
+
+At the START of milestone execution (between Step 2 and Step 3), if Linear is configured:
+
+1. Find issues associated with this milestone in Linear.
+2. Transition them to "In Progress".
+3. Transition the project to "In Progress" (if not already).
+4. Add a brief comment: "Starting execution via forge:go."
+
+If Linear is not configured, skip silently.
+
+## Edge Cases
+
+- **No PRD:** Abort with message to run `/forge:spec` first.
+- **No waves in milestone:** The milestone section may not have structured wave definitions (e.g., it was written by hand without the spec engine). In this case, treat the entire milestone as a single wave with one agent whose task is the milestone's goal.
+- **Agent failure:** If an agent in a wave fails (exits with error, times out), record the failure, include the error in the wave result, and proceed to verification. The self-healing loop may fix the issue.
+- **Branch diverged:** If `git push` fails due to divergence, attempt `git pull --rebase` first. If that fails, stop and ask the user.
+- **Interrupted execution:** If execution is interrupted mid-wave, the state files are NOT updated. Running `/forge:go` again will retry the same milestone from the beginning. Completed agents' work will be in the working tree — the new run's verification will detect what's already working.
+- **Empty milestone section:** If the PRD has a milestone header but no content, abort with:
+  > Milestone {N} has no wave definitions. Update the PRD with agent assignments before running /forge:go.
+- **Already on correct milestone:** If STATE.md's current milestone matches the target, proceed normally (this is the expected case).
+- **Linear auth fails:** Warn but continue execution. Linear sync is not blocking.

package/skills/forge-spec.md

@@ -0,0 +1,251 @@
+# /forge:spec — Linear Project to PRD with Milestones
+
+Turn a Linear project into a detailed PRD with milestones and issues. This skill scans the codebase, conducts an adaptive interview, generates a PRD, and syncs the plan back to Linear.
+
+## Instructions
+
+Follow these steps exactly. The interview is adaptive — lead with recommendations, not blank-slate questions.
+
+### Step 1 — Select Linear Project
+
+Fetch incomplete projects from Linear:
+
+```
+Use mcp__linear__list_projects to get all existing projects.
+```
+
+Filter to projects in "Backlog" state (these are triaged but not yet specced). Present them as a numbered list:
+
+```
+## Projects Ready for Spec
+
+1. **Project Name** — description
+2. **Project Name** — description
+```
+
+Then ask:
+
+> Which project would you like to spec? Pick a number, or type a project name.
+
+If no Backlog projects exist, say:
+
+> No projects in Backlog state. Run `/forge:triage` first to create projects from your ideas, or create one directly in Linear.
+
+Wait for the user's selection before continuing.
+
+### Step 2 — Scan the Codebase
+
+Run 3 parallel codebase scan agents using the Task tool. Each agent should use the scanner module at `src/spec/scanners.ts`:
+
+**Agent 1 — Structure Scanner:**
+```
+Scan the project directory for framework, language, config files, dependencies, and key files.
+Use the scanStructure() function from the scanner module.
+Report the StructureScanResult.
+```
+
+**Agent 2 — Routes/UI Scanner:**
+```
+Scan for route files, pages, API routes, layouts, and routing framework.
+Use the scanRoutes() function from the scanner module.
+Report the RoutesScanResult.
+```
+
+**Agent 3 — Data/APIs Scanner:**
+```
+Scan for API endpoints, database files, env files, external services, and schema files.
+Use the scanDataAPIs() function from the scanner module.
+Report the DataAPIsScanResult.
+```
+
+Combine the results into a `ScanAllResult`. Print a brief summary:
+
+```
+## Codebase Scan Complete
+
+- **Framework:** Next.js (TypeScript)
+- **Pages:** 12 | **API Routes:** 8
+- **Dependencies:** 24 | **DB Files:** 3
+- **Key Files:** src/lib/auth.ts, src/db/schema.prisma, ...
+```
+
+If the current working directory does not look like a project (no package.json, no src/), warn:
+
+> This directory doesn't look like a project root. Should I scan here, or provide a path to the project?
+
+### Step 3 — Adaptive Interview
+
+Conduct an adaptive interview using the interview engine logic from `src/spec/interview.ts`. The interview covers 5 sections in priority order:
+
+1. **Problem & Goals** — what problem, desired outcome, success criteria
+2. **User Stories** — primary users, workflows, secondary users
+3. **Technical Approach** — architecture decisions, constraints, stack
+4. **Scope** — what's out, sacred files, boundaries
+5. **Milestones** — phasing, dependencies, delivery chunks
+
+**Interview Rules:**
+
+- **Lead with recommendations.** Every question includes context from the codebase scan. Never ask a blank "what do you want to build?" question.
+- **Ask 1-3 questions per round.** Present them as a numbered list. The user can answer all at once or pick which to answer.
+- **Follow interesting threads.** If the user mentions migration, breaking changes, multiple user types, or external integrations, follow up with targeted questions.
+- **Show progress.** After each answer round, show a compact status:
+
+```
+Progress: [##---] Problem & Goals (2/2) | User Stories (0/2) | Technical (0/1) | Scope (0/1) | Milestones (0/1)
+```
+
+- **Update the PRD draft every 2-3 answers.** Write the current draft to `.planning/prds/{project-slug}.md`. Tell the user:
+
+> Updated PRD draft at `.planning/prds/{slug}.md` — you can review it anytime.
+
+- **Stop when complete.** When all sections have enough info (Problem 2+, Users 2+, Technical 1+, Scope 1+, Milestones 1+), move to Step 4. Don't drag the interview out.
+- **Allow early exit.** If the user says "that's enough", "skip", or "generate it", respect that and move to Step 4 with what you have.
+
+**Question Format:**
+
+```
+### Round N
+
+Based on your codebase scan, I have some questions:
+
+1. **[Section]** Context from scan or previous answers.
+   Question text here?
+
+2. **[Section]** Context observation.
+   Question text here?
+
+> Answer by number (e.g., "1. My answer to first question. 2. Second answer") or answer all at once.
+```
+
+### Step 4 — Generate PRD
+
+Using all gathered interview answers and codebase scan results, generate the final PRD. Use the generator module at `src/spec/generator.ts`:
+
+The PRD should follow this structure:
+
+```markdown
+# PRD: {Project Name}
+
+## Problem & Goals
+{Synthesized from interview answers}
+
+## User Stories
+{Structured user stories derived from interview}
+
+## Technical Approach
+{Stack decisions, architecture, constraints — informed by codebase scan}
+
+## Scope
+### In Scope
+{What will be built}
+
+### Out of Scope
+{Explicitly excluded items}
+
+### Sacred Files
+{Files/areas not to be touched}
+
+## Milestones
+
+### Milestone 1: {Name}
+**Goal:** {What this delivers}
+**Issues:**
+- [ ] Issue title — brief description
+- [ ] Issue title — brief description
+
+### Milestone 2: {Name}
+...
+```
+
+Write the final PRD to `.planning/prds/{project-slug}.md`. Tell the user:
+
+> Final PRD written to `.planning/prds/{slug}.md`.
+
+Present the full PRD in chat for review and ask:
+
+> Review the PRD above. You can:
+> - **Approve** — I'll create milestones and issues in Linear
+> - **Edit** — tell me what to change (e.g., "add a milestone for testing" or "remove the admin user story")
+> - **Regenerate** — start the interview over
+>
+> What would you like to do?
+
+Wait for approval before continuing to Step 5.
+
+### Step 5 — Sync to Linear
+
+After the user approves the PRD, create milestones and issues in Linear.
+
+First, get the team ID:
+
+```
+Use mcp__linear__list_teams to get available teams.
+```
+
+If there is only one team, use it automatically. If multiple, ask the user which team.
+
+For each milestone in the PRD:
+
+```
+Use mcp__linear__create_milestone with:
+  - projectId: the selected project's ID
+  - name: milestone name
+  - description: milestone goal
+```
+
+For each issue under that milestone:
+
+```
+Use mcp__linear__create_issue with:
+  - title: issue title
+  - description: issue description (from PRD)
+  - teamId: the team ID
+  - projectId: the project ID
+  - milestoneId: the milestone ID just created
+```
+
+After all milestones and issues are created, transition the project to "Planned":
+
+```
+Use mcp__linear__update_project to set the project state to "planned".
+```
+
+Print a summary:
+
+```
+## Synced to Linear
+
+- **Project:** {name} (now "Planned")
+- **Milestones:** {N} created
+- **Issues:** {M} created across all milestones
+
+View in Linear: {project URL}
+```
+
+If any creation fails, report the error and continue with remaining items.
+
+### Step 6 — Handoff
+
+After sync, print the handoff prompt:
+
+```
+## Ready for Development
+
+PRD: `.planning/prds/{slug}.md`
+Linear: {project URL}
+
+**Next step:** Run `/forge:go` to start executing Milestone 1. The execution engine will:
+- Read the PRD and milestone plan
+- Spawn agent teams for each issue
+- Verify each change with forge-mcp gates
+- Open PRs and transition issues automatically
+```
+
+## Edge Cases
+
+- **No Linear connection:** Warn the user. Still generate the PRD locally — skip the Linear sync steps.
+- **Empty codebase:** The interview still works — questions will be more open-ended without scan context. Note this to the user.
+- **User wants to spec a project not in Linear:** Allow it. Skip Step 1 project selection, ask for a project name, and create the Linear project in Step 5 before creating milestones.
+- **User provides info upfront:** If the user includes project details in the same message as `/forge:spec`, use that info to pre-fill interview answers and skip questions that are already answered.
+- **Very large codebase:** Scan agents may return truncated results. That's fine — the interview fills in gaps.
+- **Interrupted interview:** If the user stops mid-interview, save what you have to the PRD draft. They can resume by running `/forge:spec` again and selecting the same project.