# GitHub Spec Kit integration
This repository can carry [GitHub Spec Kit](https://github.com/github/spec-kit)
(the `specify` CLI, `specify-cli`) alongside tix. tix treats Spec Kit the same way
it treats Spec Kitty and OpenSpec: `tix init-agents` detects the framework and
generates task-tracking guidance so autonomous agents mirror Spec Kit work onto
the tix board. See [`docs/spec-kitty-integration.md`](spec-kitty-integration.md)
for the detection model in general, and
[`docs/openspec-integration.md`](openspec-integration.md) for the first
analogous third-party framework.
## Detection
`tix init-agents` detects Spec Kit with a **single deterministic existence
check**: a `.specify/` directory at the resolved project root
(`src/commands/agents.rs` → `has_spec_kit`). It does not read Spec Kit config,
probe markers, or make network calls — the same zero-cost principle as the
`.kittify/` and `openspec/` checks. The three checks are independent, so a
project can detect neither, any one, or all three.
`.specify/` is uniquely Spec Kit's own marker: the `specify` CLI resolves the
project root by searching upward for it (`SPECIFY_INIT_DIR` documents the root as
"the directory *containing* `.specify/`"). No other tool uses the name, so the
check does not collide.
When a framework is detected, `tix init-agents` prints a **stdout detection
line** before its status messages, mirroring the generated section one-to-one:
```
Detected Spec Kit (via .specify/)
```
The three framework lines are printed in the fixed order Spec Kitty, OpenSpec,
Spec Kit (the helper is `detection_report(detected) -> Vec<String>`); with no
framework present no detection line is printed, keeping the no-framework output
identical to before.
## The generated AGENTS.md section
When `.specify/` is present, the `<!-- tix:start -->` … `<!-- tix:end -->` block
written by `tix init-agents` also contains a `### Tracking Spec Kit work with
tix` section, placed between the `### Updating` and `### Storage layout`
headings (after the Spec Kitty and OpenSpec sections when those are also
present). It reads:
```
### Tracking Spec Kit work with tix
This project uses GitHub Spec Kit (detected via `.specify/`). Use tix to track its tasks:
- Filing a Spec Kit task/work package → `tix create --title "<feature>: <task>" --labels speckit`
- Add the feature's spec/plan/task context in the issue markdown body.
- Opening an issue → `tix list --status "todo"`
- Marking a task done → `tix move <number> done` (interactive) or
`tix move <number> done --commit <hash>` (non-interactive)
- Commenting on a task issue → `tix edit <number>` (body/comment section is plain markdown)
- ... REQUIRED tix-mcp / mirroring guidance ...
```
The section is a frozen, byte-deterministic constant (`SPEC_KIT_SECTION`), and
each framework's section is gated independently: with all three roots present
the block carries all three sections in order; with none, the block is the
byte-identical golden baseline.
## The label: `speckit`, not `spec-kit`
The framework label is **`speckit`** (no hyphen) deliberately. `spec-kit` would
be a **prefix** of the existing `spec-kitty` label, so `grep spec-kit` would
match issues from both frameworks and the two labels ("spec kit" vs "spec kitty")
would be one keystroke apart. `speckit` is a substring of neither and matches the
framework's own agent-skill prefix (`/speckit-*`).
## The tracking workflow (`speckit` label convention)
The generated section instructs agents to track Spec Kit work as tix **issues and
subissues**:
1. **One parent issue per feature**, labeled `speckit`:
`tix create --title "<feature>" --labels speckit`.
2. **Every task as a child issue.** File each task in
`specs/NNN-<feature>/tasks.md` as its own subissue:
`tix create --title "<task>" --parent <feature-issue>`. Inspect the
decomposition with `tix parent children <feature-issue>`.
3. **Bugs and assessments each get an issue.**
`.specify/bugs/<slug>/` and `.specify/assessments/<slug>/` are mirrored as
their own `speckit`-labeled issues.
4. **Record findings and progress on the issue as you work it.** When you run
`/speckit-analyze` (or otherwise assess a task), append its findings and every
decision taken to that issue's comments (`tix edit <number>`, or MCP
`comment_on_issue`), and keep the status moving — `tix move <number> "in
progress"` while in flight, `done --commit <hash>` when it lands.
5. **Mark done with the landing commit**: `tix move <number> done --commit <hash>`.
Per the repo's AGENTS.md rules, agents always use `tix mcp` to create and move
these issues (never hand-edited files or CLI prompts).
## Artifact → tix mapping
| Spec Kit artifact on disk | tix mirror |
| --- | --- |
| `specs/NNN-<feature>/tasks.md` tasks | one `speckit` issue per task, child of the feature's parent issue |
| feature itself | one parent `speckit` issue |
| `.specify/bugs/<slug>/` (read the bug-fix extension `assess → fix → test` reports) | one `speckit` issue per bug slug |
| `.specify/assessments/<slug>/` (idea assessment `intake → … → decide`) | one `speckit` issue per assessment slug |
## Relationship to `/speckit-taskstoissues`
Spec Kit ships `/speckit-taskstoissues`, which converts `tasks.md` into GitHub
issues. It is **GitHub-only**: it requires a GitHub `origin` remote and the
GitHub MCP tools, and (as of upstream issue #2968) creates duplicates with no
deduplication. It is **not** the tix board and does not know tix exists. The
generated AGENTS.md section therefore tells agents to mirror to tix instead;
`/speckit-taskstoissues` remains opt-in for teams that also want GitHub issues.
Agent-driven mirroring through AGENTS.md is one half of the integration; the
deterministic command below is the other.
## The first-class mirror: `tix import --target speckit`
tix ships a deterministic, idempotent mirror of the same artifacts:
```bash
tix import --target speckit
```
It reads the Spec Kit project root (the directory holding `tix.toml`, where
`.specify/` lives) and creates, through the same create core as `tix create`:
| `specs/NNN-<feature>/` | one **parent** issue; `files` records the feature dir |
| each `T0xx` task in that feature's `tasks.md` | one **child** issue (`parent:` set); `files` records `specs/NNN-<feature>/tasks.md#T0xx` |
| `.specify/bugs/<slug>/` | one issue; `files` records the directory; body is the concatenated report |
| `.specify/assessments/<slug>/` | one issue; `files` records the directory; body is the concatenated report |
Every created issue carries the `speckit` label. The **source path in `files` is
the identity**: a re-run builds a `source path -> issue` map from every existing
issue and skips what it already finds, so the command is safe to run repeatedly
and only creates what is new (a single issue number is never assigned twice). The
landing column follows the same `--triage-policy` (`entry | remote`; the default
routes to the inbox when the project has a `[triage]` section, exactly like the
remote import targets), so a Spec Kit project with an inbox lands its issues in
triage like any other import.
The MCP `import_issues` tool accepts `"target": "speckit"` and runs the same
core.
## Reference
- `src/speckit/mod.rs` — discovery (`discover`), the task parser (`parse_tasks`),
and the mirror engine (`mirror` / `run` / `import_core`).
- `src/commands/agents.rs` — `Detected` detection, `SPEC_KIT_SECTION`,
`build_section`.
- `tests/agents.rs`, `tests/speckit.rs` — detection and mirror integration tests.
- [github/spec-kit](https://github.com/github/spec-kit) — upstream repository
and [docs](https://github.github.com/spec-kit/).