Add design spec and component library guidance to annotask-apply skill

Includes new sections on:
- Referencing design spec for consistent tokens and styling
- Searching component libraries before creating new UI
- Updated section_request guidance to use both resources

Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>

Author: kurtstohrer

.docs/README.md docs/README.md.docs/README.md renamed to docs/README.md

@@ -18,14 +18,16 @@ Annotask is a visual markup tool that integrates with Vite and Webpack. The user
 
 If you have `annotask_*` MCP tools available, prefer them over CLI commands — they return structured data directly, are faster, and avoid shell/npx issues. If MCP tools are not available, use the CLI commands shown below.
 
+**Always pass `--mcp` to CLI commands.** The flag emits compact JSON that matches the MCP tool response shapes exactly (no ANSI colors, no human prefixes, `visual` stripped, `agent_feedback` trimmed). That way the same parsing logic works whether you're calling the MCP tool or the CLI fallback.
+
 ## Steps
 
 ### 0. Check server status
 
 **MCP:** If you have MCP tools, the server is already running — skip this step.
 
 ```bash
-npx annotask status
+npx annotask status --mcp
 ```
 
 If this fails, the Annotask dev server isn't running. Ask the user to start it.
@@ -35,7 +37,7 @@ If this fails, the Annotask dev server isn't running. Ask the user to start it.
 **MCP:** `annotask_get_tasks(status: "pending")` — returns compact summaries. Use `detail: true` for full objects.
 
 ```bash
-npx annotask tasks
+npx annotask tasks --mcp --status=pending
 ```
 
 Response (compact task summaries):
@@ -45,7 +47,7 @@ Response (compact task summaries):
 
 Each task summary has: `id`, `type`, `status`, `description`, `file`, `line`, and optionally `component`, `action`, `screenshot`, `feedback` (on denied tasks), `blocked_reason`, `resolution`.
 
-For full task details (context, element_context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask tasks --pretty`. Only fetch full details when the summary doesn't provide enough context to apply the change.
+For full task details (context, element_context, viewport, interaction_history, agent_feedback), use `annotask_get_task` MCP tool or `npx annotask task <id> --mcp` for a single task (`npx annotask tasks --mcp --detail` for the full list). Only fetch full details when the summary doesn't provide enough context to apply the change.
 
 ### Screenshot reference
 
@@ -57,7 +59,7 @@ Some tasks include a `screenshot` field. The screenshot shows exactly what the u
 npx annotask screenshot TASK_ID
 ```
 
-This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code.
+This downloads the PNG to `.annotask/screenshots/`. Use it as visual context alongside the task description and source code. (The screenshot command writes the file on disk — `--mcp` doesn't apply.)
 
 ### 2. Process each pending task — one at a time
 
@@ -70,10 +72,75 @@ Mark it `in_progress` so the user sees you're working on it:
 **MCP:** `annotask_update_task(task_id: "TASK_ID", status: "in_progress")`
 
 ```bash
-npx annotask update-task TASK_ID --status=in_progress
+npx annotask update-task TASK_ID --status=in_progress --mcp
+```
+
+#### b. Reference the design spec for consistency
+
+Before making any design or styling decisions, fetch the project's design spec to ensure consistency with existing tokens (colors, typography, spacing, borders, etc.):
+
+**MCP:** `annotask_get_design_spec()` — returns design tokens summary, framework detection (Tailwind, CSS-in-JS, etc.), and responsive breakpoints.
+
+```bash
+npx annotask design-spec --mcp
+```
+
+Response example:
+```json
+{"version":"1.0","framework":"tailwind","tokens":{"colors":{"primary":"#3b82f6","secondary":"#8b5cf6"},"typography":{"scale":["xs","sm","base","lg","xl"],"families":["Inter","Roboto"]}},"breakpoints":{"sm":"640px","md":"768px","lg":"1024px"}}
+```
+
+For detailed tokens in a specific category:
+
+```bash
+npx annotask design-spec --category=colors --mcp
 ```
 
-#### b. Apply the change
+**When to use:**
+- **Style updates** — Use design tokens instead of arbitrary colors or spacing values
+- **Typography changes** — Reference the font scale and families from the spec
+- **Responsive design** — Use detected breakpoints when adding media queries
+- **New components** — Match the design system when creating new UI
+
+**How to apply:**
+- For color changes, use token names (e.g., `--color-primary`) instead of hardcoded hex values
+- For spacing/sizing, use the project's scale (e.g., Tailwind scale: xs, sm, base, lg, xl)
+- For responsive design, use the detected breakpoints
+- Document the token reference in your resolution note (e.g., "Applied primary color token")
+
+#### c. Find relevant components (optional but recommended)
+
+Before applying structural changes (e.g., `section_request`, new UI elements), check if there are existing components in the project's component library that you can reuse:
+
+**MCP:** `annotask_get_components(search: "button")` — returns matching components from registered libraries with names, descriptions, and prop signatures. Limit results with `limit`, offset with `offset`, filter by `library`.
+
+```bash
+npx annotask components "button" --mcp
+```
+
+Response example:
+```json
+{"version":"1.0","libraries":[{"name":"antenna","components":[{"name":"Button","description":"Primary button component","props":{"variant":{"type":"string","default":"primary","options":["primary","secondary","tertiary"]},"size":{"type":"string","default":"md"},"disabled":{"type":"boolean"}}}]}]}
+```
+
+For a specific component, get its full prop signature:
+
+```bash
+npx annotask component Button --mcp
+```
+
+**When to use:**
+- **Section requests** — Instead of creating HTML from scratch, search for relevant components and compose them
+- **UI additions** — Check if a button, card, modal, or input component already exists before writing custom HTML
+- **Styling consistency** — Using library components ensures your changes match the design system
+
+**How to apply:**
+- Search for components matching the intent (e.g., "dropdown" if adding a select menu)
+- Read the props to understand customization options (variant, size, disabled, etc.)
+- Use the component in your JSX/Vue/Svelte code with appropriate props
+- Document the component reference in your resolution note
+
+#### d. Apply the change
 
 Read the task type and apply accordingly:
 
@@ -85,7 +152,7 @@ Read the task type and apply accordingly:
 
 - **`style_update`**: Apply CSS property changes. The `context.changes` array contains each change with `property`, `before`, and `after` values. Use scoped styles, inline styles, or Tailwind classes based on project patterns.
 
-- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints.
+- **`section_request`**: Create a new section in the template near the referenced element. The `description` field describes what content to create. `placement` gives spatial hints. Use the design spec (step b) and component library search (step c) to find relevant components and tokens before writing custom HTML.
 
 - **`a11y_fix`**: Fix an accessibility violation. The `context` contains `rule` (axe rule ID), `impact`, `help` (what to fix), `helpUrl` (WCAG reference), and `elements` array with `html` snippets, `selector`, `fix` suggestions, and source `file`/`line`/`component`.
 
@@ -105,14 +172,14 @@ Read the task type and apply accordingly:
   - If `isNew` is true: add the new variable/config entry in the most appropriate location (`:root` block in the main CSS file, or Tailwind config `theme.extend`).
   - After applying, update `.annotask/design-spec.json` to reflect the new value so the Theme page stays in sync.
 
-#### c. Ask for clarification (only when stuck)
+#### e. Ask for clarification (only when stuck)
 
 If you are **genuinely stuck** — missing API context, unclear library usage, ambiguous intent that could lead to a wrong implementation — ask the user for clarification instead of guessing:
 
 **MCP:** `annotask_update_task(task_id: "TASK_ID", questions: [{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}])`
 
 ```bash
-npx annotask update-task TASK_ID --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
+npx annotask update-task TASK_ID --mcp --ask='{"message":"Optional markdown context","questions":[{"id":"q1","text":"Which auth library should I use?","type":"choice","options":["NextAuth","Clerk","Custom"]},{"id":"q2","text":"Where is the session config located?","type":"text"}]}'
 ```
 
 This sets the task to `needs_info` status. The user sees your questions in the Annotask UI and responds there. When answered, the task returns to `in_progress` with answers in `agent_feedback`.
@@ -125,16 +192,16 @@ This sets the task to `needs_info` status. The user sees your questions in the A
 - Only ask when you truly cannot proceed — do not ask for confirmation on straightforward tasks
 - Be specific: "Which CSS framework should I use for the grid?" is better than "How should I do this?"
 - Combine related questions into a single ask rather than multiple rounds
-- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks`
+- After asking, move on to the next task. Come back to check answers later via `annotask_get_tasks` MCP tool or `npx annotask tasks --mcp`
 
-#### d. Mark as blocked (when the task can't be done)
+#### f. Mark as blocked (when the task can't be done)
 
 If the task is **fundamentally outside your control** — a performance issue in a third-party library, an accessibility bug in a dependency, a config change that requires infrastructure access, etc. — mark it as blocked with an explanation:
 
 **MCP:** `annotask_update_task(task_id: "TASK_ID", blocked_reason: "This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone.")`
 
 ```bash
-npx annotask update-task TASK_ID --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
+npx annotask update-task TASK_ID --mcp --blocked-reason="This layout shift is caused by vue-router v4's async route loading. Needs upstream fix or a loading skeleton wrapper — cannot be resolved by editing component code alone."
 ```
 
 This sets the task to `blocked` status automatically. The user sees your explanation and can either **dismiss** the task or **push back** (deny it with feedback asking you to try a different approach).
@@ -143,21 +210,21 @@ This sets the task to `blocked` status automatically. The user sees your explana
 - `needs_info` = "I can do this, but I need more information from you"
 - `blocked` = "This can't be done through source code changes — here's why"
 
-#### e. Mark for review immediately
+#### g. Mark for review immediately
 
 As soon as you finish applying **this** task, mark it for review with a brief resolution note:
 
 **MCP:** `annotask_update_task(task_id: "TASK_ID", status: "review", resolution: "Swapped grid to flexbox, added gap-4 for spacing")`
 
 ```bash
-npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing"
+npx annotask update-task TASK_ID --status=review --resolution="Swapped grid to flexbox, added gap-4 for spacing" --mcp
 ```
 
 Keep resolutions short — one sentence describing what you changed, not why. The user sees it in the Annotask shell alongside the diff.
 
-#### f. Move to the next task
+#### h. Move to the next task
 
-Repeat steps a–c for each remaining pending task. This way the user gets incremental feedback — they can accept or deny early tasks while later ones are still being applied.
+Repeat steps a–g for each remaining pending task. This way the user gets incremental feedback — they can accept or deny early tasks while later ones are still being applied.
 
 ### 3. Report to the user