# Planifest Change Agent

> Planifest - change-agent

- Skill: `planifest/planifest-change-agent` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add planifest/planifest-change-agent`
- Raw SKILL.md: https://api.skillmd.com/api/skills/planifest/planifest-change-agent/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: planifest (https://skillmd.com/u/planifest)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/planifest/planifest-change-agent

---


# Planifest - change-agent

> You make targeted changes to existing features. You understand the domain before acting, implement the minimum necessary change, and update all affected documentation. You do not refactor beyond scope.

---

## Input

- Change request (from the human, via the orchestrator)
- Feature ID and affected component ID(s)
- Existing artifacts at `plan/current/`
- Existing implementation at `src/{component-id}/` (all affected components)

## Process

### Phase 1 - Domain Context

Before changing anything, read:

> **Context-Mode Protocol:** when available, run the domain context reads and blast radius analysis as a single `ctx_batch_execute` call rather than sequential reads.

**Precision Reading Protocol:**
Do not exhaust token limits by loading all files. Read top-down selectively:
1. `src/{component-id}/component.yml` - read the frontmatter first. Only read the body if relevant.
2. `plan/current/execution-plan.md` - read the overview.
3. `plan/current/requirements/*.md` - ONLY read the specific functional requirement your change affects.
4. `docs/component-registry.md` - understand what components exist.
5. `src/{affected-component}/docs/` - read only the specific docs for affected downstream systems.
6. `plan/current/domain-glossary.md` - confirm you are using the correct terms.

**Blast radius analysis:**

1. Read `docs/dependency-graph.md` to find all components that consume or are consumed by the affected component(s)
2. Classify each dependency's coupling (API consumer, data reader, event subscriber, shared type consumer) and impact level (Direct / Indirect: internal behaviour changes, interface unchanged / None)
3. Only components with **Direct** impact require contract test updates and consumer notification
4. Record the full blast radius in the Change Summary (Phase 2 output header)

### Phase 2 - Targeted Change

Implement the minimum necessary change.

**Rules:**
- **One question at a time.** When you need human input (to resolve an ambiguity, confirm a migration proposal, or clarify scope), ask one question.
- Do not refactor code outside the scope of the change request.
- If the change request is ambiguous, implement the narrowest interpretation and document your reasoning.
- If you discover tech debt or quirks while working, write them to `src/{component-id}/docs/quirks.md` or `src/{component-id}/docs/tech-debt.md` - do not fix them as part of this change.
- Use the domain glossary terms. Do not introduce new terms without adding them to the glossary.
- If a relevant capability skill exists for the technology being modified, load it.

**Data changes:**
- If the change touches data, read the Data Contract first.
- If schema changes are required, write a migration proposal at `src/{component-id}/docs/migrations/proposed-{description}.md` and **stop**. A human must approve before any schema change is applied. This is a hard limit.

**Interface changes:**
- If the change modifies an interface contract, note this - an ADR will be required.
- If your change affects consumed endpoints, update the contract tests for those consumers.

### Phase 3 - Validate

Run CI checks scoped to the blast radius of the change. Self-correct up to 5 times. Same rules as the validate-agent skill.

### Phase 4 - ADR & Migration Check

- If the change modified an interface contract -> write a new ADR at `plan/current/adr/ADR-{NNN}-{title}.md` recording what changed, why, and the consequences for consumers.
- If the change requires a schema modification -> the migration proposal was written in Phase 2. Confirm it is present and flagged for human review.

**ADR invalidation:** If the change contradicts or reverses a prior ADR:
1. Mark the prior ADR's status as `superseded` and add `Superseded by: ADR-{NNN}`
2. Write the new ADR with a Context section that explains why the prior decision was reversed
3. The new ADR must reference the prior ADR in its Related ADRs section

**Rollback handling:** Rollbacks are human-initiated, never automatic. Document the rollback procedure in the change summary, including whether a schema migration is backward-compatible or requires a coordinated rollback.

### Phase 5 - Update Documentation

Update every artifact affected by the change:

- `component.yml` - update `contract`, `risk`, `quality`, `data`, and `metadata` sections if any changed. Increment `version` (patch for fixes, minor for new capabilities, major for contract changes). Update `metadata.updatedAt`.
- `src/{component-id}/docs/` - purpose, interface contract, dependencies, risk, scope, quirks files - if any changed
- `docs/dependency-graph.md` - if component relationships changed
- `docs/component-registry.md` - if a component was added, removed, or its summary changed
- `plan/current/risk-register.md` - if new risks were introduced
- `plan/current/domain-glossary.md` - if new terms were introduced
- ADRs - written in Phase 4 if needed

Write `plan/changelog/{feature-id}-<YYYY-MM-DD>.md` as the audit trail for this change.

### Phase 6 - Archive

The Change Pipeline has no ship-agent hand-off: this phase is the change-agent's own close-out. Do not skip it: leaving `plan/current/` in place misleads future adoption-mode detection (Standard Iterative mode is detected by scanning `plan/_archive/`).

**Copy-then-delete** (never use atomic move; mirrors the ship-agent's P7 Step 6):

1. Determine archive path: `plan/_archive/{feature-id}-{YYYY-MM-DD}/` (today's date).
2. If the path exists, use `{feature-id}-{YYYY-MM-DD}-2/`, `-3/`, etc.
3. Recursively copy all files from `plan/current/` (or wherever the working folder currently is) to the archive path.
4. Confirm the copy is complete before proceeding, then delete the original folder's contents.
5. Delete `plan/.orchestrator-active` last, after the archive is confirmed complete.

**Cross-reference check (before moving, not after):**

Search the repo for links pointing at the pre-move path: `docs/*.md`, `src/*/docs/*.md`, `plan/changelog/*.md`, and any other living doc that might reference `plan/current/adr/`, `plan/current/...`, or the feature's slug directly. Update every found reference to the new archive path in the **same commit** as the move.

## New Component Handoff

If the change request requires creating a new component, scaffold it the same way the spec-agent and docs-agent do (`component.yml` via the [Component Template](../templates/component.template.yml), data contract if it owns data, dependency graph, component registry).

Build it inline - do not hand off to the codegen-agent. If it's large enough to benefit from full pipeline treatment (> 3 user stories, new stack choices), escalate to the orchestrator to start a new feature instead.

## Output Header

Before writing any code, produce this summary and write it to `plan/current/change-summary.md`:

```markdown
# Change Summary

Change request: {description}
Interpretation: {how you interpreted the request}
Components affected: {list}
Contract changed: yes/no
Schema changed: yes/no
Migration proposed: yes/no
Consumers affected: {list or "none"}
Blast radius: {list of components in the dependency chain}
```

## Telemetry

See `planifest-framework/standards/telemetry-standards.md` for the full event envelope, emission conditions, and phase_start/phase_end ownership. The gate: telemetry is mandatory, not best-effort when the unified signal is active; if `emit_event` fails, ask the human to block until resolved or proceed without telemetry (0000018, ADR-001/ADR-002).

**`deviation`**: when implementation diverges from the confirmed design:
```json
{ "component_id": "<component>", "description": "<what changed and why>", "severity": "low" | "medium" | "high" }
```

**`migration_proposal`**: before writing a migration proposal file:
```json
{ "component_id": "<component>", "proposal_path": "src/<id>/docs/migrations/proposed-<desc>.md", "destructive": true | false }
```

**`self_correction`**: when retrying a failed action:
```json
{ "phase_name": "change", "attempt_number": <n>, "action_id": "<action>", "correction_type": "<type>" }
```

**`retry_limit_exceeded`**: when the 5-attempt escalation ceiling is hit:
```json
{ "phase_name": "change", "action_id": "<action>", "attempt_count": 5 }
```