The Spec Directory Convention

Day 40 · Week 8 · Plugins — Full Package

Slack Message — copy & paste

🤖 Tip #40 — Every skill writes to `.ai/specs/<id>-<slug>/`. Inspectable, resumable, debuggable — file convention over data passing at its best.

#40 Claude Code

**The convention** — Every skill in the pipeline writes to `.ai/specs/<ticket-id>-<slug>/`. The directory grows as you progress: raw-story.md, explain.md, research.md, implement.md, share-plan.md, figma-extract.md.
**Inspectable** — Want to see what the AI extracted from the ticket? Read `raw-story.md`. No log diving, no API calls. Every intermediate result is a plain text file you can read.
**Resumable** — Step 3 failed? Fix the issue and re-run just step 3. It reads step 2's file, which is already there. No need to repeat the entire pipeline.

Specs Convention Pipeline

#40 Plugins — Full Package

1 **Debuggable** — If the plan looks wrong, check `explain.md` — maybe the requirements were misunderstood. Trace backwards through the files to find where things went off track.
2 Know what each file represents
- › `raw-story.md` — fetched ticket from ADO/Jira
- › `explain.md` — dev-focused requirements
- › `research.md` — affected files and codebase analysis
- › `implement.md` — step-by-step implementation plan
- › `share-plan.md` — team-shareable summary
- › `dod.md` — definition of done checklist
3 **Shareable** — Copy `share-plan.md` to Teams or Slack. It's a human-readable summary, not a log dump. Stakeholders can review AI output without touching dev tools.

Specs Convention Pipeline

Your screenshot here Optional — add a screenshot from your own workflow