sdd-harness

name	sdd-harness
description	Operate a vendor-neutral spec-driven development harness for coding agents. Choose the appropriate SDD ceremony, create durable feature artifacts, enforce approval and implementation gates, coordinate bounded agent handoffs, and route work to feature execution or independent review. Use for multi-file, ambiguous, risky, cross-agent, or long-running coding work.
metadata	{"version":"2.0","tags":["sdd","harness","orchestration","coding-agents","handoff"]}
license	MIT

SDD Harness

Use the lightest workflow that preserves safety and traceability. The harness is an operating protocol, not a replacement for repository instructions or human ownership of product intent.

Choose the workflow

• Small, reversible, obvious change: inspect → edit → narrow test.
• Several files or one architectural decision: create/update a plan and task checklist.
• Ambiguous behavior, substantial feature, migration, or risky refactor: use sdd-feature.
• Cross-team, security-critical, long-running, or multi-agent work: use sdd-feature plus independent sdd-review.
• Final review, merge, release, or disputed completion claim: use sdd-review.

Default lifecycle: explore -> specify -> clarify -> design -> analyze -> approve -> bounded implementation -> verify -> reconcile. Use the quality gates for risky work; skip them only for genuinely small, obvious changes.

Do not impose full SDD ceremony on a trivial change. Do not downgrade a risky change merely to move faster.

Harness invariants

• Human-owned intent: agents may clarify and structure requirements but must not approve product scope on the human’s behalf.
• Artifact handoff: agents communicate through committed or explicitly scoped artifacts, not hidden chat context.
• Approval gate: do not implement until requirements/design/tasks are sufficiently resolved and the user or project process approves the intended scope.
• Bounded execution: select one task group, define owned and forbidden files, and stop at the milestone.
• Evidence gate: no task or requirement is complete without concrete validation evidence.
• Reconciliation gate: never rewrite artifacts retrospectively to excuse accidental behavior.
• Isolation: parallel agents use separate worktrees/branches when edits can overlap; define ownership, dependencies, interfaces, and merge order.
• Traceability: use stable IDs (REQ-###, AC-###, T-###) and link tasks and evidence back to them.
• Spec co-evolution: behavior changes require a deliberate artifact update; never update artifacts merely to make accidental code pass.

Standard feature layout

specs/<feature>/
├── spec.md
├── design.md
├── tasks.md
└── verification.md

Use repository-specific locations when they already exist. Keep permanent repository rules in AGENTS.md; keep feature intent and decisions in the feature artifacts. Record artifact status (draft, needs-clarification, approved, in-progress, verified, or blocked) where the repository convention permits; a checkbox alone is not evidence.

Agent handoff contract

Give each implementation agent:

• one task or dependency-closed task group
• owned files/components and forbidden boundaries
• linked requirement/design references
• interface and data contracts
• exact validation commands
• stop condition and reporting format

Require the agent to report changed files, tests and observed output, deviations, unresolved concerns, and next task. A fresh reviewer should be able to continue from artifacts alone.

Completion gate

Before declaring completion, require sdd-review to compare the current implementation, diff, tests, and artifacts. Record unsupported or environment-blocked evidence explicitly. A build-only result cannot prove live behavior, browser behavior, provider integration, persistence across restart, migration safety, or cross-user authorization.

The final record must distinguish verified, partial, failed, and blocked; never silently promote partial evidence to complete.

Failure handling

On missing inputs, contradictory artifacts, failed validation, dirty-scope collision, unavailable dependency, or unsafe ambiguity: stop the affected workflow, preserve evidence, report the blocker, and request the smallest decision needed. Never guess, silently broaden scope, or continue past a failed safety gate.

If implementation reveals a missing or wrong requirement, stop the affected task, record evidence, request the scope decision, update dependent artifacts deliberately, and rerun analysis. Do not rewrite the specification to explain away an implementation defect.