forge-cc 0.1.3 → 0.1.5

package/README.md

@@ -8,7 +8,7 @@ Pre-PR verification harness and development workflow tool for Claude Code agents
 
 - **Verification gates** -- runs TypeScript type-checking, linting, tests, visual screenshots, runtime endpoint validation, and PRD acceptance criteria checks against your project before you commit.
 - **Mechanical enforcement** -- Claude Code PreToolUse hook and git pre-commit hook block commits that haven't passed verification. No discipline required; the machine enforces it.
-- **Workflow skills** -- `/forge:triage` turns brain dumps into Linear projects, `/forge:spec` interviews you and generates a PRD with milestones, `/forge:go` executes milestones with wave-based agent teams.
+- **Workflow skills** -- `/forge:triage` turns brain dumps into Linear projects, `/forge:spec` interviews you and generates a PRD with milestones, `/forge:go` executes milestones with wave-based agent teams, `/forge:setup` scaffolds new projects, `/forge:update` keeps forge-cc current.
 - **Linear lifecycle** -- programmatic status transitions through Backlog, Planned, In Progress, In Review, and Done. Every skill keeps Linear in sync automatically.
 
 ## Quick Start
@@ -149,6 +149,32 @@ Add to your `.claude/settings.json`:
 }
 ```
 
+### Version Check Hook
+
+Optional session hook that checks for forge-cc updates when Claude Code starts a task. Prints a one-line notice to stderr if a newer version is available. Never blocks execution.
+
+Add to `.claude/settings.local.json`:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node node_modules/forge-cc/hooks/version-check.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`/forge:setup` installs this hook automatically.
+
 ### Git Pre-Commit Hook
 
 Standard git hook for non-Claude-Code environments. Same four checks as the PreToolUse hook.
@@ -208,6 +234,18 @@ Execute the next pending milestone from your PRD with wave-based agent teams. Ea
 
 **Flow:** Orient (read state) -> pre-flight checks -> execute waves -> verify -> update state -> (optional) create PR.
 
+### `/forge:setup` -- Initialize or Refresh a Project
+
+Bootstrap a new project with forge-cc scaffolding (`.forge.json`, `CLAUDE.md`, planning docs, hooks), or refresh an existing project's files to the latest templates while preserving your learned rules and lessons.
+
+**Flow:** Detect project -> choose mode (Fresh/Refresh) -> configure gates -> create files -> patch global config -> install hooks -> summary.
+
+### `/forge:update` -- Update Forge
+
+Check for newer versions of forge-cc and install the latest. After updating, suggests running `/forge:setup` in Refresh mode to pick up new templates.
+
+**Flow:** Check versions -> compare -> update via npm -> post-update check.
+
 ## Linear Integration
 
 forge-cc manages the full Linear project lifecycle:
@@ -226,12 +264,12 @@ For a new developer joining the team:
 
 1. **Clone the repo** that uses forge-cc.
 2. **Install dependencies:** `npm install` (forge-cc should be in `devDependencies`).
-3. **Run verification:** `npx forge verify` -- confirms your environment is set up correctly.
-4. **Check status:** `npx forge status` -- shows current branch and last verification.
-5. **Install the hook** (optional but recommended): add the PreToolUse hook to `.claude/settings.json` (see Enforcement section above).
-6. **Create a `.forge.json`** if the auto-detected gates don't match your needs.
+3. **Run `/forge:setup`** -- scaffolds `.forge.json`, `CLAUDE.md`, planning docs, and installs hooks automatically. Or set up manually:
+   - `npx forge verify` to confirm your environment.
+   - Add the PreToolUse hook to `.claude/settings.json` (see Enforcement section).
+   - Create `.forge.json` if auto-detected gates don't match.
 
-That's it. The gates run the same commands your CI does, so if `npx forge verify` passes locally, CI will pass too.
+The gates run the same commands your CI does, so if `npx forge verify` passes locally, CI will pass too.
 
 ## Project Structure
 
@@ -249,8 +287,9 @@ forge-cc/
     state/              # Session state reader/writer (STATE.md, ROADMAP.md)
     spec/               # Spec interview engine + PRD generation
     go/                 # Execution engine + verify loop + PR creation
-  skills/               # Claude Code skill definitions (/forge:triage, /forge:spec, /forge:go)
-  hooks/                # Installable hook files (PreToolUse)
+    setup/              # Setup templates for project scaffolding
+  skills/               # Claude Code skill definitions (/forge:triage, /forge:spec, /forge:go, /forge:setup, /forge:update)
+  hooks/                # Installable hook files (PreToolUse, version-check)
   tests/                # Test suite (vitest)
   .forge.json           # Default configuration
 ```

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,133 @@
+// ── 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
+- **On start:** Read CLAUDE.md → .planning/STATE.md → .planning/ROADMAP.md → tasks/lessons.md
+- **When lost:** Re-read planning docs, don't guess from stale context
+
+## 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.
+- **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
+
+## How to Work
+- **Follow instructions exactly.** Skills, CLAUDE.md rules, and workflow steps are tested — execute every step as written, including all AskUserQuestion prompts.
+- **Default to action.** Don't ask for confirmation. Plan internally, execute, verify.
+- **Iterate on failure.** Fix what breaks. Only stop to ask when truly blocked on missing credentials, ambiguous business requirements, or destructive actions on shared infrastructure.
+- **Use agent teams** for non-trivial work (3+ files or 3+ steps).
+
+## Verification
+- Never mark complete without proving it works.
+- Build and tests must pass. Run them.
+
+## Principles
+- Simple changes only. Find root causes. Touch only 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;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;gBAqCtD,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;;;;;;;;;;;;;;CAcR,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.3",
+  "version": "0.1.5",
   "description": "Pre-PR verification harness for Claude Code agents — gate runner + CLI + MCP server",
   "type": "module",
   "license": "MIT",

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.