SpecPilot

Turn one vague idea into a validated spec, a bounded plan, and a safer downstream handoff.

SpecPilot is a skill-first, cross-host, spec-first workflow framework for coding agents. It is invoked by a host agent, not an independent model runtime.

Quick Start

Global install:

npm install -g @atombombbbaby/specpilot@latest
specpilot init
specpilot doctor

Project-local install:

npm install --save-dev @atombombbbaby/specpilot
npx specpilot init
npx specpilot doctor

The shortest useful workflow after initialization is:

specpilot intake start --json
specpilot validate run --json
specpilot validate prompt --json
specpilot validate finalize --summary "Spec is ready for planning." --review-source manual-cli --reviewer-type human --check-scope-aligned true --check-scenarios-testable true --check-acceptance-testable true --allow-planning true --json
specpilot plan generate --json
specpilot artifact export --json

What You Get

SpecPilot helps a host agent turn a vague idea into:

• clarified requirements
• a development-ready spec
• a spec-check result with a hard planning gate
• a plan derived from the validated spec
• a bounded handoff for downstream execution

In short:

idea -> guided intake -> spec -> validation gate -> plan -> bounded handoff

The Product Contract

SpecPilot enforces two workflow promises:

1. No planning before a validated spec-check explicitly allows planning.
2. No handoff is considered current if the spec or validation input has gone stale.

That contract is persisted under .specpilot/ so the host agent can always recover state, blockers, stale artifacts, and the recommended next command.

Codex Usage

specpilot init creates .specpilot/, writes a managed block into AGENTS.md, and links the packaged skills for Codex.

After initialization, Codex should use these packaged skills:

• node_modules/@atombombbbaby/specpilot/skills/spec-intake/SKILL.md
• node_modules/@atombombbbaby/specpilot/skills/spec-validate/SKILL.md
• node_modules/@atombombbbaby/specpilot/skills/spec-plan/SKILL.md

README is supplemental context only. SpecPilot is meant to be driven by the host agent through its skills and the public CLI protocol. The intake layer is now moving toward a host-driven Socratic UX while preserving the same CLI protocol for compatibility.

Human-Friendly Commands

specpilot init
specpilot update
specpilot doctor
specpilot version

Use these to install, refresh, and inspect the current project wiring.

Agent-Oriented Commands

specpilot intake start --json
specpilot intake next --json
specpilot intake answer --value "..." --json
specpilot spec build --json
specpilot validate run --json
specpilot validate prompt --json
specpilot validate finalize --summary "..." --review-source manual-cli|host-assisted --reviewer-type human|agent --check-scope-aligned true|false --check-scenarios-testable true|false --check-acceptance-testable true|false --allow-planning true|false --json
specpilot plan generate --json
specpilot artifact list --json
specpilot artifact show spec --json
specpilot artifact export --json
specpilot host status --json

Use --json whenever a host agent needs stable machine-readable state, including blockers, stale artifacts, refinement targets, and recommended next commands. When the workflow is driven directly from the CLI without host-assisted review, SpecPilot now labels that path as degraded/manual review mode rather than treating it as equivalent to the host-driven path.

Eval Harness

SpecPilot also includes an eval harness for real-world provider simulation without changing the default workflow. This is eval-only and does not turn the CLI into a general model runtime:

specpilot eval intake --provider ark --scenario "我想做一个极简风个人网站" --json
specpilot eval intake --provider openai-compatible --scenario "我想做一个极简风个人网站" --json
specpilot eval validate --provider ark --json
specpilot eval scenarios --provider ark --json
specpilot eval scenarios --provider openai-compatible --release-subset --json
specpilot eval scenarios --provider ark --scenario-id intake-asset-readiness,validate-good-spec --json
npm run eval:release

specpilot eval scenarios runs the built-in standard scenario suite and reports provider-vs-deterministic-local differences. npm run eval:release runs the curated release subset and emits a machine-readable soft-gate report. Failed live-provider scenarios should trigger human review before publish, not automatic release rejection. npm run eval:v03:matrix runs the 8-scenario real-user matrix used to close 0.3.0. The hard closeout signal is coreGatePassed; remaining provider-only warnings should be deferred, not silently ignored.

Environment variables:

• ARK_API_KEY
• ARK_BASE_URL (OpenAI-compatible Ark Coding base URL; defaults to https://ark.cn-beijing.volces.com/api/coding/v3)
• ARK_MODEL_ID (defaults to ark-code-latest)
• optional: ARK_TIMEOUT_MS, ARK_APP_ID
• OPENAI_COMPAT_API_KEY
• OPENAI_COMPAT_BASE_URL
• OPENAI_COMPAT_MODEL_ID
• optional: OPENAI_COMPAT_TIMEOUT_MS

Local template files:

• .env.eval.example: committed template
• .env.eval: local gitignored file for your real credentials

Full eval guide:

• docs/EVAL.md

Artifact Boundary

SpecPilot centers the workflow around a structured boundary workspace:

.specpilot/
  session/
    session.json
    profile.md
    profile.json
    intake-result.json
  spec/
    spec.md
    spec.json
    spec-check.md
    spec-check.json
  plan/
    plan.md
    plan.json
    handoff.md
    handoff.json
  meta/
    host.json
    adapter.json
    workflow-state.json

This is the contract between upstream specification work and downstream execution.

Docs

• Install Guide
• CLI Reference
• Eval Harness Guide
• v0.3 Scenario Matrix
• Roadmap
• v0.2 Acceptance
• Project Docs Index
• Next-Version Handoff

Status

Current status: 0.3.0 closeout candidate with a working install/init path, public CLI protocol, semantic validation gate, manual CLI degraded safeguards, provider-based eval, plan generation, and bounded handoff.

Planned next phase: move remaining spec-richness work into v0.4, then continue the host-first workflow migration in v0.5.

License

UNLICENSED