chatroom-cli 1.91.0 → 1.91.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
package/dist/index.js.map
CHANGED
|
@@ -621,7 +621,7 @@
|
|
|
621
621
|
"/**\n * Command generator for handoff CLI command.\n *\n * Single source of truth for all handoff command examples and actual commands.\n *\n * Now uses stdin (HERE documents) instead of file-based approach.\n */\n\nimport type { HandoffParams } from '../../types/cli';\nimport {\n formatStdinHeredocCommand,\n HANDOFF_MESSAGE_MARKER,\n HANDOFF_STDIN_DELIMITER,\n} from '../stdin-heredoc';\n\n/**\n * Generate a handoff command string using stdin.\n * Returns a bash command that uses HERE document for message input.\n *\n * @example\n * // Command with placeholders\n * handoffCommand({ cliEnvPrefix: '' })\n * // → \"chatroom handoff ... << 'CHATROOM_HANDOFF_END'\\n---MESSAGE---\\n[Your message here]\\nCHATROOM_HANDOFF_END\"\n *\n * @example\n * // Command with real values\n * handoffCommand({\n * chatroomId: 'abc123',\n * role: 'builder',\n * nextRole: 'planner',\n * })\n * // → \"chatroom handoff --chatroom-id=abc123 --role=builder --next-role=planner << 'CHATROOM_HANDOFF_END'\\n[Your message here]\\nCHATROOM_HANDOFF_END\"\n */\nexport function handoffCommand(params: HandoffParams): string {\n const prefix = params.cliEnvPrefix || '';\n const chatroomId = params.chatroomId || '<chatroom-id>';\n const role = params.role || '<role>';\n const nextRole = params.nextRole || '<target>';\n const placeholder = params.messagePlaceholder ?? '[Your message here]';\n\n const commandPrefix = `${prefix}chatroom handoff --chatroom-id=\"${chatroomId}\" --role=\"${role}\" --next-role=\"${nextRole}\"`;\n return formatStdinHeredocCommand(commandPrefix, HANDOFF_STDIN_DELIMITER, placeholder, {\n messageMarker: HANDOFF_MESSAGE_MARKER,\n });\n}\n",
|
|
622
622
|
"/**\n * Commands Reference Section\n *\n * CLI command reference (handoff, get-next-task).\n */\n\nimport { contextReadCommand } from '../cli/context/read';\nimport { getNextTaskCommand } from '../cli/get-next-task/command';\nimport { getNextTaskReminder } from '../cli/get-next-task/reminder';\nimport { handoffCommand } from '../cli/handoff/command';\nimport { roleGuidanceCommand } from '../cli/role-guidance/command';\nimport type { PromptSection } from '../types/sections';\nimport { createSection } from '../types/sections';\nimport { getCliEnvPrefix } from '../utils/index';\nimport { messagesDownloadSinceCommand } from '../utils/proof-of-verification';\n\nconst HANDOFF_BODY_GUIDANCE = `Fill in the message using the matching template from \\`<handoff-templates>\\` in your task delivery output. Replace \\`[Your message here]\\` with that template content. The closing line must be exactly \\`CHATROOM_HANDOFF_END\\` (not \\`EOF\\`).`;\n\nexport interface CommandsReferenceParams {\n chatroomId: string;\n role: string;\n convexUrl: string;\n}\n\n/**\n * Generate the commands reference section with handoff and get-next-task commands.\n */\nexport function getCommandsReferenceSection(params: CommandsReferenceParams): PromptSection {\n const cliEnvPrefix = getCliEnvPrefix(params.convexUrl);\n const contextReadCmd = contextReadCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n cliEnvPrefix,\n });\n const messagesDownloadCmd = messagesDownloadSinceCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n cliEnvPrefix,\n sinceMessageId: '<from-anchor>',\n limit: 100,\n });\n\n const handoffCmd = handoffCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n nextRole: '<target>',\n cliEnvPrefix,\n });\n\n const waitCmd = getNextTaskCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n cliEnvPrefix,\n });\n\n const content = `### Commands\n\n**Complete chatroom task and hand off:**\n\n\\`\\`\\`bash\n${handoffCmd}\n\\`\\`\\`\n\n${HANDOFF_BODY_GUIDANCE}\n\n**Continue receiving messages after \\`handoff\\`:**\n\\`\\`\\`\n${waitCmd}\n\\`\\`\\`\n\n${getNextTaskReminder()}\n\n**History retrieval:** Run \\`${contextReadCmd}\\` for current-task grounding; run \\`${messagesDownloadCmd}\\` for searchable history (required for cross-task summaries). Use the absolute path printed by the CLI.\n\n**Reference commands:**\n- Download message history: \\`${cliEnvPrefix}chatroom messages download --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\" --format=linear --limit=10\\`\n- Anchor on the user's last message: \\`${cliEnvPrefix}chatroom messages anchor --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\`\n- Read current chatroom task context: \\`${cliEnvPrefix}chatroom context read --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\`\n- Git log: \\`git log --oneline -10\\`\n\n**Recovery commands** (only needed after compaction/restart):\n- Reload system prompt: \\`${cliEnvPrefix}chatroom get-system-prompt --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\`\n- Reload role guidance: \\`${roleGuidanceCommand({ chatroomId: params.chatroomId, role: params.role, cliEnvPrefix })}\\`\n- Read current chatroom task context: \\`${cliEnvPrefix}chatroom context read --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\``;\n\n return createSection('commands-reference', 'knowledge', content);\n}\n\n/** ... */\nexport function getNativeCommandsReferenceSection(params: CommandsReferenceParams): PromptSection {\n const cliEnvPrefix = getCliEnvPrefix(params.convexUrl);\n const contextReadCmd = contextReadCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n cliEnvPrefix,\n });\n const messagesDownloadCmd = messagesDownloadSinceCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n cliEnvPrefix,\n sinceMessageId: '<from-anchor>',\n limit: 100,\n });\n\n const handoffCmd = handoffCommand({\n chatroomId: params.chatroomId,\n role: params.role,\n nextRole: '<target>',\n cliEnvPrefix,\n });\n\n const content = `### Commands\n\n**Complete chatroom task and hand off:**\n\n\\`\\`\\`bash\n${handoffCmd}\n\\`\\`\\`\n\n${HANDOFF_BODY_GUIDANCE}\n\n**Do not run \\`register-agent\\`** — your session was registered when the harness started.\n\n**History retrieval:** Run \\`${contextReadCmd}\\` for current-task grounding; run \\`${messagesDownloadCmd}\\` for searchable history (required for cross-task summaries). Use the absolute path printed by the CLI.\n\n// Mirrors the CLI commands reference above (native harness variant).\n// fallow-ignore-next-line code-duplication\n**Reference commands:**\n- Download message history: \\`${cliEnvPrefix}chatroom messages download --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\" --format=linear --limit=10\\`\n- Anchor on the user's last message: \\`${cliEnvPrefix}chatroom messages anchor --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\`\n- Read current chatroom task context: \\`${cliEnvPrefix}chatroom context read --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\`\n- Git log: \\`git log --oneline -10\\`\n\n**Recovery commands** (only needed after compaction/restart):\n- Reload system prompt: \\`${cliEnvPrefix}chatroom get-system-prompt --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\`\n- Reload role guidance: \\`${roleGuidanceCommand({ chatroomId: params.chatroomId, role: params.role, cliEnvPrefix })}\\`\n- Read current chatroom task context: \\`${cliEnvPrefix}chatroom context read --chatroom-id=\"${params.chatroomId}\" --role=\"${params.role}\"\\``;\n\n return createSection('commands-reference-native', 'knowledge', content);\n}\n",
|
|
623
623
|
"/**\n * Command generators for backlog CLI stdin examples.\n */\n\nimport type { CommandContext } from '../../types/cli';\nimport { BACKLOG_STDIN_DELIMITER, formatStdinHeredocCommand } from '../stdin-heredoc';\n\nexport interface BacklogContentCommandParams extends CommandContext {\n chatroomId?: string;\n role?: string;\n backlogItemId?: string;\n contentPlaceholder?: string;\n}\n\n// fallow-ignore-next-line complexity\nexport function backlogAddCommand(params: BacklogContentCommandParams): string {\n const prefix = params.cliEnvPrefix || '';\n const chatroomId = params.chatroomId || '<id>';\n const role = params.role || '<role>';\n const placeholder = params.contentPlaceholder ?? 'Your backlog item content here';\n const commandPrefix = `${prefix}chatroom backlog add --chatroom-id=${chatroomId} --role=${role}`;\n return formatStdinHeredocCommand(commandPrefix, BACKLOG_STDIN_DELIMITER, placeholder);\n}\n\n// fallow-ignore-next-line complexity\nexport function backlogUpdateCommand(params: BacklogContentCommandParams): string {\n const prefix = params.cliEnvPrefix || '';\n const chatroomId = params.chatroomId || '<id>';\n const role = params.role || '<role>';\n const backlogItemId = params.backlogItemId || '<id>';\n const placeholder = params.contentPlaceholder ?? 'New content here';\n const commandPrefix = `${prefix}chatroom backlog update --chatroom-id=${chatroomId} --role=${role} --backlog-item-id=${backlogItemId}`;\n return formatStdinHeredocCommand(commandPrefix, BACKLOG_STDIN_DELIMITER, placeholder);\n}\n",
|
|
624
|
-
"import {\n backlogAddCommand,\n backlogUpdateCommand,\n} from '../../../../../../prompts/cli/backlog/command';\nimport type { SkillModule } from '../../registry';\n\nexport const backlogSkill: SkillModule = {\n skillId: 'backlog',\n name: 'Backlog Reference',\n description:\n 'Full backlog command reference: list/add/update, scoring, completion, close, export/import, and workflow guides.',\n getPrompt: (cliEnvPrefix: string) => `You have been activated with the \"backlog\" skill.\n\n## Command Reference\n\n### List\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog list --chatroom-id=<id> --role=<role>\n\\`\\`\\`\nOptions: \\`--limit=<n>\\`, \\`--sort=date:desc|priority:desc\\`, \\`--filter=unscored\\` (only items without a priority score)\n\nThe list output shows scoring info (complexity, value, priority) for each item if it has been scored.\n\n### History\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog history --chatroom-id=<id> --role=<role>\n\\`\\`\\`\nOptions: \\`--from=YYYY-MM-DD\\`, \\`--to=YYYY-MM-DD\\`, \\`--limit=<n>\\`\n\nDefaults: last 30 days through today; shows completed and closed tasks in range.\n\nUse \\`history\\` for finished work; use \\`list\\` for active backlog items.\n\n### Add\nContent via **stdin / heredoc** or \\`--content-file\\`:\n\n\\`\\`\\`\n${backlogAddCommand({ cliEnvPrefix })}\n\\`\\`\\`\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog add --chatroom-id=<id> --role=<role> --content-file=./task.md\n\\`\\`\\`\n\n### Update\nReplace the **text content** of an existing item. Allowed only while the item is in \\`backlog\\` status. Same input pattern as **add** (stdin/heredoc or \\`--content-file\\`).\n\n\\`\\`\\`\n${backlogUpdateCommand({ cliEnvPrefix })}\n\\`\\`\\`\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog update --chatroom-id=<id> --role=<role> --backlog-item-id=<id> --content-file=./revised.md\n\\`\\`\\`\n\nUse **update** to revise a description in place instead of adding a superseding item.\n\n### Score\n**Requires at least one** of \\`--complexity\\`, \\`--value\\`, or \\`--priority\\` (you can combine multiple).\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog score --chatroom-id=<id> --role=<role> --backlog-item-id=<id> \\\\\n [--complexity=<low|medium|high>] \\\\\n [--value=<low|medium|high>] \\\\\n [--priority=<n>]\n\\`\\`\\`\n\n\\`--priority\\` must be an integer (higher = more important). There is no enforced max in the CLI.\n\n**Important**: Only score items that do not already have all three fields set (complexity, value, priority).\nCheck the list output — items showing \"Score: ...\" are already scored. Skip them to avoid overwriting.\n\n### Complete\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog complete --chatroom-id=<id> --role=<role> --backlog-item-id=<id> [-f|--force]\n\\`\\`\\`\n\nOptional \\`-f\\` / \\`--force\\` is a registered flag (see \\`chatroom backlog complete --help\\`). It is **not** forwarded to the Convex mutation yet, so it does not change server behavior today; omit it unless your runbook says otherwise.\n\n### Reopen\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog reopen --chatroom-id=<id> --role=<role> --backlog-item-id=<id>\n\\`\\`\\`\n\n### Mark for Review\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog mark-for-review --chatroom-id=<id> --role=<role> --backlog-item-id=<id>\n\\`\\`\\`\n\n### Export\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog export --chatroom-id=<id> --role=<role> [--path=<directory>]\n\\`\\`\\`\nExports all backlog items (status=\\`backlog\\`) to a \\`backlog-export.json\\` file in the specified directory.\nCreates the directory if it doesn't exist.\nDefault path (if \\`--path\\` is omitted): \\`<cwd>/.chatroom/exports/\\`\n\n### Import\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog import --chatroom-id=<id> --role=<role> [--path=<directory>]\n\\`\\`\\`\nImports backlog items from a \\`backlog-export.json\\` file in the specified directory.\n- **Idempotent**: skips items whose content already exists (matched by SHA-256 content hash)\n- **Staleness warning**: warns if the export is older than 7 days\nDefault path (if \\`--path\\` is omitted): \\`<cwd>/.chatroom/exports/\\`\n\n### Close\nRetires an item as stale, superseded, or duplicate. **\\`--reason\\` is required** (audit trail).\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog close --chatroom-id=<id> --role=<role> --backlog-item-id=<id> --reason=\"duplicate of XYZ\"\n\\`\\`\\`\n\n⚠️ **RESTRICTED: Only use when the user explicitly asks you to close an item.**\nAgents must NEVER close backlog items autonomously. If an item looks stale or already implemented, prefer \\`mark-for-review\\` so the user decides.\n\nGive a concise, factual reason (e.g. \\`User confirmed: shipped in PR #119\\`).\n\n### Delete\nPermanently removes an item from any status (backlog / pending_user_review / closed). NOT a lifecycle\ntransition — the row is hard-deleted and cannot be reopened. Use for mistakes or items that must not persist.\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog delete --chatroom-id=<id> --role=<role> --backlog-item-id=<id>\n\\`\\`\\`\n\n⚠️ **RESTRICTED: Only use when the user explicitly asks you to delete an item.**\nAgents must NEVER delete backlog items autonomously. For stale/superseded items, prefer \\`close\\` or \\`mark-for-review\\` so the user decides.\n\n---\n\n## Lifecycle\n\nBacklog items move through explicit statuses. **When you raise a PR for user review, use \\`mark-for-review\\` — not \\`complete\\`.** Only mark \\`complete\\` after the PR is merged and verified (or the user confirms).\n\n\\`\\`\\`mermaid\nstateDiagram-v2\n [*] --> backlog: user creates\n backlog --> pending_user_review: agent raises PR (mark-for-review)\n pending_user_review --> closed: user confirms / PR merged (complete)\n backlog --> closed: stale/superseded (close)\n closed --> backlog: reopen\n\\`\\`\\`\n\n\\`delete\\` is a hard removal outside this FSM — not a status transition.\n\n### Command decision table\n\n| Situation | Command |\n|-----------|---------|\n| Fix PR opened, awaiting user review/merge | \\`mark-for-review\\` |\n| PR merged and verified | \\`complete\\` |\n| Stale/duplicate/won't fix | \\`close --reason=...\\` |\n| Mistakenly completed early | \\`reopen\\` then \\`mark-for-review\\` |\n| Permanently remove a mistaken item (cannot be undone) | \\`delete\\` (user-only) |\n\nReference: \\`docs/plans/backlog-item-lifecycle-and-attachments.md\\`\n\n---\n\n## Workflows\n\n### 1. Score Unscored Items\n\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[List backlog items]\n B --> C{Any unscored?}\n C -->|No| D([Done])\n C -->|Yes| E[\"Check item: does it already have complexity + value + priority set?\"]\n E -->|Already scored| F[Skip — do not overwrite existing score]\n F --> C\n E -->|Not scored| G[Score item: complexity, value, priority]\n G --> C\n\\`\\`\\`\n\nAn item is \"already scored\" if the list output shows \"Score: complexity=... | value=... | priority=...\".\n\n### 2. After Completing a Backlog Task (PR raised)\n\n\\`\\`\\`mermaid\nflowchart TD\n A([Implementation complete]) --> B[Open PR for user review]\n B --> C[\"mark-for-review (NOT complete)\"]\n C --> D[Hand off to user with PR link + summary]\n D --> E([User reviews in Pending Review section])\n\\`\\`\\`\n\nMoves item to \\`pending_user_review\\`. User confirms completion (\\`complete\\`) or sends back for rework (\\`reopen\\`).\n\n### 3. Continuous Backlog Execution\n\nOnly activate when the user explicitly instructs autonomous execution\n(e.g. \"work through the backlog\", \"autonomously implement backlog items\").\n\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[List all backlog items]\n B --> C{Any unscored?}\n C -->|Yes| D[\"Score only items missing complexity/value/priority\\\\n(skip already-scored items)\"] --> E[Re-list]\n C -->|No| E\n E --> F[\"Select items: complexity=low AND value=high\"]\n F --> G{Qualifying items?}\n G -->|No| H([Hand off — no high-ROI items found])\n G -->|Yes| I[Take next item]\n I --> J{Already implemented?\\\\nCheck codebase / recent commits}\n J -->|Yes — stale| K[\"Mark for review\\\\n(note: already implemented)\"]\n J -->|No| L[Implement: code changes + PR]\n L --> K\n K --> M[Mark item for review]\n M --> N{More items?}\n N -->|Yes| I\n N -->|No| O[Hand off to user with full summary]\n O --> P([Done])\n\\`\\`\\`\n\nStale item = backlog task already present in the codebase. Mark immediately; skip implementation.\nROI = low complexity × high value.\n\n### 4. Backlog Cleanup\n\nFollow these steps to clean up the backlog by identifying and closing stale items.\n\n1. List all backlog items:\n \\`\\`\\`\n ${cliEnvPrefix}chatroom backlog list --chatroom-id=<id> --role=<role>\n \\`\\`\\`\n\n2. For each item, assess staleness:\n - Read the content carefully\n - If the item is still valid but the **wording is wrong**, use \\`backlog update\\` to fix the description in place (do not add a duplicate item)\n - Check if already implemented (look at recent commits, PRs, or existing code)\n - Check if superseded by a newer backlog item\n\n3. For stale items, mark for review:\n \\`\\`\\`\n ${cliEnvPrefix}chatroom backlog mark-for-review --chatroom-id=<id> --role=<role> --backlog-item-id=<item-id>\n \\`\\`\\`\n **Important:** Always mark for review — do NOT close directly. Let the user confirm.\n\n4. If you are the coordinator, delegate assessment to workers:\n - Builder checks codebase to determine if items are stale\n - Builder marks stale items for review and reports back\n\n5. Report summary: items reviewed, marked for review, kept, needs clarification\n\n### 5. Export / Import Backlog\n\nUse export/import to transfer backlog items between workspaces or for backup.\nDefault path: \\`<cwd>/.chatroom/exports/\\` — omit \\`--path\\` to use this.\n\n**Export workflow:**\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[\"Export backlog\"]\n B --> C[\"chatroom backlog export\\\\n(writes to <cwd>/.chatroom/exports/ by default)\"]\n C --> D[\"File written: backlog-export.json\"]\n D --> E([Done — report file path to user])\n\\`\\`\\`\n\n**Import workflow:**\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[\"Import backlog\"]\n B --> C[\"chatroom backlog import\\\\n(reads from <cwd>/.chatroom/exports/ by default)\"]\n C --> D{Staleness warning?}\n D -->|Yes — export > 7 days old| E[\"Warn user: export may be stale\"]\n D -->|No| F[\"Import items (skip duplicates)\"]\n E --> F\n F --> G[\"Report: total / imported / skipped\"]\n G --> H([Done])\n\\`\\`\\`\n\n**Key points:**\n- Default path is \\`<cwd>/.chatroom/exports/\\` — no \\`--path\\` needed for standard usage\n- Use \\`--path=<dir>\\` to override with a custom directory\n- Imports are idempotent — running import twice with the same file won't create duplicates\n- Each item is identified by a SHA-256 hash of its content`,\n};\n",
|
|
624
|
+
"import {\n backlogAddCommand,\n backlogUpdateCommand,\n} from '../../../../../../prompts/cli/backlog/command';\nimport type { SkillModule } from '../../registry';\n\nexport const backlogSkill: SkillModule = {\n skillId: 'backlog',\n name: 'Backlog Reference',\n description:\n 'Full backlog command reference: list/add/update, scoring, completion, close, export/import, and workflow guides.',\n getPrompt: (cliEnvPrefix: string) => `You have been activated with the \"backlog\" skill.\n\n## Command Reference\n\n### List\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog list --chatroom-id=<id> --role=<role>\n\\`\\`\\`\nOptions: \\`--limit=<n>\\`, \\`--sort=date:desc|priority:desc\\`, \\`--filter=unscored\\` (only items without a priority score)\n\nThe list output shows scoring info (complexity, value, priority) for each item if it has been scored.\n\n### History\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog history --chatroom-id=<id> --role=<role>\n\\`\\`\\`\nOptions: \\`--from=YYYY-MM-DD\\`, \\`--to=YYYY-MM-DD\\`, \\`--limit=<n>\\`\n\nDefaults: last 30 days through today; shows completed and closed tasks in range.\n\nUse \\`history\\` for finished work; use \\`list\\` for active backlog items.\n\n### Add\nContent via **stdin / heredoc** or \\`--content-file\\`:\n\n\\`\\`\\`\n${backlogAddCommand({ cliEnvPrefix })}\n\\`\\`\\`\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog add --chatroom-id=<id> --role=<role> --content-file=./task.md\n\\`\\`\\`\n\n### Update\nReplace the **text content** of an existing item. Allowed only while the item is in \\`backlog\\` status. Same input pattern as **add** (stdin/heredoc or \\`--content-file\\`).\n\n\\`\\`\\`\n${backlogUpdateCommand({ cliEnvPrefix })}\n\\`\\`\\`\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog update --chatroom-id=<id> --role=<role> --backlog-item-id=<id> --content-file=./revised.md\n\\`\\`\\`\n\nUse **update** to revise a description in place instead of adding a superseding item.\n\n### Score\n**Requires at least one** of \\`--complexity\\`, \\`--value\\`, or \\`--priority\\` (you can combine multiple).\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog score --chatroom-id=<id> --role=<role> --backlog-item-id=<id> \\\\\n [--complexity=<low|medium|high>] \\\\\n [--value=<low|medium|high>] \\\\\n [--priority=<n>]\n\\`\\`\\`\n\n\\`--priority\\` must be an integer (higher = more important). There is no enforced max in the CLI.\n\n**Important**: Only score items that do not already have all three fields set (complexity, value, priority).\nCheck the list output — items showing \"Score: ...\" are already scored. Skip them to avoid overwriting.\n\n### Complete\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog complete --chatroom-id=<id> --role=<role> --backlog-item-id=<id> [-f|--force]\n\\`\\`\\`\n\nOptional \\`-f\\` / \\`--force\\` is a registered flag (see \\`chatroom backlog complete --help\\`). It is **not** forwarded to the Convex mutation yet, so it does not change server behavior today; omit it unless your runbook says otherwise.\n\n### Reopen\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog reopen --chatroom-id=<id> --role=<role> --backlog-item-id=<id>\n\\`\\`\\`\n\n### Mark for Review\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog mark-for-review --chatroom-id=<id> --role=<role> --backlog-item-id=<id>\n\\`\\`\\`\n\n### Export\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog export --chatroom-id=<id> --role=<role> [--path=<directory>]\n\\`\\`\\`\nExports all backlog items (status=\\`backlog\\`) to a \\`backlog-export.json\\` file in the specified directory.\nCreates the directory if it doesn't exist.\nDefault path (if \\`--path\\` is omitted): \\`<cwd>/.chatroom/exports/\\`\n\n### Import\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog import --chatroom-id=<id> --role=<role> [--path=<directory>]\n\\`\\`\\`\nImports backlog items from a \\`backlog-export.json\\` file in the specified directory.\n- **Idempotent**: skips items whose content already exists (matched by SHA-256 content hash)\n- **Staleness warning**: warns if the export is older than 7 days\nDefault path (if \\`--path\\` is omitted): \\`<cwd>/.chatroom/exports/\\`\n\n### Close\nRetires an item as stale, superseded, or duplicate. **\\`--reason\\` is required** (audit trail).\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog close --chatroom-id=<id> --role=<role> --backlog-item-id=<id> --reason=\"duplicate of XYZ\"\n\\`\\`\\`\n\n⚠️ **RESTRICTED: Only use when the user explicitly asks you to close an item.**\nAgents must NEVER close backlog items autonomously. If an item looks stale or already implemented, prefer \\`mark-for-review\\` so the user decides.\n\nGive a concise, factual reason (e.g. \\`User confirmed: shipped in PR #119\\`).\n\n### Delete\nSoft-deletes an item from any status (backlog / pending_user_review / closed). The row is retained for\nreferential integrity, excluded from normal backlog lists, and cannot be reopened.\n\n\\`\\`\\`\n${cliEnvPrefix}chatroom backlog delete --chatroom-id=<id> --role=<role> --backlog-item-id=<id>\n\\`\\`\\`\n\n⚠️ **RESTRICTED: Only use when the user explicitly asks you to delete an item.**\nAgents must NEVER delete backlog items autonomously. For stale/superseded items, prefer \\`close\\` or \\`mark-for-review\\` so the user decides.\n\n---\n\n## Lifecycle\n\nBacklog items move through explicit statuses. **When you raise a PR for user review, use \\`mark-for-review\\` — not \\`complete\\`.** Only mark \\`complete\\` after the PR is merged and verified (or the user confirms).\n\n\\`\\`\\`mermaid\nstateDiagram-v2\n [*] --> backlog: user creates\n backlog --> pending_user_review: agent raises PR (mark-for-review)\n pending_user_review --> closed: user confirms / PR merged (complete)\n backlog --> closed: stale/superseded (close)\n closed --> backlog: reopen\n\\`\\`\\`\n\n\\`delete\\` is a hard removal outside this FSM — not a status transition.\n\n### Command decision table\n\n| Situation | Command |\n|-----------|---------|\n| Fix PR opened, awaiting user review/merge | \\`mark-for-review\\` |\n| PR merged and verified | \\`complete\\` |\n| Stale/duplicate/won't fix | \\`close --reason=...\\` |\n| Mistakenly completed early | \\`reopen\\` then \\`mark-for-review\\` |\n| Permanently remove a mistaken item (cannot be undone) | \\`delete\\` (user-only) |\n\nReference: \\`docs/plans/backlog-item-lifecycle-and-attachments.md\\`\n\n---\n\n## Workflows\n\n### 1. Score Unscored Items\n\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[List backlog items]\n B --> C{Any unscored?}\n C -->|No| D([Done])\n C -->|Yes| E[\"Check item: does it already have complexity + value + priority set?\"]\n E -->|Already scored| F[Skip — do not overwrite existing score]\n F --> C\n E -->|Not scored| G[Score item: complexity, value, priority]\n G --> C\n\\`\\`\\`\n\nAn item is \"already scored\" if the list output shows \"Score: complexity=... | value=... | priority=...\".\n\n### 2. After Completing a Backlog Task (PR raised)\n\n\\`\\`\\`mermaid\nflowchart TD\n A([Implementation complete]) --> B[Open PR for user review]\n B --> C[\"mark-for-review (NOT complete)\"]\n C --> D[Hand off to user with PR link + summary]\n D --> E([User reviews in Pending Review section])\n\\`\\`\\`\n\nMoves item to \\`pending_user_review\\`. User confirms completion (\\`complete\\`) or sends back for rework (\\`reopen\\`).\n\n### 3. Continuous Backlog Execution\n\nOnly activate when the user explicitly instructs autonomous execution\n(e.g. \"work through the backlog\", \"autonomously implement backlog items\").\n\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[List all backlog items]\n B --> C{Any unscored?}\n C -->|Yes| D[\"Score only items missing complexity/value/priority\\\\n(skip already-scored items)\"] --> E[Re-list]\n C -->|No| E\n E --> F[\"Select items: complexity=low AND value=high\"]\n F --> G{Qualifying items?}\n G -->|No| H([Hand off — no high-ROI items found])\n G -->|Yes| I[Take next item]\n I --> J{Already implemented?\\\\nCheck codebase / recent commits}\n J -->|Yes — stale| K[\"Mark for review\\\\n(note: already implemented)\"]\n J -->|No| L[Implement: code changes + PR]\n L --> K\n K --> M[Mark item for review]\n M --> N{More items?}\n N -->|Yes| I\n N -->|No| O[Hand off to user with full summary]\n O --> P([Done])\n\\`\\`\\`\n\nStale item = backlog task already present in the codebase. Mark immediately; skip implementation.\nROI = low complexity × high value.\n\n### 4. Backlog Cleanup\n\nFollow these steps to clean up the backlog by identifying and closing stale items.\n\n1. List all backlog items:\n \\`\\`\\`\n ${cliEnvPrefix}chatroom backlog list --chatroom-id=<id> --role=<role>\n \\`\\`\\`\n\n2. For each item, assess staleness:\n - Read the content carefully\n - If the item is still valid but the **wording is wrong**, use \\`backlog update\\` to fix the description in place (do not add a duplicate item)\n - Check if already implemented (look at recent commits, PRs, or existing code)\n - Check if superseded by a newer backlog item\n\n3. For stale items, mark for review:\n \\`\\`\\`\n ${cliEnvPrefix}chatroom backlog mark-for-review --chatroom-id=<id> --role=<role> --backlog-item-id=<item-id>\n \\`\\`\\`\n **Important:** Always mark for review — do NOT close directly. Let the user confirm.\n\n4. If you are the coordinator, delegate assessment to workers:\n - Builder checks codebase to determine if items are stale\n - Builder marks stale items for review and reports back\n\n5. Report summary: items reviewed, marked for review, kept, needs clarification\n\n### 5. Export / Import Backlog\n\nUse export/import to transfer backlog items between workspaces or for backup.\nDefault path: \\`<cwd>/.chatroom/exports/\\` — omit \\`--path\\` to use this.\n\n**Export workflow:**\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[\"Export backlog\"]\n B --> C[\"chatroom backlog export\\\\n(writes to <cwd>/.chatroom/exports/ by default)\"]\n C --> D[\"File written: backlog-export.json\"]\n D --> E([Done — report file path to user])\n\\`\\`\\`\n\n**Import workflow:**\n\\`\\`\\`mermaid\nflowchart TD\n A([Start]) --> B[\"Import backlog\"]\n B --> C[\"chatroom backlog import\\\\n(reads from <cwd>/.chatroom/exports/ by default)\"]\n C --> D{Staleness warning?}\n D -->|Yes — export > 7 days old| E[\"Warn user: export may be stale\"]\n D -->|No| F[\"Import items (skip duplicates)\"]\n E --> F\n F --> G[\"Report: total / imported / skipped\"]\n G --> H([Done])\n\\`\\`\\`\n\n**Key points:**\n- Default path is \\`<cwd>/.chatroom/exports/\\` — no \\`--path\\` needed for standard usage\n- Use \\`--path=<dir>\\` to override with a custom directory\n- Imports are idempotent — running import twice with the same file won't create duplicates\n- Each item is identified by a SHA-256 hash of its content`,\n};\n",
|
|
625
625
|
"/**\n * Skill Module Registry\n *\n * Defines the SkillModule interface and the SKILLS_REGISTRY constant.\n * To add a new skill: create a module in ./modules/<skill-id>/index.ts\n * and add it to SKILLS_REGISTRY below. No Convex changes needed.\n */\n\nimport { backlogSkill } from './modules/backlog/index';\nimport { codeReviewSkill } from './modules/code-review/index';\nimport type { SkillId } from '../../types/skills';\n\nexport interface SkillModule {\n skillId: SkillId;\n name: string;\n description: string;\n getPrompt(cliEnvPrefix: string): string;\n}\n\nexport const SKILLS_REGISTRY: readonly SkillModule[] = [backlogSkill, codeReviewSkill];\n",
|
|
626
626
|
"/**\n * Glossary Section\n *\n * Provides system-specific definitions of key terms used by agents.\n * Each term can optionally declare a linked skill, shown with \"(1 skill available)\"\n * so agents know they can run `chatroom skill activate <term>` to get more detail.\n */\n\nimport { SKILLS_REGISTRY } from '../../src/domain/usecase/skills/registry';\nimport type { PromptSection } from '../types/sections';\nimport { createSection } from '../types/sections';\nimport { getCliEnvPrefix } from '../utils/index';\n\nexport interface GlossarySectionParams {\n convexUrl: string;\n chatroomId?: string;\n role?: string;\n nativeIntegration?: boolean;\n compactSkills?: boolean;\n}\n\nexport interface GlossaryTerm {\n /** The term name (also the skill ID if linkedSkillId is set) */\n term: string;\n /** Short, system-specific definition (~2 lines) */\n definition: string;\n /** If set, the ID of the skill the agent can activate for this term */\n linkedSkillId?: string;\n}\n\nexport const GLOSSARY_TERMS: GlossaryTerm[] = [\n {\n term: 'session',\n definition:\n 'The entire agent invocation (one harness turn) — from harness startup to shutdown. ' +\n 'A session spans many chatroom tasks. Completing a chatroom task (handoff) does NOT end the session. ' +\n 'Always run `get-next-task` after a handoff to stay in the session.',\n },\n {\n term: 'chatroom-task',\n definition:\n 'One discrete unit of work delivered by `get-next-task`. ' +\n 'A chatroom task begins when the agent receives it and ends when the agent runs `handoff`. ' +\n 'Completing a chatroom task only closes Level B — the session (Level A) continues.',\n },\n {\n term: 'listen-loop',\n definition:\n 'The mandatory foreground loop: after every `handoff`, run `get-next-task` to listen for the next chatroom task. ' +\n 'Running `get-next-task` in the background or skipping it breaks the listen loop and disconnects the agent.',\n },\n {\n term: 'backlog',\n definition:\n 'The list of work items the team intends to do but has not yet started. ' +\n 'Agents use the `chatroom backlog` CLI command group to manage backlog items.',\n linkedSkillId: 'backlog',\n },\n {\n term: 'attachments',\n definition:\n 'Message attachment types (task, backlog, message, snippet) delivered in agent prompts as XML when users attach context to messages.',\n },\n {\n term: 'code-review',\n definition:\n 'Eight-pillar code review framework: simplification, type drift, duplication, design patterns, security, test quality, ownership/observability, and dead code elimination. ' +\n 'Covers AI-generated code review with focus on maintainability and tech debt prevention.',\n linkedSkillId: 'code-review',\n },\n {\n term: 'structural-decisions',\n definition:\n 'Meta-level architectural choices that persist in the codebase and influence consistency: ' +\n 'folder structure, file naming, interface definitions, and key abstraction names/locations ' +\n '(e.g., Repository/Service layers).',\n // No linkedSkillId - this is a concept, not a standalone skill\n },\n];\n\nconst NATIVE_GLOSSARY_TERMS: GlossaryTerm[] = [\n {\n term: 'session',\n definition: 'Your ongoing involvement in this chatroom across multiple tasks.',\n },\n {\n term: 'chatroom-task',\n definition: 'One discrete unit of work. Complete it with `handoff`.',\n },\n ...GLOSSARY_TERMS.filter(\n (entry) =>\n entry.term !== 'session' && entry.term !== 'chatroom-task' && entry.term !== 'listen-loop'\n ),\n];\n\nfunction formatGlossaryEntry(entry: GlossaryTerm): string[] {\n const skillNote = entry.linkedSkillId ? ' (1 skill available)' : '';\n return [`- \\`${entry.term}\\`${skillNote}`, ` - ${entry.definition}`, ''];\n}\n\nfunction buildSkillsSection(cliEnvPrefix: string): string[] {\n const lines = ['# Skills', ''];\n lines.push(\n `Run \\`${cliEnvPrefix}chatroom skill list --chatroom-id=<id> --role=<role>\\` to list all available skills.`\n );\n lines.push('');\n lines.push('## When to Activate Skills');\n lines.push('');\n lines.push('**Proactively activate skills** when your task matches their purpose:');\n for (const skill of SKILLS_REGISTRY) {\n lines.push(`- **${skill.skillId}**: ${skill.description}`);\n }\n lines.push('');\n lines.push(\n \"Don't wait for the user to ask — proactively activate the skill that matches the task.\"\n );\n return lines;\n}\n\n/**\n * Generate the glossary section for the system prompt.\n * Lists all known terms with definitions and skill availability indicators,\n * followed by a Skills discovery line.\n */\nexport function getGlossarySection(params: GlossarySectionParams): PromptSection {\n const cliEnvPrefix = getCliEnvPrefix(params.convexUrl);\n const lines: string[] = ['# Glossary', ''];\n const terms = params.nativeIntegration ? NATIVE_GLOSSARY_TERMS : GLOSSARY_TERMS;\n\n for (const entry of terms) {\n lines.push(...formatGlossaryEntry(entry));\n }\n\n if (params.compactSkills) {\n lines.push('# Skills', '');\n lines.push(\n `Run \\`${cliEnvPrefix}chatroom skill list --chatroom-id=<id> --role=<role>\\` to list available skills. Activate skills proactively when your task matches their purpose.`\n );\n } else {\n lines.push(...buildSkillsSection(cliEnvPrefix));\n }\n\n return createSection('glossary', 'knowledge', lines.join('\\n'));\n}\n",
|
|
627
627
|
"/**\n * Barrel export for planner prompt section builders.\n *\n * Each section builder accepts an explicit team composition config\n * and returns a standalone prompt section string. Callers (team\n * prompt files) compose sections by passing their known team config —\n * no runtime derivation or conditionals inside the section builders.\n */\n\nexport { getCoreResponsibilitiesSection } from './core-responsibilities';\nexport { getDelegationAndDecompositionSection } from './delegation-and-decomposition';\nexport { getDelegationGuidelinesSection } from './delegation-guidelines';\nexport { getHandoffRulesSection } from './handoff-rules';\nexport { getWhenWorkComesBackSection } from './when-work-comes-back';\nexport { getTeamCompositionSection } from './team-composition';\nexport { getProofOfVerificationSection } from './proof-of-verification';\nexport {\n getOperatingModelSection,\n getPlannerPlusBuilderOperatingModel,\n getPlannerSoloOperatingModel,\n} from './operating-model';\nexport type { TeamCompositionConfig } from './team-composition';\n",
|