DIDP v1

DIDP is a deterministic, phase-based workflow designed to make software development restartable, auditable, and safe under context compaction when using humans and AI agents together.

Core principle

Sessions are disposable; repository state is authoritative. If a session is compacted/reset, work resumes from versioned artifacts, not conversational memory.

Authoritative artifacts

DIDP v1 is defined by four canonical artifacts:

1. Iteration State — iteration_state.yaml (single source of truth for “where are we right now?”)
2. Phase Model — the allowed phases + transitions (state machine)
3. Workflow Contract — agent constitution (authority rules + behavior)
4. Bootstrap Prompt — single minimal prompt used at the start of every session

Rule: the assistant must always load (2) and (3) via references, then (1), then phase-relevant artifacts.

---

1) Iteration State Document

Filename (canonical): iteration_state.yaml

Goals

• Authoritative
• Machine + human readable
• Diff-friendly
• Restart-safe

Schema (v1.0)

iteration:
  id: ITER-YYYY-MM-DD-X
  session_scope: single-session
  started_at: YYYY-MM-DD
  last_updated: YYYY-MM-DD

phase:
  name: planning|analysis|spec_lock|implementation|testing|archive|merge|complete
  entered_at: YYYY-MM-DD
  auto_advance: true
  locked: true|false

phase_progress:
  summary: >
    Short human summary of progress.
  completed_tasks: []
  pending_tasks: []

artifacts:
  workflow_contract: docs/workflow_contract.md
  spec: specs/<ITER-ID>/spec.md
  implementation_plan: specs/<ITER-ID>/implementation_plan.md
  roadmap: docs/roadmap.md
  git_ingest: ingests/<date>.txt

constraints:
  spec_locked: true|false
  implementation_plan_locked: true|false
  scope_changes_allowed: true|false

entry_criteria_met: []
exit_criteria: []

handoff_notes:
  risks: []
  decisions: []
  next_recommended_action: >
    The next step to take.

Invariants

• iteration_state.yaml overrides chat memory.
• Phase controls what work is allowed.
• Phase may auto-advance only when exit criteria are met.
• Agents update progress, not goals, unless allowed by phase.

---

2) Phase Model

Canonical phases (ordered)

1. planning
2. analysis
3. spec_lock
4. implementation
5. testing
6. archive
7. merge
8. complete

Allowed transitions

planning → analysis
analysis → spec_lock
analysis → planning   (only if replan_required = true)
spec_lock → implementation
implementation → testing
testing → archive
archive → merge
merge → complete

Replan loop (formal)

During analysis, if assumptions are invalidated:

analysis_outcome:
  replan_required: true
  reason: >
    Explain exactly what was invalidated and why.

Then the conductor resets the phase to planning and records the replan event.

---

3) Workflow Contract (Agent Constitution)

See: docs/workflow_contract.md (authoritative).

---

4) Canonical Bootstrap Prompt (minimal)

See: prompts/bootstrap_prompt_minimal.txt.

---

Testing placement (note)

Testing is layered:

• planning/spec_lock: define acceptance intent & test definitions
• implementation: TDD is allowed as an implementation technique
• testing: validation/proof phase, no new feature work

(Detailed testing integration reserved for DIDP v3; see roadmap.)