ai-procedure-maintenance
Ensure the AI coding procedure ecosystem stays current and consistent when new elements are introduced. This skill provides a checklist-driven approach to propagating updates across all affected files
SKILL.md.claude/skills/ai-procedure-maintenance
GitHubai-procedure-maintenance
Last Reviewed: 2026-05-16 Reviewed By: ai-procedure-quality-r1 (Phase 2b Wave 2b-A) Exemplar rationale: This skill produces no artifact — it's a propagation checklist. The canonical "use" is "an ADR was added and every cross-reference is now consistent" — verifiable by
Find-SkillReferenceDrift.ps1(Phase 4a F-15.4) once it exists.
Purpose
Ensure the AI coding procedure ecosystem stays current and consistent when new elements are introduced. This skill provides a checklist-driven approach to propagating updates across all affected files.
Problem Solved: Without this procedure, adding a new ADR might update docs/adr/ but miss .claude/adr/, constraints, patterns, skill mappings, INDEX files, and root CLAUDE.md references.
When to Use
Invoke this skill when:
- Creating a new ADR
- Adding a new constraint file
- Creating a new pattern file
- Adding a new protocol (AIP)
- Creating or significantly modifying a skill
- Updating root CLAUDE.md with new procedures
- Discovering that existing files have inconsistent references
Trigger Phrases:
- "update AI procedures for new ADR"
- "add new pattern to the system"
- "maintain AI coding procedures"
- "propagate ADR changes"
Maintenance Checklists by Element Type
Checklist A: New ADR
When creating a new Architecture Decision Record:
□ 1. CREATE full ADR
Location: docs/adr/ADR-{NNN}-{slug}.md
Follow template in docs/adr/
□ 2. CREATE concise ADR (AI-optimized version)
Location: .claude/adr/ADR-{NNN}-{slug}.md
Target: 100-150 lines
Focus: MUST/MUST NOT rules, key rules
Remove: Historical context, alternatives considered (keep in full version)
□ 3. UPDATE ADR indexes
- docs/adr/INDEX.md - Add row to ADR table
- .claude/adr/INDEX.md - Add row to concise ADR table
□ 4. UPDATE relevant constraint file
Location: .claude/constraints/{domain}.md
Action: Add constraint rules derived from ADR
Domain mapping:
- API/endpoints → api.md
- PCF/frontend → pcf.md
- Plugins → plugins.md
- Auth → auth.md
- Caching → data.md
- AI features → ai.md
- Background jobs → jobs.md
- Testing → testing.md
□ 5. UPDATE constraint INDEX
Location: .claude/constraints/INDEX.md
Action: Update line count, add ADR reference if new file created
□ 6. CREATE pattern file (if ADR introduces code patterns)
Location: .claude/patterns/{domain}/{pattern-name}.md
Content: Pointer format — When/Read/Constraints/Key Rules (~25 lines, no inline code)
□ 7. UPDATE pattern INDEX
Location: .claude/patterns/{domain}/INDEX.md
Action: Add new pattern to table
□ 8. UPDATE skill mappings (CRITICAL)
Files to update:
- .claude/skills/adr-aware/SKILL.md
→ Rule 1 table: Add resource type → ADR mapping
→ Resource Type to Context Files Mapping table
- .claude/skills/task-execute/SKILL.md
→ Step 4a: Tag → constraint mapping
→ Step 4b: Tag → pattern mapping
→ Step 5: ADR loading section
- .claude/skills/task-create/SKILL.md
→ Step 3.4: Tag-to-Knowledge Mapping table
→ Step 3.5: ADR mapping section
□ 9. UPDATE .claude/adr/INDEX.md (NOT root CLAUDE.md — it has no ADR table)
Add a root CLAUDE.md §17 trigger ONLY if agents must read the ADR before a specific
action they would not otherwise connect to it — one line, as short as it can be while keeping any 🔒 guard
(aim for ~200 chars; see Checklist F).
□ 10. UPDATE CROSS-REFERENCE-MAP.md
Location: /CROSS-REFERENCE-MAP.md
Action: Add entries showing ADR → files relationship
□ 11. VERIFY consistency
Run: grep for ADR number across all .claude/ and CLAUDE.md files
Ensure: All references use correct paths
□ 12. ENFORCE each MUST / MUST NOT (Checklist G)
For every rule the ADR adds, record "Enforced by: <type | lint rule | ArchTest | hook |
permission | prose — reason>" in the concise ADR. Build the mechanism in the same change
when it is cheap; otherwise file it.
Checklist B: New Constraint File
When creating a new constraint file for a domain:
□ 1. CREATE constraint file
Location: .claude/constraints/{domain}.md
Structure:
- Purpose section
- MUST rules (positive constraints)
- MUST NOT rules (negative constraints)
- Quick reference table
- ADR references
□ 2. UPDATE constraint INDEX
Location: .claude/constraints/INDEX.md
Add: New row with file, ADRs covered, line count
□ 3. CREATE corresponding pattern directory
Location: .claude/patterns/{domain}/
Add: INDEX.md listing available patterns
□ 4. UPDATE skill mappings
- .claude/skills/adr-aware/SKILL.md → Rule 2, Resource Type table
- .claude/skills/task-execute/SKILL.md → Step 4a table
- .claude/skills/task-create/SKILL.md → Step 3.4 table
□ 5. ADD standard tag for domain
Location: .claude/skills/INDEX.md (Standard Tag Vocabulary)
Location: .claude/TAGGING-EXAMPLES.md (if applicable)
□ 6. VERIFY pattern INDEX exists
Location: .claude/patterns/INDEX.md
Add: New domain pattern directory reference
Checklist C: New Pattern File
When adding a code pattern:
□ 1. CREATE pattern file
Location: .claude/patterns/{domain}/{pattern-name}.md
Content:
- Brief description
- When to use
- Read: pointers to canonical source files
- ADR references
- Related patterns
□ 2. UPDATE domain pattern INDEX
Location: .claude/patterns/{domain}/INDEX.md
Add: New row with pattern name, purpose, ADR refs
□ 3. UPDATE root pattern INDEX
Location: .claude/patterns/INDEX.md
Verify: Domain directory is listed
□ 4. UPDATE skill mappings (if pattern should be auto-loaded)
- .claude/skills/adr-aware/SKILL.md → Rule 2c pattern loading
- .claude/skills/task-execute/SKILL.md → Step 4b table
- .claude/skills/task-create/SKILL.md → Step 3.4 Patterns column
□ 5. ADD to CROSS-REFERENCE-MAP.md
Location: /CROSS-REFERENCE-MAP.md
Add: Pattern file with ADR relationships
Checklist D: AI Execution Rules (protocols retired 2026-07-08)
The .claude/protocols/AIP-00x layer was removed 2026-07-08. It duplicated the executable skills, was dropped from root CLAUDE.md in the 2026-05-17 rewrite, and had drifted (stale context thresholds). Do not recreate a standalone protocols/ layer. Execution/behavioral rules now live in exactly two load-bearing surfaces:
□ Behavioral RULE the agent must apply every turn (escalation triggers, task-execution
routing, review limits) → root /CLAUDE.md (the always-loaded layer)
□ RULE that applies only when editing certain files → .claude/rules/{name}.md with
`paths:` frontmatter (loads when Claude reads/edits a matching file). Example: bff-hygiene.md.
□ Procedural HOW-TO the agent runs on demand (task-create, task-execute, code-review, adr-check)
→ the relevant .claude/skills/{name}/SKILL.md
When in doubt, follow the maintainer notes at the top of root CLAUDE.md (§18): binding
every-turn rule → CLAUDE.md; path-specific rule → .claude/rules/; reference/tutorial/procedure
→ skill or docs/. There is no "protocol" home.
Checklist E: New Skill
When creating a new skill:
□ 1. CREATE skill directory and files
Location: .claude/skills/{skill-name}/
Files:
- SKILL.md (required)
- references/ (optional)
- scripts/ (optional)
- assets/ (optional)
□ 2. ADD YAML frontmatter to SKILL.md
Required fields:
- description: Brief phrase (5-10 words)
- tags: [tag1, tag2, ...]
- techStack: [tech1, tech2, ...]
- appliesTo: [patterns or scenarios]
- alwaysApply: true/false
□ 3. UPDATE skills INDEX
Location: .claude/skills/INDEX.md
Add: Row to Available Skills table
Add: Entry in appropriate category section
Update: Skill Flow diagram if orchestrator/component
□ 4. UPDATE SKILL-INTERACTION-GUIDE.md (if skill changes workflow)
Location: .claude/skills/SKILL-INTERACTION-GUIDE.md
Add: Skill to interaction matrix
Update: Workflow diagrams if needed
□ 5. TRIGGER PHRASES go in the skill's own frontmatter (`description`, `appliesTo`) and in
.claude/skills/INDEX.md — NOT root CLAUDE.md (it has no skills, trigger or slash-command
tables; Claude Code lists skills from their frontmatter).
□ 6. Add a root CLAUDE.md §17 trigger only if the skill MUST run before an action an agent
would not otherwise connect to it (one line, see Checklist F)
□ 7. VERIFY tags use standard vocabulary
Reference: .claude/skills/INDEX.md → Standard Tag Vocabulary
Reference: .claude/TAGGING-EXAMPLES.md
Checklist F: Update Root CLAUDE.md
When modifying the main instruction file:
□ 1. IDENTIFY all places that might need parallel updates
- .claude/skills/INDEX.md (if skill-related)
- .claude/skills/SKILL-INTERACTION-GUIDE.md (if workflow)
- docs/CLAUDE.md (if documentation-related)
- Project-specific CLAUDE.md files
□ 2. VERIFY path references are correct
- Use .claude/adr/ for concise ADRs
- Use docs/adr/ for full ADRs
- NOTE: .claude/protocols/ was retired 2026-07-08 — execution rules live in root CLAUDE.md + skills
□ 3. UPDATE "Last Updated" dates
All affected files should have current date
□ 4. RESPECT the budget and placement rules in the maintainer notes (HTML comment at the
top of root CLAUDE.md): < 200 lines and ≤ 30 KB; one-line §17 triggers; no findings,
history or aging numbers; never renumber sections. Path-specific rules go to
.claude/rules/; the full doc catalogue is docs/INDEX.md.
□ 5. STATE the byte delta in the .claude/CHANGELOG.md entry, and run /doctor prompt-audit
(Claude Code ≥ 2.1.283) after the change.
□ 6. RUN consistency check
Grep for old paths that might have been left behind, and run
pwsh -File scripts/quality/Test-InstructionPaths.ps1 (every path named in an instruction
file must exist; it also runs in CI Tier 2)
Checklist G: New rule, lesson or guard (the enforcement ladder — root CLAUDE.md §16)
When an ADR, constraint, FAILURE-MODES entry, code-review finding, project directive, or a bug fix whose cause is a repeatable pattern (task-execute Step 9.5 rule 6) creates a rule agents must follow:
□ 1. PICK the strongest mechanism that works, in this order:
a. TYPE the compiler checks — make the misuse unrepresentable (e.g. a return type that
cannot be non-OK, a branded id type, a required parameter)
b. LINT rule — ESLint / Roslyn analyzer / PSScriptAnalyzer. scripts/quality/post-edit-lint.sh
returns findings to the agent after each Edit/Write (additionalContext; best-effort within
its 4 s linter timeout) and CI runs the linters too
c. ARCHTEST / source-scan guard — tests/Spaarke.ArchTests/** (e.g. CredentialGuardTests,
ProblemDetailsContentTypeGuardTests — in flight, PR #1427). Runs in CI, and in the Stop-hook
quality gate when .cs files changed
d. HOOK or PERMISSION rule — .claude/settings.json (PreToolUse/PostToolUse hook; `ask` rule).
Only for narrow, fast (< 5 s), zero-false-positive checks; `ask` over `deny` for policies
that change over time
e. PROSE — only with a one-line reason a–d cannot express it
Pick what fits in this change. If the strongest mechanism is more than a small addition, write
"Enforced by: prose — <mechanism> planned, #<issue>" and file it; never hold the change for a guard.
□ 2. RECORD it with the rule: "Enforced by: <mechanism, file>". The prose then shrinks to a
pointer ("if X fires, read Y") instead of restating the rule.
□ 3. PROVE the guard: a must-fire control (a seeded violation it catches) and a must-not-fire
control (the sanctioned shape it accepts). A guard nobody has seen fail may never fire —
the instruction-path check silently skipped every src/ path until its must-fire test ran.
If a control cannot be seeded in the same change, say so in the Enforced-by line rather than
skipping the guard.
□ 4. RATCHET when it finds existing violations: record them in a baseline file; new violations
fail, known ones are reported and worked down (pattern: scripts/quality/Test-InstructionPaths.ps1
+ instruction-paths.baseline.txt). Never block every project on day one.
□ 5. FIX THE CLASS: search for other instances of the pattern that created the rule
(task-execute Step 9.5 rule 6) — fix, guard or list them.
Examples in this repo: secret-bearing credentials → CredentialGuardTests (ArchTest); BFF error
content type → ProblemDetailsContentTypeGuardTests (ArchTest, in flight: PR #1427); dead instruction paths →
Test-InstructionPaths.ps1 (CI, ratcheted); shared git stash → ask permission rule;
authenticatedFetch throws → isApiError/problemOf helpers (in flight: PR #1451), an OkResponse return type planned.
Cross-Reference Verification
After completing any checklist, run these verification steps:
1. PATH CONSISTENCY CHECK
Search for old/wrong paths:
- "docs/reference/adr" → Should be ".claude/adr/" or "docs/adr/"
- ".claude/protocols/" or "AIP-00" → RETIRED 2026-07-08; point to root CLAUDE.md + skills instead
2. INDEX COMPLETENESS CHECK
Verify each INDEX.md includes all files in directory:
- .claude/adr/INDEX.md vs actual ADR files
- .claude/constraints/INDEX.md vs actual constraint files
- .claude/patterns/*/INDEX.md vs actual pattern files
- .claude/skills/INDEX.md vs actual skill directories
3. MAPPING CONSISTENCY CHECK
Verify skill mappings are consistent:
- adr-aware Rule 1 table matches task-execute Step 4a
- adr-aware Resource Type table matches task-create Step 3.4
- All constraint files are referenced in at least one skill
4. DATE CONSISTENCY CHECK
All modified files should have "Last Updated" matching today's date
Quick Reference: File Locations
| Element Type | Primary Location | Index File | Skills to Update |
|---|---|---|---|
| ADR (Full) | docs/adr/ |
docs/adr/INDEX.md |
— |
| ADR (Concise) | .claude/adr/ |
.claude/adr/INDEX.md |
adr-aware, task-execute, task-create |
| Constraint | .claude/constraints/ |
.claude/constraints/INDEX.md |
adr-aware, task-execute, task-create |
| Pattern | .claude/patterns/{domain}/ |
.claude/patterns/{domain}/INDEX.md |
adr-aware, task-execute, task-create |
| Skill | .claude/skills/{name}/ |
.claude/skills/INDEX.md |
SKILL-INTERACTION-GUIDE, root CLAUDE.md |
Example: Adding ADR-023
Scenario: Adding a new ADR for "API Rate Limiting"
Step 1: Create docs/adr/ADR-023-api-rate-limiting.md (full version)
Step 2: Create .claude/adr/ADR-023-api-rate-limiting.md (concise, ~120 lines)
Step 3: Add to docs/adr/INDEX.md and .claude/adr/INDEX.md
Step 4: Add rules to .claude/constraints/api.md:
- "MUST implement rate limiting on public endpoints"
- "MUST use sliding window algorithm"
Step 5: Update .claude/constraints/INDEX.md (update api.md line count)
Step 6: Create .claude/patterns/api/rate-limiting.md in pointer format (When/Read/Constraints/Key Rules)
Step 7: Add to .claude/patterns/api/INDEX.md
Step 8: Update skill mappings:
- adr-aware: Add "Rate Limiting" → ADR-023 to Rule 1
- task-execute: Add rate-limiting pattern to Step 4b
- task-create: Add to Step 3.4 api row
Step 9: Add a root CLAUDE.md §17 trigger only if agents must read it before a specific action (Checklist A9) — root has no ADR table
Step 10: Add to CROSS-REFERENCE-MAP.md
Step 11: Grep verify: Search "ADR-023" appears consistently
Automation Opportunity
Future Enhancement: Create a script that:
- Scans all INDEX.md files for completeness
- Checks path references for correctness
- Validates skill mapping consistency
- Reports missing cross-references
Location: scripts/Validate-AIProcedures.ps1 (to be created)
Related Skills
- adr-aware: Consumes ADR mappings this skill maintains
- task-execute: Uses constraint/pattern mappings
- task-create: Uses knowledge mapping tables
- repo-cleanup: Can validate procedure file structure
Failure Modes & Recovery
| Failure | Cause | Prevention / Recovery |
|---|---|---|
New ADR added but only docs/adr/ updated — .claude/adr/, adr-aware mapping, constraints/ all missed |
Author skipped the checklist; ran only manual ADR creation | Always invoke /ai-procedure-maintenance after any ADR/skill/pattern/constraint addition. Future state: pre-commit hook will flag this automatically once Find-SkillReferenceDrift.ps1 (F-15.4) ships. |
| Skill rename propagates everywhere except inline mentions in OTHER SKILL.md bodies | Cross-skill references in prose aren't caught by tooling that scans only registry files | After rename, grep -rn "<old-name>" .claude/ catches inline mentions. The Phase 4a validators will mechanize this. |
| CLAUDE.md trigger map drifts after skill addition — trigger phrases exist for non-existent skill | New skill added but root CLAUDE.md trigger map not updated | Checklist E (this skill, "Add new skill") explicitly mandates root CLAUDE.md update. If skipped, Find-SkillReferenceDrift.ps1 will catch it. |
| Multiple cross-reference surfaces give different answers about a skill's existence | Surface-by-surface manual maintenance drifts | Treat notes/inventory/skill-cross-refs.json (Phase 0 task 006) as authoritative; rebuild it when in doubt. |
Last updated 2026-05-16 by ai-procedure-quality-r1 Phase 2b Wave 2b-A. Replaces "December 25, 2025" stamp.