gswd 0.1.0 → 1.0.0

package/README.md

@@ -0,0 +1,187 @@
+```
+   ██████╗ ███████╗██╗    ██╗██████╗
+  ██╔════╝ ██╔════╝██║    ██║██╔══██╗
+  ██║  ███╗███████╗██║ █╗ ██║██║  ██║
+  ██║   ██║╚════██║██║███╗██║██║  ██║
+  ╚██████╔╝███████║╚███╔███╔╝██████╔╝
+   ╚═════╝ ╚══════╝ ╚══╝╚══╝ ╚═════╝
+```
+
+**Clarity is the bottleneck, not compute. GSWD produces bulletproof specs so you can one-shot the build.**
+
+[![npm version](https://img.shields.io/npm/v/gswd)](https://www.npmjs.com/package/gswd)
+[![License: MIT](https://img.shields.io/npm/l/gswd)](https://opensource.org/licenses/MIT)
+![Tests](https://img.shields.io/badge/tests-518%20passing-brightgreen)
+
+GSWD is the thinking stage before [GSD](https://www.npmjs.com/package/get-shit-done-cc) builds. The bottleneck in building with AI isn't the AI — it's feeding it a spec that's complete, traceable, and unambiguous. GSWD forces that rigor upfront so you can hand off a GSD contract and build the first time, without guessing.
+
+## Pipeline
+
+```
+IMAGINE  ->  SPECIFY  ->  AUDIT  ->  COMPILE
+   |            |           |           |
+Direction    Spec+IDs   Coverage   GSD Contract
+```
+
+1. **IMAGINE** — turn a fuzzy idea into a validated product direction
+2. **SPECIFY** — turn that direction into a build-ready, traceable spec
+3. **AUDIT** — enforce full coverage (no missing journeys, no orphan requirements)
+4. **COMPILE** — deterministically generate the GSD contract files
+
+## Install
+
+```bash
+npx gswd-install
+```
+
+Copies `/gswd:*` slash commands to `~/.claude/commands/gswd/` for use in Claude Code.
+
+## Quick Start
+
+```
+/gswd:start
+```
+
+That's it. Describe your idea conversationally — GSWD walks you through the full pipeline.
+
+**Have an idea file already?**
+
+```
+/gswd:start @idea.md
+```
+
+## What It Looks Like
+
+```
+$ /gswd:start
+
+Describe your product idea (or press Enter to type it out):
+> A task management app for remote teams with async standups
+> and no meeting culture overhead.
+
+Got it. Let me confirm before we begin:
+
+  Product: Async standup and task coordination tool for remote teams
+  Angle:   No meeting overhead — async-first by design
+
+Does this capture your idea? [yes]
+
+┌─────────────────────────────────────────────┐
+│  IMAGINE — Validating direction              │
+│  Running research agents...                  │
+└─────────────────────────────────────────────┘
+
+  Researching market landscape...
+  Analyzing ICP and GTM angles...
+  Freezing key decisions...
+
+  ✓ DECISIONS.md
+  ✓ IMAGINE.md  ICP.md  GTM.md  COMPETITION.md
+
+┌─────────────────────────────────────────────┐
+│  SPECIFY — Building execution-grade spec     │
+└─────────────────────────────────────────────┘
+
+  ✓ SPEC.md  JOURNEYS.md  ARCHITECTURE.md
+  ✓ INTEGRATIONS.md  NFR.md
+
+┌─────────────────────────────────────────────┐
+│  AUDIT — Checking spec coverage              │
+└─────────────────────────────────────────────┘
+
+  Checking journeys... PASS
+  Checking requirements... PASS
+  Checking architecture linkage... PASS
+
+  ✓ AUDIT.md — PASS
+
+┌─────────────────────────────────────────────┐
+│  COMPILE — Generating GSD contract           │
+└─────────────────────────────────────────────┘
+
+  ✓ PROJECT.md  REQUIREMENTS.md  ROADMAP.md  STATE.md
+
+  Done! Run /gsd:plan-phase 01 to start building.
+```
+
+## Commands
+
+### Primary Commands
+
+| Command | Description |
+|---------|-------------|
+| `/gswd:start` | Full pipeline: intake -> imagine -> specify -> audit -> compile |
+| `/gswd:status` | Show pipeline status and stage progress |
+| `/gswd:settings` | Configure GSWD workflow settings |
+| `/gswd:help` | Show command reference |
+
+### Advanced Commands
+
+Run stages individually if you need finer control:
+
+| Command | Description |
+|---------|-------------|
+| `/gswd:imagine [@idea.md]` | Validate direction and freeze key decisions |
+| `/gswd:specify` | Build execution-grade spec with traceable IDs |
+| `/gswd:audit-spec` | Audit spec for coverage — produces PASS/FAIL |
+| `/gswd:compile` | Compile spec into GSD contract docs |
+
+## Common Flags
+
+| Flag | Available On | Description |
+|------|-------------|-------------|
+| `--auto` | `/gswd:start`, imagine, specify | Auto mode — minimal interruptions |
+| `--resume` | `/gswd:start`, imagine, specify, audit-spec | Resume from last checkpoint |
+| `--skip-research` | `/gswd:start`, imagine | Disable research agents |
+| `--auto-fix` | audit-spec | Auto-fix gaps found during audit |
+| `--phase-style=thin\|thick` | compile | Phase sizing for GSD roadmap |
+| `--policy=<name>` | `/gswd:start` | Auto policy: strict, balanced, aggressive |
+
+## Output Artifacts
+
+### GSWD artifacts (in `.planning/`)
+
+- `IMAGINE.md` — product vision and direction
+- `ICP.md` — ideal customer profile
+- `GTM.md` — go-to-market strategy
+- `COMPETITION.md` — competitive landscape
+- `DECISIONS.md` — frozen decisions, success metrics, risks
+- `SPEC.md` — full product specification
+- `JOURNEYS.md` — user journeys with traceable IDs
+- `ARCHITECTURE.md` — system architecture
+- `INTEGRATIONS.md` — external integrations
+- `NFR.md` — non-functional requirements
+- `AUDIT.md` — coverage matrix and PASS/FAIL verdict
+
+### Compiled GSD contract (in `.planning/`)
+
+- `PROJECT.md` — project context
+- `REQUIREMENTS.md` — scoped requirements
+- `ROADMAP.md` — phased execution plan
+- `STATE.md` — project memory
+
+## After GSWD
+
+Once compile is done, hand off to GSD:
+
+```
+/gsd:plan-phase 01
+```
+
+GSD picks up the compiled contract and builds phase by phase.
+
+## CLI Usage
+
+GSWD also ships a CLI for scripting and non-interactive workflows:
+
+```bash
+gswd imagine @idea.md
+gswd specify
+gswd audit
+gswd compile
+gswd status
+```
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Colors
+const cyan = '\x1b[36m';
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+const banner = '\n' +
+  cyan + '   ██████╗ ███████╗██╗    ██╗██████╗\n' +
+  '  ██╔════╝ ██╔════╝██║    ██║██╔══██╗\n' +
+  '  ██║  ███╗███████╗██║ █╗ ██║██║  ██║\n' +
+  '  ██║   ██║╚════██║██║███╗██║██║  ██║\n' +
+  '  ╚██████╔╝███████║╚███╔███╔╝██████╔╝\n' +
+  '   ╚═════╝ ╚══════╝ ╚══╝╚══╝ ╚═════╝' + reset + '\n' +
+  '\n' +
+  '  Get Shit Well Done ' + dim + 'v' + pkg.version + reset + '\n' +
+  '  Imagine, specify, audit, and compile — before GSD builds.\n';
+
+console.log(banner);
+
+// Parse args
+const args = process.argv.slice(2);
+const hasHelp = args.includes('--help') || args.includes('-h');
+const hasUninstall = args.includes('--uninstall') || args.includes('-u');
+
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx gswd-install [options]\n
+  ${yellow}Options:${reset}
+    ${cyan}-u, --uninstall${reset}    Remove GSWD commands from ~/.claude/commands/gswd/
+    ${cyan}-h, --help${reset}         Show this help message\n
+  ${yellow}What it does:${reset}
+    Copies GSWD slash command files to ~/.claude/commands/gswd/
+    so they are available as /gswd:* commands in Claude Code.\n`);
+  process.exit(0);
+}
+
+// Resolve paths
+const claudeDir = process.env.CLAUDE_CONFIG_DIR
+  ? process.env.CLAUDE_CONFIG_DIR
+  : path.join(os.homedir(), '.claude');
+const destDir = path.join(claudeDir, 'commands', 'gswd');
+const srcDir = path.join(__dirname, '..', 'commands', 'gswd');
+
+// Uninstall
+if (hasUninstall) {
+  if (fs.existsSync(destDir)) {
+    fs.rmSync(destDir, { recursive: true });
+    console.log(`  ${green}✓${reset} Removed ${destDir.replace(os.homedir(), '~')}\n`);
+  } else {
+    console.log(`  ${yellow}⚠${reset} Nothing to remove — ${destDir.replace(os.homedir(), '~')} does not exist.\n`);
+  }
+  process.exit(0);
+}
+
+// Verify source commands exist
+if (!fs.existsSync(srcDir)) {
+  console.error(`  ${yellow}✗${reset} Source commands not found at ${srcDir}`);
+  console.error(`    This usually means the package is not installed correctly.\n`);
+  process.exit(1);
+}
+
+// Create destination directory
+fs.mkdirSync(destDir, { recursive: true });
+
+// Copy all .md files
+const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.md'));
+let copied = 0;
+
+for (const file of files) {
+  const src = path.join(srcDir, file);
+  const dest = path.join(destDir, file);
+  fs.copyFileSync(src, dest);
+  copied++;
+}
+
+console.log(`  ${green}✓${reset} Installed ${copied} commands to ${destDir.replace(os.homedir(), '~')}\n`);
+
+// Show available commands
+console.log(`  ${yellow}Available commands:${reset}\n`);
+console.log(`    ${cyan}/gswd:start${reset}         Start here — idea to GSD contract`);
+console.log(`    ${cyan}/gswd:imagine${reset}       Validate direction and freeze decisions`);
+console.log(`    ${cyan}/gswd:specify${reset}       Build execution-grade spec`);
+console.log(`    ${cyan}/gswd:audit-spec${reset}    Audit spec coverage — PASS/FAIL`);
+console.log(`    ${cyan}/gswd:compile${reset}       Compile spec into GSD contract docs`);
+console.log(`    ${cyan}/gswd:status${reset}        Show pipeline status`);
+console.log(`    ${cyan}/gswd:settings${reset}      Configure GSWD settings`);
+console.log(`    ${cyan}/gswd:help${reset}          Show command reference`);
+console.log('');
+console.log(`  ${green}Done!${reset} Launch Claude Code and run ${cyan}/gswd:start${reset} to get started.\n`);
+
+// Non-blocking update check — silently ignored on network failure
+const https = require('https');
+https.get(`https://registry.npmjs.org/${pkg.name}/latest`, (res) => {
+  let data = '';
+  res.on('data', chunk => data += chunk);
+  res.on('end', () => {
+    try {
+      const latest = JSON.parse(data).version;
+      if (latest && latest !== pkg.version) {
+        console.log(`\n  ${yellow}Update available:${reset} ${pkg.version} \u2192 ${latest}`);
+        console.log(`  Run ${cyan}npx gswd-install${reset} to update.\n`);
+      }
+    } catch (_) {}
+  });
+}).on('error', () => {});

package/commands/gswd/audit-spec.md

@@ -0,0 +1,50 @@
+---
+name: gswd:audit-spec
+description: Audit spec for full coverage — produces PASS/FAIL
+argument-hint: "[--auto-fix] [--resume]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Task
+---
+<objective>
+Enforce full coverage across the specification. Produces a coverage matrix and PASS/FAIL verdict.
+
+**Creates/updates:**
+- `.planning/AUDIT.md` — coverage matrix, gap analysis, verdict
+
+**Checks:**
+- All journeys have linked FRs and NFRs
+- No orphan requirements (FRs/NFRs not linked to any journey)
+- Edge cases, error states, empty states are covered
+- Auth/session and onboarding/activation flows exist
+- ID formats follow conventions (J-*, FR-*, NFR-*, I-*, C-*)
+
+**Flags:**
+- `--auto-fix` — automatically attempt to fix gaps found during audit
+- `--resume` — continue from last checkpoint
+
+**Hard gate:**
+- `/gswd:compile` cannot run unless audit is PASS.
+
+**After this command:** If PASS, run `/gswd:compile`. If FAIL, fix gaps and re-run.
+</objective>
+
+<process>
+1. Verify specify stage is complete by checking `.planning/gswd/STATE.json`.
+
+2. Run the audit workflow:
+   ```bash
+   node ./bin/gswd-tools.cjs audit $ARGUMENTS
+   ```
+
+3. The CLI runs deterministic coverage checks across all spec artifacts.
+
+4. If `--auto-fix` is enabled, the CLI will attempt to fix gaps automatically.
+
+5. Display the coverage matrix and PASS/FAIL verdict.
+
+6. On PASS: show Next Up: `/gswd:compile`
+   On FAIL: show gap summary and suggest fixes before re-running `/gswd:audit-spec`
+</process>

package/commands/gswd/compile.md

@@ -0,0 +1,43 @@
+---
+name: gswd:compile
+description: Compile spec into GSD contract docs
+argument-hint: "[--phase-style=thin|thick] [--milestone=v1|v2]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+<objective>
+Deterministically generate GSD contract docs from the audited specification.
+
+**Creates/updates:**
+- `.planning/PROJECT.md` — project context for GSD
+- `.planning/REQUIREMENTS.md` — scoped requirements with FR/NFR IDs
+- `.planning/ROADMAP.md` — phased execution plan
+- `.planning/STATE.md` — project memory and state
+
+**Flags:**
+- `--phase-style=thin|thick` — thin phases (1-2 tasks) or thick phases (3-5 tasks)
+- `--milestone=v1|v2` — which milestone scope to compile
+
+**Hard gate:**
+- Audit must be PASS before compile can run
+- Contract validator must pass (Section 9 of spec)
+
+**After this command:** Review generated contract, then run `/gsd:plan-phase 01`.
+</objective>
+
+<process>
+1. Verify audit stage is PASS by checking `.planning/gswd/STATE.json`.
+
+2. Run the compile workflow:
+   ```bash
+   node ./bin/gswd-tools.cjs compile $ARGUMENTS
+   ```
+
+3. The CLI deterministically transforms spec artifacts into GSD contract format.
+
+4. Display the generated contract summary with phase count and requirement mapping.
+
+5. Show Next Up: review `.planning/PROJECT.md`, `.planning/REQUIREMENTS.md`, `.planning/ROADMAP.md`, `.planning/STATE.md`, then run `/gsd:plan-phase 01`.
+</process>

package/commands/gswd/help.md

@@ -0,0 +1,79 @@
+---
+name: gswd:help
+description: Show available GSWD commands and usage guide
+---
+<objective>
+Display the complete GSWD command reference.
+
+Output ONLY the reference content below. Do NOT add:
+- Project-specific analysis
+- Git status or file context
+- Next-step suggestions
+- Any commentary beyond the reference
+</objective>
+
+<process>
+Output the following command reference exactly:
+
+---
+
+# GSWD Command Reference
+
+**Get Shit Well Done** — front-end system for imagining and specifying before GSD builds.
+
+## Quick Start
+
+```
+/gswd:start                         # Start here — describe your idea interactively
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `/gswd:start` | Full pipeline: intake -> imagine -> specify -> audit -> compile |
+| `/gswd:status` | Show pipeline status and stage progress |
+| `/gswd:settings` | Configure GSWD workflow settings |
+| `/gswd:help` | Show this reference |
+
+## Advanced Commands
+
+| Command | Description |
+|---------|-------------|
+| `/gswd:imagine [@idea.md]` | Validate direction and freeze key decisions |
+| `/gswd:specify` | Build execution-grade spec with traceable IDs |
+| `/gswd:audit-spec` | Audit spec for coverage — produces PASS/FAIL |
+| `/gswd:compile` | Compile spec into GSD contract docs |
+
+## Common Flags
+
+| Flag | Available On | Description |
+|------|-------------|-------------|
+| `--auto` | `/gswd:start`, imagine, specify | Auto mode — minimal interruptions |
+| `--resume` | `/gswd:start`, imagine, specify, audit-spec | Resume from last checkpoint |
+| `--skip-research` | `/gswd:start`, imagine | Disable research agents |
+| `--auto-fix` | audit-spec | Auto-fix gaps found during audit |
+| `--phase-style=thin\|thick` | compile | Phase sizing for GSD roadmap |
+| `--policy=<name>` | `/gswd:start` | Auto policy: strict, balanced, aggressive |
+
+## Pipeline Flow
+
+```
+/gswd:imagine  →  /gswd:specify  →  /gswd:audit-spec  →  /gswd:compile
+     ↓                  ↓                   ↓                    ↓
+ DECISIONS.md       SPEC.md            AUDIT.md           PROJECT.md
+ IMAGINE.md         JOURNEYS.md        (PASS/FAIL)        REQUIREMENTS.md
+ ICP.md             ARCHITECTURE.md                        ROADMAP.md
+ GTM.md             INTEGRATIONS.md                        STATE.md
+ COMPETITION.md     NFR.md
+```
+
+## After GSWD
+
+Once compile is done, hand off to GSD:
+```
+/gsd:plan-phase 01
+```
+
+---
+</process>

package/commands/gswd/imagine.md

@@ -0,0 +1,52 @@
+---
+name: gswd:imagine
+description: Validate product direction and freeze key decisions
+argument-hint: "[--auto] [--resume] [--skip-research] [@idea.md]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+  - Task
+---
+<objective>
+Turn a fuzzy product idea into a validated direction with frozen decisions.
+
+**Creates/updates:**
+- `.planning/IMAGINE.md` — product vision and direction
+- `.planning/ICP.md` — ideal customer profile
+- `.planning/GTM.md` — go-to-market strategy
+- `.planning/COMPETITION.md` — competitive landscape
+- `.planning/DECISIONS.md` — frozen decisions, success metrics, risks
+
+**Hard gate to complete:**
+- `.planning/DECISIONS.md` must include:
+  - **Frozen Decisions** (>= 8)
+  - **Success Metrics** (1-3)
+  - **Out of Scope**
+  - **Risks & Mitigations** (>= 5)
+
+**Flags:**
+- `--auto` — apply auto policy for decision-making
+- `--resume` — continue from last checkpoint
+- `--skip-research` — disable research agents (faster, offline-friendly)
+
+**After this command:** Run `/gswd:specify` to build the execution-grade spec.
+</objective>
+
+<process>
+1. Ensure GSWD is initialized. If `.planning/gswd/STATE.json` does not exist, run init first.
+
+2. Run the imagine workflow:
+   ```bash
+   node ./bin/gswd-tools.cjs imagine $ARGUMENTS
+   ```
+
+3. The CLI runs the imagine workflow which may spawn research agents (unless `--skip-research`).
+
+4. Interactive prompts will ask the founder to confirm or override key decisions.
+
+5. Display stage banners, checkpoint progress, and decision summaries as emitted.
+
+6. On completion, show Next Up: `/gswd:specify`
+</process>

package/commands/gswd/settings.md

@@ -0,0 +1,46 @@
+---
+name: gswd:settings
+description: Configure GSWD workflow settings interactively
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+---
+<objective>
+Interactive editor for `.planning/config.json` under the `gswd` key.
+
+**Configurable settings:**
+- `mode` — balanced / strict / aggressive
+- `strict_gates` — enforce hard gates (true/false)
+- `max_parallel_agents` — parallel agent limit (1-8)
+- `external_research` — enable research agents (true/false)
+- `integration_budget_usd_month` — monthly integration budget cap
+- `doc_verbosity` — normal / verbose / minimal
+- `phase_style` — thin / thick
+- `auto.policy` — auto mode policy (strict/balanced/aggressive)
+
+**Never overwrites** user config keys outside `gswd`.
+</objective>
+
+<process>
+1. Read current config:
+   ```bash
+   node ./bin/gswd-tools.cjs config read
+   ```
+
+2. Present current settings to the user using AskUserQuestion with the current values as defaults.
+
+3. Ask for each setting group:
+   - **Mode & Gates**: mode (balanced/strict/aggressive), strict_gates (on/off)
+   - **Agents**: max_parallel_agents, external_research (on/off)
+   - **Output**: doc_verbosity (normal/verbose/minimal), phase_style (thin/thick)
+   - **Auto Policy**: auto policy (strict/balanced/aggressive), budget, defaults
+
+4. Merge updated settings:
+   ```bash
+   node ./bin/gswd-tools.cjs config merge --overrides '<json>'
+   ```
+
+5. Display confirmation with the updated settings.
+</process>

package/commands/gswd/specify.md

@@ -0,0 +1,49 @@
+---
+name: gswd:specify
+description: Build execution-grade spec with traceable IDs
+argument-hint: "[--auto] [--resume] [--integration-budget=<usd>]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+  - Task
+---
+<objective>
+Turn validated direction into a build-ready, traceable specification.
+
+**Creates/updates:**
+- `.planning/SPEC.md` — full product specification
+- `.planning/JOURNEYS.md` — user journeys (J-001, J-002, ...)
+- `.planning/ARCHITECTURE.md` — system architecture and components
+- `.planning/INTEGRATIONS.md` — external integrations
+- `.planning/NFR.md` — non-functional requirements
+
+**Hard gate to complete:**
+- `J-*`, `FR-*`, `NFR-*` IDs exist and are cross-linked
+- Each journey has: preconditions, steps, success outcome, failure modes (>= 2), acceptance tests (>= 1), linked FR + NFR
+
+**Flags:**
+- `--auto` — apply auto policy for decision-making
+- `--resume` — continue from last checkpoint
+- `--integration-budget=<usd>` — monthly integration budget cap
+
+**After this command:** Run `/gswd:audit-spec` to validate coverage.
+</objective>
+
+<process>
+1. Verify imagine stage is complete by checking `.planning/gswd/STATE.json`.
+
+2. Run the specify workflow:
+   ```bash
+   node ./bin/gswd-tools.cjs specify $ARGUMENTS
+   ```
+
+3. The CLI builds the spec iteratively, creating journeys and requirements with traceable IDs.
+
+4. Interactive prompts will ask for decisions on architecture, integrations, and priorities.
+
+5. Display progress with ID allocation summaries and cross-link status.
+
+6. On completion, show Next Up: `/gswd:audit-spec`
+</process>

package/commands/gswd/start.md

@@ -0,0 +1,123 @@
+---
+name: gswd:start
+description: Imagine, specify, audit, and compile — from idea to GSD contract
+argument-hint: "[@idea.md]"
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - AskUserQuestion
+  - Task
+---
+
+<objective>
+One command to go from a product idea to a GSD-ready contract.
+
+**Pipeline stages (run sequentially):**
+1. Imagine — validate direction and freeze decisions
+2. Specify — build execution-grade spec with traceable IDs
+3. Audit — enforce full coverage (PASS/FAIL)
+4. Compile — deterministically generate GSD contract docs
+
+**Outputs:**
+- Full GSWD bundle (IMAGINE.md, DECISIONS.md, SPEC.md, JOURNEYS.md, etc.)
+- Compiled GSD contract: PROJECT.md, REQUIREMENTS.md, ROADMAP.md, STATE.md
+
+**Power-user flags (all optional):**
+- `--auto` — apply auto policy for decision-making (minimal interruptions). Requires @idea.md to skip interactive intake.
+- `--policy=<name>` — select named policy: `strict`, `balanced`, `aggressive`
+- `--resume` — continue from last checkpoint in `.planning/gswd/STATE.json`
+- `--skip-research` — disable research agents
+
+**Hard gates:**
+- Cannot finish if audit is FAIL
+- In auto mode, cannot finish if policy requires manual approvals and they are not present
+</objective>
+
+<process>
+
+## Step 1 — Initialize (silently)
+
+Run init via Bash:
+
+```bash
+node ./bin/gswd-tools.cjs init
+```
+
+Check if `.planning/gswd/STATE.json` existed before this call. If STATE.json did not already exist (i.e., this is the first run), show one line: "Initialized GSWD for <project-name>" where project-name is derived from the current directory basename (e.g., `basename $PWD`). If STATE.json already existed, say nothing — initialization is silent.
+
+The init call is idempotent and safe to run regardless of existing state.
+
+## Step 2 — Check for existing state
+
+Read `.planning/gswd/STATE.json` using the Read tool. Branch on the `stage` field:
+
+- If `stage` is not `done` and not `init` (work is in progress): ask the user "Resume from [stage]? [yes / start fresh]"
+  - If yes: add `--resume` to the bootstrap call arguments assembled in Step 4
+  - If start fresh: proceed without `--resume`
+- If `stage` is `done` (pipeline already completed): ask the user "You already have a completed spec. Start fresh or resume?"
+  - If resume: add `--resume` to the bootstrap arguments
+  - If fresh: proceed without `--resume`
+- If `stage` is `init` or STATE.json was just created by Step 1: proceed directly to Step 3 (no resume prompt)
+
+## Step 3 — Collect idea
+
+**Path A — Idea file provided in $ARGUMENTS**
+
+Detect Path A if $ARGUMENTS contains any word starting with `@` OR a path ending in `.md`.
+
+1. Read the idea file content using the Read tool
+2. Summarize the idea in 2-3 sentences
+3. Ask: "Did I get that right? [yes / edit]"
+4. If the user chooses edit: let them revise, then re-summarize and re-confirm
+5. Once confirmed, proceed to Step 4
+
+**Path B — No file provided in $ARGUMENTS**
+
+1. Ask the user (via conversation, not AskUserQuestion tool): "Describe your product idea — include what it does, who it's for, and what makes now the right time to build it."
+   - The intake prompt should feel like one natural question, not a form. The hints guide but don't constrain.
+   - For partial or vague descriptions: use judgment — either ask a brief follow-up or proceed with what's given.
+2. After the user responds, summarize their response in 2-3 sentences
+3. Ask: "Did I get that right? [yes / edit]"
+4. If the user chooses edit: let them revise, then re-summarize and re-confirm
+5. Once confirmed, write the confirmed summary to `.planning/gswd/intake.md` using the Write tool so it can be passed to the bootstrap CLI:
+
+```
+# Idea
+
+<confirmed summary here>
+```
+
+6. Proceed to Step 4
+
+Note: "Did I get that right?" is the key moment — it is the last manual touchpoint before automated stages run.
+
+## Step 4 — Run the bootstrap pipeline
+
+Assemble the CLI command:
+
+- Base: `node ./bin/gswd-tools.cjs bootstrap`
+- If Path A: append the original `$ARGUMENTS` (contains the file path and any flags as-is)
+- If Path B: append `@.planning/gswd/intake.md` as the idea file argument, then append any flags from `$ARGUMENTS` that are NOT file paths (e.g., `--skip-research`, `--policy=balanced`)
+- If `--auto` is in `$ARGUMENTS` but no file was provided (Path B): note that `--auto` applies to pipeline stages after intake; proceed with interactive intake first, then pass `--auto` to the bootstrap call along with the intake.md path
+- If `--resume` was added in Step 2: include it in the arguments
+
+Run the assembled command via Bash:
+
+```bash
+node ./bin/gswd-tools.cjs bootstrap <assembled arguments>
+```
+
+## Step 5 — Show pipeline progress
+
+Display stage banners, checkpoint boxes, and output as the CLI emits them.
+
+## Step 6 — On completion
+
+Show the Next Up block with generated artifacts and suggest running `/gsd:plan-phase 01`.
+
+## Step 7 — On failure
+
+If any stage fails (especially audit), display the failure reason and suggest remediation before retrying.
+
+</process>

package/commands/gswd/status.md

@@ -0,0 +1,29 @@
+---
+name: gswd:status
+description: Show GSWD pipeline status and stage progress
+allowed-tools:
+  - Bash
+  - Read
+---
+<objective>
+Display the current GSWD pipeline status.
+
+**Shows:**
+- Stage status: IMAGINE / SPECIFY / AUDIT / COMPILE — each with not_started / in_progress / done / pass / fail
+- Last run timestamp
+- Quick links to key docs
+- Current auto mode and policy settings
+
+This is a read-only command that never modifies state.
+</objective>
+
+<process>
+1. Run the status command:
+   ```bash
+   node ./bin/gswd-tools.cjs status
+   ```
+
+2. Display the CLI output directly to the user.
+
+3. If `.planning/gswd/STATE.json` does not exist, suggest running `/gswd:start` first.
+</process>

package/lib/bootstrap.ts

@@ -17,6 +17,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 
 import { initState, readState, writeState, writeCheckpoint } from './state.js';
+import type { StageStatus } from './state.js';
 import { getGswdConfig } from './config.js';
 import type { GswdConfig } from './config.js';
 import { renderBanner, renderCheckpoint, renderNextUp } from './render.js';
@@ -287,7 +288,7 @@ export function validateStageArtifacts(
  */
 export function shouldSkipStage(
   stage: BootstrapStage,
-  state: { stage_status: Record<string, string> },
+  state: { stage_status: StageStatus | Record<string, string> },
   planningDir: string,
   resume: boolean
 ): boolean {

package/lib/imagine.ts

@@ -301,13 +301,11 @@ export async function runImagine(options: ImagineOptions): Promise<ImagineResult
         };
       }
       // Allocate ID ranges for imagine agents before spawning (FNDN-05)
-      if (spawnFn) {
-        try {
-          allocateIdRange(statePath, 'J', 'journey-mapper', 50);
-          allocateIdRange(statePath, 'FR', 'market-researcher', 50);
-        } catch {
-          // Non-fatal — ID allocation failure should not block imagine
-        }
+      try {
+        allocateIdRange(statePath, 'J', 'journey-mapper', 50);
+        allocateIdRange(statePath, 'FR', 'market-researcher', 50);
+      } catch {
+        // Non-fatal — ID allocation failure should not block imagine
       }
       agentResults = await orchestrateAgents(
         IMAGINE_AGENTS,

package/lib/state.ts

@@ -207,7 +207,7 @@ export function updateStageStatus(
   if (!state) {
     throw new Error(`Cannot read STATE.json at ${statePath}`);
   }
-  (state.stage_status as Record<string, string>)[stage] = status;
+  (state.stage_status as unknown as Record<string, string>)[stage] = status;
   writeState(statePath, state);
 }
 

package/package.json

@@ -1,22 +1,25 @@
 {
   "name": "gswd",
-  "version": "0.1.0",
+  "version": "1.0.0",
   "type": "commonjs",
   "description": "Get Shit Well Done — CLI meta-prompting and spec-generation system",
   "bin": {
     "gswd": "./bin/gswd-tools.cjs",
-    "gswd-tools": "./bin/gswd-tools.cjs"
+    "gswd-tools": "./bin/gswd-tools.cjs",
+    "gswd-install": "./bin/install.js"
   },
   "files": [
     "bin/",
     "lib/",
     "templates/",
-    "agents/"
+    "agents/",
+    "commands/"
   ],
   "scripts": {
     "test": "node --import tsx --test tests/*.test.ts",
     "test:cjs": "node --test tests/*.test.cjs",
-    "build": "tsc"
+    "build": "tsc",
+    "prepublishOnly": "npm test && npm run build"
   },
   "devDependencies": {
     "typescript": "^5.7.0",