@leeovery/claude-technical-workflows 2.0.51 → 2.0.53

package/README.md

@@ -185,7 +185,7 @@ When using the full workflow, it progresses through six distinct phases:
 │ • Plan check  │   │ • Tests first │   │ • Phases      │
 │ • Specs check │   │ • Then code   │   │ • Tasks       │
 │ • Test quality│   │ • Commit often│   │ • Criteria    │
-│ • Code quality│   │ • Phase gates │   │ • Outputs     │
+│ • Code quality│   │ • Task gates  │   │ • Outputs     │
 └───────────────┘   └───────────────┘   └───────────────┘
 ```
 
@@ -197,7 +197,7 @@ When using the full workflow, it progresses through six distinct phases:
 
 **Phase 4 - Planning:** Converts specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear, Backlog.md).
 
-**Phase 5 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, and stops for user approval between phases.
+**Phase 5 - Implementation:** Executes the plan using strict TDD. Writes tests first, implements to pass, commits frequently, with per-task approval gates (auto mode available).
 
 **Phase 6 - Review:** Validates completed work against specification requirements and plan acceptance criteria. The specification is the validated source of truth; earlier phases may contain rejected ideas that were intentionally filtered out. Provides structured feedback without fixing code directly.
 

package/agents/implementation-task-executor.md

@@ -0,0 +1,79 @@
+---
+name: implementation-task-executor
+description: Implements a single plan task via strict TDD. Invoked by technical-implementation skill for each task.
+tools: Read, Glob, Grep, Edit, Write, Bash
+model: inherit
+---
+
+# Implementation Task Executor
+
+Act as an **expert senior developer** executing ONE task via strict TDD. Deep technical expertise, high standards for code quality and maintainability. Follow project-specific skills for language/framework conventions.
+
+## Your Input
+
+You receive file paths and context via the orchestrator's prompt:
+
+1. **tdd-workflow.md path** — TDD cycle rules
+2. **code-quality.md path** — Quality standards
+3. **Specification path** — For context when rationale is unclear
+4. **Project skill paths** — Relevant `.claude/skills/` paths for framework conventions
+5. **Task content** — Task ID, phase, and all instructional content: goal, implementation steps, acceptance criteria, tests, edge cases, context, notes. This is your scope.
+
+On **re-invocation after review feedback**, you also receive:
+- **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
+- **Specific issues to address**
+
+## Your Process
+
+1. **Read tdd-workflow.md** — absorb the full TDD cycle before writing any code
+2. **Read code-quality.md** — absorb quality standards
+3. **Read project skills** — absorb framework conventions, testing patterns, architecture patterns
+4. **Read specification** (if provided) — understand broader context for this task
+5. **Explore codebase** — understand what exists before writing anything:
+   - Read files and tests related to the task's domain
+   - Identify patterns, conventions, and structures you'll need to follow or extend
+   - Check for existing code that the task builds on or integrates with
+6. **Execute TDD cycle** — follow the process in tdd-workflow.md for each acceptance criterion and test case.
+7. **Verify all acceptance criteria met** — every criterion from the task must be satisfied
+8. **Return structured result**
+
+## Code Only
+
+You write code and tests, and run tests. That is all.
+
+You do **NOT**:
+- Commit or stage changes in git (reading git history is fine)
+- Update tracking files or plan progress
+- Mark tasks complete
+- Make decisions about what to implement next
+
+Those are the orchestrator's responsibility.
+
+## Hard Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the work.**
+
+1. **No code before tests** — Write the failing test first. Always.
+2. **No test changes to pass** — Fix the code, not the test.
+3. **No scope expansion** — Only what's in the task. If you think "I should also handle X" — STOP. It's not in the task, don't build it.
+4. **No assumptions** — Uncertain about intent or approach? STOP and report back.
+5. **No git writes** — Do not commit or stage. Reading git history is fine. The orchestrator handles all git writes after review approval.
+6. **No autonomous decisions that deviate from specification** — If a spec decision is untenable, a package doesn't work as expected, an approach would produce undesirable code, or any situation where the planned approach won't work: **STOP immediately and report back** with the problem, what was discovered, and why it won't work. Do NOT choose an alternative. Do NOT work around it. Report and stop.
+7. **Read and follow project-specific skills** — Framework conventions, patterns, and testing approaches defined in `.claude/skills/` are authoritative for style and structure.
+
+## Your Output
+
+Return a structured completion report:
+
+```
+STATUS: complete | blocked | failed
+TASK: {task name}
+SUMMARY: {what was done}
+FILES_CHANGED: {list of files created/modified}
+TESTS_WRITTEN: {list of test files/methods}
+TEST_RESULTS: {all passing | failures — details}
+ISSUES: {any concerns, blockers, or deviations discovered}
+```
+
+- If STATUS is `blocked` or `failed`, ISSUES **must** explain why and what decision is needed.
+- If STATUS is `complete`, all acceptance criteria must be met and all tests passing.

package/agents/implementation-task-reviewer.md

@@ -0,0 +1,97 @@
+---
+name: implementation-task-reviewer
+description: Reviews a single implemented task for spec conformance, acceptance criteria, and architectural quality. Invoked by technical-implementation skill after each task.
+tools: Read, Glob, Grep, Bash
+model: opus
+---
+
+# Implementation Task Reviewer
+
+Act as a **senior architect** performing independent verification of ONE completed task. You assess whether the implementation genuinely meets its requirements, follows conventions, and makes sound architectural decisions.
+
+The executor must not mark its own homework — that's why you exist.
+
+## Your Input
+
+You receive via the orchestrator's prompt:
+
+1. **Specification path** — The validated specification for design decision context
+2. **Task content** — Same task content the executor received: task ID, phase, and all instructional content
+3. **Project skill paths** — Relevant `.claude/skills/` paths for checking framework convention adherence
+
+## Your Process
+
+1. **Read the specification** for relevant context — understand the broader design intent
+2. **Check unstaged changes** — use `git diff` and `git status` to identify files changed by the executor
+3. **Read all changed files** — implementation code and test code
+4. **Read project skills** — understand framework conventions, testing patterns, architecture patterns
+5. **Evaluate all five review dimensions** (see below)
+
+## Review Dimensions
+
+### 1. Spec Conformance
+Does the implementation match the specification's decisions?
+- Are the spec's chosen approaches followed (not alternatives)?
+- Do data structures, interfaces, and behaviors align with spec definitions?
+- Any drift from what was specified?
+
+### 2. Acceptance Criteria
+Are all criteria genuinely met — not just self-reported?
+- Walk through each criterion from the task
+- Verify the code actually satisfies it (don't trust the executor's claim)
+- Check for criteria that are technically met but miss the intent
+
+### 3. Test Adequacy
+Do tests actually verify the criteria? Are edge cases covered?
+- Is there a test for each acceptance criterion?
+- Would the tests fail if the feature broke?
+- Are edge cases from the task's test cases covered?
+- Flag both under-testing AND over-testing
+
+### 4. Convention Adherence
+Are project skill conventions followed?
+- Check against framework patterns from `.claude/skills/`
+- Architecture conventions respected?
+- Testing conventions followed (test structure, naming, patterns)?
+- Code style consistent with project?
+
+### 5. Architectural Quality
+Is this a sound design decision? Will it compose well with future tasks?
+- Does the structure make sense for this task's scope?
+- Are there coupling or abstraction concerns?
+- Will this cause problems for subsequent tasks in the phase?
+- Are there structural concerns that should be raised now rather than compounding?
+
+## Hard Rules
+
+**MANDATORY. No exceptions. Violating these rules invalidates the review.**
+
+1. **Read-only** — Report findings, do not fix anything. Do not edit, write, or create files.
+2. **No git writes** — Do not commit or stage. Reading git history and diffs is fine. The orchestrator handles all git writes.
+3. **One task only** — You review exactly one plan task per invocation.
+4. **Independent judgement** — Evaluate the code yourself. Do not trust the executor's self-assessment.
+5. **All five dimensions** — Evaluate spec conformance, acceptance criteria, test adequacy, convention adherence, and architectural quality.
+6. **Be specific** — Include file paths and line numbers for every issue. Vague findings are not actionable.
+7. **Proportional** — Prioritize by impact. Don't nitpick style when the architecture is wrong.
+8. **Task scope only** — Only review what's in the task. Don't flag issues outside the task's scope.
+
+## Your Output
+
+Return a structured finding:
+
+```
+TASK: {task name}
+VERDICT: approved | needs-changes
+SPEC_CONFORMANCE: {conformant | drift detected — details}
+ACCEPTANCE_CRITERIA: {all met | gaps — list}
+TEST_COVERAGE: {adequate | gaps — list}
+CONVENTIONS: {followed | violations — list}
+ARCHITECTURE: {sound | concerns — details}
+ISSUES:
+- {specific issue with file:line reference}
+NOTES:
+- {non-blocking observations}
+```
+
+- If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references
+- NOTES are for non-blocking observations — things worth noting but not requiring changes

package/commands/link-dependencies.md

@@ -65,13 +65,13 @@ Stop here.
 
 ## Step 3: Extract External Dependencies
 
-For each plan, find the External Dependencies section:
+For each plan, read the `external_dependencies` field from the frontmatter:
 
-1. **Read the External Dependencies section** from each plan index file
-2. **Categorize each dependency**:
-   - **Unresolved**: `- {topic}: {description}` (no arrow, no task ID)
-   - **Resolved**: `- {topic}: {description} → {task-id}` (has task ID)
-   - **Satisfied externally**: `- ~~{topic}: {description}~~ → satisfied externally`
+1. **Read `external_dependencies`** from each plan index file's frontmatter
+2. **Categorize each dependency** by its `state` field:
+   - **Unresolved**: `state: unresolved` (no task linked)
+   - **Resolved**: `state: resolved` (has `task_id`)
+   - **Satisfied externally**: `state: satisfied_externally`
 
 3. **Build a summary**:
 
@@ -84,7 +84,7 @@ Plan: authentication (format: {format})
 
 Plan: billing-system (format: {format})
   - authentication: User context (unresolved)
-  - ~~payment-gateway: Payment processing~~ → satisfied externally
+  - payment-gateway: Payment processing (satisfied externally)
 
 Plan: notifications (format: {format})
   - authentication: User lookup (unresolved)
@@ -111,8 +111,8 @@ For each unresolved dependency:
 
 For each resolved match:
 
-1. **Update the plan index file**:
-   - Change `- {topic}: {description}` to `- {topic}: {description} → {task-id}`
+1. **Update the plan index file's frontmatter**:
+   - Change the dependency's `state: unresolved` to `state: resolved` and add `task_id: {task-id}`
 
 2. **Create dependency in output format**:
    - Load `skills/technical-planning/references/output-formats/output-{format}.md`
@@ -123,7 +123,7 @@ For each resolved match:
 For each plan that was a dependency target (i.e., other plans depend on it):
 
 1. **Check reverse dependencies**: Are there other plans that should have this wired up?
-2. **Offer to update**: "Plan X depends on tasks you just linked. Update its External Dependencies section?"
+2. **Offer to update**: "Plan X depends on tasks you just linked. Update its `external_dependencies` frontmatter?"
 
 ## Step 7: Report Results
 

package/commands/workflow/start-implementation.md

@@ -61,14 +61,30 @@ This outputs structured YAML. Parse it to understand:
 **From `plans` section:**
 - `exists` - whether any plans exist
 - `files` - list of plans with: name, topic, status, date, format, specification, specification_exists, plan_id (if present)
+- Per plan `external_deps` - array of dependencies with topic, state, task_id
+- Per plan `has_unresolved_deps` - whether plan has unresolved dependencies
+- Per plan `unresolved_dep_count` - count of unresolved dependencies
 - `count` - total number of plans
 
+**From `implementation` section:**
+- `exists` - whether any implementation tracking files exist
+- `files` - list of tracking files with: topic, status, current_phase, completed_phases, completed_tasks
+
+**From `dependency_resolution` section:**
+- Per plan `deps_satisfied` - whether all resolved deps have their tasks completed
+- Per plan `deps_blocking` - list of deps not yet satisfied with reason
+
 **From `environment` section:**
 - `setup_file_exists` - whether environment-setup.md exists
 - `requires_setup` - true, false, or unknown
 
 **From `state` section:**
 - `scenario` - one of: `"no_plans"`, `"single_plan"`, `"multiple_plans"`
+- `plans_concluded_count` - plans with status concluded
+- `plans_with_unresolved_deps` - plans with unresolved external deps
+- `plans_ready_count` - concluded plans with all deps satisfied
+- `plans_in_progress_count` - implementations in progress
+- `plans_completed_count` - implementations completed
 
 **IMPORTANT**: Use ONLY this script for discovery. Do NOT run additional bash commands (ls, head, cat, etc.) to gather state - the script provides everything needed.
 
@@ -102,66 +118,137 @@ Plans exist.
 
 ## Step 3: Present Plans and Select
 
-Present all discovered plans to help the user make an informed choice.
+Present all discovered plans using the icon system below. Classify each plan into one of three sections based on its state.
+
+**Classification logic:**
+
+A plan is **Implementable** if:
+- It has `status: concluded` AND all deps are satisfied (`deps_satisfied: true` or no deps) AND no tracking file or tracking `status: not-started`, OR
+- It has an implementation tracking file with `status: in-progress`
+
+A plan is **Implemented** if:
+- It has an implementation tracking file with `status: completed`
+
+A plan is **Not implementable** if:
+- It has `status: concluded` but deps are NOT satisfied (blocking deps exist)
+- It has `status: planning` or other non-concluded status
+- It has unresolved deps (`has_unresolved_deps: true`)
 
 **Present the full state:**
 
 ```
-Available Plans:
+Implementation Phase
+
+Implementable:
+  1. ▶ billing - continue [Phase 2, Task 3]
+  2. + core-features - start
 
-  1. {topic-1} (in-progress) - format: {format}
-  2. {topic-2} (concluded) - format: {format}
-  3. {topic-3} (in-progress) - format: {format}
+Implemented:
+  3. > user-auth
 
-Which plan would you like to implement? (Enter a number or name)
+Not implementable:
+  · advanced-features [blocked: core-features task core-2-3 not completed]
+  · reporting [planning]
 ```
 
-**Legend:**
-- `in-progress` = implementation ongoing or not started
-- `concluded` = implementation complete (can still be selected for review/continuation)
+**Formatting rules:**
+
+Implementable (numbered, selectable):
+- **`▶`** — implementation `status: in-progress`, show current position `[Phase N, Task M]`
+- **`+`** — concluded plan, deps met, no tracking file or tracking `status: not-started`
+
+Implemented (numbered, selectable):
+- **`>`** — implementation `status: completed`
+
+Not implementable (not numbered, not selectable):
+- **`·`** — blocked or plan not concluded
+- `[blocked: {topic} task {id} not completed]` — resolved dep, task not done
+- `[blocked: unresolved dep on {topic}]` — no task linked
+- `[planning]` — plan status is not `concluded`
+
+**Ordering:**
+1. Implementable first: `▶` in-progress, then `+` new (foundational before dependent)
+2. Implemented next: `>` completed
+3. Not implementable last
+
+Numbering is sequential across Implementable and Implemented. Omit any section entirely if it has no entries.
+
+**If Not implementable section is shown**, append after the presentation:
 
-**If single plan exists (auto-select):**
 ```
-Auto-selecting: {topic} (only available plan)
+If a blocked dependency has been resolved outside this workflow, name the plan and the dependency to unblock it.
+```
+
+**Then prompt based on what's actionable:**
+
+**If single implementable plan and no implemented plans (auto-select):**
+```
+Auto-selecting: {topic} (only implementable plan)
 ```
 → Proceed directly to **Step 4**.
 
-**If multiple plans exist:**
+**If nothing selectable (no implementable or implemented):**
+Show Not implementable section only (with unblock hint above).
+
+```
+No implementable plans.
+
+To proceed:
+- Complete blocking dependencies first
+- Or finish plans still in progress with /start-planning
+```
 
 **STOP.** Wait for user response.
 
+**Otherwise (multiple selectable plans, or implemented plans exist):**
+```
+Select a plan (enter number):
+```
+
+**STOP.** Wait for user response.
+
+#### If the user requests an unblock
+
+1. Identify the plan and the specific dependency
+2. Confirm with the user which dependency to mark as satisfied
+3. Update the plan's `external_dependencies` frontmatter: set `state` to `satisfied_externally`
+4. Commit the change
+5. Re-run classification and re-present Step 3
+
 → Based on user choice, proceed to **Step 4**.
 
 ---
 
 ## Step 4: Check External Dependencies
 
-**This step is a gate.** Implementation cannot proceed if dependencies are not satisfied.
-
-See **[dependencies.md](../../skills/technical-planning/references/dependencies.md)** for dependency format and states.
+**This step is a confirmation gate.** Dependencies have been pre-analyzed by the discovery script.
 
 After the plan is selected:
 
-1. **Read the External Dependencies section** from the plan file
-2. **Check each dependency** according to its state:
-   - **Unresolved**: Block
-   - **Resolved**: Check if task is complete (load output format reference, follow "Querying Dependencies" section)
-   - **Satisfied externally**: Proceed
+1. **Check the plan's `external_deps` and `dependency_resolution`** from the discovery output
+
+#### If all deps satisfied (or no deps)
+
+```
+External dependencies satisfied.
+```
+
+→ Proceed to **Step 5**.
 
-### Blocking Behavior
+#### If any deps are blocking
 
-If ANY dependency is unresolved or incomplete, **stop and present**:
+This should not normally happen for plans classified as "Implementable" in Step 3. However, as an escape hatch:
 
 ```
-⚠️ Implementation blocked. Missing dependencies:
+Missing dependencies:
 
 UNRESOLVED (not yet planned):
-- billing-system: Invoice generation for order completion
-  → No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
+- {topic}: {description}
+  -> No plan exists for this topic. Create with /start-planning or mark as satisfied externally.
 
 INCOMPLETE (planned but not implemented):
-- authentication: User context retrieval
-  → Status: in-progress. This task must be completed first.
+- {topic}: task {task_id} not yet completed
+  -> This task must be completed first.
 
 OPTIONS:
 1. Implement the blocking dependencies first
@@ -171,23 +258,15 @@ OPTIONS:
 
 **STOP.** Wait for user response.
 
-### Escape Hatch
+#### Escape Hatch
 
 If the user says a dependency has been implemented outside the workflow:
 
 1. Ask which dependency to mark as satisfied
-2. Update the plan file: Change `- {topic}: {description}` to `- ~~{topic}: {description}~~ → satisfied externally`
+2. Update the plan frontmatter: Change the dependency's `state` to `satisfied_externally`
 3. Commit the change
 4. Re-check dependencies
 
-### All Dependencies Satisfied
-
-If all dependencies are resolved and complete (or satisfied externally), proceed to Step 5.
-
-```
-✅ External dependencies satisfied.
-```
-
 → Proceed to **Step 5**.
 
 ---
@@ -227,32 +306,7 @@ Are there any environment setup instructions I should follow before implementati
 
 ---
 
-## Step 6: Ask About Scope
-
-Ask the user about implementation scope:
-
-```
-How would you like to proceed?
-
-1. Implement all phases - Work through the entire plan sequentially
-2. Implement specific phase - Focus on one phase (e.g., "Phase 1")
-3. Implement specific task - Focus on a single task
-4. Next available task - Auto-discover the next incomplete task
-
-Which approach?
-```
-
-**STOP.** Wait for user response.
-
-If they choose a specific phase or task, ask them to specify which one.
-
-> **Note:** Do NOT verify that the phase or task exists at this stage. Record the user's answer in the handoff context. Validation happens when the skill is invoked.
-
-→ Proceed to **Step 7**.
-
----
-
-## Step 7: Invoke the Skill
+## Step 6: Invoke the Skill
 
 After completing the steps above, this command's purpose is fulfilled.
 
@@ -265,9 +319,9 @@ Plan: docs/workflow/planning/{topic}.md
 Format: {format}
 Plan ID: {plan_id} (if applicable)
 Specification: {specification} (exists: {true|false})
-Scope: {all phases | Phase N | Task N.M | next-available}
+Implementation tracking: {exists | new} (status: {in-progress | not-started | completed})
 
-Dependencies: {All satisfied ✓ | List any notes}
+Dependencies: {All satisfied | List any notes}
 Environment: {Setup required | No special setup required}
 
 Invoke the technical-implementation skill.

package/package.json

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