/change-creation

name: change-creation
description: Create change specification and implementation plan with dynamic phase generation. Supports feature, bugfix, refactor, and epic types.
user-invocable: false

Change Creation Skill

Purpose

Create a complete change specification package consisting of:

• Change directory: `changes/YYYY/MM/DD/<change-name>/`
• Specification: `SPEC.md` with proper frontmatter, type-specific sections, and domain updates
• Implementation plan: `PLAN.md` with dynamically generated phases
• INDEX.md update with new change entry

Key Principles

Skills vs Agents Separation

| Context | Responsibility | |---------|----------------| | **Skills** (main context) | All planning, spec creation, domain docs - interactive, needs user input | | **Agents** (subagent) | Execution only - non-interactive, implements approved plans |

This skill handles all spec and plan creation. Implementation agents only execute the approved plan.

Domain Documentation During Planning

Domain documentation is specified **in SPEC.md during planning**, not discovered during implementation:

• Glossary terms are explicitly listed
• Definition specs are identified upfront
• Architecture changes are noted

Implementation simply executes these specifications.

Dynamic Phase Generation

Plans are generated dynamically based on: 1. Project components from `sdd/sdd-settings.yaml` (delegate to the `project-settings` skill for the settings schema — it returns the component list with `name`, `type`, and type-specific settings) 2. Which components are affected by the change 3. Dependency order between components 4. Contextual agent assignment

Input

Schema: [`schemas/input.schema.json`](./schemas/input.schema.json)

Accepts change metadata (name, type, title, domain), optional workflow context, and content from spec solicitation or external integration.

Output

Schema: [`schemas/output.schema.json`](./schemas/output.schema.json)

Returns paths to created SPEC.md and PLAN.md files, and whether the index was updated.

Workflow

Step 1: Validate Inputs

1. Validate `name` is a valid directory name:

• Lowercase letters, numbers, hyphens only
• No spaces or special characters
• Not empty

2. Validate `type` is one of: `feature`, `bugfix`, `refactor`, `epic`

3. Ensure required parameters are provided:

• `name`, `type`, `title`, `description`, `domain`

Step 2: Generate Date Path

1. Get current date 2. Format as `YYYY/MM/DD` 3. Full path: `changes/YYYY/MM/DD/<name>/`

Step 3: Read Plugin Version and Settings

1. Read SDD plugin version from `.claude-plugin/plugin.json` 2. Read project components from `sdd/sdd-settings.yaml` 3. Identify affected components (from input or infer from description)

Step 4: Create Change Directory

mkdir -p changes/YYYY/MM/DD/<name>/

Step 5: Create SPEC.md

Create `changes/YYYY/MM/DD/<name>/SPEC.md` using type-specific template.

Common Frontmatter (all types)

---
title: <title>
type: <type>
status: active
domain: <domain>
issue: <issue or "TBD">
created: YYYY-MM-DD
updated: YYYY-MM-DD
sdd_version: <plugin_version>
affected_components:
  - <component-1>
  - <component-2>
decomposition_id: <uuid>  # Only if provided
---

Type-Specific Content

Use the template for the change type. Each template is a complete markdown document to use as the SPEC.md body (after the frontmatter above).

| Type | Template | Notes | |------|----------|-------| | `feature` | [`templates/spec-feature.md`](./templates/spec-feature.md) | Thorough, self-sufficient technical spec | | `bugfix` | [`templates/spec-bugfix.md`](./templates/spec-bugfix.md) | Focused on symptoms, root cause, and fix | | `refactor` | [`templates/spec-refactor.md`](./templates/spec-refactor.md) | Current state, proposed design, behavior preservation | | `epic` | [`templates/spec-epic.md`](./templates/spec-epic.md) | Parent spec with child change breakdown |

**Epic Directory Structure:**

After creating the epic's own SPEC.md and PLAN.md, create child change directories:

changes/YYYY/MM/DD/<epic-name>/
├── SPEC.md
├── PLAN.md
└── changes/
    ├── <child-change-1>/
    │   ├── SPEC.md
    │   └── PLAN.md
    └── <child-change-2>/
        ├── SPEC.md
        └── PLAN.md

Each child change uses the standard feature spec template with `parent_epic: ../SPEC.md` in frontmatter.

Step 6: Create PLAN.md with Dynamic Phases

Create `changes/YYYY/MM/DD/<name>/PLAN.md` using dynamic phase generation.

Phase Generation Algorithm

1. **Read project components** from `sdd/sdd-settings.yaml` 2. **Filter to affected components** (from SPEC.md `affected_components`) 3. **Order by dependency graph:** Invoke `techpacks.dependencyOrder` for the active tech pack to get the topological order of component types. Filter to only affected components while preserving dependency order. 4. **Assign agents:** Invoke `techpacks.readManifest` and read `components.<type>.agent` for each affected component type. For standards, invoke `techpacks.routeSkills(phase: plan-generation, component_type: <type>)`. 5. **Add final phases:** Read `lifecycle.testing.agent` and `lifecycle.verification.agent` from the manifest.

Plan Frontmatter

---
title: <title> - Implementation Plan
change: <name>
type: <type>
spec: ./SPEC.md
status: draft
created: YYYY-MM-DD
sdd_version: <plugin_version>
---

Plan Content

Use the template for the change type. Each template is a complete markdown document to use as the PLAN.md body (after the frontmatter above).

| Type | Template | Notes | |------|----------|-------| | `feature` | [`templates/plan-feature.md`](./templates/plan-feature.md) | Dynamic phases based on affected components | | `bugfix` | [`templates/plan-bugfix.md`](./templates/plan-bugfix.md) | 4 phases: investigation, fix, test, review | | `refactor` | [`templates/plan-refactor.md`](./templates/plan-refactor.md) | 4 phases: preparation, refactor,