gswd 0.2.0 → 1.0.0

package/README.md

@@ -1,15 +1,26 @@
-# GSWD — Get Shit Well Done
+```
+   ██████╗ ███████╗██╗    ██╗██████╗
+  ██╔════╝ ██╔════╝██║    ██║██╔══██╗
+  ██║  ███╗███████╗██║ █╗ ██║██║  ██║
+  ██║   ██║╚════██║██║███╗██║██║  ██║
+  ╚██████╔╝███████║╚███╔███╔╝██████╔╝
+   ╚═════╝ ╚══════╝ ╚══╝╚══╝ ╚═════╝
+```
 
-**Front-end system for imagining and specifying before [GSD](https://www.npmjs.com/package/get-shit-done-cc) builds.**
+**Clarity is the bottleneck, not compute. GSWD produces bulletproof specs so you can one-shot the build.**
 
-GSWD adds the missing infrastructure for **imagining and specifying** so a founder can reliably reach an execution-grade spec and then hand off to GSD with zero guessing.
+[![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
+IMAGINE  ->  SPECIFY  ->  AUDIT  ->  COMPILE
+   |            |           |           |
+Direction    Spec+IDs   Coverage   GSD Contract
 ```
 
 1. **IMAGINE** — turn a fuzzy idea into a validated product direction
@@ -23,51 +34,108 @@ Direction   Spec+IDs   Coverage   GSD Contract
 npx gswd-install
 ```
 
-This copies `/gswd:*` slash commands to `~/.claude/commands/gswd/` for use in Claude Code.
+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:init` | Initialize GSWD planning state and config |
-| `/gswd:bootstrap [@idea.md]` | Run full pipeline: imagine → specify → audit → compile |
-| `/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 |
+| `/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 |
 
-## Quick Start
+### Advanced Commands
 
-```bash
-# Install commands
-npx gswd-install
+Run stages individually if you need finer control:
 
-# In Claude Code:
-/gswd:init
-/gswd:bootstrap @idea.md
-```
-
-Or run stages manually:
-
-```bash
-/gswd:imagine @idea.md
-/gswd:specify
-/gswd:audit-spec
-/gswd:compile
-```
+| 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` | bootstrap, imagine, specify | Auto mode — minimal interruptions |
-| `--resume` | bootstrap, imagine, specify, audit-spec | Resume from last checkpoint |
-| `--skip-research` | bootstrap, imagine | Disable research agents |
+| `--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
 
@@ -96,17 +164,17 @@ Or run stages manually:
 
 Once compile is done, hand off to GSD:
 
-```bash
+```
 /gsd:plan-phase 01
 ```
 
+GSD picks up the compiled contract and builds phase by phase.
+
 ## CLI Usage
 
-GSWD also ships a CLI tool:
+GSWD also ships a CLI for scripting and non-interactive workflows:
 
 ```bash
-gswd init
-gswd bootstrap @idea.md --auto
 gswd imagine @idea.md
 gswd specify
 gswd audit

package/bin/install.js

@@ -88,8 +88,7 @@ console.log(`  ${green}✓${reset} Installed ${copied} commands to ${destDir.rep
 
 // Show available commands
 console.log(`  ${yellow}Available commands:${reset}\n`);
-console.log(`    ${cyan}/gswd:init${reset}          Initialize planning state`);
-console.log(`    ${cyan}/gswd:bootstrap${reset}     Run full pipeline (imagine → specify → audit → compile)`);
+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`);
@@ -98,4 +97,20 @@ 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:help${reset} to get started.\n`);
+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/help.md

@@ -24,34 +24,37 @@ Output the following command reference exactly:
 ## Quick Start
 
 ```
-/gswd:init                          # Initialize planning state
-/gswd:bootstrap @idea.md            # Run full pipeline (recommended)
+/gswd:start                         # Start here — describe your idea interactively
 ```
 
 ## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/gswd:init` | Initialize GSWD planning state and config |
-| `/gswd:bootstrap [@idea.md]` | Run full pipeline: imagine → specify → audit → compile |
+| `/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 |
-| `/gswd:status` | Show pipeline status and stage progress |
-| `/gswd:settings` | Configure GSWD workflow settings |
-| `/gswd:help` | Show this reference |
 
 ## Common Flags
 
 | Flag | Available On | Description |
 |------|-------------|-------------|
-| `--auto` | bootstrap, imagine, specify | Auto mode — minimal interruptions |
-| `--resume` | bootstrap, imagine, specify, audit-spec | Resume from last checkpoint |
-| `--skip-research` | bootstrap, imagine | Disable research agents |
+| `--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>` | bootstrap | Auto policy: strict, balanced, aggressive |
+| `--policy=<name>` | `/gswd:start` | Auto policy: strict, balanced, aggressive |
 
 ## Pipeline Flow
 

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

@@ -25,5 +25,5 @@ This is a read-only command that never modifies state.
 
 2. Display the CLI output directly to the user.
 
-3. If `.planning/gswd/STATE.json` does not exist, suggest running `/gswd:init` first.
+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,6 +1,6 @@
 {
   "name": "gswd",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "type": "commonjs",
   "description": "Get Shit Well Done — CLI meta-prompting and spec-generation system",
   "bin": {
@@ -18,7 +18,8 @@
   "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",

package/commands/gswd/bootstrap.md

@@ -1,58 +0,0 @@
----
-name: gswd:bootstrap
-description: Run full GSWD pipeline — imagine, specify, audit, compile
-argument-hint: "[--auto] [--resume] [--skip-research] [--policy=<name>] [@idea.md]"
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - AskUserQuestion
-  - Task
----
-<objective>
-One command to generate a GSD-ready contract from a product idea.
-
-**Runs 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
-
-**Flags:**
-- `--auto` — apply auto policy for decision-making (minimal interruptions)
-- `--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
-
-**After this command:** Review `.planning/` artifacts, then run `/gsd:plan-phase 01`.
-</objective>
-
-<process>
-1. Ensure GSWD is initialized. If `.planning/gswd/STATE.json` does not exist, run init first:
-   ```bash
-   node ./bin/gswd-tools.cjs init
-   ```
-
-2. Run the bootstrap pipeline:
-   ```bash
-   node ./bin/gswd-tools.cjs bootstrap $ARGUMENTS
-   ```
-
-3. The CLI orchestrates imagine → specify → audit → compile with checkpoint tracking.
-
-4. If `--resume` is passed and a checkpoint exists, the pipeline resumes from the last completed stage.
-
-5. Display stage banners, checkpoint boxes, and progress as the CLI emits them.
-
-6. On completion, show the Next Up block with generated artifacts and suggest `/gsd:plan-phase 01`.
-
-7. If any stage fails (especially audit), display the failure reason and suggest remediation before retrying.
-</process>

package/commands/gswd/init.md

@@ -1,40 +0,0 @@
----
-name: gswd:init
-description: Initialize GSWD planning state and config
-argument-hint: "[--project-slug <slug>]"
-allowed-tools:
-  - Bash
-  - Read
-  - Write
----
-<objective>
-Initialize GSWD planning state and config for the current project.
-
-**Creates if missing:**
-- `.planning/gswd/STATE.json` — stage tracking and checkpoint state
-- `.planning/gswd/NOTES.md` — scratch notes for GSWD workflows
-- Adds/merges `.planning/config.json` under top-level `gswd` key
-
-**Never:**
-- Deletes existing planning docs
-- Overwrites user config keys outside `gswd`
-
-**After this command:** Run `/gswd:bootstrap @idea.md` or `/gswd:imagine @idea.md`.
-</objective>
-
-<process>
-1. Run the init command via the CLI:
-   ```bash
-   node "$(dirname "$(which gswd-tools)")/gswd-tools.cjs" init $ARGUMENTS
-   ```
-   If `gswd-tools` is not on PATH, use the project-local binary:
-   ```bash
-   node ./bin/gswd-tools.cjs init $ARGUMENTS
-   ```
-
-2. Display the CLI output directly to the user.
-
-3. Show Next Up guidance:
-   - If an idea file exists: suggest `/gswd:bootstrap @idea.md`
-   - Otherwise: suggest creating an idea file first, then `/gswd:bootstrap @idea.md`
-</process>