Quick Start

Product model

Spec-To-Ship (s2s) is a CLI SDLC orchestrator. You initialize a project once with s2s init, then work from your chat app (claude-cli or codex-cli). S2S classifies your intent, plans the minimum stage route, and keeps execution governed through operational state, worktree isolation, and runtime contracts.

First run

cd /path/to/app
s2s init

Daily workflow

1. Start/resume chat in a configured project:

   • s2s

2. Or launch explicit chat app + app path:

   • s2s claude-cli (current path)
   • s2s codex-cli /path/to/app

3. Check installed CLI version when needed:

   • s2s help
   • s2s version
   • s2s --version
   • s2s -v

4. Submit freeform intent to the orchestrator:

   • s2s request "build a release dashboard with approval gates"
   • s2s request "fix the timeout issue in the auth flow"
   • The orchestrator classifies intent, plans the minimum route, and creates or reuses a Change and Spec.

5. Inspect workflow and entity state when needed:

   • s2s status
   • s2s show change
   • s2s show slices
   • s2s show runs
   • s2s config
   • s2s doctor

6. Resolve approval gates:

   • s2s approve
   • s2s reject

7. Create/restore safety snapshots when needed:

   • s2s backup
   • s2s restore --latest
   • s2s restore --snapshot=<snapshot-id>

8. Run stages using the two-phase pattern (chat-native mode):

   Phase 1 — get the task:

   • s2s stage pm
   • s2s stage research
   • s2s stage design
   • s2s stage engineering

   This outputs a structured task package: objective, context, artifact specification, and exact file paths to write. S2S updates .s2s/live.md with status: context_delivered and the next action.

   Phase 2 — generate and submit:

   • Generate the artifact(s) described in the task package.
   • Write each artifact to the path specified.
   • Run s2s stage <stage> --submit to record completion and advance the workflow.

   After --submit, follow the next-action instruction in the output:

   • Quality passes, no gate: proceed to the next stage.
   • Quality fails: fix the listed issues and re-submit.
   • Review gate created: wait for s2s approve <gateId> or s2s reject <gateId>.

   Other stage options:

   • s2s stage <stage> --refine "add dark mode to the existing feature" — refine with a specific intent
   • s2s stage <stage> --refine — refine the active change (generic fallback)
   • s2s stage engineering_exec — runs the existing agent pipeline in an isolated worktree (standalone mode or explicit invocation)

Session observability

At chat launch, s2s prints a Session Banner with:

• S2S status
• project alias and path
• selected client

Runtime toggles live in .s2s/config/runtime.json under chatObservability:

• sessionBannerEnabled
• wrapperPrefixEnabled
• wrapperPrefixTemplate

Use s2s config edit to update these values interactively. Wrapper prefix is available only for CLI-launched sessions (codex-cli / claude-cli), not desktop app sessions.

Guardrail conflict policy also lives in .s2s/config/runtime.json:

• guardrailPolicy=strict: discrepancy blocks s2s stage and fails s2s doctor.
• guardrailPolicy=warn: discrepancy is reported as warning.
• guardrailPolicy=prompt: init/config asks you to choose strict, warn, or abort.

Desktop workflow

1. In guided init (s2s init), select launch client by number:
   • codex-cli
   • claude-cli
   • codex-desktop
   • claude-desktop
2. If desktop client is selected, open the same app root in desktop workspace and start chat there.
3. If you later run s2s in terminal while desktop mode is active:
   • s2s shows desktop guidance
   • s2s offers switching to equivalent CLI app
   • if you keep desktop mode, no CLI launch happens
4. Change preference anytime with:
   • s2s config edit

Project resolution rules

Project commands accept optional final [project]:

• s2s config my-project
• s2s config edit my-project
• s2s stage engineering my-project
• s2s status my-project

Resolution behavior:

1. If .s2s exists in current path or ancestors, local context is used.
2. If local context is not available, [project] is required.
3. If [project] is provided, explicit project takes precedence.

List projects:

s2s list

Session orientation with live.md and protocol.md

.s2s/live.md is written by s2s after every significant command. It always contains:

• The active project and feature
• Current stage and status
• The next action the AI should take

At the start of a session, read .s2s/live.md to orient without re-running any commands. If s2s output has scrolled off-screen, reading live.md is cheaper than re-running s2s status.

.s2s/protocol.md is generated by s2s init and s2s update. It contains the full command reference for the current CLI version — purpose, arguments, flags, and examples for every active command. If you are unsure of a command’s syntax, read protocol.md before guessing.

Project structure managed by s2s

<app-root>/.s2s/
  project.json
  project.local.json
  config/
    runtime.json
    backup.policy.json
    governance.exceptions.json
  guardrails/
  artifacts/
    <projectId>/
      changes/
      specs/
      slices/
      runs/
      gates/
      ledger.json
  logs/
    orchestrator.log
  backups/

Root compatibility shim files:

• AGENTS.md
• CODEX.md
• CLAUDE.md

Global state location:

~/.s2s/
  projects.json
  runtime/worktree-provider/
  worktrees/<project>/
  backups/projects/<project-hash>/<snapshot-id>/

Troubleshooting

1. No local .s2s context found

   • This happens for project commands outside local context.
   • Run command inside a configured project or pass [project].

2. Command not found in PATH: codex / claude

   • Install and authenticate that chat CLI first.

3. Version compatibility block

   • Upgrade s2s and retry.

4. Engineering execution issues

   • Validate app dependencies and verify commands in target repo.

5. Desktop/terminal mismatch warning

   • This appears when lastClient is desktop and s2s runs in terminal.
   • Open the desktop app on the same repo root, or run s2s config edit and switch to codex-cli/claude-cli.

6. Wrapper prefix enabled but header cadence is inconsistent

   • Wrapper header is designed for first response and agent-change moments.
   • In fully interactive terminal mode, s2s may fallback to plain passthrough for compatibility.
   • Keep Session Banner enabled for deterministic launch-level visibility.

7. stage '<x>' blocked by strict guardrail policy

   • Canonical guardrails or root shim overrides contain instructions that conflict with .s2s/guardrails/*.
   • Run s2s doctor to inspect discrepancies and resolve them.
   • If needed temporarily, switch to warn using s2s config edit.

8. Orchestrator errors or unexpected routing

   • Non-fatal orchestrator errors are logged to .s2s/logs/orchestrator.log.
   • Run with --verbose to surface orchestrator warnings to stderr.
   • Use s2s request "<prompt>" to resubmit intent and let the orchestrator re-plan the route.