Spec frameworks
Write requirements with whichever spec-driven development framework your team already uses. tg reads its files, gives every requirement an id that code and tests can point at, and reports what is implemented, verified and documented. If your format is missing, you can map it onto one that is supported, or add a reader.
Supported frameworks
Each framework has its own id prefix, so their ids never clash with each other or with your lat.md sections. The ids are the ones the framework already writes.
| Framework | Detected by | Files tg reads | Ids |
|---|---|---|---|
| OpenSpec | openspec/ | openspec/specs/<capability>/spec.md and the deltas of open changes | openspec:auth#Login, openspec:auth#Login#Valid password |
| GitHub Spec Kit | .specify/ | specs/<feature>/spec.md | speckit:001-checkout#FR-001, #US1, #US1#Scenario 2, #SC-001 |
| Kiro-style specs (Kiro, cc-sdd, spec-workflow-mcp) | .kiro/, .spec-workflow/ | .kiro/specs/<feature>/requirements.md, .spec-workflow/specs/<feature>/requirements.md | kiro:reports#Requirement 2, #Requirement 2#2.1 |
| BMAD Method | _bmad/, .bmad-core/, _bmad-output/ | The PRD (_bmad-output/planning-artifacts/prd.md, docs/prd.md) and story files | bmad:prd#FR-1, bmad:epic-1#Story 1.2#AC1 |
| Get Shit Done | .planning/ | .planning/REQUIREMENTS.md | gsd:requirements#AUTH-01 |
| Architecture decision records (MADR, Nygard / adr-tools, log4brains) | A numbered record in docs/adr, doc/adr, docs/decisions, …; .adr-dir; .log4brains.yml | NNNN-title.md in that folder | adr:0003 (also adr:3, the slug or the title) |
Lookups ignore case and extra spaces, and aliases resolve:
- a Spec Kit feature without its number (
speckit:checkout#FR-001); - a user story's title;
- a bare criterion number (
kiro:reports#2#1); - an ADR number without leading zeros.
A misspelled id fails tg check with a did-you-mean.
Point code and tests at requirements
The comment grammar is the same for every framework. Put an implements line above the code that realizes a requirement or a decision, and a verifies line above the test that proves a scenario or acceptance criterion.
// @tg: implements:: [[speckit:checkout#FR-001]], implements:: [[adr:2]]
export function pay(orderId: string, card: string) { … }
// @tg: verifies:: [[kiro:reports#Requirement 2#2.1]] {level: integration}
it('downloads a CSV when the analyst clicks export', () => { … });
Docs say what they explain in their frontmatter. openspec: takes bare OpenSpec capabilities, and specs: takes ids of any framework:
--- type: Decision specs: ["speckit:001-checkout", "adr:0002"] ---
Then tg trace reports every framework at once. Narrow it with tg trace speckit:001-checkout or tg trace adr, and fail CI on gaps with --gaps --strict.
Two kinds of records never count as gaps:
- Decision records need no test, so they never count as unverified.
- Retired records are listed but never reported as gaps: superseded, deprecated or rejected ADRs, and out-of-scope GSD items.
In the graph
Every requirement keeps the base type the code ontology knows (Requirement, Scenario or Decision), so implements and verifies work without changing your schema. It also gets its framework's own label:
UserStorywith itspriority,FunctionalRequirementandSuccessCriterion(Spec Kit);AcceptanceCriterionwith its EARS pattern (Kiro, BMAD), for exampleears: unwantedforIF … THENcriteria;Story(BMAD);ADRwithadrStatusanddate. ASupersedes [...]line in a record becomes asupersedesedge.
tg cypher "MATCH (u:UserStory {priority: 'P1'})-[:contains]->(s:Scenario)
OPTIONAL MATCH (t)-[:verifies]->(s)
RETURN s.scenario, count(t) AS tests"
tg init declares these labels in Types/spec-types.md, for the frameworks you chose only, and rewrites the file on every run. Your own vocabulary stays in Types/code-types.md, which tg never overwrites.
Choose and install with tg init
Run tg init in a terminal. After the agents and the parts, it shows a checklist of the six frameworks:
- Detects: the frameworks it finds are ticked and marked found.
- Recommends: if it finds none, it ticks one and shows why. A project with existing code gets OpenSpec, because change proposals with deltas suit an evolving codebase. A new project gets Spec Kit, because feature specs, plans and tasks suit greenfield work. Tick ADRs as well if you want decision records next to either.
- Installs: for each ticked framework that is not set up yet,
tg initoffers to run the framework's own installer. Each option shows its exact command, and you can always skip.
| Framework | What tg init runs |
|---|---|
| OpenSpec | openspec init --tools <your agents>, or once with npx -y @fission-ai/openspec@latest, or after npm install -g @fission-ai/openspec@latest |
| Spec Kit | specify init --here --force --integration <agent>, or once with uvx --from specify-cli specify …, or after uv tool install specify-cli |
| Kiro-style specs | npx -y cc-sdd@latest --claude-skills (in the Kiro IDE, create specs from its Specs panel instead) |
| BMAD | npx -y bmad-method@latest install |
| Get Shit Done | npx -y get-shit-done-cc@latest, in a terminal only, because it asks questions |
| ADRs | No tool: tg writes docs/adr/0001-record-architecture-decisions.md and docs/adr/template.md |
Installers run before tg plans its files, so the skills they write get their tg steps in the same run. That covers Spec Kit's speckit-specify, -plan, -tasks and -implement, cc-sdd's kiro-spec-*, BMAD's story skills, and OpenSpec's propose, apply, archive and explore. Kiro gets an always-included steering file, .kiro/steering/tg.md. The tg-trace skill and the instruction block in CLAUDE.md or AGENTS.md describe only the frameworks you chose.
In scripts and CI nothing is asked and nothing is installed unless you say so:
tg init --spec openspec,adr # wire OpenSpec and ADRs; print installer commands tg init --spec speckit --install-spec # also run the Spec Kit installer tg init --spec none # no spec framework tg init --spec kiro --dry-run # show the diff and the commands, change nothing
Add your own
Most teams can use a format they already have without touching tg's code. Try the routes in this order.
1. Write the requirements in lat.md
Typed docs work today with any Markdown. Give a lat.md file the type Requirement (or Decision) and one section per requirement. Code points at the section, and tg check, tg cypher and the coverage rules for test specs all apply:
--- type: Requirement --- # Payments ## Charge once per order A retried request never charges a card twice. - refines:: [[product#Checkout]]
// @tg: implements:: [[payments#Charge once per order]]
export function pay(orderId: string, card: string) { … }
Use this when your requirements live in a wiki or a tracker today and you want them next to the code. You keep tg's graph and checks. What you give up is tg trace's per-requirement report, which reads only spec frameworks.
2. Use a supported format as the target
If your tool exports or generates Markdown, have it write one of the formats above. The Kiro format is the easiest to emit: a ### Requirement N heading, a **User Story:** line and a numbered list under #### Acceptance Criteria, in .kiro/specs/<feature>/requirements.md. For decisions, any numbered Markdown file with a status: line in a folder named in .adr-dir is read as an ADR.
3. Add a reader to tg
A framework with its own files and its own ids deserves its own reader. A reader is a small, pure function in packages/core, and the pull request touches six places:
- Register it. Add an entry to
SPEC_FRAMEWORKSinpackages/core/src/openspec/frameworks.ts(id, display name, scheme<id>:, andflat: truewhen records are addressed without a group, as ADRs are), and add the id to theSpecFrameworkIdtype. - Locate its files. Teach
locateSpecFilethe path pattern, and return the group: the folder that becomes the middle of the id, such as a feature or epic. - Parse them. Write
parse<Name>(path, text, group)and call it fromparseSpecFile. It returns oneSpecRequirementper requirement, with:name: the id the framework already uses;aliases: titles and short forms;labels: framework types such asStory;props: priority, status and the like;scenarios: acceptance criteria;status:pendingorretiredwhen the format says so.
- Wire up the CLI. In
packages/cli/src/specs.mts:- add a
SPEC_SETUPSentry: the line shown in the wizard, example ids, and the skill and command names to patch per stage; - add a marker to
detectSpecs; - add the file list to
specFiles; - add install commands to
installOptions; - add the ontology types to
FRAGMENTS.
packages/cli/templates/specs/<id>.md. - add a
- Specify and test it. Add a requirement for the reader to the
spec-frameworkscapability in an OpenSpec change, with scenarios taken from a real file of that framework. Putverifieson each test, and add a section per test tolat.md/tests/spec-frameworks.md. - Check.
npm test,tg check,tg ontology checkandtg trace spec-frameworks --gapsmust all pass.
A reader for a hypothetical rfcs/0012-title.md format, with REQ-1: lines, looks like this:
// @tg: implements:: [[openspec:spec-frameworks#RFC reader]]
export function parseRfc(path: string, text: string, group: string): SpecRequirement[] {
const out: SpecRequirement[] = [];
for (const [line, i] of prose(text)) { // skips fenced code
const m = /^\s*[-*]?\s*(REQ-\d+):\s*(.+)$/.exec(line);
if (m) out.push(requirement('rfc', group, m[1]!, path, i + 1, { text: strip(m[2]!), labels: ['RfcRequirement'] }));
}
return out;
}
Good readers follow five rules:
- Keep the framework's own ids and make titles aliases, because people retitle more often than they renumber.
- Skip lines you don't understand instead of failing.
- Keep the base label (
Requirement,Scenario,Decision) and add yours beside it. - Retire, don't drop: a record the format marks obsolete stays in the trace as retired.
- Never read a folder another tool might own without that tool's own marker. Spec Kit's
specs/is read only when.specify/exists.
Not ready to write the reader yourself? Open an issue with a real example file and where your tool writes it.