@leeovery/claude-technical-workflows 2.0.0

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

@@ -0,0 +1,227 @@
+# Output: Backlog.md
+
+*Output adapter for **[technical-planning](../SKILL.md)***
+
+---
+
+Use this output format when you want a **local Kanban board with MCP integration**. Backlog.md is a markdown-native task manager designed for Git repositories with AI assistant support.
+
+## About Backlog.md
+
+Backlog.md is a CLI + web Kanban tool that:
+- Stores tasks as individual markdown files in `backlog/` directory
+- Has MCP (Model Context Protocol) support for Claude Code
+- Provides terminal and web Kanban views
+- Supports dependencies, priorities, assignees
+- Built for Git workflows with auto-commit
+
+See: https://github.com/MrLesk/Backlog.md
+
+## Setup
+
+Install via npm:
+
+```bash
+npm install -g backlog-md
+```
+
+Initialize in your project:
+
+```bash
+backlog init "Project Name"
+```
+
+For MCP integration, configure the Backlog.md MCP server in Claude Code settings.
+
+## Output Location
+
+For Backlog.md integration, use the project's `backlog/` directory:
+
+```
+backlog/
+├── task-1 - Phase 1 Setup.md
+├── task-2 - Implement login endpoint.md
+└── task-3 - Add session management.md
+```
+
+The plan file in `docs/workflow/planning/{topic}.md` serves as the reference pointer to backlog tasks.
+
+## File Structure
+
+### Plan Reference File (`docs/workflow/planning/{topic}.md`)
+
+```markdown
+---
+format: backlog-md
+project: {TOPIC_NAME}
+---
+
+# Plan Reference: {Topic Name}
+
+**Specification**: `docs/workflow/specification/{topic}.md`
+**Created**: {DATE}
+
+## About This Plan
+
+This plan is managed via Backlog.md. Tasks are stored in the `backlog/` directory.
+
+## How to Use
+
+**View the board**: Run `backlog board` (terminal) or `backlog browser` (web UI)
+
+**Implementation will**:
+1. Read this file to identify the plan
+2. Query backlog via MCP or read task files directly
+3. Work through tasks by status/priority
+4. Update task status as work completes
+
+**To add tasks**: Run `backlog add "Task title"` or create task files directly.
+
+## Phases
+
+Tasks are organized with labels/priorities:
+- Label: `phase-1`, `phase-2`, etc.
+- Priority: high (foundational), medium (core), low (refinement)
+
+## Key Decisions
+
+[Summary of key decisions from specification]
+```
+
+### Task File Format
+
+Each task is a separate file: `backlog/task-{id} - {title}.md`
+
+Tasks should be **fully self-contained** - include all context so humans and agents can execute without referencing other files.
+
+```markdown
+---
+status: To Do
+priority: high
+labels: [phase-1, api]
+---
+
+# {Task Title}
+
+## Goal
+
+{What this task accomplishes and why - include rationale from specification}
+
+## Implementation
+
+{The "Do" - specific files, methods, approach}
+
+## Acceptance Criteria
+
+1. [ ] Test written: `it does expected behavior`
+2. [ ] Test written: `it handles edge case`
+3. [ ] Implementation complete
+4. [ ] Tests passing
+5. [ ] Committed
+
+## Edge Cases
+
+{Specific edge cases for this task}
+
+## Context
+
+{Relevant decisions and constraints from specification}
+
+Specification reference: `docs/workflow/specification/{topic}.md` (for ambiguity resolution)
+```
+
+### Frontmatter Fields
+
+| Field | Purpose | Values |
+|-------|---------|--------|
+| `status` | Workflow state | To Do, In Progress, Done |
+| `priority` | Importance | high, medium, low |
+| `labels` | Categories | `[phase-1, api, edge-case, needs-info]` |
+| `assignee` | Who's working on it | (optional) |
+| `dependencies` | Blocking tasks | `[task-1, task-3]` |
+
+### Using `needs-info` Label
+
+When creating tasks with incomplete information:
+
+1. **Create the task anyway** - don't block planning
+2. **Add `needs-info` to labels** - makes gaps visible
+3. **Note what's missing** in task body - be specific
+4. **Continue planning** - circle back later
+
+This allows iterative refinement. Create all tasks, identify gaps, circle back to specification if needed, then update tasks with missing detail.
+
+## Phase Representation
+
+Since Backlog.md doesn't have native milestones, represent phases via:
+
+1. **Labels**: `phase-1`, `phase-2`, etc.
+2. **Task naming**: Prefix with phase number `task-X - [P1] Task name.md`
+3. **Priority**: Foundation tasks = high, refinement = low
+
+## Benefits
+
+- Visual Kanban board in terminal or web UI
+- Local and fully version-controlled
+- MCP integration for Claude Code
+- Auto-commit on task changes
+- Individual task files for easy editing
+
+## MCP Integration
+
+If Backlog.md MCP server is configured, planning can:
+- Create tasks via MCP tools
+- Set status, priority, labels
+- Query existing tasks
+
+Implementation can:
+- Query tasks by status/label
+- Update task status as work completes
+- Add notes to tasks
+
+## Resulting Structure
+
+After planning:
+
+```
+project/
+├── backlog/
+│   ├── task-1 - [P1] Configure auth.md
+│   ├── task-2 - [P1] Add login endpoint.md
+│   └── task-3 - [P2] Session management.md
+├── docs/workflow/
+│   ├── discussion/{topic}.md      # Phase 2 output
+│   ├── specification/{topic}.md   # Phase 3 output
+│   └── planning/{topic}.md        # Phase 4 output (format: backlog-md - pointer)
+```
+
+## Implementation
+
+### Reading Plans
+
+1. If Backlog.md MCP is available, query tasks via MCP
+2. Otherwise, read task files from `backlog/` directory
+3. Filter tasks by label (e.g., `phase-1`) or naming convention
+4. Process in priority order (high → medium → low)
+
+### Updating Progress
+
+- Update task status to "In Progress" when starting
+- Check off acceptance criteria items in task file
+- Update status to "Done" when complete
+- Backlog.md CLI auto-moves to completed folder
+
+### Fallback
+
+Can read `backlog/` files directly if MCP unavailable.
+
+## CLI Commands Reference
+
+```bash
+backlog init "Project"     # Initialize backlog
+backlog add "Task title"   # Add task
+backlog board              # Terminal Kanban view
+backlog browser            # Web UI
+backlog list               # List all tasks
+backlog search "query"     # Search tasks
+```

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

@@ -0,0 +1,302 @@
+# Output: Beads
+
+*Output adapter for **[technical-planning](../SKILL.md)***
+
+---
+
+Use this output format when you need **dependency-aware task tracking designed for AI agents**. Beads is a git-backed graph issue tracker that excels at complex, multi-phase implementations with real dependency management.
+
+## About Beads
+
+Beads (`bd`) is an issue tracker built specifically for AI agents:
+- Git-backed storage in `.beads/` directory (JSONL format)
+- Hash-based IDs (`bd-a1b2`) prevent merge conflicts
+- Native dependency graph with blocking relationships
+- Hierarchical tasks: epics → tasks → subtasks
+- `bd ready` command identifies unblocked work
+- Semantic summarization preserves context windows
+- Multi-agent coordination via sync protocol
+
+See: https://github.com/steveyegge/beads
+
+## Setup
+
+### 1. Check Installation
+
+Check if beads is installed (required every session in ephemeral environments):
+
+```bash
+which bd
+```
+
+- **Local systems**: May already be installed via Homebrew
+- **Ephemeral environments** (Claude Code on web): Needs installation each session
+
+If not installed:
+```bash
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+```
+
+### 2. Check If Project Initialized
+
+Check if beads is already set up in this project:
+
+```bash
+ls .beads/config.yaml
+```
+
+**If `.beads/` exists**: Project is already initialized - skip to using beads.
+
+**If not initialized**: Continue with steps 3 and 4.
+
+### 3. Choose Database Mode
+
+Beads supports two modes. Ask the user:
+
+> "Beads can run with or without a local database. Database mode uses a daemon that auto-syncs to JSONL. No-database mode writes directly to JSONL. Which do you prefer? (default: database)"
+
+### 4. Initialize
+
+Based on the user's choice:
+
+```bash
+bd init --quiet          # database mode (default)
+bd init --quiet --no-db  # no-database mode
+```
+
+This creates `.beads/config.yaml` with the appropriate `no-db` setting.
+
+## Benefits
+
+- Complex dependency graphs with native blocking relationships
+- Multi-session context preservation via semantic summarization
+- Multi-agent coordination support
+- `bd ready` identifies actionable unblocked work
+- Git-backed and version-controlled
+
+## Beads Structure Mapping
+
+| Planning Concept | Beads Entity |
+|------------------|--------------|
+| Plan | Epic issue |
+| Phase | Sub-issue under epic |
+| Task | Sub-task under phase |
+| Dependency | `bd dep add` relationship |
+
+Example hierarchy:
+```
+bd-a3f8        (Epic: User Authentication)
+├── bd-a3f8.1  (Phase 1: Core Auth)
+│   ├── bd-a3f8.1.1  (Task: Login endpoint)
+│   └── bd-a3f8.1.2  (Task: Session management)
+└── bd-a3f8.2  (Phase 2: OAuth)
+    └── bd-a3f8.2.1  (Task: Google provider)
+```
+
+## Output Process
+
+### 1. Create Epic for Plan
+
+```bash
+bd create "Plan: {Topic Name}" -p 1
+```
+
+Note the returned ID (e.g., `bd-a3f8`). This is the plan epic.
+
+### 2. Create Phase Issues
+
+For each phase, create a sub-issue under the epic:
+
+```bash
+bd create "Phase 1: {Phase Name}" -p 1 --parent bd-a3f8
+bd create "Phase 2: {Phase Name}" -p 2 --parent bd-a3f8
+```
+
+Add phase acceptance criteria in the issue body.
+
+### 3. Create Task Issues
+
+For each task, create under the appropriate phase:
+
+```bash
+bd create "{Task Name}" -p 1 --parent bd-a3f8.1
+```
+
+Tasks should be **fully self-contained** - include all context so humans and agents can execute without referencing other files.
+
+Task body should include:
+```
+## Goal
+{What this task accomplishes and why - include rationale from specification}
+
+## Implementation
+{Specific files, methods, approach}
+
+## Tests
+- `it does expected behavior`
+- `it handles edge case`
+
+## Edge Cases
+{Specific edge cases for this task}
+
+## Context
+{Relevant decisions and constraints from specification}
+
+Specification reference: docs/workflow/specification/{topic}.md (for ambiguity resolution)
+```
+
+### 4. Add Dependencies
+
+When tasks depend on each other:
+
+```bash
+bd dep add bd-a3f8.1.2 bd-a3f8.1.1  # 1.2 blocked by 1.1
+```
+
+### 5. Create Local Plan File
+
+Create `docs/workflow/planning/{topic}.md`:
+
+```markdown
+---
+format: beads
+epic: bd-{EPIC_ID}
+---
+
+# Plan Reference: {Topic Name}
+
+**Specification**: `docs/workflow/specification/{topic}.md`
+**Created**: {DATE}
+
+## About This Plan
+
+This plan is managed via Beads. Tasks are stored in `.beads/` and tracked as a dependency graph.
+
+## How to Use
+
+**View ready tasks**: Run `bd ready`
+**View all tasks**: Run `bd list --tree`
+**View specific task**: Run `bd show bd-{id}`
+
+**Implementation will**:
+1. Read this file to identify the epic
+2. Query `bd ready` for unblocked tasks
+3. Work through tasks respecting dependencies
+4. Close tasks with `bd close bd-{id} "reason"`
+
+## Key Decisions
+
+[Summary of key decisions from specification]
+
+## Phase Overview
+
+| Phase | Goal | Epic ID |
+|-------|------|---------|
+| Phase 1 | {Goal} | bd-{id}.1 |
+| Phase 2 | {Goal} | bd-{id}.2 |
+```
+
+## Frontmatter
+
+The `format: beads` frontmatter tells implementation to use beads CLI:
+
+```yaml
+---
+format: beads
+epic: bd-a3f8
+---
+```
+
+## Flagging Incomplete Tasks
+
+When information is missing, note it in the task body:
+
+```bash
+bd create "Configure rate limiting [needs-info]" -p 2 --parent bd-a3f8.1
+```
+
+In the task body:
+```
+## Needs Clarification
+- What's the rate limit threshold?
+- Per-user or per-IP?
+```
+
+## Implementation
+
+### Reading Plans
+
+1. Extract `epic` ID from frontmatter
+2. Check `.beads/config.yaml` for `no-db` setting
+3. Run `bd ready` to get unblocked tasks
+4. View task details with `bd show bd-{id}`
+5. Process by priority (P0 → P1 → P2 → P3)
+6. Respect dependency graph - only work on ready tasks
+
+### Updating Progress
+
+- Close tasks with `bd close bd-{id} "reason"` when complete
+- Include task ID in commit messages: `git commit -m "message (bd-{id})"`
+- **Database mode**: Run `bd sync` before committing or ending session to ensure changes are persisted
+- **No-db mode**: No sync needed - changes write directly to JSONL
+- Use `bd ready` to identify next unblocked task
+
+### Fallback
+
+If `bd` CLI is unavailable, follow the installation steps in the **Setup** section above.
+
+## Beads Workflow Commands
+
+| Command | Purpose |
+|---------|---------|
+| `bd ready` | List tasks with no open blockers |
+| `bd list --tree` | Show full task hierarchy |
+| `bd show bd-{id}` | View task details |
+| `bd close bd-{id} "reason"` | Complete a task |
+| `bd dep add child parent` | Add dependency |
+| `bd sync` | Force immediate sync to JSONL (database mode only) |
+
+## Sync Protocol (Database Mode Only)
+
+In database mode, a daemon auto-syncs changes to JSONL with a ~5 second debounce. Run `bd sync` before committing or ending a session to ensure all pending changes are persisted:
+
+```bash
+bd sync
+```
+
+**Skip this entirely if `no-db: true`** - changes write directly to JSONL, no sync needed.
+
+## Commit Message Convention
+
+Include issue IDs in commits:
+
+```bash
+git commit -m "Add login endpoint (bd-a3f8.1.1)"
+```
+
+This enables `bd doctor` to identify orphaned issues.
+
+## Resulting Structure
+
+After planning:
+
+```
+project/
+├── .beads/
+│   └── issues.jsonl          # Beads database
+├── docs/workflow/
+│   ├── discussion/{topic}.md      # Phase 2 output
+│   ├── specification/{topic}.md   # Phase 3 output
+│   └── planning/{topic}.md        # Phase 4 output (format: beads)
+```
+
+## Priority Mapping
+
+| Planning Priority | Beads Priority |
+|-------------------|----------------|
+| Foundation/Setup | P0 |
+| Core functionality | P1 |
+| Enhancement | P2 |
+| Nice-to-have | P3 |
+
+Use `-p {0-3}` flag when creating issues.

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

@@ -0,0 +1,14 @@
+# Output Formats
+
+*Reference for **[technical-planning](../SKILL.md)***
+
+---
+
+Plans can be stored in different formats. **Ask the user which format they prefer** - present the benefits from each adapter file and let them decide.
+
+## Available Formats
+
+- **[Local Markdown](output-local-markdown.md)** - Single markdown file, no external tools
+- **[Linear](output-linear.md)** - Linear project with labeled issues (requires MCP)
+- **[Backlog.md](output-backlog-md.md)** - Kanban board with task files
+- **[Beads](output-beads.md)** - Git-backed graph issue tracker for AI agents