# OpenSpec integration
This repository uses OpenSpec (openspec.dev) alongside tix, and tix treats OpenSpec the
same way it treats Spec Kitty: `tix init-agents` detects the framework and generates
task-tracking guidance so autonomous agents mirror OpenSpec changes and their tasks onto
the tix board. See [`docs/spec-kitty-integration.md`](spec-kitty-integration.md) for the
Spec Kitty side of the same story and the tix ↔ framework detection model in general.
## Detection
`tix init-agents` detects OpenSpec with a **single deterministic existence check**: an
`openspec/` directory at the resolved project root (`src/commands/agents.rs` →
`has_openspec`). It does not read OpenSpec config, probe markers, or make network calls —
the same zero-cost, deterministic principle as the `.kittify/` check documented in
`docs/spec-kitty-integration.md` §6.1. Both checks are independent, so a project can detect
neither, either, or both frameworks.
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 OpenSpec (via openspec/)
```
Spec Kitty and OpenSpec lines are independent and printed in that fixed order (the helper
is `detection_report(detected) -> Vec<String>` in `src/commands/agents.rs`); with neither
framework present no detection line is printed, keeping the no-framework output identical
to before.
## The generated AGENTS.md section
When `openspec/` is present, the `<!-- tix:start -->` … `<!-- tix:end -->` block written by
`tix init-agents` also contains a `### Tracking OpenSpec work with tix` section, placed
between the `### Updating` and `### Storage layout` headings. It reads:
```
### Tracking OpenSpec work with tix
This project uses OpenSpec (detected via `openspec/`). Use tix to track its changes and tasks:
- Filing an OpenSpec change/task → `tix create --title "<change>: <task>" --labels openspec`
- Add the change's proposal/spec/plan to the issue markdown body.
- Opening an issue → `tix list --status "todo"`
- Marking a task done → `tix move <number> done` (interactive); the commit hash is
optional — pass `tix move <number> done --commit <hash>` to record it non-interactively
- Commenting on a task issue → `tix edit <number>` (body/comment section is plain markdown)
- Linking related change/task issues → `tix link <a> <b>` (symmetry is maintained; drop it with `tix unlink <a> <b>`)
- Populating `files` with the change's spec path → `tix edit <number> --files "<path>"`
```
The section is a frozen, byte-deterministic constant (`OPENSPEC_SECTION`), and each
framework's section is gated independently: with both `.kittify/` and `openspec/` present
the block carries both sections (Spec Kitty first); with neither, the block is the
byte-identical golden baseline.
## The tracking workflow (`openspec` label convention)
The generated section instructs agents to track OpenSpec work as tix issues:
1. **File a task as a tix issue** labeled `openspec`
(e.g. `tix create --title "<change>: <task>" --labels openspec`), reproducing the
change's proposal/spec/plan (from `openspec/changes/<change>/tasks.md` and
`specs/<capability>/spec.md`) in the issue body.
2. **Open the board** with `tix list --status "todo"`.
3. **Mark done with the landing commit**: `tix move <number> done --commit <hash>`
(non-interactive; the interactive form prompts).
4. **Comment** for review findings: `tix edit <number>`.
5. **Relate issues** with `tix link <a> <b>` — the change issue and the task issues that
belong to it link to each other symmetrically (back-references are written on both
files; `tix unlink <a> <b>` drops a pair). The MCP `link_issue` tool does the same for
agents.
6. **Record the governing spec paths** with `--files` (create seeds, edit replaces — an
empty value clears): `tix edit <number> --files "openspec/changes/<change>/tasks.md"`.
The TUI detail view renders `files` as clickable hyperlinks to those paths.
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), and mirror every OpenSpec change's tasks
plus review findings as their own `openspec`-labeled issues, marking them `done --commit
<hash>` when the change/task lands.
## Marker boundary and hand-maintained content
Like the Spec Kitty section, the generated OpenSpec section lives **inside** the tix markers,
so `tix init-agents` re-runs replace only between them and never touch unrelated AGENTS.md
content. Richer hand-maintained guidance (the REQUIRED `tix mcp` / mirroring rules above)
lives *outside* the markers — the same layout used for the Spec Kitty guidance in this
repo. See `docs/spec-kitty-integration.md` §6.3 for the operational note about keeping
marker-wrapped vs. hand-maintained sections consistent.
## Reference
- `src/commands/agents.rs` — `Detected` detection, `OPENSPEC_SECTION`, `build_section`.
- `tests/agents.rs` — integration tests for the openspec detection states.
- [`docs/spec-kit-integration.md`](spec-kit-integration.md) — the GitHub Spec Kit
analog (`speckit` label, `.specify/` detection, subissue workflow).
- [`openspec.dev`](https://openspec.dev) — the OpenSpec spec-driven workflow.