build-memory
/build-memory
Owns the build-memory contract that the multi-session build skills share: the committed layout under docs/build/, docs/tickets/ and docs/adr/, the templates, the validator, and legacy-scratch migration. Use it to initialise the layout in a repo (init), validate it (check), migrate a legacy gitignored scratch dir into the committed tree (migrate), or regenerate the ADR index (adr-index). Other skills cite skills/build-memory/layout.md rather than restating the layout.
- Author
- stevevitali ↗
- Repository
- agent-skills ↗
- Licence
- MIT
- Last repository change
- 14.10.2026
Assessment and security
- Files in this package
- 110
- Scripts
- 8
- HTML comments
- 2
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
- 8 scripts in this package. Review them before installing, as Claude may execute them.
- SKILL.md zawiera komentarze HTML (2). Nie widać ich w podglądzie Markdown, a model je czyta.
Scripts: scripts/adr-index.sh, scripts/check-build-memory.sh, scripts/check-history.sh, scripts/memory-root.sh, scripts/migrate-legacy-scratch.sh, tests/history/build.sh, tests/legacy-scratch/.agents/scratch/tools/gen.sh, tests/run-tests.sh
What it does and when to use it
Owns the build-memory contract that the multi-session build skills share: the committed layout under docs/build/, docs/tickets/ and docs/adr/, the templates, the validator, and legacy-scratch migration. Use it to initialise the layout in a repo (init), validate it (check), migrate a legacy gitignored scratch dir into the committed tree (migrate), or regenerate the ADR index (adr-index). Other skills cite skills/build-memory/layout.md rather than restating the layout.
Original author description
Owns the build-memory contract that the multi-session build skills share: the committed layout under docs/build/, docs/tickets/ and docs/adr/, the templates, the validator, and legacy-scratch migration. Use it to initialise the layout in a repo (init), validate it (check), migrate a legacy gitignored scratch dir into the committed tree (migrate), or regenerate the ADR index (adr-index). Other skills cite skills/build-memory/layout.md rather than restating the layout.
How it works
- Resolve the root first (every mode)
- Mode: check (default)
- Mode: init
- Mode: adr-index
- Mode: migrate
- Templates and tests
- Scripts (all bash 3.2+, read-only unless noted)
- What this skill does NOT do
SKILL.md preview
---
name: build-memory
license: MIT
description: "Owns the build-memory contract that the multi-session build skills share: the committed layout under docs/build/, docs/tickets/ and docs/adr/, the templates, the validator, and legacy-scratch migration. Use it to initialise the layout in a repo (init), validate it (check), migrate a legacy gitignored scratch dir into the committed tree (migrate), or regenerate the ADR index (adr-index). Other skills cite skills/build-memory/layout.md rather than restating the layout."
inputs:
- name: mode
required: false
description: "'init' (write the layout into a repo), 'check' (validate — default), 'migrate' (move a legacy scratch dir into docs/build/), or 'adr-index' (regenerate docs/adr/README.md)."
- name: memory_root
required: false
description: "The build-memory root. Default: resolved by scripts/memory-root.sh (committed docs/build when the marker is present, else legacy scratch)."
- name: from
required: false
description: "[migrate] The legacy scratch path to migrate (e.g. .agents/scratch or $AGENT_SCRATCH_DIR)."
- name: apply
required: false
description: "[migrate] Default false = print the dry-run plan only. true = perform the move/rename."
---
# Build Memory
The **owner of the build-memory layer** that `decompose-spec`, `orchestrate-build`,
`implement-spec`, `synthesize-spec` and `reconcile-build` all read and write. It owns one
contract file, one set of templates, one validator and one migration tool, so build memory
is defined in exactly one place.
> **Precedent.** `agent-docs` owns the shared Doc Authoring Guidelines other skills cite;
> `build-memory` owns the layout the same way. **The contract is
> [`layout.md`](layout.md)** — the tree, the modes, the machine-state ledger, the manifest /
> ticket / marker / tail shapes, the deferrals / ADR / index / gate rules, who writes what,
> the validator, and the compatibility policy. Read it before any mode below; every other
> skill cites it and does not restate the tree.
Build memory is **committed** (the record of a multi-session build is audit-valuable and git
is the artifact store); only regenerable bulk (`logs/`) is gitignored. A repo opts in with
the marker `<!-- build-memory: v2 -->` in `docs/build/README.md`. A repo without it runs in
**legacy scratch mode** — byte-for-byte the pre-0.2.0 behaviour (see `layout.md` §
Compatibility and [`README.md`](README.md)).
## Resolve the root first (every mode)
// turbo
```bash
bash scripts/memory-root.sh # prints: mode=<committed|scratch> root=<abs path>
```
Committed mode → the root is `<worktree>/docs/build`, resolved from the **current** worktree
(a sibling build worktree reads its own chain tip). Scratch mode → the legacy gitignored
dir. `$BUILD_MEMORY_ROOT` overrides both.
---
## Mode: `check` (default)
Validate the layout. Read-only; exit-code gated; runnable in CI.
// turbo
```bash
bash scripts/check-build-memory.sh . # tree mode: 0 clean · 1 violations · 2 not a build-memory repo · 3 vacuous
bash scripts/check-build-memory.sh . --range BASE..HEAD # history mode (also --staged, --first-parent SHA); 5 = unknown
bash scripts/check-build-memory.sh . --planning docs/research-ledger.md # planning-ledger freshness (V14)
```
It checks everything the skills derive (layout allowlist + `logs/.gitignore`; ticket filename
grammar + unique sequence; manifest ↔ files both ways; backward `Depends on`; skeletons carry
no run line; markers referenced; DEFERRALS ids unique + valid statuses; no OPEN row past a
PASSED gate; ADR files ↔ generated index; every ADR has `## Revisit trigger`; spec ADR
appendix == file set when present; `LEDGER.md` key set + order and `nextTicket`; PHASE-LOG
"done" ↔ `BUILD_INDEX` row + `runs/<ID>.md`; REQ→ticket coverage when the spec and
`req_id_pattern` resolve; size + secret scans; the ledger budget and shape, BM-LEDGER-08; the
`kind` of 7-column GATE DECISIONS rows and scoped pre-authorizations, BM-GATE-05/-09; the
CURRENT STATE vocabularies; stale orient text; record dates later than the clock; BUILD_INDEX
row shape; readout guard sentences; run-ledger `Harness:` lines; `living-pin?` tests). The PHASE
LOG parser reports what it evaluated, and exits 3 rather than pass vacuously. The human summary
lists each violation and warning; the JSON report (`build-memory-check/2`: input identity, counts,
diagnostics) goes to `--json PATH` or a unique temp file named on the last line. **A failure is
a real block** — the caller does not proceed past it. *Guarded* rules warn unless
`docs/build/README.md` also carries `<!-- build-memory-guards: 1 -->` (BM-COMPAT-06), so legacy
content never fails on them.
**History mode** (`--range`, `--staged`, `--first-parent`; `scripts/check-history.sh`, BM-HIST-01)
judges only the lines a change adds or removes — append-only regions and their append position,
row-annotated DEFERRALS, frozen contracts and ADRs, `*.jsonl` prefixes, the living-archived
ledger head, and the record dates on added lines (R1–R6) — so legacy content never fails it. A
repo guard `docs/build/tools/memory_guard.*` takes over when present; repo policy lives in
`docs/build/tools/record_policy/history.policy`.
`decompose-spec` runs `check` after seeding, `implement-spec` before its close commit (tree,
then `--staged`), `orchestrate-build` at every boundary (tree, then `--range`).
---
## Mode: `init`
Write the layout into a repo. **Idempotent — never overwrites an existing file.** For each
target, if the file is absent, create it from the matching template in [`templates/`](templates/)
(filling any placeholders); if present, leave it untouched.
1. Resolve the root (above). `init` implies committed mode: the target root is
`<repo>/docs/build`.
2. Create, if absent:
- `docs/build/README.md` (from `templates/build-README.md`; **must** contain the marker).
- `docs/build/LEDGER.md` (from `templates/LEDGER.md`; the state-only shape — seed
`projectStatus: NOT_STARTED`, `round: 1`).
- `docs/build/BUILD_INDEX.md` (from `templates/BUILD_INDEX.md`; header row only).
- `docs/build/logs/.gitignore` containing `*` then `!.gitignore` (the one ignored subtree).
- `docs/tickets/{00_MANIFEST.md,_TEMPLATE.md,DEFERRALS.md}` (from `templates/MANIFEST.md`,
`templates/ticket.md`, `templates/DEFERRALS.md`).
- `docs/build/readouts/_TEMPLATE.md` (from `templates/READOUT.md`).
- `docs/adr/{_TEMPLATE.md}` (from `templates/adr-TEMPLATE.md`); then generate
`docs/adr/README.md` with `adr-index` (below).
- `AGENTS.md` "Build memory" section (from `templates/AGENTS-build-memory.md`) — appended
if `AGENTS.md` exists, else the section is offered to `agent-docs`.
- `docs/README.md` — if it exists, **add** the build-memory rows (build/, tickets/, adr/)
with their modes; else create it from `templates/docs-README.md`.
3. Do **not** overwrite tickets, ledgers, ADRs, or a spec that already exist.
4. Run `check` — a fresh `init` must be clean.
`decompose-spec` calls `init` during seeding; the operator may call it directly to adopt the
layout in an existing repo.
---
## Mode: `adr-index`
Regenerate `docs/adr/README.md` from the ADR files (numeric order; columns ADR · Title ·
Ticket · Status; carries the generated marker). Never hand-edit the index.
```bash
bash scripts/adr-index.sh docs/adr # writes docs/adr/README.md
bash scripts/adr-index.sh --check docs/adr # print to stdout only (what the validator diffs)
```
---
## Mode: `migrate`
Move a legacy gitignored scratch dir into the committed `docs/build/` tree. **Mutating** with
`apply=true`; a dry-run plan otherwise. Move/rename only — the contents of every moved run
ledger / PR body / tool / fixture stay byte-identical; the machine ledger is the one file
edited, and only by appending `manifest:` / `memoryRoot:` / `round:` to CURRENT STATE.
```bash
bash scripts/migrate-legacy-scratch.sh --from .agents/scratch # dry-run plan
bash scripts/migrate-legacy-scratch.sh --from .agents/scratch --apply # perform it
```
Mapping (see the script header for the full list): `implement-spec_*.md` → `runs/<ID>.md`
(id from the filename, else the file's H1; unresolvable names keep their basename);
`pr/*`, `tools/*`, `fixtures/*`, `planning/*` → the same-named dirs; `*build-ledger.md` →
`LEDGER.md` (converted); `*.log` → dropped; the rename mapping is appended to
`docs/build/README.md`. After migrating, run `check` and review the diff before committing;
then remove the now-empty legacy dir and add `docs/build/logs/` to `.gitignore` (leave the old
`.agents/` line — it is harmless).
---
## Templates and tests
- [`templates/`](templates/) holds one self-describing template per artifact (each with a
header comment naming who fills it and when):
- **memory root & docs map:** `build-README.md`, `docs-README.md`, `AGENTS-build-memory.md`.
- **machine state & index:** `LEDGER.md`, `BUILD_INDEX.md`.
- **contracts & markers:** `MANIFEST.md`, `ticket.md`, `ticket-skeleton.md`, `HUMAN.md`,
`GATE.md`, `READOUT.md`, `DEFERRALS.md`, `adr-TEMPLATE.md`.
- **upstream (synthesize-spec):** `research-ledger.md`, `research-CONVENTIONS.md`,
`spec-front-matter.md`.
- **closeout CSVs:** `COVERAGE_MATRIX.csv`, `BACKLOG.csv`.
- [`templates/tail/`](templates/tail/) — the tail tickets `decompose-spec` instantiates:
`CAP.1`, `CAP.2`, `CAP.3`, `GATE-ACCEPT`, `REC.1`, `REC.2`, `REC.3`, `DOC.1`, `DOC.2`
(`tail=full`), and `DOC` (the default `tail=minimal`'s single docs row).
- [`tests/`](tests/) holds five fixture repos (`v2-clean`, `v2-violations`, `legacy-scratch`,
`v2-legacy-ledger`, `v2-guards-violations`), `history/build.sh` (throw-away git repos committed
with `GIT_COMMITTER_DATE` in the shapes of real violations) and `run-tests.sh`, which exercises
all five scripts, asserts exit codes and expected files, and golden-checks the templates. Run it
from anywhere:
// turbo
```bash
bash tests/run-tests.sh # one PASS line per fixture; exit 0 iff all pass
```
## Scripts (all bash 3.2+, read-only unless noted)
| Script | Role |
|---|---|
| `scripts/memory-root.sh` | resolve `mode` + `root` for the current worktree |
| `scripts/check-build-memory.sh` | the validator (BM-VALID-01): tree, history and planning modes |
| `scripts/check-history.sh` | history mode (BM-HIST-01) — what a change adds or removes |
| `scripts/adr-index.sh` | regenerate the ADR index (BM-ADR-02) |
| `scripts/migrate-legacy-scratch.sh` | **mutating** with `--apply`: legacy scratch → `docs/build/` |
## What this skill does NOT do
- **No sequencing, no implementation** — it owns the layer; `orchestrate-build` sequences and
`implement-spec` implements.
- **No harness-specific config** — the layout is portable prose + POSIX-ish bash.
- **No deletion of history** — migration moves and renames; it never edits moved contents and
never drops anything but regenerable logs.
Files in this package (110)
- README.md 5 KB
- SKILL.md 11 KB
- layout.md 52 KB
- scripts/adr-index.sh 7 KB
- scripts/check-build-memory.sh 80 KB
- scripts/check-history.sh 48 KB
- scripts/memory-root.sh 3 KB
- scripts/migrate-legacy-scratch.sh 9 KB
- templates/AGENTS-build-memory.md 2 KB
- templates/BACKLOG.csv 1 KB
- templates/BUILD_INDEX.md 1 KB
- templates/COVERAGE_MATRIX.csv 1 KB
- templates/DEFERRALS.md 2 KB
- templates/GATE.md 2 KB
- templates/HUMAN.md 2 KB
- templates/LEDGER.md 5 KB
- templates/MANIFEST.md 5 KB
- templates/READOUT.md 2 KB
- templates/adr-TEMPLATE.md 1 KB
- templates/build-README.md 1 KB
- templates/docs-README.md 2 KB
- templates/research-CONVENTIONS.md 1 KB
- templates/research-ledger.md 3 KB
- templates/spec-front-matter.md 2 KB
- templates/ticket-skeleton.md 1 KB
- templates/ticket.md 3 KB
- templates/tail/CAP.1__capstone-gap-analysis.md 5 KB
- templates/tail/CAP.2__capstone-composed-verification.md 4 KB
- templates/tail/CAP.3__capstone-closure.md 4 KB
- templates/tail/DOC.1__repo-docs-refresh.md 3 KB
- templates/tail/DOC.2__agent-docs-refresh.md 3 KB
- templates/tail/DOC__docs-refresh.md 4 KB
- templates/tail/GATE-ACCEPT.md 3 KB
- templates/tail/REC.1__backlog-and-readiness.md 4 KB
- templates/tail/REC.2__spec-reconciliation.md 4 KB
- templates/tail/REC.3__integration-plan.md 4 KB
- tests/run-tests.sh 49 KB
- tests/history/build.sh 23 KB
- tests/legacy-scratch/.agents/scratch/implement-spec_P19.2.md 1 KB
- tests/legacy-scratch/.agents/scratch/implement-spec_devin-p19-3-composed_20260115.md 1 KB
- tests/legacy-scratch/.agents/scratch/implement-spec_final-notes_20260101.md 1 KB
- tests/legacy-scratch/.agents/scratch/implement-spec_p20-3_20260909.md 1 KB
- tests/legacy-scratch/.agents/scratch/implement-spec_scratchpad.md 1 KB
- tests/legacy-scratch/.agents/scratch/sig-postbuild-build-ledger.md 1 KB
- tests/legacy-scratch/.agents/scratch/logs/run.log 1 KB
- tests/legacy-scratch/.agents/scratch/pr/pr_1.md 1 KB
- tests/legacy-scratch/.agents/scratch/tools/gen.sh 1 KB
- tests/v2-clean/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-clean/docs/adr/README.md 1 KB
- tests/v2-clean/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-clean/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-clean/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-clean/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-clean/docs/tickets/DEFERRALS.md 1 KB
- tests/v2-clean/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-guards-violations/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-guards-violations/docs/adr/README.md 1 KB
- tests/v2-guards-violations/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-guards-violations/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-guards-violations/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-guards-violations/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-guards-violations/docs/tickets/DEFERRALS.md 1 KB
- tests/v2-guards-violations/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-legacy-ledger/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-legacy-ledger/docs/adr/README.md 1 KB
- tests/v2-legacy-ledger/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-legacy-ledger/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-legacy-ledger/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-legacy-ledger/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-legacy-ledger/docs/tickets/DEFERRALS.md 1 KB
- tests/v2-legacy-ledger/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-positional-status/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-positional-status/docs/adr/README.md 1 KB
- tests/v2-positional-status/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-positional-status/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-positional-status/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-positional-status/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-positional-status/docs/tickets/DEFERRALS.md 2 KB
- tests/v2-positional-status/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-reqcov/docs/spec.md 1 KB
- tests/v2-reqcov/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-reqcov/docs/adr/README.md 1 KB
- tests/v2-reqcov/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-reqcov/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-reqcov/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-reqcov/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-reqcov/docs/tickets/03_T3__state-and-lists.md 1 KB
- tests/v2-reqcov/docs/tickets/04_T4__engine-and-hypotheses.md 1 KB
- tests/v2-reqcov/docs/tickets/DEFERRALS.md 1 KB
- tests/v2-reqcov/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-vacuous/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-vacuous/docs/adr/README.md 1 KB
- tests/v2-vacuous/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-vacuous/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-vacuous/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-vacuous/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-vacuous/docs/tickets/DEFERRALS.md 1 KB
- tests/v2-vacuous/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-violations/docs/adr/ADR-001-seed-schema-shape.md 1 KB
- tests/v2-violations/docs/adr/ADR-002-hasty-decision.md 1 KB
- tests/v2-violations/docs/adr/README.md 1 KB
- tests/v2-violations/docs/adr/_TEMPLATE.md 1 KB
- tests/v2-violations/docs/tickets/00_MANIFEST.md 2 KB
- tests/v2-violations/docs/tickets/01_T1__seed-schema.md 1 KB
- tests/v2-violations/docs/tickets/02_T2__extra.md 1 KB
- tests/v2-violations/docs/tickets/02_T2__wire-consumers.md 1 KB
- tests/v2-violations/docs/tickets/03_T5__skeleton.md 1 KB
- tests/v2-violations/docs/tickets/DEFERRALS.md 1 KB
- tests/v2-violations/docs/tickets/_TEMPLATE.md 1 KB
- tests/v2-violations/docs/tickets/bad_name.md 1 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · stevevitali/agent-skills | 100 | MIT |
| Aicoo-Team/AICOO-Skills | 100 | MIT |
Database snapshot: 13.11.2026 · package version 9d2810a083dd (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 86adr
Record an architecture decision as a short ADR in docs/adr and index it in docs/ARCHITECTURE.md. Use when a significant technical choice is made (state management, module boundaries, persistence, audio pipeline, a new shared pattern) or when the user asks to record or document a decision. - 100adr-create
Use when capturing an architectural decision — file naming, next ADR number, Status / Context / Decision / Consequences, index regen; fires even without saying 'ADR'. - 100adr
Create, review, and manage Architecture Decision Records (ADRs) with auto-numbering, template detection, quality review, and index maintenance. Use when user mentions "ADR", "architecture decision", "document this decision", "create ADR", "review ADR", editing ADR files… - 100adr-writer
Create short Architecture Decision Records under docs/adr. Use when the user makes a repo-level decision, changes skill format, publishing, validation, license, layout, or maintainer policy, and wants a concise ADR without documentation bloat. - 100docs-adr
Create a numbered Architecture Decision Record (ADR) documenting a technical decision with context, alternatives, and consequences. Trigger on "create an ADR", "document this architectural decision", "record why we chose X", or "write an ADR for [decision]". Not for a decision… - 100adr
Read and write Architecture Decision Records in docs/adr/. Use for /adr, when decisions are made, and before changing areas covered by ADRs.