Artifact Inventory
This document catalogs all artifacts produced and consumed by DIDP, their purposes, locations, and lifecycle.
Core Artifacts
iteration_state.yaml
Purpose: Single source of truth for iteration progress
Location: Project root or .didp/iteration_state.yaml
Lifecycle: Created at iteration start, updated throughout, archived at completion
Contents:
iteration:
id: "unique-iteration-id"
goal: "What we're trying to achieve"
created_at: "2025-01-01"
phase:
name: "planning|analysis|spec_lock|implementation|testing|archive|merge|complete"
entered_at: "2025-01-01"
auto_advance: true|false
locked: true|false
exit_criteria:
- criterion: "Description of requirement"
satisfied: true|false
artifacts:
- path: "path/to/artifact"
type: "spec|plan|code|test|doc"
status: "draft|review|approved|frozen"
handoff_notes:
summary: "What happened this session"
decisions_made: []
risks_identified: []
next_recommended_action: "What to do next"
Authority: Highest in source-of-truth hierarchy
workflow_contract.md
Purpose: Agent constitution governing development behavior
Location: docs/workflow_contract.md or project docs
Lifecycle: Created once, rarely modified, versioned with protocol
Contents:
- Purpose and authority statement
- Source of truth hierarchy
- Session bootstrap requirements
- Phase obedience rules
- Conversational mode by phase
- Replan protocol
- Error handling guidance
Authority: Second only to iteration_state.yaml
Bootstrap Prompt
Purpose: Initialize new sessions with minimal context
Location: prompts/bootstrap_prompt_minimal.txt
Variants:
| Variant | Size | Use Case |
|---|---|---|
bootstrap_prompt_minimal.txt | ~500 tokens | Standard initialization |
bootstrap_prompt_ultra_minimal.txt | ~200 tokens | Extremely constrained contexts |
Contents:
You are operating under DIDP (Deterministic Iterative Development Protocol).
MANDATORY FIRST ACTIONS:
1. Read docs/workflow_contract.md
2. Read iteration_state.yaml
3. Identify current phase
4. Resume from handoff_notes.next_recommended_action
If any document is missing or inconsistent, STOP and report.
Do not proceed with any work until these documents are loaded.
Specification Artifacts
Protocol Specification
Purpose: Normative definition of a protocol
Location: spec/<name>/v<major>/index.md
Required Frontmatter:
---
title: "Protocol Name"
version: "1.0"
status: "draft|review|published|deprecated"
owner: "owner@example.com"
published: "2025-01-01" # if published
---
Lifecycle:
- Draft: Initial creation, open to changes
- Review: Seeking feedback, structural changes discouraged
- Published: Frozen, only errata allowed
- Deprecated: Superseded by newer version
JSON Schema
Purpose: Machine-readable validation for YAML artifacts
Location: schemas/<artifact>.schema.json
Example: schemas/iteration_state.schema.json
Usage:
# Validate iteration state
ajv validate -s schemas/iteration_state.schema.json -d iteration_state.yaml
Phase Artifacts
Planning Phase
| Artifact | Purpose | Format |
|---|---|---|
| Goals document | Define iteration objectives | Markdown |
| Scope statement | Boundaries of work | Section in iteration_state |
| Initial requirements | Raw requirements gathering | Markdown list |
Analysis Phase
| Artifact | Purpose | Format |
|---|---|---|
| Analysis report | Findings from investigation | Markdown |
| Risk register | Identified risks and mitigations | YAML or table |
| Feasibility assessment | Can we do this? | Markdown |
Spec Lock Phase
| Artifact | Purpose | Format |
|---|---|---|
| Frozen specification | Immutable requirements | Markdown |
| Implementation plan | How to build it | Markdown |
| Test plan | How to verify it | Markdown |
Implementation Phase
| Artifact | Purpose | Format |
|---|---|---|
| Source code | The thing being built | Various |
| Unit tests | Code-level verification | Various |
| Progress log | What was done | In iteration_state |
Testing Phase
| Artifact | Purpose | Format |
|---|---|---|
| Test results | Pass/fail outcomes | Various |
| Defect log | Issues found | Markdown or YAML |
| Coverage report | What was tested | Various |
Archive Phase
| Artifact | Purpose | Format |
|---|---|---|
| Archive bundle | Preserved iteration state | Zip or directory |
| Retrospective | Lessons learned | Markdown |
Artifact Locations
Standard Directory Structure
project/
├── .didp/
│ ├── iteration_state.yaml # Current state
│ └── archive/ # Past iterations
├── docs/
│ ├── workflow_contract.md # Agent constitution
│ └── ... # Other documentation
├── spec/
│ └── <name>/v<version>/ # Published specs
├── schemas/
│ └── *.schema.json # Validation schemas
├── prompts/
│ └── bootstrap_*.txt # Session prompts
└── src/ # Source code (if applicable)
Artifact Authority Hierarchy
When artifacts conflict, authority is resolved in this order:
iteration_state.yaml(highest)workflow_contract.md- Phase artifacts (specs, plans)
- Git repository state
- Conversational context (lowest)
Artifact Versioning
Specifications
- Major version in URL path
- Minor/patch in frontmatter
- Immutable once published
Iteration State
- Not versioned (current state only)
- History in git commits
- Archived iterations preserved
Supporting Documents
- Version in frontmatter metadata
- Can evolve freely
- Track changes in git
Artifact Validation
Required Validations
| Artifact | Validation |
|---|---|
iteration_state.yaml | JSON Schema, phase transition rules |
| Specification frontmatter | Required fields present |
| Bootstrap prompt | Contains mandatory sections |
Recommended CI Checks
# Example CI validation
validate:
- ajv validate -s schemas/iteration_state.schema.json -d iteration_state.yaml
- check-frontmatter spec/**/*.md
- lint-markdown docs/**/*.md