arch-sync

name	arch-sync
description	Use after any ADR status change or new ADR creation to regenerate the machine-readable architecture constraints document from all ADRs.
allowed-tools	Read, Write, Edit, Bash, Glob, Grep

Architecture Sync

Regenerate the machine-readable architecture constraints document from all ADRs. This is the bridge between ADRs (WHY decisions were made) and other agents that need to enforce those decisions (standards-check, dev-plan, arch-validate).

Argument (optional): --dry-run to preview changes without writing.

---

Step 1 — Read the ADR index

Read docs/adr/README.md. Parse the index table to extract every ADR file path and its Status column.

Expected table format:

| [ADR-NNN](ADR-NNN-kebab-title.md) | Title | Status |

Note: some entries may have Superseded by ADR-NNN in the Status column.

---

Step 2 — Read all ADR files

Read every ADR file listed in the index. For each ADR, extract:

1. Status — from the metadata table (Accepted, Proposed, Deprecated, Superseded by ADR-NNN)
2. Decision summary — the first paragraph or key rule bullets from the Decision section. Capture the essence in one sentence. Do NOT copy implementation details, struct layouts, or enum tables.
3. Constraints — every item under the **Constrained:** subheading in the Consequences section. Capture verbatim or in tight paraphrase.
4. Title — from the # ADR-NNN — Title heading.
5. See also — links to architecture docs and related ADRs.

If an ADR has **Status** = Superseded by ADR-NNN, extract only the title and which ADR superseded it.

---

Step 3 — Classify

Sort ADRs into three buckets:

Bucket	Status values
Active	Accepted
Proposed	Proposed
Superseded	Superseded by ADR-NNN, Deprecated

Proposed ADRs are documented but their constraints are NOT binding. Mark them in the output clearly.

---

Step 4 — Generate the constraints file

Write docs/architecture/architecture-constraints.md with this exact structure:

# Architecture Constraints

> Auto-generated by arch-sync from N ADRs on YYYY-MM-DD.
> Do not edit manually. Run /arch-sync to regenerate.

## Active Constraints (N ADRs accepted)

| ADR | Decision | Implementation Constraints |
|---|---|---|
| [ADR-NNN](../adr/ADR-NNN-title.md) | One-sentence decision summary. | • Constraint 1 (from Consequences/Constrained) • Constraint 2 |

### Constraint reference (by topic)

Group constraints by architectural concern for easy lookup by other agents:

- **zbus / IPC:** ADR-002 — ...
- **Data model:** ADR-003 — ...
- **Sensor architecture:** ADR-004, ADR-005 — ...
- **App composition:** ADR-008 — ...
- ... (add groups as ADRs warrant)

## Proposed Decisions (N ADRs proposed)

| ADR | Title | Status |
|---|---|---|
| [ADR-NNN](../adr/ADR-NNN-title.md) | Title | Proposed |

## Superseded Decisions

| ADR | Superseded by | Title |
|---|---|---|
| [ADR-NNN](../adr/ADR-NNN-title.md) | ADR-NNN | Title |

Rules for content:

• Decision summary: one sentence, no struct layouts, no code. Reference the architecture doc for details.
• Constraints: bullet list. Each constraint must be concrete and checkable (e.g. "no heap pointers" not "be careful with memory").
• Topic groups: use the categories from ADR-001 through ADR-016 as they exist. Don't invent categories.
• The Constraint reference by topic section is for human navigation. Group ADRs that share a concern domain into named categories. An ADR can appear in multiple categories. Example categories: zbus/IPC, Data model, Sensor architecture, App composition, Testing, Connectivity, CI/Dev, Display, Security/FOTA.

---

Step 5 — Validate the output

Count the ADRs in the generated file. The total must equal the number of ADRs found in the index. If the counts differ, re-read the ADRs and find the discrepancy.

Check that every ADR referenced in the "Constraint reference by topic" section has a corresponding row in the "Active Constraints" table.

---

Step 6 — Update the architecture index

Edit docs/architecture/README.md. Add a row to the index table:

| [architecture-constraints.md](architecture-constraints.md) | Auto-generated constraint summary from all ADRs |

Insert it as the first row (table position 1) so agents find it first.

If the row already exists, leave it in place — the content is auto-generated so the index entry never changes.

---

Step 7 — Summary

Print a one-line report:

• Number of ADRs read
• Active constraints extracted
• Proposed ADRs listed (not binding)
• Superseded ADRs listed
• File written: docs/architecture/architecture-constraints.md

If --dry-run: display the generated content in chat. Do not write files. Do not ask for confirmation — the dry run IS the preview.

---

Red Flags — STOP and re-check

Feeling	Reality
"The index hasn't changed, skip it"	New ADRs change the constraint landscape. Always regenerate.
"I remember what ADR-003 says"	Re-read it. ADRs may have been updated.

Rules

• Never modify any ADR file — this skill is read-only on docs/adr/.
• Only write docs/architecture/architecture-constraints.md and edit docs/architecture/README.md.
• If an ADR has no Constrained items in Consequences (empty or only Easier/Harder), write "No explicit constraints" in the table. This is valid — some ADRs are enabling decisions, not constraining ones.
• The "Constrained" extraction is mechanical — copy the bullets verbatim. Do not interpret or expand them.
• After running this skill, other skills (standards-check, explore-adrs) can read the generated constraints file for up-to-date ADR information.

Terminal state: docs/architecture/architecture-constraints.md regenerated, docs/architecture/README.md updated, counts validated.