feat(opencode+squad): add opencode detection, fix stale ck ai refs, improve squad PO clarification (0.13.1)

Author: nolrm

CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## [0.13.1] - 2026-03-07
+
+### Fixed
+- **`ck ai` stale reference** — removed leftover `ck ai <cmd>` line from post-install Quick Reference output (command was removed in 0.13.0)
+- **Install "In CLI" example** — replaced `ck ai "..."` example with generic slash command guidance
+
+### Added
+- **OpenCode auto-detection** — `ck install` now detects the `opencode` binary in PATH and suggests the OpenCode integration automatically, consistent with how `claude`, `codex`, and `gemini` CLI tools are detected
+
+### Changed
+- **`/squad` vague task handling** — PO now pushes back with up to 5 clarifying questions when a task description is too ambiguous to spec. Sets `status: po-clarify`, writes questions to the handoff, and pauses the pipeline. Running `/squad` again (no args) with answers resumes and writes the full spec.
+- **`/squad` Clarification Mode** — split into two paths: kickoff clarification (questions in PO Spec block → write spec, advance to architect) and downstream clarification (questions from Architect/Reviewer → existing behavior)
+
+---
+
 ## [0.13.0] - 2026-03-07
 
 ### Removed

CLAUDE.md

@@ -4,7 +4,7 @@
 This project uses [ContextKit](https://github.com/nolrm/contextkit) for AI development standards.
 
 ## ContextKit
-Version: 0.12.22
+Version: 0.13.1
 
 ## Project Standards
 

README.md

@@ -143,7 +143,7 @@ ContextKit installs reusable slash commands for supported platforms:
 | `/test` | Generate comprehensive tests |
 | `/doc` | Add documentation |
 | `/spec` | Write a component spec (MD-first) before any code is created |
-| `/squad` | Kick off a squad task — one task or many (auto-detects batch mode) |
+| `/squad` | Kick off a squad task — one task or many (auto-detects batch mode). Pushes back with clarifying questions if the task is vague. |
 | `/squad-architect` | Design the technical plan from the PO spec |
 | `/squad-dev` | Implement code following the architect plan |
 | `/squad-test` | Write and run tests against acceptance criteria |
@@ -168,7 +168,7 @@ The squad workflow turns a single AI session into a structured multi-role pipeli
 
 | Step | Role | Command | What it does |
 |------|------|---------|-------------|
-| 1 | Product Owner | `/squad` | Writes a user story, acceptance criteria, edge cases, and scope. Optionally captures screenshots/images as visual assets. |
+| 1 | Product Owner | `/squad` | Writes a user story, acceptance criteria, edge cases, and scope. If the task is ambiguous, asks up to 5 clarifying questions before writing the spec. Optionally captures screenshots/images as visual assets. |
 | 2 | Architect | `/squad-architect` | Designs the technical approach, files to change, and implementation steps |
 | 3 | Developer | `/squad-dev` | Implements the code following the architect's plan |
 | 4 | Tester | `/squad-test` | Writes and runs tests against the PO's acceptance criteria |

commands/squad.md

@@ -81,7 +81,13 @@ model_routing: false
    - Is scope clear enough to write testable acceptance criteria?
    - Are there decisions the user needs to make first?
 
-   **If clarification needed:** Ask the user up to 5 focused, numbered questions. Wait for answers. Capture Q&A under `### User Clarifications`.
+   **If clarification needed:**
+   - Write up to 5 focused, numbered questions under `### Questions for PO` in the handoff's PO Spec block
+   - Set `## 1. PO Spec` → `status: po-clarify`
+   - Set top-level `status:` → `po-clarify`
+   - Tell the user: "I need some clarification before writing the spec. Please answer these questions and run `/squad` again (no args)."
+   - **Stop here.** Do not write the spec yet.
+
    **If clear:** Continue.
 
 4. Read the codebase to understand the project.
@@ -175,32 +181,48 @@ created: [TIMESTAMP]
 ### Single-task clarification (`handoff.md`)
 
 1. Read `handoff.md`.
-2. Find `### Questions for PO` in any role's block (Architect Plan, Review, etc.).
-3. **Check for a split recommendation**: Look for `### Recommended Split` in the Architect Plan block.
-
-   **If `### Recommended Split` exists** (Architect flagged task as too complex):
-   - Read the recommended sub-tasks and reason.
-   - Present the two options to the user:
-     - **Option A — Approve split**: Run `/squad "sub-task A" "sub-task B" ...` with the proposed sub-tasks. The current handoff will be superseded by the new batch.
-     - **Option B — Proceed as-is**: Add a note in the PO Spec `### Answers` block: `- Split recommendation from Architect → "Proceed as one task"`. Set the top-level `status:` back to `architect`. Tell the user: "Noted. Run `/squad-architect` to continue — the Architect will write the full plan."
-   - **Stop here** — do not run the standard Q&A answer flow below.
-
-   **If no `### Recommended Split`**: Continue to step 4.
-
-4. Update the PO Spec to address the questions (update User Story, Acceptance Criteria, Edge Cases, Out of Scope as needed).
-5. Add answers under `### Answers` in the PO Spec block:
-   ```
-   - Q1 from [Role]: "[question]" → "[answer]"
-   - Q2 from [Role]: "[question]" → "[answer]"
-   ```
-6. Set top-level `status:` back to the asking role:
-   - Questions from Architect → `architect`
-   - Questions from Reviewer → `review`
-7. Tell the user which command to run next.
+2. Find `### Questions for PO` — note **which block** it appears in:
+   - **In `## 1. PO Spec`** → kickoff clarification (PO needs more info before writing the spec). Continue to step 3a.
+   - **In `## 2. Architect Plan` or `## 6. Review`** → downstream clarification (Architect or Reviewer raised questions). Skip to step 3b.
+
+3a. **Kickoff clarification path** (questions in PO Spec block):
+   - Read the questions from `### Questions for PO` and the user's answers (from their message or from `### User Clarifications`).
+   - Write the full PO Spec using the answers: User Story, Acceptance Criteria, Edge Cases, Out of Scope.
+   - Capture Q&A under `### User Clarifications`:
+     ```
+     - Q: "[question]" → A: "[answer]"
+     ```
+   - Set `## 1. PO Spec` → `status: done`
+   - Set top-level `status:` → `architect`
+   - Tell the user: "Spec written. Run `/squad-auto` to continue the pipeline."
+   - **Stop here.**
+
+3b. **Downstream clarification path** (questions in Architect Plan or Review block):
+   - **Check for a split recommendation**: Look for `### Recommended Split` in the Architect Plan block.
+
+     **If `### Recommended Split` exists** (Architect flagged task as too complex):
+     - Read the recommended sub-tasks and reason.
+     - Present the two options to the user:
+       - **Option A — Approve split**: Run `/squad "sub-task A" "sub-task B" ...` with the proposed sub-tasks. The current handoff will be superseded by the new batch.
+       - **Option B — Proceed as-is**: Add a note in the PO Spec `### Answers` block: `- Split recommendation from Architect → "Proceed as one task"`. Set the top-level `status:` back to `architect`. Tell the user: "Noted. Run `/squad-architect` to continue — the Architect will write the full plan."
+     - **Stop here** — do not run the Q&A answer flow below.
+
+     **If no `### Recommended Split`**: Continue.
+
+   - Update the PO Spec to address the questions (update User Story, Acceptance Criteria, Edge Cases, Out of Scope as needed).
+   - Add answers under `### Answers` in the PO Spec block:
+     ```
+     - Q1 from [Role]: "[question]" → "[answer]"
+     - Q2 from [Role]: "[question]" → "[answer]"
+     ```
+   - Set top-level `status:` back to the asking role:
+     - Questions from Architect → `architect`
+     - Questions from Reviewer → `review`
+   - Tell the user which command to run next.
 
 ### Batch clarification (`handoff-[N].md`)
 
-Follow the same steps above, but target the specific `handoff-[N].md` file that has `status: po-clarify`.
+Follow the same steps above, targeting the specific `handoff-[N].md` that has `status: po-clarify`. Apply the kickoff path (3a) or downstream path (3b) based on which block the questions appear in.
 
 ---
 
@@ -228,6 +250,8 @@ status: pending
 
 ### Visual Assets
 
+### Questions for PO
+
 ### User Clarifications
 
 ### Answers

lib/commands/install.js

@@ -1622,7 +1622,6 @@ enforcement:
     console.log(chalk.bold('📖 Quick Reference'));
     console.log(''.padEnd(48, '─'));
     console.log(`ck status    → Check installation & integrations`);
-    console.log(`ck ai <cmd>  → Use AI with project context`);
     console.log(`ck <platform> → Add platform (claude, cursor, copilot, codex, opencode, gemini, aider, continue, windsurf)`);
     console.log('');
     console.log(`Docs → ${chalk.blue('https://contextkit-docs.vercel.app')}`);
@@ -1668,7 +1667,7 @@ enforcement:
     }
 
     console.log(chalk.bold('In CLI'));
-    console.log(`ck ai "create a Button component for customer checkout"`);
+    console.log(chalk.dim('Use your AI tool\'s slash command, e.g. /analyze or @.contextkit/commands/create-component.md'));
     console.log('');
 
     if (platform === 'claude' || platform === 'gemini') {

lib/utils/tool-detector.js

@@ -29,6 +29,7 @@ class ToolDetector {
       claude_cli: await this.detectCLITool('claude'),
       gemini_cli: await this.detectCLITool('gemini'),
       codex_cli: await this.detectCLITool('codex'),
+      opencode_cli: await this.detectCLITool('opencode'),
     };
 
     return this.detectedTools;
@@ -120,6 +121,7 @@ class ToolDetector {
       'claude_cli',  // Good CLI
       'gemini_cli',  // Alternative CLI
       'codex_cli',   // OpenAI Codex CLI
+      'opencode_cli', // OpenCode CLI
     ];
 
     return priority.filter(tool => detected[tool]);

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "ContextKit - Context Engineering for AI Development. Provide rich context to AI through structured MD files with standards, code guides, and documentation. Works with Cursor, Claude, Aider, VS Code Copilot, and more.",
   "main": "lib/index.js",
   "bin": {