@leeovery/claude-technical-workflows 2.0.50 → 2.0.52

package/skills/technical-implementation/SKILL.md

@@ -23,7 +23,6 @@ Either way: Execute via strict TDD - tests first, implementation second.
 - **Plan format** (required) - How to parse tasks (from plan frontmatter)
 - **Specification content** (optional) - For context when task rationale is unclear
 - **Environment setup** (optional) - First-time setup instructions
-- **Scope** (optional) - Specific phase/task to work on
 
 **Before proceeding**, verify all required inputs are available and unambiguous. If anything is missing or unclear, **STOP** — do not proceed until resolved.
 
@@ -38,6 +37,21 @@ Either way: Execute via strict TDD - tests first, implementation second.
 
 If no specification is available, the plan becomes the sole authority for design decisions.
 
+---
+
+## Resuming After Context Refresh
+
+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.
+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.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## Hard Rules
 
 **MANDATORY. No exceptions. Violating these rules invalidates the work.**
@@ -77,19 +91,90 @@ Complete ALL setup steps before proceeding to implementation work.
 
 3. **Read the TDD workflow** - Load **[tdd-workflow.md](references/tdd-workflow.md)** before writing any code. This is mandatory.
 
-4. **Validate scope** (if specific phase or task was requested)
-   - If the requested phase or task doesn't exist in the plan, STOP immediately
-   - Ask the user for clarification - don't assume or proceed with a different scope
-   - Wait for the user to either correct the scope or ask you to stop
+4. **Initialize or resume implementation tracking**
+   - Check if `docs/workflow/implementation/{topic}.md` exists
+   - **If not**: Create it with the initial tracking frontmatter (see [Implementation Tracking](#implementation-tracking) below), set `status: in-progress`, `started: {today}`. Commit: `impl({topic}): start implementation`
+   - **If exists**: Read it to determine current position (see [Resuming After Context Refresh](#resuming-after-context-refresh) below)
 
-5. **For each phase**:
+5. **For each phase** (working through phases and tasks in plan order):
    - Announce phase start and review acceptance criteria
    - For each task: follow the TDD cycle loaded in step 3
+   - After each task completes: update progress in **both** the output format (as loaded in step 2) **and** the implementation tracking file (see below)
    - Verify all phase acceptance criteria met
    - **Ask user before proceeding to next phase**
 
 6. **Reference specification** when rationale unclear
 
+## Implementation Tracking
+
+Each topic has a tracking file at `docs/workflow/implementation/{topic}.md` that records progress programmatically (frontmatter) and as a human-readable summary (body).
+
+### Initial Tracking File
+
+When starting implementation for a topic, create:
+
+```yaml
+---
+topic: {topic}
+plan: ../planning/{topic}.md
+format: {format from plan}
+status: in-progress
+current_phase: 1
+current_task: ~
+completed_phases: []
+completed_tasks: []
+started: YYYY-MM-DD
+updated: YYYY-MM-DD
+completed: ~
+---
+
+# Implementation: {Topic Name}
+
+Implementation started.
+```
+
+### Updating Progress
+
+When a task or phase completes, update **two** things:
+
+1. **Output format progress** — Follow the output adapter's Implementation section (loaded in workflow step 2) to mark tasks/phases complete in the plan index file and any format-specific files. This is the plan's own progress tracking.
+
+2. **Implementation tracking file** — Update `docs/workflow/implementation/{topic}.md` as described below. This enables cross-topic dependency resolution and resume detection.
+
+**After each task completes (tracking file):**
+- Append the task ID to `completed_tasks`
+- Update `current_task` to the next task (or `~` if phase done)
+- Update `updated` date
+- Update the body progress section
+
+**After each phase completes (tracking file):**
+- Append the phase number to `completed_phases`
+- Update `current_phase` to the next phase (or leave as last)
+- Update the body progress section
+
+**On implementation completion (tracking file):**
+- Set `status: completed`
+- Set `completed: {today}`
+- Commit: `impl({topic}): complete implementation`
+
+Task IDs in `completed_tasks` use whatever ID format the output format assigns -- the same IDs used in dependency references.
+
+### Body Progress Section
+
+The body provides a human-readable summary for context refresh:
+
+```markdown
+# Implementation: {Topic Name}
+
+## Phase 1: Foundation
+All tasks completed.
+
+## Phase 2: Core Logic (current)
+- Task 2.1: Service layer - done
+- Task 2.2: Validation - done
+- Task 2.3: Controllers (next)
+```
+
 ## Progress Announcements
 
 Keep user informed of progress:

package/skills/technical-planning/SKILL.md

@@ -22,6 +22,7 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 - **Specification content** (required) - The validated decisions and requirements to plan from
 - **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
 - **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,6 +35,19 @@ Either way: Transform specifications into actionable phases, tasks, and acceptan
 
 ---
 
+## Resuming After Context Refresh
+
+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.
+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.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## The Process
 
 This process constructs a plan from a specification. A plan consists of:
@@ -97,7 +111,21 @@ Read **[output-formats.md](references/output-formats.md)**, find the entry match
 
 #### If no Plan Index File exists
 
-First, choose the Output Format. Present the formats from **[output-formats.md](references/output-formats.md)** to the user — including description, pros, cons, and "best for". Number each format and ask the user to pick.
+First, choose the Output Format.
+
+**If a recommended output format was provided** (non-empty, not "none"):
+
+Present the recommendation:
+
+> "Existing plans use **{format}**. Use the same format for consistency?
+> - **yes** — use {format}
+> - **no** — see all available formats"
+
+**STOP.** Wait for user choice. If declined, fall through to the full list below.
+
+**If no recommendation, or user declined:**
+
+Present the formats from **[output-formats.md](references/output-formats.md)** to the user — including description, pros, cons, and "best for". Number each format and ask the user to pick.
 
 **STOP.** Wait for the user to choose.
 
@@ -118,6 +146,7 @@ cross_cutting_specs:              # Omit if none
 spec_commit: {output of git rev-parse HEAD}
 created: YYYY-MM-DD  # Use today's actual date
 updated: YYYY-MM-DD  # Use today's actual date
+external_dependencies: []
 planning:
   phase: 1
   task: ~

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

@@ -18,22 +18,26 @@ External dependencies are things a feature needs from other topics or systems th
 
 ## Format
 
-In Plan Index Files, external dependencies appear in a dedicated section:
-
-```markdown
-## External Dependencies
-
-- billing-system: Invoice generation for order completion
-- user-authentication: User context for permissions → {task-id} (resolved)
-- ~~payment-gateway: Payment processing~~ → satisfied externally
+In Plan Index Files, external dependencies are stored in the **frontmatter** as a YAML array:
+
+```yaml
+external_dependencies:
+  - topic: billing-system
+    description: Invoice generation for order completion
+    state: unresolved
+  - topic: user-authentication
+    description: User context for permissions
+    state: resolved
+    task_id: auth-1-3
+  - topic: payment-gateway
+    description: Payment processing
+    state: satisfied_externally
 ```
 
-If there are no external dependencies, still include the section:
-
-```markdown
-## External Dependencies
+If there are no external dependencies, use an empty array:
 
-No external dependencies.
+```yaml
+external_dependencies: []
 ```
 
 This makes it explicit for downstream stages that dependencies were considered and none exist.
@@ -42,16 +46,16 @@ This makes it explicit for downstream stages that dependencies were considered a
 
 | State | Format | Meaning |
 |-------|--------|---------|
-| Unresolved | `- {topic}: {description}` | Dependency exists but not yet linked to a task |
-| Resolved | `- {topic}: {description} → {task-id}` | Linked to specific task in another plan |
-| Satisfied externally | `- ~~{topic}: {description}~~ → satisfied externally` | Implemented outside workflow |
+| `unresolved` | `state: unresolved` | Dependency exists but not yet linked to a task |
+| `resolved` | `state: resolved` + `task_id: {id}` | Linked to specific task in another plan |
+| `satisfied_externally` | `state: satisfied_externally` | Implemented outside workflow |
 
 ## Lifecycle
 
 ```
 SPECIFICATION                    PLANNING
 ───────────────────────────────────────────────────────────────────
-Dependencies section    →    Copied to Plan Index File as unresolved
+Dependencies section    →    Added to plan frontmatter as unresolved
 (natural language)                      ↓
                              Resolved when linked to specific task ID
                              (via planning or /link-dependencies)
@@ -59,11 +63,11 @@ Dependencies section    →    Copied to Plan Index File as unresolved
 
 ## Resolution
 
-Dependencies move from unresolved → resolved when:
+Dependencies move from `unresolved` → `resolved` when:
 - The dependency topic is planned and you identify the specific task
 - The `/link-dependencies` command finds and wires the match
 
-Dependencies become "satisfied externally" when:
+Dependencies become `satisfied_externally` when:
 - The user confirms it was implemented outside the workflow
 - It already exists in the codebase
 - It's a third-party system that's already available

package/skills/technical-planning/references/steps/resolve-dependencies.md

@@ -10,29 +10,29 @@ Orient the user:
 
 After all phases are detailed and written, handle external dependencies — things this plan needs from other topics or systems.
 
+Dependencies are stored in the plan's **frontmatter** as `external_dependencies`. See [dependencies.md](../dependencies.md) for the format and states.
+
 #### If the specification has a Dependencies section
 
 The specification's Dependencies section lists what this feature needs from outside its own scope. These must be documented in the plan so implementation knows what is blocked and what is available.
 
-1. **Document each dependency** in the plan's External Dependencies section using the format described in [dependencies.md](../dependencies.md). Initially, record each as unresolved.
+1. **Document each dependency** in the plan's `external_dependencies` frontmatter field using the format described in [dependencies.md](../dependencies.md). Initially, record each as `state: unresolved`.
 
 2. **Resolve where possible** — For each dependency, check whether a plan already exists for that topic:
-   - If a plan exists, identify the specific task(s) that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply. Update the dependency entry from unresolved → resolved with the task reference.
-   - If no plan exists, leave the dependency as unresolved. It will be linked later via `/link-dependencies` or when that topic is planned.
+   - If a plan exists, identify the specific task(s) that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply. Update the dependency entry from `state: unresolved` → `state: resolved` with the `task_id`.
+   - If no plan exists, leave the dependency as `state: unresolved`. It will be linked later via `/link-dependencies` or when that topic is planned.
 
-3. **Reverse check** — Check whether any existing plans have unresolved dependencies that reference *this* topic. Now that this plan exists with specific tasks:
-   - Scan other plan files for External Dependencies entries that mention this topic
+3. **Reverse check** — Check whether any existing plans have unresolved dependencies in their `external_dependencies` frontmatter that reference *this* topic. Now that this plan exists with specific tasks:
+   - Scan other plan files' `external_dependencies` for entries that mention this topic
    - For each match, identify which task(s) in the current plan satisfy that dependency
-   - Update the other plan's dependency entry with the task reference (unresolved → resolved)
+   - Update the other plan's `external_dependencies` entry with the task reference (`state: resolved`, `task_id`)
 
 #### If the specification has no Dependencies section
 
-Document this explicitly in the plan:
-
-```markdown
-## External Dependencies
+Set the frontmatter field to an empty array:
 
-No external dependencies.
+```yaml
+external_dependencies: []
 ```
 
 This makes it clear that dependencies were considered and none exist — not that they were overlooked.

package/skills/technical-research/SKILL.md

@@ -28,6 +28,21 @@ Either way: Explore feasibility (technical, business, market), validate assumpti
 - **Topic is vague or could go many directions?**
   > "You mentioned {topic}. That could cover a lot of ground — is there a specific angle you'd like to start with, or should I explore broadly?"
 
+---
+
+## Resuming After Context Refresh
+
+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.
+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.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## Your Expertise
 
 You bring knowledge across the full landscape:

package/skills/technical-review/SKILL.md

@@ -41,6 +41,21 @@ Either way: Verify every plan task was implemented, tested adequately, and meets
 
 The specification is optional — the review can proceed with just the plan.
 
+---
+
+## Resuming After Context Refresh
+
+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.
+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.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## Review Approach
 
 Start from the **plan** - it contains the granular tasks and acceptance criteria.

package/skills/technical-specification/SKILL.md

@@ -39,6 +39,21 @@ Either way: Transform unvalidated reference material into a specification that's
 
 **Multiple sources:** When multiple sources are provided, extract exhaustively from ALL of them. Content may be scattered across sources - a decision in one may have constraints or details in another. The specification consolidates everything into a single standalone document.
 
+---
+
+## Resuming After Context Refresh
+
+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.
+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.
+
+Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.
+
+---
+
 ## The Process
 
 **Load**: [specification-guide.md](references/specification-guide.md)

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

@@ -295,12 +295,6 @@ Ask: **"Is there a standalone thing to build, or does this inform how we build o
 
 **Trust nothing without validation**: Synthesize and present, but never assume source material is correct.
 
-## After Context Refresh
-
-Read the specification. It contains validated, approved content. Trust it - you built it together with the user.
-
-If working notes exist, they show where you left off.
-
 ## Dependencies Section
 
 At the end of every specification, add a **Dependencies** section that identifies **prerequisites** - systems that must exist before this feature can be built.