forge-cc 0.1.4 → 0.1.6

package/skills/forge-go.md

@@ -65,6 +65,12 @@ Verify the execution environment is ready:
 
    > You have uncommitted changes. Commit or stash them before running /forge:go.
 
+5. **Milestone size:** Count waves and agents in the milestone. If >3 waves or >6 total agents, warn:
+
+   > Warning: This milestone has {N} waves and {M} agents. Large milestones risk context overflow. Consider splitting before execution.
+
+   This is a pre-flight warning, not a hard abort — the user can choose to proceed. But the warning should be prominent so they can split the milestone first if needed.
+
 Print the pre-flight summary:
 
 ```
@@ -78,6 +84,21 @@ Print the pre-flight summary:
 Ready to execute Milestone 4.
 ```
 
+### Step 2.5 — Session Isolation (Automatic)
+
+The execution engine automatically creates a git worktree for isolated execution. This happens transparently — you don't need to manage it manually.
+
+**What happens behind the scenes:**
+1. A worktree is created at `../.forge-wt/<repo>/<session-id>/` based on the feature branch
+2. A session is registered in `.forge/sessions.json`
+3. All wave execution happens inside the worktree directory
+4. After completion, changes are merged back to the feature branch
+5. The worktree and session are cleaned up
+
+**Why:** Multiple users or terminals can run `/forge:go` simultaneously without corrupting each other's work. Each session gets an isolated copy of the codebase.
+
+**If worktree creation fails:** The engine falls back to running in the main working directory (original behavior). A warning is printed but execution continues.
+
 ### Step 3 — Execute Waves
 
 Parse the milestone section from the PRD. Each milestone contains waves with agent definitions:
@@ -325,6 +346,23 @@ After each milestone completes (Step 5-7):
 
 This prevents context rot — each milestone starts with clean context reading CLAUDE.md + STATE.md + current milestone section only (~20% of context window).
 
+### Parallel Milestones (dependsOn)
+
+When milestones specify `dependsOn` fields in the PRD, the scheduler can identify which milestones are independent and run them in parallel:
+
+- Milestones with no `dependsOn` (or `dependsOn: []`) can run in the first wave
+- Milestones that depend on completed milestones become ready as dependencies finish
+- The scheduler builds a DAG and groups milestones into execution waves
+
+Example PRD milestone with dependencies:
+```
+### Milestone 3: Integration Layer
+**dependsOn:** 1, 2
+**Goal:** Combine components from M1 and M2...
+```
+
+If no `dependsOn` fields are present, milestones execute sequentially (backward compatible).
+
 ### Step 9 — Linear Issue Start (On Milestone Begin)
 
 At the START of milestone execution (between Step 2 and Step 3), if Linear is configured:
@@ -347,3 +385,4 @@ If Linear is not configured, skip silently.
   > 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.
+- **Worktree conflict:** If the worktree directory already exists (e.g., from a crashed session), the engine attempts `npx forge cleanup` first. If that fails, it falls back to main directory execution.

package/skills/forge-setup.md

@@ -1,157 +1,183 @@
-# /forge:setup — Initialize or Refresh a Forge Project
-
-Bootstrap a new project with forge-cc scaffolding, or refresh an existing project's forge files to the latest templates. Creates `.forge.json`, `CLAUDE.md`, planning docs, and installs hooks.
-
-## Instructions
-
-Follow these steps exactly. Do not skip confirmation.
-
-### Step 1 — Detect Project
-
-Check the current directory for existing forge files:
-
-```bash
-ls .forge.json CLAUDE.md .planning/STATE.md .planning/ROADMAP.md tasks/lessons.md 2>/dev/null
-```
-
-Determine which files exist. This determines whether this is a fresh setup or a refresh.
-
-- **If `.forge.json` exists:** This is an existing forge project → default to Refresh mode
-- **If `.forge.json` does not exist:** This is a new project → default to Fresh Setup mode
-
-### Step 2 — Choose Setup Mode
-
-Present the detected mode and ask the user to confirm or override:
-
-<AskUserQuestion>
-question: "Detected {existing/new} forge project. Which mode?"
-options:
-  - "Fresh Setup — scaffold all forge files from scratch"
-  - "Refresh — update existing files to latest templates (preserves Learned Rules and lessons)"
-</AskUserQuestion>
-
-**Fresh Setup** will create all files, overwriting any that exist.
-**Refresh** will update templates while preserving:
-- `CLAUDE.md` → keeps `## Learned Rules` section content
-- `tasks/lessons.md` → keeps all existing lessons
-- `.planning/STATE.md` → keeps current state
-- `.planning/ROADMAP.md` → keeps current roadmap
-
-### Step 3 — Configure Gates
-
-Ask the user which verification gates to enable:
-
-<AskUserQuestion>
-question: "Which verification gates should be active?"
-multiSelect: true
-options:
-  - "types — TypeScript type checking (tsc --noEmit)"
-  - "lint — ESLint / Biome linting"
-  - "tests — Vitest / Jest test runner"
-  - "visual — Playwright screenshot regression"
-  - "runtime — Start the app and check for crashes"
-  - "prd — PRD completeness check"
-</AskUserQuestion>
-
-Default recommendation: `types`, `lint`, `tests`.
-
-Also collect project metadata (skip in Refresh mode if `.forge.json` already has values):
-
-<AskUserQuestion>
-question: "Project name?"
-</AskUserQuestion>
-
-<AskUserQuestion>
-question: "Tech stack? (e.g., TypeScript, React, Node.js)"
-</AskUserQuestion>
-
-<AskUserQuestion>
-question: "One-line project description?"
-</AskUserQuestion>
-
-### Step 4 — Create or Update Files
-
-Use the template functions from `forge-cc/src/setup/templates.ts` to generate file contents. The templates are:
-
-- `forgeConfigTemplate(ctx)` → `.forge.json`
-- `claudeMdTemplate(ctx)` → `CLAUDE.md`
-- `stateMdTemplate(ctx)` → `.planning/STATE.md`
-- `roadmapMdTemplate(ctx)` → `.planning/ROADMAP.md`
-- `lessonsMdTemplate(ctx)` → `tasks/lessons.md`
-- `gitignoreForgeLines()` → lines to append to `.gitignore`
-
-**Fresh Setup mode:** Create all files. Create directories `.planning/` and `tasks/` if they don't exist. Append forge lines to `.gitignore` if not already present.
-
-**Refresh mode:** Only overwrite `.forge.json` and the structural parts of `CLAUDE.md` (everything except `## Learned Rules`). Do NOT touch `STATE.md`, `ROADMAP.md`, or `lessons.md`.
-
-Write the actual files using the Write tool. Do not just print them.
-
-### Step 5 — Patch Global Config
-
-Check if `~/.claude/CLAUDE.md` exists:
-
-- **If it does not exist:** Create it using `globalClaudeMdTemplate()` from the templates.
-- **If it exists:** Leave it alone. Do not overwrite the user's global config.
-
-### Step 6 — Install Hooks
-
-Check if the user has a `.claude/settings.json` or `.claude/settings.local.json` in the project:
-
-```bash
-ls .claude/settings.json .claude/settings.local.json 2>/dev/null
-```
-
-If no settings file exists, create `.claude/settings.local.json` with the version-check hook:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Task",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node node_modules/forge-cc/hooks/version-check.js"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
-
-If a settings file already exists, inform the user:
-
-> Settings file already exists. To add the version-check hook manually, add this to your hooks config:
-> `"command": "node node_modules/forge-cc/hooks/version-check.js"`
-
-### Step 7 — Summary
-
-Print a summary of everything that was created or updated:
-
-```
-## Forge Setup Complete
-
-**Mode:** {Fresh Setup / Refresh}
-**Project:** {projectName}
-**Gates:** {comma-separated list}
-
-### Files Created/Updated
-- .forge.json ✓
-- CLAUDE.md ✓
-- .planning/STATE.md ✓
-- .planning/ROADMAP.md ✓
-- tasks/lessons.md ✓
-- .gitignore (forge lines) ✓
-- .claude/settings.local.json ✓ (version-check hook)
-
-### Next Steps
-1. Review the generated `CLAUDE.md` and customize the Code Map section
-2. Run `npx forge verify` to test your gate configuration
-3. Run `/forge:spec` to create a PRD for your first feature
-```
-
----
-
-Do NOT commit or push. The user decides when to commit the scaffolded files.
+# /forge:setup — Initialize or Refresh a Forge Project
+
+Bootstrap a new project with forge-cc scaffolding, or refresh an existing project's forge files to the latest templates. Creates `.forge.json`, `CLAUDE.md`, planning docs, and installs hooks.
+
+## Instructions
+
+Follow these steps exactly. Do not skip confirmation.
+
+### Step 1 — Detect Project
+
+Check the current directory for existing forge files:
+
+```bash
+ls .forge.json CLAUDE.md .planning/STATE.md .planning/ROADMAP.md tasks/lessons.md 2>/dev/null
+```
+
+Determine which files exist. This determines whether this is a fresh setup or a refresh.
+
+- **If `.forge.json` exists:** This is an existing forge project → default to Refresh mode
+- **If `.forge.json` does not exist:** This is a new project → default to Fresh Setup mode
+
+### Step 2 — Choose Setup Mode
+
+Present the detected mode and ask the user to confirm or override:
+
+<AskUserQuestion>
+question: "Detected {existing/new} forge project. Which mode?"
+options:
+  - "Fresh Setup — scaffold all forge files from scratch"
+  - "Refresh — update existing files to latest templates (preserves Learned Rules and lessons)"
+</AskUserQuestion>
+
+**Fresh Setup** will create all files, overwriting any that exist.
+**Refresh** will update templates while preserving:
+- `CLAUDE.md` → keeps `## Learned Rules` section content
+- `tasks/lessons.md` → keeps all existing lessons
+- `.planning/STATE.md` → keeps current state
+- `.planning/ROADMAP.md` → keeps current roadmap
+
+### Step 3 — Configure Gates
+
+Ask the user which verification gates to enable:
+
+<AskUserQuestion>
+question: "Which verification gates should be active?"
+multiSelect: true
+options:
+  - "types — TypeScript type checking (tsc --noEmit)"
+  - "lint — ESLint / Biome linting"
+  - "tests — Vitest / Jest test runner"
+  - "visual — Playwright screenshot regression"
+  - "runtime — Start the app and check for crashes"
+  - "prd — PRD completeness check"
+</AskUserQuestion>
+
+Default recommendation: `types`, `lint`, `tests`.
+
+Also collect project metadata (skip in Refresh mode if `.forge.json` already has values):
+
+<AskUserQuestion>
+question: "Project name?"
+</AskUserQuestion>
+
+<AskUserQuestion>
+question: "Tech stack? (e.g., TypeScript, React, Node.js)"
+</AskUserQuestion>
+
+<AskUserQuestion>
+question: "One-line project description?"
+</AskUserQuestion>
+
+### Step 4 — Create or Update Files
+
+Use the template functions from `forge-cc/src/setup/templates.ts` to generate file contents. The templates are:
+
+- `forgeConfigTemplate(ctx)` → `.forge.json`
+- `claudeMdTemplate(ctx)` → `CLAUDE.md`
+- `stateMdTemplate(ctx)` → `.planning/STATE.md`
+- `roadmapMdTemplate(ctx)` → `.planning/ROADMAP.md`
+- `lessonsMdTemplate(ctx)` → `tasks/lessons.md`
+- `gitignoreForgeLines()` → lines to append to `.gitignore`
+
+**Fresh Setup mode:** Create all files. Create directories `.planning/` and `tasks/` if they don't exist. Append forge lines to `.gitignore` if not already present.
+
+**Refresh mode:** Only overwrite `.forge.json` and the structural parts of `CLAUDE.md` (everything except `## Learned Rules`). Do NOT touch `STATE.md`, `ROADMAP.md`, or `lessons.md`.
+
+Write the actual files using the Write tool. Do not just print them.
+
+### Step 5 — Patch Global Config
+
+Check if `~/.claude/CLAUDE.md` exists:
+
+- **If it does not exist:** Create it using `globalClaudeMdTemplate()` from the templates.
+- **If it exists:** Leave it alone. Do not overwrite the user's global config.
+
+### Step 6 — Install Skills
+
+Copy all forge skills to `~/.claude/commands/forge/` so they're discoverable via `/forge:*`:
+
+```bash
+mkdir -p ~/.claude/commands/forge
+```
+
+Find the installed forge-cc package and copy skill files, stripping the `forge-` prefix:
+
+```bash
+SKILLS_DIR="$(dirname "$(which forge)")/../lib/node_modules/forge-cc/skills"
+# Fallback: check local node_modules
+if [ ! -d "$SKILLS_DIR" ]; then
+  SKILLS_DIR="node_modules/forge-cc/skills"
+fi
+
+for f in "$SKILLS_DIR"/forge-*.md; do
+  name=$(basename "$f" | sed 's/^forge-//')
+  cp "$f" ~/.claude/commands/forge/"$name"
+done
+```
+
+Print: "Installed forge skills to ~/.claude/commands/forge/"
+
+### Step 7 — Install Hooks
+
+Check if the user has a `.claude/settings.json` or `.claude/settings.local.json` in the project:
+
+```bash
+ls .claude/settings.json .claude/settings.local.json 2>/dev/null
+```
+
+If no settings file exists, create `.claude/settings.local.json` with the version-check hook:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node node_modules/forge-cc/hooks/version-check.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+If a settings file already exists, inform the user:
+
+> Settings file already exists. To add the version-check hook manually, add this to your hooks config:
+> `"command": "node node_modules/forge-cc/hooks/version-check.js"`
+
+### Step 8 — Summary
+
+Print a summary of everything that was created or updated:
+
+```
+## Forge Setup Complete
+
+**Mode:** {Fresh Setup / Refresh}
+**Project:** {projectName}
+**Gates:** {comma-separated list}
+
+### Files Created/Updated
+- ~/.claude/commands/forge/*.md ✓ (skills)
+- .forge.json ✓
+- CLAUDE.md ✓
+- .planning/STATE.md ✓
+- .planning/ROADMAP.md ✓
+- tasks/lessons.md ✓
+- .gitignore (forge lines) ✓
+- .claude/settings.local.json ✓ (version-check hook)
+
+### Next Steps
+1. Review the generated `CLAUDE.md` and customize the Code Map section
+2. Run `npx forge verify` to test your gate configuration
+3. Run `/forge:spec` to create a PRD for your first feature
+```
+
+---
+
+Do NOT commit or push. The user decides when to commit the scaffolded files.

package/skills/forge-spec.md

@@ -83,12 +83,31 @@ Conduct an adaptive interview using the interview engine logic from `src/spec/in
 4. **Scope** — what's out, sacred files, boundaries
 5. **Milestones** — phasing, dependencies, delivery chunks
 
+**Milestone Sizing Constraint (Hard Rule):**
+
+Each milestone MUST be completable in one main agent context window. If a milestone requires more than ~4 agents across 2-3 waves, split it. This is non-negotiable — large milestones cause context overflow and execution failures. When interviewing about milestones, actively recommend splitting any milestone that looks too large.
+
+**Milestone Dependencies (dependsOn):**
+
+During the milestones phase of the interview, ask about milestone dependencies using AskUserQuestion. For each milestone after the first, ask:
+
+- question: "Does Milestone {N} depend on any previous milestones?"
+- options:
+  - "No dependencies — can start immediately"
+  - "Depends on Milestone {N-1} (sequential)"
+  - "Depends on specific milestones (I'll specify)"
+
+If milestones have explicit dependencies, include `**dependsOn:** 1, 2` in the milestone section of the PRD. If no dependencies are specified, omit the field (backward compatible — treated as sequential).
+
+Independent milestones enable parallel execution via `/forge:go`, which creates separate worktrees for each parallel milestone.
+
 **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:
+- **NEVER present questions as numbered text — always use AskUserQuestion with 2-4 options per question.** Every interview question MUST be delivered via Claude Code's AskUserQuestion tool with structured multiple-choice options. Do not print numbered lists of questions for the user to answer in free text.
+- **Lead with recommendations.** Every question includes context from the codebase scan as the question text. Never ask a blank "what do you want to build?" question.
+- **Ask 1 question at a time via AskUserQuestion.** Each question gets its own AskUserQuestion call with 2-4 predefined options derived from codebase scan context and common patterns. Always include a final option like "Other (I'll describe)" to allow the user to provide a custom answer.
+- **Follow interesting threads.** If the user's selection mentions migration, breaking changes, multiple user types, or external integrations, follow up with targeted AskUserQuestion calls.
+- **Show progress.** After each answer round, show a compact status as text output:
 
 ```
 Progress: [##---] Problem & Goals (2/2) | User Stories (0/2) | Technical (0/1) | Scope (0/1) | Milestones (0/1)
@@ -101,22 +120,35 @@ Progress: [##---] Problem & Goals (2/2) | User Stories (0/2) | Technical (0/1) |
 - **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:**
+**Question Format (AskUserQuestion):**
+
+Each interview question MUST use AskUserQuestion. Build the question text from codebase scan context and the section being asked about. Provide 2-4 options that reflect likely answers based on the scan results, plus a free-text escape hatch. Example:
 
 ```
-### Round N
+AskUserQuestion:
+  question: "[Section] Context from scan or previous answers. Question text here?"
+  options:
+    - "Option A — a likely answer based on scan findings"
+    - "Option B — another plausible direction"
+    - "Option C — a third possibility (if applicable)"
+    - "Other (I'll describe)"
+```
+
+If the user selects "Other (I'll describe)", prompt them for a free-text answer using a follow-up AskUserQuestion or accept their typed response.
 
-Based on your codebase scan, I have some questions:
+**Do NOT do this (anti-pattern):**
 
-1. **[Section]** Context from scan or previous answers.
-   Question text here?
+```
+### Round N
 
-2. **[Section]** Context observation.
-   Question text here?
+1. **[Section]** Question text?
+2. **[Section]** Question text?
 
-> Answer by number (e.g., "1. My answer to first question. 2. Second answer") or answer all at once.
+> Answer by number...
 ```
 
+This numbered-text format is explicitly prohibited. Always use AskUserQuestion.
+
 ### 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`:
@@ -154,9 +186,13 @@ The PRD should follow this structure:
 - [ ] Issue title — brief description
 
 ### Milestone 2: {Name}
+**dependsOn:** 1
+**Goal:** {What this delivers}
 ...
 ```
 
+**Milestone sizing check:** Before finalizing, review each milestone against the sizing constraint. Every milestone MUST fit in one agent context window (~4 agents across 2-3 waves max). If any milestone exceeds this, split it into smaller milestones before writing the final PRD. Set `maxContextWindowFit: true` on all milestones — if you cannot make a milestone fit, flag it as `maxContextWindowFit: false` and warn the user.
+
 Write the final PRD to `.planning/prds/{project-slug}.md`. Tell the user:
 
 > Final PRD written to `.planning/prds/{slug}.md`.
@@ -241,6 +277,8 @@ Linear: {project URL}
 - Open PRs and transition issues automatically
 ```
 
+**Note:** `/forge:go` now uses git worktrees for session isolation. Multiple users can run `/forge:go` on different milestones simultaneously without conflicts.
+
 ## Edge Cases
 
 - **No Linear connection:** Warn the user. Still generate the PRD locally — skip the Linear sync steps.