# Task Spec Format

## XML Structure

```xml
<task>
  <name>Short descriptive name</name>
  <files>Comma-separated list of files to create or edit</files>
  <reads>Files to read before starting (context, design system, existing code)</reads>
  <action>
    Precise instructions. What to build, what patterns to follow, what to avoid.
    Be specific enough that a fresh agent with no prior context can execute this correctly.
  </action>
  <verify>
    How to confirm this worked. A command to run, a URL to open, a file to check.
    Must be executable — not "looks correct" but "running X returns Y".
  </verify>
  <done>
    The single, observable condition that means this task is complete.
  </done>
</task>
```

---

## Examples

### Build a page

```xml
<task>
  <name>Build CE pricing page</name>
  <files>work/pitches/acme/pricing/index.html</files>
  <reads>work/internal-ce/system-export/DESIGN.md</reads>
  <action>
    Build a static HTML pricing page for Acme using CE design system tokens from DESIGN.md.
    Three tiers: Starter (free), Pro ($49/mo), Enterprise (contact).
    Use CE grid-3 layout. Section label in Signal Red (#cc0000). No gradients, no shadows,
    no bold (700) font weight. Max container width 1100px.
  </action>
  <verify>
    Open in browser with: python3 -m http.server 8080 from the file's directory.
    Check: white background, three columns, red section label, Larken headings.
    Run: grep -c "box-shadow\|gradient\|font-weight: 700" index.html — must return 0.
  </verify>
  <done>
    Page renders in browser with three pricing tiers, passes CE compliance grep (0 violations).
  </done>
</task>
```

### Write a script

```xml
<task>
  <name>Script to compress images in a directory</name>
  <files>scripts/images/compress-images.js</files>
  <reads>scripts/images/ (existing scripts for patterns)</reads>
  <action>
    Write a Node.js script that takes a directory path as CLI argument and compresses
    all .jpg/.png files in-place using sharp. Target: <200KB per image. Skip files
    already under target. Log: filename, before size, after size, % saved.
    Follow existing script patterns in scripts/images/.
  </action>
  <verify>
    Run: node scripts/images/compress-images.js work/test-images/
    Check: output log shows before/after sizes. Verify file sizes decreased.
    Run: node scripts/images/compress-images.js — check error message when no arg given.
  </verify>
  <done>
    Script runs, compresses at least one test image, logs before/after, handles missing arg gracefully.
  </done>
</task>
```

### Fix a bug

```xml
<task>
  <name>Fix broken nav link on CE homepage</name>
  <files>public/index.html</files>
  <reads>public/index.html</reads>
  <action>
    The "Work" nav link in the header points to "#work" but the section ID is "case-studies".
    Fix the href to match the correct anchor. Do not change anything else.
  </action>
  <verify>
    Run: grep 'href="#case-studies"' public/index.html — must return at least one match.
  </verify>
  <done>
    Nav "Work" link href is "#case-studies" and matches the section ID on the page.
  </done>
</task>
```

### API integration

```xml
<task>
  <name>Add Notion page creation to daily log script</name>
  <files>scripts/core/log-day.py</files>
  <reads>scripts/core/log-day.py, /home/clawd/secrets/notion/api_key</reads>
  <action>
    Extend log-day.py to also create a Notion page in database ID "301330c2-8646-8146-8451-cf7d2d142925"
    after writing the local markdown file. Page title = today's date. Body = same content as the markdown.
    Use the Notion API key from /home/clawd/secrets/notion/api_key.
    Handle API errors gracefully — local log must succeed even if Notion call fails.
  </action>
  <verify>
    Run: python3 scripts/core/log-day.py --test
    Check: local .md file created AND Notion API returns 200.
    Check: if Notion key is wrong/missing, script still writes local file and prints a warning.
  </verify>
  <done>
    Script creates both local markdown and Notion page. Fails gracefully if Notion is unreachable.
  </done>
</task>
```

---

## Wave Planning Template

Use when a brief contains multiple tasks with dependencies.

```
Wave 1 (parallel): Task A, Task B        — no dependencies
Wave 2 (parallel): Task C, Task D        — need Wave 1 complete
Wave 3 (sequential): Task E              — needs C + D
```

Rule: if two tasks touch the same file → put them in different waves (sequential), not parallel.