@jamie-tam/forge 6.0.0

package/hooks/scripts/telemetry.sh

@@ -0,0 +1,41 @@
+#!/bin/bash
+# PostToolUse telemetry hook: logs every Skill and Task (subagent-dispatch) call.
+# Captures which skills were loaded and which agents were dispatched
+# for benchmarking harness compliance.
+#
+# Output: .forge/state/telemetry.jsonl (one JSON object per line)
+#
+# Note: the subagent-dispatch tool was renamed `Agent` → `Task` (canonical name
+# in current Claude Code releases). Both names are accepted here for backward
+# compatibility with existing telemetry written before the rename; `Task` is
+# the dispatch path going forward and the matcher in hooks.json fires on it.
+
+set -euo pipefail
+
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+STATE_DIR="$PROJECT_ROOT/.forge/state"
+TELEMETRY_FILE="$STATE_DIR/telemetry.jsonl"
+
+mkdir -p "$STATE_DIR"
+
+# Read hook input from stdin
+INPUT=$(cat)
+
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // "unknown"')
+TIMESTAMP=$(date -u '+%Y-%m-%dT%H:%M:%SZ')
+
+# Extract relevant fields based on tool type.
+# Task and Agent share input shape (subagent_type + description); accept either.
+case "$TOOL_NAME" in
+  Skill)
+    SKILL_NAME=$(echo "$INPUT" | jq -r '.tool_input.skill // "unknown"')
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"type\":\"skill\",\"name\":\"$SKILL_NAME\"}" >> "$TELEMETRY_FILE"
+    ;;
+  Task|Agent)
+    AGENT_TYPE=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // "unknown"')
+    DESCRIPTION=$(echo "$INPUT" | jq -r '.tool_input.description // ""')
+    echo "{\"timestamp\":\"$TIMESTAMP\",\"type\":\"agent\",\"name\":\"$AGENT_TYPE\",\"description\":\"$DESCRIPTION\"}" >> "$TELEMETRY_FILE"
+    ;;
+esac
+
+exit 0

package/hooks/scripts/wiki-lint.sh

@@ -0,0 +1,87 @@
+#!/bin/bash
+# PostToolUse hook: validates aiwiki/** markdown writes against their declared
+# schemas. Reads the file path from hook input, invokes the lint script if the
+# write targets a typed wiki page, surfaces findings to stderr.
+#
+# Cannot block the write (it already happened); informs the AI/user via stderr
+# so the next edit corrects the issue. Returns continue:true unconditionally.
+#
+# Skipped for: non-markdown files, files outside aiwiki/, schema files
+# themselves (they describe other pages), and fresh projects before aiwiki/
+# is scaffolded by /setup.
+
+set -uo pipefail
+
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""')
+
+# Only Edit, Write, and MultiEdit can modify files. MultiEdit shares Edit's
+# top-level file_path shape (one file, multiple edits) — the edit deltas live
+# in tool_input.edits[*] but we only need the path here (the linter re-reads
+# the file from disk, so it sees the final post-write content regardless of
+# whether the change was one Edit or many).
+case "$TOOL_NAME" in
+  Edit|Write|MultiEdit) ;;
+  *)
+    echo '{"continue":true}'
+    exit 0
+    ;;
+esac
+
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""')
+
+# Only check aiwiki/ writes
+case "$FILE_PATH" in
+  *aiwiki/*) ;;
+  *) echo '{"continue":true}'; exit 0 ;;
+esac
+
+# Skip non-markdown files
+case "$FILE_PATH" in
+  *.md) ;;
+  *) echo '{"continue":true}'; exit 0 ;;
+esac
+
+# Skip schema files themselves (they describe other pages; aren't validated against schemas)
+case "$FILE_PATH" in
+  *aiwiki/schemas/*) echo '{"continue":true}'; exit 0 ;;
+esac
+
+# Skip aiwiki/proposed/ writes during dream output; dream's lint runs separately at completion
+case "$FILE_PATH" in
+  *aiwiki/proposed/*) echo '{"continue":true}'; exit 0 ;;
+esac
+
+# Skip the wiki's own meta files (CLAUDE.md, INDEX.md, projectbrief.md)
+case "$(basename "$FILE_PATH")" in
+  CLAUDE.md|INDEX.md|projectbrief.md) echo '{"continue":true}'; exit 0 ;;
+esac
+
+# Locate inputs
+PROJECT_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
+SCHEMAS_DIR="$PROJECT_ROOT/aiwiki/schemas"
+SCRIPT_PATH="$PROJECT_ROOT/.claude/skills/support-wiki-lint/scripts/lint.mjs"
+
+# Skip if scaffolded path missing (fresh project before /setup, or installation gap)
+if [ ! -d "$SCHEMAS_DIR" ] || [ ! -f "$SCRIPT_PATH" ]; then
+  echo '{"continue":true}'
+  exit 0
+fi
+
+# Resolve the file path relative to repo root for the script
+case "$FILE_PATH" in
+  /*) REL_PATH="${FILE_PATH#$PROJECT_ROOT/}" ;;
+  *) REL_PATH="$FILE_PATH" ;;
+esac
+
+# Run lint (don't let non-zero exit kill us — we surface findings, not block)
+LINT_OUTPUT=$(node "$SCRIPT_PATH" --file "$REL_PATH" --schemas "$SCHEMAS_DIR" --root "$PROJECT_ROOT" 2>&1)
+LINT_EXIT=$?
+
+if [ $LINT_EXIT -ne 0 ]; then
+  echo "wiki-lint findings on $REL_PATH:" >&2
+  echo "$LINT_OUTPUT" >&2
+fi
+
+echo '{"continue":true}'
+exit 0

package/hooks/templates/AGENTS.md.template

@@ -0,0 +1,48 @@
+# AGENTS.md
+
+> Auto-generated by `npx @jamie-tam/forge init`. Run `/setup` in Claude Code to detect your stack and fill in the project profile.
+
+## Project
+
+<!-- Filled by /setup after stack detection -->
+- **Name:** (run /setup)
+- **Stack:** (run /setup)
+- **Test runner:** (run /setup)
+- **Package manager:** (run /setup)
+
+<!-- FORGE:START — do not edit between markers; updated by forge -->
+
+> This file is imported by `.claude/CLAUDE.md` via `@AGENTS.md` so Claude Code reads it. It also serves as the ecosystem-standard agent-context file (read by Cursor, Codex, and other tools). For the forge command catalog, skill prefix groups, and `.forge/` directory layout, see `.claude/CLAUDE.md`.
+
+## Required Checks
+
+- Run tests before committing
+- Every commit must leave the project buildable
+- No `--no-verify` on git commands
+- No hardcoded secrets
+
+## Commit Conventions
+
+Format: `type(scope): description` — lowercase, imperative mood.
+Types: `feat`, `fix`, `refactor`, `test`, `docs`, `chore`.
+
+## Key Constraints
+
+- Quality gates block phase transitions until criteria are met (see `.claude/references/common/quality-gates.md`)
+- Test-driven development is mandatory for production code (RED → GREEN → REFACTOR)
+- Code review is a chain of focused subagents: safety → craft → runtime reachability → gotcha-hunter (→ optional Codex adversarial)
+- Work state lives in `.forge/work/{type}/{name}/manifest.yaml` (type: feature|bugfix|refactor|hotfix|greenfield)
+
+## Deeper Docs
+
+| File | Contents |
+|------|----------|
+| `.claude/CLAUDE.md` | Claude Code project configuration, command catalog, First Prompts |
+| `.claude/references/common/quality-gates.md` | Gate definitions and pass/fail criteria |
+| `.claude/rules/common/` | Always-loaded coding standards (security, verification, guardrails, skill-selection) |
+
+<!-- FORGE:END -->
+
+## Project-Specific Notes
+
+<!-- Add project-specific context: key decisions, architecture notes, known issues -->

package/hooks/templates/CLAUDE.md.template

@@ -0,0 +1,45 @@
+# CLAUDE.md — Project Configuration
+
+> Auto-generated by `npx @jamie-tam/forge init`. Run `/setup` to detect your stack and fill the project profile, then customize as needed.
+
+@AGENTS.md
+
+## Project Profile
+
+```yaml
+project:
+  name: "{detected name}"
+  stack: "{detected stack}"
+  database: "{detected database}"
+  test_runner: "{detected test_runner}"
+  package_manager: "{detected package_manager}"
+```
+
+## First Prompts
+
+New to this project? Describe your goal in plain English — forge auto-routes via skills, OR invoke a command directly:
+
+- `/forge` — one-screen orientation: what's installed, what's in flight, what to run next
+- `/setup` — detect your stack and install matching language rules (run this first)
+- `/feature <name>` — develop a feature end-to-end with quality gates
+- `/bugfix <name>` — systematic debugging with root-cause analysis
+- `/refactor <name>` — restructure code without new functionality
+- `/task-force <list>` — parallel agents for a punch list of ad-hoc tasks
+- `/validate` — check skill/rule/command consistency
+
+Operational state lives in `.forge/state/`; project knowledge in `aiwiki/`.
+Claude Code's auto-memory (v2.1.59+) lives in `~/.claude/projects/<project>/memory/` — separate from `.forge/state/notepad.md`.
+
+<!-- FORGE:START — do not edit between markers; updated by forge -->
+
+## Development Workflow
+
+This project uses **forge** as its development workflow. Every session should follow it: route via skills, use the `/feature`, `/bugfix`, `/refactor` etc. commands, and keep work artifacts in `.forge/`.
+
+System structure — skills (prefix-grouped), commands, `.forge/` layout, context recovery — lives in **`.claude/rules/common/forge-system.md`** (always-on rule, auto-loaded every session).
+
+<!-- FORGE:END -->
+
+## Project-Specific Notes
+
+<!-- Add project-specific context below: key decisions, architecture notes, known issues -->

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@jamie-tam/forge",
+  "version": "6.0.0",
+  "description": "AI Development Life Cycle — structured AI-assisted development with quality gates, feature manifests, and agent coordination",
+  "type": "module",
+  "bin": {
+    "forge": "./dist/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "pretest": "tsc",
+    "test": "node --test dist/__tests__/*.test.js",
+    "prepublishOnly": "tsc"
+  },
+  "files": [
+    "dist/",
+    "agents/",
+    "commands/",
+    "skills/",
+    "hooks/",
+    "rules/",
+    "references/",
+    "protocols/",
+    "templates/"
+  ],
+  "keywords": [
+    "claude-code",
+    "sdlc",
+    "tdd",
+    "code-review",
+    "quality-gates",
+    "ai-agents",
+    "feature-tracking"
+  ],
+  "author": "aideas-jamie-tam",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/lps-ai/forge"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1"
+  }
+}

package/protocols/README.md

@@ -0,0 +1,40 @@
+# Protocols
+
+A **protocol** in this repo is a reusable consent + invocation + error-handling contract for an external CLI tool consumed by two or more skills. Protocols centralize the "how do we talk to this tool?" surface so each consuming skill only has to handle the tool-specific call site, not the cross-cutting concerns of detection, consent, error handling, and version compatibility.
+
+## Required Sections
+
+Every protocol file MUST include the following sections:
+
+- **Detection** — how a skill checks whether the tool is available (subshell command, exit code).
+- **Consent** — the user-visible consent surface, including the `.forge/local.yaml` keys this protocol owns, the prompt copy, and the first-use setup behavior.
+- **Invocation** — the command(s) used to call the tool, prompt/template structure, file-vs-inline rules, and timeouts.
+- **Presentation / Error Handling** — how results are surfaced back to the user, and what happens when the tool fails, returns empty output, times out, or has corrupted config.
+- **Constraints** — what the protocol does NOT do (lifecycle management, auto-suggestion, etc.).
+- **Version Compatibility** — minimum tool version, pinned install source (commit SHA / release tag), and any breaking-change notes.
+
+## Current Protocols
+
+- **[codex.md](codex.md)** — Codex CLI integration (Verify / Takeover / Delegate modes) for review and build skills.
+- **[graphify.md](graphify.md)** — Knowledge graph enrichment via the `/graphify` skill and `graphify` CLI for skills that benefit from architectural context.
+
+## Intake Criteria
+
+A new protocol file is justified only when ALL of the following hold:
+
+1. The tool is **external** — invoked via subshell, not a forge-internal skill.
+2. The tool is consumed by **two or more skills** — a single-skill caller belongs inline in that skill.
+3. The tool has a **user-visible consent surface** — installation prompts, mode selection, or preference storage.
+
+If any criterion fails, the integration belongs inline in the consuming skill, not as a shared protocol.
+
+## `.forge/local.yaml` Merge Contract
+
+Each protocol owns its own top-level namespace in `.forge/local.yaml`:
+
+- `codex.md` owns the `codex:` namespace.
+- `graphify.md` owns the `graphify:` namespace.
+
+Writers MUST preserve other namespaces when writing to their own. Read-modify-write the whole file; do not truncate.
+
+When a single namespace is corrupted (malformed YAML, unexpected types), the owning protocol resets only that namespace to its defaults and warns the user. Other namespaces are left untouched. If the whole file is unparseable, the protocol that detects it first resets the file to a minimal default with all known namespaces and warns the user.

package/protocols/codex.md

@@ -0,0 +1,151 @@
+# Codex Integration
+
+Protocol for Codex integration across forge skills. Skills that support Codex add a `### Codex Integration` block to their SKILL.md and follow this protocol for detection, consent, invocation, and presentation. Skills without a Codex block are unaffected. Users without Codex installed never see any Codex-related prompts. The consent flow handles user choice — skills always route to it.
+
+## Modes
+
+| Mode | Purpose | Who does the work | Risk |
+|------|---------|-------------------|------|
+| **Verify** | Codex reviews Claude's work | Claude works, Codex checks | Low — additive |
+| **Takeover** | Codex does the work, Claude reviews | Codex works, Claude checks | Medium — saves tokens |
+| **Delegate** | Codex executes the work independently — no Claude execution. Codex's output then enters the normal review pipeline (quality-code-review on the PR). | Codex works alone, then artifacts go through Claude review | Higher — build skills only (scaffold, tdd) |
+
+13 skills support both **Verify** and **Takeover**. 2 build skills use **Delegate**. The consent flow lets the user choose between Verify and Takeover per invocation, or save a preference.
+
+## Detection
+
+Run `codex --version` in a subshell. If exit code is 0, Codex is available. If non-zero, skip all Codex steps silently.
+
+- Detection runs at the point where a skill would invoke Codex, not at session start.
+- Do not cache the result across skill invocations.
+- Do not warn about Codex not being installed. Users who don't have it never see it.
+
+## Consent
+
+User preferences stored in `.forge/local.yaml` (gitignored, per-user):
+
+```yaml
+codex:
+  mode: ask         # verify | takeover | ask | never  (default: ask)  — applies to Verify/Takeover skills
+  delegate: ask     # always | ask | never             (default: ask)  — applies to Delegate build skills only
+```
+
+`codex.mode` is the shared key for Verify/Takeover skills (13 skills). `codex.delegate` is a separate key used only by build-tdd and build-scaffold. Keeping them separate prevents a `delegate` value from leaking into non-build skills whose mode check only handles Verify/Takeover/Skip.
+
+**Consent flow:**
+
+**Run consent ONCE per skill invocation**, at the Codex Mode Check step. Record the resulting mode (verify / takeover / skip) in skill-local state. Later inline Codex steps in the same skill MUST reuse that decision — do not re-prompt or re-run the consent flow.
+
+1. Detect Codex (`codex --version`). If unavailable, record `skip` and proceed without Codex.
+2. Read `.forge/local.yaml` for the `codex.mode` preference.
+3. If `verify` or `takeover` — record that mode and proceed.
+4. If `never` — record `skip` and proceed silently.
+5. If `ask` or file/key is absent — prompt the user:
+
+```
+Codex is available for [skill description].
+  (a) Claude does the work, Codex verifies
+  (b) Codex does the work, Claude reviews  (saves tokens)
+  (c) Skip Codex
+  (d) Save my preference — always use [a|b|c]
+```
+
+Option (a) = Verify mode. Option (b) = Takeover mode. Option (c) = skip.
+
+6. If user picks (d), write the choice to `.forge/local.yaml`.
+7. For **Delegate** mode (build-tdd, build-scaffold only): the skill reads `codex.delegate` (not `codex.mode`) and handles its own consent flow — see the skill's Codex Integration section. If a non-build skill ever reads `codex.mode` and finds an unexpected value (e.g., `delegate`), treat it as `ask` and re-prompt.
+
+**First-use setup:**
+
+- If `.forge/local.yaml` does not exist, create it with `codex.mode: ask`.
+- If `.gitignore` does not contain `.forge/local.yaml`, append it.
+
+## Invocation
+
+Codex is invoked via the existing Codex plugin runtime. Three commands are available — use the one that fits the skill's needs:
+
+| Command | When to Use | Supports |
+|---------|-------------|----------|
+| `adversarial-review` | Reviewing **code in git** — challenges approach, finds gaps | `--scope`, `--base`, custom focus text |
+| `review` | Reviewing **code in git** — standard defect finding | `--scope`, `--base`, no custom focus |
+| `task` | Reviewing **documents/artifacts** or **building code** | Arbitrary prompt, any files |
+
+**Command selection per skill type:**
+- **Quality skills reviewing code diffs** (code-review, security-audit): Use `adversarial-review --scope branch` with focus text. Auto-scopes to git state — no need to manually point at files.
+- **Plan/discover skills reviewing documents**: Use `task` with a custom prompt. Design artifacts and analyses aren't in git state.
+- **Build skills delegating work**: Use `task` with the skill's SKILL.md path as methodology.
+- **Debug/support skills**: Use `task` with custom prompt for hypothesis generation.
+
+**Verify template (for `task` command):**
+```
+Context: [artifact file paths — Codex reads files, not inline content]
+Task: [what Codex should do — review, critique, analyze]
+Focus: [specific concerns — gaps, security, feasibility, coverage]
+Output format: [structured findings with severity, location, and reasoning]
+```
+
+**Adversarial review invocation (for code-reviewing skills):**
+```bash
+node "${CLAUDE_PLUGIN_ROOT}/scripts/codex-companion.mjs" adversarial-review --scope branch [focus text]
+```
+
+**Delegate template (for `task` command):**
+```
+Context: [artifact file paths — task spec, architecture artifacts]
+Task: [what Codex should build]
+Methodology: [path to the skill's SKILL.md file — Codex reads and follows it]
+Output format: [implementation code following the skill's methodology]
+```
+
+**Rules:**
+
+- Pass file paths, not inline content. Codex reads current files.
+- Exception: skills at pre-artifact stages (e.g., brainstorming before a spec is written) may write a temp draft file for Codex context. Delete the temp file after the step completes.
+- Each skill defines its own prompt specifics. This section defines the template structure only.
+- Timeout: 5 minutes for verify mode, 10 minutes for delegate mode.
+
+## Presentation
+
+**Verify mode** — present a unified view:
+
+```markdown
+## Claude's Analysis
+[Claude's existing findings from the skill's normal process]
+
+## Codex's Analysis
+[Codex findings, structured with severity and location]
+
+## Disagreements
+[Where they differ, with reasoning from each side]
+[If no disagreements: "Claude and Codex agree on all findings."]
+
+## Resolution
+User decides. The existing quality gate makes the final call.
+```
+
+**Delegate mode** — no dual presentation. Codex produced the artifact. It goes through forge's standard quality gates (tests pass, coverage meets threshold, code review by Claude).
+
+## Error Handling
+
+- **Codex invocation fails** (timeout, auth error, runtime crash): Log the error. Present Claude's findings only. Note: "Codex was unavailable for this step."
+- **Codex returns empty or malformed output:** Treat as unavailable. Present Claude's findings only.
+- **`.forge/local.yaml` is corrupted:** Reset to `codex.mode: ask`. Warn user.
+- **Codex failure NEVER blocks the workflow.** Every Codex step is optional. The skill's normal process completes regardless.
+
+## Model Selection
+
+This protocol does not specify which Codex model to use. The Codex plugin handles model selection via its own configuration. Forge defers to the plugin's defaults.
+
+## Constraints
+
+1. This protocol does NOT manage Codex installation, authentication, or updates. The Codex plugin owns its own lifecycle.
+2. This protocol does NOT auto-suggest switching to Codex based on token usage or session length. The user initiates Codex usage.
+3. This protocol works unchanged if more skills opt in later. Skill names that appear above (build-tdd, build-scaffold, code-review, security-audit) are illustrative — they show how the protocol is currently consumed, not a closed set.
+
+## Version Compatibility
+
+Tested with: Codex CLI v?.? (commit pinned). Update this section when bumping CLI version.
+
+- Minimum Codex CLI: unpinned for now — relies on whatever ships in the Codex plugin currently installed in the user's harness.
+- Pinned commit: TODO — record the Codex CLI commit SHA the protocol was validated against once the Codex plugin is versioned in this repo.
+- Breaking-change notes: when Codex CLI changes the `adversarial-review` / `review` / `task` command surface or output structure, update this protocol's Invocation section and bump the recorded commit.

package/protocols/graphify.md

@@ -0,0 +1,156 @@
+# Graphify Integration (Optional)
+
+Protocol for optional knowledge graph enrichment across forge skills and commands. Graphify is a skill — graph building is handled by invoking `/graphify`. This protocol defines the reusable guard (install/build/update check) and the query interface skills use to consume graph data.
+
+## How It Works
+
+1. **`/graphify` skill** builds the graph — AST extraction (tree-sitter, free) + semantic extraction (LLM subagents) + Leiden clustering. Outputs `graphify-out/graph.json`, `graphify-out/GRAPH_REPORT.md`, and `graphify-out/graph.html`.
+2. **Skills and commands** consume the graph — read static files and run CLI queries. They do not build or manage the graph.
+3. **The guard** (below) is a reusable check any skill or command can run at its start to ensure graphify is available and the graph is current.
+
+The graphify CLI provides queries (`query`, `path`, `explain`), platform installers, hooks, and benchmarking — but has no `build` subcommand. Graph construction is orchestrated by the `/graphify` skill, which calls graphify's Python library functions (`detect`, `extract`, `build`, `cluster`, `export`, `report`) and dispatches Claude subagents for semantic extraction. This system intentionally does not use graphify's installer or hook-writing commands (`graphify install`, `graphify hook install`) — it manages its own files.
+
+## Guard: Graphify Status Check
+
+Any skill or command that benefits from graph data can run this check at its start. The guard handles install, build, and update — so the skill's own methodology only needs to focus on querying.
+
+**Step 1 — Check status:**
+
+Three independent checks:
+- **Graph file:** `test -f graphify-out/graph.json`
+- **CLI installed:** `graphify --version` (exit 0 = installed)
+- **`/graphify` skill installed:** `test -f ~/.claude/skills/graphify/SKILL.md`
+
+Combine the results:
+
+```
+graphify-out/graph.json exists?  →  CLI installed?  →  /graphify skill installed?  →  Action
+──────────────────────────────────────────────────────────────────────────────────
+No                     No                   No                            Offer full install (CLI + skill)
+No                     Yes                  No                            Offer skill install only
+No                     Yes                  Yes                           Offer build via /graphify
+Yes                    No                   (don't care)                  Use static files only
+Yes                    Yes                  No                            Use static files + CLI queries; offer skill install for /graphify --update
+Yes                    Yes                  Yes                           Offer update via /graphify --update (or use as-is)
+```
+
+**Step 2 — Prompt the user:**
+
+For skills where graphify enriches but isn't essential:
+
+```
+This skill works great with graphify (knowledge graph).
+
+  Current status: {not installed | installed, no graph | graph exists (N nodes, M communities)}
+
+  {(a) Install now — runs these commands (skill-only, no project file changes):
+         # Note: the PyPI package is `graphifyy` (double-y) — `graphify` on PyPI
+         # is a different unrelated package. The CLI binary it installs is
+         # still `graphify` (single-y). Do NOT "fix" this to `pip install graphify`.
+         pip install graphifyy
+         mkdir -p ~/.claude/skills/graphify
+         # TODO pin version — replace `v1` with a commit SHA or release tag once one is published.
+         curl -fsSL https://raw.githubusercontent.com/safishamsi/graphify/v1/skills/graphify/skill.md \
+           > ~/.claude/skills/graphify/SKILL.md
+       Then add this line to ~/.claude/CLAUDE.md (your global file):
+         - **graphify** (`~/.claude/skills/graphify/SKILL.md`) - any input to knowledge graph. Trigger: `/graphify`} ← only if not installed
+  {(b) Build graph now — /graphify}               ← only if installed but no graph
+  {(c) Update graph — /graphify --update}         ← only if graph exists
+  {(d) Skip — proceed without graph}
+```
+
+If the user picks install → run the manual-install commands above, then re-check. This path avoids modifying project files. Graphify's native `graphify install` is also available but NOT recommended here — it writes a graphify section to the project's CLAUDE.md and a PreToolUse hook to `.claude/settings.json`, which conflict with files this system manages. If a user wants those features, they can run `graphify install` themselves outside the guard. If they pick build/update → invoke the `/graphify` skill (or `/graphify --update`). If they skip → proceed without graph data.
+
+**Step 3 — Save preference (optional):**
+
+If `.forge/local.yaml` exists, respect stored preferences:
+
+```yaml
+graphify:
+  build: ask          # always | ask | never  (default: ask)
+  query: ask          # always | ask | never  (default: ask)
+  install_hint: ask   # ask | never           (default: ask)
+```
+
+- `build: always` → invoke `/graphify` or `/graphify --update` without prompting.
+- `build: never` → skip build/update silently, still use existing graph if present.
+- `query: always` → run CLI queries without prompting.
+- `query: never` → skip CLI queries, use static files only.
+- `query: ask` → prompt on first CLI query per skill invocation.
+- `install_hint: never` → don't suggest installation.
+
+**First-use setup:**
+
+- If `.forge/local.yaml` does not exist, create it with defaults (`ask` for all keys).
+- If `.gitignore` does not contain `.forge/local.yaml`, append it.
+
+### Query-only skills
+
+Skills that only use CLI queries on an existing graph (e.g., `support-debug` using `graphify path`) do not need the full guard. They just check:
+
+1. Does `graphify-out/graph.json` exist? → if no, skip graphify entirely.
+2. Is the `graphify` CLI available? → if yes, run queries. If no, read static files only.
+3. Check `query` preference in `.forge/local.yaml` before first CLI query.
+
+No install/build prompts. The graph either exists (from a prior `/graphify` or `/setup` run) or it doesn't.
+
+### Staleness
+
+Graphify manages freshness internally. The `--update` flag re-extracts only new/changed files (using content hashes and file mtimes). There is no standalone staleness check command — `--update` IS the staleness check and is cheap if nothing changed.
+
+Skills should not implement their own staleness heuristics (no mtime-vs-git-commit checks). Either offer `--update` via the guard, or use the graph as-is.
+
+## Querying the Graph
+
+### Static files
+
+Skills can read these directly — no consent needed:
+
+- **`graphify-out/graph.json`** — full graph with nodes, edges, communities
+- **`graphify-out/GRAPH_REPORT.md`** — compact summary with god nodes, community labels
+- **`graphify-out/graph.html`** — interactive visualization (reference in onboarding docs)
+
+Key structures in `graphify-out/graph.json`:
+
+- **God nodes** — highest-degree nodes (critical components, architectural hubs)
+- **Communities** — Leiden-clustered subsystems with labels and cohesion scores. Use top 20 by cohesion; beyond that is typically noise (singletons).
+- **Edge confidence** — `EXTRACTED` (trusted, from AST/source), `INFERRED` (hypothesis, verify before acting), `AMBIGUOUS` (investigation target). These labels come from semantic extraction via the `/graphify` skill.
+- **Node metadata** — `source_file`, `source_location`, `file_type`, `community`
+
+**Team-safe:** If a teammate committed `graphify-out/`, everyone benefits without needing graphify installed.
+
+### CLI commands
+
+Require the `graphify` CLI to be installed. Check `query` preference in `.forge/local.yaml` before first use.
+
+| Command | Purpose | Token Cost |
+|---------|---------|-----------|
+| `graphify query "<question>" --budget N --graph graphify-out/graph.json` | BFS traversal, token-capped answer | ~345 tokens avg |
+| `graphify query "<question>" --dfs --graph graphify-out/graph.json` | DFS traversal, trace dependency paths | ~345 tokens avg |
+| `graphify path "NodeA" "NodeB" --graph graphify-out/graph.json` | Shortest path between two concepts | Minimal |
+| `graphify explain "NodeName" --graph graphify-out/graph.json` | Plain-language node explanation | ~200 tokens |
+
+Always use `--budget` with `query` to cap token usage. Default budget: 1500 tokens.
+
+## Error Handling
+
+- CLI query fails → log error, continue with static file data only.
+- CLI query returns empty → treat as no result, do not retry.
+- `graphify-out/graph.json` is malformed → skip graph context, note "`graphify-out/graph.json` could not be parsed."
+- `pip install graphifyy` fails → note the error, proceed without graphify.
+- **Graphify failure NEVER blocks the workflow.** Every graphify step is optional enrichment.
+
+## Constraints
+
+1. Do NOT manage graph rebuilds or freshness. The user invokes `/graphify --update` themselves (or accepts the guard's offer).
+2. Do NOT invoke `graphify install` or `graphify hook install`. These commands modify CLAUDE.md and settings.json, which this system manages — the guard's install prompt uses the manual curl-based path instead. Users who want graphify's hook/CLAUDE.md integration can run `graphify install` themselves outside this workflow.
+3. Treat `graphify-out/` as read-only input (except when building via the `/graphify` skill).
+4. Always run CLI commands from the repo root, or use `--graph graphify-out/graph.json` explicitly to avoid path issues.
+
+## Version Compatibility
+
+Tested with: graphify v1 (TODO pin commit). Update when v2 lands.
+
+- Minimum graphify CLI: v1 (PyPI package `graphifyy`).
+- Pinned commit: TODO — replace the `v1` reference in the install snippet (Step 2 install URL) with a commit SHA or release tag once one is published.
+- Breaking-change notes: when graphify v2 lands or the `graphify-out/graph.json` schema changes (god-node fields, community labels, edge-confidence enum), update the "Outputs" section and the BFS/DFS query examples, then bump the recorded version here.