@imix-js/taproot 0.2.0

package/skills/grill-me.md

@@ -0,0 +1,65 @@
+# Skill: grill-me
+
+## Description
+
+Interview the user relentlessly about a plan or design, resolving each decision branch with a recommendation until shared understanding is reached.
+
+Based on Matt Pocock's `grill-me` skill (MIT licensed, https://github.com/mattpocock/skills/blob/main/grill-me/SKILL.md).
+
+## Inputs
+
+- `plan` (required): The plan, design decision, or concept to explore. Can be a few words or a paragraph — the skill will sharpen it.
+
+## Steps
+
+1. Identify the key decision branches in the plan — the points where different choices lead to meaningfully different outcomes. These become the agenda for the session. If the plan relates to an existing taproot artefact, read the relevant `usecase.md` or `intent.md` now (and `taproot/OVERVIEW.md` if you need the broader hierarchy context).
+
+3. For each unresolved branch, in dependency order:
+
+   a. **Ask the question** — one question at a time, never more
+   b. **Immediately provide your recommended answer** — the developer should react to your recommendation, not start from scratch. Say: "My recommendation: [answer]. What do you think?"
+   c. If the question can be answered by exploring the codebase or hierarchy, do that instead of asking. Present what you found: "I checked `<path>` — it already handles X, so this resolves to Y."
+   d. When the developer responds: accept, refine, or push back on their answer. If their answer is vague or incomplete, probe once more before marking the branch resolved.
+   e. Mark the branch resolved and move to the next.
+
+4. Continue until all identified branches are resolved or explicitly deferred (developer says "skip this for now" — mark it deferred with their reason).
+
+5. If the plan is too vague to extract decision branches, ask one grounding question first: "What specifically are you trying to decide? What outcome are you aiming for?" Then proceed from step 2.
+
+6. Present a decision synthesis:
+
+   ```
+   ## Decisions resolved
+   - [branch]: [chosen path] — [reason]
+
+   ## Deferred
+   - [branch]: deferred — [reason / what would trigger revisiting]
+
+   ## Constraints surfaced
+   - [constraint or risk that emerged]
+   ```
+
+   Then present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-ineed "<clarified requirement>"` — route the sharpened requirement into the hierarchy
+   [B] `/tr-behaviour <path>/` — write the spec now that the design is clear
+
+## Output
+
+A structured decision synthesis with every branch resolved or explicitly deferred, and a recommended next action. When called from another skill (embedded mode), the synthesis is passed back to the calling skill as structured input rather than presented as a standalone report.
+
+## CLI Dependencies
+
+None — pure agent skill.
+
+## Notes
+
+- **"Relentless"** means the agent does not drop a branch because the developer gives a short answer. Push until the branch is genuinely resolved or explicitly deferred with a stated reason.
+- **Always recommend first.** The session is a dialogue about recommendations, not a blank-slate interview. Developers can agree, refine, or reject — but they should never have to start from scratch.
+- **One question at a time.** Batching questions lets the developer give vague omnibus answers. One question forces a specific answer on each branch.
+- **Explore the codebase proactively.** Many questions about existing behaviour, architecture, or conventions can be answered by reading files — do this instead of asking.
+- **Distinction from `/taproot:review`** (formerly `tr-grill`): `tr-review` stress-tests a finished taproot artefact from an adversarial reviewer's perspective. `tr-grill-me` interviews the developer *before* the artefact is written, to sharpen the thinking that goes into it.
+- **Called by other skills:** `/taproot:ineed` delegates to `grill-me` on the "Go deeper [A]" path. When called in embedded mode, output the synthesis summary to the calling skill context rather than presenting it to the user.

package/skills/guide.md

@@ -0,0 +1,118 @@
+# Skill: guide
+
+## Description
+
+Present a tailored onboarding guide for the Taproot workflow. Explains what Taproot is, the three-layer hierarchy, available slash commands, CLI tools, and where to start. Read-only — no files are created or modified.
+
+## Inputs
+
+None required. The skill reads current project state to tailor the guide.
+
+## Steps
+
+1. Check whether `taproot/` exists in the project root. If it does, check whether any intent directories exist (subdirectories containing an `intent.md` file). Note whether `taproot/OVERVIEW.md` exists.
+
+2. Present the following guide, tailored to current state:
+
+---
+
+**Taproot** is a requirements traceability system that links business intent to code through a three-layer hierarchy.
+
+### The Three-Layer Hierarchy
+
+```
+taproot/
+└── <intent>/          # Why — business goal, stakeholders, success criteria
+    └── <behaviour>/   # What — use cases, acceptance criteria
+        └── <impl>/    # How — code, tests, traceability records
+```
+
+Every folder is identified by its marker file: `intent.md`, `usecase.md`, or `impl.md`.
+
+### Typical Workflow
+
+```
+ineed → intent → behaviour → implement → trace → status
+```
+
+1. **ineed** — route a requirement to the right place; runs structured discovery for vague ideas
+2. **intent** — define a business goal with stakeholders and success criteria
+3. **behaviour** — specify use cases under an intent (or decompose an intent first)
+4. **implement** — write code, tests, and an `impl.md` traceability record
+5. **trace** — link recent commits back to existing taproot documents
+6. **status** — health dashboard: coverage, orphans, stale specs
+
+### Slash Commands (AI-driven content creation)
+
+| Command | Purpose |
+|---|---|
+| `/tr-ineed` | Route a requirement; runs structured discovery for vague ideas |
+| `/tr-bug` | Diagnose a defect through 5-Why root cause analysis and delegate to the right fix skill |
+| `/tr-intent` | Create or refine a business intent document |
+| `/tr-behaviour` | Define use cases under an intent or another behaviour |
+| `/tr-decompose` | Break an intent into multiple behaviours |
+| `/tr-implement` | Implement a behaviour with code, tests, and `impl.md` |
+| `/tr-trace` | Navigate the hierarchy in any direction — file to intent (bottom-up), intent to code (top-down), lateral across siblings |
+| `/tr-status` | Generate a health dashboard for the hierarchy |
+| `/tr-review` | Stress-test a spec with adversarial questions |
+| `/tr-review-all` | Run review across an entire subtree |
+| `/tr-grill-me` | Interview the user relentlessly to sharpen a plan or design |
+| `/tr-research` | Research a domain or technical subject before speccing — local resources, web search, expert grilling |
+| `/tr-sweep` | Apply a uniform task to a filtered set of hierarchy files — enumerate, confirm, then call `taproot apply` |
+| `/tr-commit` | Execute the full commit procedure: classify type, run proactive gates, resolve DoD/DoR conditions, stage, and commit |
+| `/tr-refine` | Update a behaviour spec based on implementation learnings |
+| `/tr-promote` | Move discoveries from implementation back upstream |
+| `/tr-guide` | Show this guide |
+
+### CLI Commands (validation and reporting)
+
+| Command | Purpose |
+|---|---|
+| `taproot validate-structure` | Check folder and file naming conventions |
+| `taproot validate-format` | Check document frontmatter, required fields, and cross-link sections |
+| `taproot check-orphans` | Find folders missing their marker files |
+| `taproot coverage` | Show implementation coverage across the hierarchy |
+| `taproot sync-check` | Detect specs that may be stale relative to code |
+| `taproot overview` | Regenerate `taproot/OVERVIEW.md` summary |
+| `taproot dod [impl-path]` | Run Definition of Done checks; mark impl complete if all pass |
+| `taproot commithook` | Pre-commit gate: classifies staged files and runs DoR or DoD as appropriate |
+| `taproot update` | Refresh agent adapters, skills, and cross-link sections across the hierarchy |
+| `taproot init` | Initialize Taproot in a project |
+
+### Rule of Thumb
+
+> **Slash commands for content, CLI for validation.**
+>
+> Use `/tr-*` commands when you want the AI to create or update documents.
+> Use `taproot` CLI commands to validate, report, and check structural integrity.
+
+---
+
+3. After presenting the guide, add a context-aware note:
+
+   - **If `taproot/OVERVIEW.md` exists**: "Your project has an overview at `taproot/OVERVIEW.md` — read it for a summary of current intents and their status."
+   - **If intents exist but no OVERVIEW.md**: "Your project has existing intents. Run `taproot overview` to generate a summary, or use `/tr-status` for a full health report."
+   - **If no intents exist yet** (empty or missing `taproot/`): "This looks like a new project. A good starting point: describe your problem to `/tr-ineed`, or jump straight to `/tr-intent` if you already know what you want to build."
+
+4. Close with context-aware guidance:
+
+   Nothing obvious next — whenever you're ready:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-ineed` — capture your first (or next) requirement
+   [B] `/tr-status` — see the current project health at a glance
+
+## Output
+
+A formatted guide presented in the conversation. No files are created or modified.
+
+## CLI Dependencies
+
+None.
+
+## Notes
+
+- This skill is read-only. It reports, it does not modify.
+- The guide is intentionally self-contained — it can be understood without prior Taproot knowledge.

package/skills/implement.md

@@ -0,0 +1,149 @@
+# Skill: implement
+
+## Description
+
+Implement a behaviour spec: write the code, write the tests, create the `impl.md` traceability record, and commit with the conventional tag format. The spec is the contract — code must satisfy it, not redefine it.
+
+## Inputs
+
+- `path` (required): Path to the behaviour folder containing `usecase.md` to implement.
+- `name` (optional): Slug for the implementation folder (e.g., `rest-api`, `background-job`). If omitted, derive from the implementation approach chosen.
+
+## Steps
+
+1. Read `<path>/usecase.md` thoroughly. Understand:
+   - The Actor and what they initiate
+   - Every step in the Main Flow
+   - Every Alternate Flow and its trigger condition
+   - Every Error Condition and its expected system response
+   - All Postconditions — these are the acceptance test targets
+
+2. Read any existing implementation folders under `<path>/`. Understand what is already built to avoid duplication and to understand the existing architecture.
+
+3. Walk up the hierarchy: read the parent `intent.md` to understand the broader goal. This context should inform design decisions (e.g., if the intent has a constraint about performance, that should influence implementation choices).
+
+4. **Pattern check + plan mode.** Before proposing the plan: if `.taproot/docs/patterns.md` exists, scan the behaviour description and any design notes for semantic matches. Match signals:
+   - "applies to all implementations / cross-cutting concern" → `check-if-affected-by`
+   - "enforce a rule on all future work" → `check-if-affected-by`
+   - "keep a file in sync / update X on every change" → `check-if-affected: X`
+
+   If a match is found, surface it before the plan:
+   > "Before the plan — this looks like it could use the **`<pattern-name>`** pattern rather than a custom implementation. See `.taproot/docs/patterns.md`."
+   > **[A] Use the pattern** — apply it via `.taproot/settings.yaml` instead of writing source code
+   > **[B] Continue with implementation** — the custom implementation is intentional
+
+   Then **propose the implementation plan:**
+   - Which files to create or modify (with brief rationale for each)
+   - Which tests to write, mapped to specific UseCase steps and postconditions
+   - Any design decisions that need to be made (with options and recommendation)
+   - The implementation folder slug and path
+
+   Present the plan. Do not proceed to writing code until the user approves.
+
+5. Create the implementation folder `<path>/<impl-slug>/` and write `impl.md`:
+   - **Behaviour**: relative path to `../usecase.md`
+   - **Design Decisions**: record every non-obvious choice made during implementation, with the reason
+   - **Source Files**: list every file created or significantly modified, with a one-line description of its role
+   - **Commits**: leave placeholder — will be filled by `taproot link-commits` after commit
+   - **Tests**: list every test file, with a brief description of what scenarios it covers
+   - **Status**: `in-progress`
+
+5a. Update the parent `usecase.md`'s `## Implementations <!-- taproot-managed -->` section:
+    - Read `<path>/usecase.md`.
+    - If the `## Implementations` section does not exist, insert it immediately before `## Status` (or append at end of file if `## Status` is absent), with the heading `## Implementations <!-- taproot-managed -->`.
+    - Derive the link title from the first `# Heading` line of the new `impl.md`; strip any type prefix (e.g. `# Implementation: Foo` → `Foo`). Fall back to the folder slug if no heading is found.
+    - Append `- [<Title>](./<impl-slug>/impl.md)` to the section if the link is not already present.
+    - If the behaviour `**State:**` is `specified`, advance it to `implemented` and update `**Last reviewed:**` to today.
+    - Write the updated `usecase.md`. Stage it together with `impl.md` for the declaration commit.
+
+6. **Declaration commit** — commit `impl.md` and any `usecase.md` link-section update together (no source files):
+
+   Before committing:
+   - Read `.taproot/settings.yaml` and note the `definitionOfReady` conditions — these are the checks the hook will run. If the file has no `definitionOfReady` section, only baseline DoR checks run.
+   - There is no standalone `taproot dor` command — DoR runs automatically via the pre-commit hook when impl.md is staged without source files (this is a **declaration commit**). Resolve any agent-driven DoR conditions (e.g. `check-if-affected-by`) in impl.md under `## DoR Resolutions` before staging.
+
+   ```
+   taproot(<intent-slug>/<behaviour-slug>/<impl-slug>): declare implementation
+   ```
+   If DoR fails, fix the spec or add the missing DoR resolution before proceeding — do not bypass the hook.
+
+7. After the declaration commit, implement:
+   a. Write the source code files
+   b. Write the tests — each test should be traceable to a specific UseCase step, postcondition, error condition, or alternate flow trigger. Name tests descriptively.
+   c. Verify the tests pass
+
+8. Run `taproot dod <impl-path>` to evaluate the Definition of Done. For agent-driven conditions (`check-if-affected`, `document-current`): reason about each, apply any needed changes, then record your resolution with `taproot dod <impl-path> --resolve "<condition>" --note "<reasoning>"`. Re-run until all conditions pass. `taproot dod` marks `impl.md` state `complete` when all pass.
+
+9. **Implementation commit** — commit source files and `impl.md` together:
+
+   Before staging:
+   - This is an **implementation commit** — the hook detects source files tracked by impl.md and requires impl.md to be staged alongside them with a **real diff**. The `--resolve` records written by `taproot dod` in step 8 are that diff. If impl.md shows no diff, re-run `taproot dod` to confirm all conditions are resolved and that status was updated.
+   - Stage impl.md with source files in the same commit — the hook rejects implementation commits missing their traceability record.
+
+   ```
+   taproot(<intent-slug>/<behaviour-slug>/<impl-slug>): <what this commit does>
+   ```
+   The pre-commit hook checks that `impl.md` changed only in the `## Status` and `## DoD Resolutions` sections and re-runs DoD in dry-run mode.
+
+10. Run `taproot link-commits --path <taproot-root>` to update the `impl.md` Commits section with the new hashes.
+
+11. Run `taproot validate-structure --path <taproot-root>`.
+
+12. Run `taproot coverage --path <taproot-root>` to show updated progress.
+
+13. Present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-plan` — surface the next implementable behaviour
+   [B] `/tr-status` — see full project health after this implementation
+
+## Output
+
+- Working source code satisfying the UseCase
+- Tests covering all main flow steps, alternate flows, postconditions, and error conditions
+- A `impl.md` in `<path>/<impl-slug>/impl.md` with all sections filled
+- Two commits: a declaration commit (impl.md alone) and an implementation commit (source + impl.md)
+
+## CLI Dependencies
+
+- `taproot link-commits`
+- `taproot dod`
+- `taproot validate-structure`
+- `taproot coverage`
+
+## Document Format Reference
+
+```markdown
+# Implementation: <Title>
+
+## Behaviour
+../usecase.md
+
+## Design Decisions
+- <Decision: what was chosen and why — reference UseCase requirements>
+
+## Source Files
+- `<path/to/file.ts>` — <what this file does for this implementation>
+
+## Commits
+- `<hash>` — <one-line summary>
+
+## Tests
+- `<path/to/test.test.ts>` — <which UseCase steps/conditions this covers>
+
+## Status
+- **State:** planned | in-progress | complete | needs-rework
+- **Created:** <YYYY-MM-DD>
+- **Last verified:** <YYYY-MM-DD>
+
+## Notes
+<Technical debt, known limitations, future improvements>
+```
+
+## Notes
+
+- If the UseCase has error conditions or alternate flows that are difficult to implement in the current sprint, create the `impl.md` with Status `in-progress` and add a Notes entry listing what is deferred and why.
+- If you discover during implementation that the spec is incomplete or incorrect, **stop and use `/taproot:refine`** to update the spec before continuing. Do not silently diverge from the spec.
+- The commit message tag path should match the impl folder's path relative to the `taproot/` root.

package/skills/ineed.md

@@ -0,0 +1,147 @@
+# Skill: ineed
+
+## Description
+
+Route a natural language requirement to the right place in the taproot hierarchy — clarifying vague requirements through structured discovery before placing and delegating them.
+
+## Inputs
+
+- `requirement` (required): Natural language description of what the system needs to do. Can be vague — the skill will sharpen it through discovery.
+
+## Steps
+
+0. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the stated requirement for semantic matches against the patterns listed there. Match signals:
+   - "apply to all / every implementation / every skill / everywhere" → `check-if-affected-by`
+   - "guide agents / architecture rules / agents should follow / enforce a rule" → `check-if-affected-by`
+   - "enforce documentation / docs must stay current / keep docs accurate" → `document-current`
+   - "every new feature must update X / keep X in sync / always update X" → `check-if-affected: X`
+   - "research before building / check if a library exists / look up how to implement" → research-first (`/tr-research`)
+
+   If a match is found, **interrupt before proceeding**:
+   > "Before I route this — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md` for how to use it."
+   > **[A] Use this pattern now** — I'll guide you through applying it
+   > **[B] Continue as a new requirement** — route and spec it normally
+
+   - **[A]**: read the relevant section of `.taproot/docs/patterns.md` and guide the user through applying the pattern directly. Do not create a new hierarchy entry.
+   - **[B]** or no match: proceed to step 1.
+
+   If multiple patterns match, list all before asking. If `.taproot/docs/patterns.md` is absent, skip silently.
+
+1. **Classify the requirement** — Load `taproot/OVERVIEW.md` if it exists; if not, walk `taproot/` and read each `intent.md`. Use this hierarchy map to decide which path to take:
+
+   - **Bug path** (hand off immediately): Input contains bug-shaped language — "it's broken", "wrong output", "this crashes", "not working", "regression", "it used to work", "unexpected behaviour", or explicit "bug" / "defect" terminology. State: *"That sounds like a bug report rather than a new requirement. I'll hand this off to `/tr-bug` to run root cause analysis."* Call `/tr-bug` with `handoff: true` and the original symptom. Stop — do not route to the hierarchy.
+   - **Quick path** (proceed to Step 4): Clear actor, clear goal, unambiguous outcome. The requirement can be matched against the hierarchy without exploration.
+   - **Discovery path** (proceed to Step 2): Vague, new domain, significant new capability, or unclear what success looks like. The requirement needs to be understood before it can be placed.
+
+   When in doubt, take the discovery path. A well-understood requirement produces a better behaviour spec.
+
+2. **Structured discovery** (discovery path only) — You are a facilitator, not a content generator. Ask one question at a time, build on answers, and don't move to the next phase until you understand the current one.
+
+   Open: *"Before I place this, let me make sure I understand it properly. A few questions."*
+
+   **Phase 1 — Problem space**
+
+   Ask, building on each answer:
+   - "What triggered this need right now — is there a specific incident, user complaint, or gap that surfaced it?"
+   - "Who is blocked or frustrated without this? What do they do instead today?"
+   - "What happens if this is never built — what's the real cost of not having it?"
+
+   **Phase 2 — Actor and persona**
+
+   Ground the requirement in a specific person:
+   - "Walk me through a specific person who would use this. What's their role, and what are they trying to accomplish?"
+   - "Is there more than one type of user involved, with meaningfully different needs?"
+
+   **Phase 3 — Success criteria**
+
+   Elicit concrete, observable outcomes — not "what does done look like" but specific scenarios:
+   - "Give me 2–3 scenarios where this requirement is fully satisfied. Walk me through what happens in each."
+   - "How would you demonstrate this is solved — what would you show in a demo or test?"
+   - "What's the earliest, smallest version that would deliver real value?"
+
+   Push back on vague answers: *"users are happy"* → *"users can complete [action] without [current friction]"*
+
+   **Phase 4 — Scope boundary**
+
+   Establish what's explicitly deferred:
+   - "What's out of scope for now — what would you push to a later version?"
+   - "Are there edge cases you'd consciously defer?"
+
+4. **Synthesise and confirm** (discovery path only) — Produce a structured summary and confirm it before routing:
+
+   > "Here's what I understood:
+   > **Actor:** [specific user persona]
+   > **Need:** [concrete capability]
+   > **So that:** [observable outcome]
+   > **Success looks like:** [scenario 1], [scenario 2], [scenario 3]
+   > **Out of scope:** [deferred items]
+   >
+   > Does that capture it?
+   > **[A]** Go deeper   **[C]** Continue to placement"
+
+   **If [A] — Advanced elicitation:** Apply one or more of the following, then return to synthesis:
+   - *Stress-test assumptions*: "What would have to be true for this requirement to be wrong or unnecessary?"
+   - *Edge cases*: "What happens when [user has no data / is offline / does it twice / does it wrong]?"
+   - *MVP challenge*: "What's the absolute minimum version that proves this works? What could you cut?"
+   - *Alternative approaches*: "Is there a simpler way to solve the underlying problem?"
+   - *Pre-mortem*: "Imagine this was built and nobody used it. What would be the most likely reason?"
+
+   **If [C]:** Proceed to Step 4 with the synthesised requirement as context. This summary will carry forward into `/tr-behaviour` as richer input than a raw one-liner.
+
+4. **Search for near-duplicates** — Scan existing `usecase.md` files under `taproot/`. If a behaviour closely matches the stated (or synthesised) requirement, surface it:
+
+   > "There's already a behaviour `<path>` that covers `<summary>`. Is your requirement the same, a refinement, or a distinct addition?"
+
+   - **Same** → link to existing document and present: **Next:** `/tr-refine <path>` — refine the existing behaviour if the wording needs updating
+   - **Refinement** → call `/taproot:refine <path>` and stop
+   - **Distinct** → continue with placement as a new sibling
+
+5. **Find the best-fit parent** — Match the requirement's domain and goal against existing intents. Consider:
+   - Which intent's goal would be incomplete without this requirement?
+   - Which stakeholders are affected — do they match an existing intent's stakeholders?
+   - Is this a new top-level business goal (needs a new intent) or a behaviour under an existing one?
+
+6. **Resolve ambiguity** — If two or more intents could plausibly own this requirement, ask grill-style questions to resolve:
+   - "Who is the primary stakeholder — an end user, an operator, or a developer?"
+   - "If this was removed, which intent's success criteria would be most affected?"
+   - "Is this really one requirement or two that happen to arrive together?"
+
+   Re-propose placement after each answer.
+
+7. **Propose placement with reasoning** — State your proposed location clearly:
+
+   > "This sounds like it belongs under **`<intent-slug>`** (*`<intent goal>`*) as a new behaviour. Does that feel right?"
+
+   If no suitable parent exists:
+
+   > "This doesn't clearly fit any existing intent — it may need a new one. I'd name it `<proposed-slug>` — *`<proposed goal>`*. Agree?"
+
+   If the developer disagrees: "Which intent feels like the right home? Or should this be a new intent entirely?" Re-propose based on their answer.
+
+8. **Confirm and delegate** — Once the developer confirms placement, call the appropriate skill — carrying the synthesised summary (if discovery was run) as context for the behaviour definition:
+
+   - **New top-level intent needed**: call `/taproot:intent` with the proposed slug and description, then call `/taproot:behaviour` under the new intent
+   - **New behaviour under existing intent**: call `/taproot:behaviour <taproot/<intent-slug>/> "<synthesised requirement>"`
+   - **New sub-behaviour under existing behaviour**: call `/taproot:behaviour <taproot/<intent-slug>/<behaviour-slug>/> "<synthesised requirement>"`
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+**What's next?**
+Delegated to the appropriate skill above.
+
+## Output
+
+Delegates to `/taproot:intent` and/or `/taproot:behaviour`. No files are written directly by this skill. For discovery-path requirements, the synthesis summary produced in Step 3 becomes the input context for the delegated skill.
+
+## CLI Dependencies
+
+None — this skill delegates all writing to other skills.
+
+## Notes
+
+- **Fast path vs discovery path**: The fast path is for requirements that are already clear. When in doubt, take the discovery path — a few extra minutes of elicitation produces a behaviour spec with less need for immediate refinement.
+- **Facilitator mindset**: You are not generating content, you are helping the developer articulate what they already know. Every question should help them think, not just answer.
+- **Discovery produces richer specs**: The synthesis summary from Step 4 carries forward into `/taproot:behaviour`, giving it a structured actor, goal, success criteria, and scope boundary to work from — not just a raw one-liner.
+- **Advanced elicitation** techniques (pre-mortem, MVP challenge, edge cases, alternative approaches) are available via `/taproot:grill-me` — reuse that framing rather than inventing new questions.
+- **Conversational detection**: Detecting a requirement from casual speech without explicit `/tr-ineed` invocation is a Claude Code behaviour — the agent watches for phrases like "we also need...", "the system should...", "I want users to be able to..." and asks "Should I add that to the taproot hierarchy?" before proceeding.
+- `/tr-ineed` is the Claude Code adapter command name for this skill.

package/skills/intent.md

@@ -0,0 +1,104 @@
+# Skill: intent
+
+## Description
+
+Create a new business intent or refine an existing one. An intent captures the "why" and "for whom" — the goal, the stakeholders who care about it, and how you'll know it's been achieved.
+
+## Inputs
+
+- `description` (required unless `path` is given): Natural language description of the goal. Can be vague — the skill will clarify.
+- `path` (optional): Path to an existing `intent.md` to refine rather than create new.
+
+## Steps
+
+### Creating a new intent
+
+1. If the description is vague (under two sentences, or contains words like "improve", "better", "more" without specifics), ask up to three clarifying questions before drafting:
+   - "Who benefits from this, and what specifically changes for them?"
+   - "How would you know in 6 months that this was a success?"
+   - "What is the biggest risk or constraint on achieving this?"
+
+2. Search existing intents under `taproot/` for overlap. Read each `intent.md` found. If a closely related intent exists, show it to the user and ask: "This looks related to existing intent at `<path>`. Should I refine that one, or create a separate intent for a genuinely different goal?"
+
+3. Draft the `intent.md` content:
+   - Title: noun phrase capturing the desired outcome (e.g., "Password Reset Without Support", not "Password Reset Feature")
+   - Stakeholders: at minimum the direct user/actor and the business/product owner; consider: ops, security, compliance, support, third-party integrators
+   - Goal: 1–3 sentences, outcome-focused (what changes in the world), not solution-focused (not "we will build X")
+   - Success Criteria: 2–5 items, each measurable (can be checked off), each from a stakeholder's perspective
+   - Constraints: real constraints only (regulatory, contractual, architectural); avoid listing preferences as constraints
+   - Status: `draft`
+   - Dates: today's date for both Created and Last reviewed
+
+4. Determine the folder slug: kebab-case, 2–4 words describing the intent (e.g., `password-reset`, `user-onboarding`, `payment-failure-recovery`).
+
+5. Check if `taproot/<slug>/` already exists. If so, append a distinguishing suffix.
+
+6. Create the directory `taproot/<slug>/` and write `intent.md`.
+
+7. Run `taproot validate-format --path taproot/<slug>/`.
+
+8. If validation passes, present next steps:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-behaviour taproot/<slug>/` — define the first behaviour under this intent
+   [B] `/tr-decompose taproot/<slug>/` — decompose the intent into a full behaviour set
+   [C] `/tr-review taproot/<slug>/intent.md` — stress-test the spec before building
+
+### Refining an existing intent
+
+1. Read the existing `intent.md` at `path`.
+
+2. Ask what changed: "What needs to be updated — the goal, the stakeholders, the success criteria, or the status?"
+
+3. Apply changes, preserving all sections. Update "Last reviewed" to today's date.
+   **Preserve the `## Behaviours <!-- taproot-managed -->` section exactly** — read and re-insert it unchanged before `## Status` after applying other edits. Never discard it during a rewrite.
+
+4. If the status is changing to `achieved`, verify at least one success criterion is checked off.
+
+5. Run `taproot validate-format --path <parent-of-path>`.
+
+6. Report what changed.
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-behaviour <path>/` — add or refine a behaviour under this intent
+   [B] `/tr-review <path>/intent.md` — stress-test the updated intent
+   [C] `/tr-status` — see overall project health
+
+## Output
+
+A new `intent.md` in `taproot/<slug>/intent.md` (create mode), or an updated `intent.md` in place (refine mode).
+
+## CLI Dependencies
+
+- `taproot validate-format`
+
+## Document Format Reference
+
+```markdown
+# Intent: <Title>
+
+## Stakeholders
+- <Role>: <Name or team> — <their interest in this intent>
+
+## Goal
+<1-3 sentences describing the desired outcome from the stakeholder's perspective>
+
+## Success Criteria
+- [ ] <Measurable criterion 1>
+- [ ] <Measurable criterion 2>
+
+## Constraints
+- <Constraint 1 (regulatory, technical, timeline, etc.)>
+
+## Status
+- **State:** draft | active | achieved | deprecated
+- **Created:** <YYYY-MM-DD>
+- **Last reviewed:** <YYYY-MM-DD>
+
+## Notes
+<Free-form context, links to external docs, meeting notes, etc.>
+```

package/skills/plan.md

@@ -0,0 +1,63 @@
+# Skill: plan
+
+## Description
+
+Surface the next independently-implementable work item from the requirement hierarchy. Runs `taproot plan` to scan and classify candidates as AFK (agent can proceed autonomously) or HITL (human input required), presents the recommended next slice, and delegates to `/tr-implement` once the developer confirms.
+
+## Inputs
+
+- `path` (optional): Behaviour path to implement directly — skips discovery and goes straight to `/tr-implement`.
+
+## Steps
+
+1. **If a path was provided**: skip to Step 5 and invoke `/tr-implement <path>` directly.
+
+2. Run `taproot plan` and read the output. It lists:
+   - **AFK** candidates: behaviours with `specified` state, ready to implement autonomously
+   - **HITL** candidates: behaviours with `proposed` state, needing human review first
+   - **In-progress** implementations: partially-implemented behaviours that can be resumed
+
+3. If no candidates are found (all behaviours fully implemented), report: "Everything is implemented."
+
+   Nothing obvious next — whenever you're ready:
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-review-all` — semantic review of the full hierarchy
+   [B] `/tr-ineed` — capture a new requirement
+
+   Then stop.
+
+4. Recommend the top AFK candidate (first in the sorted output). Present it as:
+   > "Next recommended slice: **`<behaviour-path>`** (`<intent goal>`)"
+   > "Classification: AFK — spec is complete, no design decisions required."
+   > "To implement: `/tr-implement taproot/<behaviour-path>/`"
+   >
+   > **[Y]** Implement this   **[L]** Show full list   **[S]** Skip to a different behaviour
+
+   - **[Y]**: proceed to Step 5
+   - **[L]**: display the full `taproot plan` output, then ask the developer to pick a behaviour path, then proceed to Step 5
+   - **[S]**: ask "Which behaviour path would you like to implement?" then proceed to Step 5
+
+5. If the top candidate is HITL (no AFK candidates exist), flag it:
+   > "The next unimplemented behaviour is HITL — the spec needs clarification before an agent can proceed autonomously."
+   > "Behaviour: `<path>`"
+
+   **Next:** `/tr-refine taproot/<path>/` — sharpen the spec, then return here
+
+6. Invoke `/tr-implement taproot/<behaviour-path>/` with the confirmed path.
+
+## Output
+
+Delegates to `/tr-implement`. No files are written directly by this skill.
+
+## CLI Dependencies
+
+- `taproot plan`
+
+## Notes
+
+- AFK/HITL classification is determined by the `taproot plan` command using the behaviour's `usecase.md` state as a proxy: `specified` → AFK, `proposed` → HITL.
+- This skill is the conversational wrapper around `taproot plan` — it adds selection, confirmation, and delegation logic that the CLI command cannot provide.
+- `/tr-plan` is the Claude Code adapter command name for this skill.