feat(squad): architect split signal — recommend task splits via po-clarify (0.12.21)

- Architect evaluates complexity before writing the plan (step 5.5):
  flags tasks with >~7 files or multiple independent concerns via
  ### Recommended Split + status: po-clarify, stopping before any dev work
- /squad Clarification Mode detects split recommendation and guides PO
  through approve (run /squad as batch) or proceed-as-is options
- /squad-auto po-clarify message updated to cover split scenario
- Tests: 203 passed; added sync parity test (commands/ == .contextkit/commands/)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nolrm

CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [0.12.21] - 2026-03-06
+
+### Added
+- **Architect split signal** — the Architect now evaluates task complexity before writing the plan. If a task is too large (>~7 files, multiple independent concerns, or significant wasted effort risk), it writes a `### Recommended Split` with proposed sub-tasks and sets `status: po-clarify`. The PO then approves the split (running `/squad` as a batch) or dismisses it and proceeds as-is — no code is written until the PO decides.
+
+### Changed
+- **`/squad` Clarification Mode** — detects `### Recommended Split` in the Architect Plan block and guides the PO through the two response options (approve split or proceed as-is), separate from the standard spec Q&A flow.
+- **`/squad-auto` `po-clarify` message** — updated to mention the split recommendation scenario so users understand what to expect when running `/squad`.
+
+---
+
 ## [0.12.20] - 2026-03-06
 
 ### Added

CLAUDE.md

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

__tests__/integration/download-manifest.test.js

@@ -94,4 +94,36 @@ describe('Download manifest validation', () => {
     expect(content).toContain('`doc`');
     expect(content).toContain('## 7. Doc');
   });
+
+  it('7. commands/squad-architect.md contains the complexity check step and split signal', () => {
+    const content = fs.readFileSync(path.join(ROOT, 'commands/squad-architect.md'), 'utf8');
+    expect(content).toContain('Evaluate complexity');
+    expect(content).toContain('### Recommended Split');
+    expect(content).toContain('po-clarify');
+    expect(content).toContain('7 files');
+  });
+
+  it('8. commands/squad.md Clarification Mode handles split recommendation', () => {
+    const content = fs.readFileSync(path.join(ROOT, 'commands/squad.md'), 'utf8');
+    expect(content).toContain('### Recommended Split');
+    expect(content).toContain('Approve split');
+    expect(content).toContain('Proceed as-is');
+  });
+
+  it('9. commands/squad-auto.md po-clarify message covers split scenario', () => {
+    const content = fs.readFileSync(path.join(ROOT, 'commands/squad-auto.md'), 'utf8');
+    expect(content).toContain('split recommendation');
+  });
+
+  it('10. every file in commands/ has an identical copy in .contextkit/commands/', () => {
+    const commandFiles = listRepoFiles('commands');
+    const outOfSync = commandFiles.filter((f) => {
+      const contextKitCopy = path.join(ROOT, '.contextkit', f);
+      if (!fs.existsSync(contextKitCopy)) return true;
+      const src = fs.readFileSync(path.join(ROOT, f), 'utf8');
+      const dst = fs.readFileSync(contextKitCopy, 'utf8');
+      return src !== dst;
+    });
+    expect(outOfSync).toEqual([]);
+  });
 });

commands/squad-architect.md

@@ -44,7 +44,37 @@ You are the **Architect** in a squad workflow.
    - Tell the user: "The Architect has questions for the PO. Run `/squad` to address them."
    - **Stop here** — do not write the plan yet.
 
-   **If the spec is clear**: Continue to step 6.
+   **If the spec is clear**: Continue to step 5.5.
+
+5.5. **Evaluate complexity** before exploring the codebase:
+   - Count the approximate number of files that would need to change.
+   - Identify whether the task contains multiple independent concerns with no shared implementation dependency.
+   - Ask: if this dev phase fails or goes wrong, is the wasted effort significant?
+
+   **A split is warranted if any of these are true:**
+   - More than ~7 files would need to change
+   - Two or more concerns that could ship independently
+   - Scope large enough that a failed dev phase would waste significant effort
+
+   **If a split is warranted:**
+   - Write a `### Recommended Split` section in the Architect Plan block:
+     ```
+     ### Recommended Split
+     Reason: [one sentence explaining why this task should be split]
+
+     Proposed sub-tasks:
+     1. [sub-task A description]
+     2. [sub-task B description]
+     3. [sub-task C description] (if applicable)
+
+     Note: Run `/squad "sub-task A" "sub-task B" ...` to start a new batch with these tasks.
+     The current handoff will be superseded.
+     ```
+   - Set the top-level `status:` to `po-clarify`
+   - Tell the user: "This task is too large to implement safely as one unit. A split is recommended. Run `/squad` to review the recommendation and decide."
+   - **Stop here** — do not explore the codebase or write the full plan.
+
+   **If none apply**: Continue to step 6.
 
 6. Explore the codebase to understand the current architecture, patterns, and conventions.
 

commands/squad-auto.md

@@ -17,7 +17,7 @@ You are the **Pipeline Runner** for a squad batch workflow. Your job is to read
    If any task has a clarify status:
    - **Pause the pipeline for that task** — do not advance it further.
    - Tell the user which task needs clarification, which role raised questions, and which command to run. For example:
-     - `po-clarify`: "Task #N needs PO clarification. Run `/squad` to address the Architect's questions, then run `/squad-auto` again."
+     - `po-clarify`: "Task #N needs PO input. Run `/squad` — if the Architect flagged a split recommendation, you'll be guided through approving or dismissing it; otherwise you'll answer the Architect's spec questions. Then run `/squad-auto` again."
      - `arch-clarify`: "Task #N needs Architect clarification. Run `/squad-architect` to address the Dev's questions, then run `/squad-auto` again."
      - `dev-clarify`: "Task #N needs Dev clarification. Run `/squad-dev` to address the Tester's questions, then run `/squad-auto` again."
      - `test-clarify`: "Task #N needs Tester clarification. Run `/squad-test` to address the Reviewer's questions, then run `/squad-auto` again."

commands/squad.md

@@ -175,17 +175,28 @@ created: [TIMESTAMP]
 ### Single-task clarification (`handoff.md`)
 
 1. Read `handoff.md`.
-2. Find `### Questions for PO` in any role's block.
-3. Update the PO Spec to address the questions (update User Story, Acceptance Criteria, Edge Cases, Out of Scope as needed).
-4. Add answers under `### Answers` in the PO Spec block:
+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]"
    ```
-5. Set top-level `status:` back to the asking role:
+6. Set top-level `status:` back to the asking role:
    - Questions from Architect → `architect`
    - Questions from Reviewer → `review`
-6. Tell the user which command to run next.
+7. Tell the user which command to run next.
 
 ### Batch clarification (`handoff-[N].md`)
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nolrm/contextkit",
-  "version": "0.12.20",
+  "version": "0.12.21",
   "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": {