forge-cc 2.0.0 → 2.0.2

package/skills/forge-build.md

@@ -1,3 +1,23 @@
+---
+name: forge-build
+hooks:
+  WorktreeCreate:
+    - hooks:
+        - type: command
+          command: "node \"$CLAUDE_PROJECT_DIR/node_modules/forge-cc/hooks/linear-worktree-create.js\""
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "node \"$CLAUDE_PROJECT_DIR/node_modules/forge-cc/hooks/linear-branch-enforce.js\""
+  PostToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "node \"$CLAUDE_PROJECT_DIR/node_modules/forge-cc/hooks/linear-post-action.js\""
+          async: true
+---
+
 # /forge:build — Graph Execution with Adversarial Review
 
 Orchestrates requirement graph execution with worktree isolation, adversarial review, and Linear state transitions. Replaces `/forge:go`.
@@ -59,43 +79,55 @@ options:
 
 ### Step 1 — Execution Loop
 
-Execute requirements one at a time in priority order until the graph is complete.
+Execute requirements in parallel waves using `computeWaves()`. Each wave contains requirements whose dependencies are satisfied. Requirements within a wave run in parallel; waves run sequentially.
 
 ```
-while (!isProjectComplete(index)) {
-  ready = findReady(index)
-  if (ready.length === 0) break  // all blocked or discovered
-
-  reqId = ready[0]  // priority desc → group order → insertion order
-  result = executeRequirement(index, reqId)
-
-  if (result === "complete") {
-    updateRequirementStatus(projectDir, slug, reqId, "complete")
-    syncRequirementDone(client, index, reqId)  // Issue → Done
-  } else if (result === "failed") {
-    handleFailure(index, reqId, result.errors)
-  }
-
-  // Reload index — status may have changed, corrections may have been applied
-  index = loadIndex(projectDir, slug)
-}
-
-syncGraphProjectDone(client, index)  // Project → Done if all complete
+waves = computeWaves(index)
+
+for each wave in waves:
+  // Filter to pending/ready requirements only — skip already-complete ones
+  waveReqs = wave.filter(reqId => index.requirements[reqId].status !== "complete")
+  if (waveReqs.length === 0) continue  // entire wave already complete
+
+  if (waveReqs.length === 1):
+    // Sequential fallback — no team overhead for a single requirement
+    reqId = waveReqs[0]
+    Spawn a builder agent via Task tool with isolation: "worktree"
+    The builder executes Step 2 (build → verify → adversarial review)
+
+    if (result === "complete"):
+      updateRequirementStatus(projectDir, slug, reqId, "complete")
+      mergeWorktree()
+    else if (result === "failed"):
+      handleFailure(index, reqId, result.errors)  // Step 4
+
+  else:
+    // Parallel execution — spawn agent team for the wave
+    Create team via TeamCreate (team_name: "{slug}-wave-{N}")
+    For each reqId in waveReqs:
+      Create task via TaskCreate (subject: reqId, description: requirement prompt)
+      Spawn builder agent via Task tool with:
+        - isolation: "worktree"
+        - team_name: "{slug}-wave-{N}"
+        - The builder executes Step 2 independently
+
+    Coordinate: wait for all builders to complete
+    For each completed requirement:
+      updateRequirementStatus(projectDir, slug, reqId, "complete")
+      mergeWorktree()
+    For each failed requirement:
+      handleFailure(index, reqId, result.errors)  // Step 4
+
+  // Between waves — checkpoint:
+  Restage all files (git add -A && git reset)  // parallel agents disrupt each other's index
+  Run npx tsc --noEmit                         // catch integration issues before next wave
+  index = loadIndex(projectDir, slug)           // pick up status changes and corrections
+  Check for discovered requirements or graph corrections (see Step 5)
 ```
 
-**Execution order when multiple requirements are ready:**
-
-`findReady()` may return multiple requirement IDs. Order them by:
-1. Priority descending (P0 before P1 before P2)
-2. Group order (earlier groups first)
-3. Insertion order (lower req number first)
-
-Execute `ready[0]` sequentially. Future parallel execution will use `computeWaves()`.
+**Wave ordering:** `computeWaves(index)` returns `string[][]` — an array of waves, each wave an array of requirement IDs. Within each wave, requirements have no mutual dependencies and can run in parallel. Waves are ordered so that all dependencies of wave N are in waves 0..N-1.
 
-**Between requirements — checkpoint:**
-- Re-run `loadIndex()` to pick up any status changes
-- Check for discovered requirements or graph corrections (see Step 5)
-- Restage all files at wave boundaries — parallel agents can disrupt each other's git index
+**Always delegate to builder agents** for implementation work, even for sequential (single-requirement) waves. The point is preserving the orchestrator's context window, not just parallelism.
 
 ---
 
@@ -250,15 +282,28 @@ options:
 
 ---
 
-### Step 6 — Completion
+### Step 6 — Ship and Codex Review
 
-When the execution loop ends, determine the final state:
+When the execution loop ends and `isProjectComplete(index)` is true:
 
-**If `isProjectComplete(index)` is true:**
+1. **Ship the PR:**
+   ```bash
+   git push -u origin feat/{slug}
+   gh pr create --title "{project title}" --body "..."
+   ```
+   Push the branch and create a PR. The PostToolUse hook automatically links the PR to Linear issues and transitions the project to In Review — no manual `forge linear ship` needed.
 
-```
-syncGraphProjectDone(client, index)  // Project → Done in Linear
-```
+2. **Codex Review:** If a PR was created, follow the **Codex Review Protocol** in `ref/codex-review.md`.
+
+   **This step is mandatory.** Do not skip to the summary step until the Codex review protocol completes (either comments were resolved or polling timed out with no review found).
+
+---
+
+### Step 7 — Completion
+
+Determine the final state:
+
+**If all requirements are complete:**
 
 Print the completion summary:
 
@@ -268,7 +313,7 @@ Print the completion summary:
 **Slug:** {slug}
 **Requirements completed:** {completed} / {total}
 **Waves executed:** {count}
-**Linear Project:** {project URL} — Done
+**Linear Project:** {project URL} — In Review
 
 All requirements verified and merged.
 ```
@@ -295,16 +340,18 @@ All requirements verified and merged.
 
 ## Linear State Reference
 
-State transitions are driven by execution progress:
+All state transitions are handled automatically by hooks and Linear's GitHub integration. No manual sync calls are needed during build execution.
 
-| Item | Transition | When |
-|------|-----------|------|
-| Issue | Planned → In Progress | Agent starts working on requirement |
-| Issue | In Progress → Done | Requirement verified + merged |
-| Project | Planned → In Progress | First requirement starts |
-| Project | In Progress → Done | ALL requirements complete |
+| Item | Transition | Triggered By |
+|------|-----------|-------------|
+| Issue | Planned → In Progress | **WorktreeCreate hook** — fires when builder agent worktree is created |
+| Project | Planned → In Progress | **WorktreeCreate hook** — first requirement starts |
+| Issue | In Progress → In Review | **Linear GitHub integration** — PR opened from branch containing issue identifier |
+| Project | In Progress → In Review | **PostToolUse hook** — fires when `gh pr create` succeeds |
+| Issue | In Review → Completed | **Linear GitHub integration** — PR merged |
+| Project | In Review → Completed | **PostToolUse hook** — fires when `gh pr merge` succeeds |
 
-**If any Linear transition fails:** Log a warning and continue. Never block execution on Linear API failures.
+**If any Linear transition fails:** Hooks log warnings to stderr and continue. Never block execution on Linear API failures.
 
 ---
 
@@ -314,16 +361,17 @@ Keep these limits during execution to preserve the orchestrator's context window
 
 | Item | Budget |
 |------|--------|
-| Orchestrator context | Track progress only — delegate all implementation to builder agents |
+| Orchestrator context | Track wave progress only — delegate all implementation to builder agents |
 | Builder prompt | Target requirement + completed dep artifacts + overview + transitive deps |
 | Review prompt | Requirement file + actual files on disk — no diffs, no builder summaries |
-| Between-requirement checkpoint | Reload index, check discoveries, restage files |
+| Between-wave checkpoint | Restage files, run `tsc --noEmit`, reload index, check discoveries |
 
 ---
 
 ## Key References
 
 - `ref/adversarial-review.md` — Full review protocol (reviewer receives requirement file + actual files on disk, NOT diff/builder summary; stub detection; PASS/FAIL output)
+- `ref/codex-review.md` — Codex auto-review polling, evaluation, and resolution protocol
 - `ref/graph-correction.md` — Mid-execution correction protocol (discovered reqs, missing edges, file scope, group ordering; checkpoint timing; auto-apply rules)
 - `ref/requirement-sizing.md` — Sizing rules (hard/soft limits, splitting guide)
 

package/skills/forge-capture.md

@@ -152,13 +152,13 @@ For each project's issues, call `client.createIssueBatch()`:
       description: "{issue description}",
       teamId: teamId,
       projectId: "{project's Linear ID}",
-      stateId: "{Planned state ID}"
+      stateId: "{Backlog state ID}"
     }
   ]
 }
 ```
 
-To get the "Planned" state ID, look up the team's workflow states and find the one named "Planned". If "Planned" does not exist, fall back to "Backlog".
+To get the "Backlog" state ID, look up the team's workflow states and find the one with category "backlog". If not found, fall back to "Triage".
 
 **Error handling:**
 - If a project creation fails, report it but continue with remaining projects
@@ -183,7 +183,7 @@ Print a summary of everything created:
 {for each project with issues:}
 - {project name}: {count} issues
 
-**Linear state:** All projects and issues created at "Planned"
+**Linear state:** All projects and issues created at "Backlog"
 ```
 
 If any items failed, include a failures section:
@@ -198,7 +198,7 @@ If any items failed, include a failures section:
 
 | Item    | Created State |
 |---------|--------------|
-| Project | Planned      |
-| Issue   | Planned      |
+| Project | Backlog      |
+| Issue   | Backlog      |
 
-Do NOT set any item to "In Progress", "Todo", or "Backlog". Everything starts at "Planned" — the user promotes items when ready.
+Everything starts at "Backlog" — captured ideas haven't been planned yet. The plan skill transitions to "Planned" when requirements are defined.

package/skills/forge-fix.md

@@ -160,6 +160,10 @@ Print the current state and preserve the worktree for later:
 **Remaining issues:** {list}
 ```
 
+**Codex Review (if a PR exists for this graph):** After completing the fix, if a PR was previously created via `forge linear ship`, follow the **Codex Review Protocol** in `ref/codex-review.md`.
+
+**This step is mandatory.** Do not skip to the resume step until the Codex review protocol completes (either comments were resolved or polling timed out with no review found).
+
 ---
 
 ### Step 5 — Resume Build (optional)
@@ -192,6 +196,7 @@ options:
 ## Key References
 
 - `ref/adversarial-review.md` — Full review protocol (reviewer receives requirement file + actual files on disk, NOT diff/builder summary; stub detection; PASS/FAIL output)
+- `ref/codex-review.md` — Codex auto-review polling, evaluation, and resolution protocol
 - `ref/graph-correction.md` — Mid-execution correction protocol (for context on how graph state evolves)
 
 ## Graph Module API

package/skills/forge-plan.md

@@ -251,7 +251,7 @@ options:
 
 ### Step 6 — Linear Sync
 
-Create the project and issues in Linear.
+Create the project, milestones, and issues in Linear.
 
 1. **Load `.forge.json`** to get the `linearTeam` name.
 
@@ -260,18 +260,30 @@ Create the project and issues in Linear.
    - Description: content from `overview.md`
    - State: **Planned**
 
-3. **Create Linear issues** — one per requirement:
+3. **Create milestones** — one per group in the graph:
+   - For each group in `_index.yaml`, call `ForgeLinearClient.createMilestone({ name: groupName, projectId })`
+   - Store the returned `milestoneId` as `linearMilestoneId` in the group's entry in `_index.yaml`
+   - Milestone progress auto-calculates in Linear based on child issue completion
+
+4. **Create Linear issues** — one per requirement:
    - Title: requirement title
    - Description: requirement body (context + technical approach)
    - State: **Planned**
    - Labels: group name
+   - `projectMilestoneId`: the group's `linearMilestoneId` from step 3
 
-4. **Store Linear IDs** back into `_index.yaml`:
+5. **Store Linear IDs** back into `_index.yaml`:
    - Project ID at the top level
+   - Milestone IDs in each group entry (`linearMilestoneId`)
    - Issue ID in each requirement entry
    - Write via `writeIndex()`
 
-5. **Commit the graph directory** to the current feature branch:
+6. **Transition project to Planned:**
+   ```bash
+   npx forge linear sync-planned --slug {slug}
+   ```
+
+7. **Commit the graph directory** to the current feature branch:
 
    ```bash
    git add .planning/graph/{slug}/

package/skills/forge-quick.md

@@ -121,6 +121,10 @@ options:
 - Transition the issue to **Done**
 - Add the commit SHA or PR URL as a comment on the issue
 
+**Codex Review (if PR was created):** Follow the **Codex Review Protocol** in `ref/codex-review.md`.
+
+**This step is mandatory.** Do not skip to the report step until the Codex review protocol completes (either comments were resolved or polling timed out with no review found).
+
 ---
 
 ### Step 7 — Report

package/skills/ref/codex-review.md

@@ -0,0 +1,158 @@
+# Codex Review Protocol
+
+After a PR is created, poll for Codex auto-review comments, evaluate them, fix valid issues, and return to the user for merge approval.
+
+**The agent must NEVER auto-merge a PR.** Always return to the user for merge approval.
+
+---
+
+## Step 1 — Check Prerequisites
+
+Before polling, verify:
+- `GITHUB_TOKEN` is set in the environment
+- A PR was actually created in the previous step (you have the PR URL and number)
+
+**If `GITHUB_TOKEN` is not set:** Skip this protocol entirely. Print: "Skipping Codex review — GITHUB_TOKEN not set." Proceed to the skill's summary step.
+
+Extract the owner, repo, and PR number from the PR URL:
+```
+# Example: https://github.com/troyhoffman-oss/forge-cc/pull/30
+# owner=troyhoffman-oss, repo=forge-cc, pr=30
+```
+
+---
+
+## Step 2 — Poll for Review
+
+Run the Codex poll CLI command:
+
+```bash
+npx forge codex-poll --owner {owner} --repo {repo} --pr {pr_number}
+```
+
+This polls every 60 seconds for up to 8 minutes. The command outputs JSON:
+
+**If Codex review found** (exit code 0):
+```json
+{
+  "found": true,
+  "reviews": [{ "id": 123, "state": "commented", "body": "...", "user": "codex-bot" }],
+  "comments": [{ "id": 456, "body": "...", "path": "src/foo.ts", "user": "codex-bot" }]
+}
+```
+
+**If no review found** (exit code 1):
+```json
+{
+  "found": false,
+  "error": "No Codex review found after 8 minutes"
+}
+```
+
+**If no review found:** This is not a failure. Print: "No Codex review received. Proceeding." Continue to the skill's summary step.
+
+---
+
+## Step 3 — Evaluate Comments
+
+For each comment in the poll result, evaluate whether the feedback is valid:
+
+1. **Read the code** at the file path referenced in the comment (`path` field)
+2. **Understand the suggestion** — what is Codex recommending?
+3. **Assess validity** using your judgment. Categorize each comment as:
+
+| Category | Meaning | Action |
+|----------|---------|--------|
+| **Valid** | The feedback identifies a real issue worth fixing | Fix the code |
+| **Acknowledged** | The feedback is reasonable but a fix isn't appropriate (by design, out of scope, or would introduce other issues) | Reply explaining why |
+| **Dismissed** | The feedback is incorrect or not applicable | Reply explaining why |
+
+**Evaluation guidelines:**
+- Security issues are almost always valid
+- Performance suggestions are valid if the impact is meaningful
+- Style preferences that contradict the project's existing conventions should be dismissed
+- Suggestions that would break existing tests or APIs should be carefully evaluated
+
+---
+
+## Step 4 — Fix Valid Issues
+
+For each comment categorized as **Valid**:
+
+1. Make the code change in the current branch
+2. Run verification to ensure the fix doesn't break anything:
+   ```bash
+   npx forge verify
+   ```
+3. If verification fails, fix the verification issue before proceeding
+4. Stage and commit the fix:
+   ```bash
+   git add {changed files}
+   git commit -m "Address Codex review: {brief description of fix}"
+   ```
+
+After all valid fixes are committed:
+```bash
+git push
+```
+
+---
+
+## Step 5 — Reply and Resolve
+
+For **each** Codex comment, reply on GitHub with what was done:
+
+**For valid (fixed) comments:**
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr}/comments \
+  -F body="Fixed — {brief description of what was changed}. {commit SHA}" \
+  -F in_reply_to={comment_id}
+```
+
+**For acknowledged comments:**
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr}/comments \
+  -F body="Acknowledged — {reason this wasn't fixed}." \
+  -F in_reply_to={comment_id}
+```
+
+**For dismissed comments:**
+```bash
+gh api repos/{owner}/{repo}/pulls/{pr}/comments \
+  -F body="Dismissed — {reason this doesn't apply}." \
+  -F in_reply_to={comment_id}
+```
+
+---
+
+## Step 6 — Return to User
+
+After all comments are addressed, present a summary and ask for merge approval:
+
+```
+## Codex Review Summary
+
+**Comments found:** {total count}
+- Fixed: {count}
+- Acknowledged: {count}
+- Dismissed: {count}
+
+{For each comment, one line:}
+- [{Valid/Acknowledged/Dismissed}] {file path}: {brief description}
+```
+
+Then ask:
+
+<AskUserQuestion>
+question: "Codex review comments have been addressed. Ready to merge?"
+options:
+  - "Merge the PR"
+  - "I want to review the changes first"
+  - "Don't merge — I'll handle it"
+</AskUserQuestion>
+
+**If "Merge the PR":** Merge using `gh pr merge {pr_number} --squash --delete-branch`
+
+**If "I want to review first":** Print the PR URL and stop. Let the user review manually.
+
+**If "Don't merge":** Print the PR URL and stop. Do not merge.