The meta/ directory

The meta/ directory is the persistent shared memory that lets skills communicate through the filesystem instead of the conversation. Each skill reads and writes predictable paths within it. Every path below is the plugin default; all are configurable via /configure (see Configuration) — the paths.* keys map one-to-one onto these directories.

At a glance

• Directorymeta/

  • Directorywork/ work items (NNNN-title.md)

    • …
  • Directoryplans/ phased implementation plans

    • …
  • Directoryresearch/

    • Directorycodebase/ codebase research documents

      • …
    • Directoryissues/ root-cause analyses (RCAs)

      • …
    • Directorydesign-inventories/ design inventory snapshots

      • …
    • Directorydesign-gaps/ design gap artefacts

      • …
  • Directorydecisions/ architecture decision records

    • …
  • Directorynotes/ short-form notes

    • …
  • Directoryprs/ PR descriptions

    • …
  • Directoryvalidations/ plan validation reports

    • …
  • Directoryreviews/

    • Directoryplans/ plan review artefacts

      • …
    • Directoryprs/ PR review artefacts

      • …
    • Directorywork/ work-item review artefacts

      • …
  • Directoryglobal/ cross-repo / org-wide context

    • …

Directory map

Path	Contents	Written by	Read by
meta/work/	Work items (NNNN-title.md)	create-work-item, extract-work-items, refine-work-item, update-work-item, sync-work-items, conduct-spike	list-work-items, review-work-item, create-plan
meta/plans/	Phased implementation plans	create-plan; implement-plan ticks criteria	review-plan, stress-test-plan, validate-plan, extract-adrs
meta/research/codebase/	Codebase research documents	research-codebase	create-plan, extract-adrs
meta/research/issues/	Root-cause analyses (RCAs)	research-issue	planning and work-item skills
meta/research/design-inventories/	Design inventory snapshots	inventory-design	analyse-design-gaps
meta/research/design-gaps/	Design gap artefacts	analyse-design-gaps	extract-work-items
meta/decisions/	Architecture decision records	create-adr, extract-adrs; review-adr transitions status	research and planning skills
meta/notes/	Short-form notes	create-note	research skills via documents-locator
meta/prs/	PR descriptions	describe-pr	review-pr
meta/validations/	Plan validation reports	validate-plan	—
meta/reviews/plans/	Plan review artefacts	review-plan	—
meta/reviews/prs/	PR review artefacts	review-pr	—
meta/reviews/work/	Work-item review artefacts	review-work-item	—
meta/global/	Cross-repo / org-wide context	you, by hand	research skills via documents-locator

Beyond these directed reads, the documents-locator and documents-analyser agents search all configured paths during research, so anything captured in meta/ can resurface as context later.

Artefact lifecycle

Work items

Work items carry a status field in their YAML frontmatter. The template allows draft, ready, in-progress, review, done, blocked, and abandoned. The typical flow:

Transitions are made with update-work-item, which shows a diff preview but enforces no state machine — any field change is allowed. The diagram is the convention, not a constraint.

Plans

Plans use draft → ready → in-progress → done. A plan starts as a draft from create-plan, becomes ready once reviewed and approved, implement-plan moves it through in-progress while ticking success criteria, and done marks a fully implemented plan — validate-plan then confirms the code matches it.

ADRs

ADRs use proposed → accepted | rejected, and accepted ADRs can later become superseded or deprecated. They are append-only: review-adr enforces that only a proposed ADR’s content can be modified. To revise an accepted decision, run create-adr with --supersedes ADR-NNNN; the original is marked superseded, never edited.

Everything else

Research documents, reviews, validations, and PR descriptions are point-in-time artefacts (status: complete); notes are captured. Design inventories start as draft and are superseded when a newer snapshot of the same source is taken — the old snapshot is kept.