forge-cc 0.1.2 → 0.1.4

package/dist/setup/templates.d.ts

@@ -0,0 +1,14 @@
+export interface SetupContext {
+    projectName: string;
+    techStack: string;
+    description: string;
+    gates: string[];
+    date: string;
+}
+export declare function forgeConfigTemplate(ctx: SetupContext): string;
+export declare function claudeMdTemplate(ctx: SetupContext): string;
+export declare function stateMdTemplate(ctx: SetupContext): string;
+export declare function roadmapMdTemplate(ctx: SetupContext): string;
+export declare function lessonsMdTemplate(ctx: SetupContext): string;
+export declare function globalClaudeMdTemplate(): string;
+export declare function gitignoreForgeLines(): string;

package/dist/setup/templates.js

@@ -0,0 +1,158 @@
+// ── Setup Templates ─────────────────────────────────────────────────
+// String template functions used by /forge:setup to scaffold project files.
+// ── .forge.json ─────────────────────────────────────────────────────
+export function forgeConfigTemplate(ctx) {
+    const config = {
+        gates: ctx.gates,
+        maxIterations: 5,
+    };
+    return JSON.stringify(config, null, 2) + "\n";
+}
+// ── Project CLAUDE.md ───────────────────────────────────────────────
+export function claudeMdTemplate(ctx) {
+    const gatesList = ctx.gates.map((g) => `\`${g}\``).join(", ");
+    return `# ${ctx.projectName} — Claude Code Instructions
+
+## What This Is
+${ctx.description}
+
+**Tech:** ${ctx.techStack}
+
+## Quick Reference
+
+| Action | Command |
+|--------|---------|
+| Run verification | \`npx forge verify\` |
+| Run specific gates | \`npx forge verify --gate ${ctx.gates.join(",")}\` |
+| Check status | \`npx forge status\` |
+| Build | \`npm run build\` |
+| Test | \`npm test\` |
+
+## Code Map
+
+\`\`\`
+src/
+  (add your project structure here)
+\`\`\`
+
+## Key Docs
+
+| File | Purpose |
+|------|---------|
+| \`.planning/STATE.md\` | Current session state (<80 lines) |
+| \`.planning/ROADMAP.md\` | Milestone progress tracker |
+| \`tasks/lessons.md\` | Lessons learned (max 10 active) |
+
+## Session Protocol END (Mandatory)
+1. \`.planning/STATE.md\` — replace, don't append
+2. \`.planning/ROADMAP.md\` — check off completed milestones
+3. \`tasks/lessons.md\` — add/refine lessons (max 10, promote when full)
+4. Commit doc updates to the feature branch
+
+## Execution Rules
+- **Plan before building.** Read the PRD before touching code.
+- **Delegate immediately.** 3+ files or 3+ steps → spawn agent team.
+- **Verify everything.** Run \`npx forge verify\` after changes land.
+- **All changes via PR.** Never commit directly to main.
+- **Branch naming:** \`feat/short-description\` or \`fix/short-description\`
+
+## Verification Gates
+Active gates: ${gatesList}
+
+## Learned Rules
+(none yet)
+`;
+}
+// ── .planning/STATE.md ──────────────────────────────────────────────
+export function stateMdTemplate(ctx) {
+    return `# State — ${ctx.projectName}
+
+## Current Status
+- **Phase:** Setup complete
+- **Active project:** None
+- **Branch:** main
+
+## What Was Done
+- Initialized forge-cc scaffolding (${ctx.date})
+- Created .forge.json, CLAUDE.md, planning docs
+
+## Next Actions
+- Run \`/forge:spec\` to create a PRD for the first feature
+`;
+}
+// ── .planning/ROADMAP.md ────────────────────────────────────────────
+export function roadmapMdTemplate(ctx) {
+    return `# Roadmap — ${ctx.projectName}
+
+## Projects
+
+| Project | Status | PRD | Milestones |
+|---------|--------|-----|------------|
+| (none yet) | — | — | — |
+
+## Completed
+(none yet)
+`;
+}
+// ── tasks/lessons.md ────────────────────────────────────────────────
+export function lessonsMdTemplate(ctx) {
+    return `# Lessons Learned — ${ctx.projectName}
+
+<!-- Max 10 active one-liners. Format: - **[topic]** The rule -->
+<!-- When full, promote the most battle-tested to CLAUDE.md ## Learned Rules -->
+
+(none yet)
+`;
+}
+// ── ~/.claude/CLAUDE.md (global, for fresh installs) ────────────────
+export function globalClaudeMdTemplate() {
+    return `# Global Claude Code Instructions
+
+## Autonomous Execution Mode
+
+- **Default to action.** Plan internally, execute immediately, verify results.
+- **Use agent teams** for non-trivial work (3+ files or 3+ steps).
+- **Don't ask questions** unless truly blocked on: missing credentials, ambiguous business logic, or destructive actions on shared infrastructure. **Exception:** Always honor AskUserQuestion prompts defined in skills — those are workflow inputs, not questions.
+- **Make mistakes and iterate.** If something breaks, fix it.
+- **Summarize after completion**, not during.
+
+## Session Protocol
+
+Fresh context per phase. Memory lives in the repo, not the conversation.
+
+- **On start:** Read CLAUDE.md → STATE.md → ROADMAP.md → lessons files
+- **On finish (MANDATORY — work is not done without these):**
+  1. Update \`.planning/STATE.md\` — replace, don't append, <80 lines
+  2. Update \`.planning/ROADMAP.md\` — check off completed items
+  3. Update \`tasks/lessons.md\` — max 10 one-liners, promote to CLAUDE.md Learned Rules when full (max 15)
+  4. Commit and push doc updates on the feature branch
+  5. Write handoff summary
+- **Fresh sessions preferred** over long sessions with context bloat
+- **When lost:** Re-read planning docs rather than guessing from stale context
+
+## Verification (Mandatory)
+
+- Never mark a task complete without proving it works
+- Build must pass. Tests must pass. No exceptions.
+- Run tests, check logs, demonstrate correctness
+- If verification fails, fix it and re-verify
+
+## Lessons System
+
+- **\`tasks/lessons.md\`**: max 10 active one-liners
+- **\`CLAUDE.md ## Learned Rules\`**: max 15 permanent one-liners (promoted from lessons.md)
+- **When to write:** After any correction, and when agents hit issues
+
+## Core Principles
+
+- **Simplicity First:** Make every change as simple as possible.
+- **No Laziness:** Find root causes. No temporary fixes.
+- **Minimal Impact:** Changes should only touch what's necessary.
+`;
+}
+// ── .gitignore lines ────────────────────────────────────────────────
+export function gitignoreForgeLines() {
+    return `.forge/
+`;
+}
+//# sourceMappingURL=templates.js.map

package/dist/setup/templates.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"templates.js","sourceRoot":"","sources":["../../src/setup/templates.ts"],"names":[],"mappings":"AAAA,uEAAuE;AACvE,4EAA4E;AAU5E,uEAAuE;AAEvE,MAAM,UAAU,mBAAmB,CAAC,GAAiB;IACnD,MAAM,MAAM,GAAG;QACb,KAAK,EAAE,GAAG,CAAC,KAAK;QAChB,aAAa,EAAE,CAAC;KACjB,CAAC;IACF,OAAO,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;AAChD,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,gBAAgB,CAAC,GAAiB;IAChD,MAAM,SAAS,GAAG,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAE9D,OAAO,KAAK,GAAG,CAAC,WAAW;;;EAG3B,GAAG,CAAC,WAAW;;YAEL,GAAG,CAAC,SAAS;;;;;;;mDAO0B,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAkCtD,SAAS;;;;CAIxB,CAAC;AACF,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,eAAe,CAAC,GAAiB;IAC/C,OAAO,aAAa,GAAG,CAAC,WAAW;;;;;;;;sCAQC,GAAG,CAAC,IAAI;;;;;CAK7C,CAAC;AACF,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,OAAO,eAAe,GAAG,CAAC,WAAW;;;;;;;;;;CAUtC,CAAC;AACF,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,iBAAiB,CAAC,GAAiB;IACjD,OAAO,uBAAuB,GAAG,CAAC,WAAW;;;;;;CAM9C,CAAC;AACF,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,sBAAsB;IACpC,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA0CR,CAAC;AACF,CAAC;AAED,uEAAuE;AAEvE,MAAM,UAAU,mBAAmB;IACjC,OAAO;CACR,CAAC;AACF,CAAC"}

package/hooks/version-check.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+
+import { execSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// Read hook input from stdin
+let input = "";
+process.stdin.setEncoding("utf-8");
+process.stdin.on("data", (chunk) => {
+  input += chunk;
+});
+process.stdin.on("end", () => {
+  try {
+    checkForUpdate();
+  } catch {
+    // Silent failure — never crash, never block
+  }
+  // Always exit cleanly with no output (allow session to proceed)
+  process.exit(0);
+});
+
+function checkForUpdate() {
+  // Get installed version from forge-cc's own package.json
+  const __dirname = dirname(fileURLToPath(import.meta.url));
+  const pkgPath = join(__dirname, "..", "package.json");
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+  const currentVersion = pkg.version;
+
+  if (!currentVersion) return;
+
+  // Query npm registry for latest version (5 second timeout)
+  let latestVersion;
+  try {
+    const result = execSync("npm view forge-cc version --json", {
+      encoding: "utf-8",
+      timeout: 5000,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    latestVersion = JSON.parse(result);
+  } catch {
+    // Offline, npm slow, or package not published yet — skip silently
+    return;
+  }
+
+  if (typeof latestVersion !== "string" || !latestVersion) return;
+
+  // Compare versions using semver-compatible numeric comparison
+  if (isOutdated(currentVersion, latestVersion)) {
+    process.stderr.write(
+      `[forge] Update available: v${currentVersion} → v${latestVersion}. Run /forge:update to upgrade.\n`
+    );
+  }
+}
+
+/**
+ * Returns true if `current` is older than `latest`.
+ * Splits on ".", compares major/minor/patch numerically.
+ */
+function isOutdated(current, latest) {
+  const parseParts = (v) =>
+    v
+      .replace(/^v/, "")
+      .split(".")
+      .map((n) => parseInt(n, 10));
+
+  const cur = parseParts(current);
+  const lat = parseParts(latest);
+
+  for (let i = 0; i < 3; i++) {
+    const c = cur[i] || 0;
+    const l = lat[i] || 0;
+    if (l > c) return true;
+    if (c > l) return false;
+  }
+  return false;
+}

package/package.json

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

package/skills/forge-go.md

@@ -6,9 +6,11 @@ Execute milestones from your PRD with wave-based agent teams, self-healing verif
 
 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
+### Step 1 — Orient + Choose Mode
 
-Read project state files to determine current position:
+**This step has two parts. Complete BOTH before moving to Step 2. Do NOT read any other files, do NOT start pre-flight checks, do NOT read the PRD until both parts are done.**
+
+**Part A — Read state (only these 3 files, nothing else):**
 
 ```
 Read these files in parallel:
@@ -32,15 +34,12 @@ 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 1.5 — Choose Execution Mode (MANDATORY)
-
-**STOP. Do NOT proceed to Step 2 until this step is complete.**
+**Part B — Ask execution mode (MANDATORY — do this IMMEDIATELY after Part A):**
 
-If `--auto` was passed as an argument, set mode to auto and skip the prompt below.
+If `--auto` was passed as an argument, set mode to auto and skip the prompt.
 
-Otherwise, you MUST use the AskUserQuestion tool RIGHT NOW to ask the user which mode they want. Do not skip this. Do not assume single milestone. Do not proceed without an answer.
+Otherwise: **your very next tool call MUST be AskUserQuestion.** No file reads, no git commands, no exploration — ask the user first. Use exactly these parameters:
 
-Use AskUserQuestion with exactly these parameters:
 - question: "How should this project be executed?"
 - header: "Mode"
 - options:
@@ -48,7 +47,7 @@ Use AskUserQuestion with exactly these parameters:
   - label: "Auto (all milestones)", description: "Chain all remaining milestones with fresh context between each. After each milestone, prints a continuation prompt for the next session."
 - multiSelect: false
 
-**Wait for the user's response before continuing.** Store their choice and apply it in Step 8 (Route Next).
+**Wait for the user's response before continuing.** Do not proceed to Step 2 until you have their answer. Store the choice for Step 8 (Route Next).
 
 ### Step 2 — Pre-flight Checks
 

package/skills/forge-setup.md

@@ -0,0 +1,157 @@
+# /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.

package/skills/forge-update.md

@@ -0,0 +1,72 @@
+# /forge:update — Update Forge to Latest Version
+
+Check for updates and install the latest version of forge-cc.
+
+## Instructions
+
+### Step 1 — Check Versions
+
+Run these commands to get version info:
+
+```bash
+# Current installed version
+npm list -g forge-cc --json 2>/dev/null | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');const j=JSON.parse(d);console.log(j.dependencies?.['forge-cc']?.version||'not installed')"
+
+# Latest available version
+npm view forge-cc version
+```
+
+Parse both versions. If the command fails, handle gracefully:
+- If forge-cc is not installed globally: print "forge-cc is not installed globally. Install with: `npm install -g forge-cc`"
+- If npm view fails (offline): print "Could not reach npm registry. Check your internet connection."
+
+### Step 2 — Compare and Report
+
+Print the version status:
+
+```
+## Forge Version Check
+
+**Installed:** v{current}
+**Latest:** v{latest}
+**Status:** {Up to date / Update available}
+```
+
+If already up to date, stop here with: "You're on the latest version."
+
+### Step 3 — Update
+
+If an update is available, run:
+
+```bash
+npm install -g forge-cc@latest
+```
+
+Verify the update succeeded:
+
+```bash
+npm list -g forge-cc --json 2>/dev/null | node -e "const d=require('fs').readFileSync('/dev/stdin','utf8');const j=JSON.parse(d);console.log(j.dependencies?.['forge-cc']?.version||'failed')"
+```
+
+### Step 4 — Post-Update Check
+
+After updating, check if the current project's forge files need refreshing:
+
+1. Check if `.forge.json` exists in the current directory
+2. If it does (this is a forge project), suggest: "Run `/forge:setup` with Refresh mode to update project files to the latest templates."
+3. If it doesn't, just confirm the update.
+
+Print final summary:
+
+```
+## Update Complete
+
+**Previous:** v{old}
+**Current:** v{new}
+
+{If forge project: "Consider running `/forge:setup` (Refresh) to update project files."}
+```
+
+---
+
+Do NOT stage, commit, or push anything. This skill only manages the npm package.