@kanon-pm/setup 0.2.0

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

@@ -0,0 +1,363 @@
+---
+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]
+---
+
+# Kanon Init — Automated Project Onboarding
+
+Scan the current codebase, resolve or create a Kanon project, seed issues and roadmap items from TODO/FIXME comments and architecture gaps, and report results. One command takes a repo from unknown to fully tracked.
+
+Supports two modes:
+- **Interactive** (user-invoked via `/kanon-init`): workspace selection + single confirmation before creation
+- **Batch** (sub-agent): zero interaction, workspace/project params passed as inputs
+
+---
+
+## Trigger
+
+`/kanon-init`, `init project`, new project onboarding
+
+---
+
+## 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**.
+
+---
+
+## 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."
+
+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.
+
+---
+
+## Phase 1: Discover
+
+Scan the codebase to understand its structure, tech stack, and areas of concern.
+
+### 1a: Directory Structure and Area Derivation
+
+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/)
+```
+
+Map directories to human-readable groups using this table. Apply in order, first match wins per directory. **Cap at 5 groups.**
+
+| Directory pattern | groupKey | Group name |
+|---|---|---|
+| `packages/api`, `api/`, `server/` | `api` | API |
+| `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) |
+
+**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):
+
+| File | Extract |
+|------|---------|
+| `package.json` | `name`, `description`, `dependencies`, `devDependencies`, `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.).
+
+### 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.
+
+### 1d: Architecture Gap Detection
+
+Check for the existence of these paths. Missing = gap.
+
+| Path to check | Gap if missing |
+|---|---|
+| `.github/workflows/` | CI/CD pipeline |
+| `Dockerfile` or `docker-compose.yml` | Containerization |
+| `.eslintrc*` or `eslint.config.*` | Linting configuration |
+| `vitest.config.*` or `jest.config.*` | Test configuration |
+| `README.md` | Project documentation |
+| `docs/` | Documentation directory |
+
+### 1e: README Content
+
+If `README.md` exists, read the first 50 lines to extract the project's stated purpose.
+
+### 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"
+
+---
+
+## 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.
+
+### 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.
+
+---
+
+## 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.
+
+### 3b: Interactive Confirmation (interactive mode only)
+
+In interactive mode, before creating anything, present a confirmation table:
+
+```
+## Proposed Items
+
+| # | Type | Title | Group |
+|---|------|-------|-------|
+| 1 | issue | [API] Fix N+1 query in user list | api |
+| 2 | issue | [Infra] Set up GitHub Actions | infra |
+| ... | | | |
+| 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.
+
+### 3c: Issue Creation
+
+Create issues in priority order, respecting a **total cap of 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`
+
+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}"
+)
+```
+
+#### 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`
+
+### 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.
+
+| Gap detected | Roadmap title | Horizon | Effort | Impact |
+|---|---|---|---|---|
+| No CI/CD pipeline | Add CI/CD pipeline | `now` | 3 | 5 |
+| No test configuration | Set up test infrastructure | `now` | 2 | 4 |
+| No docs/ directory | Add project documentation | `next` | 2 | 3 |
+| 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
+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.
+
+---
+
+## Phase 4: Report
+
+Present results and persist context.
+
+### 4a: Summary Table
+
+```
+## Kanon Init Summary
+
+| Category | Count | Details |
+|----------|-------|---------|
+| 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} | — |
+```
+
+### 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}
+  "
+)
+```
+
+---
+
+## 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.
+
+---
+
+## Best Practices
+
+1. **Clean titles for seeded issues** — TODO comments are often terse. Expand them into proper `[Area] Description` titles a teammate can understand.
+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.

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

@@ -0,0 +1,248 @@
+---
+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]
+---
+
+# Kanon MCP — Usage Guide
+
+Kanon is the **human-facing project board**. Every card should be readable by a person who has never touched the codebase. Engram holds the technical memory; Kanon holds the work narrative.
+
+---
+
+## Core Philosophy
+
+| Layer | Purpose | Audience |
+|-------|---------|----------|
+| **Kanon** | Track units of work with clean titles, rich descriptions, and meaningful states | Humans (developers, leads, stakeholders) |
+| **Engram** | Store SDD artifacts, technical decisions, and codebase knowledge | Agents across sessions |
+| **The agent** | Bridge both — create clean Kanon cards, enrich them with engram context | Both |
+
+**One issue = one unit of work.** SDD phases do NOT create separate issues. They transition the same issue through states and progressively enrich its description.
+
+---
+
+## Available Tools
+
+### Project and Group Discovery
+
+| 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) |
+
+---
+
+## Issue States
+
+`backlog` | `explore` | `propose` | `design` | `spec` | `tasks` | `apply` | `verify` | `archived`
+
+States reflect where the work currently stands — not which SDD phase generated an artifact.
+
+## Issue Types and Priorities
+
+**Types**: `feature`, `bug`, `task`, `spike`
+
+**Priorities**: `critical`, `high`, `medium`, `low` — assign meaningfully, not everything is `medium`.
+
+---
+
+## Human-Readable Issue Titles
+
+Titles follow the pattern: `[Area] Clear action description`
+
+The area tag groups related work visually on the board.
+
+**Good titles:**
+- `[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
+
+As work progresses, the issue description builds up incrementally. Each phase appends its section. A human opening the card sees the full story without needing engram access.
+
+### Target Description Structure
+
+```markdown
+## Context
+[Why this work exists — added during explore/propose phase]
+
+## Approach
+[Technical approach chosen — added during design phase]
+
+## Spec Summary
+[Key requirements, acceptance criteria, edge cases — added during spec phase]
+
+## Tasks
+- [x] Task 1 — completed
+- [ ] Task 2 — in progress
+- [ ] Task 3 — pending
+[Added during tasks phase, checkboxes updated during apply]
+
+## Verification
+[Test results, compliance status — added during verify phase]
+
+## 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]
+```
+
+### Phase-Specific Enrichment Rules
+
+| Phase Completing | Section to Add/Update | Content Source |
+|------------------|-----------------------|----------------|
+| 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 |
+| apply | **Tasks** (update) | Check off completed items, note deviations |
+| verify | **Verification** | Test results, compliance, remaining concerns |
+| archive | All sections | Final polish, ensure completeness |
+
+Every phase also appends its engram `topic_key` to the **Engram References** section.
+
+---
+
+## Proactive Issue Creation
+
+Create Kanon issues whenever the agent:
+
+- **Starts meaningful work** — not just SDD, any substantial task the user requests
+- **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`.
+
+### 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 |
+| `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.
+
+---
+
+## 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.
+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.

package/assets/skills/kanon-orchestrator-hooks/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: kanon-orchestrator-hooks
+description: Kanon-specific hooks for the SDD orchestrator — ROADMAP injection into sub-agent prompts and post-phase deferred_items processing
+version: 1.0.0
+tags: [kanon, sdd, orchestrator, roadmap]
+---
+
+# Kanon Orchestrator Hooks
+
+This skill is loaded by the orchestrator when launching SDD phases or processing phase results in the kanon project. It provides kanon-specific behavior that extends the generic SDD workflow.
+
+## Hook 1: ROADMAP Injection for Sub-Agent Launches
+
+When launching phases `sdd-explore`, `sdd-propose`, `sdd-design`, or `sdd-spec`, include this block in the sub-agent prompt:
+
+```
+ROADMAP: When you identify out-of-scope or deferred work, list it in your return envelope
+  under `deferred_items`. Format: title ([Area] Description), reason, suggested_horizon (later/someday).
+  The orchestrator handles roadmap capture — do NOT create roadmap items yourself.
+```
+
+## Hook 2: Post-Phase Roadmap Processing
+
+After receiving results from `sdd-explore`, `sdd-propose`, `sdd-design`, or `sdd-spec`:
+
+1. Check if `deferred_items` is present and non-empty in the return envelope.
+2. If yes, present to user: "This phase identified {N} items as out of scope. Add any to the roadmap?"
+3. For each confirmed item: load `kanon-roadmap` skill and follow Trigger 2 procedure (duplicate check via `kanon_list_roadmap`, create via `kanon_create_roadmap_item`, save to engram).
+4. If `kanon-roadmap` skill is not loaded, load it from `.claude/skills/kanon-roadmap/SKILL.md`.
+
+## Hook 3: Roadmap Capture During Conversation
+
+Detect these signals during any conversation in the kanon project:
+- "We should eventually...", "down the road", "someday", "not now but later"
+- User describes friction, workarounds, or missing features they defer
+- Out-of-scope items identified during any analysis
+
+Action:
+1. Acknowledge: "That sounds like a roadmap item for kanon."
+2. Confirm: "Want me to add it?"
+3. If yes: load `kanon-roadmap` skill for full capture behavior.
+
+Do NOT create roadmap items without user confirmation.