gsdd-cli 0.27.0 → 0.28.0

package/README.md

@@ -2,11 +2,11 @@
 
 # Workspine
 
-Workspine is a repo-native delivery spine for AI-assisted software work: planning, checking, execution, verification, and handoff live in the repo so any agent or runtime can pick up where the last one stopped.
+Workspine is a Spec Driven Development framework for AI-assisted software work: planning, checking, execution, verification, and handoff live in the repo, so any agent or runtime can pick up where the last one stopped. Decisions keep their why.
 
-Directly validated today: Claude Code, Codex CLI, OpenCode. Qualified support: Cursor, Copilot, Gemini.
+Proof status: one real consumer lifecycle with Codex checker support. Qualified support: Cursor, Copilot, Gemini.
 
-The public product name is Workspine. The retained technical contracts remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.planning/`.
+The public product name is Workspine. The retained technical contracts remain `gsdd-cli`, `gsdd`, `gsdd-*`, and `.work/`.
 
 [![npm version](https://img.shields.io/npm/v/gsdd-cli?style=for-the-badge&logo=npm&logoColor=white&color=CB3837)](https://www.npmjs.com/package/gsdd-cli)
 [![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
@@ -29,10 +29,10 @@ Tracked consumer proof pack: [docs/proof/consumer-node-cli/README.md](docs/proof
 
 | Workflow | Writes | What for |
 |----------|--------|----------|
-| `gsdd-new-project` | `.planning/SPEC.md`, `ROADMAP.md` | Define the project and phases |
-| `gsdd-plan` | `.planning/phases/N/PLAN.md` | Research and review before any code gets written |
-| `gsdd-execute` | `.planning/phases/N/SUMMARY.md` | Implement the approved plan, nothing more |
-| `gsdd-verify` | `.planning/phases/N/VERIFICATION.md` | Confirm the plan's claims are actually true |
+| `gsdd-new-project` | `.work/SPEC.md`, `ROADMAP.md` | Define the project and phases |
+| `gsdd-plan` | `.work/phases/N/PLAN.md` | Research and review before any code gets written |
+| `gsdd-execute` | `.work/phases/N/SUMMARY.md` | Implement the approved plan, nothing more |
+| `gsdd-verify` | `.work/phases/N/VERIFICATION.md` | Confirm the plan's claims are actually true |
 
 The discipline: plan first, execute only what's approved, verify before closing. Each phase summary carries forward what was decided, so the next session starts with context instead of from scratch.
 
@@ -40,15 +40,15 @@ For agent continuity across long sessions, `gsdd next` reads `.work/` plus repo
 
 `gsdd next` keeps the human surface tight and the agent surface structured. JSON packets include typed `next_action` values for CLI commands, workflow skills, manual review, and user-question gates. Blocking questions, decisions, graph rebuilds, and dogfood findings use explicit subcommands; duplicate question, decision, and dogfood IDs replay as unchanged when the content matches and fail unless `--replace` is passed when the content differs. The continuity graph records answer and supersession edges so future agents can reconstruct decision history without rereading raw transcripts.
 
-Workspine ships 14 workflows. The package and CLI are `gsdd-cli` / `gsdd-*` — retained as the technical contract under the Workspine product name.
+Workspine ships 13 workflows. The package and CLI are `gsdd-cli` / `gsdd-*` — retained as the technical contract under the Workspine product name.
 
 ---
 
 ## What This Is
 
-Workspine gives coding agents a durable workflow spine for work that spans sessions, agents, or runtimes. It does not host a control plane; it writes portable planning and proof artifacts into the repo.
+Workspine gives coding agents a durable workflow for work that spans sessions, agents, or runtimes. There is no hosted service; it writes portable planning and proof artifacts into the repo.
 
-Workspine began as a fork of Get Shit Done and keeps the verification-first delivery spine while stripping runtime lock-in.
+Workspine began as a fork of Get Shit Done and keeps the verification-first workflow while stripping runtime lock-in.
 
 ---
 
@@ -60,7 +60,42 @@ Workspine began as a fork of Get Shit Done and keeps the verification-first deli
 npx -y gsdd-cli init
 ```
 
-`init` is the guided install wizard for repo-local setup. It creates `.agents/skills/gsdd-*` workflow entrypoints and the `.planning/bin/gsdd*` helper runtime in the current repo; optional runtime adapters improve native discovery.
+This creates:
+
+1. `.work/` — durable workspace with templates, role contracts, and config
+2. `.agents/skills/gsdd-*` — compact open-standard workflow entrypoints for agents
+3. `.work/bin/gsdd.mjs` — repo-local helper runtime for deterministic workflow commands inside generated skills (run helper commands from the repo root)
+4. Optional tool-specific adapters you choose in the install wizard (Claude skills/commands/agents, OpenCode commands/agents, Codex CLI agents, optional governance)
+
+Then pick the first workflow lane that matches your situation:
+
+- `gsdd-new-project` for greenfield work, fuzzy brownfield work, or milestone-shaped work
+- `gsdd-quick` for a concrete bounded brownfield change
+- `gsdd-map-codebase` first when the repo is unfamiliar, risky, or needs a deeper baseline before choosing a lane
+
+In a terminal, `npx -y gsdd-cli init` opens a guided install wizard. If you installed the package globally, `gsdd init` is the equivalent shorthand:
+
+- Step 1: select the runtimes/vendors you want to support
+- Step 2: decide separately whether repo-wide `AGENTS.md` governance is worth installing
+- Step 3: configure planning defaults in the same guided flow
+
+Portable `.agents/skills/gsdd-*` skills and the repo-local `.work/bin/gsdd.mjs` helper runtime are always generated. The wizard controls extra native adapters and optional governance, not the portable baseline. Workflow helper commands assume the repo root as the current working directory.
+When those generated surfaces exist locally, `npx -y gsdd-cli health` checks them against current render output instead of asking you to trust manual review. If installed globally, `gsdd health` is equivalent.
+
+### Launch Proof Status
+
+- **Recorded proof:** the proof pack below records a full plan -> execute -> verify lifecycle on a real consumer project, including Codex checker support. Claude Code and OpenCode run the same generated workflow surface.
+- **Qualified support:** Cursor, Copilot, and Gemini CLI can use the shared `.agents/skills/` surface when their skill or slash discovery sees it; this release does not claim the same runtime proof or ergonomics.
+- **Runtime-surface freshness:** Installed generated skills and native adapters are renderer-checked locally; repair stays deterministic through `npx -y gsdd-cli update` or, when globally installed, `gsdd update`.
+
+Start with the public proof pack:
+
+- [Brownfield proof](docs/BROWNFIELD-PROOF.md)
+- [Exported consumer proof pack](docs/proof/consumer-node-cli/README.md)
+- [Runtime support matrix](docs/RUNTIME-SUPPORT.md)
+- [Verification discipline](docs/VERIFICATION-DISCIPLINE.md)
+
+### Quickstart (after init)
 
 Invoke after init:
 
@@ -85,7 +120,7 @@ npx -y gsdd-cli install --global --auto
 npx -y gsdd-cli install --global --tools claude,opencode,codex,copilot
 ```
 
-Use `--auto` for non-interactive install into detected local agent homes. Use `--tools <targets>` when you want to override detection explicitly. When run in a TTY without `--tools` or `--auto`, `install --global` lets you select which agents to install. It does not create `.planning/` in the current repo. It writes Workspine-managed skills, native agent surfaces, and per-runtime manifests under the selected agent homes:
+Use `--auto` for non-interactive install into detected local agent homes. Use `--tools <targets>` when you want to override detection explicitly. When run in a TTY without `--tools` or `--auto`, `install --global` lets you select which agents to install. It does not create `.work/` in the current repo. It writes Workspine-managed skills, native agent surfaces, and per-runtime manifests under the selected agent homes:
 
 | Target | Global surfaces |
 |--------|-----------------|
@@ -94,7 +129,7 @@ Use `--auto` for non-interactive install into detected local agent homes. Use `-
 | Codex CLI | `~/.agents/skills`, `~/.codex/agents` |
 | GitHub Copilot CLI | `~/.agents/skills`, `~/.copilot/agents` |
 
-Install availability is not a parity claim. Claude Code, OpenCode, and Codex CLI remain the directly validated runtimes; GitHub Copilot CLI is available as a qualified global target.
+Install availability is not a parity claim. Repo proof currently covers Claude Code, OpenCode, and Codex CLI paths; GitHub Copilot CLI is available as a qualified global target.
 
 OpenCode honors `OPENCODE_CONFIG_DIR` for commands and agents; Workspine installs portable skills once in the shared agent-compatible global root.
 
@@ -108,11 +143,11 @@ OpenCode honors `OPENCODE_CONFIG_DIR` for commands and agents; Workspine install
 
 ### Team Use
 
-Commit `.planning/` so the team shares specs, roadmaps, phase plans, and verification reports. Use `commitDocs` in `.planning/config.json` to control whether documentation changes are expected as part of workflow execution. Each developer runs `init --tools <their-tool>` for their own repo-local runtime adapters without changing the shared delivery artifacts.
+Commit `.work/` so the team shares specs, roadmaps, phase plans, and verification reports. Use `commitDocs` in `.work/config.json` to control whether documentation changes are expected as part of workflow execution. Each developer runs `init --tools <their-tool>` for their own repo-local runtime adapters without changing the shared delivery artifacts.
 
 ### What to Track in Git
 
-Track `.planning/`, `.agents/skills/`, and any selected runtime adapters that are part of the team workflow. Track durable `.work/` contract and research files when they define shared milestone truth. Do not track `.planning/.local/` or mutable `.work` runtime files such as `state.json`, graph logs, open questions, evidence manifests, handoff notes, or raw dogfood drafts unless you deliberately export or sanitize them.
+Track `.work/`, `.agents/skills/`, and any selected runtime adapters that are part of the team workflow. Track durable `.work/` contract and research files when they define shared milestone truth. Do not track `.work/.local/` or mutable `.work` runtime files such as `state.json`, graph logs, open questions, evidence manifests, handoff notes, or raw dogfood drafts unless you deliberately export or sanitize them.
 
 ---
 
@@ -128,7 +163,7 @@ npx -y gsdd-cli models profile budget    # minimize cost
 
 ## Troubleshooting
 
-Inside a repo-local `.planning/` workspace, start with `npx -y gsdd-cli health`. It checks local generated runtime surfaces against current render output and reports whether `npx -y gsdd-cli update` can repair drift. To repair or refresh a personal global install, rerun `npx -y gsdd-cli install --global --auto` or explicitly scope it with `npx -y gsdd-cli install --global --tools <targets>`. For details, see the [User Guide](docs/USER-GUIDE.md).
+Inside a repo-local `.work/` workspace, start with `npx -y gsdd-cli health`. It checks local generated runtime surfaces against current render output and reports whether `npx -y gsdd-cli update` can repair drift. To repair or refresh a personal global install, rerun `npx -y gsdd-cli install --global --auto` or explicitly scope it with `npx -y gsdd-cli install --global --tools <targets>`. For details, see the [User Guide](docs/USER-GUIDE.md).
 
 ---
 
@@ -139,12 +174,12 @@ Use Workspine when a feature takes more than one session, or when you need to sw
 | Tool | Good for | vs Workspine |
 |------|----------|--------------|
 | **Workspine** | Work that spans sessions, agents, or runtimes where plans and proof need to stay in the repo | — |
-| [GSD](https://github.com/gsd-build/get-shit-done) | Broad AI prompting suite — 81 commands, 78 workflows, 33 agents | Workspine is narrower: 14 workflows, fewer moving parts for the human in the loop |
+| [GSD](https://github.com/gsd-build/get-shit-done) | Broad AI prompting suite — 81 commands, 78 workflows, 33 agents | Workspine is narrower: 13 workflows, fewer moving parts for the human in the loop |
 | [OpenSpec](https://openspec.dev/) | Living spec + change proposals in a lightweight format | Workspine adds the execution, verification, and handoff layer on top of planning |
 | [LeanSpec](https://www.lean-spec.dev/docs/guide/first-principles) | Minimal specs that fit LLM context | Workspine adds workflow gates and runtime entrypoints for when you need the full structure |
 | [GitHub Spec Kit](https://github.com/github/spec-kit) | Spec-first planning workflows in `.specify/` | Similar space; Workspine is one CLI with one delivery loop instead of a broader ecosystem |
 | [Kiro](https://kiro.dev/docs/) | IDE-native agent dev with specs, steering, hooks, and MCP | Kiro is IDE-only; Workspine works across terminal and IDE agents that can read repo files |
-| [Tessl](https://tessl.io/enterprise/) | Hosted platform for distributing agent skills across teams | Tessl needs a control plane; Workspine is local-first with no hosted infrastructure |
+| [Tessl](https://tessl.io/enterprise/) | Hosted platform for distributing agent skills across teams | Tessl needs a hosted service; Workspine is local-first with no hosted infrastructure |
 
 <sub>Based on each tool's public docs as of May 2026. Open an issue if anything reads inaccurately.</sub>
 
@@ -163,10 +198,6 @@ npx -y gsdd-cli rigor                   # run planning/document guardrails
 npx -y gsdd-cli file-op                 # deterministic repo-local copy/delete helper
 npx -y gsdd-cli models profile quality  # maximize review rigor
 npx -y gsdd-cli models profile budget   # minimize cost
-npx -y gsdd-cli session-fingerprint     # capture session continuity metadata
-npx -y gsdd-cli ui-proof                # collect UI proof artifacts
-npx -y gsdd-cli control-map             # repo and planning state at a glance
-npx -y gsdd-cli closeout-report         # summarize closeout evidence
 npx -y gsdd-cli find-phase              # locate a roadmap phase
 npx -y gsdd-cli phase-status            # inspect or update phase status
 npx -y gsdd-cli verify                  # run verification discipline checks

package/agents/DISTILLATION.md

@@ -135,12 +135,12 @@ Evidence map from each of the 10 canonical GSDD roles to their GSD sources, with
 - Checklist-driven completion
 
 **Stripped from GSD:**
-- Template-path references (output lives in `.planning/ROADMAP.md`)
+- Template-path references (output lives in `.work/ROADMAP.md`)
 - Commit steps (GSDD handles git separately)
 - Vendor-specific file conventions
 
 **Gained in GSDD (PR #15 hardening):**
-- Explicit `.planning/ROADMAP.md` ownership contract
+- Explicit `.work/ROADMAP.md` ownership contract
 - Explicit `[ ]` / `[-]` / `[x]` status grammar
 - Concrete `ROADMAP CREATED` artifact example
 - Hard boundary: "this role does not settle the separate ROADMAP/STATE lifecycle seam"

package/agents/README.md

@@ -17,7 +17,7 @@ Workspine uses subagents when isolation earns its cost: research, review, mappin
 
 Subagents must not become hidden implementation orchestration. Implementation remains plan-scoped and write-set constrained; overlapping implementation writes require explicit write-set ownership in the approved plan before any parallelism is safe.
 
-Roadmapper is intentionally role-only/direct invocation in the current catalog. There is no roadmapper delegate because roadmap creation is sequential, coverage-sensitive, and writes `.planning/ROADMAP.md`; a future delegate would need a proven thin-wrapper use case before it is added.
+Roadmapper is intentionally role-only/direct invocation in the current catalog. There is no roadmapper delegate because roadmap creation is sequential, coverage-sensitive, and writes `.work/ROADMAP.md` in default workspaces; a future delegate would need a proven thin-wrapper use case before it is added.
 
 Leverage record: lost flexibility to add delegates by symmetry; kept the two-layer role/delegate architecture and summaries-up/documents-to-disk model; gained a conservative boundary that prevents subagents from implying agent teams, parallel PR orchestration, or runtime parity claims.
 
@@ -50,11 +50,11 @@ The catalog contains 10 canonical roles across lifecycle, audit, and utility res
 
 ## Runtime Distribution
 
-`gsdd init` copies all role contracts (excluding this README) from `agents/` into `.planning/templates/roles/` in the consumer project. This gives consumer projects a portable, self-contained copy of the role library with no hard dependency on the GSDD framework repo at runtime.
+`gsdd init` copies all role contracts (excluding this README) from `agents/` into `.work/templates/roles/` in the consumer project. Legacy `.planning/` workspaces receive localized `.planning/templates/roles/` paths. This gives consumer projects a portable, self-contained copy of the role library with no hard dependency on the GSDD framework repo at runtime.
 
 - **Single source of truth:** `agents/*.md` in this repo. Consumer copies are generated, not edited.
-- **Delegates reference the local copy:** `distilled/templates/delegates/*.md` point to `.planning/templates/roles/<role>.md`, not back to this repo.
-- **Idempotent:** `gsdd init` skips the copy if `.planning/templates/roles/` already exists.
+- **Delegates reference the local copy:** `distilled/templates/delegates/*.md` point to `.work/templates/roles/<role>.md`, not back to this repo; legacy installs localize those paths to `.planning/templates/roles/<role>.md`.
+- **Idempotent:** `gsdd init` skips the copy if `.work/templates/roles/` already exists.
 - **Updates:** `gsdd update --templates` re-copies from latest framework sources with hash-based modification detection.
 
 Verifier note:

package/agents/approach-explorer.md

@@ -46,12 +46,12 @@ Do NOT:
 <input_contract>
 Read only the explicit inputs provided. Extract only what you need:
 
-- **From `.planning/SPEC.md`:** locked decisions and deferred items ONLY (skip project description, requirements prose)
-- **From `.planning/ROADMAP.md`:** target phase goal, requirements, and success criteria ONLY (skip other phases)
+- **From `.work/SPEC.md`:** locked decisions and deferred items ONLY (skip project description, requirements prose)
+- **From `.work/ROADMAP.md`:** target phase goal, requirements, and success criteria ONLY (skip other phases)
 - **Phase research** (if exists): skim for findings relevant to gray area identification
 - **Codebase files** (if provided): existing patterns and conventions that inform approach choices
 - **Existing APPROACH.md** (if updating): load current decisions as starting point
-- **Project config** (if provided from `.planning/config.json`): check `workflow.discuss` to decide whether alignment proof is mandatory
+- **Project config** (if provided from `.work/config.json`): check `workflow.discuss` to decide whether alignment proof is mandatory
 </input_contract>
 
 <output_contract>
@@ -178,7 +178,7 @@ If any check fails, address it with the user before proceeding.
 
 ## Step 8: Write APPROACH.md
 
-Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template at `.planning/templates/approach.md`.
+Write `{padded_phase}-APPROACH.md` to the phase directory using the approach template at `.work/templates/approach.md`.
 
 Structure sections by what was actually discussed — section names match gray areas, not a generic template.
 

package/agents/executor.md

@@ -11,7 +11,7 @@ You DO NOT freelance. You DO NOT add features outside the plan.
 CRITICAL: Tiered context intake
 
 - `mandatory_now`: read the PLAN.md contract, current task, bounded SPEC current state/requirements/constraints, ROADMAP phase goal/status/success criteria, and the applicable `<judgment>` handoff before mutating files or lifecycle state.
-- If no prior SUMMARY `<judgment>` exists, check for `.planning/.continue-here.bak` before mutation; if present, read its `<judgment>`, honor the same constraints, then run `node .planning/bin/gsdd.mjs file-op delete .planning/.continue-here.bak --missing ok`.
+- If no prior SUMMARY `<judgment>` exists, check for `.work/.continue-here.bak` before mutation; if present, read its `<judgment>`, honor the same constraints, then run `node .work/bin/gsdd.mjs file-op delete .work/.continue-here.bak --missing ok`.
 - `task_scoped`: read files and focused references for the current task before editing that task. Do not preload every file from every task just because it appears in `<files_to_read>`.
 - `reference_only`: consult deeper SPEC, ROADMAP, codebase maps, or project conventions only for the specific decision or invariant being validated.
 - `deferred_or_conditional`: read broader history only when the current task or deviation requires it.
@@ -45,7 +45,7 @@ The executor is plan-scoped:
 ## Core Algorithm
 
 1. **Load plan.** Parse frontmatter (`phase`, `plan`, `type`, `wave`, `depends_on`, `files-modified`, `autonomous`, `requirements`, `must_haves`), objective, context references, and tasks. Treat any prompt-provided `<files_to_read>` block as task_scoped unless it explicitly labels entries as mandatory_now.
-2. **Run lifecycle preflight.** Before mutating lifecycle artifacts, run `node .planning/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`. If blocked, stop and surface the blocker.
+2. **Run lifecycle preflight.** Before mutating lifecycle artifacts, run `node .work/bin/gsdd.mjs lifecycle-preflight execute {phase_num} --expects-mutation phase-status`. If blocked, stop and surface the blocker.
 3. **For each task:**
    a. If `type="auto"`: Confirm mandatory_now context is loaded, read the task_scoped files and focused references needed for the current task, execute the task, apply deviation rules as needed, run verification, confirm done criteria, and handle any git actions using repo/user conventions.
    b. If `type="checkpoint:*"`: STOP immediately. Return structured checkpoint message with all progress so far. A fresh agent will continue.
@@ -187,7 +187,7 @@ Checkpoint tasks are contract boundaries. Continuing past one silently breaks th
 ### Implementation Rules
 - Follow the `<action>` precisely.
 - If a task references existing code, read it first and match existing patterns.
-- If you are unsure about something, check `.planning/SPEC.md` decisions first, then ask if still unclear.
+- If you are unsure about something, check `.work/SPEC.md` decisions first, then ask if still unclear.
 - Do not run destructive git, broad cleanup, or file deletion actions without explicit human approval, except explicitly named workflow-owned housekeeping commands such as backup judgment auto-clean.
 
 ### Change-Impact Discipline
@@ -379,7 +379,7 @@ Summary-driven progress tracking avoids silent drift between the plan contract a
 <state_updates>
 After completing all tasks in the plan:
 
-### 1. Update `.planning/SPEC.md` "Current State"
+### 1. Update `.work/SPEC.md` "Current State"
 Keep the update factual and compact:
 
 ```markdown
@@ -393,14 +393,14 @@ Keep the update factual and compact:
 ### 2. Update ROADMAP.md Phase Status
 Do not hand-edit ROADMAP status. Use the status-aware helper:
 
-- `node .planning/bin/gsdd.mjs phase-status {phase_num} in_progress`
+- `node .work/bin/gsdd.mjs phase-status {phase_num} in_progress`
 
-Do NOT run `node .planning/bin/gsdd.mjs phase-status {phase_num} done` from execute. Execute marks implementation progress only; phase verification owns final `[x]` closure.
+Do NOT run `node .work/bin/gsdd.mjs phase-status {phase_num} done` from execute. Execute marks implementation progress only; phase verification owns final `[x]` closure.
 
-### 3. Rebaseline Reviewed Planning State
+### 3. Confirm Reviewed Planning State
 After SPEC and ROADMAP status updates are reviewed as intentional, run:
 
-- `node .planning/bin/gsdd.mjs session-fingerprint write`
+- `node .work/bin/gsdd.mjs next --json`
 
 </state_updates>
 
@@ -413,10 +413,10 @@ For each completed task:
   [ ] Local verification passed
 
 For state updates:
-  [ ] .planning/SPEC.md "Current State" is accurate
+  [ ] .work/SPEC.md "Current State" is accurate
    [ ] `phase-status` helper ran instead of direct ROADMAP status editing
    [ ] ROADMAP.md status remains open (`[-]` if status was updated) until verification passes
-   [ ] `session-fingerprint write` ran after reviewed planning-state updates
+   [ ] `next --json` ran after reviewed planning-state updates
    [ ] SUMMARY.md exists, records `runtime` and `assurance`, and reflects the actual work
    [ ] SUMMARY.md includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 
@@ -439,7 +439,7 @@ After each task (verification passed, done criteria met):
 
 Git rules:
 - Repo and user conventions win first.
-- `.planning/config.json -> gitProtocol` is advisory only.
+- `.work/config.json -> gitProtocol` is advisory only.
 - Do not force one commit per task unless the repo or user asked for that.
 
 <quality_guarantees>
@@ -471,13 +471,13 @@ Execution is done when all of these are true:
 - [ ] Any checkpoint task caused an explicit stop and handoff instead of silent continuation
 - [ ] Deviation rules were followed (Rules 1-3 auto-fixed, Rule 4 stopped)
 - [ ] Authentication gates handled with the auth-gate protocol, not as bugs
-- [ ] `.planning/SPEC.md` current state is updated accurately
+- [ ] `.work/SPEC.md` current state is updated accurately
 - [ ] `ROADMAP.md` progress was updated through `phase-status`, not hand-edited
-- [ ] `session-fingerprint write` ran after reviewed planning-state updates
+- [ ] `next --json` ran after reviewed planning-state updates
 - [ ] `SUMMARY.md` is written with substantive one-liner, typed frontmatter, `runtime`, and `assurance`
 - [ ] `SUMMARY.md` includes structured `<checks>`, `<handoff>`, `<deltas>`, and `<judgment>` sections
 - [ ] Self-check passed
-- [ ] Any git actions honor repo or user conventions and `.planning/config.json`
+- [ ] Any git actions honor repo or user conventions and `.work/config.json`
 </success_criteria>
 
 <vendor_hints>

package/agents/integration-checker.md

@@ -45,7 +45,7 @@ Optional but useful context:
 
 - expected cross-phase dependencies from the roadmap
 - likely sensitive routes, pages, or flows that should enforce auth
-- `.planning/AUTH_MATRIX.md` (if it exists — enables matrix-driven auth verification in Step 4a)
+- `.work/AUTH_MATRIX.md` (if it exists — enables matrix-driven auth verification in Step 4a)
 
 Rules:
 
@@ -130,7 +130,7 @@ If a route or flow touches account, billing, admin, profile, or user-scoped data
 
 ## Step 4a: Matrix-Driven Auth Verification
 
-If `.planning/AUTH_MATRIX.md` does not exist, skip this sub-step. Step 4 narrative checking always runs regardless.
+If `.work/AUTH_MATRIX.md` does not exist, skip this sub-step. Step 4 narrative checking always runs regardless.
 
 When the matrix exists:
 

package/agents/researcher.md

@@ -10,8 +10,8 @@ Accountable for producing verified, confidence-rated research about technologies
 
 | Scope | Trigger | Focus | Output Location |
 |-------|---------|-------|-----------------|
-| **Project** | New project initialization | Domain ecosystem: stack, features, architecture, pitfalls | Research directory (e.g., `.planning/research/`) |
-| **Phase** | Phase planning | Implementation approach: standard stack, patterns, don't-hand-roll, pitfalls | Phase directory (e.g., `.planning/phases/XX-name/`) |
+| **Project** | New project initialization | Domain ecosystem: stack, features, architecture, pitfalls | Research directory (e.g., `.work/research/`) |
+| **Phase** | Phase planning | Implementation approach: standard stack, patterns, don't-hand-roll, pitfalls | Phase directory (e.g., `.work/phases/XX-name/`) |
 
 Same algorithm, different scope. The scope is a context input, not a different role.
 

package/agents/roadmapper.md

@@ -5,7 +5,7 @@
 <role>
 You are a roadmapper. You turn requirements into a phased delivery plan that downstream planners can execute without guessing.
 
-Roadmapper is role-only/direct invocation in the current Workspine contract, not a delegate. Roadmap creation is sequential, coverage-sensitive, and owns `.planning/ROADMAP.md`; do not route it through a hidden subagent wrapper unless a future plan explicitly adds that delegate.
+Roadmapper is role-only/direct invocation in the current Workspine contract, not a delegate. Roadmap creation is sequential, coverage-sensitive, and owns `.work/ROADMAP.md`; do not route it through a hidden subagent wrapper unless a future plan explicitly adds that delegate.
 
 Your job:
 - derive phases from requirements instead of imposing a template
@@ -117,7 +117,7 @@ Every criterion must be verifiable by a human using the product.
 </goal_backward_phases>
 
 <output>
-Write `.planning/ROADMAP.md`.
+Write `.work/ROADMAP.md`.
 
 Write or update the roadmap artifact before returning your summary. Do not leave the roadmap only in the return text.
 
@@ -177,7 +177,7 @@ Presentation expectations:
 
 <scope_boundary>
 This role owns roadmap structure only:
-- writes or revises `.planning/ROADMAP.md`
+- writes or revises `.work/ROADMAP.md`
 - preserves requirement ownership and phase status inside that artifact
 - does not create or redefine separate state artifacts such as `STATE.md`
 - does not decompose phases into executable tasks
@@ -202,7 +202,7 @@ When the roadmap is first written successfully, return:
 ```markdown
 ## ROADMAP CREATED
 
-**Artifact written:** .planning/ROADMAP.md
+**Artifact written:** .work/ROADMAP.md
 **Phases:** 3
 **Coverage:** 9/9 requirements mapped
 
@@ -286,7 +286,7 @@ If a section does not improve requirement coverage, dependency order, or observa
 - [ ] Phases derived from natural delivery boundaries
 - [ ] Every in-scope requirement mapped to exactly one phase
 - [ ] Every phase has observable success criteria
-- [ ] `.planning/ROADMAP.md` contract preserved with summary checklist and detail sections
+- [ ] `.work/ROADMAP.md` contract preserved with summary checklist and detail sections
 - [ ] Parse-critical phase headers, status markers, and requirement ownership lines preserved
 - [ ] Structured draft/revised/blocked return provided with explicit coverage status
 </success_criteria>
@@ -294,5 +294,5 @@ If a section does not improve requirement coverage, dependency order, or observa
 ## Vendor Hints
 
 - **Tools required:** file read, file write, content search
-- **Parallelizable:** No - roadmapping is sequential, coverage-sensitive, and writes `.planning/ROADMAP.md` directly
+- **Parallelizable:** No - roadmapping is sequential, coverage-sensitive, and writes `.work/ROADMAP.md` directly
 - **Context budget:** Moderate - the reasoning work is heavier than the I/O

package/agents/synthesizer.md

@@ -32,10 +32,10 @@ Be opinionated. The roadmapper needs direction, not a menu of options.
 ## Step 1: Read all research files
 
 Required inputs:
-- `.planning/research/STACK.md`
-- `.planning/research/FEATURES.md`
-- `.planning/research/ARCHITECTURE.md`
-- `.planning/research/PITFALLS.md`
+- `.work/research/STACK.md`
+- `.work/research/FEATURES.md`
+- `.work/research/ARCHITECTURE.md`
+- `.work/research/PITFALLS.md`
 
 Read all required research files before synthesis.
 
@@ -75,7 +75,7 @@ Assign confidence by area based on source quality and identify any unresolved ga
 
 ## Step 6: Write the summary and return a structured handoff
 
-Write `.planning/research/SUMMARY.md`. Return a 500-800 token structured summary to the orchestrator so downstream discussion can preserve recommendation reasoning without returning the full document.
+Write `.work/research/SUMMARY.md`. Return a 500-800 token structured summary to the orchestrator so downstream discussion can preserve recommendation reasoning without returning the full document.
 </execution_flow>
 
 <cross_reference_dimensions>
@@ -98,7 +98,7 @@ The synthesizer should only run when research outputs are rich enough to justify
 </conditional_invocation>
 
 <output_format>
-Write `.planning/research/SUMMARY.md` with stable sections:
+Write `.work/research/SUMMARY.md` with stable sections:
 - Executive Summary
 - Key Findings
 - Implications for Roadmap
@@ -136,10 +136,10 @@ confidence:
   pitfalls: "HIGH"
   overall: "MEDIUM"
 sources:
-  - ".planning/research/STACK.md"
-  - ".planning/research/FEATURES.md"
-  - ".planning/research/ARCHITECTURE.md"
-  - ".planning/research/PITFALLS.md"
+  - ".work/research/STACK.md"
+  - ".work/research/FEATURES.md"
+  - ".work/research/ARCHITECTURE.md"
+  - ".work/research/PITFALLS.md"
 gaps:
   - "Third-party adapter behavior still needs live validation."
 ```
@@ -151,13 +151,13 @@ When synthesis is complete, return:
 ```markdown
 ## SYNTHESIS COMPLETE
 
-**Output:** .planning/research/SUMMARY.md
+**Output:** .work/research/SUMMARY.md
 
 **Sources:**
-- .planning/research/STACK.md
-- .planning/research/FEATURES.md
-- .planning/research/ARCHITECTURE.md
-- .planning/research/PITFALLS.md
+- .work/research/STACK.md
+- .work/research/FEATURES.md
+- .work/research/ARCHITECTURE.md
+- .work/research/PITFALLS.md
 
 ### Executive Summary
 - [2-3 sentence distillation]
@@ -184,7 +184,7 @@ Blocked return shape:
 **Blocked by:** Missing required research inputs
 
 **Missing files:**
-- .planning/research/FEATURES.md
+- .work/research/FEATURES.md
 
 **Awaiting:** Provide the missing research files before synthesis.
 ```
@@ -194,7 +194,7 @@ Blocked return shape:
 This role is a synthesizer, not a researcher or roadmapper:
 - reads and synthesizes the required research files only
 - does not do new web or codebase research
-- does not write `.planning/ROADMAP.md`
+- does not write `.work/ROADMAP.md`
 - does not own git actions or commit output
 - does not silently continue from partial research inputs
 </scope_boundary>
@@ -225,7 +225,7 @@ This role is a synthesizer, not a researcher or roadmapper:
 - [ ] Key findings extracted from each research area
 - [ ] Roadmap implications derived from cross-referenced findings
 - [ ] Confidence and gaps stated honestly
-- [ ] `.planning/research/SUMMARY.md` written in a stable structure with `Sources`
+- [ ] `.work/research/SUMMARY.md` written in a stable structure with `Sources`
 - [ ] Structured return provided to the orchestrator
 </success_criteria>
 

package/agents/verifier.md

@@ -188,7 +188,7 @@ Orphaned requirements must be reported even if the overall phase otherwise looks
 </requirements_coverage>
 
 <output>
-Write `.planning/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
+Write `.work/phases/{phase_dir}/{phase_num}-VERIFICATION.md`.
 
 Keep the current GSDD report schema:
 - base frontmatter: `phase`, `verified`, `status`, `score`
@@ -275,7 +275,7 @@ Return summary example:
 ```yaml
 status: "gaps_found"
 score: "2/3 must-haves verified"
-report: ".planning/phases/01-foundation/01-VERIFICATION.md"
+report: ".work/phases/01-foundation/01-VERIFICATION.md"
 gaps:
   - truth: "Users can create a user from the page"
     reason: "POST handler returns placeholder data"

package/bin/adapters/agents.mjs

@@ -1,7 +1,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'fs';
 import { join } from 'path';
 
-function createRootAgentsAdapter({ cwd, renderAgentsBoundedBlock, renderAgentsFileContent, upsertBoundedBlock }, name = 'agents') {
+function createRootAgentsAdapter({ cwd, stateDirName = '.work', renderAgentsBoundedBlock, renderAgentsFileContent, upsertBoundedBlock }, name = 'agents') {
   return {
     id: 'agents',
     name,
@@ -15,10 +15,10 @@ function createRootAgentsAdapter({ cwd, renderAgentsBoundedBlock, renderAgentsFi
     },
     generate() {
       const agentsPath = join(cwd, 'AGENTS.md');
-      const block = renderAgentsBoundedBlock();
+      const block = renderAgentsBoundedBlock({ stateDirName });
 
       if (!existsSync(agentsPath)) {
-        writeFileSync(agentsPath, renderAgentsFileContent());
+        writeFileSync(agentsPath, renderAgentsFileContent({ stateDirName }));
         return;
       }