Create a new Specification Driven Development product repository that adds only product/ and keeps the versioned framework runtime outside the repository.
Install the released CLI first; installation does not initialize a product:
spec-framework versionAutomated bootstrap:
spec-framework init ../my-productCLI-style bootstrap from the framework repository:
spec-framework init ../my-product --agents codex,cursor,claude --yesThe wizard also asks for the starting point. All skills remain installed; the choice selects a versioned initialization contract that composes the product tree and changes the generated bootstrap, active registry, and entry gate. Contracts are framework-owned data and can select only validated assets and typed CLI actions; they are not adopter-executable configuration.
Initialization plans the complete tree, explicit empty directories, and artifact registry in memory, rejects file/directory collisions and invalid relationships, and publishes a staged product/ atomically. A failure leaves no partial product tree, and an existing product/ is never overwritten by init or --force.
| Starting point | Adopted path |
|---|---|
new-product |
Full Foundation: Problem -> Vision -> Principles/North Star -> Strategy. |
existing-product |
Product Baseline -> Strategy. Escalate to full Foundation when current audience or value is uncertain. |
existing-documents |
Review the latest import run -> materialize selected drafts -> route them through normal owners and gates. |
existing-feature |
Feature Brief -> complete Product Landscape -> Engineering and Design System baselines -> Target Feature -> workspace. |
existing-implementation |
Implementation Assessment -> full Foundation -> workspace. |
audit-only |
Read-only inspection. Registry, reports, approvals, workspaces, imports, and delivery mutations are blocked. |
For existing documents, use --starting-point existing-documents with --source-dir or --sources. The command inventories sources under product/knowledge/imports/ but does not create Domains, User Goals, or Features without explicit approval.
When importing a new demand into an existing product, review its proposed destination against the nearest context.md, parent chain, sibling Features and Use Cases, approved decisions, and shared Engineering and Design baselines. Record whether it extends an existing interaction, creates a new Use Case or Feature, or remains a non-delivery item before materialization. The existing hierarchy is preserved; context.md carries optional relations, traceability, and evolution metadata.
Keep implementation roots beside product/, using semantic roles such as web/, api/, worker/, mobile/, infrastructure/, or library/. Before init, the agent inspects the complete repository—including nested projects—and passes the authoritative semantic map explicitly:
spec-framework init . --agents codex --starting-point existing-implementation --code-roots web:web,api:api --yesUse --no-code-roots only when that inspection confirms no implementation. Omitting both options activates a backward-compatible CLI heuristic marked needs-agent-review; it is evidence, not a confirmed ownership map, and must be corrected before Specification.
The resulting product/knowledge/assessments/product-landscape.md is the required comprehensive inventory. Route the shared engineering baseline through engineering-orchestrator, complete engineering/engineering-system.md and design/system/design-system.md, and obtain their human approvals before authoring a real Specification. With no code, these documents are explicit hypotheses; first confirm the intended stack and official scaffold command, then create the semantic sibling root rather than placing code under product/.
After the Artifact Importer fills mapping.json, review the selected mappings and materialize them explicitly:
spec-framework import materialize --run IMPORT-001 --approved-by "Product Owner" --yesMaterialized files are explicitly marked provenance.kind: import-draft. Route each file through its owning skill before approval; the approval gate rejects imported drafts until provenance is changed to skill-normalized.
After the owner has completed the structural review, spec-framework template normalize --artifact <path> --skill <owner-skill> records that promotion without changing approval status.
For existing-documents, the latest run pinned in product/.product/framework.json must be materially complete before spec-framework work can create a workspace. Materialization authorizes selected draft writes only; review and approve each resulting product artifact through its normal owner and parent gates.
The command rejects missing evidence, paths outside product/, duplicate targets, non-draft content, and existing destination files.
Use spec-framework work --feature <path-or-id> to create an independent workspace, then status and next to see blockers and the canonical next skill. Use approve for human-reviewed status grants, gates before Code Runner, and graph ready/claim/release/complete to coordinate task ownership.
See delivery-closure.md for the complete operational flow and command examples.
Install a versioned release binary as described in install.md. Go and Node.js are not runtime requirements for adopters.
Initialization writes product/.product/framework.json, materializes the pinned embedded assets in the user cache, and installs one namespaced dispatcher for each selected agent in the user's harness directory. The Codex dispatcher uses ~/.agents/skills/spec-framework; upgrade removes only its legacy namespaced dispatcher when present. It does not create .spec-framework/, local agent trees, root guides, or CI workflows.
Activation is manifest-only. Mentions of Spec Framework do not activate the dispatcher when product/.product/framework.json is absent or invalid. After activation, the dispatcher resolves Framework Guide first unless current CLI guidance or an explicit human request names both the specialist and concrete scope. Persisted handoffs/checkpoints require read-only CLI revalidation before direct routing, and upgrade refreshes dispatchers for the agents selected in the manifest or command.
Manual development bootstrap:
- Create or open the product repository.
- From the framework source repository, run
go run ./cmd/spec-framework init <target>. - Replace
product/starter placeholders with product-specific content. - Run validation from the repository root.
spec-framework validateBefore approving a delivery artifact, use spec-framework validate --strict. Approval previews perform the narrower candidate check automatically and block missing template sections, invalid QA evidence, and applicable delivery metadata before writing approval history.
Direct validator form when debugging:
spec-framework validate --product-root product --framework-root <framework-source-root> --write-registry --write-reportFor audit-only, omit both write flags and keep findings in terminal output.
Upgrade an initialized product from the framework repository:
spec-framework upgrade --target ../my-product --agents codex --yes| Product-Owned Area | Purpose |
|---|---|
product/.product/ |
Product state, registry, derivations, approval records, and adopted framework metadata. |
product/foundation/ |
Full Foundation and proportional Feature Brief or Product Baseline contracts selected during adoption. |
product/domains/ |
Product domains, goals, features, use cases, specifications, and tasks. |
product/knowledge/decisions/ |
Product and cross-cutting decisions; design and engineering decisions use dedicated roots. |
product/knowledge/business-rules/ |
Product business rules. |
product/audits/ |
Product audits, readiness reports, QA evidence references, and threat register. |
product/releases/ |
Product release notes and release readiness. |
product/design/ |
Product design artifacts and mockups. |
| Framework-Owned Area | Purpose |
|---|---|
| Versioned user cache | Method, skills, templates, and validation assets resolved from the product manifest. |
User-scoped spec-framework dispatcher |
Manifest-gated agent integration that resolves specialized skills. |
Installed spec-framework binary |
Validation, bootstrap, upgrade, and migration tooling. |
- Do not copy framework maintenance history into any product decision domain.
- Do not inherit example domains as real product scope.
- Do not inherit retroactive approval records from the framework lab.
- Do not edit cached framework internals to encode product scope.
Stable commands:
spec-framework init ../my-product
spec-framework validate
spec-framework upgrade --target ../my-product
spec-framework dashboard --work WORK-001
spec-framework engineering-system inspect
spec-framework engineering-system validate
spec-framework engineering-system triggers
spec-framework engineering-system migrate --dry-run
spec-framework decisions migrateUse decisions migrate as a preview first. Existing repositories should use --interactive to review ambiguous inferred types and scopes before applying the metadata migration.
For CI and routine audits, run spec-framework decisions check --strict. Use --json for machine-readable findings. --fix-links is preview-only unless --yes is supplied and never changes approval records.
Engineering System catalogs created before schema versioning must run engineering-system migrate --dry-run and then the same command without --dry-run. The migration only adds schema_version: 1, preserves product-owned fields, and never creates approval records. Approved systems must be re-approved by a human after any migrated content change.
Legacy Engineering Systems whose quality area still points to quality/quality-model.md use the same migration command. The dry run reports the catalog update and missing Quality System files. The applied migration preserves the existing quality model and any pre-existing quality files, creates only missing quality-system.md, quality-system.yaml, and test-strategy.md, atomically changes the area contract to quality/quality-system.md only after materialization succeeds, rolls back generated files on failure, and never creates approval evidence. Review the generated baseline, increment the Engineering System version when required by compatibility policy, and obtain human re-approval before proposed-or-later consumers rely on it.
Adoption is backed by the validator, package smoke tests, and the external-runtime / product/ boundary.