@leeovery/claude-technical-workflows 2.0.54 → 2.1.0

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

@@ -1,328 +0,0 @@
-# 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 |
-|------------------|---------------|
-| Specification/Topic | Project |
-| Phase | Label (e.g., `phase-1`, `phase-2`) |
-| Task | Issue |
-| Internal dependency | Issue blocking relationship (within project) |
-| Cross-topic dependency | Issue blocking relationship (across projects) |
-
-Each specification topic becomes its own Linear project. Cross-topic dependencies link issues between projects.
-
-## Cross-Project Dependencies
-
-Cross-topic dependencies link issues between different Linear projects (different specifications/topics). This is how you express "billing depends on authentication being complete."
-
-### Creating Cross-Project Dependencies
-
-Linear supports blocking relationships between issues, even across projects. Via MCP or the Linear UI:
-
-1. Open the dependent issue (the one that's blocked)
-2. Add a "Blocked by" relationship to the issue in the other project
-3. Linear will show this issue as blocked until the dependency is complete
-
-## Querying Dependencies
-
-Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
-
-### Via MCP
-
-Query Linear for issues with blocking relationships:
-
-```
-# Get all issues in a project
-linear_getIssues(projectId: "{project_id}")
-
-# Check if an issue has blockers
-linear_getIssue(issueId: "{issue_id}")
-# Look for blockedByIssues in the response
-```
-
-### Check if a Dependency is Complete
-
-Query the blocking issue and check its state:
-- `state.type === "completed"` means the dependency is met
-- Any other state means it's still blocking
-
-### Find Issues Blocked by a Specific Issue
-
-Via the Linear API or MCP, query for issues where `blockedByIssues` contains the issue ID.
-
-## 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 Plan Index File
-
-Create `docs/workflow/planning/{topic}.md`:
-
-```markdown
----
-topic: {topic-name}
-status: planning
-format: linear
-specification: ../specification/{topic}.md
-cross_cutting_specs:              # Omit if none
-  - ../specification/{spec}.md
-spec_commit: {git-commit-hash}
-plan_id: {PROJECT_NAME}
-project_id: {ID from MCP response}
-team: {TEAM_NAME}
-created: YYYY-MM-DD  # Use today's actual date
-updated: YYYY-MM-DD  # Use today's actual date
-planning:
-  phase: 1
-  task: ~
----
-
-# Plan: {Topic Name}
-
-## 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. Check External Dependencies below
-3. Query Linear for project issues
-4. Work through tasks in phase order (by label)
-5. 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]
-
-## Cross-Cutting References
-
-Architectural decisions from cross-cutting specifications that inform this plan:
-
-| Specification | Key Decisions | Applies To |
-|---------------|---------------|------------|
-| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min | Tasks involving API calls |
-| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user | User-facing endpoints |
-
-*Remove this section if no cross-cutting specifications apply.*
-
-## Phases
-
-### Phase 1: {Name}
-status: draft
-label: phase-1
-
-**Goal**: {What this phase accomplishes}
-**Why this order**: {Why this comes at this position}
-
-**Acceptance**:
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-#### Tasks
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-| {issue-id} | {Task Name} | {list} | pending |
-
----
-
-### Phase 2: {Name}
-status: draft
-label: phase-2
-
-...
-
-## External Dependencies
-
-[Dependencies on other topics - copy from specification's Dependencies section]
-
-- {topic}: {description}
-- {topic}: {description} → {issue-id} (resolved)
-```
-
-The External Dependencies section tracks what this plan needs from other topics. See `../dependencies.md` for the format and states (unresolved, resolved, satisfied externally).
-
-## Frontmatter
-
-The frontmatter contains all information needed to query Linear and tracks planning progress:
-
-```yaml
----
-topic: {topic-name}
-status: planning | concluded
-format: linear
-specification: ../specification/{topic}.md
-cross_cutting_specs:              # Omit if none
-  - ../specification/{spec}.md
-spec_commit: {git-commit-hash}
-plan_id: USER-AUTH-FEATURE
-project_id: abc123-def456
-team: Engineering
-created: YYYY-MM-DD  # Use today's actual date
-updated: YYYY-MM-DD  # Use today's actual date
-planning:
-  phase: 2
-  task: 3
----
-```
-
-## 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      # Discussion output
-├── specification/{topic}.md   # Specification output
-└── planning/{topic}.md        # Planning 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 `plan_id` (Linear project name) 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
-
-### Cleanup (Restart)
-
-The official Linear MCP server does not support deletion. Ask the user to delete the Linear project manually via the Linear UI.
-
-> "The Linear project **{project name}** needs to be deleted before restarting. Please delete it in the Linear UI (Project Settings → Delete project), then confirm so I can proceed."
-
-**STOP.** Wait for the user to confirm.
-
-### 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-formats/output-local-markdown.md

@@ -1,318 +0,0 @@
-# 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 with detailed task files.
-
-## Benefits
-
-- No external tools or dependencies required
-- Plan Index File provides overview; task files provide detail
-- Human-readable and easy to edit
-- Works offline with any text editor
-- Simplest setup - just create markdown files
-
-## Setup
-
-No external tools required. This format uses plain markdown files stored in the repository.
-
-## Output Location
-
-```
-docs/workflow/planning/
-├── {topic}.md                    # Plan Index File
-└── {topic}/
-    └── {task-id}.md              # Task detail files
-```
-
-The Plan Index File contains phases and task tables. Each authored task gets its own file in the `{topic}/` directory. Task filename = task ID for easy lookup.
-
-## Plan Index Template
-
-Create `{topic}.md` with this structure:
-
-```markdown
----
-topic: {feature-name}
-status: planning
-format: local-markdown
-specification: ../specification/{topic}.md
-cross_cutting_specs:              # Omit if none
-  - ../specification/{spec}.md
-spec_commit: {git-commit-hash}
-created: YYYY-MM-DD  # Use today's actual date
-updated: YYYY-MM-DD  # Use today's actual date
-planning:
-  phase: 1
-  task: ~
----
-
-# Plan: {Feature/Project Name}
-
-## 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
-
-## Cross-Cutting References
-
-Architectural decisions from cross-cutting specifications that inform this plan:
-
-| Specification | Key Decisions | Applies To |
-|---------------|---------------|------------|
-| [Caching Strategy](../../specification/caching-strategy.md) | Cache API responses for 5 min; use Redis | Tasks involving API calls |
-| [Rate Limiting](../../specification/rate-limiting.md) | 100 req/min per user; sliding window | User-facing endpoints |
-
-*Remove this section if no cross-cutting specifications apply.*
-
-## Phases
-
-### Phase 1: {Name}
-status: draft
-
-**Goal**: What this phase accomplishes
-**Why this order**: Why this comes at this position
-
-**Acceptance**:
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-#### Tasks
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-| {topic}-1-1 | {Task Name} | {list} | pending |
-| {topic}-1-2 | {Task Name} | {list} | pending |
-
----
-
-### Phase 2: {Name}
-status: draft
-
-**Goal**: What this phase accomplishes
-**Why this order**: Why this comes at this position
-
-**Acceptance**:
-- [ ] Criterion 1
-- [ ] Criterion 2
-
-#### Tasks
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-
-(Continue pattern for remaining phases)
-
----
-
-## External Dependencies
-
-[Dependencies on other topics - copy from specification's Dependencies section]
-
-- {topic}: {description}
-- {topic}: {description} → {task-reference} (resolved)
-- ~~{topic}: {description}~~ → satisfied externally
-
-## Log
-
-| Date | Change |
-|------|--------|
-| YYYY-MM-DD *(use today's actual date)* | Created from specification |
-```
-
-## Task File Template
-
-Each authored task is written to `{topic}/{task-id}.md`:
-
-```markdown
----
-id: {topic}-{phase}-{seq}
-phase: {phase-number}
-status: pending
-created: YYYY-MM-DD  # Use today's actual date
----
-
-# {Task Name}
-
-## Goal
-
-{What this task accomplishes and why — include rationale from specification}
-
-## Implementation
-
-{The "Do" — specific files, methods, approach}
-
-## Tests
-
-- `it does expected behavior`
-- `it handles edge case`
-
-## Edge Cases
-
-{Specific edge cases for this task}
-
-## Acceptance Criteria
-
-- [ ] Test written and failing
-- [ ] Implementation complete
-- [ ] Tests passing
-- [ ] Committed
-
-## Context
-
-{Relevant decisions and constraints from specification}
-
-Specification reference: `docs/workflow/specification/{topic}.md` (for ambiguity resolution)
-```
-
-## Cross-Topic Dependencies
-
-Cross-topic dependencies link tasks between different plan files. This is how you express "this feature depends on the billing system being implemented."
-
-### In the External Dependencies Section
-
-Use the format `{topic}: {description} → {task-id}` where task-id points to a specific task:
-
-```markdown
-## External Dependencies
-
-- billing-system: Invoice generation → billing-1-2 (resolved)
-- authentication: User context → auth-2-1 (resolved)
-- payment-gateway: Payment processing (unresolved - not yet planned)
-```
-
-### Task References
-
-For local markdown plans, reference tasks using the task ID (e.g., `billing-1-2`). The task file is at `{topic}/{task-id}.md`.
-
-## Querying Dependencies
-
-Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
-
-### Find Plans With External Dependencies
-
-```bash
-# Find all plans with external dependencies
-grep -l "## External Dependencies" docs/workflow/planning/*.md
-
-# Find unresolved dependencies (no arrow →)
-grep -A 10 "## External Dependencies" docs/workflow/planning/*.md | grep "^- " | grep -v "→"
-```
-
-### Find Dependencies on a Specific Topic
-
-```bash
-# Find plans that depend on billing-system
-grep -l "billing-system:" docs/workflow/planning/*.md
-```
-
-### Check if a Task Exists
-
-```bash
-# Check if task file exists
-ls docs/workflow/planning/billing-system/billing-1-2.md
-```
-
-### Check if a Task is Complete
-
-Read the task file and check the status in frontmatter:
-
-```bash
-# Check task status
-grep "status:" docs/workflow/planning/billing-system/billing-1-2.md
-```
-
-## Frontmatter
-
-Plan Index Files use YAML frontmatter for metadata:
-
-```yaml
----
-topic: {feature-name}                    # Matches filename (without .md)
-status: planning | concluded             # Planning status
-format: local-markdown                   # Output format used
-specification: ../specification/{topic}.md
-cross_cutting_specs:                     # Omit if none
-  - ../specification/{spec}.md
-spec_commit: {git-commit-hash}        # Git commit when planning started
-created: YYYY-MM-DD  # Use today's actual date
-updated: YYYY-MM-DD  # Use today's actual date
-planning:
-  phase: 2
-  task: 3
----
-```
-
-The `planning:` block tracks current progress position. It persists after the plan is concluded — `status:` indicates whether the plan is active or concluded.
-
-## Flagging Incomplete Tasks
-
-When information is missing, mark in the task table:
-
-```markdown
-| ID | Name | Edge Cases | Status |
-|----|------|------------|--------|
-| auth-1-3 | Configure rate limiting | [needs-info] threshold, per-user vs per-IP | pending |
-```
-
-And in the task file, add a "Needs Clarification" section:
-
-```markdown
-## Needs Clarification
-
-- What's the rate limit threshold?
-- Per-user or per-IP?
-```
-
-## Resulting Structure
-
-After planning:
-
-```
-docs/workflow/
-├── discussion/{topic}.md           # Discussion output
-├── specification/{topic}.md        # Specification output
-└── planning/
-    ├── {topic}.md                  # Plan Index File (format: local-markdown)
-    └── {topic}/
-        ├── {topic}-1-1.md          # Task detail files
-        ├── {topic}-1-2.md
-        └── {topic}-2-1.md
-```
-
-## Implementation
-
-### Reading Plans
-
-1. Read the Plan Index File to get overview and task tables
-2. For each task to implement, read `{topic}/{task-id}.md`
-3. Follow phase order as written in the index
-4. Check task status in the index table
-
-### Updating Progress
-
-- Update task file frontmatter `status: completed` when done
-- Update the task table in the Plan Index File
-- Check off phase acceptance criteria when all phase tasks complete
-
-### Authoring Tasks (During Planning)
-
-When a task is approved:
-1. Create `{topic}/{task-id}.md` with the task content
-2. Update the task table: set `status: authored`
-3. Update the `planning:` block in frontmatter
-
-### Cleanup (Restart)
-
-Delete the task detail directory for this topic:
-
-```bash
-rm -rf docs/workflow/planning/{topic}/
-```