@leeovery/claude-technical-workflows 2.0.6 → 2.0.8

package/README.md

@@ -1,10 +1,11 @@
 <h1 align="center">Claude Technical Workflows</h1>
 
 <p align="center">
-  <strong>Structured Discussion & Planning Skills for Claude Code</strong>
+  <strong>From Idea to Implementation: Software Engineering Workflows for Claude Code</strong>
 </p>
 
 <p align="center">
+  <a href="#how-do-i-use-this">How to Use</a> •
   <a href="#installation">Installation</a> •
   <a href="#the-six-phase-workflow">Workflow</a> •
   <a href="#skills">Skills</a> •
@@ -24,12 +25,63 @@
 
 ## About
 
-A structured approach to technical discussions and implementation planning with Claude Code. These skills enforce a deliberate **research-then-discuss-then-specify-then-plan-then-implement-then-review** workflow that captures context, decisions, and rationale before any code is written—then validates the work against those artifacts.
+A six-phase workflow for Claude Code that captures context, decisions, and rationale before any code is written, then implements and validates the work against those artifacts.
 
-**Why this matters:** Complex features benefit from thorough discussion before implementation. These skills help you document the *what* and *why* before diving into the *how*—preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost.
+```
+Research       → Explore ideas
+     ↓
+Discussion     → Debate and decide
+     ↓
+Specification  → Validate and refine
+     ↓
+Planning       → Structure the work
+     ↓
+Implementation → Build via TDD
+     ↓
+Review         → Validate against spec
+```
+
+**Why this matters:** Complex features benefit from thorough discussion before implementation. These skills help you document the *what* and *why* before diving into the *how*, preserving architectural decisions, edge cases, and the reasoning behind choices that would otherwise be lost.
 
 **This is a work in progress.** The workflow is being refined through real-world usage. Expect updates as patterns evolve.
 
+**Model compatibility:** These skills have been developed and refined for Claude Code running on **Opus 4.5**. Different models may exhibit different edge cases, and future model releases may require adjustments to the prompts and workflows.
+
+## How do I use this?
+
+You have two entry points:
+
+| Start here... | When... | Command |
+|---------------|---------|---------|
+| **Research** | You have a fresh idea to explore: feasibility, market, viability, early thoughts | `/start-research` |
+| **Discussion** | You already know what you're building and need to iron out the details | `/start-discussion` |
+
+**Research** is a free-for-all. Explore broadly, follow tangents, challenge assumptions. Not everything researched gets built, and that's fine. Use this for ideas that need validating before you commit.
+
+**Discussion** is where you work through the challenging parts: core architecture, edge cases, non-obvious decisions. The key value is that it captures *how* you arrived at decisions, not just the decisions themselves. When you explore four approaches and pick one, the document explains why you rejected the others. This context is invaluable later.
+
+Then follow the flow:
+
+```
+Research → Discussion → Specification → Planning → Implementation → Review
+```
+
+Each phase builds on the previous. Specification validates your discussions into a standalone doc. Planning breaks that into tasks. Implementation executes via TDD. Review validates against the spec.
+
+### Commands
+
+Each phase has a command designed as its entry point:
+
+| Phase          | Command                 |
+|----------------|-------------------------|
+| Research       | `/start-research`       |
+| Discussion     | `/start-discussion`     |
+| Specification  | `/start-specification`  |
+| Planning       | `/start-planning`       |
+| Implementation | `/start-implementation` |
+
+Run the command directly or ask Claude to run it. Each command gathers the context it needs, asking what you're researching, discussing, or planning. Where relevant, it looks at outputs from the previous phase and offers you a choice from the list.
+
 ## Installation
 
 ### npm
@@ -56,7 +108,7 @@ Due to bugs in npm 7+ ([issue #3042](https://github.com/npm/cli/issues/3042)) an
 npx claude-manager remove @leeovery/claude-technical-workflows && npm rm @leeovery/claude-technical-workflows
 ```
 
-The [Claude Manager](https://github.com/leeovery/claude-manager) copies skills to `.claude/` automatically.
+The [Claude Manager](https://github.com/leeovery/claude-manager) copies skills, commands, and agents to `.claude/` automatically.
 
 ## The Six-Phase Workflow
 
@@ -110,6 +162,7 @@ Documents are stored using a **phase-first** organization:
 ```
 docs/workflow/
 ├── research/              # Phase 1 - flat, semantically named files
+│   ├── exploration.md
 │   ├── competitor-analysis.md
 │   └── pricing-models.md
 ├── discussion/            # Phase 2 - one file per topic
@@ -120,7 +173,7 @@ docs/workflow/
     └── {topic}.md
 ```
 
-Research is a flat directory of semantically named files (topics emerge later). From discussion onwards, each topic gets its own file per phase.
+Research starts with `exploration.md` and splits into topic files as themes emerge. From discussion onwards, each topic gets its own file per phase.
 
 ### Package Structure
 
@@ -148,14 +201,14 @@ agents/
 
 ## Skills
 
-| Skill | Phase | Description |
-|-------|-------|-------------|
-| [**technical-research**](skills/technical-research/) | 1 | Explore ideas from their earliest seed. Investigate market fit, technical feasibility, business viability. Free-flowing exploration across technical, business, and market domains. |
-| [**technical-discussion**](skills/technical-discussion/) | 2 | Document technical discussions as expert architect and meeting assistant. Captures context, decisions, edge cases, competing solutions, debates, and rationale. |
-| [**technical-specification**](skills/technical-specification/) | 3 | Build validated specifications from discussion documents through collaborative refinement. Filters hallucinations, enriches gaps, produces standalone spec. |
-| [**technical-planning**](skills/technical-planning/) | 4 | Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats. |
-| [**technical-implementation**](skills/technical-implementation/) | 5 | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval. |
-| [**technical-review**](skills/technical-review/) | 6 | Review completed implementation against specification requirements and plan acceptance criteria. Uses parallel subagents for efficient chain verification. Produces structured feedback without fixing code. |
+| Skill                                                            | Phase | Description                                                                                                                                                                                                  |
+|------------------------------------------------------------------|-------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**technical-research**](skills/technical-research/)             | 1     | Explore ideas from their earliest seed. Investigate market fit, technical feasibility, business viability. Free-flowing exploration across technical, business, and market domains.                          |
+| [**technical-discussion**](skills/technical-discussion/)         | 2     | Document technical discussions as expert architect and meeting assistant. Captures context, decisions, edge cases, competing solutions, debates, and rationale.                                              |
+| [**technical-specification**](skills/technical-specification/)   | 3     | Build validated specifications from discussion documents through collaborative refinement. Filters hallucinations, enriches gaps, produces standalone spec.                                                  |
+| [**technical-planning**](skills/technical-planning/)             | 4     | Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats.                                                                 |
+| [**technical-implementation**](skills/technical-implementation/) | 5     | Execute implementation plans using strict TDD workflow. Writes tests first, implements to pass, commits frequently, and gates phases on user approval.                                                       |
+| [**technical-review**](skills/technical-review/)                 | 6     | Review completed implementation against specification requirements and plan acceptance criteria. Uses parallel subagents for efficient chain verification. Produces structured feedback without fixing code. |
 
 ### technical-research
 
@@ -254,20 +307,21 @@ Reviews completed work with fresh perspective. Validates implementation against
 
 Slash commands to quickly invoke the workflow.
 
-| Command | Description |
-|---------|-------------|
-| [**/start-research**](commands/start-research.md) | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion. |
-| [**/start-discussion**](commands/start-discussion.md) | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation. |
-| [**/start-specification**](commands/start-specification.md) | Start a specification session from an existing discussion. Validates and refines discussion content into a standalone specification. |
-| [**/start-planning**](commands/start-planning.md) | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (markdown, Linear, Backlog.md, Beads). |
-| [**/interview**](commands/interview.md) | Shift into focused questioning mode during research or discussion. Probes ideas with non-obvious questions, challenges assumptions, and surfaces concerns. |
+| Command                                                       | Description                                                                                                                                                                                                |
+|---------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [**/start-research**](commands/start-research.md)             | Begin research exploration. For early-stage ideas, feasibility checks, and broad exploration before formal discussion.                                                                                     |
+| [**/start-discussion**](commands/start-discussion.md)         | Begin a new technical discussion. Gathers topic, context, background information, and relevant codebase areas before starting documentation.                                                               |
+| [**/start-specification**](commands/start-specification.md)   | Start a specification session from an existing discussion. Validates and refines discussion content into a standalone specification.                                                                       |
+| [**/start-planning**](commands/start-planning.md)             | Start a planning session from an existing specification. Creates implementation plans with phases, tasks, and acceptance criteria. Supports multiple output formats (markdown, Linear, Backlog.md, Beads). |
+| [**/start-implementation**](commands/start-implementation.md) | Start implementing a plan. Executes tasks via strict TDD, committing after each passing test.                                                                                                              |
+| [**/interview**](commands/interview.md)                       | Shift into focused questioning mode during research or discussion. Probes ideas with non-obvious questions, challenges assumptions, and surfaces concerns.                                                 |
 
 ## Agents
 
 Subagents that skills can spawn for parallel task execution.
 
-| Agent | Used By | Description |
-|-------|---------|-------------|
+| Agent                                          | Used By          | Description                                                                                                                                                                                              |
+|------------------------------------------------|------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
 | [**chain-verifier**](agents/chain-verifier.md) | technical-review | Verifies a single plan task was implemented correctly. Checks implementation, tests (not under/over-tested), and code quality. Multiple chain-verifiers run in parallel to verify ALL tasks efficiently. |
 
 ## Requirements

package/commands/start-implementation.md

@@ -59,6 +59,7 @@ After the user selects a plan:
 2. If it exists, note the file location for the skill handoff
 3. If missing, ask: "Are there any environment setup instructions I should follow?"
    - If the user provides instructions, save them to `docs/workflow/environment-setup.md`, commit and push to Git
+   - If the user says no, create `docs/workflow/environment-setup.md` with "No special setup required." and commit. This prevents asking again in future sessions.
    - See `skills/technical-implementation/references/environment-setup.md` for format guidance
 
 ## Step 4: Ask About Scope

package/commands/start-planning.md

@@ -62,7 +62,7 @@ Ask: **Which specification would you like to plan?**
 
 Ask: **Where should this plan live?**
 
-Load **[output-formats.md](skills/technical-planning/references/output-formats.md)** and present the available formats to help the user choose. Then load the corresponding output adapter for that format's setup requirements.
+Load **[output-formats.md](../skills/technical-planning/references/output-formats.md)** and present the available formats to help the user choose. Then load the corresponding output adapter for that format's setup requirements.
 
 ## Step 5: Gather Additional Context
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leeovery/claude-technical-workflows",
-  "version": "2.0.6",
+  "version": "2.0.8",
   "description": "Technical workflow skills & commands for Claude Code",
   "license": "MIT",
   "author": "Lee Overy <me@leeovery.com>",

package/skills/technical-implementation/SKILL.md

@@ -39,7 +39,8 @@ 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 exists and states "No special setup required", skip to step 2
+   - If exists with instructions, follow the setup before proceeding
    - If missing, ask: "Are there any environment setup instructions I should follow?"
 
    See **[environment-setup.md](references/environment-setup.md)** for details.

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

@@ -44,6 +44,12 @@ 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?"
 
+If they say no setup is needed, create `docs/workflow/environment-setup.md` with "No special setup required." and commit. This prevents asking the same question in future sessions.
+
+## No Setup Required
+
+If the environment setup document contains only "No special setup required" (or similar), skip environment setup and proceed directly to reading the plan.
+
 ## 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:

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

@@ -6,6 +6,8 @@
 
 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.
 
+**IMPORTANT**: Only offer formats listed below. Do not invent or suggest formats that don't have corresponding `output-*.md` files in this directory.
+
 ## Available Formats
 
 - **[Local Markdown](output-local-markdown.md)** - Single markdown file, no external tools