@kitsy/coop 2.1.1 → 2.1.2

package/README.md

@@ -23,10 +23,21 @@ For AI-oriented command discovery:
 coop help-ai
 coop help-ai --format json
 coop help-ai --format markdown
+coop help-ai --selection --format markdown
+coop help-ai --state-transitions --format json
+coop help-ai --artifacts --format markdown
+coop help-ai --post-execution --format markdown
 coop help-ai --initial-prompt --strict --repo C:/path/to/repo --delivery MVP --command coop.cmd
+coop help-ai --initial-prompt --rigour balanced --repo C:/path/to/repo --delivery MVP --command coop.cmd
 coop config artifacts.dir docs/agent-artifacts
 ```
 
+Agent contract notes:
+- `coop complete task <id>` requires the task to already be in `in_review`.
+- balanced initial prompts are the recommended default for normal implementation sessions.
+- if an agent is unsure about selection, transitions, artifacts, or whether it should continue, it should call the matching focused `help-ai` topic command instead of guessing.
+- strict initial prompts tell agents to stop after completing the selected task instead of auto-picking another one.
+
 On Windows PowerShell, the global npm install may resolve `coop` to `coop.ps1` first. If an agent or CI shell hits execution-policy issues, use `coop.cmd` explicitly.
 
 Both entrypoints operate on the nearest parent `.coop/` workspace. If no workspace log target exists, CLI errors fall back to `~/.coop/logs/cli.log` or `COOP_HOME/logs/cli.log`.

package/dist/index.js

@@ -2924,6 +2924,12 @@ var catalog = {
     "coop reopen task <id>",
     "coop transition task <id> <status>"
   ],
+  lifecycle_requirements: [
+    "`coop start task <id>` moves a ready task into `in_progress`.",
+    "`coop review task <id>` requires the task to already be `in_progress` and moves it to `in_review`.",
+    "`coop complete task <id>` requires the task to already be `in_review` and moves it to `done`.",
+    "Do not call `coop complete task <id>` directly from `in_progress` unless COOP explicitly adds that transition later."
+  ],
   unsupported_command_warnings: [
     "Do not invent COOP commands such as `coop complete` when they are not present in `help-ai` output.",
     "If a desired lifecycle action is not represented by an allowed command, state that explicitly instead of paraphrasing.",
@@ -3014,7 +3020,13 @@ var catalog = {
       name: "Execute And Integrate",
       description: "Hand execution to an AI provider or code-agent CLI and expose COOP through MCP/API.",
       commands: [
+        { usage: "coop help-ai --selection --format markdown", purpose: "Show the focused rules for deterministic task selection and workspace resolution." },
+        { usage: "coop help-ai --state-transitions --format json", purpose: "Show exact lifecycle commands, prerequisites, and warnings against invented transitions." },
+        { usage: "coop help-ai --artifacts --format markdown", purpose: "Show where contract-review, audit, and planning artifacts must be written." },
+        { usage: "coop help-ai --post-execution --format markdown", purpose: "Show what an agent must do after finishing the selected task." },
+        { usage: "coop help-ai --naming --format markdown", purpose: "Show naming guidance when IDs and naming templates matter." },
         { usage: "coop help-ai --initial-prompt --strict --repo C:/path/to/repo --delivery MVP --command coop.cmd", purpose: "Generate a strict agent bootstrap prompt for a repository and delivery." },
+        { usage: "coop help-ai --initial-prompt --rigour balanced --repo C:/path/to/repo --delivery MVP --command coop.cmd", purpose: "Generate the recommended balanced agent bootstrap prompt for day-to-day implementation work." },
         { usage: "coop config ai.provider codex_cli", purpose: "Use the installed Codex CLI as the execution/refinement backend." },
         { usage: "coop config ai.provider claude_cli", purpose: "Use the installed Claude CLI as the execution/refinement backend." },
         { usage: "coop config ai.provider gemini_cli", purpose: "Use the installed Gemini CLI as the execution/refinement backend." },
@@ -3042,8 +3054,119 @@ var catalog = {
     "Use `coop create ... --from-file|--stdin` and `coop apply draft` instead of editing `.coop` task or idea files directly.",
     "Use `coop log --last --verbose` when command execution fails and the concise error points to a stack trace.",
     "If a workflow depends on stable human-readable IDs, inspect `coop naming` or `coop config id.naming` before creating items."
+  ],
+  post_execution_rules: [
+    "After completing the currently selected task, stop and wait instead of automatically selecting the next task.",
+    "Do not auto-start a second task in the same run unless the user explicitly asks you to continue.",
+    "If you changed task state in COOP, report the exact command used and the resulting new state before doing anything else."
   ]
 };
+function renderTopicPayload(topic) {
+  if (topic === "state-transitions") {
+    return {
+      topic,
+      allowed_lifecycle_commands: catalog.allowed_lifecycle_commands,
+      lifecycle_requirements: catalog.lifecycle_requirements,
+      warnings: catalog.unsupported_command_warnings
+    };
+  }
+  if (topic === "artifacts") {
+    return {
+      topic,
+      artifact_policy: catalog.artifact_policy
+    };
+  }
+  if (topic === "post-execution") {
+    return {
+      topic,
+      post_execution_rules: catalog.post_execution_rules
+    };
+  }
+  if (topic === "selection") {
+    return {
+      topic,
+      selection_rules: catalog.selection_rules,
+      workspace_rules: catalog.workspace_rules
+    };
+  }
+  return {
+    topic,
+    naming_guidance: [
+      "Use `coop naming` to inspect the current naming template and token behavior.",
+      'Use `coop naming preview "<title>"` before creating a new idea, task, or delivery if predictable IDs matter.',
+      "Use `coop config id.naming ...` to override the default semantic naming template."
+    ]
+  };
+}
+function renderAiHelpTopic(format, topic) {
+  const payload = renderTopicPayload(topic);
+  if (format === "json") {
+    return `${JSON.stringify(payload, null, 2)}
+`;
+  }
+  const lines = [];
+  const bullet = (value) => `- ${value}`;
+  const title = topic.split("-").map((part) => part.slice(0, 1).toUpperCase() + part.slice(1)).join(" ");
+  lines.push(format === "markdown" ? `# COOP AI Help: ${title}` : `COOP AI Help: ${title}`, "");
+  if (topic === "state-transitions") {
+    lines.push(format === "markdown" ? "## Allowed Lifecycle Commands" : "Allowed Lifecycle Commands");
+    for (const item of catalog.allowed_lifecycle_commands) {
+      lines.push(bullet(`\`${item}\``));
+    }
+    lines.push("");
+    lines.push(format === "markdown" ? "## Lifecycle Requirements" : "Lifecycle Requirements");
+    for (const item of catalog.lifecycle_requirements) {
+      lines.push(bullet(item));
+    }
+    lines.push("");
+    lines.push(format === "markdown" ? "## Warnings" : "Warnings");
+    for (const item of catalog.unsupported_command_warnings) {
+      lines.push(bullet(item));
+    }
+    lines.push("");
+    return `${lines.join("\n")}
+`;
+  }
+  if (topic === "artifacts") {
+    lines.push(bullet(`Config key: \`${catalog.artifact_policy.config_key}\``));
+    lines.push(bullet(`Default dir: \`${catalog.artifact_policy.default_dir}\``));
+    lines.push(bullet(`Required for: ${catalog.artifact_policy.required_for.join(", ")}`));
+    for (const item of catalog.artifact_policy.guidance) {
+      lines.push(bullet(item));
+    }
+    lines.push("");
+    return `${lines.join("\n")}
+`;
+  }
+  if (topic === "post-execution") {
+    for (const item of catalog.post_execution_rules) {
+      lines.push(bullet(item));
+    }
+    lines.push("");
+    return `${lines.join("\n")}
+`;
+  }
+  if (topic === "selection") {
+    lines.push(format === "markdown" ? "## Selection Rules" : "Selection Rules");
+    for (const item of catalog.selection_rules) {
+      lines.push(bullet(item));
+    }
+    lines.push("");
+    lines.push(format === "markdown" ? "## Workspace Rules" : "Workspace Rules");
+    for (const item of catalog.workspace_rules) {
+      lines.push(bullet(item));
+    }
+    lines.push("");
+    return `${lines.join("\n")}
+`;
+  }
+  for (const item of renderTopicPayload("naming").naming_guidance) {
+    lines.push(bullet(item));
+  }
+  lines.push("");
+  return `${lines.join("\n")}
+`;
+}
 function normalizeRepoPath(repoPath) {
   return repoPath ? path7.resolve(repoPath) : process.cwd();
 }
@@ -3082,22 +3205,30 @@ function renderInitialPrompt(options = {}) {
     "",
     "Rules:",
     "- Learn COOP capabilities from `coop help-ai` before proposing commands.",
+    `- If you are unsure how to pick work, run \`${commandName} help-ai --selection --format markdown\`.`,
+    `- If you are unsure about lifecycle changes, run \`${commandName} help-ai --state-transitions --format markdown\`.`,
+    `- If you are unsure where artifacts should go, run \`${commandName} help-ai --artifacts --format markdown\`.`,
+    `- If you are unsure whether to continue after a task, run \`${commandName} help-ai --post-execution --format markdown\`.`,
     "- Use only commands that actually exist in COOP. Do not invent command names.",
     "- Do not reprioritize work outside COOP unless the user explicitly overrides it.",
     "- Select only the first ready task from the COOP readiness output.",
     "- Inspect the selected task with `coop show task <id>` before implementation.",
+    "- Do not create, edit, move, or normalize files directly inside `.coop/`; use COOP commands, MCP, or API surfaces so COOP remains the canonical writer.",
+    "- Respect lifecycle prerequisites: use `coop review task <id>` before `coop complete task <id>`; do not complete directly from `in_progress`.",
     `- Write any contract-review, audit, or planning artifact under \`${artifactsDir}\` unless the user explicitly chooses another location.`
   ];
   if (rigour === "strict") {
     lines.push(
       "- Before mentioning a COOP command, verify the exact command name from `coop help-ai --format json`.",
       "- If a needed workflow is not supported by an exact COOP command, say that explicitly instead of inventing one.",
-      "- Do not switch to another task unless COOP state changes or the user explicitly redirects you."
+      "- Do not switch to another task unless COOP state changes or the user explicitly redirects you.",
+      "- After executing or completing the selected task, stop and wait for user confirmation before picking another task."
     );
   } else if (rigour === "balanced") {
     lines.push(
       "- Prefer exact COOP commands from `coop help-ai --format json` when describing next actions.",
-      "- If COOP lacks a named command for a desired action, state the limitation plainly."
+      "- If COOP lacks a named command for a desired action, state the limitation plainly.",
+      "- After finishing the selected task, report the resulting COOP state before proposing follow-up work."
     );
   } else {
     lines.push("- Keep COOP as the authority for task selection and lifecycle state.");
@@ -3141,6 +3272,11 @@ function renderAiHelp(format) {
     lines.push(bullet(`\`${item}\``));
   }
   lines.push("");
+  lines.push(format === "markdown" ? "## Lifecycle Requirements" : "Lifecycle Requirements");
+  for (const item of catalog.lifecycle_requirements) {
+    lines.push(bullet(item));
+  }
+  lines.push("");
   lines.push(format === "markdown" ? "## Unsupported / Invented Command Warnings" : "Unsupported / Invented Command Warnings");
   for (const item of catalog.unsupported_command_warnings) {
     lines.push(bullet(item));
@@ -3173,6 +3309,11 @@ function renderAiHelp(format) {
     lines.push(bullet(item));
   }
   lines.push("");
+  lines.push(format === "markdown" ? "## Post-Execution Rules" : "Post-Execution Rules");
+  for (const item of catalog.post_execution_rules) {
+    lines.push(bullet(item));
+  }
+  lines.push("");
   return `${lines.join("\n")}
 `;
 }
@@ -3182,7 +3323,7 @@ function renderAiInitialPrompt(options = {}) {
 
 // src/commands/help-ai.ts
 function registerHelpAiCommand(program) {
-  program.command("help-ai").description("Print AI-oriented COOP capability and usage help").option("--format <format>", "Output format: text | json | markdown", "text").option("--initial-prompt", "Print an agent bootstrap prompt instead of the capability catalog").option("--repo <path>", "Repository path to embed in the initial prompt").option("--delivery <delivery>", "Delivery to embed in the initial prompt").option("--track <track>", "Track to embed in the initial prompt").option("--command <name>", "Command name to embed, e.g. coop or coop.cmd", "coop").option("--rigour <level>", "Prompt rigour: strict | balanced | light", "balanced").option("--strict", "Shortcut for --rigour strict").option("--balanced", "Shortcut for --rigour balanced").option("--light", "Shortcut for --rigour light").action((options) => {
+  program.command("help-ai").description("Print AI-oriented COOP capability and usage help").option("--format <format>", "Output format: text | json | markdown", "text").option("--initial-prompt", "Print an agent bootstrap prompt instead of the capability catalog").option("--topic <topic>", "Focused help topic: state-transitions | artifacts | post-execution | selection | naming").option("--state-transitions", "Focused help for lifecycle and state transition usage").option("--artifacts", "Focused help for artifact placement and policy").option("--post-execution", "Focused help for what to do after finishing the selected task").option("--selection", "Focused help for task selection and workspace resolution").option("--naming", "Focused help for naming IDs and naming templates").option("--repo <path>", "Repository path to embed in the initial prompt").option("--delivery <delivery>", "Delivery to embed in the initial prompt").option("--track <track>", "Track to embed in the initial prompt").option("--command <name>", "Command name to embed, e.g. coop or coop.cmd", "coop").option("--rigour <level>", "Prompt rigour: strict | balanced | light", "balanced").option("--strict", "Shortcut for --rigour strict").option("--balanced", "Shortcut for --rigour balanced").option("--light", "Shortcut for --rigour light").action((options) => {
     const format = options.format ?? "text";
     if (format !== "text" && format !== "json" && format !== "markdown") {
       throw new Error(`Unsupported help-ai format '${format}'. Expected text|json|markdown.`);
@@ -3191,6 +3332,7 @@ function registerHelpAiCommand(program) {
     if (rigour !== "strict" && rigour !== "balanced" && rigour !== "light") {
       throw new Error(`Unsupported help-ai rigour '${rigour}'. Expected strict|balanced|light.`);
     }
+    const topic = resolveHelpTopic(options);
     let artifactsDir = "docs";
     const repoRoot = options.repo ? resolveRepoRoot(options.repo) : resolveRepoRoot();
     try {
@@ -3206,10 +3348,40 @@ function registerHelpAiCommand(program) {
       commandName: options.command,
       rigour,
       artifactsDir
-    }) : renderAiHelp(format);
+    }) : topic ? renderAiHelpTopic(format, topic) : renderAiHelp(format);
     console.log(output3.trimEnd());
   });
 }
+function resolveHelpTopic(options) {
+  const requestedTopics = [];
+  if (options.topic) {
+    requestedTopics.push(options.topic);
+  }
+  if (options.stateTransitions) {
+    requestedTopics.push("state-transitions");
+  }
+  if (options.artifacts) {
+    requestedTopics.push("artifacts");
+  }
+  if (options.postExecution) {
+    requestedTopics.push("post-execution");
+  }
+  if (options.selection) {
+    requestedTopics.push("selection");
+  }
+  if (options.naming) {
+    requestedTopics.push("naming");
+  }
+  const unique2 = [...new Set(requestedTopics)];
+  if (unique2.length > 1) {
+    throw new Error(`Specify only one focused help-ai topic at a time. Received: ${unique2.join(", ")}.`);
+  }
+  const topic = unique2[0];
+  if (topic !== void 0 && topic !== "state-transitions" && topic !== "artifacts" && topic !== "post-execution" && topic !== "selection" && topic !== "naming") {
+    throw new Error(`Unsupported help-ai topic '${topic}'. Expected state-transitions|artifacts|post-execution|selection|naming.`);
+  }
+  return topic;
+}
 
 // src/commands/index.ts
 import path8 from "path";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@kitsy/coop",
   "description": "COOP command-line interface.",
-  "version": "2.1.1",
+  "version": "2.1.2",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -39,9 +39,9 @@
     "chalk": "^5.6.2",
     "commander": "^14.0.0",
     "octokit": "^5.0.5",
-    "@kitsy/coop-ai": "2.1.1",
-    "@kitsy/coop-ui": "^2.1.1",
-    "@kitsy/coop-core": "2.1.1"
+    "@kitsy/coop-ui": "^2.1.2",
+    "@kitsy/coop-ai": "2.1.2",
+    "@kitsy/coop-core": "2.1.2"
   },
   "devDependencies": {
     "@types/node": "^24.12.0",