trekoon 0.3.3 → 0.3.5

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

@@ -171,7 +171,10 @@ trekoon --toon --compact session
 2. **`behind > 0`?** → Sync first: `trekoon --toon sync pull --from main`.
    This pulls tracker events (not git commits) so task states are current.
 3. **`pendingConflicts > 0`?** → Resolve before claiming work:
-   `trekoon --toon sync conflicts list`.
+   `trekoon --toon sync conflicts list`. For uniform conflicts, batch resolve:
+   `trekoon --toon sync resolve --all --use ours` (or `--use theirs`). For
+   mixed conflicts, inspect individually with `sync conflicts show <id>` and
+   resolve per-conflict.
 4. **Session returned a next task?** → Proceed to step 2 (claim work).
 5. **No next task and unsure what to do?** → Run `trekoon --toon suggest` for
    priority-ranked recommendations (see step 1b below).
@@ -502,8 +505,11 @@ Rules:
 - Do not commit `.trekoon/trekoon.db`; remove the tracked DB and keep
   `.trekoon` ignored instead.
 
-Use `quickstart` for the canonical execution loop. Use help when you need exact
-syntax.
+Use `session` as the primary entry point — it returns diagnostics, sync status,
+and the next ready task in one call. Use `suggest` for priority-ranked
+recommendations. Use `quickstart` for the canonical bootstrapping walkthrough
+and execution loop reference. Use `help` when you need exact flag syntax for a
+specific command.
 
 ## Sync reminders
 
@@ -524,9 +530,93 @@ Cross-branch sync matters before merging a feature branch back:
   ```bash
   trekoon --toon sync conflicts list
   trekoon --toon sync conflicts show <conflict-id>
+  trekoon --toon sync resolve <conflict-id> --use theirs --dry-run
   trekoon --toon sync resolve <conflict-id> --use ours
   ```
 
+### Conflict resolution: ours vs theirs
+
+Conflicts are **field-level**, not whole-record. Each conflict targets one field
+(e.g., `status`, `title`, `description`) on one entity.
+
+- `--use ours` — keep the current entity field value in the shared DB. The
+  entity is not written, but the conflict record is marked resolved and a
+  resolution event is appended.
+- `--use theirs` — overwrite the shared DB entity field with the source-branch
+  value. The conflict record is marked resolved and a resolution event is
+  appended.
+- `--dry-run` — preview the resolution without mutating the database. Returns
+  `oursValue`, `theirsValue`, `wouldWrite`, and `dryRun: true`. Use this before
+  committing to a resolution.
+
+**Example:** after `sync pull --from main`, a conflict appears on epic `abc123`,
+field `status`:
+- ours (current DB): `in_progress`
+- theirs (source branch): `done`
+- `--use ours` keeps status as `in_progress`
+- `--use theirs` changes status to `done` in the live shared DB
+
+Always inspect conflicts with `sync conflicts show` before resolving. Choosing
+`theirs` without inspection can overwrite in-progress work in the shared DB.
+
+### Understanding why conflicts happen
+
+| Scenario | Typical resolution | Why |
+|---|---|---|
+| Completed work vs stale main state | ours | Your branch has the latest progress |
+| Enriched descriptions vs original | ours | Your descriptions are more detailed |
+| Upstream updates from another agent | theirs | Accept the newer upstream state |
+| User-intentional reset | theirs | Respect the user's explicit action |
+
+### Agent decision framework
+
+1. List conflicts: `trekoon --toon sync conflicts list`
+2. Group by pattern — are conflicts on the same field or direction?
+3. If uniform pattern, batch resolve: `trekoon --toon sync resolve --all --use ours`
+4. If mixed, narrow by entity or field, or inspect individually
+5. When unsure, ask the user
+
+### Batch resolve patterns
+
+Common scenarios:
+
+```bash
+# Resolve all conflicts at once (most common after completing work)
+trekoon --toon sync resolve --all --use ours
+
+# Preview before resolving
+trekoon --toon sync resolve --all --use ours --dry-run
+
+# Narrow to status field conflicts only
+trekoon --toon sync resolve --all --use ours --field status
+
+# Narrow to a specific entity
+trekoon --toon sync resolve --all --use theirs --entity <id>
+
+# Combine filters
+trekoon --toon sync resolve --all --use ours --entity <id> --field description
+```
+
+## Shared-database model
+
+Trekoon uses **one live SQLite database per repository**. The file lives at
+`<sharedStorageRoot>/.trekoon/trekoon.db`, where `sharedStorageRoot` is the
+parent of `git rev-parse --git-common-dir` (i.e., the main worktree root).
+
+Key consequences:
+
+- **All linked worktrees share the same database.** A status change in one
+  worktree is immediately visible in every other worktree.
+- **`git checkout` / `git switch` does not change tracker state.** The database
+  is outside the git object store, so switching branches does not roll back or
+  swap task data.
+- **Sync operates on tracker events, not on the database file itself.** Use
+  `sync pull` to import events between branches — never copy or commit the
+  `.db` file.
+
+Treat every write as a mutation of shared repo-wide state, not branch-scoped
+state.
+
 ## Worktree diagnostics and destructive scope
 
 - Inspect machine-readable storage fields when debugging worktrees:

package/README.md

@@ -1,167 +1,200 @@
 # Trekoon
 
-AI-first issue tracking for humans and agents.
+AI-first task tracking that lives in your repo. You describe what to build, your
+agent plans it as a dependency graph, then executes it task by task.
 
-Trekoon is a local-first CLI for planning and execution inside a repository. It
-keeps work in a shared **epic → task → subtask** graph so humans and agents can
-work against the same state, from the terminal, with deterministic machine
-output when automation needs it.
-
-## What it is for
-
-- Fast issue tracking for day-to-day terminal use
-- One repo-scoped task graph that works across branches and worktrees
-- Stable machine-readable output for AI workflows (`--toon`, `--json`)
-- Minimal command surface with strong planning and execution primitives
-
-## Why it exists
-
-Trekoon exists to make task tracking cheap enough to use while coding, and
-structured enough that agents can read, update, and complete work without
-guessing.
+Trekoon stores work as **epics > tasks > subtasks** with dependency edges in a
+local SQLite database. Every command has structured output (`--toon`, `--json`)
+so agents can read and update state without parsing human text. No server, no
+accounts. The database lives in `.trekoon/` inside your repo.
 
 ## Install
 
-Recommended (global install with Bun):
-
 ```bash
 bun add -g trekoon
 ```
 
-Alternative (npm global install — Bun must still be installed as the runtime):
+Or via npm (Bun still needs to be installed as the runtime):
 
 ```bash
 npm i -g trekoon
 ```
 
-Verify the install:
-
 ```bash
-trekoon --help
-trekoon quickstart
+trekoon init          # set up .trekoon/ in your repo
+trekoon quickstart    # walkthrough of the basics
 ```
 
-## Commands
+## The two workflows
 
-These are the commands most people need to recognize quickly:
+Trekoon gives agents two modes: **plan** and **execute**. You can run them
+separately or back to back.
 
-| Goal | Commands |
-| --- | --- |
-| Initialize a repo | `trekoon init` |
-| Install/open/update the local board | `trekoon board open`, `trekoon board update` |
-| Learn the CLI | `trekoon [command] -h`, `trekoon [command] [subcommand] -h`, `trekoon quickstart` |
-| Plan work | `trekoon epic ...`, `trekoon task ...`, `trekoon subtask ...`, `trekoon dep ...` |
-| 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 install -g`, `trekoon skills update` |
-| Maintenance | `trekoon events prune ...`, `trekoon migrate ...`, `trekoon wipe --yes` |
-
-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
-
-For the full command surface, flags, filters, and bulk update rules, read the
-[command reference](docs/commands.md).
-
-## Local board workflow
-
-Trekoon ships a no-extra-install local board for browsing and updating work in a
-browser.
-
-- `trekoon init` creates the shared `.trekoon` storage, database, and board
-  runtime under `.trekoon/board`
-- `trekoon board open` ensures those bundled board assets are installed, starts a
-  token-gated loopback server on `127.0.0.1`, and launches the browser
-- `trekoon board update` refreshes the board runtime assets only; it does not
-  start the server or open a browser
-
-Keep the operator path simple:
+### Plan
 
-```bash
-trekoon board open
-```
+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.
 
-Use `trekoon board update` only when you want to refresh the copied runtime
-assets without opening a session.
+```
+/trekoon plan <description>
+```
 
-The browser flow is local-only by design:
+What the agent does during planning:
 
-- Trekoon copies the board shell and app files into repo-shared storage, so the
-  board still starts with one CLI command and no separate frontend build step
-- the board server binds only to `127.0.0.1`
-- every `board open` session uses a per-session token in the URL/API requests
-- command output always includes a manual fallback URL if the browser launch
-  fails
+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
 
-Current runtime expectations:
+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
+task and execute it without re-reading the codebase to figure out what to do.
 
-- the local runtime is served from `.trekoon/board`
-- all assets are self-hosted: the board ships its own CSS, fonts (Inter,
-  Material Symbols), and vanilla JS with no framework or CDN dependencies
-- the board works fully offline once `trekoon board open` copies the runtime
-  assets into `.trekoon/board`
+### Execute
 
-Current board behavior to expect:
+Point the agent at an epic and it works through the dependency graph
+automatically. It is recommended to do it with clean context window.
 
-- the topbar is a compact single-row navbar showing the Trekoon brand, Epics
-  and Board navigation, search, theme toggle, and a workspace info popover;
-  selecting an epic adds the active epic context to the topbar
-- the board toggles between an epics overview and a task workspace view; task
-  detail opens as a modal overlay; responsive breakpoints adjust kanban column
-  counts and component spacing
-- the page scrolls naturally as a single SPA surface; modal overlays (task
-  detail, subtask editor) lock body scroll while open
-- overview cards are the primary entry point into an epic; clicking a card opens
-  that epic's board workspace
-- task cards show truncated descriptions; clicking anywhere on a card opens the
-  task detail modal with the full description
-- search is debounced and filters client-side across titles, descriptions,
-  statuses, and subtask content
+```
+/trekoon <id> execute
+```
 
-For the full lifecycle and examples, read [Quickstart](docs/quickstart.md) and
-[Command reference](docs/commands.md).
+What the agent does during execution:
 
-## AI skill
+1. Runs `session --epic <id>` to get diagnostics, sync status, and the first
+   ready task
+2. Marks the epic `in_progress`
+3. Groups ready tasks into lanes by subsystem to minimize redundant codebase
+   exploration
+4. Spawns sub-agents for parallel lanes (auth tasks go to one agent, billing
+   tasks to another)
+5. Each sub-agent claims a task, does the work, appends progress notes, and
+   calls `task done`
+6. `task done` returns which downstream tasks just became unblocked, so the
+   orchestrator knows what to dispatch next
+7. After all tasks complete: code review, tests, manual verification, then marks
+   the epic `done`
 
-Trekoon ships with a self-contained `trekoon` skill for AI agents. One skill
-covers the full plan-to-completion workflow:
+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.
 
-- **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`)
+## Install the skill
 
-Install it per-repo or globally:
+The `trekoon` skill is what teaches agents the planning methodology, execution
+orchestration, status machine rules, and command reference. Without the skill,
+agents don't know how to use Trekoon properly.
 
 ```bash
-trekoon skills install          # repo-local (default)
+trekoon skills install          # repo-local (.agents/skills/trekoon/)
 trekoon skills install -g       # global (~/.agents/skills/trekoon)
-trekoon update                  # refresh all installed links
+trekoon update                  # refresh all installed skills
 ```
 
-The skill accepts arguments for quick entity-scoped actions:
+The skill bundles three reference documents that agents load on demand:
+
+| Agent needs to... | Skill reads | What it covers |
+| --- | --- | --- |
+| Plan a feature | `reference/planning.md` | Decomposition, writing standard, dependency modeling, validation |
+| Execute an epic | `reference/execution.md` | Graph building, lane grouping, sub-agent dispatch, verification (universal) |
+| Execute with Agent Teams | `reference/execution-with-team.md` | TeamCreate/SendMessage, parallel Claude Code instances in tmux |
+
+### Invoke the skill
 
 ```
 /trekoon                     → load the skill
+/trekoon plan                → decompose into tasks/subtasks/deps
 /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
+/trekoon <id> execute        → start the execution loop
+/trekoon <id> analyze        → run progress + suggest, report findings
 ```
 
-Read [AI agents and the Trekoon skill](docs/ai-agents.md) for installation,
-editor linking, and example prompts.
+### Example prompts
+
+Plan only:
+
+```
+/trekoon — plan this feature as one epic with tasks, subtasks, and dependencies
+```
 
-## Read next
+Execute only:
+
+```
+/trekoon <epic-id> execute
+```
+
+Plan and execute end to end:
+
+```
+/trekoon — plan this feature, create the backlog, then execute the tasks in
+dependency order until the epic is complete
+```
+
+## Agent Teams
+
+For larger epics, Trekoon supports Claude Code Agent Teams. Instead of
+sequential sub-agents, you get real parallel Claude Code instances coordinated
+through `TeamCreate` and `SendMessage`, each running in its own tmux pane.
+
+Requires Claude Code env variable `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=true`.
+
+The team lead orchestrator creates a team, populates a shared task list, spawns
+3-5 teammates per lane, and coordinates via messages. Teammates claim tasks,
+report completions and blockers, and the lead dispatches new work as tasks get
+unblocked.
+
+## Status machine
+
+Trekoon enforces valid transitions. You can't skip straight from `todo` to
+`done`.
+
+| From | Allowed targets |
+| --- | --- |
+| `todo` | `in_progress`, `blocked` |
+| `in_progress` | `done`, `blocked` |
+| `blocked` | `in_progress`, `todo` |
+| `done` | `in_progress` |
+
+Exception: `task done` auto-transitions through `in_progress`, so agents can
+call it from any non-done status.
+
+## Local board
+
+Trekoon includes a browser-based board for humans who like having visual overview.
+No build step, no framework dependencies, works offline.
+
+```bash
+trekoon board open      # starts a local server, opens browser
+trekoon board update    # refresh assets only
+```
+
+Binds to `127.0.0.1` only with a per-session token. Gives you an epics
+overview, kanban workspace per epic, task detail modals, and search.
+
+## Commands
+
+| What you want to do | How |
+| --- | --- |
+| Set up a repo | `trekoon init` |
+| Open the local board | `trekoon board open` |
+| Plan work | `trekoon epic create ...`, `trekoon epic expand ...` |
+| Create tasks in bulk | `trekoon task create-many ...` |
+| Add dependencies | `trekoon dep add-many ...` |
+| Start an agent session | `trekoon session --epic <id>` |
+| Get next-action suggestions | `trekoon suggest --epic <id>` |
+| Check epic progress | `trekoon epic progress <id>` |
+| Mark a task done | `trekoon task done <id>` |
+| Sync across worktrees | `trekoon sync pull --from main` |
+| Get help | `trekoon [command] -h` |
+
+Every command supports `--toon`, `--json`, `--compact` for structured output.
+
+Full flag reference in [docs/commands.md](docs/commands.md).
+
+## Docs
 
 - [Quickstart](docs/quickstart.md)
 - [Command reference](docs/commands.md)
@@ -169,10 +202,3 @@ editor linking, and example prompts.
 - [Machine contracts](docs/machine-contracts.md)
 - [Contributing](CONTRIBUTING.md)
 - [Changelog](CHANGELOG.md)
-
-## Implementation principles
-
-- Minimal, composable modules
-- Strict validation at command boundaries
-- Stable automation envelopes for JSON and TOON modes
-- No unnecessary feature sprawl