@leeovery/claude-technical-workflows 2.1.39 → 2.1.41

package/skills/technical-planning/references/task-design/bugfix.md

@@ -0,0 +1,65 @@
+# Bugfix Task Design
+
+*Context guidance for **[task-design.md](../task-design.md)** — bug fixes*
+
+---
+
+## Root-Cause-First Ordering
+
+In bugfix work, the first task always reproduces the bug with a failing test, then fixes it. Foundation = the reproduction test and the minimal fix.
+
+**Example** ordering within a phase:
+
+```
+Task 1: Failing test for the N+1 query + add eager loading (reproduce + fix)
+Task 2: Verify performance with large dataset (validation)
+Task 3: Regression tests for related query paths (prevention)
+```
+
+The first task proves the bug exists and fixes it. Subsequent tasks harden the fix.
+
+---
+
+## Bugfix Vertical Slicing
+
+Each task changes the minimum code needed. A bugfix task is well-scoped when you can describe both the before (broken) and after (fixed) states in one sentence.
+
+**Example** (Single root cause):
+
+```
+Task 1: Add failing test demonstrating the race condition + add lock (fix)
+Task 2: Handle lock timeout and retry (error handling)
+Task 3: Concurrent access regression tests (prevention)
+```
+
+**Example** (Multiple related issues):
+
+```
+Task 1: Fix primary null pointer with guard clause + test (core fix)
+Task 2: Fix secondary data truncation at boundary + test (related fix)
+Task 3: Add integration test covering the full workflow (regression)
+```
+
+---
+
+## Minimal Change Focus
+
+Each task changes the minimum code needed:
+
+- Don't refactor adjacent code
+- Don't add features while fixing bugs
+- Keep the diff small and reviewable
+- If a task starts growing beyond the fix, it's probably two tasks
+
+---
+
+## Codebase Analysis During Task Design
+
+Tasks must be designed with knowledge of the affected code:
+
+- **Understand the bug's context** — what code is involved? What tests exist? What are the inputs, outputs, and side effects of the affected code?
+- **Design tasks around existing structure** — bug fixes should work within the existing architecture. Don't design tasks that require restructuring unless the specification explicitly calls for it.
+- **Keep scope surgical** — bugfix tasks should touch as few files as possible. If a task needs to touch many files, question whether the fix is truly minimal.
+- **Leverage existing tests** — if relevant tests exist, tasks can extend them. If not, the reproduction test becomes the foundation.
+
+This analysis happens during task design — it informs what needs to change without being documented separately.

package/skills/technical-planning/references/task-design/feature.md

@@ -0,0 +1,61 @@
+# Feature Task Design
+
+*Context guidance for **[task-design.md](../task-design.md)** — feature additions to existing systems*
+
+---
+
+## Integration-Aware Ordering
+
+In feature work, the existing codebase provides the foundation. "Foundation" means whatever the existing codebase doesn't provide yet — new model fields, new routes, service extensions — that other tasks in this phase need.
+
+Extend existing code first, then build new behaviour on top.
+
+**Example** ordering within a phase:
+
+```
+Task 1: Add OAuth fields to User model + migration (extends existing model)
+Task 2: OAuth callback endpoint + token exchange (new route, uses existing auth middleware)
+Task 3: Session creation from OAuth token (extends existing session logic)
+Task 4: Handle provider errors and token validation failures (error handling)
+```
+
+The first task extends what exists. Later tasks build the new behaviour using both existing and newly-added code.
+
+---
+
+## Feature Vertical Slicing
+
+Each task delivers a complete, testable increment that integrates with the existing system. Since infrastructure already exists, tasks can focus on behaviour rather than setup.
+
+**Example** (Extending an existing system):
+
+```
+Task 1: Add search index fields to Product model (extends existing)
+Task 2: Search query endpoint returning products (new endpoint, existing model)
+Task 3: Filter results by category and price range (extends search)
+Task 4: Handle empty results and malformed queries (edge cases)
+```
+
+---
+
+## Follow Existing Patterns
+
+Task implementations should match established conventions in the codebase:
+
+- Use the same testing patterns (if the project uses factory functions, use factories; if it uses fixtures, use fixtures)
+- Follow the existing file organisation and naming conventions
+- Use established service/repository/controller patterns rather than introducing new ones
+- Match the existing error handling approach
+
+---
+
+## Codebase Analysis During Task Design
+
+Tasks must be designed with knowledge of the existing code. Before finalizing task lists:
+
+- **Identify similar implementations** — find existing code that does something similar. Tasks should reference this as the pattern to follow. "Follow the same approach as UserController" is more effective than abstract descriptions.
+- **Map what needs to change** — which files, modules, or services does each task touch? Understanding this shapes task scope and ordering.
+- **Prefer addition over modification** — when possible, design tasks that add new code (functions, modules, endpoints) and call it from existing code, rather than tasks that heavily modify existing code. This reduces risk and makes changes easier to review.
+- **Keep tasks focused** — tasks touching existing code should ideally stay within one file or module. Multi-file tasks in existing codebases are significantly harder to get right.
+
+This analysis happens during task design — it informs task scope and ordering without being documented separately.

package/skills/technical-planning/references/task-design/greenfield.md

@@ -0,0 +1,47 @@
+# Greenfield Task Design
+
+*Context guidance for **[task-design.md](../task-design.md)** — new system builds*
+
+---
+
+## Foundation-First Ordering
+
+In greenfield projects, the first tasks establish the pattern that all subsequent tasks follow. Foundation means models, migrations, base configuration, and core abstractions that other tasks need to build on.
+
+**Example** ordering within a phase:
+
+```
+Task 1: Create Event model and migration (foundation)
+Task 2: Create event via API endpoint (happy path)
+Task 3: Validate event time ranges (error handling)
+Task 4: Handle overlapping events (edge case)
+```
+
+The first task builds what doesn't exist yet. Later tasks extend it.
+
+---
+
+## Greenfield Vertical Slicing
+
+Each task delivers a complete, testable slice of new functionality. Since nothing exists yet, early tasks often establish both the data layer and the first behaviour in a single TDD cycle.
+
+**Example** (Building new feature surfaces from scratch):
+
+```
+Task 1: Room model + create room endpoint (establishes the pattern)
+Task 2: Post message to room (builds on room, adds messaging)
+Task 3: List messages with pagination (extends messaging)
+Task 4: Handle empty room and deleted messages (edge cases)
+```
+
+The first task is slightly larger because it establishes the foundation AND the first working behaviour. Subsequent tasks are narrower because the pattern exists.
+
+---
+
+## Phase 2+ Considerations
+
+After Phase 1 completes, code exists. When designing tasks for subsequent phases:
+
+- **Review what Phase 1 established** — understand the patterns, conventions, and structure that were created. Subsequent tasks should extend these consistently.
+- **Check for drift** — if early implementation decisions could be improved, note them but don't redesign mid-project. Consistency matters more than perfection.
+- **Build on what's there** — subsequent phases have infrastructure to work with. Tasks should use existing models, services, and patterns rather than creating parallel structures.

package/skills/technical-planning/references/task-design.md

@@ -4,7 +4,9 @@
 
 ---
 
-This reference defines the principles for breaking phases into tasks and writing task detail. It is loaded when tasks are first proposed and stays in context through task detailing.
+This reference defines generic principles for breaking phases into tasks and writing task detail.
+
+A work-type context file (greenfield, feature, or bugfix) is always loaded alongside this file. The context file provides task ordering, slicing examples, and work-type-specific guidance. These generic principles apply across all work types.
 
 ## One Task = One TDD Cycle
 
@@ -30,46 +32,11 @@ Cross-cutting references are context, not scope. They shape how tasks are writte
 
 Prefer **vertical slices** that deliver complete, testable functionality over horizontal slices that separate by technical layer.
 
-**Horizontal (avoid)**:
-
-```
-Task 1: Create all database models
-Task 2: Create all service classes
-Task 3: Wire up integrations
-Task 4: Add error handling
-```
-
-Nothing works until Task 4. No task is independently verifiable.
-
-**Vertical (prefer)**:
-
-```
-Task 1: Fetch and store events from provider (happy path)
-Task 2: Handle pagination for large result sets
-Task 3: Handle authentication token refresh
-Task 4: Handle rate limiting
-```
-
-Each task delivers a complete slice of functionality that can be tested in isolation.
-
-Within a bounded feature, vertical slicing means each task completes a coherent unit of that feature's functionality — not that it must touch UI/API/database layers. The test is: *can this task be verified independently?*
+The test: *can this task be verified independently?* If yes, it's a good vertical slice. If it only works once other tasks are complete, it's probably a horizontal slice.
 
 TDD naturally encourages vertical slicing — when you think "what test can I write?", you frame work as complete, verifiable behaviour rather than technical layers.
 
----
-
-## Task Ordering
-
-Within a phase, order tasks by:
-
-1. **Foundation / setup** — models, migrations, base configuration needed by other tasks
-2. **Happy path** — the primary expected behaviour, end-to-end
-3. **Error handling** — validation failures, API errors, permission checks
-4. **Edge cases** — boundary conditions, unusual inputs, race conditions
-
-This ordering means the first tasks establish the pattern and the later tasks extend it. Each task builds on a working foundation rather than building in the dark.
-
-**Edge cases as separate tasks**: Keep the happy-path task focused. If a task's acceptance criteria start growing beyond 3-4 items, the edge cases probably deserve their own tasks. This keeps each TDD cycle tight and each task independently verifiable.
+The context file provides examples of vertical slicing appropriate to the work type.
 
 ---
 
@@ -140,7 +107,7 @@ Every task should follow this structure:
 > Relevant details from specification: code examples, architectural decisions,
 > data models, or constraints that inform implementation.
 
-**Spec Reference**: `docs/workflow/specification/{topic}/specification.md` (if specification was provided)
+**Spec Reference**: `.workflows/specification/{topic}/specification.md` (if specification was provided)
 ```
 
 ### Field Requirements

package/skills/technical-planning/references/verify-source-material.md

@@ -15,6 +15,6 @@ Verify that all source material exists and is accessible before entering agent-d
 ### Example
 
 ```bash
-ls docs/workflow/specification/{topic}/specification.md
-ls docs/workflow/specification/{cross-cutting-spec}/specification.md
+ls .workflows/specification/{topic}/specification.md
+ls .workflows/specification/{cross-cutting-spec}/specification.md
 ```

package/skills/technical-research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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."
+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 .workflows/research/ that may feed into discussion or specification."
 user-invocable: false
 ---
 
@@ -151,7 +151,7 @@ Ask one question at a time. Wait for the answer. Document. Then ask the next.
 
 ## File Strategy
 
-**Output**: `docs/workflow/research/exploration.md`
+**Output**: `.workflows/research/exploration.md`
 
 **Template**: Use `references/template.md` for document structure. All research documents use YAML frontmatter:
 

package/skills/technical-research/references/interview.md

@@ -4,7 +4,7 @@ Focused questioning to probe ideas more deeply during research.
 
 ## Process
 
-1. **Check existing context**: Read docs in `docs/workflow/research/` to understand what's already been explored.
+1. **Check existing context**: Read docs in `.workflows/research/` to understand what's already been explored.
 
 2. **Begin interviewing**: Use the AskUserQuestion tool to probe the idea. Focus on:
    - Non-obvious questions (not things already answered)
@@ -15,7 +15,7 @@ Focused questioning to probe ideas more deeply during research.
 
 3. **Go where it leads**: Follow tangents if they reveal something valuable. This isn't a checklist - it's a conversation.
 
-4. **Document as you go**: Don't defer writing to the end. Capture insights in `docs/workflow/research/` using semantic filenames. Ask before documenting: "Shall I capture that?"
+4. **Document as you go**: Don't defer writing to the end. Capture insights in `.workflows/research/` using semantic filenames. Ask before documenting: "Shall I capture that?"
 
 5. **Commit frequently**: At natural breaks and before context refresh.
 

package/skills/technical-review/SKILL.md

@@ -30,7 +30,7 @@ Either way: Verify plan tasks were implemented, tested adequately, and meet qual
 
 ```
 I need the implementation plan to review against. Could you point me to the
-plan file (e.g., docs/workflow/planning/{topic}/plan.md)?
+plan file (e.g., .workflows/planning/{topic}/plan.md)?
 ```
 
 **STOP.** Wait for user response.

package/skills/technical-review/references/invoke-review-synthesizer.md

@@ -10,10 +10,10 @@ This step dispatches a `review-findings-synthesizer` agent to read review findin
 
 ## Determine Cycle Number
 
-Count existing `review-tasks-c*.md` files in `docs/workflow/implementation/{primary-topic}/` and add 1.
+Count existing `review-tasks-c*.md` files in `.workflows/implementation/{primary-topic}/` and add 1.
 
 ```bash
-ls docs/workflow/implementation/{primary-topic}/review-tasks-c*.md 2>/dev/null | wc -l
+ls .workflows/implementation/{primary-topic}/review-tasks-c*.md 2>/dev/null | wc -l
 ```
 
 ---
@@ -61,4 +61,4 @@ TASKS_PROPOSED: {N}
 SUMMARY: {1-2 sentences}
 ```
 
-The full report is at `docs/workflow/implementation/{primary-topic}/review-report-c{N}.md`. If tasks were proposed, the staging file is at `docs/workflow/implementation/{primary-topic}/review-tasks-c{N}.md`.
+The full report is at `.workflows/implementation/{primary-topic}/review-report-c{N}.md`. If tasks were proposed, the staging file is at `.workflows/implementation/{primary-topic}/review-tasks-c{N}.md`.

package/skills/technical-review/references/invoke-review-task-writer.md

@@ -10,7 +10,7 @@ This step invokes the task writer agent to create plan tasks from approved revie
 
 ## Determine Format
 
-Read the `format` field from the plan's frontmatter (`docs/workflow/planning/{topic}/plan.md`). This determines which output format adapters to pass to the agent.
+Read the `format` field from the plan's frontmatter (`.workflows/planning/{topic}/plan.md`). This determines which output format adapters to pass to the agent.
 
 ---
 
@@ -21,7 +21,7 @@ Read the `format` field from the plan's frontmatter (`docs/workflow/planning/{to
 Pass via the orchestrator's prompt:
 
 1. **Topic name** — the implementation topic (scopes tasks to correct plan)
-2. **Staging file path** — `docs/workflow/implementation/{topic}/review-tasks-c{cycle-number}.md`
+2. **Staging file path** — `.workflows/implementation/{topic}/review-tasks-c{cycle-number}.md`
 3. **Plan path** — the implementation plan path
 4. **Plan format reading adapter path** — `../../technical-planning/references/output-formats/{format}/reading.md`
 5. **Plan format authoring adapter path** — `../../technical-planning/references/output-formats/{format}/authoring.md`

package/skills/technical-review/references/invoke-task-verifiers.md

@@ -35,7 +35,7 @@ From each plan in scope, list every task across all phases:
 Ensure the review output directory exists:
 
 ```bash
-mkdir -p docs/workflow/review/{topic}/r{N}
+mkdir -p .workflows/review/{topic}/r{N}
 ```
 
 ---
@@ -78,7 +78,7 @@ FINDINGS_COUNT: {N blocking issues}
 SUMMARY: {1 sentence}
 ```
 
-Full findings are written to `docs/workflow/review/{topic}/r{N}/qa-task-{index}.md`.
+Full findings are written to `.workflows/review/{topic}/r{N}/qa-task-{index}.md`.
 
 ---
 
@@ -86,7 +86,7 @@ Full findings are written to `docs/workflow/review/{topic}/r{N}/qa-task-{index}.
 
 Once all batches have completed:
 
-1. Read all `docs/workflow/review/{topic}/r{N}/qa-task-*.md` files
+1. Read all `.workflows/review/{topic}/r{N}/qa-task-*.md` files
 2. Synthesize findings from file contents:
    - Collect all tasks with `STATUS: Incomplete` or `STATUS: Issues Found` as blocking issues
    - Collect all test issues (under/over-tested)

package/skills/technical-review/references/produce-review.md

@@ -6,7 +6,7 @@
 
 Aggregate QA findings into a review document using the **[template.md](template.md)**.
 
-Write the review to `docs/workflow/review/{topic}/r{N}/review.md`. The review is always per-plan. The review number `r{N}` is passed in from the entry point.
+Write the review to `.workflows/review/{topic}/r{N}/review.md`. The review is always per-plan. The review number `r{N}` is passed in from the entry point.
 
 **QA Verdict** (from Step 3):
 - **Approve** — All acceptance criteria met, no blocking issues

package/skills/technical-review/references/review-actions-loop.md

@@ -122,7 +122,7 @@ No actionable tasks synthesized.
 
 ## C. Approval Gate
 
-Read the staging file from `docs/workflow/implementation/{topic}/review-tasks-c{cycle-number}.md`.
+Read the staging file from `.workflows/implementation/{topic}/review-tasks-c{cycle-number}.md`.
 
 Check `gate_mode` in the staging file frontmatter (`gated` or `auto`).
 
@@ -165,8 +165,10 @@ Sources: {sources}
 
 ```
 · · · · · · · · · · · ·
-- **`a`/`approve`** — Approve this task
-- **`auto`** — Approve this and all remaining tasks automatically
+Approve this task?
+
+- **`y`/`yes`** — Approve this task
+- **`a`/`auto`** — Approve this and all remaining tasks automatically
 - **`s`/`skip`** — Skip this task
 - **Comment** — Revise based on feedback
 · · · · · · · · · · · ·
@@ -188,7 +190,7 @@ Task {current} of {total}: {title} — approved (auto).
 
 Process user input:
 
-#### If `approve`
+#### If `yes`
 
 Update `status: approved` in the staging file.
 
@@ -252,7 +254,7 @@ review({topic}): add review remediation ({K} tasks)
 
 For each plan that received new tasks:
 
-1. Read the implementation tracking file at `docs/workflow/implementation/{topic}/tracking.md`
+1. Read the implementation tracking file at `.workflows/implementation/{topic}/tracking.md`
 2. Update frontmatter:
    - `status: in-progress`
    - Remove `completed` field (if present)

package/skills/technical-specification/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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}/specification.md that can be used to build implementation plans."
+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 .workflows/specification/{topic}/specification.md that can be used to build implementation plans."
 user-invocable: false
 ---
 
@@ -35,7 +35,7 @@ Either way: Transform unvalidated reference material into a specification that's
 
 ```
 I need source material to build a specification from. Could you point me to the
-source files (e.g., docs/workflow/discussion/{topic}.md), or provide the content
+source files (e.g., .workflows/discussion/{topic}.md), or provide the content
 directly?
 ```
 
@@ -47,7 +47,7 @@ directly?
 
 ```
 What should the specification be named? This determines the output file:
-docs/workflow/specification/{name}/specification.md
+.workflows/specification/{name}/specification.md
 ```
 
 **STOP.** Wait for user response.
@@ -97,7 +97,7 @@ When announcing a new step, output `── ── ── ── ──` on its o
 
 ## Step 0: Resume Detection
 
-Check if `docs/workflow/specification/{topic}/specification.md` exists.
+Check if `.workflows/specification/{topic}/specification.md` exists.
 
 #### If no file exists
 
@@ -147,7 +147,7 @@ Load **[verify-source-material.md](references/verify-source-material.md)** and f
 
 Load **[specification-format.md](references/specification-format.md)** for the template.
 
-Create the specification file at `docs/workflow/specification/{topic}/specification.md`:
+Create the specification file at `.workflows/specification/{topic}/specification.md`:
 
 1. Use the frontmatter template from specification-format.md
 2. Set `topic` to the kebab-case topic name

package/skills/technical-specification/references/dependencies.md

@@ -12,9 +12,9 @@ The same workflow applies: present the dependencies section for approval, then l
 
 Dependencies are **blockers** — things that must exist before implementation can begin.
 
-Think of it like building a house: if you're specifying the roof, the walls are a dependency. You cannot build a roof without walls to support it. The walls must exist first.
+If feature B requires data that feature A produces, then feature A is a dependency — B cannot function without A's output existing first.
 
-**The test**: "If system X doesn't exist, can we still build this feature?"
+**The test**: "If system X doesn't exist, can we still deliver this?"
 - If **no** → X is a dependency
 - If **yes** → X is not a dependency (even if the systems work together)
 

package/skills/technical-specification/references/review-tracking-format.md

@@ -8,7 +8,7 @@ Review tracking files capture analysis findings so work persists across context
 
 ## Location
 
-Store tracking files in the specification topic directory (`docs/workflow/specification/{topic}/`), cycle-numbered:
+Store tracking files in the specification topic directory (`.workflows/specification/{topic}/`), cycle-numbered:
 - `review-input-tracking-c{N}.md` — Phase 1 findings for cycle N
 - `review-gap-analysis-tracking-c{N}.md` — Phase 2 findings for cycle N
 

package/skills/technical-specification/references/specification-format.md

@@ -4,7 +4,7 @@
 
 ---
 
-This file defines the canonical structure for specification files (`docs/workflow/specification/{topic}/specification.md`).
+This file defines the canonical structure for specification files (`.workflows/specification/{topic}/specification.md`).
 
 The specification is a single file per topic. Structure is **flexible** — organize around phases and subject matter, not rigid sections. This is a working document.
 

package/skills/technical-specification/references/verify-source-material.md

@@ -15,6 +15,6 @@ Verify that all source material exists and is accessible before beginning specif
 ### Example
 
 ```bash
-ls docs/workflow/discussion/auth-flow.md
-ls docs/workflow/research/api-patterns.md
+ls .workflows/discussion/auth-flow.md
+ls .workflows/research/api-patterns.md
 ```

package/skills/view-plan/SKILL.md

@@ -17,14 +17,14 @@ Display a readable summary of a plan's phases, tasks, and status.
 If no topic is specified, list available plans:
 
 ```bash
-ls docs/workflow/planning/
+ls .workflows/planning/
 ```
 
 Ask the user which plan to view.
 
 ## Step 2: Read the Plan Index
 
-Read the plan file from `docs/workflow/planning/{topic}/plan.md` and check the `format:` field in the frontmatter.
+Read the plan file from `.workflows/planning/{topic}/plan.md` and check the `format:` field in the frontmatter.
 
 ## Step 3: Load Format Reading Reference