Skip to content
Skills Library
Programming · Automation

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.

Licence
MIT
Last repository change
14.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
110
Scripts
8
HTML comments
2
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 14.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 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

  1. Resolve the root first (every mode)
  2. Mode: check (default)
  3. Mode: init
  4. Mode: adr-index
  5. Mode: migrate
  6. Templates and tests
  7. Scripts (all bash 3.2+, read-only unless noted)
  8. What this skill does NOT do
Original SKILL.md headings · 182 lines, 1,266 words
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

RepositoryScoreLicence
This page · stevevitali/agent-skills100MIT
Aicoo-Team/AICOO-Skills100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.