@imix-js/taproot 0.6.0 → 0.8.0

package/skills/plan-execute.md

@@ -0,0 +1,127 @@
+# Skill: plan-execute
+
+## Description
+
+Execute items from `taproot/plan.md` one at a time (step-by-step) or in sequence (batch), with optional filters to process only `spec`+`refine` items (specify mode) or only `implement` items (implement mode).
+
+## Inputs
+
+- `mode` (optional): `step-by-step` (default), `batch`, `specify`, or `implement` — inferred from developer's natural language request if not explicit
+
+## Steps
+
+1. **Check for plan.** If `taproot/plan.md` does not exist, report:
+   > *"No plan found — build one first with `/tr-plan`."*
+   Stop — no skills invoked.
+
+2. **Read `taproot/plan.md`.** Collect all items and their current status.
+
+3. **Detect mode** from the developer's request:
+   - *"execute next item"* / *"execute plan"* / *"run next"* → **step-by-step** (default)
+   - *"execute all"* / *"run all"* / *"batch"* → **batch**
+   - *"hitl only"* / *"run human items"* / *"interactive only"* → **hitl** (filter: `hitl` items only)
+   - *"afk only"* / *"run autonomous"* / *"implement automatically"* → **afk** (filter: `afk` items only)
+   - *"bring all to specified"* / *"run spec and refine only"* / *"specify mode"* → **specify** (filter: `spec` + `refine` types only)
+   - *"implement all specified"* / *"implement all"* / *"run implement only"* → **implement** (filter: `implement` type only)
+   - No mode specified (bare `/tr-plan-execute` or ambiguous): → **show orientation** (step 3a)
+
+   **3a. Orientation** (only when no mode is specified): count pending items by execution mode and present the mode menu:
+   ```
+   Plan: N items pending (X hitl · Y afk)
+
+   How would you like to proceed?
+   [A] Step-by-step     — one item at a time, confirm each (default)
+   [B] Batch            — confirm full list upfront, then run all
+   [C] HITL only        — human-decision items only
+   [D] AFK only         — autonomous items only
+   [Q] Cancel
+   ```
+   Wait for developer response, then continue with the chosen mode.
+
+4. **Filter pending items** based on mode:
+   - *step-by-step / batch*: all `pending` items
+   - *hitl*: `pending` items labelled `hitl`; `afk` items remain `pending` untouched
+   - *afk*: `pending` items labelled `afk`; `hitl` items remain `pending` untouched
+   - *specify*: `pending` items where type is `[spec]` or `[refine]`; `[implement]` items remain `pending` untouched
+   - *implement*: `pending` items where type is `[implement]`; `[spec]` and `[refine]` items remain `pending` untouched
+
+5. **Check for pending items.** If the filtered list is empty (no pending items matching the filter):
+   - If the overall plan has no `pending` items at all: report *"Plan is complete — no pending items. Build a new plan with `/tr-plan`."*
+   - If items exist but none match the filter: report *"No [hitl | afk | spec/refine | implement] items pending."*
+   Stop — no skills invoked.
+
+6. **In batch mode**, present the full filtered list first and wait for confirmation:
+   ```
+   Executing N items:
+    1. [spec]      "description"
+    2. [implement] taproot/specs/<intent>/<behaviour>/
+   ...
+   [A] Begin  [Q] Abort
+   ```
+   If `[Q]`: stop — no changes made.
+
+7. **For each pending item** (in plan order, respecting the filter):
+
+   **a. Present the item** (always — even in batch mode, each item is shown before its skill runs):
+   ```
+   Next: [implement] taproot/specs/<intent>/<behaviour>/ — <description>
+   Skill: /tr-implement
+   [A] Proceed  [S] Skip  [Q] Stop
+   ```
+
+   **b. In step-by-step mode**, wait for developer response:
+   - `[A]` or affirmative: proceed to c
+   - `[S]`: mark item `skipped` in `taproot/plan.md`; move to next item
+   - `[Q]`: stop — remaining items stay `pending`
+
+   **c. Invoke the skill** based on item type:
+   - `[spec]` → `/tr-behaviour <path> "<description>"`
+   - `[implement]` → `/tr-implement <path>`
+   - `[refine]` → `/tr-refine <path>`
+
+   **d. On skill completion**: invoke `/tr-commit` to commit the output. Once the commit succeeds, mark the item `done` in `taproot/plan.md`. If the commit fails or is aborted, treat as blocked (step e).
+
+   **e. On skill failure / unresolvable blocker**: mark the item `blocked` with a one-line note in `taproot/plan.md`. Report:
+   > *"Item blocked: <reason>. Remaining items are unaffected."*
+   - *Step-by-step*: offer `[A] Continue to next · [D] Stop`
+   - *Batch*: pause and wait for developer to resolve before continuing
+
+   **f. In step-by-step mode**, after each completed item:
+   ```
+   ✓ Done — <description>
+   M items remaining.
+   [A] Continue to next  [D] Stop for now
+   ```
+   - `[A]`: continue to next item
+   - `[D]` or no items remain: report final status (see step 8)
+
+   **g. In batch mode**: mark done and proceed to next item without waiting.
+
+8. **Report final status** when done or stopped:
+   - All items executed: *"Plan complete — all N items executed."*
+   - Stopped early: *"Stopped after N items — M items remaining."*
+   - HITL pass: *"HITL pass complete — N items done. M afk items remain pending."*
+   - AFK pass: *"AFK pass complete — N items done. M hitl items remain pending."*
+   - Specify pass: *"Specify pass complete — N items done. M implement items remain pending."*
+   - Implement pass: *"Implement pass complete — N items done. M spec/refine items remain pending."*
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next item.
+
+   **What's next?**
+   [A] Continue executing — call `/tr-plan-execute` again for remaining items
+   [B] `/tr-plan` — add more items to the plan
+
+## Output
+
+Updates `taproot/plan.md` in-place — replaces `pending` with `done`, `skipped`, `blocked`, or `stale` for each processed item.
+
+## CLI Dependencies
+
+None
+
+## Notes
+
+- In batch mode, the developer confirms the whole list up-front. The agent still presents each item before invoking its skill — per-item visibility is preserved.
+- Specify and implement modes are filters, not separate modes. Filtered-out items stay `pending` (not `skipped`) so they can be processed in a later pass.
+- A typical two-pass workflow: run specify mode to bring all specs to `specified`, then run implement mode to code them all.
+- Autonomous execution (agent works through all items without any human confirmation) is explicitly out of scope.

package/skills/plan.md

@@ -1,63 +1,96 @@
-# Skill: plan
+# Skill: plan-build
 
 ## 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.
+Build a persistent implementation plan (`taproot/plan.md`) from backlog items, unimplemented hierarchy behaviours, or developer-supplied items. Each item is typed (`spec`, `implement`, or `refine`) and sequenced so prerequisites come first.
 
 ## Inputs
 
-- `path` (optional): Behaviour path to implement directly — skips discovery and goes straight to `/tr-implement`.
+- `source` (optional): `backlog`, `hierarchy`, or leave blank to let the developer specify in natural language
 
 ## Steps
 
-1. **If a path was provided**: skip to Step 5 and invoke `/tr-implement <path>` directly.
+1. **Determine sources.** Read the developer's request and identify which sources to scan:
+   - **backlog** — read `taproot/backlog.md`; filter to actionable items
+   - **hierarchy** — run `node dist/cli.js coverage` to find unimplemented or in-progress behaviours
+   - **explicit** — use the items the developer named directly, without scanning
 
-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
+2. **Collect candidates.** For each source:
+   - *backlog*: read `taproot/backlog.md`, one item per bullet/line. Skip blank lines and dated metadata lines. If `taproot/backlog.md` is absent, note *"backlog.md not found, treating as empty"* and continue.
+   - *hierarchy*: run `node dist/cli.js coverage` and collect behaviours whose state is `proposed` (→ `refine`) or have no implementation yet (→ `implement` if usecase.md is `specified`, else → `spec`).
+   - *explicit*: collect items the developer named; resolve each to a hierarchy path if one exists, or mark as `spec` if it doesn't.
 
-3. If no candidates are found (all behaviours fully implemented), report: "Everything is implemented."
+3. **Classify each candidate by type and execution mode:**
+   - Type:
+     - **`spec`** — no `usecase.md` exists yet; first action is to write one with `/tr-behaviour`
+     - **`implement`** — a `usecase.md` exists and is in `specified` state; ready to code
+     - **`refine`** — a `usecase.md` exists but is in `proposed` or `draft` state; needs `/tr-refine` before implementing
+   - Execution mode:
+     - **`hitl`** (human-in-the-loop) — requires a human decision, design choice, or external action before or during execution. Signals: open-ended design, naming decisions, external setup (accounts, secrets, infrastructure), architectural trade-offs, or vague success criteria.
+     - **`afk`** (away-from-keyboard) — agent can execute autonomously; success criteria are fully derivable from an existing spec with no open questions.
+   - Default heuristics: `spec` → `hitl`; `refine` → `hitl`; `implement` → `afk` unless the impl has known external blockers or unresolved design questions.
 
-   Nothing obvious next — whenever you're ready:
+4. **Sequence candidates.** `spec` and `refine` items that are prerequisites for `implement` items appear earlier in the list. Otherwise preserve source order.
 
-> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+5. **Present the proposed plan for review:**
+   ```
+   Proposed plan — N items:
+    1. hitl  [spec]      "description of new item"
+    2. hitl  [refine]    taproot/specs/<intent>/<behaviour>/usecase.md
+    3. afk   [implement] taproot/specs/<intent>/<behaviour>/
 
-   **What's next?**
-   [A] `/tr-review-all` — semantic review of the full hierarchy
-   [B] `/tr-ineed` — capture a new requirement
+   [A] Confirm  [E] Edit directly then reply A  [Q] Abort
+   ```
+   Wait for developer response. Do not write any files before confirmation.
+
+6. **Handle developer choice:**
+   - **[E]**: wait for the developer to paste an edited list in the conversation, then treat it as the confirmed plan and continue to step 7.
+   - **[Q]**: stop — no files written.
+   - **[A]** or any affirmative: continue to step 7.
+
+7. **Check for existing plan.** If `taproot/plan.md` already exists:
+   - Report: *"A plan already exists with N items."*
+   - Offer: `[A] Append new items · [R] Replace · [Q] Abort`
+   - **[A]**: append only items not already present (match by type + path/description).
+   - **[R]**: replace the file with the new plan.
+   - **[Q]**: stop — no files modified.
+
+8. **Write `taproot/plan.md`** using this format:
+   ```
+   # Taproot Plan
 
-   Then stop.
+   _Built: YYYY-MM-DD — N items_
+   _HITL = human decision required · AFK = agent executes autonomously_
 
-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
+   ## Items
 
-   - **[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
+   1. pending  [spec]      hitl  "description of new item"
+   2. pending  [implement] afk   taproot/specs/<intent>/<behaviour>/
+   3. pending  [refine]    hitl  taproot/specs/<intent>/<behaviour>/usecase.md
+   ```
 
-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>`"
+   Status values: `pending` · `done` · `skipped` · `blocked` · `stale`
 
-   **Next:** `/tr-refine taproot/<path>/` — sharpen the spec, then return here
+9. **Remove consumed backlog items.** If any plan items were sourced from `taproot/backlog.md`, remove those lines from the file and report: *"Removed N item(s) from `taproot/backlog.md`."* Skip this step if no backlog items were used or if `taproot/backlog.md` is absent.
 
-6. Invoke `/tr-implement taproot/<behaviour-path>/` with the confirmed path.
+10. Confirm: *"Plan saved — N items in `taproot/plan.md`."*
+
+> 💡 If this session is getting long, consider running `/compact` or starting a fresh context before the next task.
+
+   **What's next?**
+   [A] `/tr-plan-analyse` — check readiness of all items before executing
+   [B] `/tr-plan-execute` — start executing items one by one
 
 ## Output
 
-Delegates to `/tr-implement`. No files are written directly by this skill.
+`taproot/plan.md` — an ordered list of typed, status-tracked action items.
 
 ## CLI Dependencies
 
-- `taproot plan`
+- `taproot coverage`
 
 ## 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.
+- Backlog removal applies only to items sourced from `taproot/backlog.md` — explicit items and hierarchy items have no backlog entry to remove.
+- Dependency ordering is inferred by the agent, not formally declared in the plan file.
+- Autonomous execution of plan items is out of scope — see `/tr-plan-execute` for confirmed step-by-step execution.

package/skills/refine.md

@@ -11,14 +11,14 @@ Update a behaviour spec (`usecase.md`) based on what was learned during or after
 
 ## Steps
 
-0. **Pattern check** — If `.taproot/docs/patterns.md` exists, scan the `finding` input for semantic matches. Match signals:
+0. **Pattern check** — If `taproot/agent/docs/patterns.md` exists, scan the `finding` input for semantic matches. Match signals:
    - "applies to all / every implementation should" → `check-if-affected-by`
    - "enforce a rule / architectural constraint" → `check-if-affected-by`
    - "docs should stay current / keep X updated" → `document-current` or `check-if-affected: X`
 
    If a match is found, **interrupt before reading the spec**:
-   > "Before I refine this — that finding sounds like the **`<pattern-name>`** pattern. <one-line description>. See `.taproot/docs/patterns.md`."
-   > **[A] Apply the pattern** — configure it in `.taproot/settings.yaml` instead of editing the spec
+   > "Before I refine this — that finding sounds like the **`<pattern-name>`** pattern. <one-line description>. See `taproot/agent/docs/patterns.md`."
+   > **[A] Apply the pattern** — configure it in `taproot/settings.yaml` instead of editing the spec
    > **[B] Continue refining** — the spec change is the right approach
 
    - **[A]**: guide through applying the pattern. Do not modify `usecase.md`.

package/skills/research.md

@@ -55,9 +55,10 @@ Research any domain or technical subject before writing a behaviour spec — by
    - <insight 2>
    ```
 
-6. **Expert check** — ask: `"Are you an expert on this subject?"`
-   - **Yes** → delegate to `/tr-grill-me` seeded with the preliminary synthesis as grilling material. The grill session should ask questions that reference specific findings — library names, paper conclusions, known trade-offs — not generic questions. Terminate when the developer says `[Done]` or after ≤3 rounds where no new information is surfacing. Incorporate the expert answers into the synthesis.
-   - **No** → proceed with the gathered synthesis.
+6. **Mode selection** — ask: `"How should I use what I've found?"`
+   - **[A] Extract my knowledge** → delegate to `/tr-grill-me` seeded with the preliminary synthesis as grilling material. Questions should reference specific findings — library names, paper conclusions, known trade-offs — not generic topic questions. Terminate when the developer says `[Done]` or after ≤3 rounds where no new information is surfacing. Incorporate the developer's answers into the synthesis.
+   - **[B] Help me think through the design** → present the key trade-offs, open questions, and competing options surfaced by the research; engage the developer in a structured design discussion; capture agreed choices and rationale in a `## Design Decisions` section appended to the synthesis.
+   - **[C] The synthesis is enough** → proceed with the gathered synthesis as-is.
 
 7. **Present the final structured research summary:**
    ```
@@ -118,5 +119,6 @@ None — pure agent skill. Uses agent tools: file reading (local scan), web sear
 - **Graceful degradation:** if both local resources and web search produce nothing, and no expert is available, announce: `"No research sources available."` Ask whether to proceed with the spec based on the stated requirement alone, or abort. Never silently produce an empty synthesis.
 - **Slug derivation:** kebab-case the topic words, drop stop words, keep max 4 words. `"satellite tracking algorithm"` → `satellite-tracking-algorithm`. Confirm with the developer before writing.
 - **Refresh merges, not overwrites:** when `[R]efresh` is chosen, append new citations to the References section, update Key conclusions, and add a `Last refreshed:` date — do not discard prior expert insights.
-- **Expert grilling is domain-aware:** the grill session is seeded with what was actually found, not generic questions. If the synthesis found `satellite.js`, ask about its limitations, alternatives, and when it breaks — not `"what do you know about satellite tracking?"`
+- **Knowledge extraction ([A]) is domain-aware:** the grill session is seeded with what was actually found, not generic questions. If the synthesis found `satellite.js`, ask about its limitations, alternatives, and when it breaks — not `"what do you know about satellite tracking?"`. Either an expert or a well-informed practitioner can choose [A] — it is about contributing knowledge, not claiming expertise.
+- **Design assistance ([B]) uses the research as grounding:** trade-offs, competing options, and open questions come from the actual findings — not hypothetical concerns. The `## Design Decisions` section captures what was agreed and why.
 - `/tr-research` is the Claude Code adapter command name for this skill.

package/skills/review-all.md

@@ -68,7 +68,7 @@ Run a comprehensive review of an entire subtree — an intent and all its descen
 
 8. **Truth discovery pass** — if `taproot/global-truths/` exists and the hierarchy has 3 or more readable `intent.md`/`usecase.md` files (excluding `global-truths/`):
 
-   Run the same scan as `/tr-discover-truths` (Phase 2–3 of that skill): collect candidates not already defined in `global-truths/` and not suppressed by `.taproot/backlog.md` dismissed entries.
+   Run the same scan as `/tr-discover-truths` (Phase 2–3 of that skill): collect candidates not already defined in `global-truths/` and not suppressed by `taproot/backlog.md` dismissed entries.
 
    If candidates are found, append to the report:
 
@@ -86,7 +86,7 @@ Run a comprehensive review of an entire subtree — an intent and all its descen
 
    **If [P]:** invoke `/tr-discover-truths` inline; return here when it completes.
 
-   **If [D]:** append each candidate to `.taproot/backlog.md` as `- [YYYY-MM-DD] truth candidate: <term>`.
+   **If [D]:** append each candidate to `taproot/backlog.md` as `- [YYYY-MM-DD] truth candidate: <term>`.
 
    If no candidates found (hierarchy consistent with existing truths), append to report:
    ```
@@ -100,7 +100,7 @@ Run a comprehensive review of an entire subtree — an intent and all its descen
 
    **What's next?**
    [A] `/tr-refine <highest-priority-path>` — fix the top-priority finding
-   [B] `/tr-plan` — surface the next implementable behaviour
+   [B] `/tr-next` — surface the next implementable behaviour
    [C] `/tr-backlog <finding>` — capture a deferred finding before routing it to the hierarchy
 
 ## Output

package/skills/status.md

@@ -76,15 +76,15 @@ Generated: <date>
      **What's next?**
      [A] `/tr-implement taproot/<intent>/<behaviour>/` — implement unimplemented behaviour
      [B] `/tr-refine taproot/<intent>/<behaviour>/` — add missing tests
-     [C] `/tr-plan` — pick a different next item
+     [C] `/tr-next` — pick a different next item
 
-   - **If no specific items were found** (healthy project): check whether `.taproot/backlog.md` exists and contains items. Show the generic fallback menu:
+   - **If no specific items were found** (healthy project): check whether `taproot/backlog.md` exists and contains items. Show the generic fallback menu:
 
      **What's next?**
-     [A] `/tr-plan` — pick the next behaviour to implement
+     [A] `/tr-next` — pick the next behaviour to implement
      [B] `/tr-ineed` — route a new requirement into the hierarchy
      [C] `/tr-review-all` — deeper semantic review of specs
-     [D] `/tr-backlog` — triage captured ideas (only if `.taproot/backlog.md` is non-empty)
+     [D] `/tr-backlog` — triage captured ideas (only if `taproot/backlog.md` is non-empty)
 
 ## Output
 

package/skills/sweep.md

@@ -12,6 +12,11 @@ Apply a uniform task to a filtered set of hierarchy files — enumerate matching
 
 ## Steps
 
+0. Check for `.taproot/sessions/sweep-status.md`. If found, present:
+   > "A previous sweep session exists (N done, M remaining, task: `<task>`). [A] Resume  [R] Restart"
+   - **[A] Resume**: load the stored task description and file list; skip files already marked `[x]`; continue from the first `[ ]` file. Proceed directly to step 4.
+   - **[R] Restart**: overwrite the status file from scratch and run the full flow from step 1.
+
 1. Read the task description and determine the target file type(s):
    - If the developer mentions "all usecases" / "every usecase" → filter to `usecase.md` files
    - If the developer mentions "all intents" / "every intent" → filter to `intent.md` files
@@ -44,10 +49,11 @@ Apply a uniform task to a filtered set of hierarchy files — enumerate matching
 4. For each file in the confirmed list, process it in-session:
    a. Read the file to understand its current content
    b. Apply the task directly — edit the file in place
-   c. Output progress immediately after completing each file:
+   c. Mark the file complete and output progress:
       ```
       [x] taproot/intent-a/behaviour-b/usecase.md
       ```
+   d. Write the updated checklist (task description + full file list with current `[x]`/`[ ]` state) to `.taproot/sessions/sweep-status.md`. This persists progress so the session can be resumed if interrupted.
 
    **For tasks requiring codebase exploration** (e.g. "add ACs from existing tests", "fill in missing fields from source code"), before processing each file:
    - Identify **where to look**: explicit directory paths relevant to the file (e.g. `test/integration/`, `src/commands/`)
@@ -61,6 +67,7 @@ Apply a uniform task to a filtered set of hierarchy files — enumerate matching
 
 5. After all files are processed, show a summary:
    > "Sweep complete — N files processed: M modified, K skipped"
+   Delete `.taproot/sessions/sweep-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.