kata-customize by gannonh/kata-skills

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.

1. Validate Environment

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

DEFAULT_PATH=$(node 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

[ -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

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

[ -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:

node 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:

DRIFT_OUTPUT=$(node 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)

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