@gannonh/kata 1.0.2 → 1.0.3

package/agents/kata-executor.md

@@ -5,6 +5,17 @@ tools: Read, Write, Edit, Bash, Grep, Glob
 color: yellow
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <role>
 You are a Kata plan executor. You execute PLAN.md files atomically, creating per-task commits, handling deviations automatically, pausing at checkpoints, and producing SUMMARY.md files.
 
@@ -353,7 +364,7 @@ Type "done" when authenticated.
 Before any `checkpoint:human-verify`, ensure verification environment is ready. If plan lacks server startup task before checkpoint, ADD ONE (deviation Rule 3).
 
 For full automation-first patterns, server lifecycle, CLI handling, and error recovery:
-**See @~/.claude/kata/references/checkpoints.md**
+**See @$KATA_BASE/references/checkpoints.md**
 
 **Quick reference:**
 - Users NEVER run CLI commands - Claude does all automation
@@ -610,7 +621,7 @@ After all tasks complete, create `{phase}-{plan}-SUMMARY.md`.
 
 **Location:** `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 
-**Use template from:** @~/.claude/kata/templates/summary.md
+**Use template from:** @$KATA_BASE/templates/summary.md
 
 **Frontmatter population:**
 

package/agents/kata-planner.md

@@ -5,6 +5,17 @@ tools: Read, Write, Bash, Glob, Grep, WebFetch, mcp__context7__*
 color: green
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <role>
 You are a Kata planner. You create executable phase plans with task breakdown, dependency analysis, and goal-backward verification.
 
@@ -407,8 +418,8 @@ Output: [What artifacts will be created]
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/execute-plan.md
-@~/.claude/kata/templates/summary.md
+@$KATA_BASE/workflows/execute-plan.md
+@$KATA_BASE/templates/summary.md
 </execution_context>
 
 <context>

package/agents/kata-research-synthesizer.md

@@ -5,6 +5,17 @@ tools: Read, Write, Bash
 color: purple
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <role>
 You are a Kata research synthesizer. You read the outputs from 4 parallel researcher agents and synthesize them into a cohesive SUMMARY.md.
 
@@ -122,7 +133,7 @@ Identify gaps that couldn't be resolved and need attention during planning.
 
 ## Step 6: Write SUMMARY.md
 
-Use template: ~/.claude/kata/templates/research-project/SUMMARY.md
+Use template: $KATA_BASE/templates/research-project/SUMMARY.md
 
 Write to `.planning/research/SUMMARY.md`
 
@@ -159,7 +170,7 @@ Return brief confirmation with key points for the orchestrator.
 
 <output_format>
 
-Use template: ~/.claude/kata/templates/research-project/SUMMARY.md
+Use template: $KATA_BASE/templates/research-project/SUMMARY.md
 
 Key sections:
 - Executive Summary (2-3 paragraphs)

package/agents/kata-roadmapper.md

@@ -5,6 +5,17 @@ tools: Read, Write, Bash, Glob, Grep
 color: purple
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <role>
 You are a Kata roadmapper. You create project roadmaps that map requirements to phases with goal-backward success criteria.
 
@@ -286,7 +297,7 @@ After roadmap creation, REQUIREMENTS.md gets updated with phase mappings:
 
 ## ROADMAP.md Structure
 
-Use template from `~/.claude/kata/templates/roadmap.md`.
+Use template from `$KATA_BASE/templates/roadmap.md`.
 
 Key sections:
 - Overview (2-3 sentences)
@@ -295,7 +306,7 @@ Key sections:
 
 ## STATE.md Structure
 
-Use template from `~/.claude/kata/templates/state.md`.
+Use template from `$KATA_BASE/templates/state.md`.
 
 Key sections:
 - Project Reference (core value, current focus)

package/kata/VERSION

@@ -1 +1 @@
-1.0.2
+1.0.3

package/kata/templates/codebase/structure.md

@@ -216,7 +216,7 @@ kata/
 
 **New Workflow:**
 - Implementation: `kata/workflows/{name}.md`
-- Usage: Reference from command with `@~/.claude/kata/workflows/{name}.md`
+- Usage: Reference from command with `@$KATA_BASE/workflows/{name}.md`
 
 **New Reference Document:**
 - Implementation: `kata/references/{name}.md`

package/kata/templates/phase-prompt.md

@@ -1,5 +1,16 @@
 # Phase Prompt Template
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 > **Note:** Planning methodology is in `agents/kata-planner.md`.
 > This template defines the PLAN.md output format that the agent produces.
 
@@ -37,10 +48,10 @@ Output: [What artifacts will be created]
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/execute-plan.md
-@~/.claude/kata/templates/summary.md
+@$KATA_BASE/workflows/execute-plan.md
+@$KATA_BASE/templates/summary.md
 [If plan contains checkpoint tasks (type="checkpoint:*"), add:]
-@~/.claude/kata/references/checkpoints.md
+@$KATA_BASE/references/checkpoints.md
 </execution_context>
 
 <context>
@@ -75,7 +86,7 @@ Output: [What artifacts will be created]
   <done>[Acceptance criteria]</done>
 </task>
 
-<!-- For checkpoint task examples and patterns, see @~/.claude/kata/references/checkpoints.md -->
+<!-- For checkpoint task examples and patterns, see @$KATA_BASE/references/checkpoints.md -->
 <!-- Key rule: Claude starts dev server BEFORE human-verify checkpoints. User only visits URLs. -->
 
 <task type="checkpoint:decision" gate="blocking">
@@ -268,7 +279,7 @@ TDD features get dedicated plans with `type: tdd`.
 → Yes: Create a TDD plan
 → No: Standard task in standard plan
 
-See `~/.claude/kata/references/tdd.md` for TDD plan structure.
+See `$KATA_BASE/references/tdd.md` for TDD plan structure.
 
 ---
 
@@ -372,9 +383,9 @@ Output: Working dashboard component.
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/execute-plan.md
-@~/.claude/kata/templates/summary.md
-@~/.claude/kata/references/checkpoints.md
+@$KATA_BASE/workflows/execute-plan.md
+@$KATA_BASE/templates/summary.md
+@$KATA_BASE/references/checkpoints.md
 </execution_context>
 
 <context>
@@ -497,7 +508,7 @@ user_setup:
 
 **Result:** Execute-plan generates `{phase}-USER-SETUP.md` with checklist for the user.
 
-See `~/.claude/kata/templates/user-setup.md` for full schema and examples
+See `$KATA_BASE/templates/user-setup.md` for full schema and examples
 
 ---
 
@@ -564,4 +575,4 @@ Task completion ≠ Goal achievement. A task "create chat component" can complet
 5. Gaps found → fix plans created → execute → re-verify
 6. All must_haves pass → phase complete
 
-See `~/.claude/kata/workflows/verify-phase.md` for verification logic.
+See `$KATA_BASE/workflows/verify-phase.md` for verification logic.

package/kata/workflows/discovery-phase.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <purpose>
 Execute discovery at the appropriate depth level.
 Produces DISCOVERY.md (for Level 2-3) that informs PLAN.md creation.
@@ -28,7 +39,7 @@ Claude's training data is 6-18 months stale. Always verify.
 2. **Official docs** - When Context7 lacks coverage
 3. **WebSearch LAST** - For comparisons and trends only
 
-See ~/.claude/kata/templates/discovery.md `<discovery_protocol>` for full protocol.
+See $KATA_BASE/templates/discovery.md `<discovery_protocol>` for full protocol.
 </source_hierarchy>
 
 <process>
@@ -107,7 +118,7 @@ For: Choosing between options, new external integration.
 
 5. **Cross-verify:** Any WebSearch finding → confirm with Context7/official docs.
 
-6. **Create DISCOVERY.md** using ~/.claude/kata/templates/discovery.md structure:
+6. **Create DISCOVERY.md** using $KATA_BASE/templates/discovery.md structure:
 
    - Summary with recommendation
    - Key findings per option
@@ -126,7 +137,7 @@ For: Architectural decisions, novel problems, high-risk choices.
 
 **Process:**
 
-1. **Scope the discovery** using ~/.claude/kata/templates/discovery.md:
+1. **Scope the discovery** using $KATA_BASE/templates/discovery.md:
 
    - Define clear scope
    - Define include/exclude boundaries
@@ -160,7 +171,7 @@ For: Architectural decisions, novel problems, high-risk choices.
 
 6. **Create comprehensive DISCOVERY.md:**
 
-   - Full structure from ~/.claude/kata/templates/discovery.md
+   - Full structure from $KATA_BASE/templates/discovery.md
    - Quality report with source attribution
    - Confidence by finding
    - If LOW confidence on any critical finding → add validation checkpoints
@@ -184,7 +195,7 @@ Ask: What do we need to learn before we can plan this phase?
   </step>
 
 <step name="create_discovery_scope">
-Use ~/.claude/kata/templates/discovery.md.
+Use $KATA_BASE/templates/discovery.md.
 
 Include:
 

package/kata/workflows/execute-plan.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <purpose>
 Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
 </purpose>
@@ -6,7 +17,7 @@ Execute a phase prompt (PLAN.md) and create the outcome summary (SUMMARY.md).
 Read STATE.md before any operation to load project context.
 Read config.json for planning behavior settings.
 
-@~/.claude/kata/references/git-integration.md
+@$KATA_BASE/references/git-integration.md
 </required_reading>
 
 <process>
@@ -981,7 +992,7 @@ After TDD plan completion, ensure:
 - Standard plans: Multiple tasks, 1 commit per task, 2-4 commits total
 - TDD plans: Single feature, 2-3 commits for RED/GREEN/REFACTOR cycle
 
-See `~/.claude/kata/references/tdd.md` for TDD plan structure.
+See `$KATA_BASE/references/tdd.md` for TDD plan structure.
 </tdd_plan_execution>
 
 <task_commit>
@@ -1156,7 +1167,7 @@ I'll verify after: [verification]
 - If verification passes or N/A: continue to next task
 - If verification fails: inform user, wait for resolution
 
-See ~/.claude/kata/references/checkpoints.md for complete checkpoint guidance.
+See $KATA_BASE/references/checkpoints.md for complete checkpoint guidance.
 </step>
 
 <step name="checkpoint_return_for_orchestrator">
@@ -1290,7 +1301,7 @@ grep -A 50 "^user_setup:" .planning/phases/XX-name/{phase}-{plan}-PLAN.md | head
 
 **If user_setup exists and is not empty:**
 
-Create `.planning/phases/XX-name/{phase}-USER-SETUP.md` using template from `~/.claude/kata/templates/user-setup.md`.
+Create `.planning/phases/XX-name/{phase}-USER-SETUP.md` using template from `$KATA_BASE/templates/user-setup.md`.
 
 **Content generation:**
 
@@ -1351,7 +1362,7 @@ Set `USER_SETUP_CREATED=true` if file was generated, for use in completion messa
 
 <step name="create_summary">
 Create `{phase}-{plan}-SUMMARY.md` as specified in the prompt's `<output>` section.
-Use ~/.claude/kata/templates/summary.md for structure.
+Use $KATA_BASE/templates/summary.md for structure.
 
 **File location:** `.planning/phases/XX-name/{phase}-{plan}-SUMMARY.md`
 

package/kata/workflows/milestone-complete.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <purpose>
 
 Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
@@ -423,7 +434,7 @@ Extract completed milestone details and create archive file.
 
 1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`
 
-2. Read `~/.claude/kata/templates/milestone-archive.md` template
+2. Read `$KATA_BASE/templates/milestone-archive.md` template
 
 3. Extract data from current ROADMAP.md:
    - All phases belonging to this milestone (by phase number range)

package/kata/workflows/phase-execute.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <purpose>
 Execute all plans in a phase using wave-based parallel execution. Orchestrator stays lean by delegating plan execution to subagents.
 </purpose>
@@ -211,10 +222,10 @@ Execute each wave in sequence. Autonomous plans within a wave run in parallel.
    </objective>
 
    <execution_context>
-   @~/.claude/kata/workflows/execute-plan.md
-   @~/.claude/kata/templates/summary.md
-   @~/.claude/kata/references/checkpoints.md
-   @~/.claude/kata/references/tdd.md
+   @$KATA_BASE/workflows/execute-plan.md
+   @$KATA_BASE/templates/summary.md
+   @$KATA_BASE/references/checkpoints.md
+   @$KATA_BASE/references/tdd.md
    </execution_context>
 
    <context>

package/kata/workflows/phase-verify.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <purpose>
 Verify phase goal achievement through goal-backward analysis. Check that the codebase actually delivers what the phase promised, not just that tasks were completed.
 
@@ -18,8 +29,8 @@ Then verify each level against the actual codebase.
 </core_principle>
 
 <required_reading>
-@~/.claude/kata/references/verification-patterns.md
-@~/.claude/kata/templates/verification-report.md
+@$KATA_BASE/references/verification-patterns.md
+@$KATA_BASE/templates/verification-report.md
 </required_reading>
 
 <process>
@@ -564,7 +575,7 @@ Fill template sections:
 9. **Recommended Fix Plans:** If gaps_found
 10. **Verification Metadata:** Approach, timing, counts
 
-See ~/.claude/kata/templates/verification-report.md for complete template.
+See $KATA_BASE/templates/verification-report.md for complete template.
 </step>
 
 <step name="return_to_orchestrator">

package/kata/workflows/resume-project.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <trigger>
 Use this workflow when:
 - Starting a new session on an existing project
@@ -14,7 +25,7 @@ Enables seamless session continuity for fully autonomous workflows.
 </purpose>
 
 <required_reading>
-@~/.claude/kata/references/continuation-format.md
+@$KATA_BASE/references/continuation-format.md
 </required_reading>
 
 <process>

package/kata/workflows/verify-work.md

@@ -1,3 +1,14 @@
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <purpose>
 Validate built features through conversational testing with persistent state. Creates UAT.md that tracks test progress, survives /clear, and feeds gaps into /kata:phase-plan --gaps.
 
@@ -15,7 +26,7 @@ No Pass/Fail buttons. No severity questions. Just: "Here's what should happen. D
 </philosophy>
 
 <template>
-@~/.claude/kata/templates/UAT.md
+@$KATA_BASE/templates/UAT.md
 </template>
 
 <process>
@@ -360,7 +371,7 @@ Spawning parallel debug agents to investigate each issue.
 ```
 
 - Load diagnose-issues workflow
-- Follow @~/.claude/kata/workflows/diagnose-issues.md
+- Follow @$KATA_BASE/workflows/diagnose-issues.md
 - Spawn parallel debug agents for each issue
 - Collect root causes
 - Update UAT.md with root causes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gannonh/kata",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "type": "module",
   "description": "Spec-driven development framework for Claude Code.",
   "scripts": {

package/skills/kata-completing-milestones/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
 
@@ -20,8 +31,8 @@ Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tag
 <execution_context>
 **Load these files NOW (before proceeding):**
 
-- @~/.claude/kata/workflows/milestone-complete.md (main workflow)
-- @~/.claude/kata/templates/milestone-archive.md (archive template)
+- @$KATA_BASE/workflows/milestone-complete.md (main workflow)
+- @$KATA_BASE/templates/milestone-archive.md (archive template)
   </execution_context>
 
 <context>

package/skills/kata-discussing-phases/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Extract implementation decisions that downstream agents need — researcher and planner will use CONTEXT.md to know what to investigate and what choices are locked.
 
@@ -23,8 +34,8 @@ Extract implementation decisions that downstream agents need — researcher and
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/phase-discuss.md
-@~/.claude/kata/templates/context.md
+@$KATA_BASE/workflows/phase-discuss.md
+@$KATA_BASE/templates/context.md
 </execution_context>
 
 <context>

package/skills/kata-executing-phases/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Execute all plans in a phase using wave-based parallel execution.
 
@@ -19,9 +30,9 @@ Context budget: ~15% orchestrator, 100% fresh per subagent.
 </objective>
 
 <execution_context>
-@~/.claude/kata/references/ui-brand.md
-@~/.claude/kata/references/planning-config.md
-@~/.claude/kata/workflows/phase-execute.md
+@$KATA_BASE/references/ui-brand.md
+@$KATA_BASE/references/planning-config.md
+@$KATA_BASE/workflows/phase-execute.md
 </execution_context>
 
 <context>
@@ -279,7 +290,7 @@ Plans with `autonomous: false` have checkpoints. The phase-execute.md workflow h
 - Orchestrator presents to user, collects response
 - Spawns fresh continuation agent (not resume)
 
-See `@~/.claude/kata/workflows/phase-execute.md` step `checkpoint_handling` for complete details.
+See `@$KATA_BASE/workflows/phase-execute.md` step `checkpoint_handling` for complete details.
 </checkpoint_handling>
 
 <deviation_rules>

package/skills/kata-listing-phase-assumptions/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
 
@@ -18,7 +29,7 @@ Output: Conversational output only (no file creation) - ends with "What do you t
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/phase-assumptions.md
+@$KATA_BASE/workflows/phase-assumptions.md
 </execution_context>
 
 <context>

package/skills/kata-mapping-codebases/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Analyze existing codebase using parallel kata-codebase-mapper agents to produce structured codebase documents.
 
@@ -19,7 +30,7 @@ Output: .planning/codebase/ folder with 7 structured documents about the codebas
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/project-analyze.md
+@$KATA_BASE/workflows/project-analyze.md
 </execution_context>
 
 <context>

package/skills/kata-planning-phases/SKILL.md

@@ -10,8 +10,19 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <execution_context>
-@~/.claude/kata/references/ui-brand.md
+@$KATA_BASE/references/ui-brand.md
 </execution_context>
 
 <objective>

package/skills/kata-resuming-work/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Restore complete project context and resume work seamlessly from previous session.
 
@@ -23,11 +34,11 @@ Routes to the resume-project workflow which handles:
   </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/resume-project.md
+@$KATA_BASE/workflows/resume-project.md
 </execution_context>
 
 <process>
-**Follow the resume-project workflow** from `@~/.claude/kata/workflows/resume-project.md`.
+**Follow the resume-project workflow** from `@$KATA_BASE/workflows/resume-project.md`.
 
 The workflow handles all resumption logic including:
 

package/skills/kata-showing-whats-new/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Display changes between installed version and latest available version.
 
@@ -57,7 +68,7 @@ Use WebFetch tool with:
 **If fetch fails:**
 Fall back to local changelog:
 ```bash
-cat ~/.claude/kata/CHANGELOG.md 2>/dev/null
+cat $KATA_BASE/CHANGELOG.md 2>/dev/null
 ```
 
 Note to user: "Couldn't check for updates (offline or GitHub unavailable). Showing local changelog."

package/skills/kata-starting-milestones/SKILL.md

@@ -12,6 +12,17 @@ allowed-tools:
   - AskUserQuestion
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Start a new milestone through unified flow: questioning → research (optional) → requirements → roadmap.
 
@@ -28,10 +39,10 @@ This is the brownfield equivalent of project-new. The project exists, PROJECT.md
 </objective>
 
 <execution_context>
-@~/.claude/kata/references/questioning.md
-@~/.claude/kata/references/ui-brand.md
-@~/.claude/kata/templates/project.md
-@~/.claude/kata/templates/requirements.md
+@$KATA_BASE/references/questioning.md
+@$KATA_BASE/references/ui-brand.md
+@$KATA_BASE/templates/project.md
+@$KATA_BASE/templates/requirements.md
 </execution_context>
 
 <context>
@@ -218,7 +229,7 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 
 <output>
 Write to: .planning/research/STACK.md
-Use template: ~/.claude/kata/templates/research-project/STACK.md
+Use template: $KATA_BASE/templates/research-project/STACK.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Stack research")
 
@@ -259,7 +270,7 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 
 <output>
 Write to: .planning/research/FEATURES.md
-Use template: ~/.claude/kata/templates/research-project/FEATURES.md
+Use template: $KATA_BASE/templates/research-project/FEATURES.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Features research")
 
@@ -301,7 +312,7 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 
 <output>
 Write to: .planning/research/ARCHITECTURE.md
-Use template: ~/.claude/kata/templates/research-project/ARCHITECTURE.md
+Use template: $KATA_BASE/templates/research-project/ARCHITECTURE.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Architecture research")
 
@@ -339,7 +350,7 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 
 <output>
 Write to: .planning/research/PITFALLS.md
-Use template: ~/.claude/kata/templates/research-project/PITFALLS.md
+Use template: $KATA_BASE/templates/research-project/PITFALLS.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Pitfalls research")
 ```
@@ -362,7 +373,7 @@ Read these files:
 
 <output>
 Write to: .planning/research/SUMMARY.md
-Use template: ~/.claude/kata/templates/research-project/SUMMARY.md
+Use template: $KATA_BASE/templates/research-project/SUMMARY.md
 Commit after writing.
 </output>
 ", subagent_type="kata-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")

package/skills/kata-starting-projects/SKILL.md

@@ -12,6 +12,17 @@ allowed-tools:
   - AskUserQuestion
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 
 Initialize a new project through unified flow: questioning → research (optional) → requirements → roadmap.
@@ -32,10 +43,10 @@ This is the most leveraged moment in any project. Deep questioning here means be
 
 <execution_context>
 
-@~/.claude/kata/references/questioning.md
-@~/.claude/kata/references/ui-brand.md
-@~/.claude/kata/templates/project.md
-@~/.claude/kata/templates/requirements.md
+@$KATA_BASE/references/questioning.md
+@$KATA_BASE/references/ui-brand.md
+@$KATA_BASE/templates/project.md
+@$KATA_BASE/templates/requirements.md
 
 </execution_context>
 
@@ -676,7 +687,7 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 
 <output>
 Write to: .planning/research/STACK.md
-Use template: ~/.claude/kata/templates/research-project/STACK.md
+Use template: $KATA_BASE/templates/research-project/STACK.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Stack research")
 
@@ -715,7 +726,7 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 
 <output>
 Write to: .planning/research/FEATURES.md
-Use template: ~/.claude/kata/templates/research-project/FEATURES.md
+Use template: $KATA_BASE/templates/research-project/FEATURES.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Features research")
 
@@ -754,7 +765,7 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 
 <output>
 Write to: .planning/research/ARCHITECTURE.md
-Use template: ~/.claude/kata/templates/research-project/ARCHITECTURE.md
+Use template: $KATA_BASE/templates/research-project/ARCHITECTURE.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Architecture research")
 
@@ -793,7 +804,7 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 
 <output>
 Write to: .planning/research/PITFALLS.md
-Use template: ~/.claude/kata/templates/research-project/PITFALLS.md
+Use template: $KATA_BASE/templates/research-project/PITFALLS.md
 </output>
 ", subagent_type="kata-project-researcher", model="{researcher_model}", description="Pitfalls research")
 ```
@@ -816,7 +827,7 @@ Read these files:
 
 <output>
 Write to: .planning/research/SUMMARY.md
-Use template: ~/.claude/kata/templates/research-project/SUMMARY.md
+Use template: $KATA_BASE/templates/research-project/SUMMARY.md
 Commit after writing.
 </output>
 ", subagent_type="kata-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")

package/skills/kata-updating/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Check for Kata updates, install if available, and display what changed.
 
@@ -22,7 +33,8 @@ Provides a better update experience than raw `npx @gannonh/kata` by showing vers
 Read installed version:
 
 ```bash
-cat ~/.claude/kata/VERSION 2>/dev/null
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi)
+cat $KATA_BASE/VERSION 2>/dev/null
 ```
 
 **If VERSION file missing:**

package/skills/kata-verifying-work/SKILL.md

@@ -10,6 +10,17 @@ allowed-tools:
   - Bash
 ---
 
+<kata_path>
+**IMPORTANT:** Before reading any Kata file (templates, references, workflows), resolve the base path:
+
+```bash
+KATA_BASE=$(if [ -n "$CLAUDE_PLUGIN_ROOT" ]; then echo "$CLAUDE_PLUGIN_ROOT/kata"; elif [ -d ~/.claude/kata ]; then echo ~/.claude/kata; else echo ./.claude/kata; fi) && echo $KATA_BASE
+```
+
+Use the output as `$KATA_BASE` for all file paths below. For example:
+- `$KATA_BASE/templates/summary.md` instead of `~/.claude/kata/templates/summary.md`
+</kata_path>
+
 <objective>
 Validate built features through conversational testing with persistent state.
 
@@ -19,8 +30,8 @@ Output: {phase}-UAT.md tracking all test results. If issues found: diagnosed gap
 </objective>
 
 <execution_context>
-@~/.claude/kata/workflows/verify-work.md
-@~/.claude/kata/templates/UAT.md
+@$KATA_BASE/workflows/verify-work.md
+@$KATA_BASE/templates/UAT.md
 </execution_context>
 
 <context>