specpipe 1.0.1 → 1.0.3

package/README.md

@@ -1,376 +1,152 @@
 <p align="center">
-  <img src="docs/cover.svg" alt="Specpipe — spec-first multi-agent dev toolkit" width="100%">
+  <img src="docs/cover.svg" alt="Specpipe — spec-first toolkit for AI coding agents" width="100%">
 </p>
 
 <h1 align="center">Specpipe</h1>
 
 <p align="center">
-  A lightweight, spec-first development toolkit for agentic AI coding agents.
+  <b>One spec-first workflow, installed into every AI coding agent you use.</b>
 </p>
 
 <p align="center">
   <a href="https://specpipe.vercel.app"><b>Live demo&nbsp;→</b></a>
 </p>
 
-It enforces the cycle **spec (with acceptance scenarios) → code + tests → build pass** through skills, always-on guardrails, and a universal test runner.
+Specpipe installs a disciplined loop — **spec → code + tests → build pass** — as native skills, guard hooks, and project rules. You author it once; it lands in whichever agent you run (Claude Code, Codex, Cursor, Antigravity, OpenClaw, Hermes). Switch agents, keep the same `/sp-*` commands.
 
-**Agents:** [Claude Code](https://claude.ai/code) (full hook enforcement) plus Codex, Cursor, Antigravity, OpenClaw, and Hermes (skills + advisory guard rules). Install for one or all: `specpipe init --agents <list>|all`. See [docs/multi-agent.md](docs/multi-agent.md).
-**Works with:** Swift, TypeScript/JavaScript, Python, Rust, Go, Java/Kotlin, C#, Ruby.
-**Dependencies:** None (requires only a supported agent CLI, Node.js, Git, and Bash).
-**Optional:** [GraphAtlas](https://github.com/microvn/graphatlas) MCP server for graph-based code intelligence — six skills use it automatically when present and fall back to `grep` when it isn't.
-
----
-
-## Table of Contents
-
-1. [Philosophy](#1-philosophy)
-2. [Quick Start](#2-quick-start)
-3. [Setup](#3-setup)
-4. [Daily Workflows](#4-daily-workflows)
-5. [Commands](#5-commands)
-6. [Docs & Reference](#6-docs--reference)
-
----
-
-## 1. Philosophy
-
-### The Core Cycle
-
-```
-SPEC (with acceptance scenarios) → CODE + TESTS → BUILD PASS
+```bash
+npx specpipe init        # interactive picker — choose agents, skills, guards
 ```
 
-Every code change — feature, fix, or removal — follows this cycle. The spec is the source of truth. Acceptance scenarios (Given/When/Then) are embedded directly in the spec — no separate test plan file. If code contradicts the spec, the code is wrong.
+---
 
-### Why Spec-First?
+## Why
 
-- **Prevents drift.** Acceptance scenarios live inside the spec — no separate test plan to fall out of sync.
-- **Tests have purpose.** Scenarios derived from specs test behavior, not implementation details. This means tests survive refactoring.
-- **AI writes better code.** When an agent has a spec with concrete Given/When/Then scenarios, it generates more accurate implementations and more meaningful tests.
-- **Reviews are grounded.** Reviewers can check code against the spec rather than guessing at intent.
+AI agents write code fast and drift fast — they invent requirements, test the wrong things, and quietly break what worked. Specpipe fixes the loop, not the model:
 
-### Principles
+- **The spec is the source of truth.** Acceptance scenarios (Given/When/Then) live inside the spec; if code contradicts it, the code is wrong. No separate test plan to fall out of sync.
+- **Tests check behavior, not guesses.** They come from the spec, so they survive refactors.
+- **Guardrails are enforced, not suggested.** Hooks stop an agent from reading secrets or crawling `node_modules` *before* it happens.
+- **Learn it once.** The same commands and discipline work in every agent.
 
-1. **Specs are source of truth** — Code changes require spec updates first.
-2. **Incremental, not big-bang** — Test after each code chunk, not after everything is done.
-3. **Tests travel with code** — Every PR includes production code + tests + spec updates.
-4. **Build pass is the gate** — Nothing merges with failing tests.
-5. **Everything in the repo** — Specs, plans, tests, and code are version-controlled and reviewable.
+You don't have to be a developer to feel it: describe a feature in plain language, the agent turns it into a spec you can read, builds against it, and proves it with tests — every step reviewable.
 
 ---
 
-## 2. Quick Start
-
-**Time needed: 5 minutes.** Below is a realistic transcript — user input, what each skill actually asks, what it actually outputs. Nothing embellished.
+## Quick start
 
 ```bash
-npx specpipe init .              # install for Claude Code (default)
-# or target other agents:
-npx specpipe init . --agents cursor,codex
-npx specpipe init . --agents all
-
-claude                            # open your agent (claude, codex, cursor, …)
+npx specpipe init        # interactive: scope (project/global), agents, skills, guards
+npx specpipe init -y     # non-interactive defaults: this project, Claude, all skills + guards
 ```
 
-> The transcript below is on Claude Code. The same skills install for Codex, Cursor,
-> Antigravity, OpenClaw, and Hermes — see [Supported agents](#supported-agents).
+Then open your agent (`claude`, `codex`, `cursor`, …) and run the loop. The transcript below is on Claude Code with a Swift project; the same commands and output work in every agent.
 
-### Step 1 — Spec the feature (`/sp-plan`)
+**1 — Spec it (`/sp-plan`)**
 
 ```text
 You: /sp-plan "add tag filter to the todo list screen"
 
 Agent → running /sp-plan
   Phase 0: Codebase scan — found docs/specs/todo-list/todo-list.md (exists)
-  Phase 1: Scope Challenge — TodoList already supports text search; tag
-           filter can reuse the same query pipeline. Flagging: reuse vs rebuild.
-
-Multiple-choice: "Extend existing search, or add a separate tag filter UI?"
-  A) Extend search       — one input, parsed (text + "tag:work")   [lowest cost]
-  B) Separate tag chips  — chips below the search box              [clearer UX]
-  C) Both                 — chips drive the same query             [most work]
+  Phase 1: Scope Challenge — TodoList already has text search; the tag filter
+           can reuse the same query pipeline. Flagging: reuse vs rebuild.
 
+  "Extend existing search, or add a separate tag filter UI?"
+    A) Extend search       — one input, parsed (text + "tag:work")   [lowest cost]
+    B) Separate tag chips  — chips below the search box              [clearer UX]
+    C) Both                — chips drive the same query              [most work]
 You: B
 
-Agent: Drafting spec…
-  docs/specs/todo-list/todo-list.md  (Mode C update, snapshot created)
-
-  ## Stories (added)
+Agent: Drafting spec… docs/specs/todo-list/todo-list.md (Mode C update, snapshot created)
   ### S-007: Filter todos by tag (P0)
     AS-014: Given todos tagged [work, home], when user taps "work" chip,
             then only work-tagged todos show.
-    AS-015: Given no todos match the selected tags, when filter applied,
-            then empty state shows "No todos match these tags".
-
-  What Already Exists: TodoRepository.query() handles predicates — reuse.
+    AS-015: Given no todos match, when filter applied, then empty state shows.
   Not in Scope: saving favorite tag combinations (deferred).
 ```
 
-> **Complex spec?** Run `/sp-challenge docs/specs/<feature>/<feature>.md` before coding.
-> It spawns parallel hostile reviewers (Security Adversary, Failure Mode Analyst,
-> Assumption Destroyer, Scope & YAGNI Critic) that quote the spec and propose surgical
-> edits — e.g. "AS-014 doesn't define tag case-sensitivity → add constraint or AS".
-> Skip for simple CRUD like this tag filter.
-
-### Step 2 — Implement + build (`/sp-build`)
+**2 — Build it (`/sp-build`)** — TDD loop: coverage map → write the missing test → build green.
 
 ```text
-You: (edit TodoListView.swift, TagFilterChip.swift) — now /sp-build
-
-Agent → running /sp-build
   Phase 1.5: Coverage Map
-    [+] TodoListView.swift
-        └── applyTagFilter(selected:)
-            ├── [★★  TESTED] empty selection → returns all   (new test)
-            ├── [★★  TESTED] single tag match                 (new test)
-            ├── [GAP]         no-match empty state            (← AS-015)
-            └── [★★  TESTED] multi-tag AND semantics          (new test)
-
-  Writing test for [GAP]… building… running.
-  ✓ 14 tests passed (3 new, 0 regressions)
+    applyTagFilter(selected:)
+      ├── [★ TESTED] empty selection → returns all
+      ├── [GAP]      no-match empty state            (← AS-015)
+      └── [★ TESTED] multi-tag AND semantics
+  Writing test for [GAP]… building… ✓ 14 tests passed (3 new, 0 regressions)
 ```
 
-### Step 3 — Bug found? (`/sp-fix`)
+**3 — Fix a bug (`/sp-fix`)** — failing test first, then the one-line fix, then green.
 
 ```text
 You: /sp-fix "selecting two tags shows OR results, should be AND"
-
-Agent → running /sp-fix
-  Phase 0: Bug Path Diagram
-    applyTagFilter(selected: ["work","urgent"])
-      └── [BUG] predicate uses .contains(anyOf:) — should be .contains(allOf:)
-
-  Phase 1: writing failing test (AS-014 variant: 2 tags, AND)… FAILS ✓
-  Phase 2: changing .anyOf → .allOf in TodoRepository.swift:88 (1 line)
-  Phase 3: test now PASSES, full suite green.
-
-  DEBUG REPORT
-    Root cause: wrong set operator, regression from S-005 search refactor
-    Prevention: add AS for multi-tag AND to spec (auto-signaled)
+  [BUG] predicate uses .contains(anyOf:) — should be .contains(allOf:)
+  failing test → change .anyOf → .allOf (TodoRepository.swift:88) → suite green
 ```
 
-### Step 4 — Review + commit (`/sp-review` → `/sp-commit`)
+**4 — Review + commit (`/sp-review` → `/sp-commit`)** — failure-mode grid, then a secret-scanned conventional commit.
 
 ```text
-You: /sp-review
-
-Agent → Smart Focus: UI state + query predicate
-  Failure Mode Grid: all paths have tests ✓ error states covered ✓
-  Finding (confidence 8/10): selected-tags state not persisted across
-    navigation. Not in current spec — logged under "Not in Scope".
   Verdict: APPROVE
-
-You: /sp-commit
-
-Agent → secret scan: clean. debug-code scan: clean.
-  Staging 4 files. Conventional message:
-    feat(todo): filter list by selected tags with AND semantics
+  feat(todo): filter list by selected tags with AND semantics
   ✓ commit a1b2c3d (not pushed — run `git push` when ready)
 ```
 
-> **Complex bug?** Insert `/sp-investigate "<bug>"` before `/sp-fix`. It's read-only,
-> writes `docs/investigate/<slug>-<date>.md` with hypotheses + blast radius, then
-> `/sp-fix` auto-picks it up. Skip for trivial bugs.
-
-That's the 5 minutes. The CLI auto-detected your project (Swift + XCTest here) — no config touched.
+The CLI auto-detected the stack (Swift + XCTest) — no config touched. For a risky spec, run `/sp-challenge` between steps 1 and 2; it spawns hostile reviewers that quote the spec and propose surgical edits.
 
 ---
 
-## 3. Setup
+## Supported agents
 
-### Prerequisites
+A skill is authored once and **emitted into each agent's native format** — the markdown body is identical; only the location, frontmatter, and hook config change.
 
-| Tool | Required | Why |
-|------|----------|-----|
-| **A supported agent CLI** | Yes | Runs the skills — Claude Code, Codex, Cursor, Antigravity, OpenClaw, or Hermes |
-| **Git** | Yes | Change detection, commit workflow |
-| **Node.js** (18+) | Yes | File guard hook, JSON parsing |
-| **Bash** (4+) | Yes | Path guard hook, shell-based hooks |
-| **Language toolchain** | Yes | Whatever your project uses (Swift, npm, pytest, etc.) |
-| **[GraphAtlas](https://github.com/microvn/graphatlas)** | Optional | Graph-based code intelligence — skills prefer it over `grep` when connected |
+| Agent | Skills | Rules | Enforced guards |
+|-------|--------|-------|-----------------|
+| **Claude Code** | `.claude/skills/` | `.claude/CLAUDE.md` | `.claude/settings.json` — all five |
+| **Codex CLI** | `.agents/skills/` | `AGENTS.md` | `.codex/hooks.json` — shell |
+| **Cursor** | `.cursor/skills/` | `.cursor/rules/*.mdc` | `.cursor/hooks.json` — shell + read + file |
+| **Antigravity** | `.agents/skills/` | `.agents/rules/` | `.agents/hooks.json` — shell |
+| **OpenClaw** | `skills/` | `SPECPIPE-RULES.md` | advisory rules |
+| **Hermes** | `~/.hermes/skills/` (global only) | `SPECPIPE-RULES.md` | advisory rules |
 
-### Installation
+Guards run as **blocking hooks** wherever the agent exposes a pre-tool-call hook — they deny a tool call before it runs. Each agent enforces only the guards its hook system supports; most hook Claude-specific tool events:
 
-```bash
-npx specpipe init .                              # A — one-command install (recommended)
-npm install -g specpipe && specpipe init .       # B — global CLI, then init per project
-specpipe init --global                           # C — install skills for every project (~/.claude/skills/)
-npx specpipe init --force .                      # D — force re-install (overwrites existing files)
-npx specpipe init --only hooks,skills .          # E — selective install (specific components)
-npx specpipe init --agents cursor,codex .        # F — multi-agent (a list, or `all`)
-```
-
-Globally installed skills (`~/.claude/skills/`) are available in every project; per-project `.claude/skills/` always takes precedence, so a project can override individual skills.
-
-### Supported agents
+| Guard | Stops | Claude | Cursor | Codex | Antigravity |
+|---|---|:--:|:--:|:--:|:--:|
+| **shell** | crawling `node_modules`/build dirs, reading `.env`/keys in a command | ✓ | ✓ | ✓ | ✓ |
+| **read** | the agent reading a secret file | ✓ | ✓ | — | — |
+| **file** | *(advisory)* warns when a source file grows too large | ✓ | ✓ | — | — |
+| **comment / glob** | placeholder-comment edits, repo-wide broad globs | ✓ | — | — | — |
 
-The skills are authored once and emitted into each agent's native format on install.
-The markdown body is identical across agents; only the file location, name, and
-frontmatter change. Guardrails are **enforced via blocking hooks** for Claude, Codex,
-and Cursor (they can deny a tool call); Antigravity, OpenClaw, and Hermes get the same
-guard intent as **always-on advisory rules**.
+A guard an agent can't hook still reaches it as an **advisory rule** in that agent's rules file, so the intent travels everywhere; OpenClaw and Hermes (no blocking hooks) get all guards that way. Skills that lean on Claude-only tools degrade gracefully with a short "running outside Claude Code" note. Details: [docs/multi-agent.md](docs/multi-agent.md).
 
-| Agent | Install location | Guardrails |
-|-------|------------------|-----------|
-| **Claude Code** | `.claude/skills/sp-*/SKILL.md` + `.claude/hooks/` | Hook-enforced |
-| **Codex CLI** | `.agents/skills/sp-*/SKILL.md` | **enforced** `.codex/hooks.json` + `AGENTS.md` |
-| **Cursor** | `.cursor/skills/sp-*/SKILL.md` | **enforced** `.cursor/hooks.json` + `.cursor/rules/` |
-| **Antigravity** | `.agents/skills/sp-*/SKILL.md` | `.agent/rules/` (advisory) |
-| **OpenClaw** | `skills/sp-*/SKILL.md` | `SPECPIPE-GUARDS.md` (advisory) |
-| **Hermes** | `optional-skills/specpipe/sp-*/SKILL.md` | `SPECPIPE-GUARDS.md` (advisory) |
-
-Skills that use Claude-only tools (`AskUserQuestion`, subagents) get a "Running outside
-Claude Code" note appended for the other agents, so they degrade gracefully. The specs
-and workflow themselves are tool-agnostic. Full details: [docs/multi-agent.md](docs/multi-agent.md).
+---
 
-### What gets installed
+## What gets installed
 
-The default (`--agents claude`) layout. Other agents install the same skills into their own locations (see the table above).
+Each agent gets its own paths; the Claude layout, as an example:
 
 ```
 your-project/
-├── .specpipe/manifest.json     ← install manifest (tracks files per agent; used by upgrade/remove)
+├── .specpipe/manifest.json   ← tracks every installed file per agent (drives upgrade/remove)
 ├── .claude/
-│   ├── CLAUDE.md               ← project rules hub (auto-filled with detected stack)
-│   ├── settings.json           ← hook wiring
-│   ├── hooks/                  ← file/path/glob/comment/sensitive guards + self-review
-│   └── skills/sp-*/            ← the 13 skills (/sp-plan, /sp-build, /sp-fix, …)
-└── docs/
-    ├── specs/<feature>/        ← your specs (folder-per-feature) + snapshots/
-    └── WORKFLOW.md             ← process reference
+│   ├── CLAUDE.md             ← rules hub: spec-first cycle + guardrails + auto-detected stack
+│   ├── settings.json         ← hook wiring
+│   ├── hooks/                ← shell, read, comment, glob, file guards
+│   └── skills/sp-*/          ← the 13 skills
+└── docs/specs/<feature>/     ← your specs + snapshots (created by the skills)
 ```
 
-`specpipe remove` cleans up hooks, skills, and settings while preserving `CLAUDE.md` and `docs/`. See [docs/hooks.md](docs/hooks.md) for what each guard does.
-
-### Optional: GraphAtlas code intelligence
-
-The skills work out of the box with `grep`. When [GraphAtlas](https://github.com/microvn/graphatlas) (GA) is connected as an MCP server, six skills — `/sp-explore`, `/sp-plan`, `/sp-build`, `/sp-fix`, `/sp-review`, `/sp-investigate` — prefer it for code discovery, call-graph tracing, and blast-radius analysis. `grep` can't tell a call site from a string literal or follow re-exports; GA indexes the repo into a local graph with typed `CALL`/`IMPORT`/`OVERRIDE` edges and answers structural questions deterministically — 100% local, no LLM, no telemetry.
-
-Install and register it per the [GraphAtlas README](https://github.com/microvn/graphatlas); the skills detect it automatically and fall back to `grep` when it's absent or the index is stale. Nothing breaks — you only lose precision.
-
-### Upgrade & uninstall
-
-```bash
-npx specpipe check       # is an update available?
-npx specpipe diff        # what changed?
-npx specpipe list        # installed files + status
-npx specpipe upgrade     # smart upgrade — preserves files you customized (--force overwrites all)
-npx specpipe remove      # remove hooks/skills/settings; keeps CLAUDE.md + docs/
-```
+Other agents add their own dirs (`.agents/`, `.cursor/`, `.codex/`) and a shared `AGENTS.md`. `remove` cleans it all up; `remove --agents <list>` drops one agent and keeps shared files the others need. Your `CLAUDE.md` content and `docs/` are always preserved.
 
-After install, verify the **Project Info** in `.claude/CLAUDE.md` (language, test framework, directories) and edit if the auto-detection missed anything.
+> **GraphAtlas (optional):** with [GraphAtlas](https://github.com/microvn/graphatlas) connected as an MCP server, six skills prefer it over `grep` for call-graph and blast-radius analysis — 100% local, no LLM. Skills fall back to `grep` when it's absent; nothing breaks.
 
 ---
 
-## 4. Daily Workflows
-
-### New Project (Greenfield)
-
-> When: Brand-new project — no codebase yet (empty repo, no package manager / `src/`).
-
-```
-1. /sp-explore "what you're building"
-   → Detects greenfield, also decides app-type + stack (researched, current),
-     emits a Bootstrap Brief in docs/explore/<feature>.md.
-
-2. /sp-scaffold
-   → Generator-first runnable skeleton (core/ + one pattern-demonstrating module +
-     tests), smoke-gated (install→build→start GREEN), + ARCHITECTURE.md / ADRs.
-     Hands off only when it RUNS.
-
-3. /sp-plan → /sp-build   → normal New Feature flow, now on a runnable base.
-```
-
-### Explore Before Planning
-
-> When: Requirements are unclear, you're debating between approaches, or it's a brownfield feature with existing code to understand first.
-
-```
-1. /sp-explore "feature description"
-   → Asks questions as a Client Technical Lead — one topic at a time.
-   → Clarifies: why, behavior, boundaries, business rules, edge cases, permissions, UI.
-   → Output: docs/explore/<feature>.md
-
-2. /sp-plan "feature description"
-   → Auto-detects docs/explore/<feature>.md, skips redundant discovery.
-   → Continue with the normal New Feature flow.
-```
-
-### New Feature
+## Commands
 
-> When: Building something new — no existing code or spec.
-
-```
-1. /sp-plan "description of the feature"
-   → Generates spec with acceptance scenarios at docs/specs/<feature>/<feature>.md.
-
-2. Implement code in chunks.
-   After each chunk: /sp-build
-   Repeat until green.
-
-3. /sp-review (before merge)
-
-4. /sp-commit
-```
-
-**Example:**
-```
-/sp-plan "User authentication with email/password login, password reset via email, and session management with 24h expiry"
-```
-
-### Update Existing Feature
-
-> When: Changing behavior of something that already exists.
-
-```
-1. /sp-plan docs/specs/<feature>/<feature>.md "description of changes"
-   → Mode C handles everything: snapshot → classification → change report → apply.
-   Do NOT manually edit the spec before running /sp-plan.
-
-2. Implement the code change.
-   /sp-build
-   Fix until green.
-
-3. /sp-review → /sp-commit
-```
-
-### Bug Fix
-
-> When: Something is broken.
-
-```
-0. (OPTIONAL) /sp-investigate "description of the bug"
-   → Use for complex bugs, outages, data corruption, or when the cause is unclear.
-   → Read-only: hypothesis + blast radius + evidence, no code changes.
-   → Writes docs/investigate/<slug>-<date>.md for /sp-fix to consume.
-   → Skip for trivial/obvious bugs — go straight to /sp-fix.
-
-1. /sp-fix "description of the bug"  (or /sp-fix docs/investigate/<slug>-<date>.md)
-   → Writes failing test → fixes code → runs full suite.
-
-2. /sp-commit
-```
-
-### Remove Feature
-
-> When: Deleting code, removing deprecated functionality.
-
-```
-1. /sp-plan docs/specs/<feature>/<feature>.md "remove stories S-XXX"
-   → Mode C creates a snapshot (removing stories = Major), then marks as removed.
-
-2. Delete production code + related tests.
-
-3. Run the full test suite (your project's native test command). Fix cascading breaks.
-
-4. /sp-commit
-```
-
----
-
-## 5. Commands
-
-Thirteen slash commands. The one-liner and token cost are below; full per-skill behaviour (phases, rules, outputs) lives in **[docs/commands.md](docs/commands.md)**.
+Thirteen slash commands. Full per-skill behaviour (phases, rules, outputs) lives in **[docs/commands.md](docs/commands.md)**.
 
 | Command | What it does | Tokens |
 |---------|--------------|--------|
@@ -384,32 +160,56 @@ Thirteen slash commands. The one-liner and token cost are below; full per-skill
 | [`/sp-review`](docs/commands.md#sp-review--pre-merge-quality-gate) | Pre-merge quality gate with smart focus + failure-mode grid | 10–20k |
 | [`/sp-voices`](docs/commands.md#sp-voices--multi-llm-review-optional) | Multi-LLM review panel (optional second opinion) | 10–30k + API |
 | [`/sp-commit`](docs/commands.md#sp-commit--smart-git-commit) | Smart conventional commit with secret + debug-code scan | 2–4k |
-| [`/sp-spec-render`](docs/commands.md#sp-spec-render--render-spec-as-html-view) | Render a spec as a standalone, scannable HTML view | 3–8k |
-| [`/sp-md-render`](docs/commands.md#sp-md-render--render-any-markdown-as-html-view) | Render any long-form markdown as a standalone HTML view | 3–8k |
+| [`/sp-spec-render`](docs/commands.md#sp-spec-render--render-spec-as-html-view) | Render a spec as a standalone HTML view | 3–8k |
+| [`/sp-md-render`](docs/commands.md#sp-md-render--render-any-markdown-as-html-view) | Render any long-form markdown as an HTML view | 3–8k |
 | [`/sp-humanize`](docs/commands.md#sp-humanize--rephrase-to-human-voice) | Rephrase a plan/draft into natural, send-ready text | 2–6k |
 
 ---
 
-## 6. Docs & Reference
+## Workflows
 
-| Doc | What's in it |
-|-----|--------------|
-| [docs/commands.md](docs/commands.md) | Full per-skill reference — phases, rules, outputs, token cost guide |
-| [docs/hooks.md](docs/hooks.md) | Automatic guards — triggers, what each blocks, config, manual testing |
-| [docs/spec-format.md](docs/spec-format.md) | Spec template, AS depth by priority, snapshots, naming conventions |
-| [docs/customization.md](docs/customization.md) | Environment variables, extending `CLAUDE.md`, adding custom skills |
-| [docs/troubleshooting.md](docs/troubleshooting.md) | Hooks not firing, tests not detected, wrong base branch, … |
-| [docs/faq.md](docs/faq.md) | Common questions — specs for tiny changes, mocks, multi-language, … |
-| [docs/multi-agent.md](docs/multi-agent.md) | How one skill emits into every agent's native format |
-| [docs/architecture.md](docs/architecture.md) | CLI internals — registry, reconcile lifecycle, manifest |
-| [docs/adding-an-agent.md](docs/adding-an-agent.md) | Add support for a new agent |
+The four-step loop above is the **new feature** flow. Variants:
+
+- **Greenfield** (empty repo): `/sp-explore` (decides app-type + stack) → `/sp-scaffold` (runnable, smoke-gated skeleton) → the feature loop.
+- **Update a feature:** `/sp-plan docs/specs/<feature>/<feature>.md "what's changing"` — never hand-edit the spec; Mode C snapshots → diffs → applies. Then `/sp-build` → `/sp-review` → `/sp-commit`.
+- **Bug fix:** `/sp-fix "the bug"` (failing test → minimal fix → green). For a murky bug, run `/sp-investigate` first — read-only hypothesis + blast radius.
+- **Fuzzy requirements:** `/sp-explore "feature"` runs a one-topic-at-a-time Q&A and `/sp-plan` picks up its notes automatically.
 
 ---
 
-## Contributing
+## CLI reference
 
-Issues and PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, test suite, and the spec-first workflow this repo holds itself to. Security reports: [SECURITY.md](SECURITY.md).
+```bash
+npx specpipe init . --agents cursor,codex   # install for specific agents (a list, or `all`)
+npx specpipe init . --skills core           # skip optional render/humanize skills (or a comma list)
+npx specpipe init . --hooks none            # skills only, no guardrails (or --hooks shell,read)
+npx specpipe init --global --agents claude,codex   # install skills globally for chosen agents
 
-## License
+npx specpipe check | diff | list            # update available? · what changed? · installed status
+npx specpipe upgrade                        # smart upgrade, preserves files you customized (--force overwrites)
+npx specpipe remove [--agents <list>] [--dry-run]   # uninstall (keeps your CLAUDE.md content + docs/)
+```
+
+**Requirements:** a supported agent CLI, Git, Node.js 18+, Bash 4+, and your project's own toolchain. No dependencies are added to your project.
+
+**Global install** puts each agent's skills in its user-level dir (`~/.claude/skills/`, `~/.codex/skills/`, `~/.cursor/skills/`, `~/.gemini/antigravity-cli/skills/`, `~/.openclaw/skills/`, `~/.hermes/skills/`), so every project is covered. Per-project skills take precedence; Hermes is global-only; global hooks are Claude-only. The lifecycle remembers your skill selection — `upgrade` won't resurrect ones you deselected.
+
+After install, check the **Project Info** in `.claude/CLAUDE.md` and fix anything auto-detection missed. Per-skill behavior is tunable via env vars — see [docs/customization.md](docs/customization.md).
+
+---
+
+## Docs
+
+| Doc | What's in it |
+|-----|--------------|
+| [multi-agent.md](docs/multi-agent.md) | How one skill emits into every agent's native format (verified path/format matrix) |
+| [commands.md](docs/commands.md) | Full per-skill reference — phases, rules, outputs, token cost |
+| [hooks.md](docs/hooks.md) | The guards — triggers, what each blocks, config, manual testing |
+| [spec-format.md](docs/spec-format.md) | Spec template, AS depth by priority, snapshots, naming |
+| [customization.md](docs/customization.md) | Environment variables, extending rules, custom skills |
+| [troubleshooting.md](docs/troubleshooting.md) · [faq.md](docs/faq.md) | Hooks not firing, tests not detected, specs for tiny changes, … |
+| [architecture.md](docs/architecture.md) · [adding-an-agent.md](docs/adding-an-agent.md) | CLI internals; how to add a new agent |
+
+---
 
-[MIT](LICENSE) © Microvn
+Issues and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md). Security: [SECURITY.md](SECURITY.md). License: [MIT](LICENSE) © Microvn

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specpipe",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Spec-first development toolkit for agentic AI coding agents — installs skills + guardrails for Claude Code, Codex, Cursor, Antigravity, and more.",
   "bin": {
     "specpipe": "./bin/devkit.js",
@@ -15,6 +15,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@clack/prompts": "^1.6.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0"
   },

package/src/cli.js

@@ -18,21 +18,29 @@ export function cli(argv) {
     .command('init [path]')
     .description('Initialize a project with the dev-kit')
     .option('-f, --force', 'Overwrite existing files')
-    .option('-g, --global', 'Install skills globally to ~/.claude/skills/ (available in all projects)')
+    .option('-g, --global', 'Install skills globally (per-agent user-level dirs, all projects); honors --agents, defaults to claude')
     .option('--agents <list>', 'Target agent(s): claude,codex,cursor,antigravity,openclaw,hermes or "all" (default: claude)')
-    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,scripts,docs,config)')
+    .option('--skills <list>', 'Skills to install: all | core | comma list e.g. sp-build,sp-fix (default: all)')
+    .option('--hooks <list>', 'Guard hooks to install: all | none | comma list e.g. shell,read (default: all)')
+    .option('-y, --yes', 'Skip interactive prompts and use defaults (per-project, claude, all skills)')
+    .option('--only <components>', 'Install only specific components (comma-separated: hooks,skills,docs,config)')
     .option('--adopt', 'Adopt existing kit files without overwriting (migration from setup.sh)')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
-      const { initCommand } = await import('./commands/init.js');
-      await initCommand(path || '.', opts);
+      try {
+        const { initCommand } = await import('./commands/init.js');
+        await initCommand(path || '.', opts);
+      } catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
     });
 
   program
     .command('upgrade [path]')
     .description('Smart upgrade — preserves customized files')
     .option('-f, --force', 'Overwrite even customized files')
-    .option('-g, --global', 'Upgrade skills globally in ~/.claude/skills/')
+    .option('-g, --global', 'Upgrade the global install (every agent installed globally)')
     .option('--dry-run', 'Show what would be done without making changes')
     .action(async (path, opts) => {
       const { upgradeCommand } = await import('./commands/upgrade.js');
@@ -66,7 +74,9 @@ export function cli(argv) {
   program
     .command('remove [path]')
     .description('Uninstall dev-kit (preserves CLAUDE.md and docs/)')
-    .option('-g, --global', 'Remove global install (~/.claude/skills/, ~/.claude/hooks/, hook entries from ~/.claude/settings.json)')
+    .option('-g, --global', 'Remove global install (per-agent global sp-* skill dirs + Claude hooks/settings)')
+    .option('--agents <list>', 'Remove only these agent(s), keeping the rest (e.g. codex,cursor); shared files are kept while any remaining agent needs them')
+    .option('--dry-run', 'Show what would be removed without deleting anything')
     .action(async (path, opts) => {
       const { removeCommand } = await import('./commands/remove.js');
       await removeCommand(path || '.', opts);

package/src/commands/diff.js

@@ -16,7 +16,7 @@ export async function diffCommand(path) {
     process.exit(1);
   }
 
-  const desired = await computeDesired(getAgents(manifest));
+  const desired = await computeDesired(getAgents(manifest), manifest.skills ? new Set(manifest.skills) : null);
   let hasDiffs = false;
 
   for (const [file, d] of desired) {