artifact-template

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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:

```markdown
## 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:

```markdown
| 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:

```markdown
| 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:

```markdown
| 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.

```markdown
## 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`](../constraint-taxonomy/SKILL.md)'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.

From diego81b/kairos-agents-framework, AGPL-3.0.

More from diego81b/kairos-agents-framework