@leeovery/claude-technical-workflows 2.1.4 → 2.1.6

package/agents/implementation-polish.md

@@ -0,0 +1,188 @@
+---
+name: implementation-polish
+description: Performs holistic quality analysis over a completed implementation, discovering cross-task issues through multi-pass analysis and orchestrating fixes via the executor and reviewer agents. Invoked by technical-implementation skill after all tasks complete.
+tools: Read, Glob, Grep, Bash, Task
+model: opus
+---
+
+# Implementation Polish
+
+Act as a **senior developer** performing a holistic quality pass over a plan's implementation. This plan is one piece of a larger system — it implements a specific feature or capability, not the entire application. Other plans handle other features. Your scope is strictly what this plan built, not what the broader system might be missing.
+
+You've inherited a codebase built by a team — each member did solid work on their piece, but nobody has reviewed the whole picture. You discover issues through focused analysis, then orchestrate fixes through the executor and reviewer agents.
+
+## Your Input
+
+You receive file paths and context via the orchestrator's prompt:
+
+1. **code-quality.md path** — Quality standards (also passed to executor)
+2. **tdd-workflow.md path** — TDD cycle rules (passed to executor)
+3. **Specification path** — What was intended — design decisions and rationale
+4. **Plan file path** — What was built — the full task landscape
+5. **Plan format reading.md path** — How to read tasks from the plan (format-specific adapter)
+6. **Integration context file path** — Accumulated decisions and patterns from every task
+7. **Project skill paths** — Framework conventions
+
+On **re-invocation after user feedback**, additionally include:
+
+8. **User feedback** — the user's comments on what to change or focus on
+
+## Hard Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the work.**
+
+1. **No direct code changes** — dispatch the executor for all modifications. You are discovery and orchestration.
+2. **No new features** — only improve what exists. Nothing that isn't in the plan.
+3. **Plan scope only** — work within the plan's boundary. Do not flag missing features that belong to other plans (e.g., "this app lacks authentication" when authentication is a separate plan). Do not look outward for gaps in the broader system — only inward at what this plan built.
+4. **No git writes** — do not commit, stage, or interact with git. Reading git history and diffs is fine. The orchestrator handles all git operations.
+5. **Proportional** — prioritize high-impact changes. Don't spend effort on trivial style differences.
+6. **Existing tests are protected** — if a refactor breaks existing tests, the refactor is wrong. Only mechanical test updates (renames, moves) and new integration tests are allowed.
+7. **Minimum 2 cycles** — always complete at least 2 full discovery-fix cycles. A single pass is never sufficient.
+
+---
+
+## Step 1: Absorb Context
+
+Read and absorb the following. Do not write any code or dispatch any agents during this step.
+
+1. **Read code-quality.md** — absorb quality standards
+2. **Read specification** (if provided) — understand design intent
+3. **Read project skills** — absorb framework conventions
+4. **Read the plan format's reading.md** — understand how to retrieve tasks from the plan
+5. **Read the plan** — follow the reading adapter's instructions to retrieve all completed tasks. Understand the full scope: phases, tasks, acceptance criteria, what was built
+6. **Read the integration context file** — understand patterns, helpers, and conventions from all tasks
+
+→ Proceed to **Step 2**.
+
+---
+
+## Step 2: Identify Implementation Scope
+
+Find all files changed during implementation. Use git history, the plan's task list, and the integration context to build a complete picture of what was touched. Read and understand the full implemented codebase.
+
+Build a definitive list of implementation files. This list is passed to analysis sub-agents in subsequent steps.
+
+→ Proceed to **Step 3**.
+
+---
+
+## Step 3: Discovery-Fix Loop
+
+Execute discovery-fix cycles. Minimum **2** cycles, maximum **5** cycles. Each cycle follows stages A through G sequentially. Always start at **A. Cycle Gate**.
+
+### A. Cycle Gate
+
+Increment the cycle count.
+
+If cycle count > 5 → exit loop, proceed to **Step 4**.
+
+If cycle count > 2 and the previous cycle's discovery found zero actionable issues → exit loop, proceed to **Step 4**.
+
+Otherwise → proceed to **B. Dispatch Fixed Analysis Passes**.
+
+### B. Dispatch Fixed Analysis Passes
+
+Dispatch all three analysis sub-agents **in parallel** via Task tool. Each sub-agent receives:
+- The list of implementation files (from Step 2)
+- The specific analysis focus (below)
+- Instruction to return findings as a structured list with file:line references
+
+**Sub-agent 1 — Code Cleanup:**
+Analyze all implementation files for: unused imports/variables/dead code, naming quality (abbreviation overuse, unclear names, inconsistent naming across files), formatting inconsistencies across the implementation. Compare naming conventions between files written by different tasks — flag drift.
+
+**Sub-agent 2 — Structural Cohesion:**
+Analyze all implementation files for: duplicated logic across task boundaries that should be extracted, class/module responsibilities (too much in one class, or unnecessarily fragmented across many), design patterns that are now obvious with the full picture but weren't visible to individual task executors, over-engineering (abstractions nobody uses) or under-engineering (raw code that should be extracted).
+
+**Sub-agent 3 — Cross-Task Integration:**
+Analyze all implementation files for: shared code paths where multiple tasks contributed behavior — verify the merged result is correct, workflow seams where one task's output feeds another's input — verify the handoff works, interface mismatches between producer and consumer (type mismatches, missing fields, wrong assumptions), gaps in integration test coverage for cross-task workflows.
+
+**STOP.** Do not proceed until all three sub-agents have returned their findings.
+
+→ Proceed to **C. Dispatch Dynamic Analysis Passes**.
+
+### C. Dispatch Dynamic Analysis Passes
+
+Review the findings from the fixed passes and the codebase. Based on what you find — language, framework, project conventions, areas flagged by fixed passes — determine whether additional targeted analysis is needed.
+
+If no dynamic passes are needed → proceed to **D. Synthesize Findings**.
+
+If dynamic passes are needed, dispatch sub-agents for deeper analysis. Examples: language-specific idiom checks, convention consistency across early and late tasks, deeper investigation into specific areas. Each dynamic sub-agent receives the relevant file subset and a focused analysis prompt, same as fixed passes.
+
+**STOP.** Do not proceed until all dynamic sub-agents have returned their findings.
+
+→ Proceed to **D. Synthesize Findings**.
+
+### D. Synthesize Findings
+
+Collect findings from all analysis passes (fixed and dynamic). Deduplicate, discard low-value nitpicks, and prioritize by impact.
+
+If no actionable findings remain → proceed to **G. Cycle Complete** (no fix needed this cycle).
+
+If actionable findings exist → proceed to **E. Invoke Executor**.
+
+### E. Invoke Executor
+
+Craft a task description covering the prioritized fixes. Include the following **test rules** in the task description — these constrain what test changes the executor may make during polish:
+- Write NEW integration tests for cross-task workflows — yes
+- Modify existing tests for mechanical changes (renames, moves) — yes
+- Modify existing tests semantically (different behavior) — no. If a refactor breaks existing tests, the refactor is wrong. Revert it.
+
+Invoke the `implementation-task-executor` agent (`implementation-task-executor.md`) with:
+- The crafted task description (including test rules) as task content
+- tdd-workflow.md path
+- code-quality.md path
+- Specification path (if available)
+- Project skill paths
+- Plan file path
+- Integration context file path
+
+**STOP.** Do not proceed until the executor has returned its result.
+
+On receipt of result, route on STATUS:
+- `blocked` or `failed` → record in SKIPPED with the executor's ISSUES. Proceed to **G. Cycle Complete**.
+- `complete` → proceed to **F. Invoke Reviewer**.
+
+### F. Invoke Reviewer
+
+Invoke the `implementation-task-reviewer` agent (`implementation-task-reviewer.md`) to independently verify the executor's work. Include the test rules in the reviewer's prompt so it can flag violations. Pass:
+- Specification path
+- The same task description used for the executor (including test rules)
+- Project skill paths
+- Integration context file path
+
+**STOP.** Do not proceed until the reviewer has returned its result.
+
+On receipt of result, route on VERDICT:
+- `approved` → proceed to **G. Cycle Complete**
+- `needs-changes` → return to **E. Invoke Executor** with the reviewer's feedback. Maximum 3 fix attempts per cycle — if not converged after 3, record remaining issues in SKIPPED and proceed to **G. Cycle Complete**.
+
+### G. Cycle Complete
+
+Record what was discovered and fixed this cycle.
+
+→ Return to **A. Cycle Gate**.
+
+---
+
+## Step 4: Return Report
+
+Return a structured report:
+
+```
+STATUS: complete | blocked
+SUMMARY: {overview — what was analyzed, key findings, what was fixed}
+CYCLES: {number of discovery-fix cycles completed}
+DISCOVERY:
+- {findings from analysis passes, organized by category}
+FIXES_APPLIED:
+- {what was changed and why, with file:line references}
+TESTS_ADDED:
+- {integration tests written, what workflows they exercise}
+SKIPPED:
+- {issues found but not addressed — too risky, needs design decision, or low impact}
+TEST_RESULTS: {all passing | failures — details}
+```
+
+- If STATUS is `blocked`, SUMMARY **must** explain what decision is needed.
+- If STATUS is `complete`, all applied fixes must have passing tests.
+- SKIPPED captures issues that were found but intentionally not addressed — too risky, needs a design decision, or low impact relative to effort.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.1.4",
+  "version": "2.1.6",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/link-dependencies/SKILL.md

@@ -102,7 +102,7 @@ For each unresolved dependency:
 
 2. **If plan exists**: Load the format's reading reference
    - Read `format:` from the dependency plan's frontmatter
-   - Load `.claude/skills/technical-planning/references/output-formats/{format}/reading.md`
+   - Load `../technical-planning/references/output-formats/{format}/reading.md`
    - Use the task extraction instructions to search for matching tasks
 
 3. **Handle ambiguous matches**:
@@ -117,7 +117,7 @@ For each resolved match:
    - Change the dependency's `state: unresolved` to `state: resolved` and add `task_id: {task-id}`
 
 2. **Create dependency in output format**:
-   - Load `.claude/skills/technical-planning/references/output-formats/{format}/graph.md`
+   - Load `../technical-planning/references/output-formats/{format}/graph.md`
    - Follow the "Adding a Dependency" section to create the blocking relationship
 
 ## Step 6: Bidirectional Check

package/skills/migrate/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: migrate
 description: "Run migrations to keep workflow files in sync with the current system design. This skill is mandatory before running any workflow skill."
-allowed-tools: Bash(.claude/scripts/migrate.sh)
+allowed-tools: Bash(../../scripts/migrate.sh)
 ---
 
 # Migrate
@@ -13,7 +13,7 @@ Keeps your workflow files up to date with how the system is designed to work. Ru
 Run the migration script:
 
 ```bash
-.claude/scripts/migrate.sh
+../../scripts/migrate.sh
 ```
 
 ### If files were updated

package/skills/start-discussion/SKILL.md

@@ -2,7 +2,7 @@
 name: start-discussion
 description: "Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/scripts/discovery-for-discussion.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
+allowed-tools: Bash(../../scripts/discovery-for-discussion.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/research-analysis.md)
 ---
 
 Invoke the **technical-discussion** skill for this conversation.
@@ -55,7 +55,7 @@ Invoke the `/migrate` skill and assess its output.
 Run the discovery script to gather current state:
 
 ```bash
-.claude/scripts/discovery-for-discussion.sh
+../../scripts/discovery-for-discussion.sh
 ```
 
 This outputs structured YAML. Parse it to understand:

package/skills/start-implementation/SKILL.md

@@ -2,7 +2,7 @@
 name: start-implementation
 description: "Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/scripts/discovery-for-implementation-and-review.sh)
+allowed-tools: Bash(../../scripts/discovery-for-implementation-and-review.sh)
 ---
 
 Invoke the **technical-implementation** skill for this conversation.
@@ -55,7 +55,7 @@ Invoke the `/migrate` skill and assess its output.
 Run the discovery script to gather current state:
 
 ```bash
-.claude/scripts/discovery-for-implementation-and-review.sh
+../../scripts/discovery-for-implementation-and-review.sh
 ```
 
 This outputs structured YAML. Parse it to understand:

package/skills/start-planning/SKILL.md

@@ -2,7 +2,7 @@
 name: start-planning
 description: "Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/scripts/discovery-for-planning.sh)
+allowed-tools: Bash(../../scripts/discovery-for-planning.sh)
 ---
 
 Invoke the **technical-planning** skill for this conversation.
@@ -55,7 +55,7 @@ Invoke the `/migrate` skill and assess its output.
 Run the discovery script to gather current state:
 
 ```bash
-.claude/scripts/discovery-for-planning.sh
+../../scripts/discovery-for-planning.sh
 ```
 
 This outputs structured YAML. Parse it to understand:

package/skills/start-review/SKILL.md

@@ -2,7 +2,7 @@
 name: start-review
 description: "Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/scripts/discovery-for-implementation-and-review.sh)
+allowed-tools: Bash(../../scripts/discovery-for-implementation-and-review.sh)
 ---
 
 Invoke the **technical-review** skill for this conversation.
@@ -55,7 +55,7 @@ Invoke the `/migrate` skill and assess its output.
 Run the discovery script to gather current state:
 
 ```bash
-.claude/scripts/discovery-for-implementation-and-review.sh
+../../scripts/discovery-for-implementation-and-review.sh
 ```
 
 This outputs structured YAML. Parse it to understand:

package/skills/start-specification/SKILL.md

@@ -2,7 +2,7 @@
 name: start-specification
 description: "Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill."
 disable-model-invocation: true
-allowed-tools: Bash(.claude/scripts/discovery-for-specification.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
+allowed-tools: Bash(../../scripts/discovery-for-specification.sh), Bash(mkdir -p docs/workflow/.cache), Bash(rm docs/workflow/.cache/discussion-consolidation-analysis.md)
 ---
 
 Invoke the **technical-specification** skill for this conversation.
@@ -55,7 +55,7 @@ Invoke the `/migrate` skill and assess its output.
 Run the discovery script to gather current state:
 
 ```bash
-.claude/scripts/discovery-for-specification.sh
+../../scripts/discovery-for-specification.sh
 ```
 
 This outputs structured YAML. Parse it to understand:

package/skills/technical-discussion/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: technical-discussion
 description: "Document technical discussions as expert architect and meeting assistant. Capture context, decisions, edge cases, debates, and rationale without jumping to specification or implementation. Use when: (1) Users discuss/explore/debate architecture or design, (2) Working through edge cases before specification, (3) Need to document technical decisions and their rationale, (4) Capturing competing solutions and why choices were made. Creates documentation in docs/workflow/discussion/{topic}.md that can be used to build validated specifications."
+user-invocable: false
 ---
 
 # Technical Discussion

package/skills/technical-implementation/SKILL.md

@@ -1,14 +1,15 @@
 ---
 name: technical-implementation
 description: "Orchestrate implementation of plans using agent-based TDD workflow with per-task review and approval gate (auto mode available). Use when: (1) Implementing a plan from docs/workflow/planning/{topic}.md, (2) User says 'implement', 'build', or 'code this' with a plan available, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Dispatches executor and reviewer agents per task, commits after review approval."
+user-invocable: false
 ---
 
 # Technical Implementation
 
 Orchestrate implementation by dispatching **executor** and **reviewer** agents per task. Each agent invocation starts fresh — flat context, no accumulated state.
 
-- **Executor** (`.claude/agents/implementation-task-executor.md`) — implements one task via strict TDD
-- **Reviewer** (`.claude/agents/implementation-task-reviewer.md`) — independently verifies the task (opus)
+- **Executor** (`../../agents/implementation-task-executor.md`) — implements one task via strict TDD
+- **Reviewer** (`../../agents/implementation-task-reviewer.md`) — independently verifies the task (opus)
 
 The orchestrator owns: plan reading, task extraction, agent invocation, git operations, tracking, task gates.
 
@@ -100,7 +101,7 @@ Save their instructions to `docs/workflow/environment-setup.md` (or "No special
 
 1. Read the plan from the provided location (typically `docs/workflow/planning/{topic}.md`)
 2. Plans can be stored in various formats. The `format` field in the plan's frontmatter identifies which format this plan uses.
-3. Load the format's per-concern adapter files from `.claude/skills/technical-planning/references/output-formats/{format}/`:
+3. Load the format's per-concern adapter files from `../technical-planning/references/output-formats/{format}/`:
    - **reading.md** — how to read tasks from the plan
    - **updating.md** — how to write progress to the plan
 4. If no `format` field exists, ask the user which format the plan uses.
@@ -209,7 +210,81 @@ Load **[steps/task-loop.md](references/steps/task-loop.md)** and follow its inst
 
 ---
 
-## Step 6: Mark Implementation Complete
+## Step 6: Polish
+
+If the task loop exited early (user chose `stop`), skip to **Step 7**.
+
+**Git checkpoint** — ensure a clean working tree before invoking the polish agent. Run `git status`. If there are unstaged changes or untracked files, commit them:
+
+```
+impl({topic}): pre-polish checkpoint
+```
+
+This ensures all prior work is safely committed. The polish agent makes no git operations — all its changes will exist as unstaged modifications. If the user discards polish, the working tree resets cleanly to this checkpoint.
+
+**Invoke the polish agent:**
+
+1. Load **[steps/invoke-polish.md](references/steps/invoke-polish.md)** and follow its instructions.
+2. **STOP.** Do not proceed until the polish agent has returned its result.
+3. Route on STATUS:
+   - `blocked` → present SUMMARY to the user, ask how to proceed
+   - `complete` → present the report below
+
+> **Implementation polish complete** ({N} cycles)
+>
+> {SUMMARY}
+>
+> Findings:
+> {DISCOVERY}
+>
+> Fixes applied:
+> {FIXES_APPLIED}
+>
+> Integration tests added:
+> {TESTS_ADDED}
+>
+> Skipped (not addressed):
+> {SKIPPED}
+>
+> Test results: {TEST_RESULTS}
+>
+> · · ·
+>
+> - **`y`/`yes`** — Approve and commit polish changes
+> - **`s`/`skip`** — Discard polish changes, mark complete as-is
+> - **Comment** — Feedback (re-invokes polish agent with your notes)
+
+**STOP.** Wait for user input.
+
+#### If `yes`
+
+Commit all polish changes:
+
+```
+impl({topic}): polish — {brief description}
+```
+
+→ Proceed to **Step 7**.
+
+#### If `skip`
+
+Discard all polish changes. Reset the working tree to the pre-polish checkpoint:
+
+```
+git checkout . && git clean -fd
+```
+
+This is safe because the checkpoint commit captured all prior work. Only polish-created changes are discarded. Gitignored files are untouched.
+
+→ Proceed to **Step 7**.
+
+#### If comment
+
+→ Re-invoke the polish agent with the user's feedback. Return to the top of **Step 6** (after the git checkpoint — do not re-checkpoint).
+
+---
+
+## Step 7: Mark Implementation Complete
 
 Update the tracking file (`docs/workflow/implementation/{topic}.md`):
 - Set `status: completed`
@@ -226,6 +301,7 @@ Commit: `impl({topic}): complete implementation`
 - **[steps/task-loop.md](references/steps/task-loop.md)** — Task execution loop, task gates, tracking, commits
 - **[steps/invoke-executor.md](references/steps/invoke-executor.md)** — How to invoke the executor agent
 - **[steps/invoke-reviewer.md](references/steps/invoke-reviewer.md)** — How to invoke the reviewer agent
+- **[steps/invoke-polish.md](references/steps/invoke-polish.md)** — How to invoke the polish agent
 - **[task-normalisation.md](references/task-normalisation.md)** — Normalised task shape for agent invocation
 - **[tdd-workflow.md](references/tdd-workflow.md)** — TDD cycle (passed to executor agent)
 - **[code-quality.md](references/code-quality.md)** — Quality standards (passed to executor agent)

package/skills/technical-implementation/references/environment-setup.md

@@ -55,7 +55,7 @@ If the environment setup document contains only "No special setup required" (or
 Some plan formats require specific tools. Check the plan's `format` field and load the format's about file for setup instructions:
 
 ```
-.claude/skills/technical-planning/references/output-formats/{format}/about.md
+../../technical-planning/references/output-formats/{format}/about.md
 ```
 
 Each format's about.md contains prerequisites and installation instructions.

package/skills/technical-implementation/references/steps/invoke-executor.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step invokes the `implementation-task-executor` agent (`.claude/agents/implementation-task-executor.md`) to implement one task.
+This step invokes the `implementation-task-executor` agent (`../../../../agents/implementation-task-executor.md`) to implement one task.
 
 ---
 
@@ -12,8 +12,8 @@ This step invokes the `implementation-task-executor` agent (`.claude/agents/impl
 
 **Every invocation** — initial or re-attempt — includes these file paths:
 
-1. **tdd-workflow.md**: `.claude/skills/technical-implementation/references/tdd-workflow.md`
-2. **code-quality.md**: `.claude/skills/technical-implementation/references/code-quality.md`
+1. **tdd-workflow.md**: `../tdd-workflow.md`
+2. **code-quality.md**: `../code-quality.md`
 3. **Specification path**: from the plan's frontmatter (if available)
 4. **Project skill paths**: from `project_skills` in the implementation tracking file
 5. **Task content**: normalised task content (see [task-normalisation.md](../task-normalisation.md))

package/skills/technical-implementation/references/steps/invoke-polish.md

@@ -0,0 +1,51 @@
+# Invoke Polish
+
+*Reference for **[technical-implementation](../../SKILL.md)***
+
+---
+
+This step invokes the `implementation-polish` agent (`../../../../agents/implementation-polish.md`) to perform holistic quality analysis and orchestrate fixes after all tasks are complete.
+
+---
+
+## Invoke the Agent
+
+**Every invocation** includes these file paths:
+
+1. **code-quality.md**: `../code-quality.md`
+2. **tdd-workflow.md**: `../tdd-workflow.md`
+3. **Specification path**: from the plan's frontmatter (if available)
+4. **Plan file path**: the implementation plan
+5. **Plan format reading.md**: `../../../technical-planning/references/output-formats/{format}/reading.md` (format from plan frontmatter)
+6. **Integration context file**: `docs/workflow/implementation/{topic}-context.md`
+7. **Project skill paths**: from `project_skills` in the implementation tracking file
+
+**Re-invocation after user feedback** additionally includes:
+
+8. **User feedback**: the user's comments on what to change or focus on
+
+The polish agent is stateless — each invocation starts fresh. Always pass all inputs.
+
+---
+
+## Expected Result
+
+The agent returns a structured report:
+
+```
+STATUS: complete | blocked
+SUMMARY: {overview — what was analyzed, key findings, what was fixed}
+CYCLES: {number of discovery-fix cycles completed}
+DISCOVERY:
+- {findings from analysis passes, organized by category}
+FIXES_APPLIED:
+- {what was changed and why, with file:line references}
+TESTS_ADDED:
+- {integration tests written, what workflows they exercise}
+SKIPPED:
+- {issues found but not addressed — too risky, needs design decision, or low impact}
+TEST_RESULTS: {all passing | failures — details}
+```
+
+- `complete`: all applied fixes have passing tests, discovery-fix loop finished
+- `blocked`: SUMMARY explains what decision is needed

package/skills/technical-implementation/references/steps/invoke-reviewer.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step invokes the `implementation-task-reviewer` agent (`.claude/agents/implementation-task-reviewer.md`) to independently verify a completed task.
+This step invokes the `implementation-task-reviewer` agent (`../../../../agents/implementation-task-reviewer.md`) to independently verify a completed task.
 
 ---
 

package/skills/technical-planning/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: technical-planning
 description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from docs/workflow/specification/{topic}.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/planning/{topic}.md that can be executed via strict TDD."
+user-invocable: false
 ---
 
 # Technical Planning

package/skills/technical-planning/references/steps/analyze-task-graph.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step uses the `planning-dependency-grapher` agent (`.claude/agents/planning-dependency-grapher.md`) to analyze all authored tasks, establish internal dependencies, assign priorities, and detect cycles. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-dependency-grapher` agent (`../../../../agents/planning-dependency-grapher.md`) to analyze all authored tasks, establish internal dependencies, assign priorities, and detect cycles. You invoke the agent, present its output, and handle the approval gate.
 
 ---
 

package/skills/technical-planning/references/steps/author-tasks.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step uses the `planning-task-author` agent (`.claude/agents/planning-task-author.md`) to write full detail for a single task. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-task-author` agent (`../../../../agents/planning-task-author.md`) to write full detail for a single task. You invoke the agent, present its output, and handle the approval gate.
 
 ---
 
@@ -14,14 +14,14 @@ This step uses the `planning-task-author` agent (`.claude/agents/planning-task-a
 
 Invoke `planning-task-author` with these file paths:
 
-1. **read-specification.md**: `.claude/skills/technical-planning/references/read-specification.md`
+1. **read-specification.md**: `../read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
-4. **task-design.md**: `.claude/skills/technical-planning/references/task-design.md`
+4. **task-design.md**: `../task-design.md`
 5. **All approved phases**: the complete phase structure from the Plan Index File body
 6. **Task list for current phase**: the approved task table
 7. **Target task**: the task name, edge cases, and ID from the table
-8. **Output format authoring reference**: path to the format's `authoring.md` (e.g., `.claude/skills/technical-planning/references/output-formats/{format}/authoring.md`)
+8. **Output format authoring reference**: path to the format's `authoring.md` (e.g., `../output-formats/{format}/authoring.md`)
 
 ### Present the Output
 

package/skills/technical-planning/references/steps/define-phases.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step uses the `planning-phase-designer` agent (`.claude/agents/planning-phase-designer.md`) to define or review the phase structure. Whether phases are being designed for the first time or reviewed from a previous session, the process converges on the same approval gate.
+This step uses the `planning-phase-designer` agent (`../../../../agents/planning-phase-designer.md`) to define or review the phase structure. Whether phases are being designed for the first time or reviewed from a previous session, the process converges on the same approval gate.
 
 ---
 
@@ -30,11 +30,11 @@ Orient the user:
 
 Invoke `planning-phase-designer` with these file paths:
 
-1. **read-specification.md**: `.claude/skills/technical-planning/references/read-specification.md`
+1. **read-specification.md**: `../read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
-4. **phase-design.md**: `.claude/skills/technical-planning/references/phase-design.md`
-5. **task-design.md**: `.claude/skills/technical-planning/references/task-design.md`
+4. **phase-design.md**: `../phase-design.md`
+5. **task-design.md**: `../task-design.md`
 
 The agent returns a complete phase structure. Write it directly to the Plan Index File body.
 

package/skills/technical-planning/references/steps/define-tasks.md

@@ -4,7 +4,7 @@
 
 ---
 
-This step uses the `planning-task-designer` agent (`.claude/agents/planning-task-designer.md`) to design a task list for a single phase. You invoke the agent, present its output, and handle the approval gate.
+This step uses the `planning-task-designer` agent (`../../../../agents/planning-task-designer.md`) to design a task list for a single phase. You invoke the agent, present its output, and handle the approval gate.
 
 ---
 
@@ -18,10 +18,10 @@ Orient the user:
 
 Invoke `planning-task-designer` with these file paths:
 
-1. **read-specification.md**: `.claude/skills/technical-planning/references/read-specification.md`
+1. **read-specification.md**: `../read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
-4. **task-design.md**: `.claude/skills/technical-planning/references/task-design.md`
+4. **task-design.md**: `../task-design.md`
 5. **All approved phases**: the complete phase structure from the Plan Index File body
 6. **Target phase number**: the phase being broken into tasks
 

package/skills/technical-research/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: technical-research
 description: "Explore ideas, validate concepts, and research broadly across technical, business, and market domains. Use when: (1) User has a new idea to explore, (2) Need to research a topic deeply, (3) Validating feasibility - technical, business, or market, (4) Learning and exploration without necessarily building anything, (5) User says 'research this' or 'explore this idea', (6) Brain dumping early thoughts before formal discussion. Creates research documents in docs/workflow/research/ that may feed into discussion or specification."
+user-invocable: false
 ---
 
 # Technical Research

package/skills/technical-review/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: technical-review
 description: "Validate completed implementation against plan tasks and acceptance criteria. Use when: (1) Implementation is complete, (2) User wants validation before merging/shipping, (3) Quality gate check needed after implementation. Reviews ALL plan tasks for implementation correctness, test adequacy, and code quality. Produces structured feedback (approve, request changes, or comments) - does NOT fix code."
+user-invocable: false
 ---
 
 # Technical Review

package/skills/technical-specification/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: technical-specification
 description: "Build validated specifications from source material through collaborative refinement. Use when: (1) User asks to create/build a specification from source material, (2) User wants to validate and refine content before planning, (3) Converting source material (discussions, research, requirements) into standalone specifications, (4) User says 'specify this' or 'create a spec', (5) Need to filter hallucinations and enrich gaps before formal planning. Creates specifications in docs/workflow/specification/{topic}.md that can be used to build implementation plans."
+user-invocable: false
 ---
 
 # Technical Specification

package/skills/view-plan/SKILL.md

@@ -25,7 +25,7 @@ Read the plan file from `docs/workflow/planning/{topic}.md` and check the `forma
 Load the format's reading reference:
 
 ```
-.claude/skills/technical-planning/references/output-formats/{format}/reading.md
+../technical-planning/references/output-formats/{format}/reading.md
 ```
 
 This file contains instructions for reading plans in that format.