Docs · CLI · Spec frameworks

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.

FrameworkDetected byFiles tg readsIds
OpenSpecopenspec/openspec/specs/<capability>/spec.md and the deltas of open changesopenspec:auth#Login, openspec:auth#Login#Valid password
GitHub Spec Kit.specify/specs/<feature>/spec.mdspeckit: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.mdkiro: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 filesbmad:prd#FR-1, bmad:epic-1#Story 1.2#AC1
Get Shit Done.planning/.planning/REQUIREMENTS.mdgsd:requirements#AUTH-01
Architecture decision records (MADR, Nygard / adr-tools, log4brains)A numbered record in docs/adr, doc/adr, docs/decisions, …; .adr-dir; .log4brains.ymlNNNN-title.md in that folderadr:0003 (also adr:3, the slug or the title)

Lookups ignore case and extra spaces, and aliases resolve:

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:

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:

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:

FrameworkWhat tg init runs
OpenSpecopenspec init --tools <your agents>, or once with npx -y @fission-ai/openspec@latest, or after npm install -g @fission-ai/openspec@latest
Spec Kitspecify init --here --force --integration <agent>, or once with uvx --from specify-cli specify …, or after uv tool install specify-cli
Kiro-style specsnpx -y cc-sdd@latest --claude-skills (in the Kiro IDE, create specs from its Specs panel instead)
BMADnpx -y bmad-method@latest install
Get Shit Donenpx -y get-shit-done-cc@latest, in a terminal only, because it asks questions
ADRsNo 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:

  1. Register it. Add an entry to SPEC_FRAMEWORKS in packages/core/src/openspec/frameworks.ts (id, display name, scheme <id>:, and flat: true when records are addressed without a group, as ADRs are), and add the id to the SpecFrameworkId type.
  2. Locate its files. Teach locateSpecFile the path pattern, and return the group: the folder that becomes the middle of the id, such as a feature or epic.
  3. Parse them. Write parse<Name>(path, text, group) and call it from parseSpecFile. It returns one SpecRequirement per requirement, with:
    • name: the id the framework already uses;
    • aliases: titles and short forms;
    • labels: framework types such as Story;
    • props: priority, status and the like;
    • scenarios: acceptance criteria;
    • status: pending or retired when the format says so.
  4. Wire up the CLI. In packages/cli/src/specs.mts:
    • add a SPEC_SETUPS entry: 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.
    Then write the skill section packages/cli/templates/specs/<id>.md.
  5. Specify and test it. Add a requirement for the reader to the spec-frameworks capability in an OpenSpec change, with scenarios taken from a real file of that framework. Put verifies on each test, and add a section per test to lat.md/tests/spec-frameworks.md.
  6. Check. npm test, tg check, tg ontology check and tg trace spec-frameworks --gaps must 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:

Not ready to write the reader yourself? Open an issue with a real example file and where your tool writes it.