@leeovery/claude-technical-workflows 2.0.15 → 2.0.17

package/skills/technical-planning/SKILL.md

@@ -9,23 +9,25 @@ Act as **expert technical architect**, **product owner**, and **plan documenter*
 
 Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work).
 
-## Six-Phase Workflow
+## Purpose in the 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
+This skill can be used:
+- **Sequentially** (Phase 4): From a validated specification
+- **Standalone** (Contract entry): From any specification meeting format requirements
 
-You're at step 4. Create the plan. Don't jump to implementation.
+Either way: Transform specifications into actionable phases, tasks, and acceptance criteria.
 
-## Source Material
+### What This Skill Needs
+
+- **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
 
-Plans are built **exclusively** from the specification:
-- **Specification** (`docs/workflow/specification/{topic}.md`)
+**If missing:** Will ask user for specification location or content.
+
+## Source Material
 
-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 specification is your sole input.** Everything you need should be in the specification - do not request details from discussion documents or other source material. If information is missing, ask for clarification on the specification itself.
 
 ## The Process
 

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

@@ -0,0 +1,69 @@
+# Dependencies
+
+*Reference for dependency handling across the technical workflow*
+
+---
+
+## Internal Dependencies
+
+Internal dependencies are dependencies within a single topic/epic - where one task depends on another task in the same plan. These are handled by the planning output format's native dependency system.
+
+During planning, structure tasks in the correct order with appropriate dependencies so work proceeds logically. The output format manages these relationships and ensures tasks are worked in the right sequence.
+
+See the relevant output format reference for how to create and query internal dependencies.
+
+## External Dependencies
+
+External dependencies are things a feature needs from other topics or systems that are outside the current plan's scope. They come from the specification's Dependencies section.
+
+## 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 → beads-9m3p (resolved)
+- ~~payment-gateway: Payment processing~~ → satisfied externally
+```
+
+If there are no external dependencies, still include the section:
+
+```markdown
+## External Dependencies
+
+No external dependencies.
+```
+
+This makes it explicit for downstream stages that dependencies were considered and none exist.
+
+## States
+
+| 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 |
+
+## Lifecycle
+
+```
+SPECIFICATION                    PLANNING
+───────────────────────────────────────────────────────────────────
+Dependencies section    →    Copied to plan index as unresolved
+(natural language)                      ↓
+                             Resolved when linked to specific task ID
+                             (via planning or /link-dependencies)
+```
+
+## Resolution
+
+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:
+- 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/formal-planning.md

@@ -19,9 +19,29 @@ From the specification (`docs/workflow/specification/{topic}.md`), extract:
 - Architectural choices
 - Edge cases identified
 - Constraints and requirements
+- **External dependencies** (from the Dependencies section)
 
 **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.
 
+#### Extract External Dependencies
+
+The specification's Dependencies section lists things this feature needs from other topics/systems. These are **external dependencies** - things outside this plan's scope that must exist for implementation to proceed.
+
+Copy these into the plan index file (see "External Dependencies Section" below). During planning:
+
+1. **Check for existing plans**: For each dependency, search `docs/workflow/planning/` for a matching topic
+2. **If plan exists**: Try to identify specific tasks that satisfy the dependency. Query the output format to find relevant tasks. If ambiguous, ask the user which tasks apply.
+3. **If no plan exists**: Record the dependency in natural language - it will be linked later via `/link-dependencies` or when that topic is planned.
+
+**Optional reverse check**: Ask the user: "Would you like me to check if any existing plans depend on this topic?"
+
+If yes:
+1. Scan other plan indexes for External Dependencies that reference this topic
+2. For each match, identify which task(s) in the current plan satisfy that dependency
+3. Update the other plan's dependency entry with the task ID (unresolved → resolved)
+
+Alternatively, the user can run `/link-dependencies` later to resolve dependencies across all plans in bulk.
+
 ### 2. Define Phases
 
 Break into logical phases:
@@ -106,6 +126,11 @@ Before handing off to implementation:
 - [ ] Each task has micro acceptance (test name)
 - [ ] All edge cases mapped to tasks
 - [ ] Gaps flagged with `[needs-info]`
+- [ ] External dependencies documented in plan index
+
+## External Dependencies Section
+
+The plan index file must include an External Dependencies section. See **[dependencies.md](dependencies.md)** for the format, states, and how they affect implementation.
 
 ## Commit Frequently
 

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

@@ -71,9 +71,10 @@ This plan is managed via Backlog.md. Tasks are stored in the `backlog/` director
 
 **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
+2. Check External Dependencies below
+3. Query backlog via MCP or read task files directly
+4. Work through tasks by status/priority
+5. Update task status as work completes
 
 **To add tasks**: Run `backlog add "Task title"` or create task files directly.
 
@@ -86,8 +87,17 @@ Tasks are organized with labels/priorities:
 ## Key Decisions
 
 [Summary of key decisions from specification]
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {topic}: {description} → {task-id} (resolved)
 ```
 
+The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+
 ### Task File Format
 
 Each task is a separate file: `backlog/task-{id} - {title}.md`
@@ -138,7 +148,68 @@ Specification reference: `docs/workflow/specification/{topic}.md` (for ambiguity
 | `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]` |
+| `dependencies` | Blocking tasks (internal) | `[task-1, task-3]` |
+| `external_deps` | Cross-topic dependencies | `[billing-system#task-5]` |
+
+## Cross-Topic Dependencies
+
+Cross-topic dependencies link tasks between different plan topics. This is how you express "this task depends on the billing system being implemented."
+
+### In Task Frontmatter
+
+Use the `external_deps` field with the format `{topic}#{task-id}`:
+
+```yaml
+---
+status: To Do
+priority: high
+labels: [phase-1]
+external_deps: [billing-system#task-5, authentication#task-3]
+---
+```
+
+### In Plan Reference File
+
+The plan reference file at `docs/workflow/planning/{topic}.md` tracks external dependencies in a dedicated section (see template below).
+
+## Querying Dependencies
+
+Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
+
+### Find Tasks With External Dependencies
+
+```bash
+# Find all tasks with external dependencies
+grep -l "external_deps:" backlog/*.md
+
+# Find tasks depending on a specific topic
+grep -l "billing-system#" backlog/*.md
+```
+
+### Check Internal Dependencies
+
+```bash
+# Find tasks with dependencies
+grep -l "dependencies:" backlog/*.md
+
+# Show dependency values
+grep "dependencies:" backlog/*.md
+```
+
+### Check if a Dependency is Complete
+
+Read the task file and check the frontmatter:
+- `status: Done` means the dependency is met
+- Any other status means it's still blocking
+
+### Parse Frontmatter Programmatically
+
+For more complex queries, parse the YAML frontmatter:
+
+```bash
+# Extract frontmatter from a task file
+sed -n '/^---$/,/^---$/p' backlog/task-5*.md
+```
 
 ### Using `needs-info` Label
 

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

@@ -78,10 +78,13 @@ This creates `.beads/config.yaml` with the appropriate `no-db` setting.
 
 | Planning Concept | Beads Entity |
 |------------------|--------------|
-| Plan | Epic issue |
+| Specification/Topic | Epic issue |
 | Phase | Sub-issue under epic |
 | Task | Sub-task under phase |
-| Dependency | `bd dep add` relationship |
+| Internal dependency | `bd dep add` within same epic |
+| Cross-topic dependency | `bd dep add` across epics |
+
+Each specification topic becomes its own epic. All epics live in one beads database, enabling cross-topic dependencies.
 
 Example hierarchy:
 ```
@@ -91,8 +94,85 @@ bd-a3f8        (Epic: User Authentication)
 │   └── bd-a3f8.1.2  (Task: Session management)
 └── bd-a3f8.2  (Phase 2: OAuth)
     └── bd-a3f8.2.1  (Task: Google provider)
+
+bd-b7c2        (Epic: Billing System)  ← Different topic, same database
+├── bd-b7c2.1  (Phase 1: Invoicing)
+│   └── bd-b7c2.1.1  (Task: Invoice generation)
+```
+
+## Cross-Epic Dependencies
+
+Cross-topic dependencies link tasks between different epics (different specifications/topics). This is how you express "billing depends on authentication being complete."
+
+### Creating Cross-Epic Dependencies
+
+Use the same `bd dep add` command - it works across epics:
+
+```bash
+# Invoice generation (in billing epic) depends on user authentication (in auth epic)
+bd dep add bd-b7c2.1.1 bd-a3f8.1.1
+```
+
+After adding, `bd ready` will not show `bd-b7c2.1.1` until `bd-a3f8.1.1` is closed.
+
+### Viewing Cross-Epic Dependencies
+
+```bash
+# Show what a task depends on
+bd show bd-b7c2.1.1
+
+# Show what depends on a task
+bd show bd-a3f8.1.1 --deps
+```
+
+## Querying Dependencies
+
+Use these queries to understand the dependency graph for implementation blocking and `/link-dependencies`.
+
+### Find Ready Tasks (No Open Blockers)
+
+```bash
+bd ready
 ```
 
+Returns tasks with no incomplete dependencies - these are safe to implement.
+
+### Find All Tasks Blocked By a Specific Task
+
+```bash
+bd show bd-a3f8.1.1 --deps
+```
+
+Shows what will be unblocked when this task completes.
+
+### Find What a Task Depends On
+
+```bash
+bd show bd-b7c2.1.1
+```
+
+The output includes a "Blocked by" section listing dependencies.
+
+### Query Via JSONL (Advanced)
+
+For programmatic queries, read `.beads/issues.jsonl` directly:
+
+```bash
+# Find all dependencies (grep for blocked_by field)
+grep -o '"blocked_by":\[[^]]*\]' .beads/issues.jsonl
+
+# Find tasks depending on a specific ID
+grep '"bd-a3f8.1.1"' .beads/issues.jsonl | grep blocked_by
+```
+
+### Check if a Task is Complete
+
+```bash
+bd show bd-a3f8.1.1
+```
+
+Look for `status: closed` in the output. A dependency is "met" when the task is closed.
+
 ## Output Process
 
 ### 1. Create Epic for Plan
@@ -180,9 +260,10 @@ This plan is managed via Beads. Tasks are stored in `.beads/` and tracked as a d
 
 **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"`
+2. Check External Dependencies below
+3. Query `bd ready` for unblocked tasks
+4. Work through tasks respecting dependencies
+5. Close tasks with `bd close bd-{id} "reason"`
 
 ## Key Decisions
 
@@ -194,8 +275,17 @@ This plan is managed via Beads. Tasks are stored in `.beads/` and tracked as a d
 |-------|------|---------|
 | Phase 1 | {Goal} | bd-{id}.1 |
 | Phase 2 | {Goal} | bd-{id}.2 |
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {topic}: {description} → {task-id} (resolved)
 ```
 
+The External Dependencies section tracks what this plan needs from other topics. See `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+
 ## Frontmatter
 
 The `format: beads` frontmatter tells implementation to use beads CLI:

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

@@ -18,9 +18,52 @@ Ask the user: **Which team should own this project?**
 
 | Planning Concept | Linear Entity |
 |------------------|---------------|
-| Plan | Project |
+| 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
 
@@ -125,17 +168,27 @@ This plan is managed in Linear. The source of truth for tasks and progress is th
 
 **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
+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]
+
+## 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 `formal-planning.md` for the format and states (unresolved, resolved, satisfied externally).
+
 ## Frontmatter
 
 The frontmatter contains all information needed to query Linear:

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

@@ -124,11 +124,18 @@ Map edge cases from specification to specific tasks:
 
 Tables, schemas, API contracts
 
-## Dependencies
+## Internal Dependencies
 
 - Prerequisites for Phase 1
-- Phase dependencies
-- External blockers
+- Phase dependencies (Phase 2 depends on Phase 1, etc.)
+
+## External Dependencies
+
+[Dependencies on other topics - copy from specification's Dependencies section]
+
+- {topic}: {description}
+- {topic}: {description} → {task-reference} (resolved)
+- ~~{topic}: {description}~~ → satisfied externally
 
 ## Rollback (if applicable)
 
@@ -141,6 +148,67 @@ Triggers and steps
 | YYYY-MM-DD | Created from specification |
 ```
 
+## 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-reference}` where task-reference points to a specific task in another plan file:
+
+```markdown
+## External Dependencies
+
+- billing-system: Invoice generation → billing-system.md#phase-1-task-2 (resolved)
+- authentication: User context → authentication.md#phase-2-task-1 (resolved)
+- payment-gateway: Payment processing (unresolved - not yet planned)
+```
+
+### Task References
+
+For local markdown plans, reference tasks using:
+- `{topic}.md#phase-{n}-task-{m}` - references a specific task by phase and number
+- Consider adding nano IDs to task headers for more stable references
+
+## 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 Dependency Task Exists
+
+Read the referenced plan file and verify the task exists:
+
+```bash
+# Check if a task exists in another plan
+grep "Phase 1.*Task 2" docs/workflow/planning/billing-system.md
+```
+
+### Check if a Dependency is Complete
+
+For local markdown, check if the task's acceptance criteria are checked off:
+
+```bash
+# Look for completed acceptance criteria
+grep -A 5 "### Phase 1" docs/workflow/planning/billing-system.md | grep "\[x\]"
+```
+
 ## Frontmatter
 
 The `format: local-markdown` frontmatter tells implementation that the full plan content is in this file.

package/skills/technical-research/SKILL.md

@@ -7,16 +7,20 @@ description: "Explore ideas, validate concepts, and research broadly across tech
 
 Act as **research partner** with broad expertise spanning technical, product, business, and market domains. Your role is learning, exploration, and discovery.
 
-## Six-Phase Workflow
+## Purpose in the 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
+This skill can be used:
+- **Sequentially** (Phase 1): First phase, to explore ideas before discussion
+- **Standalone** (Contract entry): To research and validate any idea, feature, or concept
 
-You're at step 1. Explore freely.
+Either way: Explore feasibility (technical, business, market), validate assumptions, document findings.
+
+### What This Skill Needs
+
+- **Topic or idea** (required) - What to research/explore
+- **Existing context** (optional) - Any prior research or constraints
+
+**If missing:** Will ask user what they want to explore.
 
 ## Your Expertise
 
@@ -58,7 +62,7 @@ Start with one file. Early research is messy - topics aren't clear, you're follo
 
 **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/`.
+**Periodic review**: Every few sessions, assess: are themes emerging? Split them out. Still fuzzy? Keep exploring. Ready for deeper discussion? Research phase is complete.
 
 ## Documentation Loop
 

package/skills/technical-review/SKILL.md

@@ -9,20 +9,37 @@ Act as a **senior software architect** with deep experience in code review. You
 
 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
+## Review Artifacts
 
-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
+This skill reviews against available artifacts. Required:
+- **Plan** (the tasks and acceptance criteria)
 
-You're at step 6. The code exists. Your job is comprehensive verification.
+Optional but helpful:
+- **Specification** (context for design decisions)
+
+## Purpose in the Workflow
+
+This skill can be used:
+- **Sequentially** (Phase 6): After implementation of a planned feature
+- **Standalone** (Contract entry): To review any implementation against a plan
+
+Either way: Verify every plan task was implemented, tested adequately, and meets quality standards.
+
+### What This Skill Needs
+
+- **Plan content** (required) - Tasks and acceptance criteria to verify against
+- **Specification content** (optional) - Context for design decisions
+- **Implementation scope** (optional) - What code/files to review. Will identify from git if not specified.
+
+**If missing:** Will ask user for plan location. Can proceed without specification.
 
 ## 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.
+Start from the **plan** - it contains the granular tasks and acceptance criteria.
+
+Use the **specification** for context if available. If no specification exists, the plan is the source of truth for design decisions.
+
+Verify **all** tasks, not a sample.
 
 ```
 Plan (tasks + acceptance criteria)

package/skills/technical-review/references/review-checklist.md

@@ -6,8 +6,10 @@
 
 ## Before Starting
 
-1. Read plan: `docs/workflow/planning/{topic}.md`
-2. Read specification: `docs/workflow/specification/{topic}.md` (for context)
+1. Read plan (from the location provided)
+   - If not found at expected path, ask user where the plan is
+2. Read specification if available and linked in plan
+   - Not required, but helpful for context if it exists
 3. Identify what code/files were changed
 4. Check for project-specific skills in `.claude/skills/`