kata-customize

What this skill does

<objective>
Manage template overrides for customizing Kata output formats.

Templates control the structure of planning artifacts (plans, summaries, UAT sessions, verification reports, changelogs). Override a template to change how Kata generates these files for your project.

Operations: list, copy, edit, validate.
</objective>

<context>
$ARGUMENTS
</context>

<process>

## 1. Validate Environment

```bash
ls .planning/ 2>/dev/null
```

**If not found:** Error — run `/kata-new-project` first.

## 2. Determine Operation

Parse `$ARGUMENTS` for the operation:

- If contains "list" or "show" or no arguments → **list** operation
- If contains "copy" → **copy** operation (extract template name from remaining args)
- If contains "edit" or "modify" or "change" → **edit** operation (extract template name)
- If contains "validate" or "check" or "drift" → **validate** operation

If unclear, present AskUserQuestion:

```
What would you like to do?

1. **List templates** — See all customizable templates and their override status
2. **Copy a template** — Copy a default template for local customization
3. **Edit a template** — Modify an existing template override
4. **Validate overrides** — Check all overrides for missing required fields
```

## 3. List Operation

Run the discovery script:

```bash
bash "${CLAUDE_PLUGIN_ROOT}/skills/kata-customize/scripts/list-templates.sh"
```

Parse the JSON output. Display:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > CUSTOMIZABLE TEMPLATES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Template | Used By | Controls | Status |
| --- | --- | --- | --- |
| summary-template.md | kata-execute-phase | Phase completion docs | {override / default} |
| plan-template.md | kata-plan-phase | Phase plan structure | {override / default} |
| UAT-template.md | kata-verify-work | UAT session format | {override / default} |
| verification-report.md | kata-verify-work | Verification report format | {override / default} |
| changelog-entry.md | kata-complete-milestone | Changelog entry format | {override / default} |

Override location: `.planning/templates/`

To customize a template:
  `/kata-customize copy summary-template.md`
```

After displaying the list, stop. Do not proceed to another operation.

## 4. Copy Operation

Requires a template name argument. If not provided, run list operation first, then ask user to select.

**Step 4a: Resolve the default template path**

```bash
DEFAULT_PATH=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-customize/scripts/kata-lib.cjs" resolve-template "$TEMPLATE_NAME" 2>&1)
```

If the resolve script exits non-zero, the template name is invalid. Display the error and stop.

**Step 4b: Check for existing override**

```bash
[ -f ".planning/templates/$TEMPLATE_NAME" ] && echo "EXISTS" || echo "NEW"
```

If EXISTS, ask user via AskUserQuestion:

```
An override for `{TEMPLATE_NAME}` already exists at `.planning/templates/{TEMPLATE_NAME}`.

1. **Overwrite** — Replace with default (your customizations will be lost)
2. **Cancel** — Keep current override
```

If user selects Cancel, stop.

**Step 4c: Copy the default**

```bash
mkdir -p .planning/templates
cp "$DEFAULT_PATH" ".planning/templates/$TEMPLATE_NAME"
```

**Step 4d: Confirm**

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > TEMPLATE COPIED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Copied default to: `.planning/templates/{TEMPLATE_NAME}`

Edit the file to customize, then validate:
  `/kata-customize validate`
```

## 5. Edit Operation

Requires a template name argument. If not provided, run list operation to show overrides, then ask which to edit.

**Step 5a: Check override exists**

```bash
[ -f ".planning/templates/$TEMPLATE_NAME" ] && echo "EXISTS" || echo "MISSING"
```

If MISSING, ask user via AskUserQuestion:

```
No override exists for `{TEMPLATE_NAME}`.

1. **Copy and edit** — Copy the default first, then edit
2. **Cancel** — Do nothing
```

If user selects "Copy and edit", run step 4c first.

**Step 5b: Read current content**

Read `.planning/templates/{TEMPLATE_NAME}` and display the current content to the user.

**Step 5c: Accept modifications**

Ask the user what they want to change. Two paths:

- If user describes specific changes ("change heading X to Y", "add field Z"), apply the edits to the file using Edit tool and write the updated content.
- If user says they will edit externally ("let me edit it", "I'll do it in my editor"), acknowledge and offer to validate when they return.

**Step 5d: Validate after edit**

After writing changes (or when user returns from external editing), run single-template validation:

```bash
node "${CLAUDE_PLUGIN_ROOT}/skills/kata-customize/scripts/kata-lib.cjs" check-template-drift
```

If drift warnings mention the edited template, display them. If clean, display:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > TEMPLATE VALID
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

`{TEMPLATE_NAME}` has all required fields. Override is active.
```

## 6. Validate Operation

Run validation on all overrides:

```bash
DRIFT_OUTPUT=$(node "${CLAUDE_PLUGIN_ROOT}/skills/kata-customize/scripts/kata-lib.cjs" check-template-drift 2>/dev/null)
```

If `DRIFT_OUTPUT` is empty and `.planning/templates/` exists with .md files:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > ALL TEMPLATES VALID
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

All template overrides pass schema validation.
```

If `DRIFT_OUTPUT` is empty and no overrides exist:

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > NO OVERRIDES
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

No template overrides found at `.planning/templates/`.

To create an override:
  `/kata-customize copy summary-template.md`
```

If `DRIFT_OUTPUT` has content (warnings):

```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata > TEMPLATE DRIFT DETECTED
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

{DRIFT_OUTPUT}

To fix, edit the override or reset to default:
  `/kata-customize edit {template-name}`
  `/kata-customize copy {template-name}` (resets to default)
```

</process>

<success_criteria>

- [ ] Templates listed with descriptions and override status
- [ ] Default copied to .planning/templates/ with overwrite protection
- [ ] Edit operation reads current content and applies user changes
- [ ] Validation runs after edit and reports missing fields
- [ ] All operations use existing infrastructure (kata-lib.cjs resolve-template, kata-lib.cjs check-template-drift)
- [ ] Skill responds to natural language triggers
      </success_criteria>