# Terrace Terrace is a strict-core workflow CLI for spec-driven, test-governed AI-assisted development. It keeps implementation work tied to a recoverable repo state, explicit spec intent, protected tests, and deterministic quality gates. ## Install Terrace requires Node.js 22 or newer. ```sh npm install --save-dev @jakyeamos33/terrace ``` Run it with `npx @jakyeamos33/terrace` or through the installed `terrace` binary. If you want `terrace` available globally (no `npx`), install it globally: ```sh npm install --global @jakyeamos33/terrace ``` ## Quickstart Run Terrace from the root of an existing repository: ```sh npx @jakyeamos33/terrace init npx @jakyeamos33/terrace doctor npx @jakyeamos33/terrace audit npx @jakyeamos33/terrace report npx @jakyeamos33/terrace ship check --json ``` `terrace doctor` confirms the local installation is usable. `terrace audit` checks Terrace-owned governance state. `terrace report` prints the current Tier One readiness card without writing files. `terrace ship check --json` runs release-readiness checks and exits nonzero when a blocking gate fails. ## What Terrace Creates `terrace init` writes only repo-local governance state and docs scaffolding: - `.terrace/state.json` - `.terrace/config.json` - `.terrace/presets/registry.json` - `.terrace/rules/*.json` - `.terrace/events.jsonl` - `docs/prd/` - `docs/spec/` - `docs/testing/` Report artifacts are explicit: `terrace report` is read-only, while `terrace report update` writes `.terrace/report-card.json`, `docs/terrace/REPORT-CARD.md`, and report history. ## PRD Intake Start a new project from a PRD file: ```sh terrace new-project hoopscout --prd docs/input/HOOPSCOUT-PRD.md ``` Start a new project from pasted PRD content: ```sh terrace new-project hoopscout --paste-prd <<'PRD' # Hoopscout PRD - Coaches need a faster way to evaluate prospects. PRD ``` Import a later feature PRD: ```sh terrace prd import saved-search --file docs/input/SAVED-SEARCH-PRD.md ``` ## Release Readiness Use these checks before publishing protected work: ```sh npm run ci npm audit --audit-level=moderate npm run package:dry-run npx @jakyeamos33/terrace ship check --json ``` `terrace ship check` is read-only. Use `terrace ship prepare` when you want Terrace to write a release-readiness summary under `docs/terrace/ship/`. ## Command Reference - `terrace --help` shows the top-level command list. - `terrace --version` prints the package version. - `terrace init` initializes Terrace state. - `terrace new-project --prd ` or `--paste-prd` initializes Terrace from a source PRD and writes project artifacts. - `terrace prd import --file ` or `--paste` imports a feature PRD into an existing Terrace project. - `terrace doctor` checks installation health. - `terrace spec validate` validates governance artifacts. - `terrace spec hash --file ` computes a stable spec hash. - `terrace audit` checks artifacts and protected baselines. - `terrace ci check [files...]` runs audit and protected-change enforcement. - `terrace port gsd --dry-run` inventories legacy GSD artifacts. - `terrace port gsd` migrates supported legacy GSD artifacts into Terrace state. - `terrace next` reports the next workflow action from state, handoff data, and blockers. - `terrace resume` reconstructs paused workflow context from sessions and migrated handoff data. - `terrace history` summarizes migrated phases, sessions, decisions, and quick tasks. - `terrace do ` routes natural-language agent instructions to stable Terrace commands. - `terrace autonomous` plans the next phase, prepares execution readiness, and stops at blockers or agent handoff. - `terrace commands discover` detects package manager, project scripts, and quality-gate command mapping. - `terrace align ` writes `docs/terrace/features//ALIGNMENT.md` with customer, problem, success metrics, risks, rollout, observability, validation, and cleanup intent. - `terrace interrogate ` writes edge-case, assumption-challenge, and failure-mode interrogation. - `terrace map-codebase` writes codebase map, architecture, risks, testing, and observability context under `docs/terrace/codebase/`. - `terrace design ` records architecture decisions, tradeoffs, maintainability, and the no band-aid rule. - `terrace test-plan ` writes the behavior-first `docs/testing/TEST-PLAN.md` required before implementation. - `terrace observe ` writes feature observability and post-launch debugging intent. - `terrace validate-prod ` writes production success signals, monitoring, and rollback conditions. - `terrace cleanup ` writes the cleanup contract for flags, temporary code, and docs. - `terrace ui import-stitch `, `terrace ui plan-refresh `, and `terrace ui diff ` support design-driven greenfield and brownfield UI workflows. - `terrace phase list` lists canonical roadmap phases. - `terrace phase show ` shows one roadmap phase and its migrated plans. - `terrace phase plan ` writes `docs/terrace/phases//PLAN.md`, pulling migrated source plans, likely files, related quick tasks, blockers, and discovered project commands into the phase plan. - `terrace phase execute ` writes `docs/terrace/phases//EXECUTION.md`, enters RED-gate readiness after blockers are clear, and reports an execution queue. - `terrace phase validate ` writes `docs/terrace/phases//VALIDATION.md`. - `terrace phase review ` writes `docs/terrace/phases//REVIEW.md`. - `terrace phase complete ` writes `docs/terrace/phases//SUMMARY.md` and marks the phase complete. - `terrace quick list` lists migrated GSD quick-task history. - `terrace quick show ` shows one migrated quick task. - `terrace quick plan ` creates a stateful quick-task plan under `docs/terrace/quick/<id>/`. - `terrace quick execute <id>` enters RED-gate execution for a quick task after a behavior-first test plan exists. - `terrace quick complete <id>` writes a quick-task summary and marks it complete after verification evidence exists. - `terrace backlog list` lists backlog items. - `terrace backlog add <title>` appends a backlog item. - `terrace ship check` runs release-readiness checks, discovers available project scripts, enforces active Senior Cycle ship gates, treats missing optional scripts as warnings, and exits nonzero when an available quality gate fails. - `terrace ship prepare` writes `docs/terrace/ship/SHIP.md` from release-readiness results. - `terrace plan-phase <id>`, `terrace execute-phase <id>`, `terrace validate-phase <id>`, `terrace review-phase <id>`, and `terrace complete-phase <id>` are GSD-compatible aliases. - `terrace rule list` and `terrace rule explain <id>` inspect rule packs. - `terrace preset list` and `terrace preset install <id>` manage presets. ## GSD Migration `terrace port gsd` preserves the source `.planning/` tree and writes converted Terrace artifacts under `.terrace/`, `docs/prd/`, `docs/spec/`, `docs/terrace-migration/`, and `docs/testing/gsd/`. The migration report is written to `.terrace/migration/gsd-port-report.json` and includes `converted`, `skipped`, `writes`, `blockers`, `warnings`, `readiness`, `next_command`, `review_checklist`, and `validation_commands`. Migrated state includes roadmap phases and plans, decisions, sessions, handoff context, backlog items, blocked human actions, and quick-task history. Quick-task PLAN/SUMMARY files are archived under `docs/terrace-migration/quick/` and exposed through `terrace quick list` / `terrace quick show <id>`. Handoff remaining tasks and blocking human actions become backlog items so post-migration work is visible. Unsupported files are not deleted; each skipped artifact includes a reason and manual review action. ## Workflow Example 1. Capture intent in `docs/prd/PRD.md`. 2. Compile spec details in `docs/spec/COMPILED-SPEC.md`. 3. Design test trust in `docs/testing/TEST-ARCH.md`. 4. Use Terrace gates to require RED evidence before implementation and GREEN evidence before protection. 5. Run `terrace phase plan <id>`, `terrace phase execute <id>`, `terrace phase validate <id>`, `terrace phase review <id>`, and `terrace phase complete <id>` to preserve execution history. 6. Run `terrace audit`, `terrace ci check`, and `terrace ship prepare` before committing protected changes. Agents can use `terrace do "plan phase 11"`, `terrace do "/gsd:plan-phase 11"`, `terrace do "run the next phase"`, `terrace do "create quick task fix login redirect"`, or `terrace do "ship prepare"` when they have plain text instead of a structured command. ## Senior Cycle Terrace now has a senior-cycle artifact layer for adaptive rigor: - Small changes: alignment-lite, test-first, execute, verify. - Medium features: alignment, edge cases, test strategy, execute, ship check. - Large/risky features: full alignment, interrogation, codebase mapping, design, TDD, observability, rollout, production validation, and cleanup. See `docs/terrace/SENIOR-CYCLE.md` for the audit report, target workflow, artifact structure, enforcement rules, and implementation milestones. The no band-aid rule is the default: even `terrace quick` should choose maintainable architecture unless a short-term choice explicitly preserves future development and has a cleanup contract. ## Troubleshooting - `Missing .terrace/state.json`: run `terrace init` from the repo root. - `Protected file changed without DECISION-LOG.md`: add a spec-linked decision before committing. - `terrace port gsd` refuses to overwrite state: re-run with `--force` only after preserving existing `.terrace/state.json`. - `terrace next` reports a blocked action after migration: complete or clear the migrated human action before treating the project as ready. - `terrace ship check` exits nonzero: inspect the failed category and run the listed command directly for detailed output. - `terrace ship check` reports `QUALITY_SCRIPT_MISSING`: add the suggested package script if that gate should be enforced for this project. - `terrace do <plain text>` cannot route an instruction: use an explicit command from `terrace --help` or include a clear phase number, quick-task request, resume/next/history request, or ship request. - Typecheck errors from package dependencies usually mean the repo is not using the supported `Bundler` module resolution settings in `tsconfig.json`. ## Development Canonical local verification is: ```sh npm run ci ``` The publish allowlist is controlled by `package.json#files`; local planning, tests, and agent settings are not shipped.