@tcanaud/product-manager 1.0.0

package/templates/commands/product.dashboard.md

@@ -0,0 +1,188 @@
+---
+description: View product health dashboard — status counts, category distribution, conversion metrics, and warnings.
+handoffs:
+  - label: Triage feedbacks
+    agent: product.triage
+    prompt: Triage new feedbacks into backlogs
+    send: true
+  - label: Check health
+    agent: product.check
+    prompt: Run product health check
+    send: true
+  - label: Browse backlogs
+    agent: product.backlog
+    prompt: List all backlogs
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+- If `$ARGUMENTS` contains `--json`: output structured JSON instead of Markdown
+- Otherwise: output Markdown dashboard
+
+## Purpose
+
+Read-only command that displays a complete product health overview: feedback counts by status, backlog counts by status, category distribution, conversion metrics (feedback-to-backlog rate, backlog-to-feature rate, resolution rate), and warnings for stale feedbacks or critical bugs.
+
+## Execution Flow
+
+### 1. Validate environment
+
+- Check that `.product/` directory exists. If not → **ERROR**: "Product directory not initialized."
+
+### 2. Gather data
+
+Scan the filesystem directly for accurate counts:
+
+**Feedbacks:**
+- Count files in `.product/feedbacks/new/`
+- Count files in `.product/feedbacks/triaged/`
+- Count files in `.product/feedbacks/excluded/`
+- Count files in `.product/feedbacks/resolved/`
+
+**Backlogs:**
+- Count files in `.product/backlogs/open/`
+- Count files in `.product/backlogs/in-progress/`
+- Count files in `.product/backlogs/done/`
+- Count files in `.product/backlogs/promoted/`
+- Count files in `.product/backlogs/cancelled/`
+
+**Categories:**
+- For each feedback file across all status directories, read the `category` field from frontmatter
+- Count occurrences of each category: `critical-bug`, `bug`, `optimization`, `evolution`, `new-feature`
+
+**Backlog priorities:**
+- For each backlog file across all status directories, read the `priority` field
+
+### 3. Compute metrics
+
+- **Feedback-to-backlog rate**: count of feedbacks with non-empty `linked_to.backlog[]` / total non-excluded feedbacks. If total non-excluded is 0, rate = 0.
+- **Backlog-to-feature rate**: count of promoted backlogs / total backlogs. If total backlogs is 0, rate = 0.
+- **Resolution rate**: count of resolved feedbacks / total feedbacks. If total feedbacks is 0, rate = 0.
+
+### 4. Identify warnings
+
+- **Stale feedbacks**: For each feedback in `feedbacks/new/`, read the `created` date. If today minus created > 14 days → add stale warning with count and oldest age.
+- **Critical bugs**: For each backlog with `priority: critical` → add critical bug alert with ID and title.
+
+### 5. Output — Markdown (default)
+
+```markdown
+## Product Dashboard
+
+**Last updated**: {today's date}
+
+### Feedbacks
+
+| Status | Count |
+|--------|-------|
+| New | {count} |
+| Triaged | {count} |
+| Excluded | {count} |
+| Resolved | {count} |
+| **Total** | **{total}** |
+
+### Backlogs
+
+| Status | Count |
+|--------|-------|
+| Open | {count} |
+| In Progress | {count} |
+| Done | {count} |
+| Promoted | {count} |
+| Cancelled | {count} |
+| **Total** | **{total}** |
+
+### Categories
+
+| Category | Count | % |
+|----------|-------|---|
+| critical-bug | {count} | {pct}% |
+| bug | {count} | {pct}% |
+| optimization | {count} | {pct}% |
+| evolution | {count} | {pct}% |
+| new-feature | {count} | {pct}% |
+
+### Conversion Metrics
+
+| Metric | Value |
+|--------|-------|
+| Feedback → Backlog | {rate}% |
+| Backlog → Feature | {rate}% |
+| Resolution rate | {rate}% |
+
+### Warnings
+
+{If stale feedbacks:}
+- **{count} stale feedback(s)** in `new/` (oldest: {days} days) — run `/product.triage`
+
+{If critical bugs:}
+- **{count} critical bug(s)** in backlogs — {id} "{title}"
+
+{If no warnings:}
+No warnings.
+```
+
+If the product directory is empty (no feedbacks, no backlogs), display the dashboard with all zeros and add:
+> No feedbacks or backlogs yet. Start with `/product.intake`.
+
+### 6. Output — JSON (`--json` flag)
+
+Output a structured JSON object:
+
+```json
+{
+  "updated": "{ISO timestamp}",
+  "feedbacks": {
+    "total": {n},
+    "new": {n},
+    "triaged": {n},
+    "excluded": {n},
+    "resolved": {n}
+  },
+  "backlogs": {
+    "total": {n},
+    "open": {n},
+    "in_progress": {n},
+    "done": {n},
+    "promoted": {n},
+    "cancelled": {n}
+  },
+  "categories": {
+    "critical-bug": {n},
+    "bug": {n},
+    "optimization": {n},
+    "evolution": {n},
+    "new-feature": {n}
+  },
+  "metrics": {
+    "feedback_to_backlog_rate": {float},
+    "backlog_to_feature_rate": {float},
+    "resolution_rate": {float}
+  },
+  "warnings": [
+    { "type": "stale_feedbacks", "count": {n}, "oldest_days": {n} },
+    { "type": "critical_bug", "id": "{BL-xxx}", "title": "{title}" }
+  ]
+}
+```
+
+## Error Handling
+
+- `.product/` missing → ERROR with init instructions
+- Empty `.product/` → display dashboard with all zeros and a note
+
+## Rules
+
+- This command is **READ-ONLY** — no files are modified
+- ALWAYS scan the filesystem directly for accurate counts — do not rely solely on index.yaml
+- ALWAYS compute percentages as integers (rounded)
+- ALWAYS show all categories even if count is 0
+- ALWAYS show all status groups even if count is 0
+- NEVER modify any files

package/templates/commands/product.intake.md

@@ -0,0 +1,125 @@
+---
+description: Capture feedback from free text or inbox files into structured .product/feedbacks/new/ entries.
+handoffs:
+  - label: Triage feedbacks
+    agent: product.triage
+    prompt: Triage new feedbacks into backlogs
+    send: true
+  - label: View dashboard
+    agent: product.dashboard
+    prompt: View product health dashboard
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Purpose
+
+Capture user feedback — either from free-text arguments or from files dropped in `.product/inbox/` — and create structured feedback entries in `.product/feedbacks/new/` with proper YAML frontmatter. This is the entry point for all product feedback.
+
+## Execution Flow
+
+### 1. Validate environment
+
+- Check that `.product/` directory exists. If not → **ERROR**: "Product directory not initialized. Run `npx @tcanaud/product-manager init` first."
+- Check that `.product/_templates/feedback.tpl.md` exists. If not → **ERROR**: "Feedback template missing. Run `npx @tcanaud/product-manager update` to restore templates."
+
+### 2. Determine intake mode
+
+- **If `$ARGUMENTS` is non-empty**: Free-text mode (Mode 1) is active
+- **Check `.product/inbox/`**: If inbox has files, inbox mode (Mode 2) is active
+- **If both**: Combined mode — process both
+- **If neither**: **INFO**: "No feedback to process. Provide a description or drop files in `.product/inbox/`." → STOP
+
+### 3. Assign next ID
+
+Scan ALL `.product/feedbacks/` subdirectories (`new/`, `triaged/`, `excluded/`, `resolved/`) for existing feedback files. Extract the numeric portion from filenames matching `FB-xxx.md`. Find the highest number and increment by 1. Zero-pad to 3 digits.
+
+Example: If highest existing is `FB-012.md` → next ID is `FB-013`.
+If no feedbacks exist → start at `FB-001`.
+
+### 4. Mode 1 — Free-text intake (if `$ARGUMENTS` provided)
+
+1. Read `.product/_templates/feedback.tpl.md` for the schema
+2. Analyze the free-text content to:
+   - Extract a concise **title** (max 80 chars) summarizing the feedback
+   - Propose a **category** from: `critical-bug`, `bug`, `optimization`, `evolution`, `new-feature`
+   - Determine **source**: default to `user`
+3. Create the feedback file at `.product/feedbacks/new/FB-{NNN}.md`:
+   - Replace `{{id}}` with `FB-{NNN}`
+   - Replace `{{title}}` with the extracted title
+   - Replace `{{category}}` with the proposed category
+   - Replace `{{source}}` with `user`
+   - Replace `{{reporter}}` with the git user name (from `git config user.name`) or `unknown`
+   - Replace `{{created}}` and `{{updated}}` with today's date (YYYY-MM-DD)
+   - Replace `{{body}}` with the full free-text description
+4. Record this feedback for the summary report
+
+### 5. Mode 2 — Inbox processing (if `.product/inbox/` has files)
+
+1. List all files in `.product/inbox/`
+2. For each file:
+   a. Read the file content
+   b. If the file appears to be binary or empty → **WARN**: "Skipped {filename}: unrecognizable content. Left in inbox for manual review." → skip
+   c. Check for YAML frontmatter (between `---` markers):
+      - If present: extract `source`, `reporter`, `timestamp` fields
+      - If absent: infer metadata from content
+   d. Assign next sequential ID (continuing from Mode 1 if both modes active)
+   e. Analyze content to propose category and extract title
+   f. Create structured feedback in `.product/feedbacks/new/FB-{NNN}.md`:
+      - Use extracted/inferred metadata for frontmatter fields
+      - Use the file content (minus frontmatter) as the body
+   g. Delete the processed inbox file
+3. Record each created feedback for the summary report
+
+### 6. Update index
+
+Read `.product/index.yaml`. For each new feedback created:
+- Increment `feedbacks.total` by 1
+- Increment `feedbacks.by_status.new` by 1
+- Increment the appropriate `feedbacks.by_category.{category}` by 1
+- Add an entry to `feedbacks.items[]` with: id, title, status, category, priority, created
+- Update the `updated` timestamp
+
+Write the updated index back to `.product/index.yaml`.
+
+### 7. Output report
+
+Display a Markdown summary:
+
+```markdown
+## Intake Complete
+
+**Created**: {count} new feedback(s)
+
+| ID | Title | Category | Source |
+|----|-------|----------|--------|
+| FB-{NNN} | {title} | {category} | {source} |
+| ... | ... | ... | ... |
+
+**Next**: Run `/product.triage` when ready to process new feedbacks.
+```
+
+## Error Handling
+
+- `.product/` does not exist → ERROR with initialization instructions
+- No arguments AND empty inbox → INFO message, no action taken
+- Inbox file is empty or binary → WARN, skip that file, continue with others
+- Unreadable inbox file → WARN, leave file in inbox for manual review
+
+## Rules
+
+- ALWAYS assign IDs by scanning ALL feedbacks/ subdirectories — never reuse IDs
+- ALWAYS use today's date for `created` and `updated`
+- ALWAYS set `status: "new"` for newly created feedbacks
+- ALWAYS update `index.yaml` after creating feedbacks
+- ALWAYS delete successfully processed inbox files
+- NEVER modify existing feedback files
+- NEVER modify backlog files
+- Category MUST be one of: `critical-bug`, `bug`, `optimization`, `evolution`, `new-feature`

package/templates/commands/product.promote.md

@@ -0,0 +1,159 @@
+---
+description: Promote a backlog item to a full kai feature with traceability links.
+handoffs:
+  - label: Start feature workflow
+    agent: feature.workflow
+    prompt: Start the feature workflow for the newly created feature
+    send: true
+  - label: Browse backlogs
+    agent: product.backlog
+    prompt: List all backlogs
+    send: true
+  - label: View dashboard
+    agent: product.dashboard
+    prompt: View product health dashboard
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+`$ARGUMENTS` must contain a backlog ID (e.g., `BL-001`).
+
+## Purpose
+
+Convert a backlog item into a kai feature — creating the `.features/{NNN}-{name}.yaml` file, updating `.features/index.yaml`, moving the backlog to `promoted/`, and updating all traceability links through the feedback → backlog → feature chain.
+
+## Execution Flow
+
+### 1. Validate arguments
+
+- If `$ARGUMENTS` is empty → **ERROR**: "Backlog ID required. Usage: `/product.promote BL-xxx`"
+- Extract the backlog ID from arguments (should match pattern `BL-\d{3}`)
+- If invalid format → **ERROR**: "Invalid backlog ID format. Expected BL-xxx (e.g., BL-001)."
+
+### 2. Find the backlog
+
+Search for the backlog file across these directories (in order):
+1. `.product/backlogs/open/`
+2. `.product/backlogs/in-progress/`
+
+If found in `promoted/` → **ERROR**: "Backlog {id} is already promoted (feature: {feature_id})."
+If found in `done/` or `cancelled/` → **ERROR**: "Cannot promote a {status} backlog. Only open or in-progress backlogs can be promoted."
+If not found anywhere → **ERROR**: "Backlog {id} not found."
+
+Read the backlog file: parse YAML frontmatter and body content.
+
+### 3. Determine feature identity
+
+1. Read `.features/index.yaml` to list all existing features
+2. Scan `.features/` for all `{NNN}-*.yaml` files
+3. Find the highest feature number (NNN)
+4. Next feature number = highest + 1, zero-padded to 3 digits
+5. Derive the feature name from the backlog title:
+   - Convert to lowercase
+   - Replace spaces and special characters with hyphens
+   - Remove consecutive hyphens
+   - Trim hyphens from start/end
+   - Example: "Search Performance on Large Repos" → `search-performance-on-large-repos`
+6. Feature ID = `{NNN}-{name}` (e.g., `009-search-performance-on-large-repos`)
+
+### 4. Create feature YAML
+
+1. Read `.features/_templates/feature.tpl.yaml`
+2. Copy to `.features/{feature_id}.yaml`
+3. Replace template placeholders:
+   - `{{feature_id}}` → the feature ID
+   - `{{title}}` → the backlog title (title case)
+   - `{{owner}}` → the backlog `owner` field, or `default_owner` from `.features/config.yaml`
+   - `{{date}}` → today's date (YYYY-MM-DD)
+   - `{{timestamp}}` → current ISO timestamp
+4. Set `workflow_path: "full"` (promoted features use the full method)
+
+### 5. Update feature index
+
+Read `.features/index.yaml` and add the new feature entry:
+- `id`: the feature ID
+- `title`: the backlog title
+- `status`: `active`
+- `stage`: `ideation`
+- `progress`: `0.0`
+- `health`: `HEALTHY`
+
+Write the updated index back.
+
+### 6. Update backlog
+
+1. Move the backlog file from its current directory to `.product/backlogs/promoted/`
+2. Update the backlog frontmatter:
+   - `status: "promoted"`
+   - `updated: today's date`
+   - `promotion.promoted_date: today's date`
+   - `promotion.feature_id: "{feature_id}"`
+   - Add the feature ID to `features[]` array
+3. Write the updated file
+
+### 7. Update linked feedbacks
+
+For each feedback ID in the backlog's `feedbacks[]` array:
+1. Find the feedback file across all `feedbacks/` subdirectories
+2. Read its frontmatter
+3. Add the feature ID to `linked_to.features[]`
+4. Update `updated` to today's date
+5. Write the updated file
+
+### 8. Update product index
+
+Read `.product/index.yaml` and update:
+- Decrement the appropriate `backlogs.by_status.{old_status}` count
+- Increment `backlogs.by_status.promoted`
+- Update the backlog entry in `backlogs.items[]`
+- Recalculate `metrics.backlog_to_feature_rate`
+- Update `updated` timestamp
+
+Write the updated index back.
+
+### 9. Output report
+
+```markdown
+## Promotion Complete
+
+**Backlog**: {backlog_id} → promoted
+**Feature**: {feature_id} created
+
+### Traceability Chain
+
+{For each linked feedback:}
+FB-xxx ──→ {backlog_id} ──→ {feature_id}
+
+### Next Steps
+
+1. Run `/feature.workflow {feature_id}` to start the feature pipeline
+2. The feature begins at **ideation** stage — proceed through Brief → PRD → Spec → Tasks → Code
+```
+
+## Error Handling
+
+- `$ARGUMENTS` is empty → ERROR with usage instructions
+- Backlog not found → ERROR with ID
+- Backlog already promoted → ERROR with existing feature ID
+- Backlog in wrong status (done/cancelled) → ERROR with explanation
+- `.features/` missing → ERROR: "Feature lifecycle system not initialized. Run `npx feature-lifecycle init` first."
+- `.features/_templates/feature.tpl.yaml` missing → ERROR: "Feature template missing."
+- Feature index update fails → ERROR but backlog move is already done — instruct to run `/product.check`
+
+## Rules
+
+- ALWAYS validate the backlog exists and is in a promotable status before any mutations
+- ALWAYS create the feature YAML before moving the backlog (fail-safe ordering)
+- ALWAYS update bidirectional links: backlog → feature AND feedback → feature
+- ALWAYS use the next sequential feature number from `.features/`
+- NEVER modify feedbacks beyond adding to `linked_to.features[]` and updating `updated`
+- NEVER promote backlogs in `done/` or `cancelled/` status
+- NEVER overwrite an existing feature YAML
+- Feature name derivation MUST produce valid kebab-case (lowercase, hyphens only)

package/templates/commands/product.triage.md

@@ -0,0 +1,205 @@
+---
+description: Triage new feedbacks — semantic clustering, duplicate/regression detection, backlog creation.
+handoffs:
+  - label: Browse backlogs
+    agent: product.backlog
+    prompt: List all backlogs
+    send: true
+  - label: Promote backlog
+    agent: product.promote
+    prompt: Promote a backlog to feature
+    send: true
+  - label: View dashboard
+    agent: product.dashboard
+    prompt: View product health dashboard
+    send: true
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+- If `$ARGUMENTS` contains `--supervised`: use supervised mode (confirm each action)
+- Otherwise: use autonomous mode (execute all actions immediately)
+
+## Purpose
+
+Read all new feedbacks, perform AI semantic clustering, detect duplicates and regressions against resolved feedbacks, propose backlog items, and execute triage actions — moving feedbacks to `triaged/` or `excluded/` and creating backlog items in `backlogs/open/`.
+
+## Execution Flow
+
+### 1. Validate environment
+
+- Check that `.product/` directory exists. If not → **ERROR**: "Product directory not initialized."
+- List files in `.product/feedbacks/new/`. If empty → **INFO**: "No new feedbacks to triage." → STOP
+- If more than 30 feedbacks in `new/` → **WARN**: "Large batch ({count} feedbacks). Processing first 30; re-run for remainder." Process only the first 30 (sorted by filename).
+
+### 2. Read all feedbacks for context
+
+Read **all** feedback files from:
+- `.product/feedbacks/new/` — the feedbacks to triage (primary input)
+- `.product/feedbacks/resolved/` — for regression/duplicate detection
+- `.product/feedbacks/triaged/` — for existing context and deduplication
+
+For each file, parse the YAML frontmatter and body content.
+
+### 3. Read existing backlogs for context
+
+Read all backlog files from all `.product/backlogs/` subdirectories to understand what already exists and avoid creating duplicate backlogs.
+
+### 4. Semantic analysis
+
+For each new feedback, perform the following analysis:
+
+#### 4a. Clustering
+
+Group new feedbacks that describe the **same problem or request**, even with different phrasings. Use semantic understanding — NOT keyword matching.
+
+Example: "Search takes 40 seconds" and "Search is unusable with 10k files" → same cluster (search performance).
+
+#### 4b. Regression / duplicate detection
+
+Compare each new feedback against **resolved** feedbacks:
+
+1. If semantically similar to a resolved feedback:
+   - Find the resolution chain: read the resolved feedback's `linked_to.backlog[]` → read that backlog's `features[]` → find the feature
+   - Read the feature's `.features/{feature_id}.yaml` to get `lifecycle.stage` and `lifecycle.stage_since`
+   - **If** feedback `created` date > feature `stage_since` date (feature was released BEFORE the new feedback was created) → classify as **REGRESSION**
+   - **If** feedback `created` date <= feature `stage_since` date → classify as **DUPLICATE-RESOLVED**
+2. If no resolution chain can be traced, treat as a new standalone feedback
+
+#### 4c. Category assignment
+
+For each feedback, verify or reassign its category from the predefined set: `critical-bug`, `bug`, `optimization`, `evolution`, `new-feature`.
+
+#### 4d. Priority proposal
+
+For each cluster/standalone feedback, propose a priority: `low`, `medium`, `high`, `critical`.
+Consider: user impact, frequency of reports, severity of the issue.
+
+### 5. Present triage proposal
+
+Build a structured proposal showing all planned actions:
+
+```markdown
+## Triage Proposal
+
+### Group 1: {cluster title} ({count} feedbacks)
+- FB-xxx: "{title}"
+- FB-yyy: "{title}"
+**Action**: Create backlog BL-{NNN} "{proposed title}" ({category}, {priority})
+
+### Group 2: Standalone
+- FB-zzz: "{title}"
+**Action**: Create backlog BL-{NNN} "{proposed title}" ({category}, {priority})
+
+### Excluded
+- FB-aaa: "{title}"
+**Action**: Move to excluded/ (reason: {noise | out-of-scope | duplicate-resolved | ...})
+
+### Regression Detected
+- FB-bbb: Similar to resolved FB-ccc (resolved by feature {feature_id}, released {date})
+  FB-bbb created: {date} — AFTER release
+**Action**: Create backlog BL-{NNN} "{title}" (critical-bug, critical, tag: regression)
+```
+
+### 6. Execute actions
+
+#### Autonomous mode (default)
+
+Execute all proposed actions immediately:
+
+#### Supervised mode (`--supervised`)
+
+Present each action individually and wait for user confirmation:
+- **Accept**: execute the action
+- **Reject**: skip the action, leave the feedback in `new/`
+- **Modify**: let the user change the proposed action before executing
+
+#### For each triage action:
+
+**Creating a backlog item:**
+1. Scan ALL `.product/backlogs/` subdirectories for highest existing BL-xxx number
+2. Assign next sequential ID (zero-padded to 3 digits)
+3. Read `.product/_templates/backlog.tpl.md` for the schema
+4. Create backlog file at `.product/backlogs/open/BL-{NNN}.md`:
+   - Replace `{{id}}` with `BL-{NNN}`
+   - Replace `{{title}}` with the synthesized title from the cluster
+   - Replace `{{category}}` with the determined category
+   - Replace `{{priority}}` with the proposed priority
+   - Replace `{{created}}` and `{{updated}}` with today's date
+   - Replace `{{owner}}` with git user name or `unknown`
+   - Set `feedbacks:` array with all feedback IDs in the cluster
+   - Replace `{{body}}` with a synthesized description of the problem from the cluster
+5. For each feedback in the cluster:
+   - Move file from `feedbacks/new/` to `feedbacks/triaged/`
+   - Update frontmatter: `status: "triaged"`, `updated: today`
+   - Add the backlog ID to `linked_to.backlog[]`
+
+**Excluding a feedback:**
+1. Move file from `feedbacks/new/` to `feedbacks/excluded/`
+2. Update frontmatter: `status: "excluded"`, `updated: today`
+3. Set `exclusion_reason` to the specific reason (e.g., "duplicate-resolved", "noise", "out-of-scope")
+
+**Handling a regression:**
+1. Create a backlog item (same as above) with:
+   - `category: "critical-bug"`
+   - `priority: "critical"`
+   - `tags: ["regression"]`
+2. Move the feedback to `triaged/` with the backlog link
+
+### 7. Update index
+
+Read `.product/index.yaml` and update:
+- Feedback counts by status (decrement `new`, increment `triaged`/`excluded` as appropriate)
+- Backlog counts (increment `open` for each new backlog)
+- Category distributions
+- Recalculate `metrics.feedback_to_backlog_rate`
+- Update `updated` timestamp
+
+Write the updated index back.
+
+### 8. Output report
+
+```markdown
+## Triage Complete
+
+**Processed**: {count} feedbacks
+**Created**: {count} backlog item(s)
+**Excluded**: {count} feedback(s)
+**Regressions**: {count} detected
+
+| Feedback | Action | Result |
+|----------|--------|--------|
+| FB-xxx | Grouped → BL-{NNN} | triaged/ |
+| FB-yyy | Grouped → BL-{NNN} | triaged/ |
+| FB-zzz | Standalone → BL-{NNN} | triaged/ |
+| FB-aaa | Excluded ({reason}) | excluded/ |
+
+**Next**: Review backlogs with `/product.backlog` or promote with `/product.promote BL-xxx`.
+```
+
+## Error Handling
+
+- No feedbacks in `new/` → INFO, stop gracefully
+- `.product/` missing → ERROR with init instructions
+- Batch > 30 items → WARN, process first 30, instruct to re-run
+- Feature file not found during regression check → skip regression detection for that feedback, note in report
+- Feedback file cannot be parsed → WARN, skip, leave in `new/`
+
+## Rules
+
+- ALWAYS use semantic similarity for clustering — NEVER keyword matching
+- ALWAYS scan ALL backlogs/ and feedbacks/ subdirs for ID assignment — NEVER reuse IDs
+- ALWAYS update bidirectional links (feedback → backlog AND backlog → feedbacks)
+- ALWAYS move files to new directories as state transitions — NEVER just update frontmatter status without moving
+- ALWAYS update `index.yaml` after all actions
+- NEVER modify resolved feedbacks (read-only context)
+- NEVER modify existing backlog items (read-only context)
+- Category MUST be one of: `critical-bug`, `bug`, `optimization`, `evolution`, `new-feature`
+- Priority MUST be one of: `low`, `medium`, `high`, `critical`
+- In supervised mode, respect user decisions without argument

package/templates/core/backlog.tpl.md

@@ -0,0 +1,21 @@
+---
+id: "{{id}}"
+title: "{{title}}"
+status: "open"
+category: "{{category}}"
+priority: "{{priority}}"
+created: "{{created}}"
+updated: "{{updated}}"
+owner: "{{owner}}"
+feedbacks: []
+features: []
+tags: []
+promotion:
+  promoted_date: ""
+  feature_id: ""
+cancellation:
+  cancelled_date: ""
+  reason: ""
+---
+
+{{body}}