trekoon 0.4.2 → 0.4.4

package/.agents/skills/trekoon/reference/execution.md

@@ -1,466 +1,256 @@
 # Execution Reference
 
-**You are an orchestrator.** Execute work from Trekoon, not markdown plan files.
-Spawn and coordinate sub-agents based on the task dependency graph and subsystem
-grouping so independent lanes run in parallel and dependent lanes run
-sequentially.
+You are an orchestrator. Execute work from Trekoon, not markdown plan files.
+Execution is complete only when the epic is marked `done`, all remaining work is
+blocked with recorded reasons, or real user input is required.
 
-**Execute mode contract:** execution is complete only when the epic is marked
-`done`, all remaining work is blocked with recorded reasons, or user input is
-required to continue.
+When executing an epic, use subagents by default for any meaningful work that
+can run independently. Keep small or tightly coupled tasks in the parent agent.
+Use your context for orchestration, dependency decisions, user communication,
+and final synthesis.
 
-**Clarify ambiguity upfront.** If the plan has unclear requirements or meaningful
-tradeoffs, ask the user before starting.
+If the plan has unclear requirements or meaningful tradeoffs, ask before
+starting. Do not stop at status reporting when ready work exists.
 
-## Choose execution shape first
+## Choose Shape
 
-Use the lightest shape that still preserves momentum:
+- Direct work: one ready task, tiny change, narrow scope, or tightly coupled
+  work. Use the direct work loop below.
+- Orchestrated work: multiple ready tasks across separable lanes. Build the
+  graph, group by lane, delegate meaningful independent lanes, and coordinate
+  completion from the parent session.
 
-- **Single-agent execution**: one ready task, narrow scope, or strongly coupled
-  work. Use the `session → claim → work → task done → repeat` loop from
-  `SKILL.md`.
-- **Orchestrated execution**: multiple ready tasks across separable lanes. This
-  file focuses on that path.
+If a higher-priority harness policy blocks subagent use without explicit user
+wording, tell the user immediately after the lane graph is known:
 
-Do not stop at status reporting when ready work exists.
-
-## Build the execution graph
-
-Construct a runnable graph from Trekoon entities using the deterministic
-scheduler loop:
-
-1. **Get the ready set for batching decisions:**
-   ```bash
-   trekoon --toon task ready --epic <epic-id> --limit 50
-   ```
-2. **Use reverse lookup when deciding what completed work unblocks:**
-   ```bash
-   trekoon --toon dep reverse <task-or-subtask-id>
-   ```
-3. **Load full context only when execution details are needed:**
-   ```bash
-   trekoon --toon epic show <epic-id> --all
-   ```
-
-Prefer scheduler primitives (`task next`, `task ready`, `dep reverse`) over
-broad scans (`task list --all`, `epic show --all`).
+```text
+I found <n> independent Trekoon lanes. This harness requires explicit
+permission before I can spawn subagents. Should I delegate those lanes and keep
+coordinating from the parent session?
+```
 
-## Group tasks into lanes
+## Build The Graph
 
-Batch ready tasks by subsystem/domain to minimize repeated context loading:
+Use scheduler reads before broad tree reads:
 
+```bash
+trekoon --toon task ready --epic <epic-id> --limit 50
+trekoon --toon dep reverse <task-or-subtask-id>
+trekoon --toon epic show <epic-id> --all
 ```
-Without: Task 1 (auth/login)  -> Agent 1 [explores auth/]
-         Task 2 (auth/logout) -> Agent 2 [explores auth/ again]
-
-With:    Tasks 1-2 (auth/*)   -> Agent 1 [explores once, executes both]
-```
-
-| Signal | Group together |
-|--------|----------------|
-| Same directory prefix | `src/auth/*` tasks |
-| Same domain/feature | Auth tasks, billing tasks |
-| Same `--owner` value | Tasks assigned to same lane |
-| Same Trekoon intent | Similar task title/description scope |
 
-**Limits:** 3-4 tasks max per group. Split if larger.
+Group ready tasks by lane:
 
-**Parallel:** Groups touch different subsystems.
-**Sequential:** Groups have dependency edges between them.
+- Same directory prefix.
+- Same subsystem/domain.
+- Same owner.
+- Same implementation context.
 
-## Mark epic in-progress
+Keep each lane to about 3-4 tasks. Split larger lanes. Parallel lanes touch
+different subsystems and have no dependency edge. Sequential lanes have hard
+dependencies.
 
-Before dispatching any work, transition the epic so it reflects actual state:
+Mark the epic in progress once, before dispatching:
 
 ```bash
 trekoon --toon epic update <epic-id> --status in_progress
 ```
 
-This must happen once, immediately after building the execution graph. If
-execution is interrupted, the epic is at least `in_progress` rather than `todo`.
+## Delegate Lanes
 
-## Dispatch sub-agents
+For each meaningful independent lane, spawn a subagent when the harness exposes
+subagents. Keep local todo/task tools as a live progress display only; Trekoon
+remains the durable source of truth.
 
-For each parallel lane group, spawn a sub-agent with a prompt like:
+Prompt shape:
 
-```
-Execute these Trekoon tasks IN ORDER unless task description says parallel
-subtasks:
+```text
+Spawn or act as a write-capable subagent for this Trekoon execution lane.
+
+Epic: <epic-id>
+Lane owner: <lane-name>
+Execute these Trekoon tasks IN ORDER unless task descriptions say parallel
+subtasks are safe:
 - Task <id>: <title>
 - Task <id>: <title>
 
-Before starting each task:
-- claim and assign owner:
-  trekoon --toon task claim <id> --owner <lane-name>
-- append a short start note:
-  trekoon --toon task update <id> --append "Starting implementation"
+Scope:
+- Target files: <paths from task descriptions>
+- Read first: <paths/patterns to inspect before editing>
+- Do not touch: <paths owned by other lanes>
 
-While executing:
-- complete required subtasks, update subtask statuses
-- append meaningful progress notes (do not rewrite the task description)
-- respect the status machine: todo -> in_progress -> done (never skip)
+Before each task:
+- trekoon --toon task claim <id> --owner <lane-name>
+- trekoon --toon task update <id> --append "Starting implementation"
+
+While working:
+- Complete required subtasks and update subtask statuses.
+- Append meaningful progress notes; do not rewrite task descriptions.
+- Respect status flow: todo -> in_progress -> done. Use task done for completion.
+- Assume other agents may edit unrelated files. Do not revert unrelated changes.
 
 On completion:
-- append final verification evidence
-- mark done: trekoon --toon task done <id>
-  (task done auto-transitions from todo/blocked through in_progress)
-- read the response: it includes unblocked downstream tasks and open
-  subtask warnings — report these back
+- Append verification evidence.
+- trekoon --toon task done <id>
+- Read and report unblocked tasks, open subtask warnings, and next candidate.
+- For non-trivial code changes, report review result or review gap.
 
 If blocked:
-- append blocker reason, dependency id, and exact failing command/output
-- set status: trekoon --toon task update <id> --status blocked
+- Append blocker reason, dependency id, and exact failing command/output.
+- trekoon --toon task update <id> --append "Blocked by <reason>" --status blocked
 
-Use --compact to reduce output noise:
-  trekoon --toon --compact task show <id>
+Use --compact in noisy Trekoon reads. Do not create branches, commits, pushes,
+or PRs unless the user explicitly asked and harness policy allows it.
 
-Only create branches, commits, or PRs if the user explicitly requested them and
-the current harness policy allows it. Always report files changed, verification
-results, and blockers.
+Final report: tasks completed, files changed, checks, review result/gap,
+task done response, blockers.
 ```
 
-## Use task done response for orchestration
-
-When a sub-agent calls `task done`, the response includes:
-
-- **`unblocked`**: array of downstream tasks that became ready. Use this to
-  decide what to launch next without re-querying the full readiness graph.
-- **`openSubtaskIds`/`warning`**: if subtasks remain open, decide whether to
-  go back or proceed.
-- **`next`**: the next ready candidate with full tree and blockers.
-
-**Orchestration flow after each task done:**
-
-1. Read `unblocked` from the response.
-2. If unblocked tasks exist, group them by subsystem and dispatch new agents.
-3. If no unblocked tasks, check `next` for the top candidate.
-4. If neither exists, run `suggest --epic <id>` for guidance.
-
-## Auto-recovery
-
-1. Agent attempts to fix failures (has context).
-2. If can't fix, report failure with error output.
-3. Dispatch fix agent with context.
-
-**`status_transition_invalid`** — exact recovery sequence:
-1. Run `trekoon --toon --compact task show <id>` to read the current status.
-2. Append a blocker note: `trekoon --toon task update <id> --append "Blocked: status_transition_invalid from <attempted transition>; current status is <actual>"`.
-3. Identify the valid intermediate transition (see `reference/status-machine.md`).
-4. Apply the correct intermediate step, then retry the intended transition.
-5. Only move on to the next task after the target task reaches the intended status or is explicitly marked `blocked`.
-
-**`dependency_blocked`** — exact recovery sequence:
-1. Run `trekoon --toon --compact task show <id>` to identify which dependency is unmet.
-2. Append a blocker note: `trekoon --toon task update <id> --append "Blocked: dependency_blocked; depends on <dep-id>"`.
-3. Run `trekoon --toon task ready --epic <epic-id>` to get a ready candidate.
-4. Only then continue with the ready candidate — do not retry the blocked task.
-
-## Verify before closing
-
-All checks must pass before marking the epic complete:
-
-### Code review
+## Use `task done` Responses
 
-Run your code-review command/flow. Fix issues before proceeding. Poor DX/UX is
-a bug.
+`task done` returns:
 
-### Automated tests
+- `unblocked`: downstream tasks that became ready.
+- `warning`/`openSubtaskIds`: incomplete subtasks to consciously handle.
+- `next`: next ready candidate.
 
-Run the full test suite. All tests must pass.
+After every completion:
 
-### Manual verification
+1. Dispatch newly unblocked meaningful independent work to subagents when safe.
+2. If no unblocked tasks, inspect `next`.
+3. If neither exists, run `trekoon --toon suggest --epic <epic-id>`.
 
-Automated tests aren't sufficient. Actually exercise the changes:
+## Direct Work Loop
 
-- **API changes:** Curl endpoints with realistic payloads when the environment
-  allows it.
-- **External integrations:** Test against real services when credentials and
-  safe access are available; otherwise record the gap.
-- **CLI changes:** Run actual commands, verify output.
-- **Parser changes:** Feed real data, not just fixtures.
+Use this loop for small, tightly coupled work, or after meaningful independent
+lanes are already delegated.
 
-### DX quality
-
-During manual testing, watch for friction: confusing errors, noisy output,
-inconsistent behavior, rough edges. Fix inline or document for follow-up.
-
-### Record evidence
-
-Append verification results to Trekoon as progress notes:
-
-```bash
-trekoon --toon task update <task-id> --append "All 358 tests pass, lint clean"
-```
-
-### Final progress check
-
-Before closing the epic, confirm completion state:
-
-```bash
-trekoon --toon epic progress <epic-id>
-```
-
-Verify: `doneCount` equals `total`, `todoCount`/`blockedCount`/`inProgressCount`
-are all 0.
-
-## Cleanup
-
-After verification is complete:
-
-1. **Verify all tasks are done:**
+1. Orient:
    ```bash
-   trekoon --toon epic progress <epic-id>
+   trekoon --toon session
+   trekoon --toon session --epic <epic-id>
    ```
-   All tasks must be `done` or clearly `blocked` with reason.
-
-2. **Mark epic done** (already `in_progress` from the start step):
+2. If diagnostics show `recoveryRequired`, stop and run `trekoon --toon init`.
+3. If behind or conflicts exist, resolve sync before claiming work. Load
+   `reference/sync.md` for conflict handling.
+4. Claim:
    ```bash
-   trekoon --toon epic update <epic-id> --status done
+   trekoon --toon task claim <task-id> --owner <name>
    ```
-
-3. **Run suggest to confirm nothing remains:**
+5. Work and append notes:
+   ```bash
+   trekoon --toon task update <task-id> --append "Started implementation"
+   ```
+6. Update important subtasks explicitly:
+   ```bash
+   trekoon --toon subtask claim <subtask-id> --owner <name>
+   trekoon --toon subtask update <subtask-id> --append "Verified with fixture set" --status done
+   ```
+7. Finish or block:
    ```bash
-   trekoon --toon suggest --epic <epic-id>
+   trekoon --toon task update <task-id> --append "Completed implementation and checks"
+   trekoon --toon task done <task-id>
+   trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
    ```
-   Should return no actionable suggestions if the epic is cleanly closed.
+8. Repeat from the returned `unblocked`/`next` data. A fresh `session` is not
+   needed mid-loop unless you need updated diagnostics or switch epics.
 
-4. **Return final execution summary:** completed tasks, remaining blockers,
-    dependency state.
+If `task done` warns about open subtasks, decide whether the task is genuinely
+complete before moving on.
 
-## Architectural fit
+## Recovery
 
-Changes should integrate cleanly with existing patterns. If a change fights the
-architecture, refactor first rather than bolt on. The goal is zero tech debt.
+`status_transition_invalid`:
 
-## Single-agent execution loop
+1. `trekoon --toon --compact task show <id>`
+2. Append the attempted transition and current status.
+3. Load `reference/status-machine.md`.
+4. Apply the valid intermediate transition, then retry.
+5. Continue only after the target task reaches the intended status or is marked
+   `blocked` with reason.
 
-Use this loop when one agent should continue the work directly. The primary loop
-is: **session → claim → work → task done → repeat**.
+`dependency_blocked`:
 
-### 1. Orient with a single call
+1. `trekoon --toon --compact task show <id>`
+2. Append the unmet dependency.
+3. `trekoon --toon task ready --epic <epic-id>`
+4. Continue with a ready candidate. Do not retry the blocked task until its
+   dependency is complete.
 
-```bash
-trekoon --toon session
-```
+## Verify Before Closing
 
-If you already know which epic you are working on, scope the session:
+All applicable checks must pass before marking the epic done.
 
-```bash
-trekoon --toon session --epic <epic-id>
-```
+### Review
 
-`session` returns diagnostics, sync status, the next ready task with subtrees,
-blocker list, and readiness counts in one envelope. Use `--compact` to reduce
-output size when you do not need contract metadata:
+For non-trivial implementation, run a separate review pass before closing the
+task or epic. Prefer a specialized review agent/skill when available. Review
+the actual diff for correctness, regressions, missing tests, security,
+reliability, performance, and integration risks. Tiny docs/mechanical changes
+may skip separate review, but record that decision.
 
-```bash
-trekoon --toon --compact session
-```
+### Tests and Manual Checks
 
-**After session returns, follow this decision tree in order:**
+- Run the relevant automated tests for touched scope.
+- Run broader tests when shared behavior, cross-module contracts, or user flows
+  changed.
+- Exercise CLI/API/parser/integration changes with realistic inputs when
+  possible.
+- Record gaps when credentials or external services are unavailable.
+- Fix confusing errors, noisy output, inconsistent behavior, or rough DX.
 
-1. **`recoveryRequired` is true?** → Stop. Run `trekoon --toon init` and
-   re-check.
-2. **`behind > 0`?** → Sync first: `trekoon --toon sync pull --from main`.
-   This pulls tracker events (not git commits) so task states are current.
-3. **`pendingConflicts > 0`?** → Resolve before claiming work:
-   `trekoon --toon sync conflicts list`. For uniform conflicts, batch resolve:
-   `trekoon --toon sync resolve --all --use ours` (or `--use theirs`). For
-   mixed conflicts, inspect individually with `sync conflicts show <id>` and
-   resolve per-conflict. See `reference/sync.md` for full conflict guidance.
-4. **Session returned a next task?** → Proceed to step 2 (claim work).
-5. **No next task and unsure what to do?** → Run `trekoon --toon suggest` for
-   priority-ranked recommendations (see step 1b below).
-
-### 1b. Get suggestions when stuck
-
-When the session has no clear next task, or you are unsure what action to take:
+Append evidence:
 
 ```bash
-trekoon --toon suggest
-trekoon --toon suggest --epic <epic-id>
+trekoon --toon task update <task-id> --append "Verified: <commands/results>"
+trekoon --toon task update <task-id> --append "Review: <result or accepted gap>"
 ```
 
-`suggest` inspects recovery state, sync status, readiness, and epic progress,
-then returns up to 3 suggestions ranked by priority. Each suggestion includes a
-category (`recovery`, `sync`, `execution`, `planning`), a reason, and a
-ready-to-run command you can execute directly.
-
-Suggest respects the status machine — it will never recommend an invalid
-transition. Use it:
-- At session start when `readyCount` is 0 and you need guidance.
-- Mid-loop when all tasks are blocked and you need to decide what to unblock.
-- Before closing an epic to confirm the right next step.
+## Close The Epic
 
-### 1c. Check epic progress
-
-When you need a quick dashboard before or during work on an epic:
+Before closing:
 
 ```bash
 trekoon --toon epic progress <epic-id>
+trekoon --toon suggest --epic <epic-id>
 ```
 
-Returns done/in_progress/blocked/todo counts, ready task count, and the next
-candidate. Use this:
-- Before starting a work session to gauge how much remains.
-- After completing several tasks to report progress to the user.
-- To decide whether an epic is ready to be marked done.
-
-### 2. Claim work explicitly
-
-Once you know which task to work on, claim it atomically with `task claim`.
-`--owner` is required:
-
-```bash
-trekoon --toon task claim <task-id> --owner <name>
-```
-
-`task claim` sets `status=in_progress` and `owner=<name>` in a single
-compare-and-swap. It succeeds only when the task is in `todo` or `blocked`
-and is not already claimed by a different owner.
-
-For other (non-claim) status transitions such as moving to `blocked`, use
-`task update --status`:
-
-```bash
-trekoon --toon task update <task-id> --status blocked
-```
-
-To update ownership separately (e.g. reassign without claiming):
-
-```bash
-trekoon --toon task update <task-id> --owner alice
-trekoon --toon subtask update <subtask-id> --owner bob
-```
-
-### 3. Work on the task
-
-While working, append progress notes:
-
-```bash
-trekoon --toon task update <task-id> --append "Started implementation"
-trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
-```
-
-### 3b. Work on subtasks explicitly when they matter
-
-Use the same status discipline for subtasks when a task depends on concrete
-subtask progress:
-
-```bash
-trekoon --toon subtask claim <subtask-id> --owner <name>
-trekoon --toon subtask update <subtask-id> --append "Implemented parser branch"
-trekoon --toon subtask update <subtask-id> --append "Verified with fixture set" --status done
-trekoon --toon subtask update <subtask-id> --append "Blocked by <reason>" --status blocked
-```
-
-Use subtasks for real execution units, not filler. If a task has open subtasks
-when `task done` is called, treat the warning as a prompt to consciously decide
-whether the task is genuinely complete.
-
-### 4. Finish or report a block
-
-When done, append a completion note then mark done:
-
-```bash
-trekoon --toon task update <task-id> --append "Completed implementation and checks"
-trekoon --toon task done <task-id>
-```
-
-`task done` works from any non-done status (`todo`, `in_progress`, `blocked`).
-It auto-transitions through `in_progress` when needed. The response includes:
-
-- **Next candidate**: the next ready task with its full tree and blockers.
-- **Unblocked tasks**: downstream tasks that became ready after this completion.
-  Use this to decide what to claim next or to launch parallel work.
-- **Open subtask warning**: if subtasks remain incomplete (completion still
-  proceeds, but the warning is surfaced so you can decide whether to go back).
-
-If blocked instead of done:
+Verify all tasks are `done`, or all remaining work is `blocked` with recorded
+reasons. Then mark the epic done:
 
 ```bash
-trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
+trekoon --toon epic update <epic-id> --status done
 ```
 
-### 5. Repeat
+Return final summary: tasks completed, files changed, verification, review,
+remaining blockers, and dependency state.
 
-After `task done`, the returned next-task envelope is sufficient to continue
-the loop from step 2. A fresh `session` call is not required mid-loop unless
-you need updated diagnostics, sync status, or want to switch epics.
+## Update And Read Policies
 
-Run `session` again at the start of each new conversation session.
+Use descriptions as the durable work log. Append progress instead of rewriting
+descriptions unless the plan itself is wrong.
 
-**When to use each command during the loop:**
+Preferred commands:
 
-| Situation | Command |
+| Need | Command |
 |---|---|
-| Start of session | `session` or `session --epic <id>` |
-| Unsure what to do next | `suggest` or `suggest --epic <id>` |
-| Quick progress check | `epic progress <epic-id>` |
-| Claim a task | `task claim <id> --owner <name>` |
-| Assign ownership | `task update <id> --owner <name>` |
-| Log progress | `task update <id> --append "..."` |
-| Mark done | `task done <id>` |
-| Report blocker | `task update <id> --append "..." --status blocked` |
-| Reduce output noise | Add `--compact` to any command |
-
-## Update policy: prefer append-based progress logging
-
-Use descriptions as the durable work log. For progress updates, append instead
-of rewriting full descriptions.
-
-Status transitions must follow the status machine. Use `in_progress` as the
-intermediate step to reach `done`. Direct `todo → done` is invalid via
-`task update`; use `task done` instead, which auto-transitions.
-
-### Preferred patterns
-
-```bash
-trekoon --toon task claim <task-id> --owner <name>
-trekoon --toon task update <task-id> --append "Started implementation"
-trekoon --toon task update <task-id> --append "Completed implementation and checks"
-trekoon --toon task done <task-id>
-trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
-trekoon --toon task update <task-id> --owner alice
-```
+| Session diagnostics + next task | `trekoon --toon session` |
+| Scoped session | `trekoon --toon session --epic <epic-id>` |
+| Suggestions | `trekoon --toon suggest --epic <epic-id>` |
+| Progress dashboard | `trekoon --toon epic progress <epic-id>` |
+| Next task only | `trekoon --toon task next` |
+| Ready set | `trekoon --toon task ready --epic <epic-id> --limit 50` |
+| Direct blockers | `trekoon --toon dep list <task-id>` |
+| What an item unblocks | `trekoon --toon dep reverse <task-or-subtask-id>` |
+| One task | `trekoon --toon task show <task-id> --all` |
+| One epic tree | `trekoon --toon epic show <epic-id> --all` |
+| Reduce output | Add `--compact` |
 
-### Bulk update rules
+Bulk updates:
 
-- Bulk update is available for `epic update`, `task update`, and
-  `subtask update`.
-- Bulk mode uses `--ids <csv>` or `--all`.
+- Use `--ids <csv>` or `--all`; prefer `--ids`.
 - Bulk mode supports only `--append` and/or `--status`.
 - Do not pass a positional ID in bulk mode.
 - `--append` and `--description` are mutually exclusive.
-- Prefer `--ids` for narrow, explicit updates.
-- Use `--all` only for clear maintenance sweeps or when the user explicitly wants
-  a broad update.
-
-Examples:
-
-```bash
-trekoon --toon task update --ids id1,id2 --append "Waiting on release" --status blocked
-trekoon --toon epic update --ids epic1,epic2 --append "Sprint planning refreshed" --status in_progress
-```
-
-## Read policy: use the smallest sufficient read
-
-Use the narrowest command that answers the question.
-
-| Need | Preferred command |
-|---|---|
-| Session startup (diagnostics + sync + next task) | `trekoon --toon session` |
-| Session scoped to one epic | `trekoon --toon session --epic <epic-id>` |
-| Next-action suggestions | `trekoon --toon suggest` |
-| Epic progress dashboard | `trekoon --toon epic progress <epic-id>` |
-| Next task only | `trekoon --toon task next` |
-| A few ready options | `trekoon --toon task ready --limit 5` |
-| Direct blockers for one task | `trekoon --toon dep list <task-id>` |
-| What this item unblocks | `trekoon --toon dep reverse <task-or-subtask-id>` |
-| One full task payload | `trekoon --toon task show <task-id> --all` |
-| One full epic tree | `trekoon --toon epic show <epic-id> --all` |
-| Repeated text in one scope | `trekoon --toon epic\|task\|subtask search ...` |
-
-Avoid broad scans such as `task list --all` or `epic show --all` when
-`task next`, `task ready`, `dep list`, `dep reverse`, `suggest`, or `search`
-can answer the question more cheaply.
+- Use `--all` only for clear maintenance sweeps or when the user explicitly
+  wants broad updates.