change-creation

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:
2. Lowercase letters, numbers, hyphens only
3. No spaces or special characters
4. Not empty

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

1. Ensure required parameters are provided:
2. 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, test, review | | epic | [templates/plan-epic.md](./templates/plan-epic.md) | Change order and dependency graph |

Step 7: Update INDEX.md

Add entry to changes/INDEX.md:

1. Find the ## Active Changes section (create if missing)
2. Add entry with type indicator:

```markdown

• [<title>](YYYY/MM/DD/<name>/SPEC.md) - <type> - <description>

`` Note: Links are relative within the changes/` directory.

Step 8: Return Result

Return:

spec_path: changes/YYYY/MM/DD/<name>/SPEC.md
plan_path: changes/YYYY/MM/DD/<name>/PLAN.md
index_updated: true

PR Size Guidelines

Each phase should result in a reviewable PR:

| Metric | Target | Maximum | |--------|--------|---------| | Lines changed | < 400 | 800 | | Files changed | < 15 | 30 | | Acceptance criteria | < 5 | 8 |

If a phase exceeds limits:

1. Split into sub-phases (e.g., Phase 2a, Phase 2b)
2. Each sub-phase gets its own PR
3. Document splits in plan

Epic Lifecycle

Epics group multiple feature-type changes under a single goal. The creation workflow (Steps 1-8 above) handles epic SPEC.md and PLAN.md generation using the epic type templates. This section covers epic-specific tracking, implementation, and failure handling.

Workflow Tracking

Epics are tracked in sdd/workflows/<id>-<name>/workflow.yaml:

items:
  - id: 01-user-management
    title: User Management
    type: epic
    status: pending
    children:
      - id: 01-registration
        change_id: user-auth-1
        title: Registration
        type: feature
        status: pending

• Epic items have type: epic and a children array
• Only leaf features get change_ids (epics don't)
• Epic status is derived from child statuses

Implementing an Epic

For each child change, in dependency order:

1. Branch: git checkout -b epic/<epic-name>/<change-name>
2. Implement: Follow the child change's PLAN.md (standard feature implementation)
3. Test: Ensure all tests pass
4. PR: Create PR with change scope (one PR per child change)
5. Review: Get approval
6. Merge: Merge to main
7. Update: Mark change complete in epic PLAN.md

Handling Failures

If a child change