@imix-js/taproot 0.6.0 → 0.8.0

package/skills/backlog.md

@@ -14,14 +14,14 @@ Capture ideas, findings, and deferred work mid-session with a single command —
 
 1. Detect that an argument was provided.
 2. If the argument is blank or whitespace only: warn *"Nothing to capture — provide a description."* and stop.
-3. Create `.taproot/backlog.md` if absent. Append the item:
+3. Create `taproot/backlog.md` if absent. Append the item:
    `- [YYYY-MM-DD] <idea>` using today's date.
 4. Confirm in one line: *"✓ Captured: <idea>"*
    No follow-up response required from the developer — the session continues.
 
 ### Triage mode (no argument)
 
-1. Read `.taproot/backlog.md`.
+1. Read `taproot/backlog.md`.
    - If absent or contains no standard items: report *"Backlog is empty. Use `/tr-backlog <idea>` to capture something."* and stop.
 
 2. Present all standard items as a numbered list (FIFO order, oldest first):
@@ -36,8 +36,8 @@ Capture ideas, findings, and deferred work mid-session with a single command —
 3. Offer: `D <n>` discard · `P <n>` promote to /tr-ineed · `A <n>` analyze · `done` finish
 
 4. Accept commands one at a time:
-   - **`D <n>`** — remove item n from `.taproot/backlog.md`. Confirm: *"✓ Discarded #n"*. Redisplay the updated numbered list.
-   - **`P <n>` promote to /tr-ineed** — remove item n from `.taproot/backlog.md`. Invoke `/tr-ineed` with the item text. On return, redisplay the updated numbered list.
+   - **`D <n>`** — remove item n from `taproot/backlog.md`. Confirm: *"✓ Discarded #n"*. Redisplay the updated numbered list.
+   - **`P <n>` promote to /tr-ineed** — remove item n from `taproot/backlog.md`. Invoke `/tr-ineed` with the item text. On return, redisplay the updated numbered list.
    - **`A <n>` analyze** — produce a structured analysis of the item:
      - A short description of what the item is or could be (2–4 sentences)
      - A complexity signal: **simple** / **moderate** / **significant**
@@ -46,7 +46,7 @@ Capture ideas, findings, and deferred work mid-session with a single command —
    - **`done`** — end triage. Items not acted on are kept implicitly.
 
 5. After `done`: *"Triage complete — X discarded, Y promoted, Z kept."*
-   If any non-standard lines were skipped: *"Skipped N non-standard line(s) — they remain in `.taproot/backlog.md`."*
+   If any non-standard lines were skipped: *"Skipped N non-standard line(s) — they remain in `taproot/backlog.md`."*
 
    If the developer exits without `done`: unprocessed items remain unchanged. If any actions were taken, show the summary; otherwise continue naturally.
 
@@ -60,7 +60,7 @@ Capture ideas, findings, and deferred work mid-session with a single command —
 
 ## Output
 
-**Capture:** item written to `.taproot/backlog.md`, one-line confirmation.
+**Capture:** item written to `taproot/backlog.md`, one-line confirmation.
 **Triage:** backlog updated in place; promoted items handed to `/tr-ineed`; completion summary shown.
 
 ## CLI Dependencies
@@ -73,4 +73,4 @@ None.
 - Item format: `- [YYYY-MM-DD] <text>`. Items are presented FIFO (oldest first) during triage.
 - Items promoted via `[P]` are removed from the backlog before `/tr-ineed` is invoked. If the developer abandons the `/tr-ineed` discovery, re-capture the item with `/tr-backlog <idea>`.
 - This is a scratchpad, not a project management tool — no priority, labels, or status tracking.
-- Storage is `.taproot/backlog.md` — a committed markdown file inside the taproot config directory, versioned with the project.
+- Storage is `taproot/backlog.md` — a committed markdown file inside the taproot config directory, versioned with the project.

package/skills/behaviour.md

@@ -15,14 +15,14 @@ Define a UseCase (observable system behaviour) under an intent or another behavi
    - If `parent` contains `intent.md`: read the intent to understand the goal and success criteria.
    - If `parent` contains `usecase.md`: read the parent behaviour — this new behaviour is a sub-behaviour.
 
-1a. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the behaviour description for semantic matches. Match signals:
+1a. **Pattern check** — If `taproot/agent/docs/patterns.md` exists, scan the behaviour description for semantic matches. Match signals:
    - "apply to all / every implementation / every skill" → `check-if-affected-by`
    - "enforce a rule / architectural constraint / agents should follow" → `check-if-affected-by`
    - "keep docs current / enforce documentation quality" → `document-current`
    - "every new feature must update X" → `check-if-affected: X`
 
    If a match is found, **interrupt before asking clarifying questions**:
-   > "Before I write this spec — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md`."
+   > "Before I write this spec — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `taproot/agent/docs/patterns.md`."
    > **[A] Use this pattern now** — I'll guide you through applying it instead of writing a spec
    > **[B] Continue writing the spec** — the spec is distinct from the pattern
 

package/skills/bug.md

@@ -35,10 +35,10 @@ Diagnose a defect through structured root cause analysis (5-Why) and delegate to
 
    - **No (clearly one-off** — typo, isolated misconfiguration, external incident): note this and continue to step 5.
    - **Yes**: propose prevention across one or more of:
-     - A new DoR or DoD condition to add to `.taproot/settings.yaml`
+     - A new DoR or DoD condition to add to `taproot/settings.yaml`
      - An update to `docs/architecture.md`, `docs/security.md`, or `docs/patterns.md`
 
-   If a satisfactory measure is found: present it — e.g. *"I'll add `check-if-affected-by: <gate>` to `.taproot/settings.yaml`"* or *"I'll add to `docs/security.md`: `<constraint>`"* — and wait for actor confirmation.
+   If a satisfactory measure is found: present it — e.g. *"I'll add `check-if-affected-by: <gate>` to `taproot/settings.yaml`"* or *"I'll add to `docs/security.md`: `<constraint>`"* — and wait for actor confirmation.
    - On **confirm**: apply the change, then continue to step 5.
    - On **reject**: record the recurrence concern in the implicated impl.md `## Notes` and continue to step 5.
 

package/skills/commit.md

@@ -5,7 +5,7 @@
 Before following any steps, check whether autonomous mode is active:
 - `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
 - `--autonomous` was passed as an argument to this skill invocation, **or**
-- `.taproot/settings.yaml` contains `autonomous: true`
+- `taproot/settings.yaml` contains `autonomous: true`
 
 If any of these is true, **autonomous mode is active** — apply autonomous notes where they appear. If none is true, show confirmation prompts as normal.
 
@@ -35,7 +35,7 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
    **Autonomous mode:** stage all relevant files and proceed directly without waiting for confirmation.
 
-4. Read `.taproot/settings.yaml` to identify all configured `definitionOfDone` and `definitionOfReady` conditions. If the file does not exist or has no `definitionOfDone`/`definitionOfReady` sections, note: "No user-configured conditions — baseline hook checks only." and proceed to the appropriate sub-flow below.
+4. Read `taproot/settings.yaml` to identify all configured `definitionOfDone` and `definitionOfReady` conditions. If the file does not exist or has no `definitionOfDone`/`definitionOfReady` sections, note: "No user-configured conditions — baseline hook checks only." and proceed to the appropriate sub-flow below.
 
 5. Execute the sub-flow matching the commit type:
 
@@ -55,6 +55,20 @@ Execute the full commit procedure: classify the commit type, run the appropriate
       taproot dod <impl-path> --resolve "<exact-condition-name>" --note "<reasoning>"
       ```
       **One condition per invocation.** Do not pass multiple `--resolve` flags.
+
+      **`document-current` resolution — mandatory steps:**
+      1. Read `docs/` and `README.md` content (the actual text, not inferred state)
+      2. Read the git diff for this implementation to identify what changed
+      3. Compare: are the docs accurate and current relative to what was just implemented?
+      4. If stale sections are found: apply updates directly, then resolve
+      5. If docs are current: resolve with a note describing what you read and why no update is needed
+
+      **Prohibited resolutions for `document-current`:**
+      - "nothing in backlog → docs are fine"
+      - "impl.md says complete → docs must be current"
+      - "no related backlog items → no doc update needed"
+      - Any resolution that does not involve reading `docs/` content and comparing it to the git diff
+
    c. Re-run `taproot dod <impl-path>` after each resolution to check remaining failures
    d. Repeat until all conditions pass. If a condition remains `✗` after its `--resolve` invocation, stop immediately: "Cannot resolve `<condition>` — it requires: `<correction hint>`." Wait for the user to intervene.
 
@@ -72,13 +86,26 @@ Execute the full commit procedure: classify the commit type, run the appropriate
       Wait for the developer's choice. Do not proceed to step 5 until resolved.
    e. If no conflicts (or all resolved): run `taproot truth-sign` to record the session marker the hook validates.
 
-5. Stage source files + all matched impl.md files and commit with a concise one-line message.
+5. **Suggest commit tag** — derive the conventional tag from the matched impl.md paths:
+   - For each matched `impl.md`, extract the relative path between `taproot/specs/` and `/impl.md` → `<intent>/<behaviour>/<impl>`
+   - If the developer has already supplied a commit message that starts with a recognised prefix (`taproot(`, `fix:`, `feat:`, `chore:`, `refine:`, `spec:`, `build:`, `docs:`): use it as-is — do not suggest or prepend anything
+   - If all matched impl.md files share the same `<intent>/<behaviour>` prefix:
+     - Single impl: suggest `taproot(<intent>/<behaviour>/<impl>):`
+     - Multiple impls under the same behaviour: suggest `taproot(<intent>/<behaviour>):`
+   - If matched impl.md files span two or more distinct `<intent>/<behaviour>` paths:
+     - Report: *"Staged files span multiple behaviours: `<path-1>`, `<path-2>`. Suggested: commit them separately, one per behaviour, to keep commit history traceable."*
+     - Offer: `[A] Commit all together (no single tag)  [B] Split — commit one behaviour at a time`
+     - `[B]`: stage only the first behaviour's files, apply its tag, commit; then repeat for the remainder
+   - If an impl.md path does not match `taproot/specs/<intent>/<behaviour>/<impl>/impl.md`, skip the tag suggestion for that file and note: *"Could not derive tag from `<path>` — path layout unexpected."*
+   - Present: `Suggested commit tag: taproot(<path>):`
+
+6. Stage source files + all matched impl.md files and commit with the suggested tag prefix (or the developer-supplied message).
 
 ### Declaration commit
 
 1. Verify parent `usecase.md` is in `specified`, `implemented`, or `complete` state. If it is in `draft` or `proposed` state, report: "Cannot declare implementation — parent `usecase.md` is in `<state>` state. Run `/tr-refine <usecase-path>` to complete the spec first." Stop.
 
-2. Read `.taproot/settings.yaml` `definitionOfReady` entries. For each `check-if-affected-by` or `check:` condition, write an entry directly into `## DoR Resolutions` in the impl.md. There is no `taproot dor` CLI — write entries by hand:
+2. Read `taproot/settings.yaml` `definitionOfReady` entries. For each `check-if-affected-by` or `check:` condition, write an entry directly into `## DoR Resolutions` in the impl.md. There is no `taproot dor` CLI — write entries by hand:
    ```
    condition: <name> | note: <reasoning> | resolved: <date>
    ```
@@ -124,6 +151,15 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
 6. After committing, run `taproot link-commits --path <taproot-root>` if any impl.md files were staged, to update their `## Commits` sections.
 
+7. Offer contextual What's next options based on the commit type:
+   - **[A] Continue plan** — only if `taproot/plan.md` exists and contains `pending` items: invoke `/tr-plan-execute`
+   - **[B] Implement next** — only for requirement or declaration commits: prompt `Which behaviour should I implement next?` then invoke `/tr-implement <path>`
+   - **[C] Check backlog** — open `.taproot/backlog.md` to review deferred ideas and captured findings
+   - **[D] Check coverage** — `/tr-status` to review hierarchy health
+   - **[E] Done** — no further action
+
+   Omit [A] if no plan exists or no pending items remain. Omit [B] after implementation and plain commits. Developer may ignore the prompt silently.
+
 ## Output
 
 A clean commit where the pre-commit hook passes on the first attempt. All conditions resolved with written rationale before staging.

package/skills/discover-truths.md

@@ -13,12 +13,19 @@ Scan the taproot hierarchy for implicit facts — recurring terms, business rule
 Before following any steps, check whether autonomous mode is active:
 - `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
 - `--autonomous` was passed as an argument to this skill invocation, **or**
-- `.taproot/settings.yaml` contains `autonomous: true`
+- `taproot/settings.yaml` contains `autonomous: true`
 
-If any of these is true, **autonomous mode is active** — skip interactive prompts and defer all candidates to `.taproot/backlog.md` as "truth candidate: `<term>`" entries, then report the summary.
+If any of these is true, **autonomous mode is active** — skip interactive prompts and defer all candidates to `taproot/backlog.md` as "truth candidate: `<term>`" entries, then report the summary.
 
 ## Steps
 
+### Phase 0 — Resume Check
+
+1a. Check for `.taproot/sessions/discover-truths-status.md`. If found, present:
+   > "A previous session exists (N processed, M remaining). [A] Resume  [R] Restart"
+   - **[A] Resume**: load the status file, skip already-processed candidates, and continue from the first unprocessed `[ ]` entry. Proceed directly to Phase 4 using the stored candidate list.
+   - **[R] Restart**: overwrite the status file from scratch and run the full flow from Phase 1.
+
 ### Phase 1 — Pre-flight
 
 1. Verify `taproot/global-truths/` exists. If not, stop:
@@ -31,7 +38,7 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
 
 3. Read all files in `taproot/global-truths/` (excluding `intent.md` and subdirectory `usecase.md` files — truth files are files that are NOT named `intent.md` or `usecase.md`). Collect defined terms and rules from them.
 
-4. Read `.taproot/backlog.md` if it exists. Extract all lines matching `reviewed — not a truth: <term>` — these are permanently dismissed candidates. Build a suppression list from them.
+4. Read `taproot/backlog.md` if it exists. Extract all lines matching `reviewed — not a truth: <term>` — these are permanently dismissed candidates. Build a suppression list from them.
 
 ### Phase 3 — Identify Candidates
 
@@ -59,9 +66,7 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
 
 ### Phase 4 — Present Candidates
 
-7. Group remaining candidates by category. If more than 10 total, present in batches of 5. After each batch, ask: "[C] Continue to next batch  [D] Done — stop here".
-
-   For each candidate, present:
+7. Present candidates **one at a time**. For each candidate:
    ```
    Candidate: `<term or rule>`
    Category: <recurring term | business rule | implicit convention>
@@ -76,9 +81,10 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
 
    **Autonomous mode:** defer all candidates to backlog as "truth candidate: `<term>`" and skip to Phase 5.
 
-8. Handle each developer choice:
+8. Handle each developer choice. **After each response**, write progress to `.taproot/sessions/discover-truths-status.md` before moving to the next candidate (format: checklist of all candidates with `[x]`/`[ ]` markers, counts of promoted/skipped/backlogged/dismissed so far):
 
    **Promote [P]:**
+   - Mark candidate `[x promoted]` in the status file
    - Invoke `/tr-ineed` with the candidate term, proposed scope, and evidence pre-populated as context
    - If `/tr-ineed` routes to a location other than `define-truth`, surface the routing decision:
      > "This candidate was routed to `<location>`. [A] Accept routing  [B] Override — invoke define-truth directly"
@@ -86,22 +92,30 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
    - After `/tr-ineed` completes (or is abandoned), return to the candidate list
 
    **Skip [S]:**
-   - No record written; candidate reappears on next discovery run
+   - Mark candidate `[x skipped]` in the status file
+   - No record written to backlog; candidate reappears on next discovery run
 
    **Backlog [B]:**
-   - Append to `.taproot/backlog.md`: `- [YYYY-MM-DD] truth candidate: <term>`
+   - Mark candidate `[x backlogged]` in the status file
+   - Append to `taproot/backlog.md`: `- [YYYY-MM-DD] truth candidate: <term>`
    - Move to next candidate
 
    **Dismiss [D]:**
-   - Append to `.taproot/backlog.md`: `- [YYYY-MM-DD] reviewed — not a truth: <term>`
+   - Mark candidate `[x dismissed]` in the status file
+   - Append to `taproot/backlog.md`: `- [YYYY-MM-DD] reviewed — not a truth: <term>`
    - This entry suppresses the candidate on all future discovery runs
    - Move to next candidate
 
+   **Developer ends session early:**
+   - Current state is already persisted in `.taproot/sessions/discover-truths-status.md`
+   - Developer can resume by re-invoking `/tr-discover-truths` and selecting [A] Resume
+
 ### Phase 5 — Wrap Up
 
 9. Report:
    > "Discovery complete — N promoted, N skipped, N backlogged, N dismissed[, N remaining]."
    > (Include "N remaining" only if the developer ended the session early.)
+   Delete `.taproot/sessions/discover-truths-status.md` (clean completion — no resume needed).
 
 > 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
 
@@ -113,7 +127,7 @@ If any of these is true, **autonomous mode is active** — skip interactive prom
 ## Output
 
 - Zero or more truth files created in `taproot/global-truths/` (via `/tr-ineed` → define-truth)
-- `.taproot/backlog.md` updated with any backlogged or dismissed candidates
+- `taproot/backlog.md` updated with any backlogged or dismissed candidates
 - Summary report: N promoted, N skipped, N backlogged, N dismissed
 
 ## CLI Dependencies
@@ -125,5 +139,5 @@ None.
 - Truth files in `taproot/global-truths/` are any files that are NOT named `intent.md` or `usecase.md`. They may have any name (e.g. `glossary.md`, `pricing-rules.md`, `entity-model.md`).
 - "Recurring" means 2 or more specs — not just repeated within a single spec.
 - Skip generic language-level words ("the", "a", "is", "not") and taproot structural terms ("intent", "behaviour", "usecase", "implementation") — these are not domain truths.
-- Dismissed entries in `.taproot/backlog.md` are matched by the literal string "reviewed — not a truth: `<term>`" — the suppression logic is substring-match on the candidate term.
+- Dismissed entries in `taproot/backlog.md` are matched by the literal string "reviewed — not a truth: `<term>`" — the suppression logic is substring-match on the candidate term.
 - This skill is read-only on the hierarchy — it never modifies `intent.md` or `usecase.md` files directly.

package/skills/discover.md

@@ -241,7 +241,7 @@ Reverse-engineer an existing project into a taproot hierarchy — from source co
 
     **What's next?**
     [A] `/tr-status` — see coverage gaps and health report
-    [B] `/tr-plan` — surface the next behaviour to implement
+    [B] `/tr-next` — surface the next behaviour to implement
     [C] `/tr-ineed` — capture requirements that surfaced during discovery but weren't formalised
 
 ## Output

package/skills/guide.md

@@ -62,6 +62,10 @@ ineed → intent → behaviour → implement → trace → status
 | `/tr-backlog` | Capture an idea or finding instantly mid-session; called with no args opens triage to discard, keep, or promote items |
 | `/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-next` | Surface the next independently-implementable work item from the hierarchy |
+| `/tr-plan` | Build a persistent implementation plan (`taproot/plan.md`) from backlog items, hierarchy gaps, or explicit items |
+| `/tr-plan-execute` | Execute items from `taproot/plan.md` — step-by-step, batch, specify (spec+refine only), or implement (implement only) mode |
+| `/tr-plan-analyse` | Analyse `taproot/plan.md` before execution — check readiness, flag ambiguous specs, unresolved dependencies, and missing prerequisites |
 | `/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 |
@@ -107,7 +111,7 @@ ineed → intent → behaviour → implement → trace → status
    **What's next?**
    [A] `/tr-ineed` — capture your first (or next) requirement
    [B] `/tr-status` — see the current project health at a glance
-   [C] `/tr-backlog` — triage captured ideas (only if `.taproot/backlog.md` is non-empty)
+   [C] `/tr-backlog` — triage captured ideas (only if `taproot/backlog.md` is non-empty)
 
 ## Output
 

package/skills/implement.md

@@ -14,7 +14,7 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
 Before following any steps, check whether autonomous mode is active:
 - `TAPROOT_AUTONOMOUS=1` is set in the environment, **or**
 - `--autonomous` was passed as an argument to this skill invocation, **or**
-- `.taproot/settings.yaml` contains `autonomous: true`
+- `taproot/settings.yaml` contains `autonomous: true`
 
 If any of these is true, **autonomous mode is active** — apply the autonomous notes at each step where they appear. If none is true, autonomous mode is **inactive** — show confirmation prompts as normal.
 
@@ -36,14 +36,14 @@ If any of these is true, **autonomous mode is active** — apply the autonomous
    - Read each applicable file; apply defined terms and conventions when choosing the implementation approach, naming, and design decisions
    - If the implementation plan contradicts an applicable truth, surface the conflict before proceeding: "This implementation contradicts `global-truths/<file>`: `<excerpt>`. [A] update plan to align, [B] update the truth, [C] proceed with the conflict noted."
 
-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:
+4. **Pattern check + plan mode.** Before proposing the plan: if `taproot/agent/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
+   > "Before the plan — this looks like it could use the **`<pattern-name>`** pattern rather than a custom implementation. See `taproot/agent/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:**
@@ -102,7 +102,7 @@ If any of these is true, **autonomous mode is active** — apply the autonomous
 6. **Declaration commit** — commit `impl.md`, `discussion.md` (if written), 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.
+   - 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.
 
    ```
@@ -146,7 +146,7 @@ If any of these is true, **autonomous mode is active** — apply the autonomous
 > 💡 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
+   [A] `/tr-next` — surface the next implementable behaviour
    [B] `/tr-status` — see full project health after this implementation
 
 ## Output

package/skills/ineed.md

@@ -27,7 +27,7 @@ Route a natural language requirement to the right place in the taproot hierarchy
    - **[B]**: proceed to pattern check below.
    - **[C]** or no global truth signal: proceed to pattern check below.
 
-0a. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the stated requirement for semantic matches against the patterns listed there. Match signals:
+0a. **Pattern check** — If `taproot/agent/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`
@@ -35,14 +35,14 @@ Route a natural language requirement to the right place in the taproot hierarchy
    - "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."
+   > "Before I route this — that sounds like the **`<pattern-name>`** pattern. <one-line description>. See `taproot/agent/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.
+   - **[A]**: read the relevant section of `taproot/agent/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.
+   If multiple patterns match, list all before asking. If `taproot/agent/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:
 

package/skills/next.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-next` is the Claude Code adapter command name for this skill.

package/skills/plan-analyse.md

@@ -0,0 +1,81 @@
+# Skill: plan-analyse
+
+## Description
+
+Analyse `taproot/plan.md` before execution: check each pending item for readiness, flag ambiguous specs, unresolved dependencies, and missing prerequisites, and produce a per-item report so the developer knows what needs fixing before executing.
+
+## Inputs
+
+None required.
+
+## Steps
+
+1. **Check for plan.** If `taproot/plan.md` does not exist, report:
+   > *"No plan found — build one first with `/tr-plan`."*
+   Stop.
+
+2. **Read `taproot/plan.md`.** Collect all items. If no `pending` items exist, report:
+   > *"No pending items to analyse."*
+   Suggest: *"Build a new plan with `/tr-plan`."* Stop.
+
+3. **Evaluate readiness for each pending item:**
+
+   **`[spec]` items:**
+   - Is the description specific enough to write a `usecase.md`? Does it name an actor and a goal?
+   - Flag ⚠ if the description is vague, names no actor, or has no clear success outcome.
+
+   **`[implement]` items:**
+   - Does the referenced `usecase.md` exist at the given path?
+   - Is it in `specified` or `implemented` state? Flag ⚠ if it is `draft` or `proposed`.
+   - Does the spec have open questions (unresolved `?` markers, `TBD` entries, or `proposed` sub-behaviours)? Flag ⚠ if found.
+   - Flag ✗ if `usecase.md` is missing entirely.
+
+   **`[refine]` items:**
+   - Does the referenced spec exist?
+   - Is there enough context in the item description to know what to refine?
+   - Flag ⚠ if the description is too vague to guide refinement.
+   - Flag ✗ if the spec is missing.
+
+   **Dependency check (all types):**
+   - If this item depends on an earlier plan item (inferred by position: a `[spec]` or `[refine]` item for the same path appearing earlier in the list), is that predecessor `done` or `specified`?
+   - Flag ✗ if the predecessor is still `pending`.
+
+4. **Build the readiness report:**
+   ```
+   Plan Analysis — N pending items
+
+   ✓ Ready (N)
+     · [implement] taproot/<intent>/<behaviour>/ — spec specified, no open questions
+
+   ⚠ Needs attention (N)
+     · [implement] taproot/<intent>/<behaviour>/ — spec is 'proposed', run /tr-refine first
+     · [spec] "add login flow" — description is vague: actor and success criteria unclear
+
+   ✗ Blocked (N)
+     · [implement] taproot/<intent>/<behaviour>/ — depends on item 2 which is not yet done
+   ```
+   For each flagged item, append a one-line suggested action (e.g. `/tr-refine <path>`, `/tr-behaviour <path>`, "clarify actor and goal").
+
+5. **Summarise:**
+   - If all items are ready: *"All N pending items are ready — no blockers or ambiguities found."* Offer: *"[A] Execute now → `/tr-plan-execute`"*
+   - Otherwise: *"N items ready, N need attention, N blocked. Suggested: resolve ⚠ and ✗ items before executing."*
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-plan-execute` — execute the plan (after resolving flagged items)
+   [B] `/tr-plan` — rebuild or add items to the plan
+
+## Output
+
+A readiness report printed in the conversation — no files modified.
+
+## CLI Dependencies
+
+None
+
+## Notes
+
+- This behaviour is read-only — it never modifies `taproot/plan.md` or any hierarchy document.
+- Stale paths (referenced file no longer exists) are flagged inline; analysis continues for remaining items.
+- For large plans (>10 items), group by readiness category rather than plan order.