trekoon 0.3.1 → 0.3.2

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

@@ -10,24 +10,71 @@ Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
 This skill is the agent operating guide, not the full CLI reference. Use it to
 pick the right command with the fewest reads and mutations.
 
-## Companion skills
+## Skill arguments
 
-Trekoon is the data layer. Two companion skills handle the plan→execute workflow:
+When invoked with arguments (e.g., `/trekoon <id> [user text]`), resolve the
+argument as a Trekoon entity ID and choose the action based on user intent:
 
-- **writing-plans** — creates implementation plans as Trekoon epics with
-  task/subtask DAGs, dependency edges, file scopes, and owner assignments.
-  Use when: the user asks to plan, design, or architect a feature.
-- **executing-plans** — orchestrates plan execution by spawning sub-agents per
-  subsystem lane, tracking progress via Trekoon, and using `task done` /
-  `suggest` / `epic progress` for flow control.
-  Use when: the user asks to execute, implement, or complete an existing epic.
+### 1. Resolve the entity
+
+```bash
+trekoon --toon epic show <id> 2>/dev/null || \
+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.
+
+### 2. Choose the action
+
+Interpret the user's accompanying text (or lack thereof) to decide what to do:
+
+| User intent signal | Action |
+|---|---|
+| No text, just an ID | Orient: run `session --epic <epic-id>` (or show the task/subtask) and summarize status, readiness, and next steps |
+| "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`, scope session to the entity's epic, and begin the execution loop |
+| "plan", "break down", "design", "architect" | **Plan:** read `reference/planning.md` and create or expand the epic graph |
+
+### Examples
+
+```
+/trekoon abc-123
+  → shows epic/task/subtask abc-123, summarizes status and next candidate
+
+/trekoon abc-123 analyze this epic
+  → runs epic progress, suggest, reports readiness and blockers
+
+/trekoon abc-123 execute
+  → reads execution reference, starts session --epic, begins work loop
+
+/trekoon abc-123 plan the implementation
+  → reads planning reference, decomposes into tasks/subtasks/deps
+```
+
+When the entity is a **task or subtask**, resolve its parent epic ID from the
+entity record and scope session/suggest/progress calls to that epic.
+
+## Reference guides
+
+This skill ships with bundled reference guides for planning and execution. Read
+them when the task calls for it — they extend this command reference with
+methodology and orchestration patterns.
+
+| When | Read | What it covers |
+|---|---|---|
+| User asks to plan, design, or architect a feature | `reference/planning.md` | Decomposition into epic/task/subtask DAGs, writing standard, file scopes, owner assignment, dependency modeling, validation |
+| User asks to execute, implement, or complete an epic | `reference/execution.md` | Execution graph building, lane grouping, sub-agent dispatch, task done orchestration, verification, cleanup |
+| User asks to execute task with Agent Team (or just team) AND Agent Teams are available (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`) | `reference/execution-with-team.md` | TeamCreate/SendMessage pattern, teammate spawning, team coordination, shutdown |
 
 **Typical flow:**
-1. `writing-plans` creates the epic with tasks, subtasks, deps, owners.
-2. `executing-plans` runs `session --epic`, builds lane groups, dispatches
-   agents, uses `task done` responses to orchestrate waves.
-3. This skill (trekoon) is loaded by both — it provides the command reference
-   and status machine rules that both skills rely on.
+1. Read `reference/planning.md` and create the epic with tasks, subtasks, deps,
+   owners.
+2. Read `reference/execution.md` (or `reference/execution-with-team.md` for Agent
+   Teams), run `session --epic`, build lane groups, dispatch agents, use
+   `task done` responses to orchestrate waves.
+3. This file (SKILL.md) provides the command reference and status machine rules
+   that both planning and execution rely on.
 
 ## Non-negotiable defaults
 
@@ -64,6 +111,35 @@ non-done status.
 Recommended statuses for consistent workflows: `todo`, `in_progress`, `done`.
 Use `blocked` with an appended reason when work is stuck.
 
+## Epic lifecycle
+
+The orchestrator is responsible for managing the epic's status throughout
+execution. Epics follow the same status machine as tasks — they must transition
+through `in_progress` to reach `done`.
+
+### Start: mark epic `in_progress`
+
+Immediately after session bootstrap and before dispatching any work, transition
+the epic:
+
+```bash
+trekoon --toon epic update <epic-id> --status in_progress
+```
+
+This ensures the epic reflects actual state even if execution is interrupted.
+
+### Finish: mark epic `done`
+
+After all tasks are verified done (see cleanup in execution references), mark
+the epic complete:
+
+```bash
+trekoon --toon epic update <epic-id> --status done
+```
+
+Since the epic is already `in_progress` from the start step, this is a single
+valid transition.
+
 ## Default agent loop
 
 The primary loop is: **session → claim → work → task done → repeat**.
@@ -466,3 +542,39 @@ Cross-branch sync matters before merging a feature branch back:
 Trekoon stores local state in `.trekoon/trekoon.db`. In git repos and
 worktrees, storage resolves from the shared repository root rather than each
 worktree independently.
+
+## Tool selection
+
+Check your available tool list to determine which harness you are running in.
+
+### Core tools (both harnesses)
+
+| Purpose | Claude Code | OpenCode |
+|---------|------------|----------|
+| File search | `Glob` | `glob` |
+| Content search | `Grep` | `grep` |
+| Read files | `Read` | `read` |
+| Edit files | `Edit` | `edit` |
+| Write files | `Write` | `write` |
+| Shell commands | `Bash` | `bash` |
+| Ask user | `AskUserQuestion` | `question` |
+| Web fetch | `WebFetch` | `webfetch` |
+| Web search | `WebSearch` | `websearch` |
+| Directory listing | `Bash(ls)` | `list` |
+
+### LSP tools (OpenCode only — use if available)
+
+- `lsp goToDefinition`/`lsp findReferences`: navigate symbols safely.
+- `lsp hover`: inspect type signatures.
+- `lsp documentSymbol`/`lsp workspaceSymbol`: search symbols.
+- `lsp goToImplementation`: find interface implementations.
+
+**Fallbacks:** use `Grep`/`grep` for symbols, `Bash`/`bash` for compiler
+diagnostics.
+
+### General guidance
+
+- Do not overuse bash for searching/reading; prefer dedicated tools.
+- Use LSP over grep for symbol navigation when available.
+- Run Trekoon, git, build/lint/test, and verification commands via `Bash`/`bash`.
+- Use `--compact` on Trekoon commands in sub-agent prompts to reduce token usage.

package/.agents/skills/trekoon/reference/execution-with-team.md

@@ -0,0 +1,213 @@
+# Execution with Agent Teams Reference
+
+**You are a team lead orchestrator.** Execute work from Trekoon using Agent
+Teams — real parallel Claude Code instances coordinated via TeamCreate,
+TaskCreate, SendMessage, and shared task lists. Each teammate runs in its own
+tmux pane.
+
+**Prerequisite:** Agent Teams requires the Claude Code environment variable
+`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` set to `"true"`. This feature is Claude
+Code only — it is not available in OpenCode or other harnesses.
+
+- [Claude Agent Teams documentation](https://code.claude.com/docs/en/agent-teams.md)
+
+**Clarify ambiguity upfront.** If the plan has unclear requirements or meaningful
+tradeoffs, ask the user before starting.
+
+## Build the execution graph
+
+Same as the standard execution reference — use `task ready`, `dep reverse`, and
+lane grouping to construct a runnable graph. See `reference/execution.md` for
+the full scheduler loop and lane grouping rules.
+
+## Mark epic in-progress
+
+Before dispatching any work, transition the epic so it reflects actual state:
+
+```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`.
+
+## Create the team
+
+Use **TeamCreate** to set up the team, then **TaskCreate** to populate the
+shared task list, then **Agent** with `team_name` to spawn teammates.
+
+### Step 1: Create the team
+
+```
+TeamCreate:
+  team_name: "<epic-slug>"
+  description: "Executing epic <epic-id>: <title>"
+```
+
+### Step 2: Create tasks in the shared task list
+
+For each task group from the execution graph, create a task:
+
+```
+TaskCreate:
+  subject: "<lane description>: <task-ids/titles>"
+  description: |
+    Execute these Trekoon tasks IN ORDER unless task description says
+    parallel subtasks:
+    - Task <id>: <title>
+    - Task <id>: <title>
+
+    Before starting each task:
+    - claim 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"
+
+    While executing:
+    - complete required subtasks, update subtask statuses
+    - append meaningful progress notes (do not rewrite task description)
+    - respect the status machine: todo -> in_progress -> done (never skip)
+    - use --compact to reduce output noise:
+      trekoon --toon --compact task show <id>
+
+    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 via SendMessage
+
+    If blocked:
+    - append blocker reason, dependency id, and exact failing command/output
+    - set status: trekoon --toon task update <id> --status blocked
+    - notify team lead via SendMessage with blocker details
+
+    Commit after each edit tool usage.
+    Report: files changed, test results
+
+    **Commit format**:
+      <imperative verb> <what changed>     <- Line 1: max 50 chars
+      <blank line>                         <- Line 2: blank
+      <why/context, one point per line>    <- Body: max 72 chars per line
+```
+
+Use `blockedBy` via TaskUpdate to set dependencies between tasks that require
+sequential execution.
+
+### Step 3: Spawn teammates
+
+For each parallel lane, spawn a teammate using the Agent tool:
+
+```
+Agent:
+  name: "developer-1"
+  team_name: "<epic-slug>"
+  subagent_type: "general-purpose"
+  description: "<lane>: <task titles>"
+  prompt: |
+    You are a developer on team "<epic-slug>".
+    Check TaskList for your assigned tasks and work through them.
+    Use TaskUpdate to claim tasks (set owner to your name) and mark
+    them completed.
+
+    Status machine rules:
+    - todo -> in_progress -> done (valid)
+    - todo -> done (INVALID — use task done which auto-transitions)
+    - in_progress -> blocked (valid, with reason)
+    - blocked -> in_progress (valid, to resume)
+
+    When you complete a Trekoon task with `task done`, read the response:
+    - unblocked: tasks that became ready — report via SendMessage
+    - warning: open subtasks — report via SendMessage
+    - next: next ready candidate
+
+    Communicate with teammates via SendMessage if you need coordination.
+    After completing a task, check TaskList for the next available task.
+```
+
+**Teammate count:** 3-5 teammates for most epics. Don't over-parallelize.
+
+**Agent types:**
+- Use `general-purpose` for implementation work (has edit/write/bash access)
+- Use `Explore` or `Plan` only for read-only research or planning tasks
+
+## Coordinate as team lead
+
+Your job as team lead:
+
+1. **Monitor progress** — teammates send messages when they complete tasks or
+   hit blockers.
+2. **Use task done responses** — when a teammate reports `unblocked` tasks from
+   a `task done` response, create new team tasks via TaskCreate for the
+   unblocked work and assign to idle teammates.
+3. **Unblock work** — when a teammate reports a blocker, help resolve it or
+   reassign.
+4. **Assign ownership** — use TaskUpdate with `owner` to assign tasks to idle
+   teammates. Also set Trekoon owner:
+   ```bash
+   trekoon --toon task update <task-id> --owner <teammate-name>
+   ```
+5. **Send messages** — use SendMessage to direct teammates, never plain text
+   output.
+6. **Check progress** — periodically run `epic progress` to gauge completion:
+   ```bash
+   trekoon --toon epic progress <epic-id>
+   ```
+7. **Get suggestions when stuck** — when all teammates are blocked:
+   ```bash
+   trekoon --toon suggest --epic <epic-id>
+   ```
+
+## Auto-recovery
+
+1. If status update fails with `status_transition_invalid`, check current status
+   and use the valid intermediate transition.
+2. If status update fails with `dependency_blocked`, refresh with
+   `task ready`/`task next` and continue with a ready candidate.
+3. Teammate attempts to fix failures (has context).
+4. If can't fix, teammate reports failure with error output via SendMessage.
+5. Dispatch fix instructions via SendMessage to the teammate.
+6. Same error twice -> stop and ask user.
+
+## Verify and close
+
+Same verification steps as the standard execution reference: code review,
+automated tests, manual verification, DX quality, record evidence, final
+progress check. See `reference/execution.md` for details.
+
+## Shutdown and cleanup
+
+After all work is verified:
+
+1. **Check everything is done:**
+   ```bash
+   trekoon --toon epic progress <epic-id>
+   ```
+
+2. **Confirm nothing remains:**
+   ```bash
+   trekoon --toon suggest --epic <epic-id>
+   ```
+   Should return no actionable suggestions.
+
+3. **Mark epic done** (already `in_progress` from the start step):
+   ```bash
+   trekoon --toon epic update <epic-id> --status done
+   ```
+
+4. **Shutdown teammates** — send `shutdown_request` via SendMessage to each.
+5. **Delete the team** — use TeamDelete to clean up team and task directories.
+6. Merge branch to main (if using branches).
+7. Remove worktree (if using worktrees).
+8. Return final execution summary: completed tasks, remaining blockers,
+   dependency state.
+
+## Team orchestration tools
+
+| Purpose | Tool |
+|---------|------|
+| Create the team | `TeamCreate` |
+| Manage shared task list | `TaskCreate` / `TaskList` / `TaskUpdate` / `TaskGet` |
+| Spawn teammates | `Agent` (with `team_name`) |
+| Communicate | `SendMessage` |
+| Clean up | `TeamDelete` |

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

@@ -0,0 +1,210 @@
+# 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.
+
+**Clarify ambiguity upfront.** If the plan has unclear requirements or meaningful
+tradeoffs, ask the user before starting.
+
+## 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
+
+Batch ready tasks by subsystem/domain to minimize repeated context loading:
+
+```
+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.
+
+**Parallel:** Groups touch different subsystems.
+**Sequential:** Groups have dependency edges between them.
+
+## Mark epic in-progress
+
+Before dispatching any work, transition the epic so it reflects actual state:
+
+```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`.
+
+## Dispatch sub-agents
+
+For each parallel lane group, spawn a sub-agent with a prompt like:
+
+```
+Execute these Trekoon tasks IN ORDER unless task description says parallel
+subtasks:
+- 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"
+
+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)
+
+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
+
+If blocked:
+- append blocker reason, dependency id, and exact failing command/output
+- set status: trekoon --toon task update <id> --status blocked
+
+Use --compact to reduce output noise:
+  trekoon --toon --compact task show <id>
+
+Commit after each edit. Report: files changed, test results.
+```
+
+## 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.
+4. Same error twice -> stop and ask user.
+
+If a status update fails with `status_transition_invalid`, check current status
+and transition through the valid intermediate step.
+
+If a status update fails with `dependency_blocked`, refresh with
+`task ready`/`task next` and continue with a ready candidate.
+
+## Verify before closing
+
+All checks must pass before marking the epic complete:
+
+### Code review
+
+Run your code-review command/flow. Fix issues before proceeding. Poor DX/UX is
+a bug.
+
+### Automated tests
+
+Run the full test suite. All tests must pass.
+
+### Manual verification
+
+Automated tests aren't sufficient. Actually exercise the changes:
+
+- **API changes:** Curl endpoints with realistic payloads.
+- **External integrations:** Test against real services.
+- **CLI changes:** Run actual commands, verify output.
+- **Parser changes:** Feed real data, not just fixtures.
+
+### 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 committing and verifying:
+
+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. **Create a branch** for the work unless trivial. Merge branch to main when
+   done.
+
+5. **Return final execution summary:** completed tasks, remaining blockers,
+   dependency state.
+
+## Architectural fit
+
+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.