trekoon 0.3.6 → 0.3.8

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

@@ -1,21 +1,93 @@
 ---
 name: trekoon
-description: Use Trekoon only for agentic development planning and execution, limited to creating epics with tasks and subtasks, planning backlog/sprints, updating status, tracking progress, and managing dependencies/sync across repository workflows with agents. Only invoke Trekoon when explicitly requested by the user.
+description: Use for Trekoon-based planning and execution: creating epics, tasks, and subtasks; breaking work into dependency-aware graphs; checking status and progress; planning backlog or sprint work; and coordinating agent execution from Trekoon. Prefer this whenever the user wants tracked implementation planning or Trekoon entity management, even if they do not explicitly say "Trekoon."
 ---
 
 # Trekoon Skill
 
-Trekoon is a local-first issue tracker for epics, tasks, and subtasks.
+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.
 
-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.
+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.
 
-## Skill arguments
+## Operating contract
 
-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:
+Treat these entrypoints as hard mode contracts:
 
-### 1. Resolve the entity
+- `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.
+
+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.
+
+## Planning preflight
+
+Before entering plan mode, harvest the context already available in the current
+conversation and workspace. Planning should build on prior thinking, not restart
+discovery from zero.
+
+Treat these as primary inputs when they exist:
+
+- brainstorm output
+- research notes or library findings
+- codebase exploration results
+- prior user decisions and constraints
+- existing Trekoon entities that should be expanded rather than replaced
+
+Compress that context into a short internal planning brief before creating the
+epic graph:
+
+- goal and why now
+- decisions already made
+- constraints and risks already known
+- affected systems/files/interfaces
+- verification expectations
+- unresolved questions that actually block planning
+
+If the remaining unknowns are real blockers, do targeted follow-up research or
+ask the user a narrow clarification question. Use the harness's interactive user
+question tool for this — `question` in OpenCode or `AskUserQuestion` in Claude
+Code — instead of guessing.
+
+### 1. Route by first argument
+
+| 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 |
+
+### 2. Resolve entity IDs when present
+
+If the first argument is not `plan`, resolve it as a Trekoon entity:
 
 ```bash
 trekoon --toon epic show <id> 2>/dev/null || \
@@ -25,56 +97,86 @@ trekoon --toon subtask show <id> 2>/dev/null
 
 If none match, tell the user the ID was not found.
 
-### 2. Choose the action
+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.
 
-Interpret the user's accompanying text (or lack thereof) to decide what to do:
+### 3. Interpret missing or extra text
 
 | 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 |
+| 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
 
-```
-/trekoon abc-123
-  → shows epic/task/subtask abc-123, summarizes status and next candidate
+```text
+trekoon plan build a dependency-aware release workflow
+  → reads planning reference, creates a validated epic, returns epic ID + wave summary
 
-/trekoon abc-123 analyze this epic
-  → runs epic progress, suggest, reports readiness and blockers
+trekoon abc-123
+  → orients on epic/task/subtask abc-123, summarizes state and next action
 
-/trekoon abc-123 execute
-  → reads execution reference, starts session --epic, begins work loop
+trekoon abc-123 execute
+  → reads execution reference, starts the execution loop, keeps going until done or blocked
 
-/trekoon abc-123 plan the implementation
-  → reads planning reference, decomposes into tasks/subtasks/deps
+trekoon abc-123 team execute
+  → reads team execution reference, starts Agent Teams orchestration if supported
 ```
 
-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.
+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.
 
-| When | Read | What it covers |
+| Mode | Read | Use it for |
 |---|---|---|
-| 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 |
+| Plan | `reference/planning.md` | Converting a goal into a real epic/task/subtask dependency graph with validation and handoff |
+| Execute | `reference/execution.md` | Running an epic end to end, choosing lanes, dispatching sub-agents, recording evidence, and closing the epic |
+| Team execute | `reference/execution-with-team.md` | Agent Teams coordination via TeamCreate/TaskCreate/SendMessage when the environment supports it |
+
+## Mode completion rules
+
+These stop conditions are the core contract for the skill.
 
-**Typical flow:**
-1. Read `reference/planning.md` and create the epic with tasks, subtasks, deps,
-   owners.
-2. Read `reference/execution.md` for the regular subagents flow OR `reference/execution-with-team.md` for the Agent Teams flow. Then run `session --epic`, build lane groups, dispatch agents, and 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.
+- **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
 
@@ -84,10 +186,14 @@ methodology and orchestration patterns.
 - 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
 
@@ -140,9 +246,32 @@ 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
+## 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` |
+
+## 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.
 
-The primary loop is: **session → claim → work → task done → repeat**.
+## Single-agent execution loop
+
+Use this loop when one agent should continue the work directly. The primary loop
+is: **session → claim → work → task done → repeat**.
 
 ### 1. Orient with a single call
 
@@ -243,6 +372,22 @@ trekoon --toon task update <task-id> --append "Started implementation"
 trekoon --toon task update <task-id> --append "Blocked by <reason>" --status blocked
 ```
 
+### 3b. Work on subtasks explicitly when they matter
+
+Use the same status discipline for subtasks when a task depends on concrete
+subtask progress:
+
+```bash
+trekoon --toon subtask update <subtask-id> --status in_progress
+trekoon --toon subtask update <subtask-id> --append "Implemented parser branch"
+trekoon --toon subtask update <subtask-id> --append "Verified with fixture set" --status done
+trekoon --toon subtask update <subtask-id> --append "Blocked by <reason>" --status blocked
+```
+
+Use subtasks for real execution units, not filler. If a task has open subtasks
+when `task done` is called, treat the warning as a prompt to consciously decide
+whether the task is genuinely complete.
+
 ### 4. Finish or report a block
 
 When done, append a completion note then mark done:
@@ -633,38 +778,18 @@ 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.
+## Tool capability guidance
 
-**Fallbacks:** use `Grep`/`grep` for symbols, `Bash`/`bash` for compiler
-diagnostics.
+Inspect your available tools before assuming names. Prefer capability-based
+selection over harness-specific tool names.
 
-### General guidance
+- Use your harness's structured file search and file read tools instead of shell
+  commands for code inspection whenever possible.
+- Use symbol-aware tools when available; fall back to content search when they
+  are not.
+- 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.
 
-- 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.
+## User manual input:

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

@@ -5,6 +5,10 @@ Teams — real parallel Claude Code instances coordinated via TeamCreate,
 TaskCreate, SendMessage, and shared task lists. Each teammate runs in its own
 tmux pane.
 
+**Execute mode contract:** team 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.
+
 **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.
@@ -82,13 +86,9 @@ TaskCreate:
     - 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
+    Only create branches, commits, or PRs if the user explicitly requested
+    them and the current harness policy allows it.
+    Report: files changed, verification results, blockers
 ```
 
 Use `blockedBy` via TaskUpdate to set dependencies between tasks that require
@@ -197,10 +197,8 @@ After all work is verified:
 
 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.
+6. Return final execution summary: completed tasks, remaining blockers,
+    dependency state.
 
 ## Team orchestration tools
 

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

@@ -5,9 +5,25 @@ 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.
 
+**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.
+
 **Clarify ambiguity upfront.** If the plan has unclear requirements or meaningful
 tradeoffs, ask the user before starting.
 
+## Choose execution shape first
+
+Use the lightest shape that still preserves momentum:
+
+- **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.
+
+Do not stop at status reporting when ready work exists.
+
 ## Build the execution graph
 
 Construct a runnable graph from Trekoon entities using the deterministic
@@ -98,7 +114,9 @@ If blocked:
 Use --compact to reduce output noise:
   trekoon --toon --compact task show <id>
 
-Commit after each edit. Report: files changed, test results.
+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.
 ```
 
 ## Use task done response for orchestration
@@ -148,8 +166,10 @@ Run the full test suite. All tests must pass.
 
 Automated tests aren't sufficient. Actually exercise the changes:
 
-- **API changes:** Curl endpoints with realistic payloads.
-- **External integrations:** Test against real services.
+- **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.
 
@@ -179,7 +199,7 @@ are all 0.
 
 ## Cleanup
 
-After committing and verifying:
+After verification is complete:
 
 1. **Verify all tasks are done:**
    ```bash
@@ -198,11 +218,8 @@ After committing and verifying:
    ```
    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.
+4. **Return final execution summary:** completed tasks, remaining blockers,
+    dependency state.
 
 ## Architectural fit
 

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

@@ -3,11 +3,52 @@
 Write implementation plans directly into Trekoon as epics with task/subtask
 DAGs. Plans must be directly executable without re-interpretation.
 
+**Plan mode contract:** planning is complete only when the epic exists in
+Trekoon, the dependency graph is validated, and the user can immediately run
+`trekoon <epic-id> execute`.
+
 **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.
 
+Use the harness's interactive user-question tool when you need clarification:
+
+- OpenCode: `question`
+- Claude Code: `AskUserQuestion`
+
+Do not hide planning-critical questions inside a long narrative response.
+
+## Pre-plan synthesis
+
+Before creating or expanding an epic, synthesize the context you already have.
+Planning should consume previous brainstorming, research, and codebase discovery
+rather than redoing it from scratch.
+
+Build a short internal planning brief with:
+
+1. **Goal** — what outcome the user wants
+2. **Decisions already made** — chosen direction, rejected options, known tradeoffs
+3. **Known constraints** — architecture, library constraints, timelines, safety, compatibility
+4. **Affected areas** — subsystems, files, interfaces, or workflows likely involved
+5. **Verification expectations** — what evidence will prove the work is complete
+6. **Remaining unknowns** — only the ones that actually block graph creation
+
+If the brief is already sufficient, go straight into planning. If important
+unknowns remain, do targeted research or ask a narrow user question before
+creating the graph.
+
+## Research-aware planning rules
+
+- Reuse research conclusions in the epic and task descriptions.
+- Carry forward concrete patterns, file paths, APIs, and constraints that were
+  discovered earlier.
+- Do not replace prior decisions with generic planning boilerplate.
+- If the user already chose an approach during brainstorming, plan that approach
+  unless they explicitly reopen the decision.
+- If existing Trekoon items already represent part of the work, expand or refine
+  them instead of recreating parallel tracking state.
+
 ## Planning data model
 
 - **Epic** = full feature outcome and constraints.
@@ -47,6 +88,8 @@ Include:
 4. **Success criteria** (testable outcomes)
 5. **Risks/constraints** (data migration, latency budgets, auth boundaries)
 6. **Verification gates** (tests, manual checks, perf/security checks)
+7. **Key prior decisions or research findings** when they materially affect the
+   implementation path
 
 ### Task title
 
@@ -66,6 +109,8 @@ Must include:
 - required tests/verification commands
 - integration constraints (contracts, backward compatibility)
 - explicit "can run in parallel with ..." or "blocked by ..." note
+- relevant findings from prior research or brainstorming that execution agents
+  should not have to rediscover
 
 **File scope** — declare explicitly so the agent doesn't waste tokens exploring:
 
@@ -174,6 +219,9 @@ 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.
 
+Do not stop at a prose-only design. The final handoff must reference the actual
+Trekoon epic and the first execution wave.
+
 ### ID rules
 
 - **Always use full UUIDs** for epic and task IDs. Never use temp-keys

package/README.md

@@ -30,25 +30,45 @@ trekoon quickstart    # walkthrough of the basics
 Trekoon gives agents two modes: **plan** and **execute**. You can run them
 separately or back to back.
 
+For a human driving the workflow, the recommended path is:
+
+```bash
+trekoon plan <goal>
+trekoon <epic-id>
+trekoon <epic-id> execute
+```
+
+- Use `plan` after you already have enough context from discussion,
+  brainstorming, or research.
+- Use `trekoon <epic-id>` to inspect the created epic, review the next ready
+  work, and decide whether anything needs refinement.
+- Use `execute` when you want the agent to keep working through the epic until
+  it is done, all remaining work is blocked, or it needs your input.
+
 ### Plan
 
-Tell the agent what you want to build or find and fix bugs in your code. Then ask Trekoon to
-create plan and decomposes the plan into an epic with tasks, subtasks, and dependency edges,
-then writes the whole graph into Trekoon in a single transaction.
+Tell the agent what you want to build or what problem you want fixed. If you
+already did brainstorming or research, Trekoon should use that context instead
+of starting from zero. Planning decomposes the work into an epic with tasks,
+subtasks, and dependency edges, then writes the whole graph into Trekoon.
 
-```
-/trekoon plan <description>
+```bash
+trekoon plan <description>
 ```
 
 What the agent does during planning:
 
-1. Asks clarifying questions if requirements are ambiguous
-2. Creates an epic with outcome-oriented title and scoped description
-3. Breaks it into tasks grouped by subsystem (auth, billing, UI, etc.)
-4. Adds subtasks with concrete file paths, acceptance criteria, and test commands
-5. Wires dependency edges so the execution order is explicit
-6. Assigns lane owners when multiple agents will work in parallel
-7. Validates the graph with `epic progress` and `suggest` before handing off
+1. Reuses the current conversation, prior research, and existing constraints
+2. Asks clarifying questions if requirements are ambiguous
+3. Creates an epic with outcome-oriented title and scoped description
+4. Breaks it into tasks grouped by subsystem (auth, billing, UI, etc.)
+5. Adds subtasks with concrete file paths, acceptance criteria, and test commands
+6. Wires dependency edges so the execution order is explicit
+7. Assigns lane owners when multiple agents will work in parallel
+8. Validates the graph with `epic progress` and `suggest` before handing off
+
+For humans: use `plan` when you want Trekoon to turn a feature request or bug
+investigation into a tracked, execution-ready backlog.
 
 Each task description includes target files, read-first files, do-not-touch
 paths, and verification commands. Another agent (or a human) can pick up any
@@ -59,8 +79,8 @@ task and execute it without re-reading the codebase to figure out what to do.
 Point the agent at an epic and it works through the dependency graph
 automatically. It is recommended to do it with clean context window.
 
-```
-/trekoon <id> execute
+```bash
+trekoon <id> execute
 ```
 
 What the agent does during execution:
@@ -82,6 +102,11 @@ What the agent does during execution:
 The orchestrator uses `task done` responses to drive the whole loop. No polling,
 no guessing. When a task finishes, Trekoon tells you exactly what's ready next.
 
+For humans: use `execute` when the plan looks good and you want the agent to own
+the epic end to end. It should keep going until the epic is complete, all
+remaining work is blocked with recorded reasons, or it needs a product or
+technical decision from you.
+
 ## Install the skill
 
 The `trekoon` skill is what teaches agents the planning methodology, execution

package/docs/quickstart.md

@@ -2,6 +2,27 @@
 
 Shortest path from zero to a working Trekoon workflow.
 
+## Recommended human workflow
+
+If you are driving Trekoon with an AI agent, the usual path is:
+
+```bash
+trekoon plan <goal>
+trekoon <epic-id>
+trekoon <epic-id> execute
+```
+
+- Use `plan` after you already have enough context from discussion,
+  brainstorming, or research. Trekoon should turn that context into an
+  execution-ready epic.
+- Use `trekoon <epic-id>` to inspect the created epic, next ready work, and any
+  blockers before starting execution.
+- Use `execute` when you want the agent to keep working through the epic until
+  it is done, all remaining work is blocked, or it needs your input.
+
+The rest of this page is mostly the lower-level command surface that agents and
+power users rely on.
+
 ## How storage works
 
 Trekoon keeps one SQLite database per repository at `.trekoon/trekoon.db`. In

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.3.6",
+  "version": "0.3.8",
   "description": "AI-first local issue tracker CLI.",
   "keywords": [
     "ai",