Skip to content

SDS β€” Spec-Defined Software (Requirement Delivery Version)

Welcome to the future of software engineering.

Spec-Defined Software (SDS) is the transition of requirement delivery from manual coding to precise, AI-collaborative specification-defining. In this paradigm, a business requirement's complete behavioral and business identity is codified in its spec.md (the "What") and mapped to its technical realization in design.md (the "How").

The physical code, database migrations, tests, and deployment configurations are treated as logical derivatives that can be automatically synthesized, verified, and self-healed by advanced AI engines.

πŸš€ The SDS Philosophy: Code is Compile Target

Always treat the Specification as the absolute source of truth for the entire requirement delivery process. Prioritize the completeness and clarity of the Specification over immediate coding.

  [ User Scenario ] βž” [ Accepted Spec & Design ] βž” [ Implementation ] βž” [ Verification ] βž” [ Requirement Delivery ]

The code is merely a compiled artifact of the delivered requirement. By keeping our edits highly focused on the Spec-first delivery model, we map every change back to an Acceptance Criterion (AC) in the Spec, achieving zero-drift development.

πŸ› οΈ The SDS Core-Centric Lifecycle Suite

Today, the released sds-core skill provides specification validation, traceability checks, Git hooks, and MCP access. The specialized lifecycle skills below describe the product roadmap; their status in the roadmap table is the source of truth for availability:

  1. sds-ideator (Demand Phase, in progress): Planned Socratic workflows for refining fuzzy requirements into Gherkin-style Acceptance Criteria.
  2. sds-architect (Design Phase, in progress): Planned translation of accepted product specs into technical contracts and design.md.
  3. sds-coder (Implementation Phase, planned): Planned implementation assistance with @sds-trace coverage.
  4. sds-qa (Verification Phase, planned): Planned AC-driven test synthesis and quality gates.
  5. sds-ops (Delivery Phase, planned): Planned atomic deployment and rollback workflows.

πŸ“¦ Instant Quickstart

Get started with the SDS CLI in seconds:

1. Installation

Install the CLI tool globally using our one-line installer: 

curl -fsSL https://raw.githubusercontent.com/flingfox63/spec-defined-software/main/install.sh | sh

2. Install into AI agents and IDEs

Detect local agents and install the released SDS Agent Skill. MCP configuration remains untouched by default:

sds install-agents

The default is user-scoped automatic detection, with a shared-Skill fallback. Use --targets opencode,claude to choose the agents to install or upgrade. You can also select all targets, choose a subset, or keep the integration in one repository:

sds install-agents --targets all
sds install-agents --targets codex,opencode,claude,agy
sds install-agents --targets cursor --scope project --project-dir /path/to/repo

Supported selectors are shared, codex, opencode, claude, cursor, cline, antigravity (agy), gemini, copilot (vscode), windsurf, roo, and kilo. SDS follows the Agent Skills directory convention. Installation is idempotent: agents that support .agents/skills share one SDS bundle, while agent-specific copies are used only where required. Managed markers record the Skill bundle version and content hash, so older bundles update in place without creating duplicates. Existing non-SDS skills, MCP servers, and settings are preserved. Add --with-mcp when MCP is needed or --dry-run to preview changes; --no-mcp remains a compatibility alias for the default. sds version reports the CLI, harness, and Skill bundle versions separately.

3. Initialization

Run the initialization scaffold in the root of your project directory: 

sds init
This generates the .sds.harness.yaml config and sets up the standard specs/ directory layout.

4. Run Verification Checks

Verify your repository structure, code annotations, and check for spec-to-code drift: 

sds check

Every AC requires a scenario derivation record, including a durable context source, reasoning, ambiguity disposition and positive/counterexample expectations. New projects enable this gate explicitly. Older projects missing the policy key receive a migration warning; backfill records before setting enforce_ac_derivation: true. Keep business outcomes in spec and per-AC mechanisms/tests in design; independently review interpretations against context. Durable documents must not reference temporary review artifacts. See workflow and templates.

Optional manual MCP troubleshooting

Opt in with sds install-agents --with-mcp --targets TARGET. If a client cannot find the CLI, add --command /absolute/path/to/sds. OpenCode defaults to the v1 layout; v2 clients require --opencode-config-version v2. A manual stdio entry uses sds as the command and ["mcp"] as its arguments.

πŸ—ΊοΈ Ecosystem Roadmap

The SDS platform is evolving from a baseline linting tool into a fully automated, E2E AI-collaborative software delivery operating system. Below is our development timeline and milestones:

Milestone / Module Target Status Core Deliverables & Capabilities
sds-core
(The Guardrail)		 Shipped 🟒 Released β€’ Statically verifies directory layouts and Frontmatter states.
β€’ Integrates pre-commit Git hooks and global installers.
β€’ Exposes standard stdio Model Context Protocol (MCP) server.
sds-ideator
(Socratic PM)		 Q3 2026 🟑 In Progress β€’ Socratic alignment prompt suites to refine loose ideas into BDD Gherkin ACs.
β€’ Synthesizes and drafts initial spec.md files in specs_review/.
sds-architect
(Lead Engineer)		 Q3 2026 🟑 In Progress β€’ Compiles accepted product specs into concrete technical schemas.
β€’ Auto-generates TypeScript/Go API contracts, database migrations, and design.md.
sds-coder
(Autonomous Synthesizer)		 Q4 2026 πŸ”΅ Planned β€’ Subagent-driven code writer implementing functions directly from specs.
β€’ Automatically inserts @sds-trace anchors and self-heals compiler/drift errors.
sds-qa
(BDD Test Compiler)		 Q4 2026 πŸ”΅ Planned β€’ Synthesizes runnable integration, unit, and E2E test scripts from ACs.
β€’ Mandates a quality gate verification prior to deployment triggering.
sds-ops
(Atomic Release)		 Q1 2027 πŸ”΅ Planned β€’ Capistrano-style atomic releases with symbolic-link switching.
β€’ Automated virtualenv isolation and remote passwordless rollback controls.

πŸ’– Heritage & Inspiration

Spec-Defined Software (SDS) is proud of its roots and is heavily inspired by and evolved from GitHub's spec-kit methodology. We extend the original spec-kit patterns by introducing automated zero-drift linting, multi-agent LLM orchestration safety gates, and physical bidirectional traceability (@sds-trace) engineered specifically for the AI native era.

[!NOTE] The released sds-core skill integrates with the supported Agent Skills and MCP environments listed above. Lifecycle skills marked in progress or planned are not installed until they ship.

See the validation roadmap for planned behavior evaluation, rule consistency checks and negative fixtures.