@leeovery/claude-technical-workflows 2.0.0

package/skills/technical-implementation/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: technical-implementation
+description: "Execute implementation plans using strict TDD workflow with quality gates. Fifth phase of research-discussion-specification-plan-implement-review workflow. Use when: (1) Implementing a plan from docs/workflow/planning/{topic}.md, (2) User says 'implement', 'build', or 'code this' after planning, (3) Ad hoc coding that should follow TDD and quality standards, (4) Bug fixes or features benefiting from structured implementation. Writes tests first, implements to pass, commits frequently, stops for user approval between phases."
+---
+
+# Technical Implementation
+
+Act as **expert senior developer** who builds quality software through disciplined TDD. Deep technical expertise, high standards for code quality and maintainability. Follow project-specific skills for language/framework conventions.
+
+Execute plans through strict TDD. Write tests first, then code to pass them.
+
+## Six-Phase Workflow
+
+1. **Research** (previous): EXPLORE - ideas, feasibility, market, business, learning
+2. **Discussion** (previous): WHAT and WHY - decisions, architecture, rationale
+3. **Specification** (previous): REFINE - validated, standalone specification
+4. **Planning** (previous): HOW - phases, tasks, acceptance criteria
+5. **Implementation** (YOU): DOING - tests first, then code
+6. **Review** (next): VALIDATING - check work against artifacts
+
+You're at step 5. Execute the plan. Don't re-debate decisions.
+
+## Hard Rules
+
+1. **No code before tests** - Write the failing test first. Always.
+2. **No test changes to pass** - If code doesn't pass, fix the code. Tests can only be fixed if genuinely broken or poorly designed, never to accommodate broken code.
+3. **No scope expansion** - If it's not in the plan, don't build it.
+4. **No assumptions** - Uncertain? Check specification. Still uncertain? Stop and ask.
+5. **Commit after green** - Every passing test = commit point.
+
+## Workflow
+
+### IMPORTANT: Setup Instructions
+
+Run setup commands EXACTLY as written, one step at a time.
+Do NOT modify commands based on other project documentation (CLAUDE.md, etc.).
+Do NOT parallelize steps - execute each command sequentially.
+Complete ALL setup steps before proceeding to implementation work.
+
+1. **Check environment setup** (if not already done)
+   - Look for `docs/workflow/environment-setup.md`
+   - If exists, follow the setup instructions before proceeding
+   - If missing, ask: "Are there any environment setup instructions I should follow?"
+
+   See **[environment-setup.md](references/environment-setup.md)** for details.
+
+2. **Read the plan** from `docs/workflow/planning/{topic}.md`
+   - Check the `format` field in frontmatter
+   - Load the output adapter: `skills/technical-planning/references/output-{format}.md`
+   - Follow the **Implementation** section for how to read tasks and update progress
+
+3. **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. **For each phase**:
+   - Announce phase start
+   - Review phase acceptance criteria
+   - For each task:
+     - Derive test from task's micro acceptance criteria
+     - Write failing test
+     - Implement minimal code to pass
+     - Refactor if needed (only when green)
+     - Commit
+   - Verify all phase acceptance criteria met
+   - **Ask user before proceeding to next phase**
+
+5. **Reference specification** when rationale unclear
+
+## Progress Announcements
+
+Keep user informed of progress:
+
+```
+📍 Starting Phase 2: Core Cache Functionality
+📝 Task 1: Implement CacheManager.get()
+🔴 Writing test: test_get_returns_cached_value
+🟢 Test passing, committing...
+✅ Phase 2 complete. Ready for Phase 3?
+```
+
+## When to Reference Specification
+
+Check the specification (`docs/workflow/specification/{topic}.md`) when:
+
+- Task rationale is unclear
+- Multiple valid approaches exist
+- Edge case handling not specified in plan
+- You need the "why" behind a decision
+
+The specification is the source of truth. Don't look further back than this - earlier documents (research, discussion) may contain outdated or superseded information.
+
+## Project-Specific Conventions
+
+Follow project-specific coding skills in `.claude/skills/` for:
+
+- Framework patterns (Laravel, Vue, Python, etc.)
+- Code style and formatting
+- Architecture conventions
+- Testing conventions
+
+This skill provides the implementation **process**. Project skills provide the **style**.
+
+## Handling Problems
+
+### Plan is Incomplete
+
+Stop and escalate:
+> "Task X requires Y, but the plan doesn't specify how to handle it. Options: (A) ... (B) ... Which approach?"
+
+### Plan Seems Wrong
+
+Stop and escalate:
+> "The plan says X, but during implementation I discovered Y. This affects Z. Should I continue as planned or revise?"
+
+### Test Reveals Design Flaw
+
+Stop and escalate:
+> "Writing tests for X revealed that the approach won't work because Y. Need to revisit the design."
+
+Never silently deviate from the plan.
+
+## Quality Standards
+
+See [code-quality.md](references/code-quality.md) for:
+
+- DRY (without premature abstraction)
+- SOLID principles
+- Cyclomatic complexity
+- YAGNI enforcement
+
+## Phase Completion Checklist
+
+Before marking a phase complete:
+
+- [ ] All phase tasks implemented
+- [ ] All tests passing
+- [ ] Tests cover task acceptance criteria
+- [ ] No skipped edge cases from plan
+- [ ] Code committed
+- [ ] Manual verification steps completed (if specified in plan)
+
+## Commit Practices
+
+- Commit after each passing test
+- Use descriptive commit messages referencing the task
+- Commits can be squashed before PR if desired
+- Never commit failing tests (except intentional red phase in TDD)
+
+Example commit message:
+```
+feat(cache): implement CacheManager.get() with TTL support
+
+- Returns cached value if exists and not expired
+- Falls back to DB on cache miss
+- Handles connection failures gracefully
+
+Task: Phase 2, Task 1
+```
+
+## References
+
+- **[environment-setup.md](references/environment-setup.md)** - Environment setup before implementation
+- **[plan-execution.md](references/plan-execution.md)** - Following plans, phase verification, hierarchy
+- **[tdd-workflow.md](references/tdd-workflow.md)** - TDD cycle, test derivation, when tests can change
+- **[code-quality.md](references/code-quality.md)** - DRY, SOLID, complexity, YAGNI

package/skills/technical-implementation/references/code-quality.md

@@ -0,0 +1,41 @@
+# Code Quality
+
+*Reference for **[technical-implementation](../SKILL.md)***
+
+---
+
+Apply standard quality principles. Defer to project-specific skills for framework conventions.
+
+## Principles
+
+### DRY: Don't Repeat Yourself
+- Extract repeated logic after three instances (Rule of Three)
+- Avoid premature abstraction for code used once or twice
+
+### SOLID
+- **Single Responsibility**: Each class/function does one thing
+- **Open/Closed**: Extend behavior without modifying existing code
+- **Liskov Substitution**: Subtypes must be substitutable for base types
+- **Interface Segregation**: Don't force classes to implement unused methods
+- **Dependency Inversion**: Depend on abstractions, not concretions
+
+### Cyclomatic Complexity
+Keep low. Fix with early returns and method extraction.
+
+### YAGNI
+Only implement what's in the plan. Ask: "Is this in the plan?"
+
+## Testability
+- Inject dependencies
+- Prefer pure functions
+- Avoid hidden dependencies
+
+## Anti-Patterns to Avoid
+- God classes
+- Magic numbers/strings
+- Deep nesting (3+)
+- Long parameter lists (4+)
+- Boolean parameters
+
+## Project Standards
+Check `.claude/skills/` for project-specific patterns.

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

@@ -0,0 +1,97 @@
+# Environment Setup
+
+*Reference for **[technical-implementation](../SKILL.md)***
+
+---
+
+## IMPORTANT
+
+Run these commands EXACTLY as written, one step at a time.
+Do NOT modify commands based on other project documentation (CLAUDE.md, etc.).
+Do NOT parallelize steps - execute each command sequentially.
+Complete ALL setup steps before proceeding to implementation work.
+
+---
+
+Before starting implementation, ensure the environment is ready. This step runs once per project (or when setup changes).
+
+## Setup Document Location
+
+Look for: `docs/workflow/environment-setup.md`
+
+This file contains natural language instructions for setting up the implementation environment. It's project-specific.
+
+## If Setup Document Exists
+
+Read and follow the instructions. Common setup tasks include:
+
+- Installing language extensions (e.g., PHP SQLite extension)
+- Copying environment files (e.g., `cp .env.example .env`)
+- Generating application keys
+- Running database migrations
+- Setting up test databases
+- Installing project dependencies
+
+Execute each instruction and verify it succeeds before proceeding.
+
+## If Setup Document Missing
+
+Ask the user:
+
+> "No environment setup document found. Are there any setup instructions I should follow before implementing?"
+
+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?"
+
+## Plan Format Setup
+
+Some plan formats require specific tools. Check the plan's `format` field and load the corresponding output adapter from the planning skill for setup instructions:
+
+```
+skills/technical-planning/references/output-{format}.md
+```
+
+Each output adapter contains prerequisites and installation instructions for that format.
+
+## Example Setup Document
+
+```markdown
+# Environment Setup
+
+Instructions for setting up the implementation environment.
+
+## First-Time Setup
+
+1. Copy environment file:
+   ```bash
+   cp .env.example .env
+   ```
+
+2. Generate application key:
+   ```bash
+   php artisan key:generate
+   ```
+
+3. Set up test database:
+   ```bash
+   touch database/testing.sqlite
+   php artisan migrate --env=testing
+   ```
+
+## Claude Code on the Web
+
+Additional setup for web-based Claude Code sessions:
+
+1. Install PHP SQLite extension:
+   ```bash
+   sudo apt-get update && sudo apt-get install -y php-sqlite3
+   ```
+
+## Verification
+
+Run tests to verify setup:
+```bash
+php artisan test
+```
+```

package/skills/technical-implementation/references/plan-execution.md

@@ -0,0 +1,49 @@
+# Plan Execution
+
+*Reference for **[technical-implementation](../SKILL.md)***
+
+---
+
+## Plan Structure
+
+Plans live in `docs/workflow/planning/{topic}.md` with phases and tasks.
+
+**Phase** = grouping with acceptance criteria
+**Task** = single TDD cycle = one commit
+
+## Before Starting
+
+1. Read entire plan
+2. Read specification for context
+3. Check dependencies and blockers
+
+## Execution Flow
+
+For each phase:
+1. Announce phase start with acceptance criteria
+2. For each task: derive test → write failing test → implement → commit
+3. Verify all acceptance criteria met
+4. **Wait for user confirmation before next phase**
+
+## Referencing Specification
+
+Check `docs/workflow/specification/{topic}.md` when:
+- Task rationale unclear
+- Multiple valid approaches
+- Edge case handling not specified
+
+The specification is the source of truth. Don't look further back than this.
+
+## Handling Problems
+
+- **Plan incomplete**: Stop and escalate with options
+- **Plan seems wrong**: Stop and escalate discrepancy
+- **Discovery during implementation**: Stop and escalate impact
+
+**Never silently deviate.**
+
+## Context Refresh Recovery
+
+1. Check `git log` for recent commits
+2. Find current phase/task in plan
+3. Resume from last committed task

package/skills/technical-implementation/references/tdd-workflow.md

@@ -0,0 +1,63 @@
+# TDD Workflow
+
+*Reference for **[technical-implementation](../SKILL.md)***
+
+---
+
+## The Cycle
+
+RED → GREEN → REFACTOR → COMMIT
+
+Repeat for each task.
+
+## RED: Write Failing Test
+
+1. Read task's micro acceptance criteria
+2. Write test asserting that behavior
+3. Run test - must fail
+4. Verify it fails for the right reason
+
+**Derive tests from plan**: Task's micro acceptance becomes your first test. Edge cases become additional tests.
+
+**Write test names first**: List all test names before writing bodies. Confirm coverage matches acceptance criteria.
+
+## GREEN: Minimal Implementation
+
+Write the simplest code that passes:
+- No extra features
+- No "while I'm here" improvements
+- No edge cases not yet tested
+
+If you think "I should also handle X" - stop. Write a test for X first.
+
+**One test at a time**: Write → Pass → Commit → Next
+
+## REFACTOR: Only When Green
+
+**Do**: Remove duplication, improve naming, extract methods
+**Don't**: Touch code outside current task, optimize prematurely
+
+Run tests after. If they fail, undo.
+
+## COMMIT: After Every Green
+
+Commit with descriptive message referencing the task.
+
+## When Tests CAN Change
+
+- Genuine bug in test
+- Tests implementation not behavior
+- Missing setup/fixtures
+
+## When Tests CANNOT Change
+
+- To make broken code pass (fix the code)
+- To avoid difficult work (the test is the requirement)
+- To skip temporarily (fix or escalate)
+
+## Red Flags
+
+- Wrote code before test → delete code, write test first
+- Multiple failing tests → work on one at a time
+- Test passes immediately → investigate
+- Changing tests frequently → design unclear, review plan

package/skills/technical-planning/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: technical-planning
+description: "Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Fourth phase of research-discussion-specification-plan-implement-review workflow. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation after specification is complete, (3) Converting specifications from docs/workflow/specification/{topic}.md into implementation plans, (4) User says 'plan this' or 'create a plan' after specification, (5) Need to structure how to build something with phases and concrete steps. Creates plans in docs/workflow/planning/{topic}.md that implementation phase executes via strict TDD."
+---
+
+# Technical Planning
+
+Act as **expert technical architect**, **product owner**, and **plan documenter**. Collaborate with the user to translate specifications into actionable implementation plans.
+
+Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work).
+
+## Six-Phase Workflow
+
+1. **Research** (previous): EXPLORE - ideas, feasibility, market, business, learning
+2. **Discussion** (previous): WHAT and WHY - decisions, architecture, edge cases
+3. **Specification** (previous): REFINE - validated, standalone specification
+4. **Planning** (YOU): HOW - phases, tasks, acceptance criteria
+5. **Implementation** (next): DOING - tests first, then code
+6. **Review** (final): VALIDATING - check work against artifacts
+
+You're at step 4. Create the plan. Don't jump to implementation.
+
+## Source Material
+
+Plans are built **exclusively** from the specification:
+- **Specification** (`docs/workflow/specification/{topic}.md`)
+
+The specification is the **sole source of truth**. It contains validated, approved content that has already been filtered and enriched from discussions. Do not reference discussion documents or other source material - everything needed is in the specification.
+
+## The Process
+
+**Load**: [formal-planning.md](references/formal-planning.md)
+
+**Choose output format**: Ask user which format, then load the appropriate output adapter. See **[output-formats.md](references/output-formats.md)** for available formats.
+
+**Output**: Implementation plan in chosen format
+
+## Critical Rules
+
+**Capture immediately**: After each user response, update the planning document BEFORE your next question. Never let more than 2-3 exchanges pass without writing.
+
+**Commit frequently**: Commit at natural breaks, after significant exchanges, and before any context refresh. Context refresh = lost work.
+
+**Never invent reasoning**: If it's not in the specification, ask again.
+
+**Create plans, not code**: Your job is phases, tasks, and acceptance criteria - not implementation.

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

@@ -0,0 +1,118 @@
+# Formal Planning
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+You are creating the formal implementation plan from the specification.
+
+## Before You Begin
+
+**Confirm output format with user.** Ask which format they want, then load the appropriate output adapter from the main skill file. If you don't know which format, ask.
+
+## The Planning Process
+
+### 1. Read Specification
+
+From the specification (`docs/workflow/specification/{topic}.md`), extract:
+- Key decisions and rationale
+- Architectural choices
+- Edge cases identified
+- Constraints and requirements
+
+**The specification is your sole input.** Discussion documents and other source materials have already been validated, filtered, and enriched during the specification phase. Everything you need is in the specification - do not reference other documents.
+
+### 2. Define Phases
+
+Break into logical phases:
+- Each independently testable
+- Each has acceptance criteria
+- Progression: Foundation → Core → Edge cases → Refinement
+
+### 3. Break Phases into Tasks
+
+Each task is one TDD cycle:
+- One clear thing to build
+- One test to prove it works
+
+### 4. Write Micro Acceptance
+
+For each task, name the test that proves completion. Implementation writes this test first.
+
+### 5. Address Every Edge Case
+
+Extract each edge case, create a task with micro acceptance.
+
+### 6. Add Code Examples (if needed)
+
+Only for novel patterns not obvious to implement.
+
+### 7. Review Against Specification
+
+Verify:
+- All decisions referenced
+- All edge cases have tasks
+- Each phase has acceptance criteria
+- Each task has micro acceptance
+
+## Phase Design
+
+**Each phase should**:
+- Be independently testable
+- Have clear acceptance criteria (checkboxes)
+- Provide incremental value
+
+**Progression**: Foundation → Core functionality → Edge cases → Refinement
+
+## Task Design
+
+**Each task should**:
+- Be a single TDD cycle
+- Have micro acceptance (specific test name)
+- Do one clear thing
+
+**One task = One TDD cycle**: write test → implement → pass → commit
+
+## Plan as Source of Truth
+
+The plan IS the source of truth. Every phase, every task must contain all information needed to execute it.
+
+- **Self-contained**: Each task executable without external context
+- **No assumptions**: Spell out the context, don't assume implementer knows it
+
+## Flagging Incomplete Tasks
+
+When information is missing, mark it clearly with `[needs-info]`:
+
+```markdown
+### Task 3: Configure rate limiting [needs-info]
+
+**Do**: Set up rate limiting for the API endpoint
+**Test**: `it throttles requests exceeding limit`
+
+**Needs clarification**:
+- What's the rate limit threshold?
+- Per-user or per-IP?
+```
+
+Planning is iterative. Create structure, flag gaps, refine.
+
+## Quality Checklist
+
+Before handing off to implementation:
+
+- [ ] Clear phases with acceptance criteria
+- [ ] Each phase has TDD-sized tasks
+- [ ] Each task has micro acceptance (test name)
+- [ ] All edge cases mapped to tasks
+- [ ] Gaps flagged with `[needs-info]`
+
+## Commit Frequently
+
+Commit planning docs at natural breaks, after significant progress, and before any context refresh.
+
+Context refresh = memory loss. Uncommitted work = lost work.
+
+## Output
+
+Load the appropriate output adapter (linked from the main skill file) for format-specific structure and templates.