@leeovery/claude-technical-workflows 2.1.39 → 2.1.41

package/skills/technical-planning/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: technical-planning
-description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from docs/workflow/specification/{topic}/specification.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/planning/{topic}/plan.md that can be executed via strict TDD."
+description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from .workflows/specification/{topic}/specification.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in .workflows/planning/{topic}/plan.md that can be executed via strict TDD."
 user-invocable: false
 ---
 
@@ -24,6 +24,7 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 - **Topic name** (optional) - Will derive from specification if not provided
 - **Output format preference** (optional) - Will ask if not specified
 - **Recommended output format** (optional) - A format suggestion for consistency with existing plans
+- **Work type** (optional) — `greenfield`, `feature`, or `bugfix`. Determines which context-specific guidance is loaded during phase and task design. Defaults to `greenfield` when not provided.
 - **Cross-cutting references** (optional) - Cross-cutting specifications that inform technical decisions in this plan
 
 **Before proceeding**, verify the required input is available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
@@ -34,7 +35,7 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 
 ```
 I need the specification content to plan from. Could you point me to the
-specification file (e.g., docs/workflow/specification/{topic}/specification.md),
+specification file (e.g., .workflows/specification/{topic}/specification.md),
 or provide the content directly?
 ```
 
@@ -59,7 +60,7 @@ this, or is there a more complete version?
 Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:
 
 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. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress. Check for scratch files at `docs/workflow/.cache/planning/{topic}/`. If a scratch file exists, you are mid-authoring for that phase — resume the approval loop in author-tasks.md.
+2. **Read all tracking and state files** for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress. Check for scratch files at `.workflows/.cache/planning/{topic}/`. If a scratch file exists, you are mid-authoring for that phase — resume the approval loop in author-tasks.md.
 3. **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.
 4. **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.
 5. **Check `task_list_gate_mode`, `author_gate_mode`, and `finding_gate_mode`** in the Plan Index File frontmatter — if `auto`, the user previously opted in during this session. Preserve these values.
@@ -72,7 +73,7 @@ Do not guess at progress or continue from memory. The files on disk and git hist
 
 This process constructs a plan from a specification. A plan consists of:
 
-- **Plan Index File** — `docs/workflow/planning/{topic}/plan.md`. Contains frontmatter (topic, format, status, progress), phases with acceptance criteria, and task tables tracking status. This is the single source of truth for planning progress.
+- **Plan Index File** — `.workflows/planning/{topic}/plan.md`. Contains frontmatter (topic, format, status, progress), phases with acceptance criteria, and task tables tracking status. This is the single source of truth for planning progress.
 - **Authored Tasks** — Detailed task files written to the chosen **Output Format** (selected during planning). The output format determines where and how task detail is stored.
 
 Follow every step in sequence. No steps are optional.
@@ -85,7 +86,7 @@ When announcing a new step, output `── ── ── ── ──` on its o
 
 ## Step 0: Resume Detection
 
-Check if a Plan Index File already exists at `docs/workflow/planning/{topic}/plan.md`.
+Check if a Plan Index File already exists at `.workflows/planning/{topic}/plan.md`.
 
 #### If no Plan Index File exists
 
@@ -126,7 +127,7 @@ Reset `task_list_gate_mode`, `author_gate_mode`, and `finding_gate_mode` to `gat
 
 1. Read **[output-formats.md](references/output-formats.md)**, find the entry matching the `format:` field in the Plan Index File, and load the format's **[authoring.md](references/output-formats/{format}/authoring.md)**
 2. Follow the authoring file's cleanup instructions to remove Authored Tasks for this topic
-3. Delete the scratch directory if it exists: `rm -rf docs/workflow/.cache/planning/{topic}/`
+3. Delete the scratch directory if it exists: `rm -rf .workflows/.cache/planning/{topic}/`
 4. Delete the Plan Index File
 5. Commit: `planning({topic}): restart planning`
 
@@ -173,7 +174,7 @@ Once selected:
 
 1. Read **[output-formats.md](references/output-formats.md)**, find the chosen format entry, and load the format's **[about.md](references/output-formats/{format}/about.md)** and **[authoring.md](references/output-formats/{format}/authoring.md)**
 2. Capture the current git commit hash: `git rev-parse HEAD`
-3. Create the Plan Index File at `docs/workflow/planning/{topic}/plan.md` using the **Frontmatter** and **Title** templates from **[plan-index-schema.md](references/plan-index-schema.md)**. Set `status: planning`, `spec_commit` to the captured git hash, and today's actual date for `created` and `updated`.
+3. Create the Plan Index File at `.workflows/planning/{topic}/plan.md` using the **Frontmatter** and **Title** templates from **[plan-index-schema.md](references/plan-index-schema.md)**. Set `status: planning`, `spec_commit` to the captured git hash, today's actual date for `created` and `updated`, and `work_type` to the value provided by the caller (or `greenfield` if not provided).
 
 3. Commit: `planning({topic}): initialize plan`
 

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

@@ -23,7 +23,7 @@ Read **[output-formats.md](output-formats.md)**, find the entry matching the `fo
 
 Invoke `planning-dependency-grapher` with these file paths:
 
-1. **Plan Index File path**: `docs/workflow/planning/{topic}/plan.md`
+1. **Plan Index File path**: `.workflows/planning/{topic}/plan.md`
 2. **reading.md**: the format's reading reference loaded above
 3. **graph.md**: the format's graph reference loaded above
 

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

@@ -10,9 +10,9 @@ This step uses the `planning-task-author` agent (`../../../agents/planning-task-
 
 ## Section 1: Prepare the Scratch File
 
-Scratch file path: `docs/workflow/.cache/planning/{topic}/phase-{N}.md`
+Scratch file path: `.workflows/.cache/planning/{topic}/phase-{N}.md`
 
-Create the `docs/workflow/.cache/planning/{topic}/` directory if it does not exist.
+Create the `.workflows/.cache/planning/{topic}/` directory if it does not exist.
 
 ---
 
@@ -32,7 +32,7 @@ Invoke `planning-task-author` with these file paths:
 4. **task-design.md**: `task-design.md`
 5. **All approved phases**: the complete phase structure from the Plan Index File body
 6. **Task list for current phase**: the approved task table (ALL tasks in the phase)
-7. **Scratch file path**: `docs/workflow/.cache/planning/{topic}/phase-{N}.md`
+7. **Scratch file path**: `.workflows/.cache/planning/{topic}/phase-{N}.md`
 
 The agent writes all tasks to the scratch file and returns.
 
@@ -183,8 +183,8 @@ Repeat for each task.
 
 ## Section 7: Cleanup
 
-Delete the scratch file: `rm docs/workflow/.cache/planning/{topic}/phase-{N}.md`
+Delete the scratch file: `rm .workflows/.cache/planning/{topic}/phase-{N}.md`
 
-Remove the `docs/workflow/.cache/planning/{topic}/` directory if empty.
+Remove the `.workflows/.cache/planning/{topic}/` directory if empty.
 
 → Return to **Plan Construction**.

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

@@ -34,14 +34,17 @@ independently testable stages.
 
 ### Invoke the Agent
 
+Read `work_type` from the Plan Index File frontmatter.
+
 Invoke `planning-phase-designer` with these file paths:
 
 1. **read-specification.md**: `read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
 4. **phase-design.md**: `phase-design.md`
-5. **task-design.md**: `task-design.md`
-6. **plan-index-schema.md**: `plan-index-schema.md`
+5. **Context guidance**: `phase-design/{work_type}.md` (default to `greenfield` if `work_type` is empty)
+6. **task-design.md**: `task-design.md`
+7. **plan-index-schema.md**: `plan-index-schema.md`
 
 The agent returns a complete phase structure. Write it directly to the Plan Index File body.
 

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

@@ -20,15 +20,18 @@ propose a task list.
 
 ### Invoke the Agent
 
+Read `work_type` from the Plan Index File frontmatter.
+
 Invoke `planning-task-designer` with these file paths:
 
 1. **read-specification.md**: `read-specification.md`
 2. **Specification**: path from the Plan Index File's `specification:` field
 3. **Cross-cutting specs**: paths from the Plan Index File's `cross_cutting_specs:` field (if any)
 4. **task-design.md**: `task-design.md`
-5. **All approved phases**: the complete phase structure from the Plan Index File body
-6. **Target phase number**: the phase being broken into tasks
-7. **plan-index-schema.md**: `plan-index-schema.md`
+5. **Context guidance**: `task-design/{work_type}.md` (default to `greenfield` if `work_type` is empty)
+6. **All approved phases**: the complete phase structure from the Plan Index File body
+7. **Target phase number**: the phase being broken into tasks
+8. **plan-index-schema.md**: `plan-index-schema.md`
 
 ### Present the Output
 

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

@@ -13,7 +13,7 @@ This step invokes the `planning-review-integrity` agent (`../../../agents/planni
 Invoke `planning-review-integrity` with:
 
 1. **Review criteria path**: `review-integrity.md` (in this directory)
-2. **Plan path**: `docs/workflow/planning/{topic}/plan.md`
+2. **Plan path**: `.workflows/planning/{topic}/plan.md`
 3. **Format reading.md path**: load **[output-formats.md](output-formats.md)**, find the entry matching the plan's `format:` field, and pass the format's `reading.md` path
 4. **Cycle number**: current `review_cycle` from the Plan Index File frontmatter
 5. **Topic name**: from the plan's `topic` frontmatter field

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

@@ -14,7 +14,7 @@ Invoke `planning-review-traceability` with:
 
 1. **Review criteria path**: `review-traceability.md` (in this directory)
 2. **Specification path**: from the plan's `specification` frontmatter field (resolved relative to the plan directory)
-3. **Plan path**: `docs/workflow/planning/{topic}/plan.md`
+3. **Plan path**: `.workflows/planning/{topic}/plan.md`
 4. **Format reading.md path**: load **[output-formats.md](output-formats.md)**, find the entry matching the plan's `format:` field, and pass the format's `reading.md` path
 5. **Cycle number**: current `review_cycle` from the Plan Index File frontmatter
 6. **Topic name**: from the plan's `topic` frontmatter field

package/skills/technical-planning/references/output-formats/local-markdown/about.md

@@ -21,7 +21,7 @@ No external tools required. This format uses plain markdown files stored in the
 
 | Concept | Local Markdown Entity |
 |---------|-----------------------|
-| Topic | Directory (`docs/workflow/planning/{topic}/`) |
+| Topic | Directory (`.workflows/planning/{topic}/`) |
 | Phase | Encoded in task ID (`{topic}-{phase}-{seq}`) |
 | Task | Markdown file (`{task-id}.md`) |
 | Dependency | Task ID reference in frontmatter (no native blocking) |
@@ -31,7 +31,7 @@ No external tools required. This format uses plain markdown files stored in the
 Tasks are stored as individual markdown files in a `tasks/` subdirectory under the topic directory:
 
 ```
-docs/workflow/planning/{topic}/
+.workflows/planning/{topic}/
 ├── plan.md                     # Plan Index File (not a task)
 └── tasks/                      # Task files
     ├── {topic}-1-1.md          # Phase 1, task 1

package/skills/technical-planning/references/output-formats/local-markdown/authoring.md

@@ -2,7 +2,7 @@
 
 ## Task Storage
 
-Each task is written to `docs/workflow/planning/{topic}/tasks/{task-id}.md` — a markdown file with frontmatter and a description body.
+Each task is written to `.workflows/planning/{topic}/tasks/{task-id}.md` — a markdown file with frontmatter and a description body.
 
 ```markdown
 ---
@@ -60,5 +60,5 @@ In the task file, add a **Needs Clarification** section:
 Delete the tasks directory — preserves `plan.md` (the Plan Index) and any review tracking files:
 
 ```bash
-rm -rf docs/workflow/planning/{topic}/tasks/
+rm -rf .workflows/planning/{topic}/tasks/
 ```

package/skills/technical-planning/references/output-formats/local-markdown/reading.md

@@ -4,7 +4,7 @@
 
 To retrieve all tasks for a plan:
 
-1. List all `.md` files in `docs/workflow/planning/{topic}/tasks/` — every file in this directory is a task file, no filtering needed
+1. List all `.md` files in `.workflows/planning/{topic}/tasks/` — every file in this directory is a task file, no filtering needed
 2. Read each file's frontmatter to extract: `id`, `phase`, `status`, `priority`, `depends_on`
 3. Read the first heading for the task title
 
@@ -12,7 +12,7 @@ This provides the summary-level data needed for graphing, progress overview, or
 
 ## Extracting a Task
 
-To read a specific task, read the file at `docs/workflow/planning/{topic}/tasks/{task-id}.md`.
+To read a specific task, read the file at `.workflows/planning/{topic}/tasks/{task-id}.md`.
 
 The task file is self-contained — frontmatter holds id, phase, and status. The body contains the title and full description.
 
@@ -20,7 +20,7 @@ The task file is self-contained — frontmatter holds id, phase, and status. The
 
 To find the next task to implement:
 
-1. List all `.md` files in `docs/workflow/planning/{topic}/tasks/`
+1. List all `.md` files in `.workflows/planning/{topic}/tasks/`
 2. Filter to tasks where `status` is `pending` or `in-progress` (or missing — treat as `pending`)
 3. If any tasks have `depends_on`, check each referenced task's `status` — exclude the task unless all dependencies have `status: completed`
 4. Order by phase number (from task ID: `{topic}-{phase}-{seq}`) — complete all earlier phases first

package/skills/technical-planning/references/output-formats/local-markdown/updating.md

@@ -2,7 +2,7 @@
 
 ## Status Transitions
 
-Update the `status` field in the task file frontmatter at `docs/workflow/planning/{topic}/tasks/{task-id}.md`:
+Update the `status` field in the task file frontmatter at `.workflows/planning/{topic}/tasks/{task-id}.md`:
 
 | Transition | Value |
 |------------|-------|

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

@@ -0,0 +1,75 @@
+# Bugfix Phase Design
+
+*Context guidance for **[phase-design.md](../phase-design.md)** — bug fixes*
+
+---
+
+## Phase 1 Strategy
+
+Reproduce the bug and implement the fix. Start with a failing test that demonstrates the bug, then fix it.
+
+Phase 1 should:
+
+- Include a test that reliably reproduces the bug (the test fails before the fix, passes after)
+- Fix the root cause, not symptoms
+- Verify that existing tests still pass (no regressions)
+- Be as minimal as possible — change only what's necessary
+
+---
+
+## Single vs Multi-Phase Bugs
+
+Most bugs are **single-phase**: reproduce → fix → regression tests. One phase is sufficient when the bug has a single root cause and the fix is contained.
+
+Multiple phases are warranted when:
+
+- **Multiple root causes** — the bug manifests in one place but originates in different subsystems that need independent fixes
+- **Incremental refactoring required** — the fix requires restructuring code that can't be safely changed in one step
+- **Large impact area** — the fix touches enough code that dedicated regression verification in a separate phase reduces risk
+
+**Example** (Single-phase — N+1 query):
+
+```
+Phase 1: Add eager loading to order query, verify performance, regression tests
+```
+
+**Example** (Multi-phase — Race condition in payment processing):
+
+```
+Phase 1: Add locking mechanism, fix the core race condition, verify with concurrent test
+Phase 2: Add idempotency keys, handle edge cases (duplicate submissions, timeout recovery)
+```
+
+---
+
+## Minimal Change Principle
+
+Fix the root cause, don't redesign. The goal is surgical correction:
+
+- Change the minimum code needed to resolve the issue
+- Don't expand scope beyond what the specification defines
+- Resist the temptation to "improve" surrounding code
+- The fix should be easy to review — a reviewer should immediately see what changed and why
+
+---
+
+## Regression Prevention
+
+Regression tests are first-class deliverables, not afterthoughts:
+
+- Every fix includes tests that would have caught the original bug
+- Tests verify the fix doesn't break existing behaviour
+- Edge cases related to the bug get their own test cases
+- If the bug was in a poorly-tested area, the fix improves coverage for that specific area (not a general testing campaign)
+
+---
+
+## Codebase Awareness
+
+Before designing bugfix phases, understand the affected area:
+
+- **Trace the bug's scope** — what code is involved? What calls into it, what does it call? Understanding the boundaries helps design a fix that doesn't cause side effects.
+- **Check existing tests** — what coverage exists? This informs whether the fix needs new test infrastructure or can extend existing tests.
+- **Understand before fixing** — a minimal fix requires knowing exactly what's broken and why. Don't design phases until the root cause is understood.
+
+This is targeted analysis, not a general codebase review — focus on the code paths involved in the bug.

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

@@ -0,0 +1,77 @@
+# Feature Phase Design
+
+*Context guidance for **[phase-design.md](../phase-design.md)** — feature additions to existing systems*
+
+---
+
+## Phase 1 Strategy
+
+Deliver the most fundamental new capability first. The existing codebase IS the foundation — no need to re-prove architecture. Integration with established patterns is the priority.
+
+Phase 1 should:
+
+- Add the core new behaviour that all subsequent phases build on
+- Integrate naturally with existing code and conventions
+- Verify both the new functionality AND that existing behaviour isn't broken
+- Follow the project's established architectural patterns
+
+---
+
+## Feature Vertical Phases
+
+Each phase adds a complete slice of the new feature, building on the existing system.
+
+**Example** (Adding OAuth to existing Express API):
+
+```
+Phase 1: Basic OAuth flow — provider registration, callback, token exchange, session creation
+Phase 2: Permission scoping — granular permissions, role mapping, scope enforcement
+Phase 3: Token lifecycle — refresh tokens, expiry handling, revocation
+Phase 4: Edge cases — concurrent sessions, provider downtime, account linking
+```
+
+**Example** (Adding search to existing e-commerce app):
+
+```
+Phase 1: Basic keyword search — index products, query endpoint, display results
+Phase 2: Filtering and facets — category filters, price ranges, attribute facets
+Phase 3: Relevance tuning — boosting, synonyms, typo tolerance
+```
+
+Each phase delivers functionality that users or tests can validate against the existing system.
+
+### Progression
+
+**Core new functionality → Extended capability → Edge cases → Refinement**
+
+- **Core new functionality** (Phase 1): The fundamental new behaviour, integrated with existing code
+- **Extended capability**: Richer variations, additional options, deeper integration
+- **Edge cases**: Boundary conditions, failure modes, interaction with existing features
+- **Refinement**: Performance, UX polish, hardening
+
+---
+
+## Integration Considerations
+
+- **Follow existing patterns** — if the codebase uses service classes, add service classes. If it uses middleware, add middleware. Don't introduce new architectural patterns unless the specification calls for it.
+- **Tests verify both directions** — new functionality works AND existing behaviour isn't broken
+- **Existing infrastructure is available** — don't rebuild what exists. Use established models, services, and utilities.
+
+---
+
+## Codebase Awareness
+
+Before designing phases, understand what exists. You cannot plan feature work without knowing how the feature integrates with the codebase:
+
+- **Analyze the relevant areas** — read the code the feature touches. Understand existing patterns, conventions, and structure in those areas.
+- **Identify integration points** — where does this feature connect to existing code? What modules, services, or APIs will it use or extend?
+- **Follow established patterns** — if similar features exist, note how they're structured. New phases should follow the same approach unless the specification explicitly calls for something different.
+- **Understand before designing** — phase boundaries should respect existing architectural seams. Don't design phases that cut across established module boundaries without good reason.
+
+This is not a full codebase audit — focus on the specific areas relevant to the feature.
+
+---
+
+## Scope Discipline
+
+Implement what the specification defines. Don't refactor surrounding code, even if it could be "improved". If the existing code works and the specification doesn't call for changing it, leave it alone.

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.