forge-cc 0.1.25 → 0.1.27

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-cc",
-  "version": "0.1.25",
+  "version": "0.1.27",
   "description": "Pre-PR verification harness for Claude Code agents — gate runner + CLI + MCP server",
   "type": "module",
   "license": "MIT",

package/skills/forge-go.md

@@ -158,7 +158,7 @@ For each wave, in order:
 
 **Build Agent Prompts:**
 
-For each agent in the wave, construct a prompt that includes:
+For each agent in the wave, construct a prompt that includes **ALL 10 items below — do not skip any.** Items 9 and 10 are mandatory context that prevent repeated mistakes and ensure consistent agent behavior:
 
 1. **Agent identity:** "You are **{agent-name}** working on Milestone {N}: {name}."
 2. **Team context:** "You are part of team `{slug}-m{N}`. Use SendMessage to communicate with the executive and other builders."
@@ -168,8 +168,8 @@ For each agent in the wave, construct a prompt that includes:
 6. **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.
 7. **Subagent guidance:** "You may spawn subagents for research (Explore type — read-only) or implementation grunt work (general-purpose type). Use subagents for tasks that don't require team coordination."
 8. **Conflict avoidance:** "Do NOT modify files outside your assignment. If you discover a need to change a file owned by another agent, send a message to the executive describing the conflict instead of making the change."
-9. **Lessons:** Read `tasks/lessons.md` and include all active lessons.
-10. **Rules:**
+9. **Lessons (MANDATORY):** Read `tasks/lessons.md` and include the full text of all active lessons in the prompt. These are hard-won fixes for recurring mistakes — omitting them causes agents to repeat known errors.
+10. **Rules (MANDATORY):** Include these rules verbatim in every agent prompt:
     - 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
@@ -235,14 +235,14 @@ If `.forge.json` includes `visual` in gates or specifies a `devServerUrl`, captu
 
 After mechanical gates pass, engage the reviewer agent:
 
-1. **Send diff to reviewer:** Use SendMessage to send the wave's git diff to the reviewer agent, along with:
+1. **Send diff to reviewer:** Use SendMessage to send **ALL of the following** to the reviewer agent. Do not send partial context — the reviewer cannot do its job without every item:
    - The PRD milestone section including:
      - The **Goal** line (what this milestone delivers)
      - All `- [ ]` checklist items from the milestone (these are the acceptance criteria)
      - The **User Stories** section from the PRD (for context on what users expect)
-   - The full git diff for the wave
+   - The full git diff for the wave (run `git diff --cached` or `git diff HEAD` — do not summarize or truncate)
    - CLAUDE.md rules and architecture decisions
-   - The list of files changed and their ownership
+   - The list of files changed and their ownership (which agent created/modified which files)
    - If the visual gate ran, include the screenshot file paths:
      - Before: `.forge/screenshots/before/*.png` (if captured in Step 2)
      - After: `.forge/screenshots/after/*.png`

package/skills/forge-setup.md

@@ -39,21 +39,31 @@ options:
 
 ### Step 3 — Configure Gates
 
-Ask the user which verification gates to enable:
+Ask the user which verification gates to enable. **AskUserQuestion supports max 4 options — use TWO questions to cover all 8 gates:**
 
 <AskUserQuestion>
-question: "Which verification gates should be active?"
+question: "Which core gates should be active? (Recommended: all four)"
+header: "Core gates"
 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"
+  - "types — TypeScript type checking (tsc --noEmit) (Recommended)"
+  - "lint — ESLint / Biome linting (Recommended)"
+  - "tests — Vitest / Jest test runner (Recommended)"
   - "prd — PRD completeness check"
 </AskUserQuestion>
 
-Default recommendation: `types`, `lint`, `tests`.
+<AskUserQuestion>
+question: "Enable any advanced gates? These require extra setup (Playwright, dev server, API access)."
+header: "Advanced gates"
+multiSelect: true
+options:
+  - "visual — Playwright screenshot regression (requires Playwright + Chromium)"
+  - "runtime — Start the app and check for crashes (requires devServerUrl)"
+  - "review — AI code review (runs during forge verify)"
+  - "codex — Codex PR review polling (runs after PR creation)"
+</AskUserQuestion>
+
+Combine selections from both questions into the final gates list.
 
 Also collect project metadata (skip in Refresh mode if `.forge.json` already has values):
 
@@ -235,12 +245,13 @@ The target hook entry is:
 }
 ```
 
-**Merge logic:**
-1. Parse the existing file (or start with `{}`).
-2. Ensure `hooks.PreToolUse` exists as an array.
-3. Check if any entry in `hooks.PreToolUse` already has a hook with `command` containing `version-check.js`. If so, skip — already installed.
-4. Otherwise, append the hook entry to `hooks.PreToolUse`.
-5. Write the merged result back to `.claude/settings.local.json`, preserving all existing settings.
+**Merge logic — follow ALL 5 steps. Do NOT overwrite the file; you MUST read-merge-write to preserve existing user settings:**
+
+1. Parse the existing file (or start with `{}`). **Use the Read tool first** — never write without reading.
+2. Ensure `hooks.PreToolUse` exists as an array. If the key is missing, create it. If it exists, preserve all existing entries.
+3. Check if any entry in `hooks.PreToolUse` already has a hook with `command` containing `version-check.js`. **If found, skip — already installed. Do not duplicate it.**
+4. If NOT found, append the hook entry to `hooks.PreToolUse`. Do not replace existing entries.
+5. Write the merged result back to `.claude/settings.local.json`, preserving ALL existing settings (permissions, other hooks, custom keys).
 
 Create the `.claude/` directory if it doesn't exist (`mkdir -p .claude`).
 
@@ -265,8 +276,11 @@ Once all gates pass, automatically create a branch, commit, open a PR, and poll
 
 **Create branch and commit:**
 
+**IMPORTANT — CRLF check is mandatory before staging.** Run `git diff --stat` first. If any files show changes but have zero meaningful content diff (CRLF-only / whitespace-only noise on unrelated files), discard them with `git checkout -- <file>` BEFORE running `git add`. Skipping this check causes unrelated files to be included in the commit.
+
 ```bash
 git checkout -b feat/forge-setup
+git diff --stat  # Check for CRLF noise — discard any whitespace-only changes on unrelated files
 git add -A
 git commit -m "feat: initialize forge workflow scaffolding
 
@@ -280,8 +294,6 @@ Co-Authored-By: Claude <noreply@anthropic.com>"
 git push -u origin feat/forge-setup
 ```
 
-**Important:** Before `git add -A`, check `git diff --stat` for CRLF-only noise on unrelated files. If any files show changes but have zero content diff, discard them with `git checkout -- <file>` before staging.
-
 **Open PR:**
 
 ```bash

package/skills/forge-spec.md

@@ -199,9 +199,9 @@ The PRD should follow this structure:
 
 Write the final PRD to `.planning/prds/{project-slug}.md`.
 
-After writing the PRD file, also:
+After writing the PRD file, **execute BOTH steps below — do not skip either**:
 
-1. **Create status file:** Write `.planning/status/<slug>.json` with all milestones set to "pending". Include `linearProjectId` from the project selected in Step 1 (this is the Linear project UUID — required for `/forge:go` to sync issue status automatically):
+1. **Create status file:** Write `.planning/status/<slug>.json` with all milestones set to "pending". **You MUST include `linearProjectId`** — this is the Linear project UUID from the project selected in Step 1. Without it, `/forge:go` cannot sync Linear issue or project state and will silently skip all Linear operations. Copy the exact project ID string — do not omit this field:
    ```json
    {
      "project": "{project name}",
@@ -268,12 +268,14 @@ Use mcp__linear__create_issue with:
   - milestoneId: the milestone ID just created
 ```
 
-After all milestones and issues are created, transition the project to "Planned":
+**After all milestones and issues are created, transition the project to "Planned" — this is a separate mandatory step, do not skip it:**
 
 ```
 Use mcp__linear__update_project to set the project state to "planned".
 ```
 
+**The project is a separate entity from its milestones and issues.** Creating milestones and issues does NOT automatically update the project state. You must explicitly call `mcp__linear__update_project`. Without this transition, `/forge:go` will find the project still in "Backlog" and the state machine will reject the "In Progress" transition.
+
 Print a summary:
 
 ```