@imix-js/taproot 0.2.1 → 0.4.0

package/skills/commit.md

@@ -1,5 +1,14 @@
 # Skill: commit
 
+## Autonomous mode
+
+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`
+
+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.
+
 ## Description
 
 Execute the full commit procedure: classify the commit type, run the appropriate gate proactively, resolve all conditions before staging, and commit. Handles implementation, declaration, requirement, and plain commits. Invoke this skill whenever you are about to commit, or when the user says "commit", "let's commit", "commit that", or similar.
@@ -20,7 +29,11 @@ Execute the full commit procedure: classify the commit type, run the appropriate
 
    To identify impl.md ownership, run `grep -rl "<filename>" taproot/` for each candidate source file.
 
-3. If nothing is staged yet, announce: "Nothing staged yet. Here's what's changed: [list]. Should I stage these and proceed with the commit?" Wait for confirmation before proceeding.
+3. If nothing is staged yet, announce: "Nothing staged yet. Here's what's changed: [list]."
+
+   **Interactive mode:** ask "Should I stage these and proceed with the commit?" and wait for confirmation before proceeding.
+
+   **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.
 

package/skills/grill-me.md

@@ -46,6 +46,7 @@ Based on Matt Pocock's `grill-me` skill (MIT licensed, https://github.com/mattpo
    **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
+   [C] `/tr-backlog <deferred question>` — capture an unresolved question for later without routing it now
 
 ## Output
 

package/skills/guide.md

@@ -56,6 +56,8 @@ ineed → intent → behaviour → implement → trace → status
 | `/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-browse` | Read a hierarchy document section by section in the terminal — with inline editing via `[M] Modify` |
+| `/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-sweep` | Apply a uniform task to a filtered set of hierarchy files — enumerate, confirm, then call `taproot apply` |
@@ -77,7 +79,7 @@ ineed → intent → behaviour → implement → trace → status
 | `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 |
+| `taproot init [--template webapp\|book-authoring\|cli-tool]` | Initialize Taproot in a project; optionally copy a starter hierarchy |
 
 ### Rule of Thumb
 
@@ -92,7 +94,7 @@ ineed → intent → behaviour → implement → trace → status
 
    - **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."
+   - **If no intents exist yet** (empty or missing `taproot/`): "This looks like a new project. You can start from a template (`taproot init --template webapp|book-authoring|cli-tool`) for a pre-populated hierarchy, or 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:
 
@@ -103,6 +105,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)
 
 ## Output
 

package/skills/implement.md

@@ -9,6 +9,15 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
 - `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.
 
+## Autonomous mode
+
+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`
+
+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.
+
 ## Steps
 
 1. Read `<path>/usecase.md` thoroughly. Understand:
@@ -38,7 +47,9 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
    - 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.
+   **Autonomous mode:** form the plan internally, record it in the `impl.md` Design Decisions section, and proceed directly to step 5 without pausing for approval.
+
+   **Interactive mode:** 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`
@@ -56,7 +67,34 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
     - 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):
+5b. **Write `discussion.md`** — draft a `discussion.md` in the implementation folder capturing the deliberation behind the design decisions. This complements `impl.md` (which records conclusions) with the reasoning process:
+
+   ```markdown
+   # Discussion: <title matching impl.md>
+
+   ## Session
+   - **Date:** YYYY-MM-DD
+   - **Skill:** tr-implement
+
+   ## Pivotal Questions
+   <The 1–3 questions or exchanges that most shaped the design>
+
+   ## Alternatives Considered
+   - **<Option A>** — rejected because <reason>
+   - **<Option B>** — rejected because <reason>
+
+   ## Decision
+   <One paragraph: the chosen approach and why — the deliberation behind impl.md's Design Decisions>
+
+   ## Open Questions
+   - <Unresolved items deferred to a future session, or "None">
+   ```
+
+   **When to skip:** If the session involved only trivial edits (typo fix, formatting, minor wording change) with no design choices or alternatives explored, omit `discussion.md`. A file with no substantive content is worse than no file.
+
+   Stage `discussion.md` alongside `impl.md` in the declaration commit.
+
+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.
@@ -72,8 +110,15 @@ Implement a behaviour spec: write the code, write the tests, create the `impl.md
    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
 
+   **Autonomous mode — if tests fail:** record the full test output in `impl.md` under a `## Notes` entry headed `Autonomous execution — test failure`, set `**State:** needs-rework`, and stop. Do not attempt to fix tests autonomously without context from the developer.
+
 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.
 
+   **Autonomous mode — DoD self-resolution:**
+   - For every `check-if-affected-by`, `check-if-affected`, `check:`, and `document-current` condition: reason through it by reading the spec and source, then record the resolution with `--resolve` and `--note` without prompting.
+   - For any `check:` condition where the answer cannot be determined from the code and spec alone: write a `<!-- autonomous: pending-review -->` comment in `## DoD Resolutions` alongside the unresolved condition entry, with the question text. Continue evaluating remaining conditions. After all conditions are processed, if any remain marked pending-review, set `**State:** in-progress` and commit — the developer will complete them on return.
+   - For `run:` conditions that exit non-zero: record the output in `impl.md`, mark `needs-rework`, and stop.
+
 9. **Implementation commit** — commit source files and `impl.md` together:
 
    Before staging:

package/skills/review-all.md

@@ -73,7 +73,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
-   [C] `/tr-ineed` — add a requirement surfaced by the review
+   [C] `/tr-backlog <finding>` — capture a deferred finding before routing it to the hierarchy
 
 ## Output
 

package/skills/review.md

@@ -60,6 +60,7 @@ Stress-test a single Taproot artifact — an `intent.md`, `usecase.md`, or `impl
    **What's next?**
    [A] `/tr-refine <path>` — apply the findings to the spec
    [B] `/tr-implement <path>/` — spec is clean; proceed to implementation
+   [C] `/tr-backlog <finding>` — capture an out-of-scope issue for later without routing it now
 
 ## Output
 

package/skills/status.md

@@ -78,12 +78,13 @@ Generated: <date>
      [B] `/tr-refine taproot/<intent>/<behaviour>/` — add missing tests
      [C] `/tr-plan` — pick a different next item
 
-   - **If no specific items were found** (healthy project): 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
-     [B] `/tr-ineed` — capture a new requirement
+     [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)
 
 ## Output