@leeovery/claude-technical-workflows 2.1.40 → 2.1.42

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

@@ -0,0 +1,75 @@
+# Greenfield Phase Design
+
+*Context guidance for **[phase-design.md](../phase-design.md)** — new system builds*
+
+---
+
+## The Walking Skeleton
+
+Phase 1 is always a **walking skeleton** — the thinnest possible end-to-end slice that threads through all system layers and proves the architecture works.
+
+The walking skeleton:
+
+- Touches every architectural component the system needs (database, API, UI, external services)
+- Delivers one complete flow, however minimal
+- Establishes the patterns subsequent phases will follow
+- Is production code, not throwaway — it becomes the foundation
+
+**Example** (Slack clone):
+
+> Phase 1: "Any unauthenticated person can post messages in a hardcoded #general room. Messages persist through page refreshes."
+>
+> No auth, no accounts, no multiple rooms. Just the thinnest thread through the entire stack.
+
+**Example** (Calendar app):
+
+> Phase 1: "A single event can be created with title, start, and end time, persisted, and retrieved by ID."
+>
+> No recurrence, no sharing, no notifications. Just one thing working end-to-end.
+
+The skeleton validates architecture assumptions at the cheapest possible moment. If the end-to-end flow doesn't work, you discover it in Phase 1 — not after building three phases of isolated components.
+
+This is the **steel thread** principle: never have big-bang integration. By threading through all layers immediately, integration is the first thing you solve, not the last.
+
+---
+
+## Greenfield Vertical Phases
+
+After the walking skeleton, each subsequent phase adds complete functionality — a vertical slice through the relevant layers.
+
+```
+Phase 1: Walking skeleton — single event CRUD, end-to-end
+Phase 2: Recurring events — rules, instance generation, single-instance editing
+Phase 3: Sharing and permissions — invite users, permission levels, shared calendars
+Phase 4: Notifications — email and push notifications for event changes
+```
+
+Each phase delivers something a user or test suite can validate independently.
+
+### Progression
+
+**Skeleton → Core features → Edge cases → Refinement**
+
+- **Skeleton** (Phase 1): Thinnest end-to-end slice proving the architecture
+- **Core features**: Each phase adds a complete capability, building on what exists
+- **Edge cases**: Handling boundary conditions, error scenarios, unusual inputs
+- **Refinement**: Performance optimisation, UX polish, hardening
+
+This ordering means each phase builds on a working system. The skeleton establishes the pattern; core features flesh it out; edge cases harden it; refinement polishes it.
+
+---
+
+## Cross-Phase Coupling (Greenfield)
+
+- **Walking skeleton first** — subsequent phases add to a working system rather than depending on future phases
+- **Shared infrastructure in Phase 1** — if multiple phases need the same foundation, it belongs in the skeleton
+
+---
+
+## Phase 2+ Considerations
+
+After Phase 1 is implemented, code exists. When designing subsequent phases:
+
+- **Review what Phase 1 established** — understand the patterns, conventions, and architectural decisions that were made. Subsequent phases should build on these consistently.
+- **Extend, don't reinvent** — Phase 2+ should use the infrastructure Phase 1 created. If something is missing, add it — don't create parallel structures.
+- **Watch for drift** — if early decisions could be improved, note them but maintain consistency unless the specification calls for restructuring.

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

@@ -4,7 +4,9 @@
 
 ---
 
-This reference defines the principles for breaking specifications into implementation phases. It is loaded when phases are first proposed and stays in context through phase approval.
+This reference defines generic principles for breaking specifications into implementation phases.
+
+A work-type context file (greenfield, feature, or bugfix) is always loaded alongside this file. The context file provides the Phase 1 strategy, progression model, examples, and work-type-specific guidance. These generic principles apply across all work types.
 
 ## What Makes a Good Phase
 
@@ -18,49 +20,9 @@ Each phase should:
 
 ---
 
-## The Walking Skeleton
-
-Phase 1 is always a **walking skeleton** — the thinnest possible end-to-end slice that threads through all system layers and proves the architecture works.
-
-The walking skeleton:
-
-- Touches every architectural component the system needs (database, API, UI, external services)
-- Delivers one complete flow, however minimal
-- Establishes the patterns subsequent phases will follow
-- Is production code, not throwaway — it becomes the foundation
-
-**Example** (Slack clone):
-
-> Phase 1: "Any unauthenticated person can post messages in a hardcoded #general room. Messages persist through page refreshes."
->
-> No auth, no accounts, no multiple rooms. Just the thinnest thread through the entire stack.
-
-**Example** (Calendar app):
-
-> Phase 1: "A single event can be created with title, start, and end time, persisted, and retrieved by ID."
->
-> No recurrence, no sharing, no notifications. Just one thing working end-to-end.
-
-The skeleton validates architecture assumptions at the cheapest possible moment. If the end-to-end flow doesn't work, you discover it in Phase 1 — not after building three phases of isolated components.
-
-This is the **steel thread** principle: never have big-bang integration. By threading through all layers immediately, integration is the first thing you solve, not the last.
-
----
-
 ## Vertical Phases
 
-After the walking skeleton, each subsequent phase adds complete functionality — a vertical slice through the relevant layers.
-
-**Vertical (prefer):**
-
-```
-Phase 1: Walking skeleton — single event CRUD, end-to-end
-Phase 2: Recurring events — rules, instance generation, single-instance editing
-Phase 3: Sharing and permissions — invite users, permission levels, shared calendars
-Phase 4: Notifications — email and push notifications for event changes
-```
-
-Each phase delivers something a user or test suite can validate independently.
+Each phase adds complete functionality — a vertical slice through the relevant layers.
 
 **Horizontal (avoid):**
 
@@ -76,17 +38,6 @@ Nothing works until Phase 5. No phase is independently testable. Integration ris
 
 A phase may touch multiple architectural layers — that's expected. The test is: **does this phase deliver working functionality, or does it deliver infrastructure that only becomes useful later?**
 
-### Progression
-
-**Skeleton → Core features → Edge cases → Refinement**
-
-- **Skeleton** (Phase 1): Thinnest end-to-end slice proving the architecture
-- **Core features**: Each phase adds a complete capability, building on what exists
-- **Edge cases**: Handling boundary conditions, error scenarios, unusual inputs
-- **Refinement**: Performance optimisation, UX polish, hardening
-
-This ordering means each phase builds on a working system. The skeleton establishes the pattern; core features flesh it out; edge cases harden it; refinement polishes it.
-
 ---
 
 ## Phase Boundaries
@@ -122,20 +73,19 @@ If a phase has only 1-2 trivial tasks, it's probably too thin — merge it. If a
 
 **Maximize cohesion within a phase, minimize dependencies between phases.**
 
-A well-bounded phase could theoretically be reordered or dropped without cascading failures across other phases. In practice, phases have a natural sequence (the skeleton must come first), but each phase should be as self-contained as possible.
+A well-bounded phase could theoretically be reordered or dropped without cascading failures across other phases. In practice, phases have a natural sequence, but each phase should be as self-contained as possible.
 
 Strategies:
 
-- **Walking skeleton first** — subsequent phases add to a working system rather than depending on future phases
+- **Strongest foundation first** — subsequent phases add to a working system rather than depending on future phases
 - **Clear interfaces between phases** — each phase produces defined contracts (API shapes, data models, test suites) that subsequent phases consume
-- **Shared infrastructure in Phase 1** — if multiple phases need the same foundation, it belongs in the skeleton
 - **No forward references** — a phase should never depend on something that hasn't been built yet
 
 ---
 
 ## Anti-Patterns
 
-**Horizontal phases** — organising by technical layer ("all models, then all services, then all controllers"). Defers integration risk, produces phases that aren't independently valuable. The walking skeleton eliminates this by integrating from the start.
+**Horizontal phases** — organising by technical layer ("all models, then all services, then all controllers"). Defers integration risk, produces phases that aren't independently valuable. Vertical slicing eliminates this by integrating from the start.
 
 **God phase** — one massive phase covering too many concerns. Results in unclear success criteria, inability to track progress, and cognitive overload. If you can't summarise a phase's goal in one sentence, it needs splitting.
 

package/skills/technical-planning/references/plan-index-schema.md

@@ -4,7 +4,7 @@
 
 ---
 
-This file defines the canonical structure for Plan Index Files (`docs/workflow/planning/{topic}/plan.md`). All agents and references that create or update plan index content **must** follow these templates.
+This file defines the canonical structure for Plan Index Files (`.workflows/planning/{topic}/plan.md`). All agents and references that create or update plan index content **must** follow these templates.
 
 ---
 
@@ -15,6 +15,7 @@ This file defines the canonical structure for Plan Index Files (`docs/workflow/p
 topic: {topic-name}
 status: {status}
 format: {chosen-format}
+work_type:
 ext_id:
 specification: ../specification/{topic}/specification.md
 cross_cutting_specs:
@@ -37,6 +38,7 @@ planning:
 | `topic` | Plan creation (Step 1) |
 | `status` | Plan creation → `planning`; conclusion → `concluded` |
 | `format` | Plan creation — user-chosen output format |
+| `work_type` | Plan creation — set by caller if known. Values: `greenfield`, `feature`, `bugfix`. Defaults to `greenfield` when empty. |
 | `ext_id` | First task authored — external identifier for the plan |
 | `specification` | Plan creation — relative path to source specification |
 | `cross_cutting_specs` | Plan creation — relative paths to cross-cutting specs (omit key if none) |

package/skills/technical-planning/references/review-integrity.md

@@ -75,7 +75,7 @@ Read the plan end-to-end — carefully, as if you were about to implement it. Fo
 
 ## Tracking File
 
-After completing the analysis, create a tracking file at `docs/workflow/planning/{topic}/review-integrity-tracking-c{N}.md` (where N is the current review cycle).
+After completing the analysis, create a tracking file at `.workflows/planning/{topic}/review-integrity-tracking-c{N}.md` (where N is the current review cycle).
 
 Categorize each finding by severity:
 

package/skills/technical-planning/references/review-traceability.md

@@ -59,7 +59,7 @@ Is everything in the plan actually from the specification? This is the anti-hall
 
 ## Tracking File
 
-After completing the analysis, create a tracking file at `docs/workflow/planning/{topic}/review-traceability-tracking-c{N}.md` (where N is the current review cycle).
+After completing the analysis, create a tracking file at `.workflows/planning/{topic}/review-traceability-tracking-c{N}.md` (where N is the current review cycle).
 
 Tracking files are **never deleted**. After all findings are processed, the orchestrator marks `status: complete`. Previous cycles' files persist as review history.
 

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)