@leeovery/claude-technical-workflows 2.0.0

package/skills/technical-planning/references/output-linear.md

@@ -0,0 +1,211 @@
+# Output: Linear
+
+*Output adapter for **[technical-planning](../SKILL.md)***
+
+---
+
+Use this output format when you want **Linear as the source of truth** for plan management. The user can update tasks directly in Linear's UI, and implementation will query Linear for the current state.
+
+## Setup
+
+Requires the Linear MCP server to be configured in Claude Code.
+
+Check if Linear MCP is available by looking for Linear tools. If not configured, inform the user that Linear MCP is required for this format.
+
+Ask the user: **Which team should own this project?**
+
+## Linear Structure Mapping
+
+| Planning Concept | Linear Entity |
+|------------------|---------------|
+| Plan | Project |
+| Phase | Label (e.g., `phase-1`, `phase-2`) |
+| Task | Issue |
+
+## Output Process
+
+### 1. Create Linear Project
+
+Via MCP, create a project with:
+
+- **Name**: Match the specification topic name
+- **Description**: Brief summary + link to specification file
+- **Team**: As specified by user
+
+### 2. Create Labels for Phases
+
+Create labels to denote phases (if they don't already exist):
+
+- `phase-1`
+- `phase-2`
+- etc.
+
+Document the phase goals and acceptance criteria in a pinned issue or the project description:
+
+```
+Phase 1: Core Authentication
+Goal: Implement basic login/logout flow
+Acceptance:
+- [ ] User can log in with email/password
+- [ ] Session persists across page refresh
+- [ ] Logout clears session
+
+Phase 2: ...
+```
+
+### 3. Create Issues for Tasks
+
+For each task, create an issue and apply the appropriate phase label:
+
+**Title**: Clear action statement
+
+**Description** (use this structure):
+```markdown
+## Goal
+[What this task accomplishes - one sentence]
+
+## Implementation
+[The "Do" from planning - specific files, methods, approach]
+
+## Tests (Micro Acceptance)
+- `it does expected behavior`
+- `it handles edge case X`
+
+## Edge Cases
+- [Specific edge cases for this task]
+
+## Context
+Specification: `docs/workflow/specification/{topic}.md`
+[Optional: link to specific decision if relevant]
+```
+
+**Labels**:
+- **Required**: `phase-1`, `phase-2`, etc. - denotes which phase the task belongs to
+- **Optional**:
+  - `needs-info` - task requires additional information before implementation
+  - `edge-case` - for edge case handling tasks
+  - `foundation` - for setup/infrastructure tasks
+  - `refactor` - for cleanup tasks
+
+### Using `needs-info` Label
+
+When creating issues, if something is unclear or missing from the specification:
+
+1. **Create the issue anyway** - don't block planning
+2. **Apply `needs-info` label** - makes gaps visible
+3. **Note what's missing** in description - be specific about what needs clarifying
+4. **Continue planning** - don't stop and circle back
+
+This allows iterative refinement. Create all issues, identify gaps, circle back to specification if needed, then update issues with missing detail. Plans don't have to be perfect on first pass.
+
+### 4. Create Local Plan File
+
+Create `docs/workflow/planning/{topic}.md`:
+
+```markdown
+---
+format: linear
+project: {PROJECT_NAME}
+project_id: {ID from MCP response}
+team: {TEAM_NAME}
+---
+
+# Plan Reference: {Topic Name}
+
+**Specification**: `docs/workflow/specification/{topic}.md`
+**Created**: {DATE}
+
+## About This Plan
+
+This plan is managed in Linear. The source of truth for tasks and progress is the Linear project referenced above.
+
+## How to Use
+
+**To view/edit the plan**: Open Linear and navigate to the project.
+
+**Implementation will**:
+1. Read this file to find the Linear project
+2. Query Linear for project issues
+3. Work through tasks in phase order (by label)
+4. Update issue status as tasks complete
+
+**To add tasks**: Create issues in the Linear project. They'll be picked up automatically.
+
+## Key Decisions
+
+[Summary of key decisions from specification - for quick reference]
+```
+
+## Frontmatter
+
+The frontmatter contains all information needed to query Linear:
+
+```yaml
+---
+format: linear
+project: USER-AUTH-FEATURE
+project_id: abc123-def456
+team: Engineering
+---
+```
+
+## Issue Content Guidelines
+
+Issues should be **fully self-contained**. Include all context directly so humans and agents can execute without referencing other files.
+
+**Include in each issue**:
+- Goal and rationale (the "why" from the specification)
+- What to implement (specific files/methods)
+- Test names (micro acceptance)
+- Edge cases for this specific task
+- Relevant decisions and constraints
+- Any code examples for complex patterns
+
+**Specification reference**: The specification at `docs/workflow/specification/{topic}.md` remains available for resolving ambiguity or getting additional context, but issues should contain all information needed for execution.
+
+The goal: anyone (Claude or human) could pick up the issue and execute it without opening another document.
+
+## Benefits
+
+- Visual tracking with real-time progress updates
+- Team collaboration with shared visibility
+- Update tasks directly in Linear UI without editing markdown
+- Integrates with existing Linear workflows
+
+## Resulting Structure
+
+After planning:
+
+```
+docs/workflow/
+├── discussion/{topic}.md      # Phase 2 output
+├── specification/{topic}.md   # Phase 3 output
+└── planning/{topic}.md        # Phase 4 output (format: linear - pointer)
+
+Linear:
+└── Project: {topic}
+    ├── Issue: Task 1 [label: phase-1]
+    ├── Issue: Task 2 [label: phase-1]
+    └── Issue: Task 3 [label: phase-2]
+```
+
+## Implementation
+
+### Reading Plans
+
+1. Extract `project_id` from frontmatter
+2. Query Linear MCP for project issues
+3. Filter issues by phase label (e.g., `phase-1`, `phase-2`)
+4. Process in phase order
+
+### Updating Progress
+
+- Update issue status in Linear via MCP after each task
+- User sees real-time progress in Linear UI
+
+### Fallback
+
+If Linear MCP is unavailable:
+- Inform the user
+- Cannot proceed without MCP access
+- Suggest checking MCP configuration or switching to local markdown

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

@@ -0,0 +1,185 @@
+# Output: Local Markdown
+
+*Output adapter for **[technical-planning](../SKILL.md)***
+
+---
+
+Use this format for simple features or when you want everything in a single version-controlled file.
+
+## Benefits
+
+- No external tools or dependencies required
+- Everything in a single version-controlled file
+- Human-readable and easy to edit
+- Works offline with any text editor
+- Simplest setup - just create a markdown file
+
+## Setup
+
+No external tools required. This format uses plain markdown files stored in the repository.
+
+## Output Location
+
+```
+docs/workflow/planning/
+└── {topic}.md
+```
+
+This is a single file per topic in the planning directory.
+
+## Template
+
+Create `{topic}.md` with this structure:
+
+```markdown
+---
+format: local-markdown
+---
+
+# Implementation Plan: {Feature/Project Name}
+
+**Date**: YYYY-MM-DD
+**Status**: Draft | Ready | In Progress | Completed
+**Specification**: `docs/workflow/specification/{topic}.md`
+
+## Overview
+
+**Goal**: What we're building and why (one sentence)
+
+**Done when**:
+- Measurable outcome 1
+- Measurable outcome 2
+
+**Key Decisions** (from specification):
+- Decision 1: Rationale
+- Decision 2: Rationale
+
+## Architecture
+
+- Components
+- Data flow
+- Integration points
+
+## Phases
+
+Each phase is independently testable with clear acceptance criteria.
+Each task is a single TDD cycle: write test → implement → commit.
+
+---
+
+### Phase 1: {Name}
+
+**Goal**: What this phase accomplishes
+
+**Acceptance**:
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+**Tasks**:
+
+1. **{Task Name}**
+   - **Do**: What to implement
+   - **Test**: `"it does expected behavior"`
+   - **Edge cases**: (if any)
+
+2. **{Task Name}**
+   - **Do**: What to implement
+   - **Test**: `"it does expected behavior"`
+
+---
+
+### Phase 2: {Name}
+
+**Goal**: What this phase accomplishes
+
+**Acceptance**:
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+**Tasks**:
+
+1. **{Task Name}**
+   - **Do**: What to implement
+   - **Test**: `"it does expected behavior"`
+
+(Continue pattern for remaining phases)
+
+---
+
+## Edge Cases
+
+Map edge cases from specification to specific tasks:
+
+| Edge Case | Solution | Phase.Task | Test |
+|-----------|----------|------------|------|
+| {From specification} | How handled | 1.2 | `"it handles X"` |
+
+## Testing Strategy
+
+**Unit**: What to test per component
+**Integration**: What flows to verify
+**Manual**: (if needed)
+
+## Data Models (if applicable)
+
+Tables, schemas, API contracts
+
+## Dependencies
+
+- Prerequisites for Phase 1
+- Phase dependencies
+- External blockers
+
+## Rollback (if applicable)
+
+Triggers and steps
+
+## Log
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | Created from specification |
+```
+
+## Frontmatter
+
+The `format: local-markdown` frontmatter tells implementation that the full plan content is in this file.
+
+## Flagging Incomplete Tasks
+
+When information is missing, mark 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?
+```
+
+## Resulting Structure
+
+After planning:
+
+```
+docs/workflow/
+├── discussion/{topic}.md      # Phase 2 output
+├── specification/{topic}.md   # Phase 3 output
+└── planning/{topic}.md        # Phase 4 output (format: local-markdown)
+```
+
+## Implementation
+
+### Reading Plans
+
+1. Read the plan file - all content is inline
+2. Phases and tasks are in the document
+3. Follow phase order as written
+
+### Updating Progress
+
+- Check off acceptance criteria in the plan file
+- Update phase status as phases complete

package/skills/technical-research/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: technical-research
+description: "Explore ideas, validate concepts, and research broadly across technical, business, and market domains. Preliminary phase before discussion-specification-plan-implement-review workflow. Use when: (1) User has a new idea to explore, (2) Need to research a topic deeply, (3) Validating feasibility - technical, business, or market, (4) Learning and exploration without necessarily building anything, (5) User says 'research this' or 'explore this idea', (6) Brain dumping early thoughts before formal discussion. Creates research documents in docs/workflow/research/ that may seed the technical-discussion phase."
+---
+
+# Technical Research
+
+Act as **research partner** with broad expertise spanning technical, product, business, and market domains. Your role is learning, exploration, and discovery.
+
+## Six-Phase Workflow
+
+1. **Research** (YOU): EXPLORE - ideas, feasibility, market, business, learning
+2. **Discussion** (next): WHAT and WHY - decisions, architecture, edge cases
+3. **Specification** (after): REFINE - validate and build standalone spec
+4. **Planning** (after): HOW - phases, tasks, acceptance criteria
+5. **Implementation** (after): DOING - tests first, then code
+6. **Review** (final): VALIDATING - check work against artifacts
+
+You're at step 1. Explore freely.
+
+## Your Expertise
+
+You bring knowledge across the full landscape:
+
+- **Technical**: Feasibility, architecture approaches, time to market, complexity
+- **Business**: Pricing models, profitability, business models, unit economics
+- **Market**: Competitors, market fit, timing, gaps, positioning
+- **Product**: User needs, value proposition, differentiation
+
+Don't constrain yourself. Research goes wherever it needs to go.
+
+## Exploration Mindset
+
+**Follow tangents**: If something interesting comes up, pursue it.
+
+**Go broad**: Technical feasibility, pricing, competitors, timing, market fit - explore whatever's relevant.
+
+**Learning is valid**: Not everything leads to building something. Understanding has value on its own.
+
+**Be honest**: If something seems flawed or risky, say so. Challenge assumptions.
+
+## Questioning
+
+Use `/interview` for structured questioning. Good research questions:
+
+- Reveal hidden complexity
+- Surface concerns early
+- Challenge comfortable assumptions
+- Probe the "why" behind ideas
+
+Ask one question at a time. Wait for the answer. Document. Then ask the next.
+
+## File Strategy
+
+**Output**: `docs/workflow/research/exploration.md`
+
+Start with one file. Early research is messy - topics aren't clear, you're following tangents, circling back. Don't force structure too early.
+
+**Let themes emerge**: Over multiple sessions, topics may become distinct. When they do, split into semantic files (`market-landscape.md`, `technical-feasibility.md`).
+
+**Periodic review**: Every few sessions, assess: are themes emerging? Split them out. Still fuzzy? Keep exploring. Ready for deeper discussion? Move to `docs/workflow/discussion/`.
+
+## Documentation Loop
+
+Research without documentation is wasted. Follow this loop:
+
+1. **Ask** a question
+2. **Discuss** the answer
+3. **Document** the insight
+4. **Commit and push** immediately
+5. **Repeat**
+
+**Don't batch**. Every insight gets pushed before the next question. Context can refresh at any time—unpushed work is lost.
+
+## Critical Rules
+
+**Don't hallucinate**: Only document what was actually discussed.
+
+**Don't expand**: Capture what was said, don't embellish.
+
+**Verify before refreshing**: If context is running low, commit and push everything first.

package/skills/technical-review/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: technical-review
+description: "Validate completed implementation against plan tasks and acceptance criteria. Sixth phase of research-discussion-specification-plan-implement-review workflow. Use when: (1) Implementation phase is complete, (2) User wants validation before merging/shipping, (3) Quality gate check needed after implementation. Reviews ALL plan tasks for implementation correctness, test adequacy, and code quality. Produces structured feedback (approve, request changes, or comments) - does NOT fix code."
+---
+
+# Technical Review
+
+Act as a **senior software architect** with deep experience in code review. You haven't seen this code before. Your job is to verify that **every plan task** was implemented correctly, tested adequately, and meets professional quality standards.
+
+This is **product review**, **feature review**, **test review**, AND **code review**. Not just "does the code work?" but "was every task done correctly, tested properly, and built to professional standards?"
+
+## Six-Phase Workflow
+
+1. **Research** (artifact): EXPLORE - ideas, feasibility, market, business, learning
+2. **Discussion** (artifact): WHAT and WHY - decisions, architecture, rationale
+3. **Specification** (artifact): REFINE - validated, standalone specification
+4. **Planning** (artifact): HOW - phases, tasks, acceptance criteria
+5. **Implementation** (completed): DOING - tests and code
+6. **Review** (YOU): VALIDATING - verify every task
+
+You're at step 6. The code exists. Your job is comprehensive verification.
+
+## Review Approach
+
+Start from the **plan** - it contains the granular tasks and acceptance criteria. Use the **specification** for context. Verify **all** tasks, not a sample.
+
+```
+Plan (tasks + acceptance criteria)
+    ↓
+    For EACH task:
+        → Load Spec Context (deeper understanding)
+        → Verify Implementation (code exists, correct)
+        → Verify Tests (adequate, not over/under tested)
+        → Check Code Quality (readable, conventions)
+```
+
+**Use parallel `chain-verifier` subagents** to verify ALL plan tasks simultaneously. Each verifier checks one task for implementation, tests, and quality. This enables comprehensive review without sequential bottlenecks.
+
+## What You Verify (Per Task)
+
+### Implementation
+
+- Is the task implemented?
+- Does it match the acceptance criteria?
+- Does it align with spec context?
+- Any drift from what was planned?
+
+### Tests
+
+Evaluate test coverage critically - both directions:
+
+- **Not under-tested**: Does a test exist? Does it verify acceptance criteria? Are edge cases covered?
+- **Not over-tested**: Are tests focused and necessary? No redundant or bloated checks?
+- Would the test fail if the feature broke?
+
+### Code Quality
+
+Review as a senior architect would:
+
+**Project conventions** (check `.claude/skills/` for project-specific guidance):
+- Framework and architecture guidelines
+- Code style and patterns specific to the project
+
+**General principles** (always apply):
+- **SOLID**: Single responsibility, open/closed, Liskov substitution, interface segregation, dependency inversion
+- **DRY**: No unnecessary duplication (without premature abstraction)
+- **Low complexity**: Reasonable cyclomatic complexity, clear code paths
+- **Modern idioms**: Uses current language features appropriately
+- **Readability**: Self-documenting code, clear intent
+- **Security**: No obvious vulnerabilities
+- **Performance**: No obvious inefficiencies
+
+## Review Process
+
+1. **Read the plan** - Understand all phases, tasks, and acceptance criteria
+2. **Read the specification** - Load context for the feature being reviewed
+3. **Extract all tasks** - List every task from every phase
+4. **Spawn chain-verifiers in parallel** - One subagent per task, all running simultaneously
+5. **Aggregate findings** - Collect reports from all chain-verifiers
+6. **Check project skills** - Framework/language conventions
+7. **Produce review** - Structured feedback covering all tasks
+
+See **[review-checklist.md](references/review-checklist.md)** for detailed checklist.
+
+## Hard Rules
+
+1. **Review ALL tasks** - Don't sample; verify every planned task
+2. **Don't fix code** - Identify problems, don't solve them
+3. **Don't re-implement** - You're reviewing, not building
+4. **Be specific** - "Test doesn't cover X" not "tests need work"
+5. **Reference artifacts** - Link findings to plan/spec with file:line references
+6. **Balanced test review** - Flag both under-testing AND over-testing
+7. **Fresh perspective** - You haven't seen this code before; question everything
+
+## What Happens After Review
+
+Your review feedback can be:
+- Addressed by implementation (same or new session)
+- Delegated to an agent for fixes
+- Overridden by user ("ship it anyway")
+
+You produce feedback. User decides what to do with it.
+
+## References
+
+- **[template.md](references/template.md)** - Review output structure and verdict guidelines
+- **[review-checklist.md](references/review-checklist.md)** - Detailed review checklist