npm - @leeovery/claude-technical-workflows - Versions diffs - 2.1.2 → 2.1.4 - Mend

@leeovery/claude-technical-workflows 2.1.2 → 2.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (20) hide show

package/README.md CHANGED Viewed

@@ -18,7 +18,7 @@
   <a href="https://leeovery.github.io/claude-technical-workflows/"><strong>Open the Interactive Workflow Explorer</strong></a>
 </p>
-> **Workflow Explorer** — A visual, interactive guide to every phase, skill, and command in this toolkit. See how commands route to skills, trace decision logic through flowcharts, and understand the full pipeline at a glance. No install required — runs in your browser.
+> **Workflow Explorer** — A visual, interactive guide to every phase and skill in this toolkit. Trace decision logic through flowcharts and understand the full pipeline at a glance. No install required — runs in your browser.
 ---
@@ -34,7 +34,7 @@ Research → Discussion → Specification → Planning → Implementation → Re
 **Why this matters:** Complex features benefit from thorough discussion before implementation. This toolkit documents the *what* and *why* before diving into the *how*, preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost.
-**Flexible entry points:** Need the full workflow? Start at Research or Discussion and progress through each phase. Already know what you're building? Jump straight to Specification with `/start-feature`. Skills are input-agnostic - commands gather context and feed it to them.
+**Flexible entry points:** Need the full workflow? Start at Research or Discussion and progress through each phase. Already know what you're building? Jump straight to Specification with `/start-feature`. Entry-point skills gather context and feed it to processing skills.
 > [!NOTE]
 > **Work in progress.** The workflow is being refined through real-world usage. Expect updates as patterns evolve.
@@ -69,47 +69,47 @@ Research → Discussion → Specification → Planning → Implementation → Re
 Start with `/start-research` or `/start-discussion` and follow the flow. Each phase outputs files that the next phase consumes.
-**2. Standalone Commands** - Jump directly to a skill with flexible inputs:
+**2. Standalone Skills** - Jump directly to a processing skill with flexible inputs:
-| Command | What it does |
-|---------|-------------|
+| Skill | What it does |
+|-------|-------------|
 | `/start-feature` | Create a spec directly from inline context (skip research/discussion) |
-*More standalone commands coming soon.*
+*More standalone skills coming soon.*
-### The Command/Skill Architecture
+### The Two-Tier Skill Architecture
-**Skills are input-agnostic.** They don't know or care where their inputs came from: a discussion document, inline context, or external sources. They just process what they receive.
+**Processing skills** (`technical-*`) are input-agnostic. They don't know or care where their inputs came from: a discussion document, inline context, or external sources. They just process what they receive.
-**Commands are the input layer.** They gather context (from files, prompts, or inline) and pass it to skills. This separation means:
+**Entry-point skills** (`/start-*`, `/status`, etc.) are the input layer. They gather context (from files, prompts, or inline) and pass it to processing skills. This separation means:
-- The same skill can be invoked from different entry points
-- You can create custom commands that feed skills in new ways
-- Skills remain reusable without coupling to specific workflows
+- The same processing skill can be invoked from different entry points
+- You can create custom entry-point skills that feed processing skills in new ways
+- Processing skills remain reusable without coupling to specific workflows
 ```
 ┌─────────────────────────────────────────────────────────────┐
-│                        COMMANDS                             │
-│  (gather inputs from files, prompts, inline context)        │
+│                    ENTRY-POINT SKILLS                        │
+│  (gather inputs from files, prompts, inline context)         │
 ├─────────────────────────────────────────────────────────────┤
-│  /start-specification   /start-feature   (your custom)  │
-│         │                       │                 │         │
-│         └───────────┬───────────┘                 │         │
-│                     ▼                             ▼         │
+│  /start-specification   /start-feature   (your custom)      │
+│         │                       │                 │          │
+│         └───────────┬───────────┘                 │          │
+│                     ▼                             ▼          │
 ├─────────────────────────────────────────────────────────────┤
-│                         SKILLS                              │
-│  (process inputs without knowing their source)              │
+│                    PROCESSING SKILLS                         │
+│  (process inputs without knowing their source)               │
 ├─────────────────────────────────────────────────────────────┤
-│           technical-specification skill                     │
-│           technical-planning skill                          │
-│           technical-implementation skill                    │
-│           etc.                                              │
+│           technical-specification skill                      │
+│           technical-planning skill                           │
+│           technical-implementation skill                     │
+│           etc.                                               │
 └─────────────────────────────────────────────────────────────┘
 ```
-### Workflow Commands
+### Workflow Skills
-| Phase          | Command                 |
+| Phase          | Skill                   |
 |----------------|-------------------------|
 | Research       | `/start-research`       |
 | Discussion     | `/start-discussion`     |
@@ -118,7 +118,7 @@ Start with `/start-research` or `/start-discussion` and follow the flow. Each ph
 | Implementation | `/start-implementation` |
 | Review         | `/start-review`         |
-Run the command directly or ask Claude to run it. Each gathers context from previous phase outputs and passes it to the skill.
+Run the skill directly or ask Claude to run it. Each gathers context from previous phase outputs and passes it to the processing skill.
 ## Installation
@@ -234,27 +234,27 @@ Research starts with `exploration.md` and splits into topic files as themes emer
 ### Package Structure
 ```
-skills/                              # Input-agnostic processors
+skills/
+├── # Processing skills (model-invocable)
 ├── technical-research/              # Explore and validate ideas
 ├── technical-discussion/            # Document discussions
 ├── technical-specification/         # Build validated specifications
 ├── technical-planning/              # Create implementation plans
 ├── technical-implementation/        # Execute via TDD
-└── technical-review/                # Validate against artefacts
-commands/                            # Input layer (gather context → invoke skills)
-├── migrate.md                       # Keep workflow files in sync with system design
-├── start-feature.md                 # Standalone: spec from inline context
-├── link-dependencies.md             # Standalone: wire cross-topic deps
-└── workflow/                        # Sequential workflow commands
-    ├── start-research.md            # Begin research
-    ├── start-discussion.md          # Begin discussions
-    ├── start-specification.md       # Begin specification
-    ├── start-planning.md            # Begin planning
-    ├── start-implementation.md      # Begin implementation
-    ├── start-review.md              # Begin review
-    ├── status.md                    # Show workflow status
-    └── view-plan.md                 # View plan tasks
+├── technical-review/                # Validate against artefacts
+│
+├── # Entry-point skills (user-invocable)
+├── migrate/                         # Keep workflow files in sync with system design
+├── start-feature/                   # Standalone: spec from inline context
+├── link-dependencies/               # Standalone: wire cross-topic deps
+├── start-research/                  # Begin research
+├── start-discussion/                # Begin discussions
+├── start-specification/             # Begin specification
+├── start-planning/                  # Begin planning
+├── start-implementation/            # Begin implementation
+├── start-review/                    # Begin review
+├── status/                          # Show workflow status
+└── view-plan/                       # View plan tasks
 agents/
 ├── review-task-verifier.md           # Verifies single task implementation for review
@@ -265,11 +265,11 @@ agents/
 ├── planning-task-author.md          # Write full task detail
 └── planning-dependency-grapher.md   # Analyze task dependencies and priorities
-scripts/                             # Helper scripts for commands
+scripts/                             # Helper scripts for skills
 ├── migrate.sh                       # Migration orchestrator
-├── discovery-for-discussion.sh      # Discovery for discussion command
-├── discovery-for-specification.sh   # Discovery for specification command
-├── discovery-for-planning.sh        # Discovery for planning command
+├── discovery-for-discussion.sh      # Discovery for discussion skill
+├── discovery-for-specification.sh   # Discovery for specification skill
+├── discovery-for-planning.sh        # Discovery for planning skill
 ├── discovery-for-implementation-and-review.sh  # Discovery for impl/review
 └── migrations/                      # Individual migration scripts (numbered)
@@ -279,7 +279,9 @@ tests/
 ## Skills
-Skills are **input-agnostic processors**: they receive inputs and process them without knowing where the inputs came from. This makes them reusable across different commands and workflows.
+### Processing Skills
+Processing skills are **input-agnostic**: they receive inputs and process them without knowing where the inputs came from. This makes them reusable across different entry points and workflows.
 | Skill                                                            | Description                                                                                                                                                                                                  |
 |------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -290,48 +292,48 @@ Skills are **input-agnostic processors**: they receive inputs and process them w
 | [**technical-implementation**](skills/technical-implementation/) | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval.                                                       |
 | [**technical-review**](skills/technical-review/)                 | Review completed implementation against specification requirements and plan acceptance criteria. Uses parallel subagents for efficient chain verification. Produces structured feedback without fixing code. |
-## Commands
+### Entry-Point Skills
-Commands are the input layer: they gather context and pass it to skills. Two types:
+Entry-point skills are the input layer: they gather context and pass it to processing skills.
-### Workflow Commands
+#### Workflow Skills
-Sequential commands in `commands/workflow/`. They expect files from previous phases and pass content to skills.
+Sequential skills that expect files from previous phases and pass content to processing skills.
-| Command                                                                              | Description                                                                                                                                                                                                |
-|--------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-research**](commands/workflow/start-research.md)                  | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
-| [**/start-discussion**](commands/workflow/start-discussion.md)              | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
-| [**/start-specification**](commands/workflow/start-specification.md)        | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
-| [**/start-planning**](commands/workflow/start-planning.md)                  | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear). |
-| [**/start-implementation**](commands/workflow/start-implementation.md)      | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
-| [**/start-review**](commands/workflow/start-review.md)                      | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
+| Skill                                                                        | Description                                                                                                                                                                                                |
+|------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/start-research**](skills/start-research/)                                | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
+| [**/start-discussion**](skills/start-discussion/)                            | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
+| [**/start-specification**](skills/start-specification/)                      | Start a specification session from existing discussion(s). Automatically analyses multiple discussions for natural groupings and consolidates them into unified specifications.                            |
+| [**/start-planning**](skills/start-planning/)                                | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (local markdown, Linear). |
+| [**/start-implementation**](skills/start-implementation/)                    | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
+| [**/start-review**](skills/start-review/)                                    | Start reviewing completed work. Validates implementation against plan tasks and acceptance criteria.                                                                                                        |
-### Utility Commands
+#### Utility Skills
 Helpers for navigating and maintaining the workflow.
-| Command                                                                              | Description                                                                                                                                 |
-|--------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/migrate**](commands/migrate.md)                                         | Keep workflow files in sync with the current system design. Runs automatically at the start of every workflow command.                      |
-| [**/status**](commands/workflow/status.md)                                  | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
-| [**/view-plan**](commands/workflow/view-plan.md)                            | View a plan's tasks and progress, regardless of output format.                                                                              |
+| Skill                                                                        | Description                                                                                                                                 |
+|------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/migrate**](skills/migrate/)                                              | Keep workflow files in sync with the current system design. Runs automatically at the start of every workflow skill.                        |
+| [**/status**](skills/status/)                                                | Show workflow status - what topics exist at each phase, and suggested next steps.                                                           |
+| [**/view-plan**](skills/view-plan/)                                          | View a plan's tasks and progress, regardless of output format.                                                                              |
-### Standalone Commands
+#### Standalone Skills
-Independent commands that gather inputs flexibly (inline context, files, or prompts) and invoke skills directly. Use these when you want skill capabilities without the full workflow structure.
+Independent skills that gather inputs flexibly (inline context, files, or prompts) and invoke processing skills directly. Use these when you want capabilities without the full workflow structure.
-| Command                                                 | Description                                                                                                                                 |
+| Skill                                                   | Description                                                                                                                                 |
 |---------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
-| [**/start-feature**](commands/start-feature.md)         | Create a specification directly from inline context. Invokes the specification skill without requiring a discussion document.              |
-| [**/link-dependencies**](commands/link-dependencies.md) | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
+| [**/start-feature**](skills/start-feature/)              | Create a specification directly from inline context. Invokes the specification skill without requiring a discussion document.              |
+| [**/link-dependencies**](skills/link-dependencies/)      | Link external dependencies across topics. Scans plans and wires up unresolved cross-topic dependencies.                                    |
-### Creating Custom Commands
+### Creating Custom Skills
-Since skills are input-agnostic, you can create your own commands that feed them in new ways. A command just needs to:
+Since processing skills are input-agnostic, you can create your own entry-point skills that feed them in new ways. An entry-point skill just needs to:
-1. Gather the inputs the skill expects
-2. Invoke the skill with those inputs
+1. Gather the inputs the processing skill expects
+2. Invoke the processing skill with those inputs
 See `/start-feature` as an example: it provides inline context to the specification skill instead of a discussion document.

package/agents/implementation-task-executor.md CHANGED Viewed

@@ -18,10 +18,14 @@ You receive file paths and context via the orchestrator's prompt:
 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.
+6. **Plan file path** — The implementation plan, for understanding the overall task landscape and where this task fits
+7. **Integration context file path** (if exists) — Accumulated notes from prior tasks about established patterns, conventions, and decisions
-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**
+On **re-invocation after review feedback**, you receive all of the above, plus:
+8. **User-approved review notes** — may be the reviewer's original notes, modified by user, or user's own notes
+9. **Specific issues to address**
+You are stateless — each invocation starts fresh. The full task content is always provided so you can see what was asked, what was done, and what needs fixing.
 ## Your Process
@@ -29,10 +33,14 @@ On **re-invocation after review feedback**, you also receive:
 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:
+5. **Explore codebase** — you are weaving into an existing canvas, not creating isolated patches:
+   - If an integration context file was provided, read it first — identify helpers, patterns, and conventions you must reuse before writing anything new
+   - Skim the plan file to understand the task landscape — what's been built, what's coming, where your task fits. Use this for awareness, not to build ahead (YAGNI still applies)
    - 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
+   - Search for existing helpers, utilities, and abstractions that solve similar problems — reuse, don't duplicate
+   - When creating an interface or API boundary, read BOTH sides: the code that will consume it AND the code that will implement it
+   - Match conventions established in the codebase: error message style, naming patterns, file organisation, type placement
+   - Your code should read as if the same developer wrote the entire codebase
 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**
@@ -73,7 +81,10 @@ 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}
+INTEGRATION_NOTES:
+- {3-5 concise bullet points: key patterns, helpers, conventions, interface decisions established by this task. Anchor to concrete file paths where applicable (e.g., "Created `ValidationHelper` in `src/helpers/validation.ts` — use for all input validation"), but high-level observations without a specific file reference are also valuable}
 ```
 - 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.
+- After completing the task, document what you created or established that future tasks should be aware of in INTEGRATION_NOTES. This is factual — what exists and why — not evaluative.

package/agents/implementation-task-reviewer.md CHANGED Viewed

@@ -18,6 +18,7 @@ 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
+4. **Integration context file path** (if exists) — Accumulated notes from prior tasks, for evaluating cohesion with established patterns
 ## Your Process
@@ -25,7 +26,7 @@ You receive via the orchestrator's prompt:
 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)
+5. **Evaluate all six review dimensions** (see below)
 ## Review Dimensions
@@ -62,6 +63,31 @@ Is this a sound design decision? Will it compose well with future tasks?
 - Will this cause problems for subsequent tasks in the phase?
 - Are there structural concerns that should be raised now rather than compounding?
+### 6. Codebase Cohesion
+Does the new code integrate well with the existing codebase? If integration context exists from prior tasks, check against established patterns.
+- Is there duplicated logic that should be extracted into a shared helper?
+- Are existing helpers and patterns being reused where applicable?
+- Are naming conventions consistent with existing code?
+- Are error message conventions consistent (casing, wrapping style, prefixes)?
+- Do interfaces use concrete types rather than generic/any types where possible?
+- Are related types co-located with the interfaces or functions they serve?
+## Fix Recommendations (needs-changes only)
+When your verdict is `needs-changes`, you must also recommend how to fix each issue. You have full context — the spec, the task, the conventions, and the code — so use it.
+For each issue, provide:
+- **FIX**: The recommended approach to resolve the issue
+- **ALTERNATIVE** (optional): If multiple valid approaches exist, state them with tradeoffs and indicate which you recommend
+- **CONFIDENCE**: `high` | `medium` | `low`
+  - `high` — single obvious approach, no ambiguity
+  - `medium` — recommended approach is sound but alternatives exist
+  - `low` — genuinely uncertain, multiple approaches with significant tradeoffs
+Be specific and actionable. "Fix the validation" is not useful. "Add a test case in `tests/UserTest.php` that asserts `ValidationException` is thrown when email is empty, following the existing test pattern at line 45" is useful.
+When alternatives exist, explain the tradeoff briefly — don't just list options. State which you recommend and why.
 ## Hard Rules
 **MANDATORY. No exceptions. Violating these rules invalidates the review.**
@@ -70,7 +96,7 @@ Is this a sound design decision? Will it compose well with future tasks?
 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.
+5. **All six dimensions** — Evaluate spec conformance, acceptance criteria, test adequacy, convention adherence, architectural quality, and codebase cohesion.
 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.
@@ -87,11 +113,20 @@ ACCEPTANCE_CRITERIA: {all met | gaps — list}
 TEST_COVERAGE: {adequate | gaps — list}
 CONVENTIONS: {followed | violations — list}
 ARCHITECTURE: {sound | concerns — details}
+CODEBASE_COHESION: {cohesive | concerns — details}
 ISSUES:
 - {specific issue with file:line reference}
+  FIX: {recommended approach}
+  ALTERNATIVE: {other valid approach with tradeoff — optional, only when multiple valid approaches exist}
+  CONFIDENCE: {high | medium | low}
 NOTES:
 - {non-blocking observations}
+COHESION_NOTES:
+- {2-4 concise bullet points: patterns to maintain, conventions confirmed, architectural integration observations}
 ```
-- If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references
+- If VERDICT is `approved`, omit ISSUES entirely (or leave empty)
+- If VERDICT is `needs-changes`, ISSUES must contain specific, actionable items with file:line references AND fix recommendations
+- Each issue must include FIX and CONFIDENCE. ALTERNATIVE is optional — include only when genuinely multiple valid approaches exist
 - NOTES are for non-blocking observations — things worth noting but not requiring changes
+- COHESION_NOTES are always included — they capture patterns and conventions observed for future task context

package/package.json CHANGED Viewed

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

package/{commands/link-dependencies.md → skills/link-dependencies/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format.
+name: link-dependencies
+description: "Scan all plans and wire up cross-topic dependencies. Finds unresolved external dependencies, matches them to tasks in other plans, and updates both the plan index and output format."
+disable-model-invocation: true
 ---
 Link cross-topic dependencies across all existing plans.

package/{commands/migrate.md → skills/migrate/SKILL.md} RENAMED Viewed

@@ -1,5 +1,6 @@
 ---
-description: Run migrations to keep workflow files in sync with the current system design. This command is mandatory before running any workflow command.
+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)
 ---
@@ -25,7 +26,7 @@ The script will list which files were updated. Present this to the user:
 Review changes with `git diff`, then proceed when ready.
 ```
-Wait for user acknowledgment before returning control to the calling command.
+Wait for user acknowledgment before returning control to the calling skill.
 ### If no updates needed
@@ -37,7 +38,7 @@ Return control silently - no user interaction needed.
 ## Notes
-- This command is run automatically at the start of every workflow command
+- This skill is run automatically at the start of every workflow skill
 - Migrations are tracked in `docs/workflow/.cache/migrations.log`
 - To force re-running all migrations, delete the tracking file
 - Each migration is idempotent - safe to run multiple times

package/{commands/workflow/start-discussion.md → skills/start-discussion/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start a technical discussion. Discovers research and existing discussions, offers multiple entry paths, and invokes the technical-discussion skill.
+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)
 ---
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
@@ -354,9 +356,9 @@ What would you like to focus on in this session?
 ## Step 7: Invoke the Skill
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
-Invoke the [technical-discussion](../../skills/technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-discussion](../technical-discussion/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 **Example handoff (from research):**
 ```

package/{commands/start-feature.md → skills/start-feature/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start a feature specification directly, skipping formal discussion documentation. For adding features to existing projects where you already know what you're building.
+name: start-feature
+description: "Start a feature specification directly, skipping formal discussion documentation. For adding features to existing projects where you already know what you're building."
+disable-model-invocation: true
 ---
 Invoke the **technical-specification** skill for this conversation with inline feature context.
@@ -8,7 +10,7 @@ Invoke the **technical-specification** skill for this conversation with inline f
 Follow these steps EXACTLY as written. Do not skip steps or combine them.
-This command is for **feature mode** - a streamlined path to specification when you already know what you're building and don't need formal discussion documentation.
+This skill is for **feature mode** - a streamlined path to specification when you already know what you're building and don't need formal discussion documentation.
 ## Step 1: Gather Feature Context
@@ -55,7 +57,7 @@ If a specification with the same name exists, inform the user and ask how to pro
 ## Step 4: Invoke Specification Skill
-Pass the gathered context to the technical-specification skill:
+Pass the gathered context to the [technical-specification](../technical-specification/SKILL.md) skill:
 ```
 Feature specification for: {topic}

package/{commands/workflow/start-implementation.md → skills/start-implementation/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start an implementation session from an existing plan. Discovers available plans, checks environment setup, and invokes the technical-implementation skill.
+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)
 ---
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
@@ -314,9 +316,9 @@ Are there any environment setup instructions I should follow before implementati
 ## Step 6: Invoke the Skill
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
-Invoke the [technical-implementation](../../skills/technical-implementation/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-implementation](../technical-implementation/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 **Example handoff:**
 ```

package/{commands/workflow/start-planning.md → skills/start-planning/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start a planning session from an existing specification. Discovers available specifications, gathers context, and invokes the technical-planning skill.
+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)
 ---
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
@@ -250,9 +252,9 @@ These specifications contain validated architectural decisions that should infor
 ## Step 7: Invoke the Skill
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
-Invoke the [technical-planning](../../skills/technical-planning/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-planning](../technical-planning/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 **Example handoff (fresh plan):**
 ```

package/{commands/workflow/start-research.md → skills/start-research/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.
+name: start-research
+description: "Start a research exploration using the technical-research skill. For early-stage ideas, feasibility checks, and broad exploration before formal discussion."
+disable-model-invocation: true
 ---
 Invoke the **technical-research** skill for this conversation.
@@ -39,7 +41,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
@@ -116,9 +118,9 @@ Any constraints or context I should know about upfront?
 ## Step 5: Invoke the Skill
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
-Invoke the [technical-research](../../skills/technical-research/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-research](../technical-research/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 **Example handoff:**
 ```

package/{commands/workflow/start-review.md → skills/start-review/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start a review session from an existing plan and implementation. Discovers available plans, validates implementation exists, and invokes the technical-review skill.
+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)
 ---
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
@@ -153,9 +155,9 @@ If they choose specific directories/files, ask them to specify.
 ## Step 5: Invoke the Skill
-After completing the steps above, this command's purpose is fulfilled.
+After completing the steps above, this skill's purpose is fulfilled.
-Invoke the [technical-review](../../skills/technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-review](../technical-review/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 **Example handoff:**
 ```

package/{commands/workflow/start-specification.md → skills/start-specification/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Start a specification session from existing discussions. Discovers available discussions, offers consolidation assessment for multiple discussions, and invokes the technical-specification skill.
+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)
 ---
@@ -40,7 +42,7 @@ Follow these steps EXACTLY as written. Do not skip steps or combine them. Presen
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.
@@ -757,9 +759,9 @@ Before invoking the specification skill:
 ## Step 11: Invoke the Skill
-After completing all steps above, this command's purpose is fulfilled.
+After completing all steps above, this skill's purpose is fulfilled.
-Invoke the [technical-specification](../../skills/technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
+Invoke the [technical-specification](../technical-specification/SKILL.md) skill for your next instructions. Do not act on the gathered information until the skill is loaded - it contains the instructions for how to proceed.
 #### Handoff Format

package/{commands/workflow/status.md → skills/status/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: Show workflow status - what exists, where you are, and what to do next.
+name: status
+description: "Show workflow status - what exists, where you are, and what to do next."
+disable-model-invocation: true
 ---
 Show the current state of the workflow for this project.
@@ -8,7 +10,7 @@ Show the current state of the workflow for this project.
 **This step is mandatory. You must complete it before proceeding.**
-Invoke the `/migrate` command and assess its output.
+Invoke the `/migrate` skill and assess its output.
 **If files were updated**: STOP and wait for the user to review the changes (e.g., via `git diff`) and confirm before proceeding to Step 1. Do not continue automatically.

package/skills/technical-implementation/SKILL.md CHANGED Viewed

@@ -48,7 +48,7 @@ Context refresh (compaction) summarizes the conversation, losing procedural deta
 1. **Re-read this skill file completely.** Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
 2. **Check task progress in the plan** — use the plan adapter's instructions to read the plan's current state. Also read the implementation tracking file and any other working documents for additional context.
-3. **Check `task_gate_mode`** in the tracking file — if `auto`, the user previously opted out of per-task gates for this session.
+3. **Check `task_gate_mode`, `fix_gate_mode`, and `fix_attempts`** in the tracking file — if gates are `auto`, the user previously opted out. If `fix_attempts` > 0, you're mid-fix-loop for the current task.
 4. **Check git state.** Run `git status` and `git log --oneline -10` to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
 5. **Announce your position** to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
@@ -143,7 +143,7 @@ Store the selected skill paths — they will be persisted to the tracking file i
 #### If `docs/workflow/implementation/{topic}.md` already exists
-Reset `task_gate_mode` to `gated` in the tracking file before proceeding (fresh session = fresh gate).
+Reset `task_gate_mode` and `fix_gate_mode` to `gated`, and `fix_attempts` to `0`, in the tracking file before proceeding (fresh session = fresh gates).
 If `project_skills` is populated in the tracking file, present for confirmation:
@@ -174,6 +174,8 @@ plan: ../planning/{topic}.md
 format: {format from plan}
 status: in-progress
 task_gate_mode: gated
+fix_gate_mode: gated
+fix_attempts: 0
 project_skills: []
 current_phase: 1
 current_task: ~
@@ -193,6 +195,8 @@ After creating the file, populate `project_skills` with the paths confirmed in S
 Commit: `impl({topic}): start implementation`
+Integration context will accumulate in `docs/workflow/implementation/{topic}-context.md` as tasks complete. This file is created automatically during the task loop — no initialisation needed here.
 → Proceed to **Step 5**.
 ---
@@ -225,3 +229,4 @@ Commit: `impl({topic}): complete implementation`
 - **[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)
+- **Integration context** — `docs/workflow/implementation/{topic}-context.md` — accumulated notes from completed tasks (created during task loop)

package/skills/technical-implementation/references/code-quality.md CHANGED Viewed

@@ -37,5 +37,15 @@ Only implement what's in the plan. Ask: "Is this in the plan?"
 - Long parameter lists (4+)
 - Boolean parameters
+## Convention Consistency
+When adding to an existing codebase, match what's already there:
+- **Error messages**: Match the casing, wrapping style, and prefix patterns in existing code
+- **Naming**: Follow the project's conventions for files, functions, types, and variables
+- **File organisation**: Follow the project's pattern for splitting concerns across files
+- **Helpers**: Search for existing helpers before creating new ones. After creating one, check if existing code could use it too
+- **Types**: Prefer concrete types over generic/any types when the set of possibilities is known. Use structured return types over multiple bare return values for extensibility
+- **Co-location**: Keep related types near the interfaces or functions they serve
 ## Project Standards
 Check `.claude/skills/` for project-specific patterns.

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

@@ -10,17 +10,21 @@ This step invokes the `implementation-task-executor` agent (`.claude/agents/impl
 ## Invoke the Agent
-Invoke `implementation-task-executor` with these file paths:
+**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`
 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))
+6. **Plan file path**: the implementation plan (same path used to read tasks)
+7. **Integration context file** (if exists): `docs/workflow/implementation/{topic}-context.md`
-On **re-invocation after review feedback**, also include:
-- **User-approved review notes**: verbatim or as modified by the user
-- **Specific issues to address**: the ISSUES from the review
+**Re-attempts after review feedback** additionally include:
+8. **User-approved review notes**: verbatim or as modified by the user
+9. **Specific issues to address**: the ISSUES from the review
+The executor is stateless — each invocation starts fresh with no memory of previous attempts. Always pass the full task content so the executor can see what was asked, what was done, and what needs fixing.
 ---
@@ -34,6 +38,8 @@ TASK: {task name}
 SUMMARY: {2-5 lines — commentary, decisions made, anything off-script}
 TEST_RESULTS: {all passing | failures — details only if failures}
 ISSUES: {blockers or deviations — omit if none}
+INTEGRATION_NOTES:
+- {3-5 bullets: patterns, helpers, conventions established — anchor to file paths where applicable}
 ```
 - `complete`: all acceptance criteria met, tests passing

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

@@ -15,6 +15,7 @@ Invoke `implementation-task-reviewer` with:
 1. **Specification path**: same path given to the executor
 2. **Task content**: same normalised task content the executor received
 3. **Project skill paths**: from `project_skills` in the implementation tracking file
+4. **Integration context file** (if exists): `docs/workflow/implementation/{topic}-context.md` — for checking cohesion with established patterns
 ---
@@ -30,11 +31,17 @@ ACCEPTANCE_CRITERIA: {all met | gaps — list}
 TEST_COVERAGE: {adequate | gaps — list}
 CONVENTIONS: {followed | violations — list}
 ARCHITECTURE: {sound | concerns — details}
+CODEBASE_COHESION: {cohesive | concerns — details}
 ISSUES:
 - {specific issue with file:line reference}
+  FIX: {recommended approach}
+  ALTERNATIVE: {other valid approach with tradeoff — optional}
+  CONFIDENCE: {high | medium | low}
 NOTES:
 - {non-blocking observations}
+COHESION_NOTES:
+- {2-4 bullets: patterns to maintain, conventions confirmed, integration quality}
 ```
-- `approved`: task passes all five review dimensions
-- `needs-changes`: ISSUES contains specific, actionable items
+- `approved`: task passes all six review dimensions
+- `needs-changes`: ISSUES contains specific, actionable items with fix recommendations and confidence levels

package/skills/technical-implementation/references/steps/task-loop.md CHANGED Viewed

@@ -13,7 +13,7 @@ A. Retrieve next task
 B. Execute task → invoke-executor.md
    → Executor Blocked (conditional)
 C. Review task → invoke-reviewer.md
-   → Review Changes (conditional)
+   → Review Changes with fix analysis (conditional, fix_gate_mode)
 D. Task gate (gated → prompt user / auto → announce)
 E. Update progress + commit
 → loop back to A until done
@@ -26,6 +26,7 @@ E. Update progress + commit
 1. Follow the format's **reading.md** instructions to determine the next available task.
 2. If no available tasks remain → skip to **When All Tasks Are Complete**.
 3. Normalise the task content following **[task-normalisation.md](../task-normalisation.md)**.
+4. Reset `fix_attempts` to `0` in the implementation tracking file.
 ---
@@ -55,7 +56,7 @@ Present the executor's ISSUES to the user:
 #### If `retry`
-→ Return to the top of **B. Execute Task** and re-invoke the executor with the user's comments added to the task context.
+→ Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the user's comments.
 #### If `skip`
@@ -77,26 +78,44 @@ Present the executor's ISSUES to the user:
 ### Review Changes
-Present the reviewer's findings to the user:
+Increment `fix_attempts` in the implementation tracking file.
-> **Review for Task {id}: {Task Name} — needs changes**
+#### If `fix_gate_mode: auto` and `fix_attempts < 3`
+Announce the fix round (one line, no stop):
+> **Review for Task {id}: {Task Name} — needs changes** (attempt {N}/{max 3}, fix analysis included). Re-invoking executor.
+→ Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
+#### If `fix_gate_mode: gated`, or `fix_attempts >= 3`
+If `fix_attempts >= 3`, the executor and reviewer have failed to converge. Prepend:
+> The executor and reviewer have not converged after {N} attempts. Escalating for human review.
+Present the reviewer's findings and fix analysis to the user:
+> **Review for Task {id}: {Task Name} — needs changes** (attempt {N})
 >
-> {ISSUES from reviewer}
+> {ISSUES from reviewer, including FIX, ALTERNATIVE, and CONFIDENCE for each}
 >
 > Notes (non-blocking):
 > {NOTES from reviewer}
 >
 > · · ·
 >
-> - **`y`/`yes`** — Accept these notes and pass them to the executor to fix
+> - **`y`/`yes`** — Accept the review and fix analysis, pass to executor
+> - **`a`/`auto`** — Accept and auto-approve future fix analyses
 > - **`s`/`skip`** — Override the reviewer and proceed as-is
-> - **Comment** — Modify or add to the notes before passing to the executor
+> - **Comment** — Any commentary, adjustments, alternative approaches, or questions before passing to executor
 **STOP.** Wait for user choice.
-- **`y`/`yes`**: → Return to the top of **B. Execute Task** and re-invoke the executor with the reviewer's notes added.
+- **`y`/`yes`**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
+- **`auto`**: Note that `fix_gate_mode` should be updated to `auto` during the next commit step. → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the reviewer's notes (including fix analysis).
 - **`skip`**: → Proceed to **D. Task Gate**.
-- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the user's notes.
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content, the reviewer's notes, and the user's commentary.
 ---
@@ -124,7 +143,7 @@ Present a summary and wait for user input:
 - **`y`/`yes`**: → Proceed to **E. Update Progress and Commit**.
 - **`auto`**: Note that `task_gate_mode` should be updated to `auto` during the commit step. → Proceed to **E. Update Progress and Commit**.
-- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the user's notes added.
+- **Comment**: → Return to the top of **B. Execute Task** and re-invoke the executor with the full task content and the user's notes.
 ### If `task_gate_mode: auto`
@@ -145,9 +164,24 @@ Announce the result (one line, no stop):
 - Update `current_phase` if phase changed
 - Update `current_task` to the next task (or `~` if done)
 - Update `updated` to today's date
-- If user chose `auto` this turn: update `task_gate_mode: auto`
+- If user chose `auto` at the task gate this turn: update `task_gate_mode: auto`
+- If user chose `auto` at the fix gate this turn: update `fix_gate_mode: auto`
+The tracking file is a derived view for discovery scripts and cross-topic dependency resolution — not a decision-making input during implementation (except `task_gate_mode` and `fix_gate_mode`).
+**Append integration context** — extract INTEGRATION_NOTES from the executor's final output and COHESION_NOTES from the reviewer's output. Append both to `docs/workflow/implementation/{topic}-context.md`:
+```
+## T{task-id}: {task name}
+### Integration (executor)
+{INTEGRATION_NOTES content}
+### Cohesion (reviewer)
+{COHESION_NOTES content}
+```
-The tracking file is a derived view for discovery scripts and cross-topic dependency resolution — not a decision-making input during implementation (except `task_gate_mode`).
+Create the file if it doesn't exist. This is mechanical text extraction and file append — the same as extracting STATUS to route on. Use outputs from the final approved iteration only.
 **Commit all changes** in a single commit:
@@ -155,7 +189,7 @@ The tracking file is a derived view for discovery scripts and cross-topic depend
 impl({topic}): T{task-id} — {brief description}
 ```
-Code, tests, plan progress, and tracking file — one commit per approved task.
+Code, tests, plan progress, tracking file, and integration context — one commit per approved task.
 This is the end of this iteration.

package/{commands/workflow/view-plan.md → skills/view-plan/SKILL.md} RENAMED Viewed

@@ -1,5 +1,7 @@
 ---
-description: View a plan's tasks and progress, regardless of output format.
+name: view-plan
+description: "View a plan's tasks and progress, regardless of output format."
+disable-model-invocation: true
 ---
 Display a readable summary of a plan's phases, tasks, and status.