@kanon-pm/setup 0.4.0 → 0.5.0

package/assets/skills/kanon-init/SKILL.md

@@ -3,6 +3,11 @@ name: kanon-init
 description: Automated project onboarding — scan codebase, create Kanon project, seed initial issues, groups, and roadmap items from TODOs and architecture gaps
 version: 2.0.0
 tags: [kanon, onboarding, project-setup, codebase-scan, batch]
+allowed-tools:
+  - kanon_*
+  - mem_save
+  - mem_search
+  - mem_get_observation
 ---
 
 # Kanon Init — Automated Project Onboarding
@@ -23,33 +28,21 @@ Supports two modes:
 
 ## Inputs
 
-The skill accepts optional inputs. When invoked by a sub-agent or orchestrator, these are passed directly. When invoked interactively, they are derived during execution.
-
 | Input | Type | Required | Description |
 |-------|------|----------|-------------|
 | `workspaceId` | string | No | If provided, skip workspace selection (batch mode) |
 | `projectKey` | string | No | If provided, skip project creation and seed into existing project |
 | `projectName` | string | No | Override the derived project name |
 
-**Mode detection**: If `workspaceId` is provided as input, run in **batch mode** (zero prompts). Otherwise, run in **interactive mode**.
+**Mode detection**: If `workspaceId` is provided, run in **batch mode** (zero prompts). Otherwise, **interactive mode**.
 
 ---
 
 ## Prerequisites
 
-Before starting, load the Kanon MCP tools via ToolSearch:
-
-```
-ToolSearch: select:mcp__kanon__kanon_list_workspaces,mcp__kanon__kanon_create_project,mcp__kanon__kanon_list_projects,mcp__kanon__kanon_list_issues,mcp__kanon__kanon_create_issue,mcp__kanon__kanon_list_roadmap,mcp__kanon__kanon_create_roadmap_item,mcp__kanon__kanon_get_project,mcp__kanon__kanon_list_groups
-```
-
-If ToolSearch returns no results, the Kanon MCP server is not configured. Stop and tell the user:
-> "The Kanon MCP server is not configured in your Claude Code settings. Add the Kanon MCP server configuration and try again."
+Load Kanon MCP tools via ToolSearch. If tools are not available, stop and tell the user to configure the Kanon MCP server.
 
-Call `kanon_list_workspaces()` to verify connectivity. If it fails, stop and tell the user:
-> "The Kanon MCP server is not reachable. Make sure the Kanon API is running, the MCP server is configured in your Claude Code settings, and the `KANON_API_KEY` environment variable is set."
-
-Do NOT proceed past this point if connectivity fails.
+Call `kanon_list_workspaces()` to verify connectivity. If it fails, stop and report the MCP server is not reachable.
 
 ---
 
@@ -62,12 +55,12 @@ Scan the codebase to understand its structure, tech stack, and areas of concern.
 Scan top-level directories and workspace packages:
 
 ```
-Glob("*")           → top-level dirs and files
-Glob("packages/*")  → monorepo packages (if packages/ exists)
-Glob("src/*")       → flat project subdirs (if no packages/)
+Glob("*")           -> top-level dirs and files
+Glob("packages/*")  -> monorepo packages (if packages/ exists)
+Glob("src/*")       -> flat project subdirs (if no packages/)
 ```
 
-Map directories to human-readable groups using this table. Apply in order, first match wins per directory. **Cap at 5 groups.**
+Map directories to human-readable groups. **Cap at 5 groups.**
 
 | Directory pattern | groupKey | Group name |
 |---|---|---|
@@ -75,38 +68,36 @@ Map directories to human-readable groups using this table. Apply in order, first
 | `packages/web`, `web/`, `client/`, `frontend/` | `web` | Frontend |
 | `packages/mcp` | `mcp` | MCP |
 | `packages/cli`, `cli/` | `cli` | CLI |
-| `infra/`, `deploy/`, `docker/`, `.github/`, `terraform/`, `k8s/` | `infra` | Infrastructure |
-| `packages/{name}` (any other) | `{name}` | (Capitalize directory name) |
-| `src/{subdir}` (flat project) | `{subdir}` | (Capitalize subdir name) |
+| `infra/`, `deploy/`, `docker/`, `.github/`, `terraform/` | `infra` | Infrastructure |
+| `packages/{name}` (any other) | `{name}` | (Capitalize name) |
+| `src/{subdir}` (flat project) | `{subdir}` | (Capitalize subdir) |
 
 **Priority when capping at 5**: API > Frontend > Infrastructure > others alphabetically.
 
 ### 1b: Tech Stack Detection
 
-Read manifest files at the project root (and workspace package roots for monorepos):
+Read manifest files at project root (and workspace package roots for monorepos):
 
 | File | Extract |
 |------|---------|
-| `package.json` | `name`, `description`, `dependencies`, `devDependencies`, `workspaces` |
+| `package.json` | `name`, `description`, `dependencies`, `workspaces` |
 | `go.mod` | Module path, Go version |
 | `Cargo.toml` | Package name, dependencies |
 | `pyproject.toml` | Project name, dependencies |
 
-From dependencies, detect frameworks (Express, Fastify, React, Next.js, etc.), databases (Prisma, TypeORM, etc.), testing (Vitest, Jest, pytest, etc.), and build tools (Turbo, Nx, etc.).
+Detect frameworks, databases, testing tools, and build tools from dependencies.
 
 ### 1c: TODO/FIXME Scan
 
-Grep all source files for actionable comments:
-
 ```
 Grep(pattern: "TODO|FIXME|HACK|XXX", output_mode: "content", head_limit: 20)
 ```
 
-Collect each match with file path and line number. Filter out bare markers (lines where `TODO` or `FIXME` is the only content with no descriptive text). Keep entries that have meaningful text after the marker.
+Filter out bare markers with no descriptive text. Keep entries with meaningful text after the marker.
 
 ### 1d: Architecture Gap Detection
 
-Check for the existence of these paths. Missing = gap.
+Check for these paths. Missing = gap.
 
 | Path to check | Gap if missing |
 |---|---|
@@ -123,64 +114,37 @@ If `README.md` exists, read the first 50 lines to extract the project's stated p
 
 ### 1f: Derive Project Metadata
 
-From the scan, derive:
-- **Project name**: from `package.json` `name` field, `go.mod` module, or directory name
-- **Project key**: uppercase, max 6 chars, derived from name (e.g., "kanon" -> "KAN", "my-cool-app" -> "MCA"). Must match `^[A-Z][A-Z0-9]*$`
-- **Description**: from README first line or `package.json` description, or "No description found"
+- **Project name**: from `package.json` `name`, `go.mod` module, or directory name
+- **Project key**: uppercase, max 6 chars, derived from name (e.g., "kanon" -> "KAN"). Must match `^[A-Z][A-Z0-9]*$`
+- **Description**: from README first line or `package.json` description
 
 ---
 
 ## Phase 2: Resolve Project
 
-Ensure the Kanon project exists without creating duplicates.
-
 ### 2a: Workspace Selection
 
-- **Batch mode** (`workspaceId` provided): Use the provided `workspaceId`. No prompts.
-- **Interactive mode** (`workspaceId` not provided):
-  - Call `kanon_list_workspaces()`.
-  - If exactly one workspace: auto-select it, inform the user.
-  - If multiple: present a numbered list and ask the user to choose.
-  - If none: stop and tell the user to create a workspace first.
+- **Batch mode**: Use provided `workspaceId`.
+- **Interactive mode**: Call `kanon_list_workspaces()`. If one workspace, auto-select. If multiple, ask user. If none, stop.
 
 ### 2b: Project Lookup
 
 Call `kanon_list_projects(workspaceId)`.
 
-- **If a project with the derived key already exists**: Reuse it. Log:
-  > "Project **{KEY}** already exists. Reusing it for seeding."
-- **If no match**: Create the project:
-  ```
-  kanon_create_project(
-    workspaceId: "{workspaceId}",
-    key: "{KEY}",
-    name: "{projectName}",
-    description: "{description}"
-  )
-  ```
-
-Store the `projectKey` for Phase 3.
+- If project with derived key exists: reuse it.
+- If no match: create via `kanon_create_project`.
 
 ---
 
 ## Phase 3: Seed Content
 
-Create issues and roadmap items based on discovery results. This phase runs as a batch with no user prompts in batch mode.
-
 ### 3a: Idempotency Check
 
-Call these once and cache the results:
-
-```
-kanon_list_issues(projectKey: "{KEY}")
-kanon_list_roadmap(projectKey: "{KEY}")
-```
-
-Use these to skip items whose title matches an existing issue or roadmap item. Match logic: existing title starts with the same `[Area]` prefix AND contains the same key noun.
+Call `kanon_list_issues` and `kanon_list_roadmap` once, cache results. Skip items whose title matches an existing issue or roadmap item.
 
 ### 3b: Interactive Confirmation (interactive mode only)
 
-In interactive mode, before creating anything, present a confirmation table:
+Present a confirmation table before creating anything:
 
 ```
 ## Proposed Items
@@ -189,74 +153,33 @@ In interactive mode, before creating anything, present a confirmation table:
 |---|------|-------|-------|
 | 1 | issue | [API] Fix N+1 query in user list | api |
 | 2 | issue | [Infra] Set up GitHub Actions | infra |
-| ... | | | |
-| 11 | roadmap | Add test infrastructure | — |
+| 11 | roadmap | Add test infrastructure | - |
 
 Create all {N} items? (y/n)
 ```
 
-Wait for user confirmation. If declined, skip creation entirely.
-
-In **batch mode**, skip this step — create everything silently.
+In **batch mode**, skip this step.
 
 ### 3c: Issue Creation
 
-Create issues in priority order, respecting a **total cap of 10 issues**:
+Create issues in priority order, **cap at 10 issues**:
 
-1. **FIXME bugs** (up to 3): Type `bug`, priority `high`
-2. **Architecture gaps** (up to 4): Type `task`, priority `medium`
-3. **TODO tasks** (up to 3): Type `task`, priority `medium`
+1. **FIXME bugs** (up to 3): type `bug`, priority `high`
+2. **Architecture gaps** (up to 4): type `task`, priority `medium`
+3. **TODO tasks** (up to 3): type `task`, priority `medium`
 
-If fewer items exist in a category, overflow the budget to the next category.
-
-#### Issue Templates
-
-**TODO/FIXME issue:**
-```
-kanon_create_issue(
-  projectKey: "{KEY}",
-  title: "[{Area}] {Cleaned TODO/FIXME text}",
-  type: "task" | "bug",           // task for TODO, bug for FIXME
-  priority: "medium" | "high",    // medium for TODO, high for FIXME
-  description: "Found at `{file}:{line}`\n\n> {original line}\n\nExtracted from codebase scan.",
-  groupKey: "{area-groupKey}"
-)
-```
-
-**Architecture gap issue:**
-```
-kanon_create_issue(
-  projectKey: "{KEY}",
-  title: "[{Area}] Set up {missing thing}",
-  type: "task",
-  priority: "medium",
-  description: "The project is missing {thing}. This impacts {reason}.",
-  groupKey: "{area-groupKey}"       // typically "infra" for CI/Docker/linting gaps
-)
-```
-
-**Starter issue (based on tech stack):**
-```
-kanon_create_issue(
-  projectKey: "{KEY}",
-  title: "[{Area}] {Common setup task}",
-  type: "task",
-  priority: "low",
-  description: "Detected {framework/tool} in the stack. This is a common setup improvement.",
-  groupKey: "{area-groupKey}"
-)
-```
+If fewer items in a category, overflow budget to next.
 
 #### Title Format
 
 Always use: `[Area] Verb phrase`
 
-Good: `[API] Add request validation middleware`, `[Infra] Set up GitHub Actions CI`
-Bad: `TODO fix auth`, `packages/api needs work`
+Good: `[API] Add request validation middleware`
+Bad: `TODO fix auth`
 
 ### 3d: Roadmap Item Creation
 
-Create roadmap items for larger concerns detected during discovery. **Cap at 5 items.** Only create for gaps actually detected. Status: `idea` for all.
+Create roadmap items for larger concerns. **Cap at 5 items.** Status: `idea` for all.
 
 | Gap detected | Roadmap title | Horizon | Effort | Impact |
 |---|---|---|---|---|
@@ -266,37 +189,19 @@ Create roadmap items for larger concerns detected during discovery. **Cap at 5 i
 | No Dockerfile | Add containerization | `next` | 2 | 3 |
 | No linting config | Set up linting and formatting | `later` | 1 | 2 |
 
-```
-kanon_create_roadmap_item(
-  projectKey: "{KEY}",
-  title: "{roadmap title}",
-  horizon: "now" | "next" | "later",
-  effort: {1-5},
-  impact: {1-5},
-  description: "{why this matters}",
-  status: "idea"
-)
-```
-
-Skip any roadmap item whose title matches an existing roadmap item (idempotency).
-
 ### 3e: MCP Call Sequence
 
-Execute in this order:
-
 1. `kanon_list_issues(projectKey)` — cache for dedup
 2. `kanon_list_roadmap(projectKey)` — cache for dedup
-3. For each issue (in priority order): `kanon_create_issue(...)` — skip duplicates
+3. For each issue: `kanon_create_issue(...)` — skip duplicates
 4. For each roadmap item: `kanon_create_roadmap_item(...)` — skip duplicates
 
-If any individual MCP call fails, log a warning and continue with the remaining items. Do not abort the entire flow.
+If any MCP call fails, log a warning and continue.
 
 ---
 
 ## Phase 4: Report
 
-Present results and persist context.
-
 ### 4a: Summary Table
 
 ```
@@ -307,57 +212,34 @@ Present results and persist context.
 | Project | 1 | {KEY} ({created | reused}) |
 | Groups | {N} | {group1}, {group2}, ... |
 | Issues created | {N} | {X} bugs, {Y} tasks |
-| Issues skipped (duplicates) | {N} | — |
-| Roadmap items created | {N} | — |
-| Roadmap items skipped | {N} | — |
+| Issues skipped | {N} | - |
+| Roadmap items created | {N} | - |
+| Roadmap items skipped | {N} | - |
 ```
 
 ### 4b: Save to Engram
 
-```
-mem_save(
-  title: "Kanon project onboarded: {KEY}",
-  type: "architecture",
-  project: "{engram-project-name or KEY lowercase}",
-  topic_key: "kanon-project/{KEY}",
-  content: "
-    **What**: Created/reused Kanon project {KEY} ({name}) in workspace {workspace-name}
-    **Tech stack**: {detected stack summary}
-    **Monorepo**: {yes/no}
-    **Groups**: {group list}
-    **Workspace ID**: {workspaceId}
-    **Project key**: {KEY}
-    **Issues created**: {N} ({breakdown by type})
-    **Roadmap items created**: {N}
-  "
-)
-```
+Save project onboarding context with `topic_key: kanon-project/{KEY}`.
 
 ---
 
 ## Edge Cases
 
-**No recognizable project files found**: Derive minimal metadata from the directory name. Still allow project creation and seeding of architecture-gap issues.
-
-**Key exceeds 6 characters**: Truncate intelligently. Prefer acronyms (e.g., "my-cool-app" -> "MCA") over simple truncation. Validate key matches `^[A-Z][A-Z0-9]*$`.
-
-**Project key already exists**: Detected via `kanon_list_projects`. Reuse the existing project — do not create duplicates.
-
-**Very large codebase with many TODOs**: The 20-match grep cap and 10-issue creation cap prevent overwhelming the board. Prioritize FIXME entries and items with descriptive text.
-
-**Re-run on already-onboarded project**: Idempotency check (Phase 3a) prevents duplicate issues. New TODOs added since last run will be created.
-
-**No TODOs found**: Skip TODO-derived issues. Architecture-gap and starter issues are still created.
-
-**MCP call failure during seeding**: Log a warning and continue with remaining items. Never block the entire flow for a single failed call.
+- **No recognizable project files**: Derive metadata from directory name. Still allow project creation.
+- **Key exceeds 6 characters**: Truncate intelligently. Prefer acronyms.
+- **Project key already exists**: Reuse the existing project.
+- **Very large codebase**: The 20-match grep cap and 10-issue cap prevent overwhelming the board.
+- **Re-run on onboarded project**: Idempotency check prevents duplicates.
+- **No TODOs found**: Skip TODO-derived issues. Architecture-gap issues still created.
+- **MCP call failure**: Log warning and continue. Never block the entire flow.
 
 ---
 
 ## Best Practices
 
-1. **Clean titles for seeded issues** — TODO comments are often terse. Expand them into proper `[Area] Description` titles a teammate can understand.
+1. **Clean titles for seeded issues** — Expand terse TODO comments into proper `[Area] Description` titles.
 2. **Respect all caps** — 10 issues, 5 roadmap items, 5 groups. Quality over quantity.
-3. **Save to engram** — The onboarding context is valuable for future sessions. Do not skip Phase 4b.
-4. **Fail gracefully** — If any MCP call fails during seeding, log a warning and continue. Do not abort.
-5. **Idempotency first** — Always check for existing items before creating. A second run should produce zero duplicates.
-6. **One project per run** — For monorepos with multiple logical projects, suggest running once per sub-project.
+3. **Save to engram** — The onboarding context is valuable for future sessions.
+4. **Fail gracefully** — If any MCP call fails, log and continue.
+5. **Idempotency first** — Always check for existing items before creating.
+6. **One project per run** — For monorepos, suggest running once per sub-project.

package/assets/skills/kanon-mcp/SKILL.md

@@ -3,6 +3,11 @@ name: kanon-mcp
 description: Human-facing project board integration — clean cards, meaningful titles, progressive enrichment from SDD and general work
 version: 2.0.0
 tags: [kanon, project-management, sdd, issue-tracking]
+allowed-tools:
+  - kanon_*
+  - mem_save
+  - mem_search
+  - mem_get_observation
 ---
 
 # Kanon MCP — Usage Guide
@@ -23,31 +28,17 @@ Kanon is the **human-facing project board**. Every card should be readable by a
 
 ---
 
-## Available Tools
+## Issue Lifecycle
 
-### Project and Group Discovery
+1. **Pick issue**: `kanon_list_issues` — find assigned/available work
+2. **Start work**: `kanon_start_work(key)` — auto-assigns, warns about conflicts
+3. **Progress**: `kanon_transition_issue(key, "in_progress")`
+4. **Update**: `kanon_update_issue(key, {description/context})` as you work
+5. **Complete**: `kanon_transition_issue(key, "done")`
+6. **Release**: `kanon_stop_work(key)` — frees ownership
 
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `kanon_list_projects(workspaceId)` | List all projects in a workspace | `workspaceId` (required) |
-| `kanon_get_project(projectKey)` | Get full project details | `projectKey` (required) |
-| `kanon_list_groups(projectKey)` | List issue groups (epics, sprints, etc.) | `projectKey` (required) |
-
-### Issue Management
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `kanon_list_issues(projectKey, ...)` | List issues with optional filters | `projectKey` (required); filters: `state`, `type`, `priority`, `label`, `groupKey`, `assigneeId`, `sprintId` |
-| `kanon_get_issue(issueKey)` | Get full issue details | `issueKey` (required, e.g. `"KAN-42"`) |
-| `kanon_create_issue(projectKey, title, ...)` | Create a new issue | `projectKey`, `title` (required); optional: `type`, `priority`, `description`, `labels`, `groupKey`, `parentId`, `assigneeId`, `sprintId`, `dueDate` |
-| `kanon_update_issue(issueKey, ...)` | Update issue fields | `issueKey` (required); optional: `title`, `description`, `priority`, `labels`, `assigneeId`, `sprintId`, `dueDate` |
-
-### State Transitions
-
-| Tool | Purpose | Key Parameters |
-|------|---------|----------------|
-| `kanon_transition_issue(issueKey, state)` | Transition a single issue | `issueKey`, `state` (required) |
-| `kanon_batch_transition(projectKey, groupKey, state)` | Transition all issues in a group | `projectKey`, `groupKey`, `state` (required) |
+ALWAYS call `start_work` before implementing. ALWAYS call `stop_work` when done.
+Check `activeWorkers` in issue responses for conflict awareness.
 
 ---
 
@@ -75,16 +66,12 @@ The area tag groups related work visually on the board.
 - `[Bridge] Sync engine connection pooling`
 - `[Auth] JWT token refresh race condition`
 - `[UI] Dark mode toggle in settings`
-- `[API] Rate limiting for public endpoints`
 
 **Bad titles (never do this):**
 - `sdd/sync-engine/proposal`
-- `sdd-new/kanon-bridge/spec`
 - `apply dark-mode`
 - `Implement feature`
 
-When creating an issue, derive the area from the feature domain and write the action in plain language a teammate would understand.
-
 ---
 
 ## Progressive Description Enrichment
@@ -106,7 +93,6 @@ As work progresses, the issue description builds up incrementally. Each phase ap
 ## Tasks
 - [x] Task 1 — completed
 - [ ] Task 2 — in progress
-- [ ] Task 3 — pending
 [Added during tasks phase, checkboxes updated during apply]
 
 ## Verification
@@ -115,7 +101,6 @@ As work progresses, the issue description builds up incrementally. Each phase ap
 ## Engram References
 - `sdd/{change}/proposal` — Full proposal details
 - `sdd/{change}/spec` — Complete specification
-- `sdd/{change}/design` — Architecture decisions
 [Each phase appends its topic_key here as a breadcrumb trail]
 ```
 
@@ -125,11 +110,11 @@ As work progresses, the issue description builds up incrementally. Each phase ap
 |------------------|-----------------------|----------------|
 | explore | **Context** | Investigation findings, problem statement |
 | propose | **Context** (update) | Proposal intent, scope, constraints |
-| design | **Approach** | Architecture decisions, tradeoffs, diagrams |
-| spec | **Spec Summary** | Key requirements, acceptance criteria, scenarios |
-| tasks | **Tasks** | Checklist of work items with descriptions |
+| design | **Approach** | Architecture decisions, tradeoffs |
+| spec | **Spec Summary** | Key requirements, acceptance criteria |
+| tasks | **Tasks** | Checklist of work items |
 | apply | **Tasks** (update) | Check off completed items, note deviations |
-| verify | **Verification** | Test results, compliance, remaining concerns |
+| verify | **Verification** | Test results, compliance |
 | archive | All sections | Final polish, ensure completeness |
 
 Every phase also appends its engram `topic_key` to the **Engram References** section.
@@ -140,109 +125,44 @@ Every phase also appends its engram `topic_key` to the **Engram References** sec
 
 Create Kanon issues whenever the agent:
 
-- **Starts meaningful work** — not just SDD, any substantial task the user requests
+- **Starts meaningful work** — not just SDD, any substantial task
 - **Discovers a bug** worth tracking during implementation
 - **Identifies technical debt** that should not be forgotten
 - **Finds follow-up items** during code review or verification
 
-Before creating, call `kanon_list_issues` to check for duplicates or related existing cards.
-
-Before creating an issue, call `kanon_list_groups(projectKey)` to discover available groups. If the issue's domain or area matches an existing group, assign it via `groupKey`.
+Before creating, call `kanon_list_issues` to check for duplicates.
+Before creating, call `kanon_list_groups(projectKey)` to discover available groups and assign `groupKey`.
 
 ### Labels for Categorization
 
-Use labels to make the board scannable:
-
 | Label | When to use |
 |-------|-------------|
 | `sdd` | Work driven by SDD workflow |
 | `bug` | Bugs found during any work |
-| `tech-debt` | Identified technical debt for later |
+| `tech-debt` | Identified technical debt |
 | `exploration` | Spikes, investigations, research |
 
-Use groups for epics or feature areas when the project has them.
-
----
-
-## SDD Integration
-
-### Orchestrator Protocol
-
-#### On `/sdd-new {change}`
-
-1. Create ONE Kanon issue with a clean human-readable title:
-   ```
-   kanon_create_issue(
-     projectKey: "{projectKey}",
-     title: "[{Area}] {Human-readable description}",
-     type: "{mapped-type}",
-     description: "## Context\n{Initial change description}",
-     labels: ["sdd"],
-     groupKey: "{groupKey}"  // from kanon_list_groups — match area to group
-   )
-   ```
-2. If the title is ambiguous, ask the user: "What should this card be called on the board?"
-3. Store the returned `issueKey` for ALL subsequent phases.
-4. Set initial state to `explore` or `propose` depending on which phase runs first.
-
-#### On each SDD phase launch
-
-Pass the issue key and project key to the sub-agent:
-```
-KANON: Project `{projectKey}`, issue `{issueKey}`.
-  - Transition to `{phase_state}` at phase start.
-  - After completing work, update the issue description to append your phase's findings.
-  - Append your engram topic_key to the "Engram References" section.
-```
-
-#### Type Mapping
-
-| SDD Change Type | Kanon Issue Type |
-|-----------------|------------------|
-| feature | `feature` |
-| bugfix | `bug` |
-| refactor | `task` |
-| investigation | `spike` |
-
-### Sub-Agent Responsibilities
-
-Sub-agents that receive `kanon_issue_key` and `kanon_project_key`:
-
-1. **FIRST action** — Transition the issue:
-   ```
-   kanon_transition_issue(issueKey: "{kanon_issue_key}", state: "{phase_state}")
-   ```
-2. **Do their phase work** — explore, design, spec, etc.
-3. **LAST action before return** — Update the issue description:
-   - Call `kanon_get_issue` to read the current description.
-   - Append the relevant section (see Phase-Specific Enrichment Rules above).
-   - Append the engram topic_key to "Engram References".
-   - Call `kanon_update_issue` with the updated description.
-4. **If any Kanon call fails** — Log a warning and continue. Never block work due to a Kanon error.
-5. **Return envelope** — Include `kanon_issue_key` under `artifacts`.
-
 ---
 
 ## Non-SDD Usage
 
 Kanon is not only for SDD. Use it as a general work tracker:
 
-- **Track bugs found during work** — Create a card with type `bug`, label `bug`, clear title, and reproduction steps in the description.
-- **Create follow-up cards** — When implementation reveals additional work, create a new issue linked via description reference.
-- **Update existing issues** — When doing work related to an existing card, update its description with progress or findings.
-- **Check for related work** — Before creating a new issue, call `kanon_list_issues` with relevant filters to avoid duplicates.
-- **Close completed work** — Transition to `archived` when done, with a final description update summarizing the outcome.
+- **Track bugs found during work** — Create a card with type `bug`, clear title, and reproduction steps.
+- **Create follow-up cards** — When implementation reveals additional work, create a new issue.
+- **Update existing issues** — When doing related work, update the description with progress.
+- **Close completed work** — Transition to `archived` when done, with a final description update.
 
 ---
 
 ## Best Practices
 
-1. **Titles are for humans** — Write every title as if a teammate will scan it on a board. No internal identifiers, no SDD jargon.
-2. **Descriptions tell the story** — A person opening the card should understand what, why, how, and current status without any other tool.
-3. **One card, one unit of work** — Resist the urge to create cards for SDD phases. The phases are workflow steps, not work items.
-4. **Get before update** — Always call `kanon_get_issue` before `kanon_update_issue` to read current state and avoid overwriting content.
-5. **Use filters when listing** — Always use the most specific filters available. Avoid listing all issues unfiltered.
-6. **Issue keys are stable** — Store and pass `issueKey` (e.g. `KAN-42`) as the canonical reference. Do not rely on titles.
+1. **Titles are for humans** — Write every title as if a teammate will scan it on a board.
+2. **Descriptions tell the story** — A person opening the card should understand what, why, how, and current status.
+3. **One card, one unit of work** — Do not create cards for SDD phases. Phases are workflow steps, not work items.
+4. **Get before update** — Always call `kanon_get_issue` before `kanon_update_issue` to avoid overwriting content.
+5. **Use filters when listing** — Always use the most specific filters available.
+6. **Issue keys are stable** — Store and pass `issueKey` (e.g. `KAN-42`) as the canonical reference.
 7. **Batch transitions** — Use `kanon_batch_transition` when moving all issues in a group to the same state.
-8. **Engram references are breadcrumbs** — Always include them so a future agent (or curious human) can dive deeper.
-9. **Always check available groups** — Call `kanon_list_groups(projectKey)` before creating an issue. Ungrouped issues are harder to find on the board.
+8. **Engram references are breadcrumbs** — Always include them so a future agent can dive deeper.
+9. **Always check available groups** — Call `kanon_list_groups(projectKey)` before creating an issue.