/agent-spec-intent-compiler

name: agent-spec-intent-compiler
description: Use when converting PRD or issue prose into KLL requirements, running the intent compiler plan, or reverse-interviewing a human to resolve requirement ambiguity before task spec generation.

Agent Spec Intent Compiler

> **Version:** 1.0.0 | **Last Updated:** 2026-08-14 | **Tracks:** agent-spec 1.4.0

Use this skill when a user wants to move from raw PRD/issue prose to governed KLL requirements and task specs.

Routing: What You Hold, Where It Goes

Before writing anything, route the artifact. This table copies `knowledge/standards/operational/id-registry.md` — the registry is the authority, this copy is checked against it in CI.

| You hold | Directory | Id prefix | Scaffold | |---|---|---|---| | A debate: should we do this, and why | `knowledge/proposals/` | `LEP-` | `agent-spec knowledge new proposal LEP-NNN` | | A settled architectural ruling | `knowledge/decisions/` | `ADR-` | `agent-spec knowledge new decision ADR-NNN` | | An obligation the system must satisfy | `knowledge/requirements/` | `REQ-` | `agent-spec knowledge new requirement REQ-NNN` | | An executable, verifiable task contract | `specs/` | `task-` | `agent-spec init --level task` |

HARD GATE: when the workspace has a `knowledge/requirements/` corpus, do NOT write a task contract without `satisfies: [REQ-*]` — the orphan-spec lint diagnoses the jump. "This is just a small task" and "I'll link it later" are the rationalizations that produced orphan contracts before; route first, then write.

Rules

• The CLI remains deterministic and model-free.
• Raw source belongs in `docs/`.
• Machine-consumable truth belongs in `knowledge/requirements/*.md`.
• Do not silently invent missing requirements. Emit or ask clarification questions.
• Do not treat a model inference as accepted; only human-confirmed answers may change KLL truth.
• Every generated requirement must include `## Source Trace`.
• Open questions stay in `## Open Questions` until answered by the human.
• For agent-spec's own development, dogfood this workflow on the repository's own KLL requirement and task spec before presenting fixtures as sufficient proof.
• Treat KLL roots as compiler trust boundaries: do not bypass unsafe-id, strict-frontmatter, kind-directory, missing-root, or symlink diagnostics.
• Read the plan as a cross-layer DAG: requirement nodes lower to work units, work units satisfy spec nodes, and spec dependencies remain explicit edges.

Workflow

1. Read the raw PRD or issue. 2. Draft Candidate Requirement Block entries using the PRD Intake Output Contract below. 3. Ask for human confirmation before importing candidate blocks into KLL. 4. Run `agent-spec requirements import --from docs/prd.md --out knowledge/requirements` only after the candidate blocks are accepted. 5. Run `agent-spec lint-knowledge --knowledge knowledge --gate`. 6. Run `agent-spec requirements plan --knowledge knowledge --specs specs --format json --gate`. 7. Run `agent-spec requirements test-obligations --knowledge knowledge --specs specs --format json --out .agent-spec/test_obligations.json`. 8. Run `agent-spec requirements worktrees --knowledge knowledge --specs specs --base main --path-prefix ../agent-spec-worktrees --out .agent-spec/worktrees.json`. 9. After code grounding or a change, run `agent-spec requirements affected` and save the provider-neutral intent-impact report. 10. Run `agent-spec requirements affected-bundle` to apply the risk A/B/C evidence policy and select executable provider configs, justified checks, explicit tests, gates, guidance, and skill receipts; generated selector slugs remain non-authoritative candidates. 11. After lifecycle and quality execution, run `agent-spec requirements affected-record` with the same stable `run_id` to store the report, optional bundle, and normalized outcomes in trace ledger v2. 12. When debugging, run `agent-spec requirements replay REQ-*`, `requirements explain-failure REQ-*`, or `requirements trace-graph REQ-*`; all three read stored lifecycle and affected evidence only and never rerun providers, tools, skills, or models. 13. Run `agent-spec requirements questions --knowledge knowledge --specs specs --format json`. 14. Use the Reverse Interview Loop below to ask only the emitted blocking questions, grouped by requirement id. 15. Use Answer Integration below to write accepted answers back into KLL requirements as requirement clauses, scenarios, source trace entries, or resolved open questions. 16. Generate task specs with `satisfies: [REQ-*]`. 17. Run `agent-spec lifecycle`, `agent-spec guard`, and `agent-spec trace`. 18. For agent-spec itself, confirm dogfood evidence with `requirements replay`, `requirements explain-failure`, and `requirements trace-graph` for the repository requirement id.

The skill text must preserve these exact terms for documentation tests: QA class, state-machine, reverse interview, active specs, dogfood.

PRD Intake Output Contract

Natural-language PRD intake is an AI-assisted drafting step, not a CLI parser mode. The output is a set of Candidate Requirement Block entries that a human can review and then import.

Each Candidate Requirement Block must include:

• `id`: stable `REQ-*` id proposed by the agent.
• `title`: short title from the user-facing requirement, not a filename slug.
• `tags`: domain tags when the source text supports them.
• `source`: original PRD, issue, ticket, or document path.
• `source excerpt`: the smallest quoted or paraphrased source span that justifies the requirement.
• `confidence`: `high`, `medium`, or `low`, based on how directly the source states the requirement.
• `## Problem`: why the requirement exists.
• `## Requirements`: one or more normative clauses using MUST, MUST NOT, SHOULD, or MAY.
• `## Scenarios`: at least one executable scenario for each implementation-bearing leaf.
• `## Dependencies`: explicit requirement ids, or `None.`
• `## Source Trace`: source path plus source excerpt referenc