Artifacts Reference

Every AI-DLC workflow produces artifacts under its intent record dir — aidlc/spaces/<space>/intents/<YYMMDD>-<label>/ (where <space> is default unless a non-default space is in play, and <YYMMDD>-<label> is the intent dir; written <record>/ below). This chapter is a complete reference for the directory structure, per-artifact descriptions, lifecycle, and git policy.

Directory Tree

This is the complete set of places an artifact can land, not what a fresh record looks like. Intent creation makes one folder per phase your scope runs (plus verification/); the rest appear as work happens, and a per-stage folder is created the first time that stage writes.

aidlc/spaces/<space>/intents/<YYMMDD>-<label>/   # one record dir per intent
  aidlc-state.md                    # Workflow state (commit)
  audit/                            # Audit trail — per-clone shards (commit)
    <host>-<clone>.md               # this clone's shard; readers glob + merge by timestamp
  .aidlc-recovery.md                # Recovery breadcrumb (gitignore)
  runtime-graph.json                # Execution telemetry view (gitignore)

  verification/                     # Phase boundary checks (commit)
    phase-check-initialization.md
    phase-check-ideation.md
    phase-check-inception.md
    phase-check-construction.md
    phase-check-operation.md

  initialization/                   # Phase 0 artifacts
    workspace-scaffold/scaffold-report.md
    workspace-detection/workspace-findings.md
    state-init/state-init-summary.md

  ideation/                         # Phase 1 artifacts
    intent-capture/
    market-research/                (conditional)
    feasibility/                    (conditional)
    scope-definition/
    team-formation/                 (conditional)
    rough-mockups/                  (conditional)
    approval-handoff/

  inception/                        # Phase 2 artifacts
    practices-discovery/            (conditional)
    requirements-analysis/
    user-stories/                   (conditional)
    refined-mockups/                (conditional)
    domain-design/             (conditional)
    units-generation/
    contract-design/           (conditional)
    delivery-planning/

  construction/                     # Phase 3 artifacts
    {unit-name}/                    (per unit of work, repeated)
      functional-design/            (conditional)
      nfr-requirements/             (conditional)
      nfr-design/                   (conditional)
      infrastructure-design/        (conditional)
      code-generation/
    build-and-test/
    ci-pipeline/                    (conditional)

  operation/                        # Phase 4 artifacts
    deployment-pipeline/            (conditional)
    environment-provisioning/       (conditional)
    deployment-execution/           (conditional)
    observability-setup/            (conditional)
    incident-response/              (conditional)
    performance-validation/         (conditional)
    feedback-optimization/          (conditional)

  archive/                          (created on-demand)
    {ISO-date}-{stage-name}/

The 9 reverse-engineering deliverables are not in the record dir. They (architecture.md, code-structure.md, technology-stack.md, …) land one level up, in the space-level per-repo CodeKB — aidlc/spaces/<space>/codekb/<repo>/ — one store per repo rather than a copy per intent. On each applicable brownfield intent, the stage checks the store's recorded scope and working-tree fingerprint first. A verified-current store whose coverage fits the intent may be reused by human choice; otherwise a full or focused scan overwrites those nine files (reverse-engineering-timestamp.md records when the last scan ran and what it covered). Intents therefore read the newest scan of the repo, not the one taken when their own record dir was created. What the record dir does get is the stage's own memory.md diary — created on demand when the stage runs (see Per-stage memory diary below) — so an inception/reverse-engineering/ directory can appear there, holding the diary and nothing else. Codekb writes are audit-logged with a codekb > <repo> > <name> breadcrumb, so the per-intent trail still records what changed and when.

Team knowledge is not in the record dir. It lives one level up, at the space level — aidlc/spaces/<space>/knowledge/ (a sibling of intents/) — so it accumulates across every intent in the space rather than being trapped in one intent's record. The engine creates it empty; the team adds free-form files under an optional aidlc-shared/ and per-agent subdirectories. See Knowledge.

Per-stage memory diary. Each executed stage also keeps a committed memory.md alongside its artifacts (e.g. <record>/inception/requirements-analysis/memory.md). It is the stage's observation diary — auto-created from a template at stage start, maintained by the orchestrator during the stage, and read by the §13 Learnings Ritual at the approval gate. It is never hand-edited. See Rules and the Learning Loop for how the diary feeds the learning loop.

Code lives in sibling repos, not the record dir. The aidlc/ tree holds only method, state, audit, and artifacts — never application code. Generated code lands in the workspace's code repos: in the common single-repo case, the project dir itself; in a multi-repo workspace, the sibling repo directories that are immediate children of the workspace root (each with its own .git). An intent records the repos it touches at birth — auto-discovered, or scoped with --repos a,b — in its intents.json row (repos: [...]); Construction anchors each git operation to one of them. An intent with no recorded repos is the single-repo default. See CLI Commands.

Artifact Lifecycle

Artifacts flow through a predictable lifecycle from creation to consumption by downstream stages:

flowchart LR
    CREATE["Stage creates\nartifact"]
    REVIEW["Reviewed at\napproval gate"]
    COMMIT["Committed to\nversion control"]
    CONSUME["Consumed by\ndownstream stages"]
    VERIFY["Verified at\nphase boundary"]

    CREATE --> REVIEW --> COMMIT --> CONSUME --> VERIFY

    style CREATE fill:#e3f2fd,stroke:#2196f3
    style REVIEW fill:#fff3e0,stroke:#ff9800
    style VERIFY fill:#fce4ec,stroke:#e91e63

1. Created — The lead agent produces the artifact during stage execution and writes it to the appropriate subdirectory of the intent's record dir (with the space-level exceptions noted above: Reverse Engineering writes to the per-repo codekb store, team knowledge to knowledge/)
2. Reviewed — You review the artifact at the approval gate and either approve or request changes
3. Committed — After approval, the artifact is ready for version control (see git policy below)
4. Consumed — Downstream stages read the artifact as input (see the inputs table below)
5. Verified — Phase boundary verification checks confirm traceability across all artifacts in the phase

Artifacts by Phase

Initialization (stages 0.1-0.3)

The welcome message is rendered at session start via companyAnnouncements in settings.json — it is not a stage and produces no artifact.

Ideation (stages 1.1-1.7)

Inception (stages 2.1-2.9)

Construction (stages 3.1-3.7)

Stages 3.1-3.5 repeat per unit of work. Artifacts go in construction/{unit-name}/{stage-name}/. Stages 3.6-3.7 run once after all units.

The four design stages (3.1-3.4) prune their artifacts to each unit's kind (tagged in 2.7's edge block: service, spec, ui, packaging, or library). A spec unit owes no scalability doc, a packaging unit no functional spec; a unit left untagged receives the full matrix below. Which artifact applies to which kind is stage frontmatter data (produces_kinds, see Stage definition). A unit for which none of a stage's artifacts apply is complete for that stage with zero files.

Operation (stages 4.1-4.7)

Question Files

Every stage that collects user input produces a co-located question file named {stage-name}-questions.md. Questions use lettered options (A-E) plus a mandatory X. Other (please specify) option, with [Answer]: tags for recording responses.

You choose how to answer at each stage:

You can switch modes mid-stage. The question file is always the source of truth.

What to Commit vs. Gitignore

The shipped .gitignore encodes this split (vision §5.1): the shared work — method, registry, state, audit, artifacts — is committed; per-user session cursors and machine-local derived state are ignored.

Inputs and Dependencies

Each stage reads artifacts from prior stages as input. Key dependency chains:

• Intent Capture artifacts flow into Market Research, Feasibility, Scope Definition, and Rough Mockups
• Requirements Analysis artifacts flow into User Stories, Domain Design, and all Construction stages
• Domain Design and Units Generation artifacts flow into all per-unit Construction stages
• All Construction artifacts flow into Build and Test and CI Pipeline
• Infrastructure Design artifacts flow into Operation stages

For the complete per-stage input table, see the Orchestration Reference.

Phase Boundary Verification

At each phase transition, a verification check runs to confirm traceability:

Next Steps

• State Tracking and Audit Trail — State file and audit trail details
• How a Stage Runs — Stage execution and artifact production
• Glossary — Definitions for artifact, phase boundary verification, question file