Synchronizes CLAUDE.md AI agent instructions with constitution updates via selective section mapping. Use after amendments, version bumps, new principles, or explicit sync requests.
From humaninloopnpx claudepluginhub deepeshbodh/human-in-loop --plugin humaninloopThis skill uses the workspace's default tool permissions.
references/SECTION-TEMPLATES.mdreferences/SYNC-PATTERNS.mdSearches, retrieves, and installs Agent Skills from prompts.chat registry using MCP tools like search_skills and get_skill. Activates for finding skills, browsing catalogs, or extending Claude.
Searches prompts.chat for AI prompt templates by keyword or category, retrieves by ID with variable handling, and improves prompts via AI. Use for discovering or enhancing prompts.
Executes pre-written implementation plans: critically reviews, follows bite-sized steps exactly, runs verifications, tracks progress with checkpoints, uses git worktrees, stops on blockers.
Ensure CLAUDE.md (the primary AI agent instruction file) remains synchronized with the constitution. CLAUDE.md serves a different audience (AI agents) than the constitution (human governance), so synchronization is selective—specific sections map with explicit sync rules.
humaninloop:authoring-constitution or humaninloop:brownfield-constitutionhumaninloop:authoring-constitution| Mistake | Problem | Fix |
|---|---|---|
| Full duplication | CLAUDE.md becomes constitution copy, loses agent-focused format | Use selective sync per mapping table |
| Stale sync | CLAUDE.md lags behind constitution, agents use outdated rules | Sync on every constitution version bump |
| Missing version | No version tracking makes drift undetectable | Always include version footer in CLAUDE.md |
| Partial sync | Some sections synced, others forgotten | Use validation checklist before completing |
| Summary drift | Summarization loses enforcement keywords and thresholds | Preserve MUST/SHOULD/MAY and numeric thresholds |
┌─────────────────────────────────────────────────────────────────┐
│ TWO AUDIENCES │
├────────────────────────────┬────────────────────────────────────┤
│ CONSTITUTION │ CLAUDE.MD │
├────────────────────────────┼────────────────────────────────────┤
│ Audience: Humans │ Audience: AI Agents │
│ Purpose: Governance │ Purpose: Runtime Instructions │
│ Format: Detailed │ Format: Actionable │
│ Contains: Rationale │ Contains: Rules + Commands │
│ Updated: Deliberately │ Updated: Must track constitution │
└────────────────────────────┴────────────────────────────────────┘
If CLAUDE.md diverges from the constitution, AI agents operate with outdated or incorrect guidance, undermining governance.
Consequences of Drift:
Benefits of Synchronization:
The following sections MUST be synchronized:
| Constitution Section | CLAUDE.md Section | Sync Rule |
|---|---|---|
| Core Principles | Principles Summary | MUST list all principles with enforcement keywords |
| Technology Stack | Technical Stack | MUST match exactly (table format) |
| Quality Gates | Quality Gates | MUST match exactly (table format) |
| Governance | Development Workflow | MUST include versioning rules and commit conventions |
| Project Structure | Project Structure | MUST match if present in constitution |
| Layer Import Rules | Architecture | MUST replicate dependency rules |
Two primary sync rules govern how content transfers:
Principles are summarized but preserve enforcement keywords, metrics, and thresholds. Rationale is omitted because CLAUDE.md focuses on actionable rules, not justification.
What to preserve:
pytest --cov-fail-under=80)What to omit:
Tables are copied directly with no summarization. This applies to:
Why exact match: These sections contain precise configuration that agents must follow exactly. Summarization risks losing critical details like specific tool versions or threshold values.
See references/SECTION-TEMPLATES.md for detailed templates and examples for each sync rule.
The sync process follows six steps:
Load the constitution and CLAUDE.md. Verify both files exist and are readable. If CLAUDE.md does not exist, create it from the section templates.
For each row in the Mandatory Sync Mapping table, locate the corresponding sections in both files. Note any missing sections.
Create a gap report documenting drift between files:
## Sync Gap Report
**Constitution Version**: 2.1.0
**CLAUDE.md Version**: 2.0.0
### Gaps Found
| Section | Constitution | CLAUDE.md | Gap Type |
|---------|--------------|-----------|----------|
| Quality Gates | coverage ≥80% | coverage ≥70% | Value mismatch |
| Principles | 7 principles | 6 principles | Missing content |
| Version | 2.1.0 | 2.0.0 | Version drift |
### Recommended Actions
1. Update CLAUDE.md Quality Gates: 70% → 80%
2. Add Principle VII to Principles Summary
3. Update version footer to 2.1.0
Prepare specific changes needed. For each gap, draft the exact text change required. Preview changes before applying.
Update CLAUDE.md with synchronized content. Apply changes section by section, preserving any CLAUDE.md-specific content not in the mapping.
Run the Quick Validation checklist. All items must pass before considering sync complete.
See references/SYNC-PATTERNS.md for detailed process steps, validation checklists, and conflict resolution.
CLAUDE.md includes these sections for proper sync:
| Section | Source | Sync Rule | Notes |
|---|---|---|---|
| Project Overview | Manual | N/A | Brief description of project purpose |
| Principles | Constitution Core Principles | List with enforcement | Omit rationale, keep keywords |
| Technical Stack | Constitution Technology Stack | Exact match | Copy table directly |
| Quality Gates | Constitution Quality Gates | Exact match | Copy table directly |
| Development Workflow | Constitution Governance | List with enforcement | Include commit conventions |
| Version Footer | Constitution version | Exact match | Format: `Version X.Y.Z |
These sections may exist in CLAUDE.md but are not synchronized from the constitution:
Optional sections are preserved during sync—they are not deleted or modified.
See references/SECTION-TEMPLATES.md for the complete structure template.
CLAUDE.md synchronization MUST occur when:
When CLAUDE.md contains content that conflicts with the constitution:
CLAUDE.md may contain project-specific sections not in the constitution (e.g., IDE setup, local development tips). These sections are allowed and should be preserved during sync.
Action: Keep extra sections. Only update mapped sections.
A mapped section in CLAUDE.md contains different values than the constitution (e.g., different coverage threshold).
Action: Constitution is authoritative. Overwrite CLAUDE.md with constitution values.
A mapped section exists in CLAUDE.md but not in the constitution.
Action: Flag for review. Either add section to constitution or remove from CLAUDE.md.
CLAUDE.md version does not match constitution version.
Action: Always align versions. CLAUDE.md version MUST match constitution version after sync. If constitution is v2.1.0, CLAUDE.md footer must show v2.1.0.
Before completing synchronization, verify:
See references/SYNC-PATTERNS.md for the complete validation checklist.
When syncing, use this commit format:
docs: sync CLAUDE.md with constitution vX.Y.Z
- Updated Principles Summary (added Principle VII)
- Updated Quality Gates (coverage 70% -> 80%)
- Version aligned to X.Y.Z
This skill includes detailed reference documentation:
| File | Purpose | When to Use |
|---|---|---|
| references/SECTION-TEMPLATES.md | Templates for each CLAUDE.md section | When creating or restructuring CLAUDE.md |
| references/SYNC-PATTERNS.md | Detailed sync patterns, validation checklists, edge cases | When resolving complex sync scenarios |