@leeovery/claude-technical-workflows 2.1.40 → 2.1.42

package/skills/technical-implementation/references/analysis-loop.md

@@ -121,18 +121,26 @@ impl({topic}): analysis cycle {N} — synthesis
 
 ## E. Approval Gate
 
-Read the staging file from `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md`.
+Read the staging file from `.workflows/implementation/{topic}/analysis-tasks-c{cycle-number}.md`.
+
+Check `analysis_gate_mode` in the implementation tracking file (`gated` or `auto`).
 
 Present an overview:
 
-**Analysis cycle {N}: {K} proposed tasks**
+> *Output the next fenced block as a code block:*
+
+```
+Analysis cycle {N}: {K} proposed tasks
 
-1. {title} ({severity})
-2. {title} ({severity})
-...
+  1. {title} ({severity})
+  2. {title} ({severity})
+```
 
 Then present each task with `status: pending` individually:
 
+> *Output the next fenced block as markdown (not a code block):*
+
+```
 **Task {current}/{total}: {title}** ({severity})
 Sources: {sources}
 
@@ -148,12 +156,18 @@ Sources: {sources}
 
 **Tests**:
 {tests}
+```
+
+#### If `analysis_gate_mode: gated`
 
 > *Output the next fenced block as markdown (not a code block):*
 
 ```
 · · · · · · · · · · · ·
-- **`a`/`approve`** — Approve this task
+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
 · · · · · · · · · · · ·
@@ -161,12 +175,34 @@ Sources: {sources}
 
 **STOP.** Wait for user input.
 
-#### If `approve`
+#### If `analysis_gate_mode: auto`
+
+Update `status: approved` in the staging file. Note that `analysis_gate_mode` should be updated to `auto` in the tracking file during the next commit.
+
+> *Output the next fenced block as a code block:*
+
+```
+Task {current} of {total}: {title} — approved (auto).
+```
+
+→ Continue to next task without stopping.
+
+---
+
+Process user input:
+
+#### If `yes`
 
 Update `status: approved` in the staging file.
 
 → Present the next pending task, or proceed to routing below if all tasks processed.
 
+#### If `auto`
+
+Update `status: approved` in the staging file. Note that `analysis_gate_mode` should be updated to `auto` in the tracking file during the next commit.
+
+→ Continue processing remaining tasks without stopping.
+
 #### If `skip`
 
 Update `status: skipped` in the staging file.
@@ -185,7 +221,7 @@ After all tasks processed:
 
 → If all tasks were skipped:
 
-Commit the staging file updates:
+Commit the staging file updates (include tracking file if `analysis_gate_mode` was updated):
 
 ```
 impl({topic}): analysis cycle {N} — tasks skipped
@@ -201,7 +237,7 @@ Load **[invoke-task-writer.md](invoke-task-writer.md)** and follow its instructi
 
 **STOP.** Do not proceed until the task writer has returned.
 
-Commit all analysis and plan changes (staging file, plan tasks, Plan Index File):
+Commit all analysis and plan changes (staging file, plan tasks, Plan Index File, and tracking file if `analysis_gate_mode` was updated):
 
 ```
 impl({topic}): add analysis phase {N} ({K} tasks)

package/skills/technical-implementation/references/environment-setup.md

@@ -17,7 +17,7 @@ Before starting implementation, ensure the environment is ready. This step runs
 
 ## Setup Document Location
 
-Look for: `docs/workflow/environment-setup.md`
+Look for: `.workflows/environment-setup.md`
 
 This file contains natural language instructions for setting up the implementation environment. It's project-specific.
 
@@ -42,9 +42,9 @@ Ask the user:
 
 If they provide instructions, offer to save them:
 
-> "Would you like me to save these instructions to `docs/workflow/environment-setup.md` for future sessions?"
+> "Would you like me to save these instructions to `.workflows/environment-setup.md` for future sessions?"
 
-If they say no setup is needed, create `docs/workflow/environment-setup.md` with "No special setup required." and commit. This prevents asking the same question in future sessions.
+If they say no setup is needed, create `.workflows/environment-setup.md` with "No special setup required." and commit. This prevents asking the same question in future sessions.
 
 ## No Setup Required
 

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

@@ -15,7 +15,7 @@ This step invokes the task writer agent to create plan tasks from approved analy
 Pass via the orchestrator's prompt:
 
 1. **Topic name** — the implementation topic
-2. **Staging file path** — `docs/workflow/implementation/{topic}/analysis-tasks-c{cycle-number}.md`
+2. **Staging file path** — `.workflows/implementation/{topic}/analysis-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-implementation/references/task-loop.md

@@ -178,7 +178,7 @@ Check the `task_gate_mode` field in the implementation tracking file.
 - If the format's updating.md includes a **Phase / Parent Status** section, follow its phase completion instructions
 - Append the phase number to `completed_phases` in the tracking file
 
-**Mirror to implementation tracking file** (`docs/workflow/implementation/{topic}/tracking.md`):
+**Mirror to implementation tracking file** (`.workflows/implementation/{topic}/tracking.md`):
 - Append the task ID to `completed_tasks`
 - Update `current_phase` if phase changed
 - Update `current_task` to the next task (or `~` if done)

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/output-formats/tick/authoring.md

@@ -103,22 +103,10 @@ tick create "[NEEDS INFO] Rate limiting strategy" \
 
 ## Cleanup (Restart)
 
-Cancel the topic task and all its descendants. First, list the tasks to collect their IDs:
+Remove the topic task and all its descendants:
 
 ```bash
-tick list --parent <topic-id>
+tick remove <topic-id> --force
 ```
 
-Then cancel each task (leaf tasks first, then phases, then the topic):
-
-```bash
-tick cancel <task-id>
-```
-
-Cancelled tasks remain in the JSONL history but are excluded from `tick ready` and active listings.
-
-**Full reset** (removes all tasks across all topics):
-
-```bash
-rm -rf .tick && tick init
-```
+Removing a parent cascades to all children (phases and tasks). Dependency references to removed tasks are auto-cleaned from surviving tasks.

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.