Skip to content

Instructions Sync Workflow

Overview

This document explains how instruction files stay aligned with review-skill category-*.md references, which files the sync script manages, and how to validate changes before release.

For distributable-package authoring rules (repository-neutral content, edit targets, test pairing), see companion rules (stem instructions, agent-skills) and Edit routing.

Boundary: .apm/packages/** sources are distribution artifacts — do not add this-repository-specific paths, sync workflows, or consumer layout mandates to instructions or skill references/. See APM Package Design — Distributable vs maintainer-only and .apm/CLAUDE.md § Distributable vs maintainer-only.

Scope

Applies to:

  • Instruction files under .apm/packages/*/.apm/instructions/*.instructions.md
  • Review references under .apm/packages/*/.apm/skills/*-review/references/
  • Sync script: scripts/self/apm/sync_guidelines_from_categories.pl

Instruction File Structure

Every *.instructions.md file uses the same five H2 chapters in this order:

  1. ## Scope
  2. ## Standards
  3. ## Guidelines
  4. ## Testing and Validation
  5. ## Security Guidelines

Additional rules:

  • Synced ## Guidelines are thin: ItemID + (LEVEL) + title only. Do not expect Check: / Why / Fix child bullets in always-on instructions.
  • Keep full Check: / Why / Fix criteria in *-review category-*.md (review skills load those on demand).
  • Keep ### Code Modification Guidelines at the end of ## Guidelines.
  • Use H3 headings without numeric prefixes or trailing level markers (for example, ### Architecture (ARCH), not ### 6. Architecture (ARCH) (MUST)).
  • Individual rule bullets retain (MUST), (SHOULD), or (CAN) (for example, - ARCH-01 (SHOULD): ...).
  • Do not emit empty H3 sections in generated Guidelines.
  • In instructions.instructions.md, avoid duplicating TEST/SEC review criteria outside ## Guidelines.
  • Standards vs Guidelines: For instruction files in the sync map, checklist ItemID titles live in ## Guidelines (synced from *-review categories). ## Standards holds only non-duplicative authoring detail — naming/distribution tables, path maps, templates, and detail not captured by those ItemIDs (STD-05). Do not repeat synced rule IDs in Standards.

Source of Truth and Sync Direction

The sync direction is:

  1. category-*.md → normalize **ID (LEVEL): Title** format.
  2. common-checklist.md → regenerate from category headers and rule lines.
  3. Mapped *.instructions.md → replace the entire ## Guidelines block from parsed categories.

## Guidelines is the review-criteria hub. ## Testing and Validation and ## Security Guidelines remain manually maintained operational chapters.

## Testing and Validation should stay short:

  • Optional one-line on-demand skill pointer (for example On-demand validation: see go-validation skill SKILL.md.)
  • Optional notes for checks automation does not cover (tests, coverage, suite pairing, judgment review)
  • Do not embed always-run validate.sh / linter recipes
  • Do not add "Agent hooks/pre-commit handle X, so do not run Y" explanations

Skill-to-Instruction Map

The sync script updates only these pairs:

Review skill Instruction file
agent-skills-review .apm/packages/common/.apm/instructions/agent-skills.instructions.md
github-actions-review .apm/packages/github-actions/.apm/instructions/github-actions-workflow.instructions.md
instructions-review .apm/packages/common/.apm/instructions/instructions.instructions.md
go-review .apm/packages/go/.apm/instructions/go.instructions.md
shell-script-review .apm/packages/shell-script/.apm/instructions/shell-script.instructions.md
terraform-review .apm/packages/terraform/.apm/instructions/terraform.instructions.md

Files Outside Sync

These instruction files are not regenerated by the sync script. Edit them directly and run the re-evaluation checks:

File Reason
.apm/packages/common/.apm/instructions/markdown.instructions.md No *-review category source in the sync map
.apm/packages/shell-script/.apm/instructions/bats.instructions.md Bats-specific companion to stem shell-script; distributable conventions. Source filename differs from Cursor (.cursor/rules/bats.mdc) / Claude (.claude/rules/bats.md). Use applyTo that includes **/*.sh so suite pairing rules load when editing scripts.

When changing distributable instructions, keep content repository-neutral (no consumer-project paths, package names, or helper APIs). Cross-link to companion Shell Script rules (stem shell-script) for production-code rules instead of duplicating them. In agent-facing text, avoid bare *.instructions.md filenames — APM distributes different basenames per target (see G-03/G-04/G-05 in instructions.instructions.md).

Script Behavior

Path: scripts/self/apm/sync_guidelines_from_categories.pl

Main behavior:

  1. Removes numeric prefixes from category H2 headers (for example, ## 10. Architecture (ARCH) → ## Architecture (ARCH)).
  2. Normalizes category rule titles to **ID (LEVEL): Title**.
  3. Regenerates common-checklist.md entries from category sections.
  4. Regenerates ## Guidelines with:
    • H3 section headers that keep category IDs but drop heading-level markers
    • Rule bullets with (LEVEL) and titles only (no Check: children — keeps always-on instructions thin)
  5. Appends ### Code Modification Guidelines from %code_mod_guidelines in the script.
  6. Skips empty sections during generation.

Check: / Why / Fix remain in category-*.md for review skills; they are not copied into instructions.

Code Modification Guidelines Defaults

Operational bullets under ### Code Modification Guidelines live in scripts/self/apm/sync_guidelines_from_categories.pl (%code_mod_guidelines). Update that hash when adding cross-cutting authoring rules (for example, “add tests in the same change”). Do not put always-run lint/validate.sh mandates there — those belong in Agent hooks and on-demand validation skills.

Current defaults (domain-only):

Skill Extra guideline bullet
agent-skills-review Deterministic checks in skill scripts/; judgment in the review skill workflow
github-actions-review Keep map keys alphabetically ordered per ORD-01 in companion github-actions-workflow rules (stem github-actions-workflow)
shell-script-review Add or update matching Bats suites under test/bats/ when shell scripts change; follow companion Bats rules (stem bats)
go-review Add or update *_test.go files when behavior changes
instructions-review Precise applyTo, stem-based cross-links; no always-run lint recipes or hook-skip explanations
terraform-review Keep resource/module/data/local argument keys alphabetically ordered (ORD-01)

Corresponding review criteria belong in category-testing.md as TEST-00 (MUST) (or equivalent) so Guidelines and checklist stay aligned.

Changing Review Criteria

  1. Edit the relevant category-*.md under .apm/packages/<package>/.apm/skills/<skill>-review/references/.
  2. If Code Modification Guidelines need changes, update %code_mod_guidelines in scripts/self/apm/sync_guidelines_from_categories.pl.
  3. Run scripts/self/apm/sync_guidelines_from_categories.pl (skills → instructions Guidelines).
  4. If the rule is operational and not covered by automation (coverage targets, suite verification notes, on-demand skill pointer), update ## Testing and Validation in the instruction file manually.
  5. If the rule is Bats-specific and not shell authoring, update bats.instructions.md manually.
  6. Run the re-evaluation commands below.

Important: The sync script replaces the full ## Guidelines … ## Testing and Validation region. Subsections such as ### Anti-Patterns are removed unless they come from a category-*.md file. Use category-anti-patterns.md (or another category file) for anti-pattern rules.

How To Run

scripts/self/apm/sync_guidelines_from_categories.pl

Required Re-Evaluation After Instruction Changes

Whenever any *.instructions.md file changes, run a re-evaluation pass.

# 1) Ensure chapter order and 5 H2 chapters
for f in .apm/packages/*/.apm/instructions/*.instructions.md; do
  awk 'BEGIN{s=0;st=0;g=0;t=0;sec=0} /^## Scope$/{s=NR} /^## Standards$/{st=NR} /^## Guidelines$/{g=NR} /^## Testing and Validation$/{t=NR} /^## Security Guidelines$/{sec=NR} END{print FILENAME, (s<st && st<g && g<t && t<sec)?"OK":"NG"}' "$f"
done

# 2) Ensure no numbered Guidelines H3
grep -nE '^### [0-9]+\.' .apm/packages/*/.apm/instructions/*.instructions.md || true

# 3) Ensure Code Modification Guidelines exists in each file
for f in .apm/packages/*/.apm/instructions/*.instructions.md; do
  grep -q '^### Code Modification Guidelines' "$f" || echo "Missing: $f"
done

# 4) Ensure synced Guidelines stay thin (no Check: children under ## Guidelines)
for f in .apm/packages/*/.apm/instructions/*.instructions.md; do
  awk '/^## Guidelines$/{g=1;next} /^## /{g=0} g && /^Check:/{print FILENAME":"$0}' "$f"
done

After package instruction changes in this repository, also run:

apm install --update
apm audit --ci

Decisions Captured

  1. Keep always-on ## Guidelines thin (ItemID + title); keep Check: / Why / Fix in category-*.md for review skills.
  2. Keep operational content in ## Testing and Validation and ## Security Guidelines, but keep Testing concise (skill pointer + non-automated notes only).
  3. In instructions.instructions.md, avoid duplicating TEST/SEC review criteria outside ## Guidelines.
  4. Pair production changes with tests in the same change (TEST-00 (MUST) in go-review and shell-script-review; Bats details in companion Bats rules, stem bats).
  5. Keep distributable instruction content repository-neutral; consumer-specific helpers belong in the consuming repository's docs or test support, not in APM package instructions.
  6. Always-run lint belongs in Agent hooks/pre-commit; on-demand recipes belong in validation skills — not in always-on instructions or %code_mod_guidelines.

Troubleshooting

If structure looks broken after sync:

  1. Verify category files contain valid section headers (## ...) and rule titles (**ID (LEVEL): Title**).
  2. Re-run the sync script.
  3. Re-run the re-evaluation commands above.
  4. If a manual subsection disappeared from ## Guidelines, move it into a category-*.md file or out of the synced region.
  5. If needed, inspect generated Guidelines boundaries between ## Guidelines and ## Testing and Validation.