AI Procedure Maintenance

ai-procedure-maintenance

---

description: Maintain and update AI coding procedures when new elements are added tags: [maintenance, adr, constraints, patterns, protocols, skills] techStack: [all] appliesTo: ["new ADR", "new pattern", "new constraint", "new skill", "procedure update"] alwaysApply: false

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, code examples
   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: Copy-paste-ready code examples

□ 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 root CLAUDE.md (if ADR adds critical constraint)
   Location: /​CLAUDE.md
   Section: "Architecture Decision Records (ADRs)" table
   Action: Add summary row for high-impact ADRs

□ 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

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
   - Code example (copy-paste ready)
   - 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: New Protocol (AIP)

When creating a new AI Interaction Protocol:

□ 1. CREATE protocol file
   Location: .claude/​protocols/​AIP-{NNN}-{slug}.md
   Follow template in .claude/​protocols/​INDEX.md

□ 2. UPDATE protocol INDEX
   Location: .claude/​protocols/​INDEX.md
   Add: New row with AIP number, title, purpose

□ 3. EMBED critical rules in root CLAUDE.md
   Location: /​CLAUDE.md
   Section: Appropriate section based on protocol topic
   Action: Add summary of critical rules with reference to full AIP

□ 4. UPDATE skill files (if protocol affects skill behavior)
   Identify: Which skills should follow this protocol
   Add: Reference to protocol in skill's "Related" section

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. UPDATE root CLAUDE.md
   Location: /​CLAUDE.md
   Section: "AI Agent Skills" → Trigger Phrases table
   Add: Trigger phrase → skill mapping

□ 6. ADD slash command (if user-invocable)
   Location: /​CLAUDE.md → Slash Commands table
   Add: /​{skill-name} with description

□ 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/​protocols/ (not docs/​reference/​protocols/)
   - Use .claude/​adr/ for concise ADRs
   - Use docs/​adr/ for full ADRs

□ 3. UPDATE "Last Updated" dates
   All affected files should have current date

□ 4. RUN consistency check
   Grep for old paths that might have been left behind

---

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/"
   - "docs/​ai-knowledge" → Directory removed; content in .claude/
   - "docs/​reference/​protocols" → Should be ".claude/​protocols/"

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

---

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 with code example
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 to CLAUDE.md ADR table (if high-impact)
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:

1. Scans all INDEX.md files for completeness
2. Checks path references for correctness
3. Validates skill mapping consistency
4. 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

---

Last updated: December 25, 2025