trekoon 0.4.2 → 0.4.4

package/.agents/skills/trekoon/SKILL.md

@@ -5,60 +5,43 @@ description: "Use for Trekoon-based planning and execution: creating epics, task
 
 # Trekoon Skill
 
-Trekoon is a local-first execution harness for tracked implementation work.
-Treat Trekoon as the source of truth for plans, progress, blockers, readiness,
-and orchestration state.
+Trekoon is the source of truth for tracked implementation work: plans,
+readiness, owners, blockers, progress, verification evidence, and completion.
+Use this file as the router. Load references only when the current mode needs
+them.
 
-This skill is the operating guide, not the full CLI reference. Use it to route
-into the right mode quickly, keep momentum, and finish work rather than
-stalling in analysis.
+## Mode Contracts
 
-## Operating contract
+- `trekoon plan <goal>`: create an execution-ready epic in Trekoon.
+- `trekoon <id>`: orient on the epic/task/subtask and report current state,
+  blockers, and next action.
+- `trekoon <id> execute`: own the epic until it is done, hard-blocked, or needs
+  user input. Use subagents by default for meaningful work that can run
+  independently when the harness exposes them.
+- `trekoon <id> team execute`: same completion contract, using Claude Agent
+  Teams only when the user explicitly asks and the environment supports it.
 
-Treat these entrypoints as hard mode contracts:
+Do not stop at analysis when Trekoon shows ready work. Do not invent a parallel
+plan outside Trekoon.
 
-- `trekoon plan <goal>` → create an **execution-ready epic** in Trekoon.
-- `trekoon <epic-id>` → **orient** on the current state and report the next
-  concrete action.
-- `trekoon <epic-id> execute` → **own the epic until it is done, hard-blocked,
-  or requires user input**.
-- `trekoon <epic-id> team execute` → same execution contract, but use Agent
-  Teams only when the environment supports it and the user explicitly wants it.
+## Load Rules
 
-Reading `reference/planning.md` or `reference/execution.md` is a required setup
-step for those modes, not the end of the workflow.
-
-## Trigger guidance
-
-Use this skill whenever the user wants tracked planning or tracked execution in
-Trekoon, for example:
-
-- break a feature into epics, tasks, subtasks, or dependencies
-- create backlog or sprint-ready work items
-- check epic/task status, progress, readiness, or blockers
-- execute a Trekoon epic end to end with sub-agents
-- coordinate parallel implementation lanes from tracked work
-
-Do **not** use this skill for generic coding work that is not meant to be
-tracked in Trekoon.
-
-## Command router
-
-When invoked with arguments, determine the mode first, then load only the
-reference needed for that mode.
-
-### 1. Route by first argument
+| Situation | Load |
+|---|---|
+| Any Trekoon request | This file |
+| Plan, break down, design tracked work | `reference/harness-primitives.md`, then `reference/planning.md` |
+| Execute, implement, complete tracked work | `reference/harness-primitives.md`, then `reference/execution.md` |
+| User explicitly asks for Claude team execution | `reference/harness-primitives.md`, then `reference/execution-with-team.md` |
+| Sync gaps, conflicts, shared-storage questions | `reference/sync.md` |
+| Status transition error or status uncertainty | `reference/status-machine.md` |
 
-| Command shape | Mode | Required read | Completion target |
-|---|---|---|---|
-| `trekoon plan <goal>` | Plan | `reference/planning.md` | Epic exists, graph is validated, next-wave summary is returned |
-| `trekoon <epic-id>` | Orient | None beyond this file unless needed | User knows current state, next ready action, and blockers |
-| `trekoon <epic-id> execute` | Execute | `reference/execution.md` | Epic is done, all remaining work is blocked, or user input is required |
-| `trekoon <epic-id> team execute` | Team execute | `reference/execution-with-team.md` | Same as execute, using Agent Teams |
+`reference/harness-primitives.md` is required before planning or execution
+because those modes may need local task displays, user questions, subagents,
+review agents, testing tools, and Trekoon evidence recording.
 
-### 2. Resolve entity IDs when present
+## Route Input
 
-If the first argument is not `plan`, resolve it as a Trekoon entity:
+Resolve the first non-mode argument as an epic, task, or subtask:
 
 ```bash
 trekoon --toon epic show <id> 2>/dev/null || \
@@ -66,173 +49,79 @@ trekoon --toon task show <id> 2>/dev/null || \
 trekoon --toon subtask show <id> 2>/dev/null
 ```
 
-If none match, tell the user the ID was not found.
-
-When the entity is a **task or subtask**, resolve its parent epic ID from the
-entity record and scope `session`, `suggest`, and `epic progress` to that epic.
-If the user asked to execute a task or subtask, make forward progress on that
-requested entity first; continue broader epic execution only if that matches the
-user's intent.
-
-### 3. Interpret missing or extra text
+If the ID is a task or subtask, resolve its parent epic and scope `session`,
+`suggest`, and `epic progress` to that epic. If the user asked to execute a task
+or subtask, start with that item; continue broader epic execution only when it
+matches the user intent.
 
-| User intent signal | Action |
+| User signal | Mode |
 |---|---|
-| No text, just an ID | **Orient:** run `session --epic <epic-id>` (or show the task/subtask), summarize status, readiness, and next action |
-| `analyze`, `review`, `check`, `status`, `progress` | **Analyze:** run `epic progress <id>` or `task show <id> --all`, then `suggest --epic <id>`, and report findings |
-| `execute`, `implement`, `do`, `complete`, `start`, `run` | **Execute:** read `reference/execution.md`, choose single-agent vs orchestrated execution, and keep going until the mode contract is satisfied |
-| `team execute`, `execute with team` | **Team execute:** read `reference/execution-with-team.md` only when Agent Teams are available |
-| `plan`, `break down`, `design`, `architect` | **Plan:** read `reference/planning.md` and create or expand the epic graph |
-
-### Examples
-
-```text
-trekoon plan build a dependency-aware release workflow
-  → reads planning reference, creates a validated epic, returns epic ID + wave summary
-
-trekoon abc-123
-  → orients on epic/task/subtask abc-123, summarizes state and next action
-
-trekoon abc-123 execute
-  → reads execution reference, starts the execution loop, keeps going until done or blocked
-
-trekoon abc-123 team execute
-  → reads team execution reference, starts Agent Teams orchestration if supported
-```
-
-## Reference guides
-
-Read references lazily based on mode.
-
-> **Path note:** Script paths below are relative to this skill's folder (where this SKILL.md lives), not the current project root. Resolve them from this skill folder when invoking Bash.
-
-| Mode | Read | Use it for |
-|---|---|---|
-| Plan | `reference/planning.md` | Converting a goal into a real epic/task/subtask dependency graph with validation and handoff. Includes creation policy, search/replace policy. |
-| Execute | `reference/execution.md` | Running an epic end to end, choosing lanes, dispatching sub-agents, recording evidence, closing the epic. Includes single-agent loop, update policy, read policy. |
-| Team execute | `reference/execution-with-team.md` | Agent Teams coordination via TeamCreate/TaskCreate/SendMessage when the environment supports it |
-| Status machine | `reference/status-machine.md` | Canonical status transition table |
-| Sync | `reference/sync.md` | Cross-branch sync, conflict resolution, shared-database model, worktree diagnostics |
-
-## Mode completion rules
-
-These stop conditions are the core contract for the skill.
-
-- **Plan mode** is complete only when the epic has been created in Trekoon,
-  tasks/subtasks/dependencies exist, validation passes, and the user receives
-  the epic ID plus an execution-ready summary.
-- **Orient mode** is complete when the user has the current state, ready work,
-  blockers, and the most likely next command.
-- **Execute mode** is complete only when one of these is true:
-  1. the epic is fully completed and marked `done`
-  2. all remaining work is blocked and blockers are recorded in Trekoon
-  3. a real ambiguity, approval, or external dependency requires user input
-
-## Anti-stall rules
-
-- Do not stop after `session`, `suggest`, or `epic progress` if a clear next
-  action exists.
-- Do not stop after completing one task if more ready work exists.
-- After each `task done`, inspect `unblocked` and `next` to decide the next
-  move immediately.
-- If multiple independent tasks are ready and isolation is safe, group them by
-  lane and delegate.
-- Ask the user only when the work is genuinely blocked by ambiguity, approval,
-  or missing external access.
-
-## Clarification tool rule
-
-When planning or execution needs user input, use the harness's user-question
-tool rather than burying the question inside narration:
-
-- OpenCode: `question`
-- Claude Code: `AskUserQuestion`
-
-Ask narrow, decision-shaping questions. Prefer one clear question with concrete
-options over a broad list of speculative unknowns.
-
-## Non-negotiable defaults
-
-- Always include `--toon` on every Trekoon command.
-- Prefer the smallest sufficient scope.
-- Prefer transactional bulk commands over many single-item commands.
-- Prefer `--append` for progress notes, completion notes, and blocker notes.
-- Preview replace before `--apply`.
-- Prefer `--ids` over `--all` for bulk updates.
-- Treat Trekoon state updates as part of the workflow, not as after-the-fact
-  bookkeeping.
-- Never edit `.trekoon/trekoon.db` directly.
-- Treat `.trekoon` as shared repo-scoped operational state in git worktrees.
-- Keep `.trekoon` gitignored; do not commit the SQLite DB as a recovery fix.
-- Never run `trekoon wipe --yes --toon` unless the user explicitly asks for it.
-- Create branches, commits, merges, or PRs only when the user explicitly asks
-  and the current harness policy allows it.
-
-## Status machine
-
-See `reference/status-machine.md` for the canonical transition table and
-`task done` auto-transition exception.
-
-## Epic lifecycle
-
-Epics follow the same status machine as tasks — they must transition through
-`in_progress` to reach `done`.
-
-```bash
-# Start: mark epic in_progress before dispatching any work
-trekoon --toon epic update <epic-id> --status in_progress
-
-# Finish: mark epic done after all tasks are verified done
-trekoon --toon epic update <epic-id> --status done
-```
-
-## Execution mode selection
-
-Choose the lightest mode that will still move the work forward.
-
-| Situation | Mode | First move |
-|---|---|---|
-| One ready task, narrow scope, or user asked to continue personally | Single-agent execution | `session --epic <epic-id>` |
-| Multiple ready tasks across separable subsystems or owners | Orchestrated execution | Read `reference/execution.md`, then `task ready --epic <epic-id> --limit 50` |
-| User explicitly asked for team execution and Agent Teams are available | Team execution | Read `reference/execution-with-team.md` |
-
-Single-agent loop shape: **session → claim → work → task done → repeat**.
-Read `reference/execution.md` for the full loop, including subtask discipline,
-update/recovery policy, and the canonical command sequences.
-
-## Delegation policy
-
-Prefer one sub-agent per execution lane, not one sub-agent per tiny task.
-
-- Spawn sub-agents when 2+ ready tasks are independent, touch different
-  subsystems, or can be grouped into bounded lanes.
-- Keep each lane small enough to verify and report clearly.
-- Avoid delegation when the scope is tiny, the tasks are tightly coupled, or the
-  overhead exceeds the gain.
-- When tasks share the same directory roots, owners, or subsystem context, group
-  them into one lane.
-
-## Setup and fallback
-
-If Trekoon is unavailable or storage diagnostics require repair:
+| ID only | Orient: `session --epic <epic-id>` or show the item |
+| `status`, `progress`, `analyze`, `review`, `check` | Analyze: `epic progress`, targeted show, then `suggest --epic` |
+| `plan`, `break down`, `design`, `architect` | Plan |
+| `execute`, `implement`, `do`, `complete`, `start`, `run` | Execute |
+| `team execute`, `execute with team` | Team execute |
+
+## Completion Rules
+
+- Plan mode is complete only when the epic exists, tasks/subtasks/dependencies
+  exist in Trekoon, the graph is validated, and the user gets the epic ID plus
+  first execution wave.
+- Orient mode is complete when the user knows current state, blockers, ready
+  work, and the likely next command.
+- Execute mode is complete only when the epic is marked `done`, all remaining
+  work is blocked with recorded reasons, or real user input is required.
+
+## Execution Defaults
+
+- Start with `trekoon --toon session`; scope with `--epic <id>` when known.
+- If ready work exists, keep moving. After each `task done`, inspect
+  `unblocked`, `warning`/`openSubtaskIds`, and `next`.
+- 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. Your job is to finish the epic, not personally perform
+  every implementation step.
+- If a higher-priority harness rule blocks subagents without explicit user
+  wording, ask immediately and explain that Trekoon execution preserves the
+  parent context for orchestration.
+- For non-trivial implementation, run relevant tests and a separate review pass
+  when a review agent/skill is available. Record checks and review results in
+  Trekoon before closing work.
+
+## Non-Negotiables
+
+- Use `--toon` on every Trekoon command.
+- Treat Trekoon updates as workflow state, not after-the-fact bookkeeping.
+- Prefer smallest sufficient reads: `session`, `suggest`, `task ready`,
+  `task next`, `dep list`, `dep reverse`, targeted `show`.
+- Prefer transactional/bulk commands for planning and narrow `--ids` for bulk
+  updates.
+- Append progress, verification, and blocker notes with `--append`; do not
+  rewrite descriptions unless fixing the plan itself.
+- Preview search/replace before `--apply`.
+- Never edit `.trekoon/trekoon.db` directly. Keep `.trekoon` gitignored.
+- Never run `trekoon wipe --yes --toon` unless the user explicitly asks.
+- Create branches, commits, merges, pushes, or PRs only when the user explicitly
+  asks and the harness policy allows it.
+- Use `--compact` in subagent prompts and noisy reads.
+
+## Status Reminder
+
+Normal status flow is `todo -> in_progress -> done`; `blocked` requires an
+appended reason. Use `task done` for task completion because it auto-transitions
+from `todo` or `blocked` through `in_progress`. Load
+`reference/status-machine.md` for transition errors or uncertainty.
+
+## Recovery
+
+If Trekoon diagnostics show `recoveryRequired`, stop task selection and run:
 
 ```bash
 trekoon --toon init
 trekoon --toon sync status
-trekoon --toon quickstart
-trekoon --toon help sync
 ```
 
-Re-bootstrap first, then re-read diagnostics. Do not continue with task
-selection after missing shared storage or broken bootstrap.
-
-## Tool capability guidance
-
-- Use your harness's structured file search and file read tools for code
-  inspection whenever possible.
-- Use symbol-aware tools when available; fall back to content search otherwise.
-- Run Trekoon commands, build/lint/test flows, and explicit git operations via
-  your shell tool.
-- Use `--compact` on Trekoon commands in sub-agent prompts to reduce token usage.
-
-## User manual input:
+If sync is behind or conflicts exist, resolve that before claiming work. Load
+`reference/sync.md` for conflict handling.