trekoon 0.3.0 → 0.3.2

package/docs/ai-agents.md

@@ -15,9 +15,21 @@ agent to:
 - preview scoped replace before `--apply`
 - treat `.trekoon` as shared repo-scoped operational state
 
-The canonical installed file lives at:
+The skill ships with bundled reference guides for planning and execution so the
+agent can handle the full plan-to-completion workflow from a single skill:
 
-- `.agents/skills/trekoon/SKILL.md`
+```
+.agents/skills/trekoon/
+  SKILL.md                      ← command reference, status machine, agent loop
+  reference/
+    planning.md                 ← decomposition, writing standard, validation
+    execution.md                ← graph building, lane dispatch, verification
+    execution-with-team.md      ← Agent Teams pattern (Claude Code only)
+```
+
+The agent reads the relevant reference file on demand — `planning.md` when asked
+to plan, `execution.md` when asked to execute, `execution-with-team.md` when Agent
+Teams are available.
 
 ## Install the skill
 
@@ -46,34 +58,58 @@ Path behavior:
 - `--to <path>` changes only the editor link root
 - `--allow-outside-repo` is for intentional external links
 
-## Recommended skill stack
+## Using the skill with arguments
+
+The skill accepts an optional entity ID and action text:
+
+```
+/trekoon                              → loads the skill normally
+/trekoon <id>                         → resolves the entity, shows status and next steps
+/trekoon <id> analyze                 → runs epic progress + suggest, reports findings
+/trekoon <id> execute                 → starts the execution loop for the entity's epic
+/trekoon <id> plan the implementation → decomposes into tasks/subtasks/deps
+```
+
+The skill resolves the ID as an epic, task, or subtask. For tasks and subtasks,
+it scopes session/suggest/progress calls to the parent epic automatically.
 
-If your agent environment supports skills, this is the cleanest split of
-responsibilities:
+## Skill stack
 
-| Job | Skill | Why |
+The `trekoon` skill is self-contained for the full plan-to-completion workflow.
+It bundles planning methodology, execution orchestration, and the command
+reference in one install.
+
+For specialized needs, these optional companion skills add value:
+
+| Job | Skill | When to use |
 | --- | --- | --- |
-| Turn a request into a concrete backlog | `writing-plans` | Breaks work into epics, tasks, subtasks, and dependencies |
-| Create and update tracker state | `trekoon` | Uses Trekoon safely and efficiently |
-| Execute the plan in dependency order | `executing-plans` | Helps the agent work through the backlog without losing the sequence |
-| Clarify architecture before planning | `architecting-systems` | Useful when boundaries or ownership are still fuzzy |
+| Clarify architecture before planning | `architecting-systems` | Boundaries or ownership are still fuzzy |
+| Specialized code review | `code-review-expert` | Want structured review before closing an epic |
 
-In practice, the flow is usually:
+In practice, the flow is:
 
-1. plan the work
-2. load `trekoon`
-3. create or update the Trekoon graph
-4. execute the next ready task
-5. update progress, blockers, and completion state as work moves forward
+1. `/trekoon` — load the skill
+2. Plan the work (skill reads `reference/planning.md` internally)
+3. Create or update the Trekoon graph
+4. Execute the plan (skill reads `reference/execution.md` internally)
+5. Update progress, blockers, and completion state as work moves forward
 
 ## Default execution loop for agents
 
 The main loop is: **session → work → task done → repeat**.
 
-Start with a single orientation call:
+Start with a single orientation call, optionally scoped to an epic:
 
 ```bash
 trekoon --toon session
+trekoon --toon session --epic <epic-id>
+```
+
+Or use `suggest` for priority-ranked next-action recommendations:
+
+```bash
+trekoon --toon suggest
+trekoon --toon suggest --epic <epic-id>
 ```
 
 If the session output shows you are behind, pull tracker events before claiming
@@ -83,16 +119,50 @@ work:
 trekoon --toon sync pull --from main
 ```
 
-Claim work, then finish or report a block:
+Claim work, assign ownership, then finish or report a block:
 
 ```bash
-trekoon --toon task update <task-id> --status in_progress
+trekoon --toon task update <task-id> --status in_progress --owner "agent-1"
 trekoon --toon task done <task-id>
 trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
 Use `task done` when the task is actually finished. It marks the task complete
-and returns the next ready candidate with blockers inline.
+and returns the next ready candidate with blockers inline. `task done`
+auto-transitions through `in_progress` when the current status is `todo` or
+`blocked`. The response also reports newly unblocked downstream tasks and warns
+about incomplete subtasks.
+
+Use `--compact` to strip contract metadata from envelopes when you do not need
+it:
+
+```bash
+trekoon --toon --compact task done <task-id>
+```
+
+## Status machine rules
+
+Trekoon enforces valid status transitions. Do not attempt direct jumps like
+`todo → done` — they will fail with `status_transition_invalid`. Use `task done`
+for completing tasks (it handles the intermediate step automatically).
+
+Valid transitions:
+
+| From | Allowed targets |
+| --- | --- |
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `done`, `blocked` |
+| `blocked` | `in_progress`, `todo` |
+| `done` | `in_progress` |
+
+## Track epic progress
+
+Use `epic progress` to get a summary of task status counts and the next ready
+candidate for an epic:
+
+```bash
+trekoon --toon epic progress <epic-id>
+```
 
 ## Use descendant cascade mode when closing a whole tree
 
@@ -119,29 +189,34 @@ Notes:
 
 ## Tell the agent exactly what to do
 
-These prompts work well because they are explicit about the skill order and the
-expected loop.
+These prompts work well because they are explicit about the expected workflow.
 
 ### Plan first, then create the backlog
 
 ```text
-Load writing-plans, break this feature into one epic with tasks and subtasks,
-then load trekoon and create that graph in Trekoon.
+/trekoon — plan this feature as one epic with tasks, subtasks, and dependencies,
+then create the graph in Trekoon.
 ```
 
 ### Execute an existing backlog
 
 ```text
-Load trekoon, run `trekoon --toon session`, take the next ready task, do the
-work, append progress notes, mark it done, and repeat until there are no ready
-tasks or you hit a blocker.
+/trekoon <epic-id> execute
+```
+
+Or more explicitly:
+
+```text
+/trekoon — run session, take the next ready task, do the work, append progress
+notes, mark it done, and repeat until there are no ready tasks or you hit a
+blocker.
 ```
 
-### Use planning, tracking, and execution together
+### Plan and execute end to end
 
 ```text
-Load writing-plans to shape the backlog, load trekoon to create and update the
-tasks, then load executing-plans and complete the work in dependency order.
+/trekoon — plan this feature, create the backlog, then execute the tasks in
+dependency order until the epic is complete.
 ```
 
 ## Keep reads small and mutations safe
@@ -151,6 +226,9 @@ Use the narrowest command that answers the question:
 | Need | Preferred command |
 | --- | --- |
 | Session startup | `trekoon --toon session` |
+| Session scoped to epic | `trekoon --toon session --epic <epic-id>` |
+| Next-action suggestions | `trekoon --toon suggest` |
+| Epic progress summary | `trekoon --toon epic progress <epic-id>` |
 | Next task only | `trekoon --toon task next` |
 | A few ready options | `trekoon --toon task ready --limit 5` |
 | One task with subtasks | `trekoon --toon task show <task-id> --all` |

package/docs/commands.md

@@ -9,8 +9,9 @@ surface, defaults, and flag rules.
 - `trekoon board <open|update>`
 - `trekoon help [command]`
 - `trekoon quickstart`
-- `trekoon epic <create|expand|list|show|search|replace|update|delete>`
-- `trekoon session`
+- `trekoon epic <create|expand|list|show|search|replace|update|delete|progress>`
+- `trekoon session [--epic <epic-id>]`
+- `trekoon suggest [--epic <epic-id>]`
 - `trekoon task <create|create-many|list|show|ready|next|done|search|replace|update|delete>`
 - `trekoon subtask <create|create-many|list|search|replace|update|delete>`
 - `trekoon dep <add|add-many|remove|list|reverse>`
@@ -25,6 +26,7 @@ surface, defaults, and flag rules.
 
 - `--json` for structured JSON output
 - `--toon` for true TOON-encoded output
+- `--compact` strips contract metadata from TOON/JSON envelopes
 - `--compat <mode>` for explicit machine compatibility behavior
 - `--help` for root and command help
 - `--version` for CLI version
@@ -119,8 +121,8 @@ Board API endpoints (all require token authentication):
 - `GET /api/snapshot` — full board state (epics, tasks, subtasks, dependencies,
   counts)
 - `PATCH /api/epics/{id}` — update epic title, description, or status
-- `PATCH /api/tasks/{id}` — update task title, description, or status
-- `PATCH /api/subtasks/{id}` — update subtask title, description, or status
+- `PATCH /api/tasks/{id}` — update task title, description, status, or owner
+- `PATCH /api/subtasks/{id}` — update subtask title, description, status, or owner
 - `POST /api/subtasks` — create subtask (requires taskId, title)
 - `DELETE /api/subtasks/{id}` — delete subtask
 - `POST /api/dependencies` — add dependency edge (sourceId, dependsOnId)
@@ -149,7 +151,7 @@ trekoon board update
 
 These defaults apply to `epic list`, `task list`, and `subtask list`:
 
-- Default scope: open work only (`in_progress`, `in-progress`, `todo`)
+- Default scope: open work only (`in_progress`, `todo`)
 - Default limit: `10`
 - Status filter: `--status in_progress,todo`
 - Custom limit: `--limit <n>`
@@ -217,6 +219,80 @@ trekoon task update <task-id> --all --status todo
 trekoon subtask update <subtask-id> --all --status done
 ```
 
+## Status machine
+
+Trekoon enforces a status machine for all entities. The canonical statuses are
+`todo`, `in_progress`, `done`, and `blocked`. The hyphenated `in-progress`
+variant is no longer accepted.
+
+**Upgrading from 0.3.0:** Existing entities with `in-progress` or other custom
+statuses are handled gracefully — transitions from non-canonical statuses to any
+valid status are allowed, so you can update them to `in_progress` without error.
+
+Valid transitions:
+
+| From | Allowed targets |
+| --- | --- |
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `done`, `blocked` |
+| `blocked` | `in_progress`, `todo` |
+| `done` | `in_progress` |
+
+Invalid transitions return a `status_transition_invalid` error with the current
+status, target status, and allowed transitions.
+
+## Owner field
+
+Tasks and subtasks have an optional `owner` field. Set or clear it with the
+`--owner` flag on update commands:
+
+```bash
+trekoon task update <task-id> --owner "agent-1"
+trekoon subtask update <subtask-id> --owner "agent-2"
+```
+
+The board API also accepts `owner` on `PATCH /api/tasks/{id}` and
+`PATCH /api/subtasks/{id}`.
+
+## Task done behavior
+
+`trekoon task done <task-id>` marks a task complete and returns the next ready
+candidate. Additional behavior:
+
+- Auto-transitions through `in_progress` when the current status is `todo` or
+  `blocked`, emitting two sync events for the intermediate step.
+- Reports newly unblocked downstream tasks in the response (`data.unblocked`).
+- Warns when subtasks remain incomplete (`data.warning`,
+  `data.openSubtaskCount`, `data.openSubtaskIds`).
+
+## Epic progress
+
+```bash
+trekoon epic progress <epic-id>
+```
+
+Returns status counts (`total`, `doneCount`, `inProgressCount`, `blockedCount`,
+`todoCount`), `readyCount`, and `nextCandidate` for the given epic.
+
+## Session scoping
+
+```bash
+trekoon session --epic <epic-id>
+```
+
+Scopes session readiness to a specific epic instead of the full tracker.
+
+## Suggest command
+
+```bash
+trekoon suggest [--epic <epic-id>]
+```
+
+Returns up to 3 priority-ranked next-action suggestions based on recovery state,
+sync status, task readiness, and epic progress. Categories: `recovery`, `sync`,
+`execution`, `planning`. Each suggestion includes an `action`, `command`, and
+`reason`.
+
 ## Related docs
 
 - [Quickstart](quickstart.md)

package/docs/machine-contracts.md

@@ -246,6 +246,126 @@ Behavior:
 - machine output includes `metadata.compatibility` with migration guidance and
   removal timing
 
+## Compact envelope mode
+
+```bash
+trekoon --toon --compact task list
+```
+
+When `--compact` is passed, the `metadata` key is omitted from the TOON/JSON
+envelope. The `ok`, `command`, `data`, `error`, and `meta` keys are unaffected.
+
+## Status transition error contract
+
+Invalid status transitions return:
+
+```text
+ok: false
+error:
+  code: status_transition_invalid
+  message: "cannot transition <kind> <id> from '<from>' to '<to>'"
+  details:
+    entity: epic|task|subtask
+    id: <entity-id>
+    fromStatus: <current-status>
+    toStatus: <attempted-status>
+    allowedTransitions[]: <valid targets from current status>
+```
+
+## Epic progress contract
+
+```bash
+trekoon --toon epic progress <epic-id>
+```
+
+Payload fields:
+
+```text
+ok: true
+command: epic.progress
+data:
+  epicId: <epic-id>
+  title: <epic-title>
+  total
+  doneCount
+  inProgressCount
+  blockedCount
+  todoCount
+  readyCount
+  nextCandidate: { id, title } | null
+```
+
+## Task done enhanced contract
+
+```bash
+trekoon --toon task done <task-id>
+```
+
+Payload fields:
+
+```text
+ok: true
+command: task.done
+data:
+  completed: { ...task record... }
+  openSubtaskCount
+  openSubtaskIds[]
+  warning: "Warning: N subtask(s) still open." | null
+  unblocked[]:
+    id
+    kind: task
+    title
+    status
+    wasBlockedBy[]
+  next: { ...task tree... } | null
+  nextDeps[]
+  readiness:
+    readyCount
+    blockedCount
+```
+
+## Suggest command contract
+
+```bash
+trekoon --toon suggest [--epic <epic-id>]
+```
+
+Payload fields:
+
+```text
+ok: true
+command: suggest
+data:
+  suggestions[]:
+    priority
+    action
+    command
+    reason
+    category: recovery|sync|execution|planning
+  context:
+    totalEpics
+    activeEpic: <epic-id> | null
+    readyTasks
+    blockedTasks
+    inProgressTasks
+    syncBehind
+    pendingConflicts
+```
+
+## Owner field in update payloads
+
+Task and subtask update payloads now include `owner` in their event data:
+
+```text
+data:
+  task | subtask:
+    ...existing fields...
+    owner: <string> | null
+```
+
+The board API accepts `owner` on `PATCH /api/tasks/{id}` and
+`PATCH /api/subtasks/{id}`.
+
 ## Related docs
 
 - [Quickstart](quickstart.md)