Skip to content

artifacts.md

Latest commit

 

History

History
101 lines (78 loc) · 5.13 KB

artifacts.md

File metadata and controls

101 lines (78 loc) · 5.13 KB
Raw

Artifacts

Skills communicate through files in .work/. Each phase reads the previous phase's artifact and writes its own. This creates a reviewable chain — you can inspect any artifact to understand what the agent knew and decided at that point.

Directory structure

.work/
├── active/             # Active feature markers (one per in-flight feature)
├── archive/            # Markers of completed features
├── brainstorms/        # Feature brainstorm decision logs
├── research/           # Context scans
├── plans/              # Ordered task lists
├── designs/            # Architecture docs and specs
│   └── diagrams/       # Mermaid .mmd files
├── implementations/    # Per-task implementation notes
└── reviews/            # Code review findings

Active markers

Each in-flight feature has a marker at .work/active/<slug>.md recording where it is in the workflow. Skills auto-select the feature when exactly one marker exists and update the marker's stage as phases complete. The format is fixed:

---
slug: user-auth
stage: brainstorm | mini-spec | research | plan | design | implement | reviewed
date: 2026-03-11
---

/dl:review moves the marker to .work/archive/ when it sets stage: reviewed — the feature is done. When multiple markers accumulate and block auto-selection, skills offer to archive any untouched for more than 30 days.

Naming convention

Artifacts follow the pattern YYYY-MM-DD-<slug>-<type>.md:

2026-03-11-user-auth-brainstorm.md
2026-03-11-user-auth-research.md
2026-03-11-user-auth.md              (plan — no type suffix)
2026-03-11-user-auth-design.md
2026-03-11-user-auth-task-1.md       (implementation note)
2026-03-11-user-auth-review.md       (code review)
  • Date prefix — keeps artifacts sortable by when they were created
  • Slug — a short identifier for the feature, consistent across all phases
  • Type suffix — identifies the phase (brainstorm, research, design, task-N); plans omit the suffix

Slugs are how skills find related artifacts. When you run /dl:design, it matches the slug from your plan to locate the right file.

How artifacts chain

/dl:brainstorm → .work/brainstorms/<slug>-brainstorm.md (includes Research Queries)
                      ↓ (required — feeds research queries)
/dl:research   → .work/research/<slug>-research.md
                      ↓ (feeds context)
/dl:plan       → .work/plans/<slug>.md
                      ↓ (required — feeds task list)
/dl:design     → .work/designs/<slug>-design.md + diagrams/<slug>-*.mmd
                      ↓ (required — feeds specs; primary review checkpoint)
/dl:implement  → .work/implementations/<slug>-task-N.md + code changes
                      ↓ (optional — reviews changes)
/dl:review     → .work/reviews/<slug>-review.md
  • /dl:brainstorm is the recommended entry point. It sizes the work (small work gets a ## Mini-Spec consumed directly by /dl:implement) and produces decisions, research queries, and codebase context through iterative conversation.
  • /dl:research executes the brainstorm's Research Queries section as targeted codebase searches rather than broad scans; without a brainstorm artifact it derives queries from the topic.
  • /dl:plan reads brainstorm and research artifacts. Decisions from brainstorming and gaps from research inform clarifying questions and task ordering. Tasks are vertically-sliced.
  • /dl:design requires a plan. It produces a spec for each task and is the primary review checkpoint — reviewed thoroughly before implementation.
  • /dl:implement requires a plan and design (or a mini-spec for small work). It delegates each task to a fresh-context worker subagent — a single task per invocation, or all to run every unchecked task in order.
  • /dl:review is optional. It reviews changes for rule violations and security issues. Works standalone or after /dl:implement.

Diagrams

/dl:design generates Mermaid diagrams as .mmd files in .work/designs/diagrams/. Each diagram shares the design file's date-slug prefix:

.work/designs/
├── 2026-03-11-user-auth-design.md
└── diagrams/
    ├── 2026-03-11-user-auth-arch.mmd        # High-level architecture
    ├── 2026-03-11-user-auth-flow.mmd        # Data flow
    ├── 2026-03-11-user-auth-component.mmd   # Component design
    └── 2026-03-11-user-auth-sequence.mmd    # Step-by-step interactions

Not every design needs all four types. The skill picks diagram types that best illuminate the feature — an architecture diagram plus a sequence diagram if both structure and interaction flow are non-obvious.

Diagrams use Mermaid syntax (graph TD or sequenceDiagram). They're listed in the design doc under a ## Diagrams section but not embedded inline.

Gitignore

Add .work/ to your project's .gitignore. These are ephemeral workflow artifacts — they capture the agent's reasoning and decisions during development, but they're not source code. The value is in the code and commits they produce, not in the artifacts themselves.

# devloop workflow artifacts
.work/