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.

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:

npm install --global @jakyeamos33/terrace

Quickstart

Run Terrace from the root of an existing repository:

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:

terrace new-project hoopscout --prd docs/input/HOOPSCOUT-PRD.md

Start a new project from pasted PRD content:

terrace new-project hoopscout --paste-prd <<'PRD'
# Hoopscout PRD

- Coaches need a faster way to evaluate prospects.
PRD

Import a later feature PRD:

terrace prd import saved-search --file docs/input/SAVED-SEARCH-PRD.md

Release Readiness

Use these checks before publishing protected work:

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 <name> --prd <file> or --paste-prd initializes Terrace from a source PRD and writes project artifacts.
• terrace prd import <feature> --file <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 <path> 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 <plain text> 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 <feature> writes docs/terrace/features/<feature>/ALIGNMENT.md with customer, problem, success metrics, risks, rollout, observability, validation, and cleanup intent.
• terrace interrogate <feature> 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 <feature> records architecture decisions, tradeoffs, maintainability, and the no band-aid rule.
• terrace test-plan <feature> writes the behavior-first docs/testing/TEST-PLAN.md required before implementation.
• terrace observe <feature> writes feature observability and post-launch debugging intent.
• terrace validate-prod <feature> writes production success signals, monitoring, and rollback conditions.
• terrace cleanup <feature> writes the cleanup contract for flags, temporary code, and docs.
• terrace ui import-stitch <feature>, terrace ui plan-refresh <feature>, and terrace ui diff <feature> support design-driven greenfield and brownfield UI workflows.
• terrace phase list lists canonical roadmap phases.
• terrace phase show <id> shows one roadmap phase and its migrated plans.
• terrace phase plan <id> writes docs/terrace/phases/<id>/PLAN.md, pulling migrated source plans, likely files, related quick tasks, blockers, and discovered project commands into the phase plan.
• terrace phase execute <id> writes docs/terrace/phases/<id>/EXECUTION.md, enters RED-gate readiness after blockers are clear, and reports an execution queue.
• terrace phase validate <id> writes docs/terrace/phases/<id>/VALIDATION.md.
• terrace phase review <id> writes docs/terrace/phases/<id>/REVIEW.md.
• terrace phase complete <id> writes docs/terrace/phases/<id>/SUMMARY.md and marks the phase complete.
• terrace quick list lists migrated GSD quick-task history.
• terrace quick show <id> shows one migrated quick task.
• terrace quick plan <title> 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:

npm run ci

The publish allowlist is controlled by package.json#files; local planning, tests, and agent settings are not shipped.