AlexandrAI AGENTS.md
agents-md

STDD Harness Agent Guide

Project-specific AGENTS.md guidance for the STDD spec-then-test-driven development harness, orchestrator hierarchy, phase gates, pipeline scripts, and human approval checkpoints.

AGENTS.md

Guidance for coding agents working on STDD, the spec-then-test-driven development harness.

Project Overview

STDD combines SDD for specification/design and TDD for implementation. It is built for enterprise and multi-repository development where each phase creates auditable artifacts and requires QA review before moving forward.

Core structure:

  • README.md: pipeline overview and examples.
  • CLAUDE.md: runtime instruction surface.
  • .claude/agents/: 16-agent hierarchy from main orchestrator through SDD/TDD/QA/report roles.
  • .claude/skills/: phase methodology skills.
  • .claude/skills/stdd-pipeline/scripts/: workspace, scratchpad, org, stack detection, preprocessing, gate validation, and report scripts.
  • inputs/: optional feature requests, existing specs, and existing tests.

Setup Commands

bashcd <project-root>
claude

Useful harness scripts live under the STDD pipeline skill:

bashbash .claude/skills/stdd-pipeline/scripts/init-workspace.sh
bash .claude/skills/stdd-pipeline/scripts/init-scratchpad.sh
bash .claude/skills/stdd-pipeline/scripts/update-org.sh
bash .claude/skills/stdd-pipeline/scripts/detect-stack.sh <target-repo>
bash .claude/skills/stdd-pipeline/scripts/preprocess-inputs.sh
bash .claude/skills/stdd-pipeline/scripts/validate-sdd-gate.sh <workspace>
bash .claude/skills/stdd-pipeline/scripts/generate-report.sh <workspace>

Do not claim a script ran unless it was actually executed for the active workspace.

Pipeline Rules

  • Phase 0 creates mission and workspace context.
  • SDD phases analyze, specify, design, write manual ITa test cases, and derive developer test cases.
  • The SDD/TDD gate validates traceability before implementation starts.
  • Human approval is required after SDD artifacts and again after test/implementation diffs unless the operator explicitly selects an allowed bypass.
  • TDD phases write failing tests, implement, then validate with tests, coverage, static analysis, and drift checks.
  • The report phase renders the final state and any failure/incomplete banner.

Agent Boundaries

  • Main orchestrator owns coordination and human gates.
  • SDD orchestrator owns phases 1-5.
  • TDD orchestrator owns test and implementation phases.
  • QA reviewer checks deliverable quality and premise correctness after each phase.
  • Reporter should package facts from existing artifacts, not invent conclusions.

Code Style

  • Keep phase artifacts in the active workspace; do not mix artifacts from older runs.
  • Preserve JSON and Markdown pairs where the harness expects both.
  • When adding a new phase field, update downstream validators and report generation.
  • Keep code-writing agents aligned with patterns extracted from target repositories.

Testing

  • Use stack detection before selecting test commands for target repos.
  • Validate the SDD/TDD gate before writing implementation code.
  • Run target-repo tests, coverage, static analysis, and drift checks in validation.
  • For harness changes, exercise the scripts or a small synthetic workspace rather than relying on README intent alone.

Security

  • Do not commit target repository secrets or copied private docs.
  • Keep input documents in inputs/ only when the operator intends the harness to process them.
  • Redact absolute local paths, credentials, issue URLs, and customer identifiers from public examples.