improve(squad): add optional visual assets support to handoff pipeline (0.12.11)

Author: nolrm

CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.12.11] - 2026-03-03
+
+### Changed
+- **`commands/squad.md`, `.contextkit/commands/squad.md`** — PO agent now checks for screenshots or images the user attached to the `/squad` invocation. If present, each image is saved to `.contextkit/squad/assets/` and listed with a one-line description under the new optional `### Visual Assets` section in the handoff. If no images are provided the section is left empty and the pipeline continues unchanged.
+- **`commands/squad-architect.md`, `.contextkit/commands/squad-architect.md`** — Architect now reads any `### Visual Assets` file paths from the PO Spec before writing the plan.
+- **`commands/squad-dev.md`, `.contextkit/commands/squad-dev.md`** — Dev now reads any `### Visual Assets` file paths from the PO Spec before implementing.
+- **`README.md`** — Added Visual Assets section to the Squad Workflow docs and updated the PO role description.
+
+---
+
 ## [0.12.9] - 2026-03-03
 
 ### Changed

README.md

@@ -173,7 +173,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 |
+| 1 | Product Owner | `/squad` | Writes a user story, acceptance criteria, edge cases, and scope. 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 |
@@ -223,6 +223,10 @@ Architect has questions for PO → run /squad to clarify
 
 After clarifications are added, re-run the asking role's command to continue. This prevents misunderstandings from compounding through the pipeline.
 
+### Visual Assets (Optional)
+
+If you have a screenshot, mockup, or design image relevant to the task, paste or attach it when running `/squad`. The PO agent will save it to `.contextkit/squad/assets/` and reference the path in the handoff. Architect and Dev agents automatically read any listed assets when they pick up the handoff.
+
 ---
 
 ## Git Hooks & Quality Gates

commands/squad-architect.md

@@ -23,7 +23,7 @@ You are the **Architect** in a squad workflow.
    - Tell the user which command to run next (e.g., "Architect clarifications added. Run `/squad-dev` to continue.")
    - **Stop here** — do not rewrite the full plan.
 
-3. Read the **PO Spec** section (User Story, Acceptance Criteria, Edge Cases, Out of Scope).
+3. Read the **PO Spec** section (User Story, Acceptance Criteria, Edge Cases, Out of Scope). If a `### Visual Assets` section exists and has file paths listed, read each file — these are screenshots or mockups the user provided. Use them to inform your design.
 
 4. **Check for previous clarifications**: If there is a `### Questions for PO` section in the Architect Plan block AND the `### Answers` section in the PO Spec block has responses, read the answers. Use them to inform your plan — the PO has addressed your earlier questions.
 

commands/squad-dev.md

@@ -23,7 +23,7 @@ You are the **Developer** in a squad workflow.
    - Tell the user which command to run next (e.g., "Dev clarifications added. Run `/squad-test` to continue.")
    - **Stop here** — do not re-implement.
 
-3. Read the **PO Spec** (for acceptance criteria) and **Architect Plan** (for implementation steps).
+3. Read the **PO Spec** (for acceptance criteria) and **Architect Plan** (for implementation steps). If the PO Spec has a `### Visual Assets` section with file paths listed, read each file — these are screenshots or mockups relevant to what you are building.
 
 4. **Check for previous clarifications**: If there is a `### Questions for Architect` section in the Dev Implementation block AND the Architect Plan block has answers addressing them, read the answers. Use them to inform your implementation.
 

commands/squad.md

@@ -28,6 +28,8 @@ status: pending
 
 ### Out of Scope
 
+### Visual Assets
+
 ### Answers
 
 ---
@@ -99,6 +101,7 @@ status: pending
    - Write specific, testable **Acceptance Criteria** as a numbered checklist
    - Identify **Edge Cases** that the dev and tester should handle
    - Define what is **Out of Scope** to prevent scope creep
+   - **Check for visual assets** (optional): If the user provided any screenshots or images in this conversation, save each one to `.contextkit/squad/assets/<descriptive-name>.png` and list every saved file path with a one-line description under `### Visual Assets`. If no images were provided, leave `### Visual Assets` empty.
 
 5. After writing the spec, update the handoff file:
    - Set `## 1. PO Spec` status to `status: done`

contextkit-docs/app/docs/squad/page.tsx

@@ -9,6 +9,7 @@ export default function SquadPage() {
     { id: 'pipeline', text: 'Pipeline Roles' },
     { id: 'single-task', text: 'Single-Task Flow' },
     { id: 'peer-review', text: 'Peer Review (Optional)' },
+    { id: 'visual-assets', text: 'Visual Assets (Optional)' },
     { id: 'batch', text: 'Batch Flow' },
     { id: 'feedback', text: 'Feedback Loop' },
   ];
@@ -78,7 +79,7 @@ export default function SquadPage() {
                 <td className="py-2 pr-4">1</td>
                 <td className="py-2 pr-4">Product Owner</td>
                 <td className="py-2 pr-4"><code className="rounded bg-muted px-1 font-mono text-xs">/squad</code></td>
-                <td className="py-2">Writes user story, acceptance criteria, edge cases, and scope</td>
+                <td className="py-2">Writes user story, acceptance criteria, edge cases, and scope. Optionally captures screenshots or images as visual assets.</td>
               </tr>
               <tr className="border-b">
                 <td className="py-2 pr-4">2</td>
@@ -156,6 +157,22 @@ export default function SquadPage() {
         </p>
       </div>
 
+      {/* Visual Assets */}
+      <div id="visual-assets" className="space-y-4 pt-4 scroll-mt-20">
+        <h2 className="scroll-m-20 text-2xl font-semibold tracking-tight">Visual Assets <span className="text-base font-normal text-muted-foreground">(Optional)</span></h2>
+        <p className="text-muted-foreground leading-relaxed">
+          If you have a screenshot, mockup, or design image relevant to the task, paste or attach it when running <code className="rounded bg-muted px-1 font-mono text-xs">/squad</code>. The PO agent will save it to <code className="rounded bg-muted px-1 font-mono text-xs">.contextkit/squad/assets/</code> and reference the path in the handoff under a <code className="rounded bg-muted px-1 font-mono text-xs">### Visual Assets</code> section.
+        </p>
+        <div className="rounded-lg border border-primary/20 bg-primary/5 p-4">
+          <p className="text-sm font-medium mb-2">How downstream agents use it</p>
+          <div className="space-y-1 text-sm text-muted-foreground">
+            <p>— Architect reads the images before writing the technical plan</p>
+            <p>— Developer reads the images before implementing</p>
+            <p>— If no images are provided, the section is left empty and the pipeline runs unchanged</p>
+          </div>
+        </div>
+      </div>
+
       {/* Batch Flow */}
       <div id="batch" className="space-y-4 pt-4 scroll-mt-20">
         <h2 className="scroll-m-20 text-2xl font-semibold tracking-tight">Batch Flow</h2>

package.json

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