Requirements-as-Code (RaC)

Requirements-as-Code turns a paragraph of plain English into a complete, reviewable specification for an AI system — and keeps the what and the how in sync as the project evolves.

You describe the system you want in a sentence or two. RaC produces:

1. A product requirements spec — the what & why: the tasks the system handles, how each one is graded, which actions are risky, what must never happen, and the release gates.
2. A technical requirements spec — the how: architecture, guardrails, tool permissions, cost controls, security, and deployment — each item linked back to the product requirement it implements.
3. A trace report — a deterministic check that every risky product requirement is actually covered by a technical control, with no stale links.

Everything is generated by an LLM using your own API key. Set your provider key before running any RaC function. There is no offline/deterministic fallback — the LLM decides how many tasks, rubrics, safety requirements, and gates the system warrants.

Authoring and scoring only — by design

RaC authors and scores specifications. It deliberately does not ship a requirements compiler, a CI gate executor, a human-in-the-loop approval runtime, or a budget/policy enforcement engine. RaC writes the contract; your stack (CI, Spec Kit, Kiro, Claude Code, Cursor, your approval workflow) enforces it. This boundary is intentional and is stated in every spec's metadata.

Who this is for

RaC is written so that non-engineers can drive it:

Role	What RaC gives you
Product owners / managers	Turn an idea into a structured spec with explicit success criteria, scope boundaries, and open questions — without writing code.
Business analysts	A repeatable way to capture "what must never happen," acceptance rubrics, and risk tiers from a stakeholder conversation.
Infrastructure / platform teams	A technical spec with guardrails, tool permissions, cost ceilings, rollout strategy, and OWASP-agentic security controls — traceable to product intent.
Engineering leads	A coverage check (trace) that fails CI when the implementation drifts from the agreed requirements.
Risk / compliance	A pre-mortem of safety incidents, each tied to a hard release gate and a machine-checkable assertion.

If you can write a paragraph describing what you want an AI system to do, you can produce a first-draft specification in seconds.

The mental model

1. product(intent) reads your intent and emits the product spec.
2. technical(product=spec) derives the technical spec, linking every control back to a product requirement ID.
3. trace(product, technical) proves the two are in sync (and can analyze a code diff for drift).
4. project(spec, to=...) renders either spec into the file your coding agent or SDD tool expects.

A 30-second example

import os
from mycontext.rac import product, technical, trace, format_report, to_yaml

os.environ["OPENAI_API_KEY"] = "sk-..."

INTENT = (
    "Brightcart support gets ~2,000 emails/day. We want Aurora: an agent that "
    "reads each email, looks up the order, and drafts (eventually sends) a reply "
    "— refunds require human approval. Success means faster replies without wrong "
    "refunds, leaked customer data, or brand-damaging replies."
)

# 1. What & why
prod = product(INTENT)

# 2. How (traceable to the product spec)
tech = technical(product=prod)

# 3. Are they in sync?
report = trace(prod, tech)
print(format_report(report))   # -> coverage %, findings, status

# Inspect or save either spec as YAML
print(to_yaml(prod))

The same idea, on the command line

export OPENAI_API_KEY="sk-..."   # required for all rac commands

# Product requirements -> YAML on stdout (or --out file.yaml)
mycontext rac product "Aurora drafts replies to billing emails; refunds need approval."

# Technical requirements from a saved product spec
mycontext rac technical --from-product product.yaml --out technical.yaml

# Prove coverage (exit code 1 if drift is detected — CI-friendly)
mycontext rac trace --product product.yaml --technical technical.yaml

See the CLI reference for every command and flag.

What's in this section

Page	What it covers
For business teams	A non-technical, end-to-end walkthrough and a glossary of every term.
Product requirements	product() — every parameter and every section of the output, annotated.
Technical requirements	technical() — the two entry paths, 24 sections, traceability, and serves links.
Trace & validation	trace() coverage/drift checks and validate() structural + quality lint rules.
Cognitive-pattern grounding	analyze(), format_brief(), select_patterns() — inspect what lenses the LLM applies.
Projections	project() — render a spec to AGENTS.md, CLAUDE.md, Cursor, Spec Kit, Kiro, or an ADR.
CLI reference	Every mycontext rac subcommand with all flags, examples, and exit codes.
API reference	Every public symbol, signature, parameter, return value, and spec dict shape.

Core principles

• Gaps never block generation. A missing detail becomes an open question (OQ-01, OQ-02, …), not an error. You always get a complete framework to react to.
• LLM-native, key required. All generation calls an LLM through your own provider key. There is no offline skeleton and no mycontext server. Your key, your cost.
• Traceability is first-class. Technical controls carry a serves: list of the product requirement IDs they implement, so drift is detectable.
• You own enforcement. RaC stops at authoring + scoring. Your stack (CI, Spec Kit, Kiro, Claude Code, Cursor) enforces.
• Validated output. A Pydantic contract enforces the typed-ID grammar and referential integrity after each generation pass, with a self-repair loop if violations are found.