Planifest Change Agent

Process

Phase 1 - Domain Context

Before changing anything, read:

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. For each dependency, classify the coupling:
   • API consumer — calls endpoints defined in the affected component's OpenAPI spec
   • Data reader — reads from tables owned by the affected component
   • Event subscriber — listens to events published by the affected component
   • Shared type consumer — imports types from the affected component's shared package
3. Determine impact level per dependent component:
   • Direct — the change modifies an interface, schema, or type that this component uses
   • Indirect — the change modifies internal behavior but the interface is unchanged
   • None — no coupling to the changed surface area
4. Only components with Direct impact require contract test updates and consumer notification
5. Record the full blast radius in the Change Summary (Phase 2 output header)

Phase 2 - Targeted Change

Implement the minimum necessary change.

Rules:

• Do not refactor code outside the scope of the change request. Scope creep is a process violation.
• 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.

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: If the change needs to be reverted after deployment:

1. The change-agent does not perform rollbacks automatically — rollbacks are human-initiated
2. Document the rollback procedure in the change summary: what to revert, what data migration (if any) needs to be reversed, and what consumers need to be notified
3. If the change included a schema migration, note whether the migration is backward-compatible (previous code version works with new schema) 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/{initiative-id}-<YYYY-MM-DD>.md as the audit trail for this change.

New Component Handoff

If the change request requires creating a new component (not just modifying existing ones):

1. Create the component scaffold: src/{new-component-id}/component.yml using the Component Template
2. Write the data contract if the component owns data: src/{new-component-id}/docs/data-contract.md
3. Update the design at plan/current/design.md to include the new component in the components list
4. Update the dependency graph at docs/dependency-graph.md to show the new component's relationships
5. Update the component registry at docs/component-registry.md to include the new component
6. Build the component following the same rules as the codegen-agent (code, tests, docs, IaC)

The change-agent builds the new component inline — it does not hand off to the codegen-agent. This avoids a pipeline context switch for what is typically a small addition.

If the new component is large enough that it would benefit from full pipeline treatment (> 3 user stories, new stack choices), escalate to the orchestrator to start a new initiative instead.

Output Header

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

# 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}

Capability Skills

If a relevant capability skill exists for the technology being modified (e.g. frontend-design for React changes, webapp-testing for test updates), load it. For all code changes, follow the standards in Code Quality Standards - match existing patterns, keep modules small, and ensure every change would pass a senior engineer's PR review.

This skill is invoked by the orchestrator for change requests. See Orchestrator Skill