Artifact Template

Shared reference for context-extractor-agent, impact-assessment-agent, bug-triage-agent, pm-agent, architect-agent, implementer-tdd-agent, implementer-coder-agent, implementer-lead-agent, code-reviewer-agent, security-reviewer-agent, test-verifier-agent, qa-plan-agent, release-planner-agent, documentation-agent, retrospective-agent, improvement-advisor-agent, and dependency-audit-agent.

Every phase artifact has two readers with opposite needs. The human at the HITL gate wants to know in ten seconds what happened and whether to approve. The next agent needs the full data model, the complete API contracts, the whole issues table as prompt input. Cutting detail to serve the first reader breaks the second one. This skill layers instead: a fixed head block that answers the gate, and everything else below it, unchanged.

It governs four things only — the head block, the column sets of Disposition tables, the Ledger Update block a reviewer returns instead of writing the ledger in a review wave (§5), and how a row is worded when a person has to answer it (§6). Each agent's own Output Format section stays the source of truth for its frontmatter and for every detail section it emits.

1. The Summary block

Every artifact body opens with ## Summary as its first section — after the # <Title> heading where the phase uses one, immediately after the frontmatter where it doesn't — and nothing else comes before the phase's own sections. Five bold labels, in this order, one line each, always all five present:

## Summary
**What:** <what this phase produced, one line>
**Decision:** <the one choice this phase made, or `none — analysis only`>
**Needs your attention:** <row IDs of every critical/high row, or `nothing above medium`>
**Open:** <ledger IDs of the questions this phase leaves open, or `none`>
**Next:** <next agent, or `end of pipeline`, or `stop — <reason>`>

Rules:

• Seven lines maximum, heading included. This block is what the orchestrator prints at the gate (HITL step 3), which is capped at ~7 lines. A block that runs long defeats its own purpose.
• Needs your attention carries row IDs, never restated descriptions — R1, R3 — see Risks or F2 — see Findings. The Risk Disposition Loop edits those rows after this file is written; a restated description drifts out of sync the moment it does, and a reader who wants the detail is one scroll away. Cap at three IDs, then and N more. Write nothing above medium when no row is critical or high, or none when the phase has no Impact-rated table at all — never leave the line out.
• Open carries ledger/open-questions.md row IDs, never restated questions and never IDs invented locally — Q3, Q7 — see ledger. That file is the authoritative list; a question this phase raised has a row there before this line names it. Cap at three IDs, then and N more. Write none when this phase left nothing open — never leave the line out. (impact-assessment-agent is the one exception: it runs before the ledger exists and names its own ## Open Questions table's IDs instead.)
• An open point written in prose but not in open-questions.md does not exist. This is the rule that makes the line above honest. A question raised in a paragraph of the body, and nowhere else, is invisible to every later phase, to the orchestrator's end-of-run ledger audit, and to _tracking.md — it reaches nobody. Before writing the Summary, check that every unresolved question the body raises has a ledger row; raise the row if it doesn't, then name it here.
• Decision is the phase's own choice, not a summary of the work: the selected architecture option, the effort classification, the pass/fail verdict, the chosen deployment strategy. Phases that only observe (context-extractor, retrospective) write none — analysis only.
• Next is the only place the successor is named. Name the agent that runs after this one; when the phase is terminal (release-planner, documentation), write end of pipeline; when the phase's own status blocks advancement, write stop — <one-clause reason>. No frontmatter field duplicates it — the orchestrator derives the next phase from which artifacts exist, not from a field the artifact declares about itself.
• Write the block last, after the body is complete and the tallies are final — it describes what the artifact actually says, not what you set out to write.
• A cumulative artifact gets a cumulative Summary. 03-implementation.md is rewritten by every wave, loop iteration and re-run, and each rewrite carries the rest of the file forward — so the Summary must too. It describes the feature's state across every pass, with the current pass named at the end of What, never only the pass that happens to write it last: the orchestrator prints it verbatim at the gate, and a per-pass Summary on a cumulative file tells the human only what the last wave did.

2. Disposition table columns

Any table the orchestrator's Risk Disposition Loop walks row by row must carry exactly one of the column sets below, spelled exactly as written. The loop reads these tables by their Disposition column, wherever they sit in the body — this skill fixes the columns, not the position. Keep each table where its own agent's Output Format puts it.

Standard (five columns) — Risks, Issues, Findings, Contract Drift, Documentation Gaps, Flagged Conflicts:

| ID | Description | Impact | Mitigation/Fix | Disposition |

The fourth column is Mitigation/Fix in every phase, whatever the table is named. Mitigation alone and Fix alone are not variants of it — the orchestrator's Constraint & Decision Conflict Scan appends rows written against this exact header, and a table that spells it differently ends up internally inconsistent the first time that scan fires.

Extended (seven columns) — test-verifier-agent only:

| ID | Category | File:Line | Description | Impact | Mitigation/Fix | Disposition |

Leading columns before Description are the extension point. The last three columns stay Impact | Mitigation/Fix | Disposition, in that order, in every variant.

Secondary (four columns) — impact-assessment-agent's Open Questions:

| ID | Description | Why it matters | Disposition |

In all three shapes: leave every Disposition cell empty in your own output. The orchestrator's Risk Disposition Loop fills it from the human's per-row choice; when running standalone, the human does at the gate.

Row overflow. When a row's reasoning doesn't fit one line, keep a one-line Description ending in a "see below" pointer and add a short prose paragraph immediately under the table for that row. The table itself always keeps its own column count — the loop parses it either way, and the paragraph is what the loop's on-demand explain trigger reads from.

3. Detail sections

Everything after the Summary block is the phase's own. Section names, order, and depth come from that agent's Output Format section and are not constrained here. This skill adds a head, it does not reshape the body.

4. Exemptions

Artifact	Exempt from	Why
_tracking.md (orchestrator-written; _recap.md in folders from before v8.5.0)	§1 Summary	It is already a whole-pipeline summary, built from every artifact's own Summary; a summary of a summary adds nothing.
retrospective-agent's Friction Points table	§2 columns	It has no Disposition column — nothing downstream reads it; it is the evidence trail for the lessons below it.
improvement-advisor-agent's ADR files	§1 Summary	ADRs are a fixed external format (Status/Context/Decision/Consequences), not a phase artifact behind a gate. Its _improvement-advisory.md is not exempt.
implementer-lead-agent's 03-contracts.md and 03-verify.md, and each layer agent's 03-layer-<layer>.md (Layered Mode)	§1 Summary	Supporting artifacts, not gated phase outputs: 03-contracts.md is the lead's contracts, 03-layer-<layer>.md is one layer agent's report and 03-verify.md is the lead's verification result. The gate is on 03-implementation-plan.md (whose own Summary covers the contracts) and later on 03-implementation.md.
documentation-agent's _project-summary.md draft (step: summary)	§1 Summary, §2 columns	It is the text of a document the project keeps, written for a reader outside the pipeline: the gate shows its path, and a KAIROS head block would end up in the project's own files. No Disposition column either, because the gate is the whole-artifact one.
context-extractor-agent's Prompt Template section	§1 Summary	Only the artifact body opens with Summary — the prompt block inside it is copy-paste input for another agent, not a section of this document.
bug-triage-agent's Evidence table	§2 columns	It is the proof trail behind the root cause, not a set of findings for a gate to resolve.
_usage.md (orchestrator-written)	§1 Summary, §2 columns	Generated by scripts/usage.mjs from the session transcripts after every agent call, never by an agent (an agent cannot know its own token count while it runs). A measurement table for the human, not a gated phase output.
qa-plan-agent's tables other than ## Risks (Coverage Complement, Manual Test Cases, Expected Behaviour Changes, Exploratory Charters, Existing Manual Cases to Re-run, Test Data & Environment, UAT Sign-off)	§2 columns	They are a plan for a human to execute, not findings for a gate to resolve. ## Risks is the artifact's one Disposition table and uses the standard five columns.
qa-plan-agent's _qa-regression.md catalogue	§1 Summary, §2 columns	A project-wide catalogue a human draws from across features, not a gated phase output — no Disposition column, and the Loop never runs against it.
dependency-audit-agent's tables (Vulnerabilities, Version Currency, Licenses, Debt Hotspots, Backlog)	§2 columns	A standing backlog a human draws from over time, not a gate resolved in one sitting — no Disposition column anywhere, and the Loop never runs against _tech-debt.md.

5. Ledger Update block (review wave)

Outside a review wave an agent updates the three ledger files itself. In a review wave (review_wave: true in the invocation prompt) two or three reviewers run at the same moment, and two agents that read a ledger row and write it back in the same minute overwrite one another, each allocating the next C, D or Q id from the same snapshot. So in a wave code-reviewer-agent, test-verifier-agent and security-reviewer-agent do not write ledger/constraints.md, ledger/decisions.md or ledger/open-questions.md at all. Each ends its artifact with the block below, and the orchestrator applies it in its Step 4.2. What goes into the block is decided by the agent's own Ledger Update section, unchanged; only where the result is written changes.

## Ledger Update
**constraints**
| Row | Constraint | Category | Status | Note |
|-----|------------|----------|--------|------|
| C3 | — | — | 🔴 open | re-opened: `src/pay.ts:88` ignores the cap |
| new | Every error response carries `request_id` | OTHER | 🔴 open | found at review |

**decisions**
| Row | Decision | Rationale | Constraint impact |
|-----|----------|-----------|-------------------|
| new | Reject inline SQL in handlers | the repository layer owns queries | C5 |

**open-questions**
| Row | Question | Status | Answer |
|-----|----------|--------|--------|
| Q2 | — | answered | confirmed by `src/export.ts:12` |
| new | Is the cap per key or per row? | open | — |

Rules:

• Row names an existing row (C3, Q2) or says new. You never write an id for a new row: the orchestrator allocates it, one block after another, so two blocks cannot collide.
• For an existing row only Status and Note carry a value; Constraint and Category are —, because a Category is set once by whoever created the row and never rewritten. A new constraint carries a Category from constraint-taxonomy's closed vocabulary, chosen by its Writer Rule. decisions rows are always new, and the Supersedes column is never yours: the orchestrator writes —.
• Three tables, always present. A table with nothing to say holds one row, none. In Lean Mode (effort: simple_fix) write none in all three unless this pass found something worth recording.
• A row you did not act on stays out, exactly as it stays untouched outside a wave.
• The block is replaced whole on every re-dispatch (a loop iteration, a recheck wave), because it is part of the artifact. Do not list a new row the ledger already holds: you read the ledger before you start, and the orchestrator also drops a new row whose text matches an existing one.

6. Rows a person answers

A Description or a Question in a Disposition table, an open-questions.md row and a Q row in an Open Questions table all end up in front of a person at a gate, usually through one AskUserQuestion with that text as its question and nothing else on screen. The person has not read your artifact. Write each such row so that someone holding only that line can answer it.

• Open with what is undecided, in product or code words. Name the concrete thing: the file, screen, endpoint, table or flow. Should the export cap count rows or keys? can be answered cold; Which unit for the limit (see D4)? cannot.
• Offer the answers. Two or three alternatives, each with its consequence in a clause, the one you would pick first and marked as yours. A row with no alternative says what a person would have to decide, not only that something is open. The alternatives belong in Mitigation/Fix (or Why it matters in the four-column shape): the orchestrator builds its options from there.
• Ids are a trace, never the sentence. A local id (a task T5, a gap G13, an AC-2, a C4, a wave number) may follow in parentheses so a reader can find the source, and the sentence must make sense with the parentheses deleted. An id that a person cannot look up from where they are reading means nothing to them.
• Test before you write it down: could a colleague who opened only this line answer it? If they would have to open another file first, rewrite it.

A generic example. Not Q2: where does T5 live (delivery of G13 after the scope dispose)? but Where should the generated report be delivered once the scope is disposed: next to the source file, or in the shared exports folder? Next to the source keeps one place per project; the shared folder needs a name rule (T5, G13). The ids stay, the question stands alone.

No new column carries this: a legacy ledger has to resume as it is, and a ## Ledger Update block parses the shape §5 shows. The rule is about the text of the cell, so it reaches every table without changing one. The orchestrator checks it again at the point of asking and rewrites a row it cannot ask as written (orchestrator-agent.md, Risk Disposition Loop), which is a safety net for artifacts written before this section, not a reason to write the row carelessly.