forge-cc 0.1.24 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-cc",
-  "version": "0.1.24",
+  "version": "0.1.26",
   "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`
@@ -362,12 +362,12 @@ Check for the Linear project ID in this priority order:
 
 If a Linear project ID is found:
 
-1. Transition issues for the completed milestone to appropriate state:
-   - If this was the **last milestone**: move issues to "In Review"
+1. **Transition issues** for the completed milestone:
+   - If this was the **last milestone**: use `mcp__linear__update_issue` on each issue to set state 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"
+2. If this is the **last milestone**, **also transition the project itself** (separate from issues):
+   - Use `mcp__linear__update_project` to set the project state to "In Review". **Do not skip this — the project is a separate entity from its issues.**
    - Create a PR (see Step 8)
 
 If no Linear project ID is found in either location, skip this step silently.
@@ -514,12 +514,12 @@ At the START of milestone execution (between Step 2 and Step 3), check for the L
 1. `linearProjectId` field in `.planning/status/<slug>.json`
 2. `linearProject` field in `.forge.json`
 
-If a Linear project ID is found:
+If a Linear project ID is found, **execute ALL four steps below — do not skip any**:
 
-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."
+1. **Find issues:** Use `mcp__linear__list_issues` with the project ID to find issues associated with this milestone.
+2. **Transition issues:** Use `mcp__linear__update_issue` on each issue to set state to "In Progress".
+3. **Transition the project:** Use `mcp__linear__update_project` to set the project state to "In Progress". **This is a separate step from transitioning issues — do not skip it.** The project and its issues are independent entities in Linear.
+4. **Add comment:** Use `mcp__linear__create_comment` on each milestone issue with the body: "Starting execution via forge:go."
 
 If no Linear project ID is found, skip silently.
 

package/skills/forge-setup.md

@@ -235,12 +235,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 +266,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 +284,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:
 
 ```