C3 Alter - Change Through ADR
Every change flows through an ADR. No exceptions.
Relationship to c3-orchestrator agent: This skill defines the change workflow stages. The c3-skill:c3-orchestrator agent implements this workflow, dispatching to sub-agents (c3-analysis, c3-synthesizer) for comprehensive analysis. Use the agent when spawning via Task tool; use this skill directly for inline execution.
REQUIRED: Load References
Before proceeding, use Glob to find and Read these files:
-
**/references/skill-harness.md
-
Red flags and complexity rules
-
**/references/layer-navigation.md
-
How to traverse C3 docs
-
**/references/adr-template.md
-
ADR structure (for Stage 4)
-
**/references/component-lifecycle.md
-
Provisioned status model (for Stage 2b)
Core Loop (All Stages)
ANALYZE → ASK (until confident) → SYNTHESIZE → REVIEW │ │ └── until no open ───────┘ questions
On conflict: ASCEND → fix earlier stage → re-descend
Confident = No open questions. Don't proceed with "TODO" or unclear fields.
Progress Checklist
Copy and track as you work:
Change Progress:
- Stage 1: Intent clarified (type, goal confirmed)
- Stage 2: Current state documented (affected components listed)
- Stage 3: Scope assessed (all c3 IDs, breaking changes noted)
- Stage 4: ADR created (proposed, validation passed)
- Stage 4b: ADR accepted by user
- Stage 5: Plan created with ordered steps
- Stage 6: Execution complete (docs, code, diagrams)
- Stage 7: Audit passed, ADR marked implemented
Stage 1: Intent
Step Action
Analyze Add/modify/remove/fix? What problem? Scope hint?
Ask Use AskUserQuestion: feature vs fix? problem? urgency?
Synthesize Intent: [action] Goal: [outcome] Type: [feature/fix/refactor]
Review User confirms or corrects
Stage 2: Current State
Step Action
Analyze Read affected C3 docs via layer navigation
Ask Are docs accurate? Recent code changes not documented?
Synthesize List affected components, their current behavior, dependencies
Review User confirms or corrects
Stage 2b: Detect Provisioned Components
Check if component has a provisioned version:
Check for provisioned version
ls .c3/provisioned/c3-/c3-XXX-.md 2>/dev/null
If provisioned version exists:
AskUserQuestion: question: "Found provisioned design for this component at .c3/provisioned/... Implement from this design?" options: - "Yes - use provisioned design as starting point" - "No - start fresh (will supersede provisioned)"
On "Yes":
-
Load provisioned doc as starting point for analysis
-
ADR frontmatter: add implements: <provisioned-adr>
-
After implementation complete, promote provisioned docs
On "No":
-
Proceed with normal alter flow (fresh analysis)
-
After implementation, delete orphaned provisioned file
-
Update provisioned ADR: superseded-by: <this-adr> with note "Design not used"
Stage 3: Scope Impact
Step Action
Analyze Which layers change? Dependencies? Linkages? Diagrams?
Ask External systems involved? Breaking changes? Keep or replace?
Synthesize List all affected c3 IDs, note breaking changes
Review User confirms or expands
Stage 4: Create ADR
Generate at .c3/adr/adr-YYYYMMDD-{slug}.md . Use **/references/adr-template.md .
Key sections: Problem, Decision, Rationale, Affected Layers, References Affected, Verification
Note: ADR is only created after synthesizer validation passes. The synthesizer validates architectural coherence before ADR generation.
Stage 4b: ADR Acceptance
Use AskUserQuestion to ask the user to approve or reject the ADR.
On Accept Update status to accepted , then immediately execute Stage 5 and 6
On Reject Return to Stage 1/3 based on what changed
CRITICAL - After user accepts ADR: You MUST continue executing without stopping. Create the component documentation file(s) and update the container README. Do NOT end after receiving approval.
Stage 5: Create Plan
Generate at .c3/adr/adr-YYYYMMDD-{slug}.plan.md .
Include:
-
Pre-execution checklist (update ## References in affected components)
-
Ordered steps: docs first, then code, then diagrams
-
Verification commands
After ADR acceptance, immediately create the plan and continue to execution.
Stage 6: Execute
Execute the plan immediately after creating it. For documentation-only changes (no code implementation requested), this means:
-
Create component documentation - Write the new component file (e.g., c3-106-*.md )
-
Update container README - Add new component to the Components table
-
Update TOC - Add link to new component
Follow plan order:
-
Make change (doc or code)
-
Check for conflicts
-
Update ## References if code moved/added/removed
On conflict - Tiered response:
Impact Action
High: scope expansion, breaking change, new layer Ask user, update ADR if needed
Low: wording fix, diagram update, ID fix Auto-fix, note in log
Ref Maintenance
If change affects a pattern:
-
Check if ref-* exists for pattern
-
Update ref if pattern changes
-
Create new ref if pattern is new and reusable
Critical: The Three Categories
Load **/references/component-categories.md for the full Foundation vs Feature vs Ref rules.
Key rule: Components (Foundation/Feature) MUST have ## Code References . Refs must NOT. If you cannot name a concrete file, create a ref instead.
Promoting Provisioned Components
If implementing a provisioned component (detected in Stage 2b):
Move file:
mv .c3/provisioned/c3-X/c3-XXX.md .c3/c3-X/c3-XXX.md
Update frontmatter:
status: active # Changed from provisioned
Remove supersedes: field if present
Remove adr: field (or update to implementation ADR)
Add Code References section pointing to implemented files
Note: The provisioned ADR is superseded by c3-adr-transition agent AFTER verification passes in Stage 7, not during execution. This ensures we don't mark the design as superseded if implementation fails verification.
Stage 7: Verify
Run /c3 audit . Check diagrams, IDs, linkages, code-doc match.
On Pass Update ADR status to implemented
On Fail Fix issue, re-audit, loop until pass
Examples
Example 1: Add feature
User: "Add rate limiting to the API"
Stage 1 - Intent: Intent: Add rate limiting Goal: Prevent API abuse Type: Feature
Stage 2 - Current State: Affected: c3-2-api (API Backend) Current: No rate limiting exists Depends on: c3-201-auth-middleware (good injection point)
Stage 3 - Scope: Changes: Add c3-206-rate-limiter component Affects: c3-201 (middleware chain) Breaking: No
Stage 4 - ADR: Created: .c3/adr/adr-20260109-rate-limiting.md Status: proposed (validation passed)
Stage 4b - Accept: User accepts → status: accepted
Stage 5 - Plan:
- Create c3-206-rate-limiter.md
- Update c3-2-api/README.md inventory
- Implement src/api/middleware/rate-limiter.ts
- Update c3-201 hand-offs
Stage 6 - Execute: Follow plan Stage 7 - Verify: /c3 audit
Example 2: Fix bug
User: "Fix the login timeout issue"
Stage 1 - Intent: Intent: Fix bug Goal: Login doesn't timeout prematurely Type: Fix
Stage 2 - Current State: Affected: c3-201-auth-middleware Current: Session TTL hardcoded to 15min Issue: Users report logout after 10min
Stage 3 - Scope: Changes: Modify existing component Affects: c3-201 only Breaking: No
Stage 4 - ADR: Created: .c3/adr/adr-20260109-login-timeout-fix.md Status: proposed (validation passed, simpler ADR for bugfix)
Stage 4b - Accept: User accepts → status: accepted
Stage 5-7: Execute and verify
Response Format
Stage N: {Name} {findings} Open Questions: {list or "None - confident"} Next: {what happens next}