# spec-to-delivery

Claude Agent Skills and an MCP server that turn a requirements document into an RFC, functional test scenarios, and a traceability matrix that proves every requirement has a test.

Built from a pattern I used on a 25-person enterprise platform team, where RFCs and test scenarios were the most repetitive engineering work in every sprint. The agent drafts, the engineer reviews. The tools in this repo are the deterministic part that keeps the agent honest: they parse, diff and cross-check so the model cannot quietly skip a requirement.

## What is in the box

| Piece | What it does |
|---|---|
| `skills/rfc-from-requirements` | Claude Agent Skill: requirements in, structured RFC draft out, with a requirement trace table |
| `skills/functional-test-scenarios` | Claude Agent Skill: writes Gherkin scenarios tagged with requirement IDs and verifies 100 percent coverage |
| MCP server (`src/`) | Four tools: `parse_requirements`, `diff_requirements`, `parse_scenarios`, `traceability_matrix` |
| `examples/` | A small rebate-accrual requirements doc and a feature file to try it on |

## Quick start

```bash
git clone https://github.com/medhakara/spec-to-delivery
cd spec-to-delivery
npm install
npm test
npm run build
```

### Register the MCP server with Claude Code

```bash
claude mcp add spec-to-delivery -- node /absolute/path/to/spec-to-delivery/dist/index.js
```

Or in `.mcp.json` at your project root:

```json
{
  "mcpServers": {
    "spec-to-delivery": {
      "command": "node",
      "args": ["/absolute/path/to/spec-to-delivery/dist/index.js"]
    }
  }
}
```

### Install the skills

Copy the two folders under `skills/` into your project's `.claude/skills/` (or `~/.claude/skills/` for every project). Claude Code picks them up automatically.

### Try it

In Claude Code, inside this repo:

```
Use the functional-test-scenarios skill on examples/requirements.md, starting from examples/accruals.feature.
```

The example feature file deliberately covers only five of the nine requirements, so you can watch the skill find the gaps, write the missing scenarios, and re-run the traceability check until coverage is 100 percent.

Then:

```
Use the rfc-from-requirements skill to draft an RFC for REQ-010 through REQ-012.
```

## Requirement format

Any Markdown line that starts with an ID such as `REQ-001`, `FR-12`, `NFR-3` or `US-045` is a requirement. List items, bold IDs and headings all work:

```markdown
- REQ-001: The system MUST compute accruals only inside the program period.
- **REQ-002** Accruals SHOULD be recalculated when a transaction is amended.
  Continuation lines are joined to the requirement above.
### REQ-003 Claim validation
```

Priority is read from MUST / SHALL / SHOULD / MAY / COULD in the text or a trailing `[MUST]` tag. The section is the nearest heading. Duplicate IDs are flagged, not merged.

## Scenario linking

A scenario is linked to a requirement by a `@REQ-001` tag above it, or by mentioning the ID in its title. Feature-level tags apply to every scenario in the feature.

## Tool reference

All tools accept `{ "text": "..." }` or `{ "path": "..." }` for each document.

- **parse_requirements** `{ document }` → `[{ id, text, section, priority, line }]`
- **diff_requirements** `{ before, after }` → `{ added, removed, changed: [{id, before, after}], unchanged }`
- **parse_scenarios** `{ features: [document] }` → `[{ feature, name, requirementIds, line }]`
- **traceability_matrix** `{ requirements, features: [document] }` → `{ rows, uncovered, orphanScenarios, unknownIds, coverage, markdown }`

Inspect interactively with `npm run inspect`.

## Why deterministic tools around an LLM

The skills tell the model what good looks like. The tools make it checkable. A model that "believes" it covered every requirement is not the same as a matrix that shows it did, and reviewers trust the matrix. The same split (LLM drafts, code verifies) is how I structure every agent that ships to production.

## Roadmap

- Excel and Jira export as requirement sources
- Coverage gate for CI (`spec-to-delivery check --min 100`)
- ADR skill sharing the same trace table

## Licence

MIT. Kumar Gautam, 2026.

---

Built by Kumar Gautam at [Medhakara](https://medhakara.com), an AI engineering studio.