Automation#

Wiring the loop into the tools a team already runs: editors, agents, hooks and CI.

Wire the MCP server into Claude / Cursor / Aider#

Goal: let an MCP-aware AI agent read specs, list requirements, and run validate directly.

Install:

npm i -g @spec-driven/mcp-server

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "spec-driven": {
      "command": "npx",
      "args": ["-y", "@spec-driven/mcp-server"]
    }
  }
}

Tools exposed by the server:

Restart the client; the tools appear in the model's tool list as spec-driven.*.

Install the Claude Code plugin#

Goal: the loop as slash commands, the spec tree over MCP, and the gate running before the session can end rather than after it in CI.

csda agents init --tool claude-plugin --project-dir ./csda-plugin

That writes a complete plugin: .claude-plugin/plugin.json, the six commands of the loop under commands/csda/, an .mcp.json pointing at the spec-driven MCP server, and hooks/hooks.json with the gate.

The hook is the part no other target can offer. Every other tool here gets instructions — text an agent may or may not follow. A plugin gets a Stop hook, which runs whether the agent likes it or not:

The spec gate is failing, so this work is not finished:

  • [strict_tdd_1] Test artifact is TBD but status is 'In Dev'
    fix: Write the test first, then set its path in the row's
         'Test artifact' column.

Run `csda validate . --strict-tdd` to see all of it.

The session does not end while that is true. validate --strict-tdd stops being something that reviews an agent's work after it has gone and becomes something it cannot walk past.

It will not trap you. The hook blocks once per prompt. The second time the same prompt reaches it, the findings are reported and the session ends: by then the agent has been told, and a human needs to see the answer more than the loop needs another turn. A project without spec.md, or a machine without csda on PATH, is left alone entirely.

claude-plugin is the one target csda agents init does not write by default — a plugin is an installable artefact, not something to scatter into every project.

Use the VS Code extension#

Goal: get inline diagnostics for pack.yaml, code-lens to jump to the traceability row, and validate-on-save.

1. Install vscode-spec-driven from the Marketplace (ext install rsaglobaltech.vscode-spec-driven).
2. Open a project root. The extension auto-detects spec.md / docs/specs/traceability.md.
3. Open any pack.yaml — diagnostics from the JSON Schema appear in the Problems panel.
4. Hover any REQ-NNN (or UC-, SCN-, AGG-, EVT-, RUL-, CMD-) → CodeLens shows "Reveal in traceability".
5. Enable validate-on-save: open settings, search Spec-Driven, tick validateOnSave. The CLI runs after every save and posts results to the Problems panel.

Settings:

Drive delivery with the harness#

csda harness run drives plan → agent → verify → done for every pending requirement, each in its own git worktree, in dependency order, and it never merges.

→ The harness

Run the gate without Node on the build agent#

The generated CI configs call npx, which needs Node. Plenty of build agents do not have it — a Java shop's Jenkins agent, a locked-down runner — and that is the whole reason the Docker image and the Maven and Gradle plugins exist.

Docker. Mount the workspace and run the gate:

docker run --rm -v "$PWD:/workspace" \
  ghcr.io/rsaglobaltech/csda:0.2.1 validate . --strict-tdd

Pin the version. latest is a convenience for a laptop, not for a pipeline — a gate that changes under you is not a gate. The image is published for linux/amd64 and linux/arm64, so ARM runners work unchanged.

In GitLab CI, that is the whole job:

spec-gate:
  image: ghcr.io/rsaglobaltech/csda:0.2.1
  stage: test
  script:
    - csda validate . --strict-tdd

In Jenkins:

stage('Spec gate') {
    agent { docker { image 'ghcr.io/rsaglobaltech/csda:0.2.1' } }
    steps { sh 'csda validate . --strict-tdd' }
}

Maven or Gradle. If the build already runs one of those, bind the gate to a phase instead of adding a container:

<plugin>
  <groupId>com.rsaglobaltech</groupId>
  <artifactId>csda-maven-plugin</artifactId>
  <executions>
    <execution>
      <goals><goal>validate</goal></goals>
    </execution>
  </executions>
</plugin>

validate binds to the verify phase by default, so mvn verify runs the gate without further wiring. plan and doctor are goals too.

Not published yet. The plugin builds and its tests run in CI, but it is not on Maven Central — that needs an OSSRH account and a signing key. Until then, mvn -f packages/maven-plugin install from a clone puts it in your local repository. The Docker path above needs nothing.

The plugins target Java 11 deliberately: a corporate build agent is exactly where you cannot choose the JDK.

Wire validate into a pre-commit hook#

Goal: block commits that drop a REQ without a .feature or a traceability.md row before they ever leave the developer's machine.

Plain shell (works without husky/lefthook):

# .git/hooks/pre-commit  (chmod +x)
#!/usr/bin/env bash
set -e
echo "→ csda validate --strict-tdd"
npx --yes create-spec-driven-app@0.1.0 validate . --strict-tdd
echo "→ csda specops diff (must be clean)"
DIFF=$(npx --yes create-spec-driven-app@0.1.0 specops diff --format json 2>/dev/null || true)
if echo "$DIFF" | grep -q '"added":\[\([^]].\)\]\|"modified":\[\([^]].\)\]'; then
  echo "✖ Pack content drifted. Run \`csda specops sync\` and commit again."
  exit 1
fi

Or with husky (package.json):

npm install --save-dev husky
npx husky init
echo 'npx --yes create-spec-driven-app@latest validate . --strict-tdd' > .husky/pre-commit

Mirror the same call in CI (see §4) so the gate survives --no-verify.

Sync requirements with Jira or Azure Boards#

csda alm sync keeps the traceability matrix and the board in step — creating an issue for each unlinked requirement, closing it when the requirement is done, and reporting drift rather than resolving it.

→ Jira and Azure Boards

Next#

• The harness
• Jira and Azure Boards
• The agent contract
• The harness spec