gannonh 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 "${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
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
[ -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 "${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:
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)
- 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