trekoon 0.3.0 → 0.3.2

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.

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

@@ -0,0 +1,244 @@
+# Planning Reference
+
+Write implementation plans directly into Trekoon as epics with task/subtask
+DAGs. Plans must be directly executable without re-interpretation.
+
+**Clarify ambiguity upfront.** If the plan has unclear requirements or meaningful
+tradeoffs, ask the user before writing. Present options with clear tradeoffs.
+Use multi-select for independent features that can be combined; use single-select
+for mutually exclusive choices.
+
+## Planning data model
+
+- **Epic** = full feature outcome and constraints.
+- **Task** = one complete subsystem/domain work unit that can be owned by one
+  agent.
+- **Subtask** = concrete implementation/test/verification step under a task.
+- **Dependency edge** = strict prerequisite only (do not add "nice to have"
+  dependencies).
+
+All entities start in `todo`. See the status machine in the main SKILL.md.
+
+Plan implications:
+- Never set initial status to anything other than `todo` in create commands.
+- Task descriptions should reference valid transitions when documenting
+  completion flow (e.g., "todo -> in_progress -> done", not "todo -> done").
+- `task done` auto-transitions through `in_progress`, but `task update` does
+  not — plan descriptions should note this for agents.
+
+## Information-dense writing standard
+
+### Epic title
+
+Use a functional, outcome-oriented format:
+
+`<Product/Area>: <deliverable> to <user/system outcome> (<key constraint>)`
+
+Example: `Checkout: add idempotent payment capture to prevent duplicate charges
+(Stripe + retries)`
+
+### Epic description
+
+Include:
+
+1. **Goal & why now**
+2. **In scope** (specific capabilities)
+3. **Out of scope** (explicit exclusions)
+4. **Success criteria** (testable outcomes)
+5. **Risks/constraints** (data migration, latency budgets, auth boundaries)
+6. **Verification gates** (tests, manual checks, perf/security checks)
+
+### Task title
+
+Use a structure that encodes subsystem + action + outcome:
+
+`[<Subsystem>] <verb> <artifact/interface> to <observable outcome>`
+
+Example: `[API/Auth] issue refresh-token rotation endpoint to invalidate
+replayed sessions`
+
+### Task description
+
+Must include:
+
+- concrete scope and affected paths/symbols
+- acceptance criteria (observable behavior)
+- required tests/verification commands
+- integration constraints (contracts, backward compatibility)
+- explicit "can run in parallel with ..." or "blocked by ..." note
+
+**File scope** — declare explicitly so the agent doesn't waste tokens exploring:
+
+- **Target files**: files to create or modify
+- **Read-first files**: files the agent should read for context
+- **Do-not-touch**: paths that parallel agents own — prevents merge conflicts
+
+**Context loading hints** — point the agent to existing patterns:
+
+- Reference a concrete file as the pattern to mirror
+- Name the specific function/class/export to extend or integrate with
+- State project conventions rather than assuming the agent will discover them
+
+**Owner assignment** — when the plan has clear subsystem lanes, assign owners in
+task descriptions so the executor knows which agent/person owns each task:
+
+```
+Owner: auth-lane
+Can run in parallel with: billing-lane tasks
+```
+
+Example task description:
+
+```
+Implement refresh-token rotation endpoint.
+
+Target files: src/auth/refresh.ts (new), src/auth/refresh.test.ts (new)
+Read first: src/auth/login.ts (follow same handler pattern)
+Do not touch: src/billing/* (owned by billing-lane)
+
+Follow the handler pattern in login.ts: schema validation -> service call ->
+response mapping.
+
+Acceptance: POST /auth/refresh returns new token pair, invalidates old token.
+Verify: bun test src/auth/refresh.test.ts
+Owner: auth-lane
+Can run in parallel with: billing-lane. Blocked by: task-types (needs AuthToken).
+```
+
+### Subtask title/description
+
+- Titles are imperative and specific, not generic.
+- Description states exact artifact and completion signal.
+- Use subtasks for real units, not filler checklist noise.
+- Inherit file scope from parent task — only override if different files.
+
+## Parallelism & dependencies
+
+Model execution lanes intentionally:
+
+- Tasks with no dependency edge between them are parallel candidates.
+- Tasks in different subsystems should usually run in parallel.
+- Tasks in the same subsystem should be combined or sequenced.
+- Keep task groups to ~3-4 tasks per active subsystem lane.
+
+Dependency policy:
+
+1. Add an edge only for hard prerequisites.
+2. Prefer task-to-task dependencies; use subtask dependencies only when required.
+3. Validate acyclic graph assumptions before finalizing.
+
+## Assign owners after creation
+
+After creating tasks, assign ownership for multi-agent execution:
+
+```bash
+trekoon --toon task update <task-id> --owner auth-lane
+trekoon --toon task update <task-id> --owner billing-lane
+```
+
+## Validate the plan
+
+After creating the epic, validate before handing off to execution.
+
+### Check progress structure
+
+```bash
+trekoon --toon epic progress <epic-id>
+```
+
+Verify: total count matches expectations, all tasks are in `todo`, ready count
+equals the number of tasks with no dependencies.
+
+### Run suggest to confirm sanity
+
+```bash
+trekoon --toon suggest --epic <epic-id>
+```
+
+`suggest` will surface issues: sync gaps, recovery needs, or unexpected blocker
+states. If it suggests claiming a task, the plan's dependency graph is valid and
+execution-ready.
+
+### Verify dependency graph
+
+```bash
+trekoon --toon task ready --epic <epic-id> --limit 50
+```
+
+Confirm that the expected first-wave tasks appear as ready candidates and
+second-wave tasks appear as blocked with the right dependencies.
+
+## Plan output and handoff
+
+After creating the epic and validating, present a summary to the user. This
+summary is the primary handoff artifact — it must be self-contained and
+actionable.
+
+### ID rules
+
+- **Always use full UUIDs** for epic and task IDs. Never use temp-keys
+  (`task-truthy`, `@task-api`, etc.) in the summary — those are ephemeral
+  creation-time references that do not exist in the database.
+- IDs must be copy-friendly: render them in monospace/code formatting so the
+  user can select and copy a UUID directly.
+
+### Summary structure
+
+1. **Epic ID + title** — displayed prominently at the top, e.g.:
+   ```
+   Epic: <full-uuid>
+   Title: <epic title>
+   ```
+2. Tasks grouped by wave/batch with columns: full UUID, title, owner/lane
+3. Dependencies shown per task (using full UUIDs or task titles, not temp-keys)
+4. Verification gate (commands to run after all tasks complete)
+
+### Example format
+
+```
+Epic: 904b3129-be2d-4b20-8030-537dc327491a
+Title: Checkout: add idempotent payment capture
+
+Wave 1 (parallel)
+| ID                                   | Task                          | Owner        |
+|--------------------------------------|-------------------------------|--------------|
+| c12c9746-dbae-4660-bcbb-ebe660cb7054 | [API] Payment capture endpoint| api-lane     |
+| 4f0848f3-538a-44d3-8415-5bb16cf3f39e | [UI] Checkout button states   | ui-lane      |
+
+Wave 2 (depends on wave 1)
+| ID                                   | Task                          | Depends on                           |
+|--------------------------------------|-------------------------------|--------------------------------------|
+| 8a76afac-155d-45b3-b205-df2e4ef8988b | [API] Retry logic             | c12c9746-dbae-4660-bcbb-ebe660cb7054 |
+
+Verification: bun run build && bun run test
+```
+
+### Execution handoff contract
+
+Every plan must be directly executable without re-interpretation. Include these
+in task descriptions:
+
+1. **Lane/subsystem ownership** (`[Subsystem] ...` in title, `--owner` set).
+2. **Dependency intent** (explicit `blocked by ...` / `can run in parallel
+   with ...`).
+3. **Verification evidence** (exact commands and expected outcome).
+4. **Completion semantics** (`done` means verified and handoff-ready; use
+   `blocked` with reason when not).
+5. **Stable contract** (execution appends progress notes rather than rewriting
+   original plan text unless the plan itself is wrong).
+
+## Quality rules
+
+1. **No markdown plan files** as source of truth.
+2. **No vague titles** ("Refactor stuff", "Fix bugs").
+3. **Descriptions must be implementation-usable** by another agent without
+   guessing.
+4. **Every task must define completion evidence** (tests/manual checks).
+5. **Parallelism must be explicit** (not implied).
+6. **Status transitions must be valid** — never describe a `todo -> done` flow.
+7. **Owners should be assigned** when multiple execution lanes exist.
+
+## Large initiatives
+
+For large scope, create multiple epics with explicit cross-epic boundaries. Use
+dependencies within each epic DAG and keep each epic executable in bounded time.

package/README.md

@@ -51,7 +51,9 @@ These are the commands most people need to recognize quickly:
 | Install/open/update the local board | `trekoon board open`, `trekoon board update` |
 | Learn the CLI | `trekoon help [command]`, `trekoon quickstart` |
 | Plan work | `trekoon epic ...`, `trekoon task ...`, `trekoon subtask ...`, `trekoon dep ...` |
-| Start an execution session | `trekoon session` |
+| Track epic progress | `trekoon epic progress <id>` |
+| Start an execution session | `trekoon session`, `trekoon session --epic <id>` |
+| Get next-action suggestions | `trekoon suggest`, `trekoon suggest --epic <id>` |
 | Keep worktrees in sync | `trekoon sync ...` |
 | Install or refresh the AI skill | `trekoon skills install`, `trekoon skills update` |
 | Maintenance | `trekoon events prune ...`, `trekoon migrate ...`, `trekoon wipe --yes` |
@@ -60,6 +62,7 @@ Machine output modes:
 
 - `--toon` for true TOON-encoded payloads
 - `--json` for JSON output
+- `--compact` to strip metadata from TOON envelopes
 - `--compat <mode>` for explicit compatibility behavior
 - `--help` and `--version` at the root or command level
 
@@ -126,18 +129,29 @@ For the full lifecycle and examples, read [Quickstart](docs/quickstart.md) and
 
 ## AI skill
 
-Trekoon ships with a bundled `trekoon` skill for AI agents. It teaches the
-agent to:
+Trekoon ships with a self-contained `trekoon` skill for AI agents. One skill
+covers the full plan-to-completion workflow:
 
-- use `--toon` by default
-- prefer the smallest sufficient read
-- use transactional bulk planning commands when possible
-- append progress and blocker notes instead of rewriting full descriptions
-- preview scoped replace before `--apply`
-- treat `.trekoon` as shared repo-scoped operational state
+- **Command reference** — `--toon` defaults, status machine, bulk planning,
+  append-based progress logging
+- **Planning** — decomposition into epic/task/subtask DAGs, writing standard,
+  file scopes, owner assignment, dependency modeling
+- **Execution** — graph building, lane grouping, sub-agent dispatch, task done
+  orchestration, verification
+- **Agent Teams** — TeamCreate/SendMessage pattern for parallel Claude Code
+  instances (requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`)
+
+The skill accepts arguments for quick entity-scoped actions:
+
+```
+/trekoon                     → load the skill
+/trekoon <id>                → show status and next steps for an entity
+/trekoon <id> execute        → start executing the entity's epic
+/trekoon <id> plan           → decompose into tasks/subtasks/deps
+```
 
 Read [AI agents and the Trekoon skill](docs/ai-agents.md) for installation,
-editor linking, recommended skill combinations, and example prompts.
+editor linking, and example prompts.
 
 ## Read next