# Artifact Conventions > SAM artifact naming, file layout, and cross-referencing conventions for the development harness. - Skill: `tools-only/artifact-conventions` (Agent Skill, multi-file: 3 files) - Install (CLI): `npx skillmds@latest add tools-only/artifact-conventions` - Raw SKILL.md: https://api.skillmd.com/api/skills/tools-only/artifact-conventions/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tools-only (https://skillmd.com/u/tools-only) - Updated: 2026-09-29 - Page: https://skillmd.com/skills/tools-only/artifact-conventions --- # Artifact Conventions SAM artifact naming, file layout, and cross-referencing conventions for the development harness. --- ## Principle Every stage in the SAM pipeline produces a file-based artifact. These artifacts are the only communication channel between stages. No stage relies on conversation memory — each reads its predecessor's artifact and writes its own. This is the stateless property of SAM. --- ## Cross-Reference Token Pattern **Format:** `ARTIFACT:{TYPE}({SCOPE_OR_ID})` **Types:** - `ARTIFACT:DISCOVERY({feature-slug})` — S1 output - `ARTIFACT:PLAN({feature-slug})` — S2 output - `ARTIFACT:CONTEXT({feature-slug})` — S3 output (amends S2) - `ARTIFACT:TASK({task-id})` — S4 output (one per task) - `ARTIFACT:EXECUTION({task-id})` — S5 output (one per task) - `ARTIFACT:REVIEW({feature-slug})` — S6 output - `ARTIFACT:VERIFICATION({feature-slug})` — S7 output **Usage in artifacts:** Each artifact includes a header block with references to predecessor and successor artifacts. ```markdown --- artifact: ARTIFACT:PLAN(add-jwt-auth) predecessor: ARTIFACT:DISCOVERY(add-jwt-auth) successor: ARTIFACT:CONTEXT(add-jwt-auth) feature: add-jwt-auth stage: S2 created: 2026-02-15 --- ``` --- ## File Layout All artifacts are stored in `.planning/harness/` relative to the project root. **Directory structure:** ```text .planning/ harness/ discovery-{feature-slug}.md plan-{feature-slug}.md context-{feature-slug}.md task-{task-id}-{task-slug}.md (one per task) execution-{task-id}-{task-slug}.md (one per task) review-{feature-slug}.md verification-{feature-slug}.md ``` --- ## File Naming Conventions ### Feature-Level Artifacts **Pattern:** `{stage-prefix}-{feature-slug}.md` **Stage prefixes by stage:** - S1 — `discovery` - S2 — `plan` - S3 — `context` - S6 — `review` - S7 — `verification` **Feature slug rules:** - Derived from the feature name or request - Lowercase, hyphen-separated - Max 50 characters - No special characters beyond hyphens **Examples:** - `discovery-add-jwt-auth.md` - `plan-refactor-payment-module.md` - `review-add-csv-export.md` ### Task-Level Artifacts **Pattern:** `{stage-prefix}-{task-id}-{task-slug}.md` **Stage prefixes for task-level:** - S4 — `task` - S5 — `execution` **Task ID rules:** - Three-digit zero-padded integer - Assigned sequentially during S4 Task Decomposition - IDs are stable — not renumbered after creation **Task slug rules:** - Brief description of the task - Same formatting rules as feature slug **Examples:** - `task-001-add-jwt-middleware.md` - `task-002-add-token-validation.md` - `execution-001-add-jwt-middleware.md` - `execution-002-add-token-validation.md` --- ## Artifact Types ### DISCOVERY **Stage:** S1 **Purpose:** Capture requirements, codebase context, constraints, and resolved role assignments. **Required sections:** - Feature request (original, verbatim) - Codebase context (structure, relevant files, patterns) - Constraints identified (bound and unbound) - Role resolution results (which agents assigned to which roles) - Quality gates configured - ARL touchpoint assessment for Gate 1 ### PLAN **Stage:** S2 **Purpose:** Development plan with task graph, acceptance criteria, and RT-ICA analysis. **Required sections:** - RT-ICA gap analysis (present, partial, missing information) - Task graph with dependencies - Task skeletons with acceptance criteria - Quality gate schedule (which gates run at which stages) - Unblock paths for tasks with missing information ### CONTEXT **Stage:** S3 **Purpose:** Plan validated against actual codebase state. **Required sections:** - Validation results per plan element - Codebase discrepancies found (if any) - Plan amendments (if needed) - Verified integration points - Confirmed dependency availability ### TASK **Stage:** S4 **Purpose:** Individual executable task file. **Required sections:** - Task ID and description - Predecessor artifact reference - Assigned agent (from role resolution) - Inputs (files to read, context needed) - Acceptance criteria (testable, specific) - Quality gates to run after completion - Dependencies on other tasks (if any) ### EXECUTION **Stage:** S5 **Purpose:** Record of what was implemented for a task. **Required sections:** - Task reference - Files created or modified (with paths) - Implementation decisions and rationale - Quality gate results (pass/fail per gate) - Deviations from plan (if any) ### REVIEW **Stage:** S6 **Purpose:** Forensic review comparing execution against acceptance criteria. **Required sections:** - Per-task verdict (COMPLETE or NEEDS_WORK) - Acceptance criteria evaluation (pass/fail per criterion) - Quality gate summary - Regression check results - NEEDS_WORK details (what failed, what to fix) ### VERIFICATION **Stage:** S7 **Purpose:** Final certification against original requirements. **Required sections:** - Per-requirement verdict (MET or NOT_MET) - Traceability matrix (requirement to task to implementation) - Full quality gate results - Integration verification results - Final verdict (CERTIFIED or NOT_CERTIFIED) - NOT_CERTIFIED details (what requirements are unmet) --- ## Cross-Referencing Between Artifacts Each artifact references its immediate predecessor and the tasks it relates to. **Forward references:** When S4 creates tasks, each task artifact includes `predecessor: ARTIFACT:PLAN({feature-slug})`. **Backward references:** When S6 reviews tasks, the review artifact includes references to all `ARTIFACT:EXECUTION({task-id})` artifacts. **Traceability chain:** S7 verification builds a complete traceability matrix linking requirements (from S1) through plan (S2), tasks (S4), execution (S5), and review (S6). --- ## Coexistence with Other Planning Tools The `.planning/harness/` directory is scoped to the development harness. Other tools use their own subdirectories: - `.planning/gsd/` — GSD (Get Stuff Done) planning tool - `.planning/backlog/` — Backlog items and grooming - `.planning/` root — Shared or tool-agnostic planning documents The harness never reads or writes outside `.planning/harness/`. No naming collisions occur because each tool uses its own prefix and subdirectory. --- ## Cleanup Artifacts persist after feature completion for auditability. The harness does not auto-delete artifacts. **Manual cleanup:** Users can delete `.planning/harness/` or specific feature artifacts after verification. **Gitignore recommendation:** Add `.planning/` to `.gitignore` unless the team wants planning artifacts in version control. --- ## Sources - SAM methodology: - Default development flow: [./default-development-flow.md](./default-development-flow.md)