@kanon-pm/setup 0.4.0 → 0.5.0

package/assets/agents/kanon.md

@@ -0,0 +1,39 @@
+---
+name: kanon
+description: Project management delegate — handles Kanon board operations (issues, transitions, roadmap) without polluting main context
+allowed-tools:
+  - "mcp__kanon*"
+  - "mem_save"
+  - "mem_search"
+  - "mem_get_observation"
+model: haiku
+---
+
+You are a project management assistant using Kanon tools.
+
+## Your Role
+Handle ALL Kanon board operations delegated by the main agent:
+- Creating, updating, and transitioning issues
+- Managing roadmap items
+- Checking who's working on what
+- Reporting project status
+
+## Issue Lifecycle
+When asked to work on an issue:
+1. kanon_start_work(key) — signals active work, auto-assigns if unassigned
+2. kanon_transition_issue(key, "in_progress") — if not already
+3. Report back to the main agent with issue details and any warnings
+
+When work is complete:
+4. kanon_transition_issue(key, "done")
+5. kanon_stop_work(key) — releases ownership
+
+## Conflict Awareness
+- ALWAYS check activeWorkers when getting/listing issues
+- If someone else is working on an issue, WARN the main agent
+- Never silently override another developer's work
+
+## Communication
+- Be concise — return only essential information
+- Include issue key, title, status, and active workers
+- Flag conflicts prominently

package/assets/skills/kanon-create-issue/SKILL.md

@@ -1,8 +1,13 @@
 ---
-name: kanon-nl-create
+name: kanon-create-issue
 description: Natural Language Issue Creation — parse user descriptions of bugs, features, and tasks into well-structured Kanon issues without manual field-filling
 version: 1.0.0
 tags: [kanon, issue-creation, natural-language, productivity]
+allowed-tools:
+  - kanon_*
+  - mem_save
+  - mem_search
+  - mem_get_observation
 ---
 
 # Kanon NL Create — Natural Language Issue Creation
@@ -21,42 +26,25 @@ The goal is zero friction. The user should be able to say "track this bug with t
 
 ## Trigger Conditions
 
-Activate this skill when any of the following signals are present:
-
 ### Explicit creation requests
-- "Create an issue for..."
-- "Add a ticket for..."
-- "Open a card for..."
-- "Track this as..."
-- "Log a bug for..."
-- "File this as a task..."
-- "Can you create a Kanon issue for..."
+- "Create an issue for...", "Add a ticket for...", "Track this as...", "Log a bug for..."
 
 ### Implicit creation signals
 - User describes a bug or problem and says "let's track this" or "we should not forget this"
 - After a bug fix, the agent identifies follow-up work or remaining risk
-- User describes something in terms of "we need to...", "we should...", or "someone needs to..."
-- User narrates a task or feature while discussing related work
+- User describes something in terms of "we need to...", "we should..."
 
 ### Post-fix follow-up
-After completing a bug fix or feature, if the agent discovers:
-- Additional edge cases not addressed
-- Refactoring needed but deferred
-- Documentation gaps
-- Related components that may have the same issue
-
-The agent should say: "I also noticed [X] while working on this. Want me to create a follow-up issue?"
+After completing a bug fix or feature, if the agent discovers additional edge cases, deferred refactoring, or documentation gaps, suggest: "I also noticed [X]. Want me to create a follow-up issue?"
 
 ---
 
-## NL → Structured Field Mapping
+## NL to Structured Field Mapping
 
 ### Title
 
 - **Format**: `[Area] Imperative verb phrase`
-- **Imperative form**: Use action verbs — "Fix", "Add", "Refactor", "Implement", "Remove", "Investigate"
-- **Area**: Infer from domain or technology mentioned — `API`, `Auth`, `UI`, `DB`, `Infra`, `DX`, `Billing`, etc.
-- **Keep it scannable**: A teammate should understand the card at a glance on a board
+- **Area**: Infer from domain — `API`, `Auth`, `UI`, `DB`, `Infra`, `DX`, `Billing`, etc.
 
 | User says | Title |
 |-----------|-------|
@@ -67,44 +55,38 @@ The agent should say: "I also noticed [X] while working on this. Want me to crea
 
 ### Type
 
-Infer from the user's language:
-
 | Signal words / context | Type |
 |------------------------|------|
 | "bug", "broken", "not working", "error", "crash", "regression", "fix" | `bug` |
 | "add", "build", "implement", "new feature", "support", "allow users to" | `feature` |
-| "refactor", "clean up", "improve", "migrate", "rename", "move", "simplify" | `task` |
-| "investigate", "understand", "explore", "research", "figure out", "check if" | `spike` |
+| "refactor", "clean up", "improve", "migrate", "rename", "simplify" | `task` |
+| "investigate", "understand", "explore", "research", "figure out" | `spike` |
 
 When ambiguous, default to `task`.
 
 ### Priority
 
-Infer from urgency signals:
-
 | Signal | Priority |
 |--------|----------|
-| "blocking", "production down", "can't deploy", "urgent", "critical", "right now" | `critical` |
-| "before release", "important", "customer-facing", "this week", "high priority" | `high` |
-| "should fix", "eventually fix", "not urgent but", no strong signals | `medium` |
+| "blocking", "production down", "urgent", "critical", "right now" | `critical` |
+| "before release", "important", "customer-facing", "high priority" | `high` |
+| "should fix", "eventually", "not urgent but", no strong signals | `medium` |
 | "nice to have", "low priority", "someday", "minor", "cosmetic" | `low` |
 
 When no urgency signal is present, default to `medium`.
 
 ### Labels
 
-Infer from domain, technology, and concern type mentioned:
-
 | User mentions | Labels to add |
 |---------------|---------------|
-| Authentication, login, tokens, JWT, sessions | `auth` |
-| API endpoints, REST, GraphQL, rate limiting | `api` |
-| Database, queries, migrations, indexes | `db` |
-| UI components, styling, layout, dark mode | `ui` |
+| Authentication, login, tokens, JWT | `auth` |
+| API endpoints, REST, GraphQL | `api` |
+| Database, queries, migrations | `db` |
+| UI components, styling, layout | `ui` |
 | Performance, speed, latency, caching | `performance` |
-| Security vulnerabilities, XSS, injection | `security` |
+| Security vulnerabilities, XSS | `security` |
 | Infrastructure, deployment, CI/CD | `infra` |
-| Developer experience, tooling, scripts | `dx` |
+| Developer experience, tooling | `dx` |
 | Technical debt, cleanup, refactor | `tech-debt` |
 | Testing, coverage, flaky tests | `testing` |
 
@@ -112,45 +94,39 @@ Multiple labels are allowed and encouraged when multiple concerns are present.
 
 ### Description
 
-Always generate a structured markdown description. Use what the user said to fill in as much as possible. Leave sections as prompts when information is not available.
-
-**Template**:
+Always generate a structured markdown description.
 
+**Standard template**:
 ```markdown
 ## Context
-{What the problem or need is, derived from user's description}
+{What the problem or need is}
 
 ## Acceptance Criteria
-- {Condition 1 that must be true when this is done}
+- {Condition 1 that must be true when done}
 - {Condition 2}
-- {Add more as needed}
 
 ## Notes
-{Any technical context, reproduction steps, constraints, or references mentioned by the user}
+{Technical context, reproduction steps, constraints}
 ```
 
-For **bugs**, include a reproduction section if steps were mentioned:
-
+**Bug template** (when reproduction steps are available):
 ```markdown
 ## Context
 {Bug description}
 
 ## Reproduction Steps
 1. {Step 1}
-2. {Step 2}
-3. Expected: {what should happen}
-4. Actual: {what happens instead}
+2. Expected: {what should happen}
+3. Actual: {what happens instead}
 
 ## Acceptance Criteria
 - Bug no longer reproduces following the steps above
-- {Any additional fix criteria}
 
 ## Notes
 {Additional context}
 ```
 
-For **spikes**, use an outcome-oriented template:
-
+**Spike template**:
 ```markdown
 ## Context
 {Why this investigation is needed}
@@ -160,35 +136,22 @@ For **spikes**, use an outcome-oriented template:
 - {Question 2}
 
 ## Deliverable
-{What the spike should produce — a decision, a document, a prototype, a recommendation}
-
-## Notes
-{Any known constraints or starting points}
+{What the spike should produce — decision, document, prototype}
 ```
 
 ### Group
 
-Before creating any issue, call `kanon_list_groups(projectKey)` to discover available groups. Match the issue's area or domain keywords against existing group names. If a group matches, include `groupKey` in the creation call.
-
-| Issue area / domain | Group match strategy |
-|---------------------|----------------------|
-| Area tag in title (e.g., `Auth`, `API`, `UI`) | Match against group names case-insensitively |
-| Labels or domain keywords | Match if a group name contains or closely matches the keyword |
-| No match found | Omit `groupKey` — do not create groups, only use existing ones |
-
-If multiple groups could match, prefer the most specific one. When unsure, ask the user: "Should this go in the '{group}' group?"
+Before creating any issue, call `kanon_list_groups(projectKey)` to discover available groups. Match the issue's area against group names case-insensitively. If no match, omit `groupKey`.
 
 ### Default State
 
-Always create with `state: backlog` (the API default). Do not transition the issue unless the user explicitly says it is in progress or ready to start.
+Always create with `state: backlog`. Do not transition unless the user explicitly says it is in progress.
 
 ---
 
 ## Confirmation Pattern
 
-Before calling `kanon_create_issue`, always show a preview card and ask for confirmation. This prevents cluttering the board with misunderstood issues.
-
-**Card preview format**:
+Before calling `kanon_create_issue`, always show a preview card:
 
 ```
 Here is the issue I would create:
@@ -197,20 +160,17 @@ Here is the issue I would create:
   Type:        bug
   Priority:    high
   Labels:      auth, ui
-  Group:       Authentication       (matched from available groups)
+  Group:       Authentication
   State:       backlog
 
   Description:
   ## Context
   The login page redirects to a 404 error page after submitting credentials...
-  ...
 
 Create it? [yes / edit / cancel]
 ```
 
-If the user says "edit" or points out corrections, update the preview and show it again before creating.
-
-If the user says "yes" or similar confirmation, call `kanon_create_issue` and report the created issue key.
+If the user says "edit", update and show again. If "yes", create and report the issue key.
 
 ---
 
@@ -218,218 +178,54 @@ If the user says "yes" or similar confirmation, call `kanon_create_issue` and re
 
 ### Example 1: Simple Bug Report
 
-**User input**:
-> "There's a bug where logging in with Google OAuth redirects to a 404. Let's track it."
+**User**: "There's a bug where logging in with Google OAuth redirects to a 404. Let's track it."
 
-**Inferred structure**:
-- Title: `[Auth] Fix Google OAuth redirect to 404`
-- Type: `bug`
-- Priority: `medium` (no urgency signal)
-- Labels: `auth`
-- Description: Context with the reported behavior, acceptance criteria that the redirect no longer 404s
+**Inferred**: Title `[Auth] Fix Google OAuth redirect to 404`, type `bug`, priority `medium`, label `auth`.
 
-**Agent calls `kanon_list_groups("KAN")` and finds groups including `Authentication` (key: `auth-group`).**
+Agent calls `kanon_list_groups("KAN")`, finds `Authentication` group. Shows preview, user says "Yes, but make it high priority — it's blocking QA." Agent updates priority and creates.
 
-**Preview shown to user**:
-```
-Here is the issue I would create:
+**Result**: "Created KAN-47."
 
-  Title:       [Auth] Fix Google OAuth redirect to 404
-  Type:        bug
-  Priority:    medium
-  Labels:      auth
-  Group:       Authentication       (matched from available groups)
-  State:       backlog
+### Example 2: Vague Task Description
 
-  Description:
-  ## Context
-  Logging in with Google OAuth redirects to a 404 error page instead of the expected
-  post-login destination.
+**User**: "Add a task to investigate why our CI builds are taking so long."
 
-  ## Acceptance Criteria
-  - Google OAuth login completes without a 404 redirect
-  - User lands on the correct post-login page after authenticating
+**Inferred**: Title `[Infra] Investigate slow CI build times`, type `spike`, priority `medium`, labels `infra`, `dx`.
 
-  ## Notes
-  No reproduction steps provided. Investigate OAuth callback URL configuration.
+Description uses questions-to-answer format with deliverable being a recommendation. Preview shown, user confirms.
 
-Create it?
-```
-
-**User**: "Yes, but make it high priority — it's blocking QA."
-
-**Agent updates and creates**:
-```
-kanon_create_issue(
-  projectKey: "KAN",
-  title: "[Auth] Fix Google OAuth redirect to 404",
-  type: "bug",
-  priority: "high",
-  labels: ["auth"],
-  groupKey: "auth-group",  // matched "Authentication" group
-  description: "..."
-)
-```
-
-**Agent reports**: "Created KAN-47."
+**Result**: "Created KAN-50."
 
 ---
 
-### Example 2: Feature Request Mid-Conversation
+## Edge Cases
 
-**User input**:
-> "We should add rate limiting to the public API before we go live. Not urgent right now but let's not forget."
+**Project key unknown**: Ask the user or call `kanon_list_projects` to find it. Do not guess.
 
-**Inferred structure**:
-- Title: `[API] Add rate limiting for public endpoints`
-- Type: `feature`
-- Priority: `low` ("not urgent")
-- Labels: `api`, `security`
-- Description: Context about pre-launch requirement, acceptance criteria around per-endpoint limits
+**Very short description**: Generate a minimal but valid description. Better to create sparse than block on details.
 
-**Preview shown to user**:
-```
-Here is the issue I would create:
+**Conflicting signals** (e.g., "not urgent but critical"): Favor the strongest signal. If ambiguous, ask.
 
-  Title:       [API] Add rate limiting for public endpoints
-  Type:        feature
-  Priority:    low
-  Labels:      api, security
-  State:       backlog
+**Roadmap vs issue**: If user says "someday", "eventually", "down the road", suggest the roadmap instead: "This sounds more like a roadmap item — want me to add it there instead?"
 
-  Description:
-  ## Context
-  Rate limiting is needed on public API endpoints before the public launch to prevent
-  abuse and ensure fair usage.
-
-  ## Acceptance Criteria
-  - Rate limits are enforced on all public-facing API endpoints
-  - Requests exceeding the limit receive an appropriate error response (e.g., 429)
-  - Limits are configurable per endpoint or API key tier
-
-  ## Notes
-  Not urgent. To be addressed before public launch.
-
-Create it?
-```
-
-**User**: "Yes."
-
-**Agent creates and reports**: "Created KAN-48."
+**Multiple issues implied**: Identify each and offer to create separate issues.
 
 ---
 
-### Example 3: Post-Fix Follow-Up Discovery
-
-**Context**: Agent just finished fixing a memory leak in the image upload handler.
-
-**Agent proactively says**:
-> "While fixing the memory leak I noticed the video upload handler has the same pattern — it's not leaking yet but it will under load. Want me to create a follow-up issue for it?"
-
-**User**: "Yeah track it."
-
-**Inferred structure**:
-- Title: `[Media] Fix potential memory leak in video upload handler`
-- Type: `bug` (potential bug, proactive fix)
-- Priority: `medium`
-- Labels: `performance`
-
-**Preview shown and confirmed, then created**: "Created KAN-49."
-
----
-
-### Example 4: Vague Task Description
-
-**User input**:
-> "Add a task to investigate why our CI builds are taking so long."
-
-**Inferred structure**:
-- Title: `[Infra] Investigate slow CI build times`
-- Type: `spike`
-- Priority: `medium`
-- Labels: `infra`, `dx`
-- Description: Questions-to-answer format with deliverable being a recommendation
-
-**Preview shown to user**:
-```
-Here is the issue I would create:
-
-  Title:       [Infra] Investigate slow CI build times
-  Type:        spike
-  Priority:    medium
-  Labels:      infra, dx
-  State:       backlog
-
-  Description:
-  ## Context
-  CI builds are running slowly. Root cause is unknown. Investigation needed to identify
-  bottlenecks and recommend improvements.
-
-  ## Questions to Answer
-  - What are the slowest steps in the build pipeline?
-  - Are there caching opportunities not currently utilized?
-  - Is the slowness consistent or intermittent?
-
-  ## Deliverable
-  A written recommendation with specific changes to reduce build time.
-
-  ## Notes
-  No baseline timing data provided. Start by capturing current step-by-step timing.
-
-Create it?
-```
-
-**User**: "Looks good, create it."
-
-**Agent creates and reports**: "Created KAN-50."
-
----
-
-## Integration — `kanon_create_issue` Reference
-
-```
-kanon_create_issue(
-  projectKey: "{projectKey}",     // required — get from project context
-  title: "{title}",               // required — [Area] Imperative description
-  type: "feature|bug|task|spike", // optional — inferred from NL
-  priority: "critical|high|medium|low",  // optional — inferred from NL
-  description: "{markdown}",      // optional — structured markdown
-  labels: ["{label1}", ...],      // optional — inferred from domain/tech
-  // Other optional fields when context provides them:
-  groupKey: "{groupKey}",         // from kanon_list_groups — match area/domain to group
-  assigneeId: "{userId}",         // if user specifies "assign to X"
-  dueDate: "{ISO-date}"           // if deadline is mentioned
-)
-```
-
-The tool returns the created issue object including its `issueKey` (e.g., `KAN-42`). Always report this key to the user after creation.
-
-**Before creating**, call `kanon_list_issues(projectKey, ...)` with relevant filters (type, label) to check for duplicates. If a similar issue exists, surface it to the user: "There is already an open issue that looks related: KAN-35 '[Auth] OAuth callback configuration'. Is this the same thing, or a separate issue?"
-
----
-
-## Edge Cases and Clarifications
-
-**When the project key is unknown**: Ask the user or call `kanon_list_projects` to find it. Do not guess.
-
-**When the description is very short**: Generate a minimal but valid description. It is better to create a sparse issue than to block on asking for details. The user can enrich it later.
-
-**When the user provides conflicting signals** (e.g., "not urgent but this is critical"): Favor the strongest concrete signal. If truly ambiguous, ask: "Should I mark this high or medium priority?"
-
-**When the issue is actually a roadmap item**: If the user uses language like "someday", "eventually", "down the road", or "it would be nice if", consider whether this belongs on the roadmap instead of the backlog. Reference the `kanon-roadmap` skill and suggest: "This sounds more like a roadmap item than an actionable issue — want me to add it to the roadmap instead?"
+## Duplicate Check
 
-**When multiple issues are implied**: If the user describes multiple distinct problems or features in one message, identify each one and offer to create separate issues: "I see two things here. Want me to create separate issues for both?"
+Before creating, call `kanon_list_issues(projectKey, ...)` with relevant filters. If a similar issue exists, surface it: "There is already KAN-35 '[Auth] OAuth callback configuration'. Same thing, or separate?"
 
 ---
 
 ## Best Practices
 
-1. **Always preview first** — Never create an issue without showing the structured card and getting confirmation.
-2. **Titles are for humans** — Every title should be scannable on a board by someone who was not in this conversation.
-3. **Infer boldly, adjust gracefully** — Make confident inferences from the NL input. If the user corrects you, update immediately without argument.
-4. **Check for duplicates** — A quick `kanon_list_issues` with a label or type filter before creation prevents board clutter.
-5. **Report the issue key** — Always echo the created issue key (e.g., "Created KAN-42") so the user has a reference.
-6. **Default to backlog** — Issues created here are not yet in progress. Let the user or workflow move them forward.
-7. **Structured descriptions matter** — A person opening the card later should understand what to do without needing this conversation.
-8. **Roadmap vs issue** — If the request is exploratory or clearly deferred, suggest the roadmap. Do not cram everything into the backlog.
-9. **Check groups before creating** — Always call `kanon_list_groups(projectKey)` and assign `groupKey` when a match exists. Ungrouped issues are harder to find on the board.
+1. **Always preview first** — Never create without showing the structured card and getting confirmation.
+2. **Titles are for humans** — Every title should be scannable on a board.
+3. **Infer boldly, adjust gracefully** — Make confident inferences. Update immediately if corrected.
+4. **Check for duplicates** — A quick filter before creation prevents board clutter.
+5. **Report the issue key** — Always echo the created key (e.g., "Created KAN-42").
+6. **Default to backlog** — Let the user or workflow move issues forward.
+7. **Structured descriptions matter** — A person opening the card later should understand what to do.
+8. **Roadmap vs issue** — If deferred, suggest the roadmap. Do not cram everything into the backlog.
+9. **Check groups before creating** — Always call `kanon_list_groups(projectKey)` and assign `groupKey` when a match exists.