trekoon 0.4.1 → 0.4.3

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

@@ -1,227 +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`).
-
-## Group tasks into lanes
+```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?
+```
 
-Batch ready tasks by subsystem/domain to minimize repeated context loading:
+## Build The Graph
 
-```
-Without: Task 1 (auth/login)  -> Agent 1 [explores auth/]
-         Task 2 (auth/logout) -> Agent 2 [explores auth/ again]
+Use scheduler reads before broad tree reads:
 
-With:    Tasks 1-2 (auth/*)   -> Agent 1 [explores once, executes both]
+```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
 ```
 
-| 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 |
+Group ready tasks by lane:
 
-**Limits:** 3-4 tasks max per group. Split if larger.
+- Same directory prefix.
+- Same subsystem/domain.
+- Same owner.
+- Same implementation context.
 
-**Parallel:** Groups touch different subsystems.
-**Sequential:** Groups have dependency edges between them.
+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.
 
-## Mark epic in-progress
-
-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:
-- set status to in_progress and assign owner:
-  trekoon --toon task update <id> --status in_progress --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:
+## Use `task done` Responses
 
-- **`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.
+`task done` returns:
 
-**Orchestration flow after each task done:**
+- `unblocked`: downstream tasks that became ready.
+- `warning`/`openSubtaskIds`: incomplete subtasks to consciously handle.
+- `next`: next ready candidate.
 
-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.
+After every completion:
 
-## Auto-recovery
+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>`.
 
-1. Agent attempts to fix failures (has context).
-2. If can't fix, report failure with error output.
-3. Dispatch fix agent with context.
-4. Same error twice -> stop and ask user.
+## Direct Work Loop
 
-If a status update fails with `status_transition_invalid`, check current status
-and transition through the valid intermediate step.
+Use this loop for small, tightly coupled work, or after meaningful independent
+lanes are already delegated.
 
-If a status update fails with `dependency_blocked`, refresh with
-`task ready`/`task next` and continue with a ready candidate.
+1. Orient:
+   ```bash
+   trekoon --toon session
+   trekoon --toon session --epic <epic-id>
+   ```
+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 task claim <task-id> --owner <name>
+   ```
+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 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
+   ```
+8. Repeat from the returned `unblocked`/`next` data. A fresh `session` is not
+   needed mid-loop unless you need updated diagnostics or switch epics.
 
-## Verify before closing
+If `task done` warns about open subtasks, decide whether the task is genuinely
+complete before moving on.
 
-All checks must pass before marking the epic complete:
+## Recovery
 
-### Code review
+`status_transition_invalid`:
 
-Run your code-review command/flow. Fix issues before proceeding. Poor DX/UX is
-a bug.
+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.
 
-### Automated tests
+`dependency_blocked`:
 
-Run the full test suite. All tests must pass.
+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.
 
-### Manual verification
+## Verify Before Closing
 
-Automated tests aren't sufficient. Actually exercise the changes:
+All applicable checks must pass before marking the epic done.
 
-- **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.
+### Review
 
-### DX quality
+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.
 
-During manual testing, watch for friction: confusing errors, noisy output,
-inconsistent behavior, rough edges. Fix inline or document for follow-up.
+### Tests and Manual Checks
 
-### Record evidence
+- 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.
 
-Append verification results to Trekoon as progress notes:
+Append evidence:
 
 ```bash
-trekoon --toon task update <task-id> --append "All 358 tests pass, lint clean"
+trekoon --toon task update <task-id> --append "Verified: <commands/results>"
+trekoon --toon task update <task-id> --append "Review: <result or accepted gap>"
 ```
 
-### Final progress check
+## Close The Epic
 
-Before closing the epic, confirm completion state:
+Before closing:
 
 ```bash
 trekoon --toon epic progress <epic-id>
+trekoon --toon suggest --epic <epic-id>
 ```
 
-Verify: `doneCount` equals `total`, `todoCount`/`blockedCount`/`inProgressCount`
-are all 0.
-
-## Cleanup
-
-After verification is complete:
+Verify all tasks are `done`, or all remaining work is `blocked` with recorded
+reasons. Then mark the epic done:
 
-1. **Verify all tasks are done:**
-   ```bash
-   trekoon --toon epic progress <epic-id>
-   ```
-   All tasks must be `done` or clearly `blocked` with reason.
-
-2. **Mark epic done** (already `in_progress` from the start step):
-   ```bash
-   trekoon --toon epic update <epic-id> --status done
-   ```
-
-3. **Run suggest to confirm nothing remains:**
-   ```bash
-   trekoon --toon suggest --epic <epic-id>
-   ```
-   Should return no actionable suggestions if the epic is cleanly closed.
-
-4. **Return final execution summary:** completed tasks, remaining blockers,
-    dependency state.
-
-## Architectural fit
+```bash
+trekoon --toon epic update <epic-id> --status done
+```
 
-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.
+Return final summary: tasks completed, files changed, verification, review,
+remaining blockers, and dependency state.
+
+## Update And Read Policies
+
+Use descriptions as the durable work log. Append progress instead of rewriting
+descriptions unless the plan itself is wrong.
+
+Preferred commands:
+
+| Need | Command |
+|---|---|
+| 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 updates:
+
+- 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.
+- Use `--all` only for clear maintenance sweeps or when the user explicitly
+  wants broad updates.

package/.agents/skills/trekoon/reference/harness-primitives.md

@@ -0,0 +1,77 @@
+# Harness Primitives
+
+Use these intent-level primitives across Codex, Claude Code, OpenCode, Pi, and
+similar harnesses. Trekoon is durable state; harness-local todo/task tools are
+only live session display.
+
+| Need | Instruction |
+|---|---|
+| Orient | Read Trekoon session/progress/suggest for ready work and blockers. |
+| Display progress | Use local todo/task tools for the current execution shape and lane status. |
+| Ask | Use the harness question tool when available; otherwise ask one concise plain-text question. |
+| Delegate | When executing an epic, use subagents by default for meaningful work that can run independently. |
+| Explore | Use read-only/explorer subagents for noisy codebase lookup, logs, or research. |
+| Execute | Use write-capable worker/general subagents for bounded implementation lanes. |
+| Test | Run the required automated or manual checks for touched scope. |
+| Review | Use a review agent/skill for non-trivial code changes when available. |
+| Record | Append progress, blockers, tests, review, and completion evidence to Trekoon. |
+
+## Delegation Default
+
+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 the parent session to coordinate the epic, make dependency decisions, keep
+the user oriented, and synthesize results.
+
+Treat "execute this epic", "work through this Trekoon plan", "use agents",
+"spawn subagents", "delegate independent lanes", "execute with subagents",
+"parallelize this", and "team execute" as requests to orchestrate work to
+completion. If safe independent lanes exist and the harness supports subagents,
+delegate those lanes by default.
+
+If a higher-priority harness policy blocks subagents without explicit user
+wording, tell the user immediately:
+
+```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?
+```
+
+## Runtime Notes
+
+- Codex: use subagents by default when exposed. If Codex policy requires
+  explicit user wording, ask immediately before broad execution. Do not silently
+  do broad work in the parent. When available, use `spawn_agent`, `send_input`,
+  `wait_agent`, `resume_agent`, and `close_agent`.
+- Claude Code: use normal subagents for bounded side work. Use Agent Teams only
+  when the user explicitly asks for team execution and the environment supports
+  it.
+- OpenCode: use `@explore` for read-only discovery and `@general` or native
+  Task for write-capable lane work. Use `question` when available.
+- Pi/other harnesses: use the same intent and native task/subagent/question
+  tools when available.
+
+## Local Task Tools
+
+Use local todo/task tools to show only current-session coordination:
+
+1. Execution shape and lane list.
+2. Lane status: pending, in progress, blocked, review, done.
+3. Short enough to stay readable.
+
+If local state and Trekoon disagree, Trekoon wins.
+
+## Review
+
+For non-trivial implementation, run a separate review pass before closing the
+task or epic. Prefer a specialized review agent/skill. Review the actual diff
+for correctness, regressions, missing tests, security, reliability, performance,
+and integration risk.
+
+Tiny docs/mechanical changes may skip separate review. Still run relevant
+checks and record the review gap or decision:
+
+```bash
+trekoon --toon task update <task-id> --append "Review: <summary or accepted gap>"
+```