aiwork-protocol

name

aiwork-protocol

description

Structure AI work artifacts under .aiwork/{YYYY-MM-DD}_{slug}/ folders using the project's protocol (triage, research, spec, prd, plan, review, notes, docs/). Use when the user asks to plan, make a spec, triage, research a task, write a report, code review, summarize findings, save the work, document decisions, record this, write that down, persist findings, or references any path under .aiwork/. Also use when starting a non-trivial task that needs a plan or spec before implementation, or when finishing one and capturing notes.

.aiwork Folder Protocol

Repository-local folder for AI work artifacts, organized by feature or task. Artifacts structure thinking in-session and provide context for future sessions when referenced manually.

Folder layout

.aiwork/
  2026-01-27_auth-refactor/
    triage.md
    spec.md

• Folder: {YYYY-MM-DD}_{slug}/, slug lowercase kebab-case, max 40 chars.
• File: {type}.md. Numbering for multiples of same type:
  • plan.md → plan_2.md → plan_3.md — when one plan was expected, more followed.
  • plan_1.md → plan_2.md → plan_3.md — when multiple are expected from the start.
  • Don't mix schemes in one folder.
• Multi-day: optionally prefix filenames with {YYYY-MM-DD}_.

Usually 1-2 artifacts per task. Pick types that fit.

Grouping and restructuring

One task = one folder. Drift signals:

• Two folders with overlapping scope or near-identical slugs
• Cross-folder references: / "Source plan: ../..." pointers
• Folder that exists only because a ticket number arrived mid-task

On drift, propose consolidation: move artifacts into the canonical folder with a superseded_by: pointer, or merge under one date. Ask before moving files.

Artifact types (all optional)

• triage — problem framing, what's known
• research — codebase exploration, doc reading
• prd — product requirements, success criteria
• spec — technical/architecture decisions
• plan — actionable implementation steps
• review — code review report
• notes — findings, decisions from implementation
• implementation-notes — chronological log kept by /implement: workflow events (ticket started/done, chain stopped) plus decisions, deviations, open questions
• tickets/ — subfolder of vertical-slice tickets, one file per ticket (NN_slug.md, numbered in dependency order), status + blocked_by in frontmatter; created by /to-tickets, worked by /implement
• docs/ — subfolder for downloaded external docs

Custom types (cascade-map.md, checklist.md) are fine when they fit better.

When to create a new plan

New plan file when the approach changes or new constraints emerge between iterations. Otherwise continue the previous plan — don't start one just because the session is new.

Frontmatter

Folder date + filename already encode creation time and type, so don't duplicate. Add structured data that's useful for the artifact.

---
ticket: #123456
references:
  - "Parent: #38234"
  - https://docs.example.com/auth
story_points: 8
superseded_by: plan_2.md
---

Common fields: ticket, references, superseded_by. Avoid fields that need manual upkeep across sessions.

Version control

Whether to commit .aiwork/ is up to the project — either traceability or ephemeral working artifacts is fine.