Kata Customize

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)

• 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