@tcanaud/product-manager 1.0.0

package/bin/cli.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+
+import { argv, exit } from "node:process";
+
+const command = argv[2];
+const flags = argv.slice(3);
+
+const HELP = `
+product-manager — File-based product feedback & backlog system for the kai governance stack.
+
+Usage:
+  npx @tcanaud/product-manager init      Scaffold .product/ directory and install slash commands
+  npx @tcanaud/product-manager update    Update commands and templates without touching user data
+  npx @tcanaud/product-manager help      Show this help message
+
+Options (init):
+  --yes             Skip confirmation prompts
+
+Claude Code commands (after init):
+  /product.intake [text]        Capture feedback from text or inbox files
+  /product.triage [--supervised] Triage new feedbacks into backlogs
+  /product.backlog [BL-xxx]     List or inspect backlog items
+  /product.promote BL-xxx       Promote backlog to a kai feature
+  /product.check                Detect drift and integrity issues
+  /product.dashboard [--json]   View product health dashboard
+`;
+
+switch (command) {
+  case "init": {
+    const { install } = await import("../src/installer.js");
+    install(flags);
+    break;
+  }
+  case "update": {
+    const { update } = await import("../src/updater.js");
+    update(flags);
+    break;
+  }
+  case "help":
+  case "--help":
+  case "-h":
+  case undefined:
+    console.log(HELP);
+    break;
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.log(HELP);
+    exit(1);
+}

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@tcanaud/product-manager",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "File-based product feedback intake, AI semantic triage, backlog management, and feature promotion pipeline for the kai governance stack.",
+  "bin": {
+    "product-manager": "./bin/cli.js"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "templates/"
+  ],
+  "keywords": [
+    "kai",
+    "product-management",
+    "feedback",
+    "triage",
+    "backlog",
+    "claude-code"
+  ],
+  "author": "Thibaud Canaud",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tcanaud/product-manager.git"
+  }
+}

package/src/detect.js

@@ -0,0 +1,16 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+
+export function detect(projectRoot) {
+  const productDir = join(projectRoot, ".product");
+  const hasProduct = existsSync(productDir);
+  const hasClaudeCommands = existsSync(join(projectRoot, ".claude", "commands"));
+  const hasFeatures = existsSync(join(projectRoot, ".features"));
+
+  return {
+    hasProduct,
+    productDir,
+    hasClaudeCommands,
+    hasFeatures,
+  };
+}

package/src/installer.js

@@ -0,0 +1,143 @@
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createInterface } from "node:readline";
+import { detect } from "./detect.js";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(__dirname, "..", "templates");
+
+function copyTemplate(src, dest) {
+  const destDir = dirname(dest);
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+  copyFileSync(src, dest);
+}
+
+function ask(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+export async function install(flags = []) {
+  const projectRoot = process.cwd();
+  const autoYes = flags.includes("--yes");
+
+  console.log("\n  @tcanaud/product-manager v1.0.0\n");
+
+  // ── Detect environment ──────────────────────────────
+  const env = detect(projectRoot);
+
+  console.log("  Environment detected:");
+  console.log(`    .product/:        ${env.hasProduct ? "yes" : "no"}`);
+  console.log(`    .features/:       ${env.hasFeatures ? "yes" : "no"}`);
+  console.log(`    Claude commands:   ${env.hasClaudeCommands ? "yes" : "no"}`);
+  console.log();
+
+  const productDir = join(projectRoot, ".product");
+
+  if (existsSync(productDir) && !autoYes) {
+    const answer = await ask("  .product/ already exists. Overwrite templates? (y/N) ");
+    if (answer !== "y" && answer !== "yes") {
+      console.log("  Skipping. Use '@tcanaud/product-manager update' to update commands only.\n");
+      return;
+    }
+  }
+
+  // ── Phase 1/3: Create .product/ directory structure ─
+  console.log("  [1/3] Creating .product/ directory structure...");
+
+  const dirs = [
+    ".product/inbox",
+    ".product/feedbacks/new",
+    ".product/feedbacks/triaged",
+    ".product/feedbacks/excluded",
+    ".product/feedbacks/resolved",
+    ".product/backlogs/open",
+    ".product/backlogs/in-progress",
+    ".product/backlogs/done",
+    ".product/backlogs/promoted",
+    ".product/backlogs/cancelled",
+    ".product/_templates",
+  ];
+
+  for (const dir of dirs) {
+    const fullPath = join(projectRoot, dir);
+    if (!existsSync(fullPath)) {
+      mkdirSync(fullPath, { recursive: true });
+      console.log(`    create ${dir}/`);
+    }
+  }
+
+  // Copy artifact templates
+  copyTemplate(
+    join(TEMPLATES, "core", "feedback.tpl.md"),
+    join(productDir, "_templates", "feedback.tpl.md")
+  );
+  console.log("    write .product/_templates/feedback.tpl.md");
+
+  copyTemplate(
+    join(TEMPLATES, "core", "backlog.tpl.md"),
+    join(productDir, "_templates", "backlog.tpl.md")
+  );
+  console.log("    write .product/_templates/backlog.tpl.md");
+
+  // Index
+  const indexPath = join(productDir, "index.yaml");
+  if (existsSync(indexPath)) {
+    console.log("    skip .product/index.yaml (already exists)");
+  } else {
+    const template = readFileSync(join(TEMPLATES, "core", "index.yaml"), "utf-8");
+    const content = template.replace("{{generated}}", new Date().toISOString());
+    writeFileSync(indexPath, content);
+    console.log("    write .product/index.yaml");
+  }
+
+  // ── Phase 2/3: Install Claude Code commands ─────────
+  console.log("  [2/3] Installing Claude Code commands...");
+
+  if (!env.hasClaudeCommands) {
+    mkdirSync(join(projectRoot, ".claude", "commands"), { recursive: true });
+    console.log("    create .claude/commands/");
+  }
+
+  const commandMappings = [
+    ["commands/product.intake.md", ".claude/commands/product.intake.md"],
+    ["commands/product.triage.md", ".claude/commands/product.triage.md"],
+    ["commands/product.backlog.md", ".claude/commands/product.backlog.md"],
+    ["commands/product.promote.md", ".claude/commands/product.promote.md"],
+    ["commands/product.check.md", ".claude/commands/product.check.md"],
+    ["commands/product.dashboard.md", ".claude/commands/product.dashboard.md"],
+  ];
+
+  for (const [src, dest] of commandMappings) {
+    const srcPath = join(TEMPLATES, src);
+    if (existsSync(srcPath)) {
+      copyTemplate(srcPath, join(projectRoot, dest));
+      console.log(`    write ${dest}`);
+    }
+  }
+
+  // ── Phase 3/3: Summary ─────────────────────────────
+  console.log("  [3/3] Verifying installation...");
+
+  if (!env.hasFeatures) {
+    console.log("    note: .features/ not found — /product.promote requires the feature lifecycle system");
+  }
+
+  // ── Done ────────────────────────────────────────────
+  console.log();
+  console.log("  Done! Product Manager installed.");
+  console.log();
+  console.log("  Next steps:");
+  console.log("    1. Run /product.intake \"your feedback text\" to capture feedback");
+  console.log("    2. Run /product.triage to process new feedbacks into backlogs");
+  console.log("    3. Run /product.dashboard for a health overview");
+  console.log();
+}

package/src/updater.js

@@ -0,0 +1,63 @@
+import { existsSync, copyFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const TEMPLATES = join(__dirname, "..", "templates");
+
+function copyTemplate(src, dest) {
+  const destDir = dirname(dest);
+  if (!existsSync(destDir)) {
+    mkdirSync(destDir, { recursive: true });
+  }
+  copyFileSync(src, dest);
+}
+
+export function update(flags = []) {
+  const projectRoot = process.cwd();
+
+  console.log("\n  product-manager update\n");
+
+  if (!existsSync(join(projectRoot, ".product"))) {
+    console.error("  Error: .product/ not found. Run 'product-manager init' first.");
+    process.exit(1);
+  }
+
+  // Update artifact templates
+  console.log("  Updating templates...");
+  copyTemplate(
+    join(TEMPLATES, "core", "feedback.tpl.md"),
+    join(projectRoot, ".product", "_templates", "feedback.tpl.md")
+  );
+  console.log("    update .product/_templates/feedback.tpl.md");
+
+  copyTemplate(
+    join(TEMPLATES, "core", "backlog.tpl.md"),
+    join(projectRoot, ".product", "_templates", "backlog.tpl.md")
+  );
+  console.log("    update .product/_templates/backlog.tpl.md");
+
+  // Update Claude Code commands
+  console.log("  Updating Claude Code commands...");
+
+  const commandMappings = [
+    ["commands/product.intake.md", ".claude/commands/product.intake.md"],
+    ["commands/product.triage.md", ".claude/commands/product.triage.md"],
+    ["commands/product.backlog.md", ".claude/commands/product.backlog.md"],
+    ["commands/product.promote.md", ".claude/commands/product.promote.md"],
+    ["commands/product.check.md", ".claude/commands/product.check.md"],
+    ["commands/product.dashboard.md", ".claude/commands/product.dashboard.md"],
+  ];
+
+  for (const [src, dest] of commandMappings) {
+    const srcPath = join(TEMPLATES, src);
+    if (existsSync(srcPath)) {
+      copyTemplate(srcPath, join(projectRoot, dest));
+      console.log(`    update ${dest}`);
+    }
+  }
+
+  console.log();
+  console.log("  Done! Commands and templates updated.");
+  console.log("  Your feedbacks, backlogs, inbox, and index.yaml are untouched.\n");
+}

package/templates/commands/product.backlog.md

@@ -0,0 +1,134 @@
+---
+description: Browse and manage backlogs — list all by status or inspect a specific backlog with linked feedbacks.
+handoffs:
+  - label: Promote backlog
+    agent: product.promote
+    prompt: Promote a backlog to feature
+    send: true
+  - 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).
+
+- If `$ARGUMENTS` contains a backlog ID (e.g., `BL-001`): show detail view for that backlog
+- If `$ARGUMENTS` is empty: show list of all backlogs grouped by status
+
+## Purpose
+
+Read-only command to browse and inspect backlog items. List all backlogs grouped by status, or view detailed information about a specific backlog including its linked feedbacks.
+
+## Execution Flow
+
+### 1. Validate environment
+
+- Check that `.product/` directory exists. If not → **ERROR**: "Product directory not initialized."
+
+### 2. Determine mode
+
+- **If `$ARGUMENTS` is empty**: List mode (Mode 1)
+- **If `$ARGUMENTS` contains `BL-xxx`**: Detail mode (Mode 2)
+
+### 3. Mode 1 — List all backlogs
+
+1. Scan all `.product/backlogs/` subdirectories: `open/`, `in-progress/`, `done/`, `promoted/`, `cancelled/`
+2. For each backlog file found, parse YAML frontmatter to extract: id, title, priority, feedbacks count, created date, owner, features
+3. Group by status directory
+4. Display grouped summary:
+
+```markdown
+## Product Backlog
+
+**Total**: {count} items
+
+### Open ({count})
+
+| ID | Title | Priority | Feedbacks | Created |
+|----|-------|----------|-----------|---------|
+| BL-xxx | {title} | {priority} | {feedbacks.length} | {created} |
+
+### In Progress ({count})
+
+| ID | Title | Priority | Owner | Created |
+|----|-------|----------|-------|---------|
+| BL-xxx | {title} | {priority} | {owner} | {created} |
+
+### Promoted ({count})
+
+| ID | Title | Feature | Promoted |
+|----|-------|---------|----------|
+| BL-xxx | {title} | {promotion.feature_id} | {promotion.promoted_date} |
+
+### Done ({count})
+
+| ID | Title | Completed |
+|----|-------|-----------|
+(list or "(none)")
+
+### Cancelled ({count})
+
+| ID | Title | Reason |
+|----|-------|--------|
+(list or "(none)")
+```
+
+If no backlogs exist in any directory → **INFO**: "No backlog items. Run `/product.triage` to create backlogs from feedbacks."
+
+### 4. Mode 2 — Backlog detail
+
+1. Search for the backlog file matching the given ID across ALL status directories: `open/`, `in-progress/`, `done/`, `promoted/`, `cancelled/`
+2. If not found → **ERROR**: "Backlog item {id} not found."
+3. Read the full file: parse YAML frontmatter and body content
+4. For each feedback ID in the `feedbacks[]` array:
+   - Search for the feedback file across all `feedbacks/` subdirectories
+   - Read its title and current status
+5. Display detail view:
+
+```markdown
+## {id}: {title}
+
+**Status**: {status} | **Priority**: {priority} | **Category**: {category}
+**Created**: {created} | **Owner**: {owner}
+**Tags**: {tags joined by ", "}
+
+### Linked Feedbacks
+
+| ID | Title | Status | Created |
+|----|-------|--------|---------|
+| FB-xxx | {title} | {status} | {created} |
+
+### Promotion
+
+(if promoted: show feature_id and promoted_date)
+(if not promoted: "Not yet promoted. Run `/product.promote {id}` when ready.")
+
+### Description
+
+{backlog body content}
+```
+
+## Error Handling
+
+- `.product/` missing → ERROR with init instructions
+- BL-xxx not found → ERROR with ID
+- No backlogs exist → INFO suggesting `/product.triage`
+- Linked feedback file missing → show feedback ID with "(not found)" status
+
+## Rules
+
+- This command is **READ-ONLY** — no files are modified
+- ALWAYS search across ALL status directories when looking for a specific backlog or feedback
+- ALWAYS display backlogs sorted by ID within each status group
+- NEVER modify any files

package/templates/commands/product.check.md

@@ -0,0 +1,192 @@
+---
+description: Detect drift and integrity issues — status desync, stale feedbacks, orphaned backlogs, broken chains, index desync, duplicate IDs.
+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
+
+Detect inconsistencies in the `.product/` directory: status/directory desync, stale feedbacks, orphaned backlogs, broken traceability chains, index desync, and duplicate IDs. This is the self-testing mechanism for the product management system.
+
+## Execution Flow
+
+### 1. Validate environment
+
+- Check that `.product/` directory exists. If not → **ERROR**: "Product directory not initialized."
+- Check if `.product/` is empty (no feedbacks, no backlogs) → **INFO**: "Product directory is empty. No checks to perform." → STOP
+
+### 2. Scan all files
+
+Read all files from:
+- `.product/feedbacks/new/`, `triaged/`, `excluded/`, `resolved/`
+- `.product/backlogs/open/`, `in-progress/`, `done/`, `promoted/`, `cancelled/`
+
+For each file, parse the YAML frontmatter. Track all findings.
+
+### 3. Check 1 — Status/directory desync
+
+For each feedback file in all `feedbacks/` subdirectories:
+- Read the `status` field from frontmatter
+- Compare against the directory name the file resides in
+- The directory name IS the canonical status:
+  - `new/` → status should be `"new"`
+  - `triaged/` → status should be `"triaged"`
+  - `excluded/` → status should be `"excluded"`
+  - `resolved/` → status should be `"resolved"`
+- If mismatch → finding: **STATUS_DESYNC** (severity: WARNING)
+  - File path, expected status (from directory), actual status (from frontmatter)
+  - Fix: "Update frontmatter `status` to \"{expected}\""
+
+For each backlog file in all `backlogs/` subdirectories:
+- Same check: directory name must match `status` field
+  - `open/` → `"open"`, `in-progress/` → `"in-progress"`, `done/` → `"done"`, `promoted/` → `"promoted"`, `cancelled/` → `"cancelled"`
+
+### 4. Check 2 — Stale feedbacks
+
+For each feedback in `feedbacks/new/`:
+- Read the `created` date
+- Calculate days since creation: today - created
+- If > 14 days → finding: **STALE_FEEDBACK** (severity: WARNING)
+  - File path, created date, days since creation
+  - Fix: "Run `/product.triage` to process stale feedbacks"
+
+### 5. Check 3 — Orphaned backlogs
+
+For each backlog file in any status directory:
+- Read the `feedbacks[]` array from frontmatter
+- For each listed feedback ID, search for the file across ALL `feedbacks/` subdirectories
+- If **ALL** listed feedbacks are missing → finding: **ORPHANED_BACKLOG** (severity: WARNING)
+  - Backlog file path, missing feedback IDs
+  - Fix: "Remove broken references or recreate the missing feedbacks"
+- If **SOME** listed feedbacks are missing → finding: **PARTIAL_ORPHAN** (severity: INFO)
+  - Backlog file path, missing feedback IDs, existing feedback IDs
+  - Fix: "Remove broken reference(s) from feedbacks[] array"
+
+### 6. Check 4 — Broken traceability chains
+
+**Feedback → Backlog:**
+For each feedback with non-empty `linked_to.backlog[]`:
+- For each referenced backlog ID, search across ALL `backlogs/` subdirectories
+- If not found → finding: **BROKEN_CHAIN_FB_TO_BL** (severity: ERROR)
+  - Feedback file path, missing backlog ID
+  - Fix: "Remove broken reference or create the missing backlog"
+
+**Backlog → Feature:**
+For each backlog with non-empty `features[]`:
+- For each referenced feature ID, check if `.features/{feature_id}.yaml` exists
+- If not found → finding: **BROKEN_CHAIN_BL_TO_FEAT** (severity: ERROR)
+  - Backlog file path, missing feature ID
+  - Fix: "Remove broken reference or create the missing feature"
+
+### 7. Check 5 — Index consistency
+
+Read `.product/index.yaml` and compare against actual filesystem state:
+
+- Compare `feedbacks.total` against actual file count
+- Compare `feedbacks.by_status.*` against actual directory counts
+- Compare `backlogs.total` against actual file count
+- Compare `backlogs.by_status.*` against actual directory counts
+- Compare `feedbacks.items[]` list against actual files
+
+If any mismatch → finding: **INDEX_DESYNC** (severity: WARNING)
+  - What's different (expected vs actual)
+  - Fix: Auto-rebuild the index from filesystem state
+
+If index desync is detected, rebuild `index.yaml` from the filesystem:
+1. Count all feedbacks by status directory
+2. Count all backlogs by status directory
+3. Read category from each feedback for category distribution
+4. Build items arrays from all files
+5. Recalculate metrics
+6. Write the rebuilt index
+
+### 8. Check 6 — ID uniqueness
+
+Scan all feedback files and collect all `id` fields:
+- If any duplicate `id` values found → finding: **DUPLICATE_ID** (severity: ERROR)
+  - The duplicate ID, all file paths containing it
+  - Fix: "Rename one of the duplicate files and update the id field"
+
+Same for backlog files.
+
+### 9. Compile and classify findings
+
+Group findings by severity:
+- **ERROR**: Issues that break traceability or data integrity (must fix)
+- **WARNING**: Issues that indicate drift or neglect (should fix)
+- **INFO**: Minor issues or informational notes (nice to fix)
+
+### 10. Output report
+
+```markdown
+## Product Health Check
+
+**Date**: {today's date}
+**Scanned**: {feedback_count} feedbacks, {backlog_count} backlogs
+
+### Summary
+
+| Severity | Count |
+|----------|-------|
+| ERROR | {count} |
+| WARNING | {count} |
+| INFO | {count} |
+
+### Findings
+
+{For each finding, numbered sequentially:}
+
+#### FINDING-{NNN} [{severity}] {type}
+- **File**: {file path}
+- **{detail key}**: {detail value}
+- **Fix**: {suggested remediation}
+
+### Verdict
+
+**PASS** — No errors found. {warning_count} warning(s) to review.
+or
+**FAIL** — {error_count} error(s) require action.
+```
+
+If no findings at all:
+```markdown
+## Product Health Check
+
+**Date**: {today's date}
+**Scanned**: {feedback_count} feedbacks, {backlog_count} backlogs
+
+**PASS** — Zero findings. Product data is consistent.
+```
+
+## Error Handling
+
+- `.product/` missing → ERROR with init instructions
+- Empty `.product/` → INFO, no checks to perform
+- Unparseable file (malformed frontmatter) → WARN, skip file, report as finding
+- `.features/` missing when checking backlog→feature links → skip those checks, note in report
+
+## Rules
+
+- This command is **READ-ONLY** except for `index.yaml` rebuild when desync is detected
+- ALWAYS check ALL six categories of issues
+- ALWAYS number findings sequentially (FINDING-001, FINDING-002, ...)
+- ALWAYS provide a suggested fix for each finding
+- Verdict is **FAIL** if ANY error-severity findings exist
+- Verdict is **PASS** if only warnings or info findings (or none)
+- NEVER modify feedback or backlog files — only report findings
+- NEVER skip checks — run all 6 checks every time