trekoon 0.3.1 → 0.3.2

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

@@ -129,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
 

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,25 +58,41 @@ 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.
+
+## Skill stack
 
-If your agent environment supports skills, this is the cleanest split of
-responsibilities:
+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.
 
-| Job | Skill | Why |
+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
 
@@ -161,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "trekoon",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "AI-first local issue tracker CLI.",
   "keywords": [
     "ai",
@@ -34,7 +34,7 @@
     "docs",
     "src",
     "src/board/assets",
-    ".agents/skills/trekoon/SKILL.md",
+    ".agents/skills/trekoon",
     "README.md",
     "LICENSE"
   ],

package/src/board/assets/app.js

@@ -555,8 +555,13 @@ export async function bootLegacyBoard(options = {}) {
       submitCreateSubtask: (id, data) => actions.submitCreateSubtask(id, data),
       addDependency: (src, data) => actions.addDependency(src, data),
       dropTaskStatus: (id, status) => actions.dropTaskStatus(id, status),
+      getTaskStatus: (id) => actions.getTaskStatus(id),
       changeEpicStatus: (epicId, status) => actions.changeEpicStatus(epicId, status),
       bulkSetStatus: (epicId, status) => actions.bulkSetStatus(epicId, status),
+      toggleEpicStatusFilter: (status) => actions.toggleEpicStatusFilter(status),
+      toggleTaskStatusFilter: (status) => actions.toggleTaskStatusFilter(status),
+      resetEpicFilter: () => actions.resetEpicFilter(),
+      resetTaskFilter: () => actions.resetTaskFilter(),
       handleKeydown: (event) => actions.handleKeydown(event),
     });
 

package/src/board/assets/components/EpicsOverview.js

@@ -3,7 +3,10 @@ import {
   panelClasses,
   renderEmptyState,
   sectionLabelClasses,
+  STATUS_LABELS,
+  STATUS_ORDER,
 } from "./helpers.js";
+import { DEFAULT_STATUS_FILTER } from "../state/store.js";
 
 /**
  * Render the epics overview HTML.
@@ -17,6 +20,9 @@ import {
 function render(props) {
   const { visibleEpics, selectedEpicId, store } = props;
 
+  const epicStatusFilter = store.epicStatusFilter || { ...DEFAULT_STATUS_FILTER };
+  const isNonDefault = STATUS_ORDER.some(s => epicStatusFilter[s] !== DEFAULT_STATUS_FILTER[s]);
+
   return `
     <div class="board-root board-root--epics">
       <section class="board-overview ${panelClasses("board-overview--dense p-4 sm:p-5")}" aria-label="Epics overview">
@@ -31,6 +37,13 @@ function render(props) {
             <span class="board-chip board-chip--neutral">${store.snapshot.tasks.length} total tasks</span>
             ${store.isMutating ? '<span class="board-chip board-chip--neutral">Saving\u2026</span>' : ""}
           </div>
+          <div class="board-filter-bar">
+            ${STATUS_ORDER.map(status => {
+              const active = epicStatusFilter[status] !== false;
+              return `<button type="button" class="board-filter-pill ${active ? 'board-filter-pill--active' : 'board-filter-pill--inactive'} board-filter-pill--${status}" data-toggle-epic-status-filter="${status}" aria-pressed="${active}" title="${active ? 'Hide' : 'Show'} ${STATUS_LABELS[status]} epics">${STATUS_LABELS[status]}</button>`;
+            }).join('')}
+            ${isNonDefault ? `<button type="button" class="board-filter-pill board-filter-pill--reset" data-reset-epic-filter title="Reset filters to defaults">Reset</button>` : ''}
+          </div>
         </header>
         <div class="board-table board-table--epics">
           <div class="board-table__header board-table__header--epics hidden md:grid">

package/src/board/assets/components/Workspace.js

@@ -20,8 +20,8 @@ import {
   STATUS_LABELS,
   STATUS_ORDER,
 } from "./helpers.js";
-import { orderEpicsNewestFirst } from "../state/store.js";
-import { VIEW_MODES } from "../state/utils.js";
+import { DEFAULT_STATUS_FILTER, orderEpicsNewestFirst } from "../state/store.js";
+import { getSelectableStatuses, VIEW_MODES } from "../state/utils.js";
 
 // ---------------------------------------------------------------------------
 // Workspace header
@@ -58,6 +58,9 @@ function renderWorkspaceHeader(props) {
     visibleTasks,
   } = props;
 
+  const taskStatusFilter = store.taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
+  const isTaskFilterNonDefault = STATUS_ORDER.some(s => taskStatusFilter[s] !== DEFAULT_STATUS_FILTER[s]);
+
   const description = selectedEpic.description?.trim() || "";
   const inlineSelect = `${fieldClasses()} !py-1 !px-2 !text-xs !min-h-0 !rounded-xl`;
   const epicStatusTooltip = "Change this epic's overall status.";
@@ -79,7 +82,7 @@ function renderWorkspaceHeader(props) {
             <label class="board-wh__control-label">
               <span class="board-wh__control-text">Epic status</span>
               <select class="${inlineSelect}" name="status" aria-label="Epic status" title="${escapeHtml(epicStatusTooltip)}" ${store.isMutating ? "disabled" : ""}>
-                ${STATUS_ORDER.map(s => `<option value="${escapeHtml(s)}" ${selectedEpic.status === s ? 'selected' : ''}>${escapeHtml(STATUS_LABELS[s] ?? s)}</option>`).join('')}
+                ${getSelectableStatuses(selectedEpic.status).map(s => `<option value="${escapeHtml(s)}" ${selectedEpic.status === s ? 'selected' : ''}>${escapeHtml(STATUS_LABELS[s] ?? s)}</option>`).join('')}
               </select>
             </label>
           </form>
@@ -114,6 +117,14 @@ function renderWorkspaceHeader(props) {
           <span class="${neutralChipClasses()}">${visibleTasks.length} visible</span>
           ${store.isMutating ? `<span class="${neutralChipClasses()}">Saving\u2026</span>` : ""}
         </div>
+        <div class="board-filter-bar">
+          ${STATUS_ORDER.map(status => {
+            const active = taskStatusFilter[status] !== false;
+            const count = selectedEpic.counts?.[status] ?? 0;
+            return `<button type="button" class="board-filter-pill ${active ? 'board-filter-pill--active' : 'board-filter-pill--inactive'} board-filter-pill--${status}" data-toggle-task-status-filter="${status}" aria-pressed="${active}" title="${active ? 'Hide' : 'Show'} ${STATUS_LABELS[status]} tasks">${STATUS_LABELS[status]} (${count})</button>`;
+          }).join('')}
+          ${isTaskFilterNonDefault ? `<button type="button" class="board-filter-pill board-filter-pill--reset" data-reset-task-filter title="Reset filters to defaults">Reset</button>` : ''}
+        </div>
         <div class="board-wh__actions">
           <div class="board-wh__action-group">
             <button type="button" class="board-copy-btn ${isCopied ? "board-copy-btn--active" : ""}" data-copy-epic-id="${escapeHtml(selectedEpic.id)}" aria-label="${escapeHtml(isCopied ? `Copied epic UUID for ${selectedEpic.title}` : copyLabel)}" title="${escapeHtml(isCopied ? "Epic UUID copied." : copyTooltip)}">
@@ -155,9 +166,12 @@ function renderWorkspaceHeader(props) {
 // ---------------------------------------------------------------------------
 
 function renderKanbanColumns(props) {
-  const { visibleTasks, selectedTaskId, isMutating } = props;
+  const { visibleTasks, selectedTaskId, isMutating, taskStatusFilter } = props;
+  const filter = taskStatusFilter || { ...DEFAULT_STATUS_FILTER };
 
-  const columnsMarkup = STATUS_ORDER.map((status) => {
+  const columnsMarkup = STATUS_ORDER
+    .filter((status) => filter[status] !== false)
+    .map((status) => {
     const columnTasks = visibleTasks.filter((t) => t.status === status);
     const columnTitle = readStatusLabel(status);
     const content = columnTasks.length === 0
@@ -265,19 +279,20 @@ function render(props) {
   const headerMarkup = renderWorkspaceHeader({
     selectedEpic,
     snapshotEpics,
-      store: {
-        copyFeedback: store.copyFeedback,
-        notesPanelOpen: store.notesPanelOpen,
-        isMutating: store.isMutating,
-        selectedEpicId: selectedEpic.id,
-        view: store.view,
+    store: {
+      copyFeedback: store.copyFeedback,
+      notesPanelOpen: store.notesPanelOpen,
+      isMutating: store.isMutating,
+      selectedEpicId: selectedEpic.id,
+      view: store.view,
       viewModes,
+      taskStatusFilter: store.taskStatusFilter,
     },
     visibleTasks,
   });
 
   const contentMarkup = store.view === "kanban"
-    ? renderKanbanColumns({ visibleTasks, selectedTaskId, isMutating: store.isMutating })
+    ? renderKanbanColumns({ visibleTasks, selectedTaskId, isMutating: store.isMutating, taskStatusFilter: store.taskStatusFilter })
     : renderListView({ visibleTasks, selectedTaskId });
 
   return `

package/src/board/assets/components/helpers.js

@@ -1,4 +1,4 @@
-import { escapeHtml, formatDate, normalizeStatus, STATUS_ORDER } from "../state/utils.js";
+import { escapeHtml, formatDate, getSelectableStatuses, normalizeStatus, STATUS_ORDER } from "../state/utils.js";
 
 export { escapeHtml, formatDate, normalizeStatus, STATUS_ORDER };
 
@@ -123,9 +123,10 @@ export function renderStatusBadge(rawStatus, label = readStatusLabel(rawStatus))
 }
 
 export function renderStatusSelect(name, selectedStatus, disabled = false) {
+  const statuses = getSelectableStatuses(selectedStatus);
   return `
     <select class="${fieldClasses()}" name="${escapeHtml(name)}" ${disabled ? "disabled" : ""}>
-      ${STATUS_ORDER.map((status) => `
+      ${statuses.map((status) => `
         <option value="${escapeHtml(status)}" ${selectedStatus === status ? "selected" : ""}>${escapeHtml(STATUS_LABELS[status] ?? status)}</option>
       `).join("")}
     </select>