e437ded6fc
* docs(3524): propose CJS↔SDK hard-seam ADR + phased PRD Adds docs/adr/3524-cjs-sdk-hard-seam.md (Proposed) and docs/prd/3524-cjs-sdk-hard-seam.md (Reference) tracking #3524. Updates the ADR and PRD index READMEs. The ADR defines one canonical owner per responsibility across the CJS (bin/lib/*.cjs) and SDK (sdk/src/**/*.ts) sides, eliminating the recurring drift bug class (#1535, #1542, #2047, #2638, #2653, #2687, #2798, #3055, #3523). Three layers: shared data (sdk/shared/*.json), shared core logic (sdk/src/core/ → dual CJS+ESM build), thin adapters. Enforcement is layered: build-time grep, type-level contract test, mutation parity test, CODEOWNERS gate, in-file banner. The PRD phases the migration in five independently shippable steps — shared data first (closes constant drift), then config consolidation (closes #3523 class), then project-root + path projection, then state and verify handlers, then enforcement hardening + retrospective. * docs(3524): revise seam ADR + PRD after architecture review Architecture-review pass (via /improve-codebase-architecture) found seven deepening opportunities; this commit applies all of them. 1. Re-anchor on the existing generator precedent. The repo already has sdk/scripts/gen-command-aliases.ts emitting both .generated.ts and .generated.cjs from one TS source, with sdk/scripts/check-command-aliases-fresh.mjs as the CI freshness gate. The ADR's invented dual CJS+ESM bundler pipeline is dropped. Each Shared Module gets one generator script and one freshness check, modeled on that precedent. 2. Drop the generic sdk/src/core/ container. The canonical-owner table is now indexed by Module, using the CONTEXT.md domain vocabulary (STATE.md Document Module, Configuration Module, etc.) rather than file-path-based pseudo-modules. 3. Split the coarse "State management" row into three: the pure STATE.md Document Module (already a character-identical hand-synced pair — perfect Phase 1 target), the Planning Workspace Module (defer to ADR-0004), and per-side state I/O Adapters (legitimately differ sync vs async). 4. Defer to existing ADRs. Planning Path Projection (ADR-0006), Model Catalog (ADR-0003), Planning Workspace (ADR-0004), Dispatch Policy (ADR-0001), Shell Command Projection (ADR-0009 post-Phase 3-4 expansion which absorbed superseded ADR-0010). The stale ADR-0010 reference is fixed. 5. Define a Configuration Module entry in CONTEXT.md as a Phase 2 deliverable, with explicit Interface contract for loadConfig, normalizeLegacyKeys, mergeDefaults, migrateOnDisk. 6. Split the Workstream Inventory Module into a pure Builder (generated, shared) and per-side Reader Adapters (hand-authored, sync vs async). Same pattern generalizes to other paired Modules. 7. Match enforcement to existing scripts. Per-Module freshness checks (precedent: check-command-aliases-fresh.mjs), per-Module drift lints (precedent: lint-shell-command-projection-drift.cjs), and one hand-sync pair lint that blocks the #3523 anti-pattern at PR time. PRD phases reordered: STATE.md Document Module ships first as a proof of pattern (two identical files become one source plus one generated artifact). Configuration Module ships second, closing the #3523 class. Workstream Inventory Builder split third. Project-Root Resolution fourth. Enforcement and retrospective fifth. * docs(3524): expand scope — CJS router delegates to SDK runtime bridge User flagged that the original "Out of scope" list was my unilateral scoping call, not theirs. After review, the CJS router consolidation (formerly out-of-scope item #1) is brought into scope. ADR additions: - CJS Command Router Adapter Module row added to canonical-owner table. Existing Module (per CONTEXT.md) is amended so the per-family `handlers` map delegates to `QueryRuntimeBridge.execute()` in-process. Per-side CJS handler files for canonical families (state.cjs, verify.cjs, init.cjs, phase.cjs, etc.) shrink to delegates or are deleted. - Per-side I/O Adapter consequence updated to clarify the bridge preserves the in-process model. No subprocess hop is added. - "Out of scope" stripped of router item; CJS-only seam migration and verify-Module-first work remain out of scope. PRD additions: - New Phase 5: CJS Command Router Adapter delegates to SDK runtime bridge, family-by-family, with golden parity matrix per family gating each PR. - Old Phase 5 (enforcement) renumbered to Phase 6, expanded to cover Phase 5's parity matrix and runtime-bridge CODEOWNERS. - Open question #4 added for the synchronous-bridging mechanism (`deasync` vs `Atomics.wait` vs sync-handler refactor) — resolved in the Phase 5 spike before any family migration begins. - Open question #5 added for family migration order (recommended: smallest read-only family first). - Risks table expanded with three Phase 5 rows: bridging-mechanism uncertainty, observable-output regression, startup-time impact. - Done-when updated for six phases and five enforcement layers. Non-goals updated: CJS-only Module migration and verify-Module deepening remain out of scope. CJS CLI removal explicitly stays off the table — the external `gsd-tools` contract is preserved. * docs(3524): address CodeRabbit review * docs(3524): fix PRD issue reference markdown
GSD Documentation
Comprehensive documentation for the Get Shit Done (GSD) framework — a meta-prompting, context engineering, and spec-driven development system for AI coding agents.
Language versions: English · Português (pt-BR) · 日本語 · 简体中文
Documentation Index
| Document | Audience | Description |
|---|---|---|
| Architecture | Contributors, advanced users | System architecture, agent model, data flow, and internal design |
| Installer Migrations | Contributors | Architecture for safe install-time migrations, cleanup, preservation, dry-run planning, and rollback |
| Feature Reference | All users | Feature narratives and requirements for released features (see CHANGELOG for latest additions) |
| v1.42.1 Release Notes | All users | Stable release notes for the 1.42.1 release |
| Command Reference | All users | Stable commands with syntax, flags, options, and examples |
| Configuration Reference | All users | Full config schema, workflow toggles, model profiles, git branching |
| Custom PR Body Sections | All users | How to append project-specific PRD sections to /gsd-ship PR bodies |
| CLI Tools Reference | Contributors, agent authors | gsd-tools.cjs programmatic API for workflows and agents |
| JSON Error Mode | Contributors, agent authors | Machine-readable gsd-tools --json-errors failure envelopes |
| Agent Reference | Contributors, advanced users | Role cards for primary agents — roles, tools, spawn patterns (the agents/ filesystem is authoritative) |
| User Guide | All users | Workflow walkthroughs, troubleshooting, and recovery |
| Issue-Driven Orchestration | All users | Recipe for driving GSD from a tracker issue (GitHub / Linear / Jira) using existing primitives — no new commands or daemon |
| Context Monitor | All users | Context window monitoring hook architecture |
| Discuss Mode | All users | Assumptions vs interview mode for discuss-phase |
| Canary Stream | Contributors, early adopters | dev → @canary dist-tag policy, when to install, rollback path |
Quick Links
- What's new: see v1.42.1 Release Notes, CHANGELOG, and upstream README for release highlights
- Canary preview:
docs/CANARY.md— opt into the early-preview stream fromdev. Active cut:v1.50.0-canary.1 - Getting started: README → install →
/gsd-new-project - Full workflow walkthrough: User Guide
- All commands at a glance: Command Reference
- Configuring GSD: Configuration Reference
- Customizing ship PR bodies: Custom PR Body Sections
- How the system works internally: Architecture
- Contributing or extending: CLI Tools Reference + Agent Reference