refactor: Major restructuring of DEFAULT_WORKFLOW.md for documentation-first development (#1591)

* refactor: Major restructuring of DEFAULT_WORKFLOW.md for documentation-first development

This commit introduces revolutionary changes to the default workflow, shifting from
a numbered step-based approach to a more flexible, documentation-first methodology.

## Key Structural Changes

### 1. Documentation-First Approach (NEW)
- Added "Retcon Documentation Writing" step - documentation is written BEFORE implementation
- Documentation acts as specification for the feature "as it should be"
- Architect reviews documentation to align with vision before coding begins

### 2. True Test-Driven Development
- Separated TDD into dedicated step AFTER documentation
- Tests written based on documentation, before implementation
- Clearer separation between design, testing, and implementation phases

### 3. Early Review Integration
- Added "Review pass before commit" - review happens BEFORE committing
- Added "Incorporate any review feedback" - immediate feedback loop before commit
- Shifted from post-PR review to pre-commit review for earlier quality gates

### 4. Flexible Step Structure
- Removed rigid step numbering (Step 1, Step 2, etc.) from headers
- Headers now use descriptive names only
- Allows for easier customization and step insertion

### 5. Enhanced Agent Orchestration
- Added zen-architect agent consultation for philosophy alignment
- Added documentation-writer agent for retcon documentation
- Emphasized use of Skills() tool throughout workflow
- More explicit handoffs between agents

### 6. Outside-In Testing Emphasis
- Added explicit guidance: "Test like a user would use the feature - outside-in"
- Emphasis on end-to-end testing, not just unit tests
- Test results documented for PR description

### 7. Workflow Timing Simplification
- Removed specific timing requirements ("Within 24 hours", "Within 48 hours")
- More autonomous, trust-based approach
- Focus on quality over arbitrary deadlines

## Process Flow Changes

**Old Flow:**
1. Requirements → 2. Issue → 3. Worktree → 4. Design+TDD → 5. Implement →
6. Refactor → 7. Tests → 8. Local Test → 9. Commit → 10. Draft PR →
11. Review PR → 12. Feedback → 13. Philosophy Check → 14. Ready → 15. Mergeable → 16. Cleanup

**New Flow:**
Prepare Workspace → Requirements → Issue → Worktree → Research & Design →
**Retcon Documentation** → **TDD Tests** → Implement → Refactor →
**Review Before Commit** → **Incorporate Feedback** → Tests & Pre-commit →
Local Testing → Commit → Draft PR → Review PR → Implement Feedback →
Philosophy Check → **Cleanup** → Ready → Mergeable

## Philosophical Improvements

1. **Documentation as Specification**: Documentation written before code provides
   clear target and prevents implementation drift

2. **Earlier Quality Gates**: Review before commit catches issues earlier in the
   development cycle

3. **True TDD**: Separating test writing from design makes TDD process clearer
   and more deliberate

4. **Flexibility**: Removing numbered steps makes workflow more adaptable to
   different project needs

5. **Agent Specialization**: More explicit agent roles and handoffs improve
   clarity and effectiveness

## Breaking Changes

- Step numbers removed from workflow headers (affects TodoWrite formatting)
- New steps added (Retcon Documentation, Review Before Commit)
- Workflow now requires documentation-writer agent
- Success criteria updated from "All 15 steps" to "All steps"

## Migration Notes

Existing workflows referencing specific step numbers may need updates. The TodoWrite
best practices section still references step numbers for tracking purposes, but the
actual workflow headers use descriptive names only.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

* refactor: Re-number workflow steps and remove hardcoded step counts

This commit adds explicit step numbering (Steps 1-21) to all workflow section
headers and removes hardcoded step counts from documentation to prevent drift.

## Changes Made

### 1. DEFAULT_WORKFLOW.md - Complete Re-numbering
- Added "Step N:" prefix to ALL workflow section headers (1-21)
- Updated frontmatter: `steps: 15` → `steps: 21`
- Fixed inconsistent numbering (old Steps 2-4 were actually steps 3-5)
- Removed example hardcoded count: "Step X of 15" → generic "which step is active"

**New Section Headers:**
- Step 1: Prepare the Workspace
- Step 2: Rewrite and Clarify Requirements
- Step 3: Create GitHub Issue
- Step 4: Setup Worktree and Branch
- Step 5: Research and Design
- Step 6: Retcon Documentation Writing (NEW section user added)
- Step 7: Test Driven Development - Writing Tests First (NEW section user added)
- Step 8: Implement the Solution
- Step 9: Refactor and Simplify
- Step 10: Review Pass Before Commit (NEW section user added)
- Step 11: Incorporate Any Review Feedback (NEW section user added)
- Step 12: Run Tests and Pre-commit Hooks
- Step 13: Mandatory Local Testing
- Step 14: Commit and Push
- Step 15: Open Pull Request as Draft
- Step 16: Review the PR
- Step 17: Implement Review Feedback
- Step 18: Philosophy Compliance Check
- Step 19: Final Cleanup and Verification
- Step 20: Convert PR to Ready for Review
- Step 21: Ensure PR is Mergeable

### 2. Removed Hardcoded Step Counts (Multiple Files)
To prevent documentation drift as workflow evolves, removed specific step counts
from references where not critical:

**Files Updated:**
- `.claude/commands/amplihack/ultrathink.md` - Removed "(15 steps)" references (3 instances)
- `.claude/skills/default-workflow/SKILL.md` - Removed "15-step" and "(Step X of 15)" (3 instances)
- `.claude/skills/ultrathink-orchestrator/SKILL.md` - Removed "(15 steps)" references (2 instances)
- `.claude/skills/ultrathink-orchestrator/README.md` - Removed "(15 steps)" and "(6 phases)" (4 instances)
- `.claude/workflow/CONSENSUS_WORKFLOW.md` - Updated to 21 steps, removed "15-Step" header
- `docs/commands/COMMAND_SELECTION_GUIDE.md` - Removed "(15 steps)" references (2 instances)

### 3. CONSENSUS_WORKFLOW.md Updates
- Updated frontmatter: `steps: 15` → `steps: 21`
- Updated description: "Enhanced 15-step workflow" → "Enhanced workflow"
- Updated success criteria: "All 15 steps" → "All steps"
- Renamed header: "The 15-Step Consensus-Augmented Workflow" → "The Consensus-Augmented Workflow"

## Why These Changes

### Problem 1: Ambiguous Ordering Without Numbers
The workflow had inconsistent numbering:
- First 2 sections had NO numbers
- Next 3 sections had WRONG numbers (Steps 2-4 were actually 3-5)
- Remaining 16 sections had NO numbers
- Total: 21 sections but only 3 were numbered

This created ambiguity about sequential order and could confuse AI models about
whether steps can be reordered.

### Problem 2: Documentation Drift
Hardcoded step counts ("15 steps", "16 steps") throughout documentation become
stale when workflow evolves. Examples:
- Workflow grew from 15→16→21 steps over time
- Each growth required hunting down all hardcoded references
- Easy to miss references, creating inconsistencies

### Solution: Explicit Numbering + Generic References
1. **Explicit step numbers in headers** make sequential order crystal clear
2. **Remove counts from docs** prevents drift (workflow file is source of truth)
3. **Only keep counts in frontmatter** where they're programmatically useful

## Breaking Changes

None. This is purely clarification - the workflow steps and their order haven't
changed, just how they're labeled.

## Migration Notes

- TodoWrite examples still reference step numbers as before
- Agents can now reliably parse "Step N:" from headers
- Workflow file remains single source of truth for step count

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

---------

Co-authored-by: Ubuntu <azureuser@amplihack2.yb0a3bvkdghunmsjr4s3fnfhra.phxx.internal.cloudapp.net>
Co-authored-by: Claude <noreply@anthropic.com>

Author: 3 people

.claude/commands/amplihack/ultrathink.md

@@ -36,8 +36,8 @@ When this command is invoked, you MUST:
    - **Investigation keywords**: investigate, explain, understand, how does, why does, analyze, research, explore, examine, study
    - **Development keywords**: implement, build, create, add feature, fix, refactor, deploy
    - **If both types detected**: Use hybrid workflow (investigation first, then development)
-   - If only investigation keywords found: Use INVESTIGATION_WORKFLOW.md (6 phases)
-   - If only development keywords found: Use DEFAULT_WORKFLOW.md (15 steps)
+   - If only investigation keywords found: Use INVESTIGATION_WORKFLOW.md
+   - If only development keywords found: Use DEFAULT_WORKFLOW.md
 2. **Invoke the appropriate workflow skill** using the Skill tool:
    - Investigation: `Skill(skill="investigation-workflow")`
    - Development: `Skill(skill="default-workflow")`
@@ -63,8 +63,8 @@ Execute this exact sequence for the task: `{TASK_DESCRIPTION}`
 1. **Initialize**:
    - Detect task type (investigation vs. development)
    - Select appropriate workflow:
-     - Investigation: investigation-workflow skill (6 phases)
-     - Development: default-workflow skill (15 steps)
+     - Investigation: investigation-workflow skill
+     - Development: default-workflow skill
    - Inform user which workflow is being used
    - Try to invoke the selected workflow skill using Skill tool
    - **FALLBACK**: If skill not found, read the markdown workflow file using Read tool:
@@ -154,7 +154,7 @@ Always use TodoWrite to:
 User: "/ultrathink implement JWT authentication"
 
 1. Detect: Development task (contains "implement")
-2. Select: default-workflow skill (15 steps)
+2. Select: default-workflow skill
 3. Try: Skill(skill="default-workflow")
 4. Fallback if needed: Read `.claude/workflow/DEFAULT_WORKFLOW.md`
 5. Begin executing workflow steps with deep analysis

.claude/skills/default-workflow/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: default-workflow
 version: 1.0.0
-description: 15-step development workflow for features, bugs, refactoring. Auto-activates for multi-file implementations.
+description: Development workflow for features, bugs, refactoring. Auto-activates for multi-file implementations.
 auto_activates:
   - "implement feature spanning multiple files"
   - "complex integration across components"
@@ -30,7 +30,7 @@ This is a thin wrapper that references the complete workflow definition stored i
 
 **Source**: `.claude/workflow/DEFAULT_WORKFLOW.md` (471+ lines)
 
-The canonical workflow contains the complete 15-step development process with all details, agent specifications, and execution guidance.
+The canonical workflow contains the complete development process with all details, agent specifications, and execution guidance.
 
 ## Execution Instructions
 
@@ -44,12 +44,12 @@ When this skill is activated, you MUST:
 
    Note: Path is relative to project root. Claude Code resolves this automatically.
 
-2. **Follow all 15 steps** exactly as specified in the canonical workflow
+2. **Follow all steps** exactly as specified in the canonical workflow
 
 3. **Use TodoWrite** to track progress through workflow steps with format:
    - `Step N: [Step Name] - [Specific Action]`
    - Example: `Step 1: Rewrite and Clarify Requirements - Use prompt-writer agent`
-   - This helps users track exactly which workflow step is active (Step X of 15)
+   - This helps users track exactly which workflow step is active
 
 4. **Invoke specialized agents** as specified in each workflow step:
    - Step 1: prompt-writer, analyzer, ambiguity agents

.claude/skills/ultrathink-orchestrator/README.md

@@ -18,21 +18,24 @@ Provide default orchestration for non-trivial development tasks by automatically
 3. Estimates task complexity (simple/moderate/complex)
 4. Asks user for confirmation before proceeding
 5. Invokes the appropriate workflow skill:
-   - **Investigation**: `investigation-workflow` skill (6 phases)
-   - **Development**: `default-workflow` skill (15 steps)
+   - **Investigation**: `investigation-workflow` skill
+   - **Development**: `default-workflow` skill
    - **Hybrid**: Both workflows sequentially
 
 ## Task Type Detection
 
 **Investigation Tasks**:
+
 - Keywords: investigate, explain, understand, how does, why does, analyze, research, explore, examine, study
 - Examples: "Investigate authentication", "Explain routing", "Understand database schema"
 
 **Development Tasks**:
+
 - Keywords: implement, build, create, add feature, fix, refactor, deploy
 - Examples: "Implement JWT auth", "Add user registration", "Fix login bug"
 
 **Hybrid Tasks**:
+
 - Contains both investigation and development keywords
 - Examples: "Investigate auth system, then add OAuth support"
 
@@ -51,12 +54,13 @@ Provide default orchestration for non-trivial development tasks by automatically
 **User**: "Add user authentication to the API"
 
 **Skill Response**:
+
 ```
 I detected a MODERATE development request: "Add user authentication to the API"
 
 Would you like me to use /ultrathink to orchestrate this work?
-- Workflow: default-workflow (15 steps)
-- Estimated scope: 6-8 files, 8 steps
+- Workflow: default-workflow
+- Estimated scope: 6-8 files
 - Time estimate: 45-60 minutes
 
 [Yes] [No] [Custom]
@@ -67,11 +71,12 @@ Would you like me to use /ultrathink to orchestrate this work?
 **User**: "Investigate how the reflection system works"
 
 **Skill Response**:
+
 ```
 I detected a MODERATE investigation request: "Investigate how the reflection system works"
 
 Would you like me to use /ultrathink to orchestrate this work?
-- Workflow: investigation-workflow (6 phases)
+- Workflow: investigation-workflow
 - Estimated scope: 10-15 files, deep analysis
 - Time estimate: 30-40 minutes
 
@@ -83,11 +88,12 @@ Would you like me to use /ultrathink to orchestrate this work?
 **User**: "Investigate auth system, then add OAuth support"
 
 **Skill Response**:
+
 ```
 I detected a COMPLEX hybrid request: "Investigate auth system, then add OAuth support"
 
 Would you like me to use /ultrathink to orchestrate this work?
-- Workflow: investigation-workflow (6 phases) → default-workflow (15 steps)
+- Workflow: investigation-workflow → default-workflow
 - Estimated scope: 15+ files, comprehensive work
 - Time estimate: 90-120 minutes
 
@@ -97,11 +103,13 @@ Would you like me to use /ultrathink to orchestrate this work?
 ## Workflow Integration
 
 **Preferred Approach** (workflow skills):
+
 - Uses `Skill(skill="default-workflow")` for development tasks
 - Uses `Skill(skill="investigation-workflow")` for investigation tasks
 - Automatic task type detection from keywords
 
 **Fallback** (if skills not available):
+
 - Reads `.claude/workflow/DEFAULT_WORKFLOW.md`
 - Reads `.claude/workflow/INVESTIGATION_WORKFLOW.md`
 - Provides same functionality via markdown workflows

.claude/skills/ultrathink-orchestrator/SKILL.md

@@ -21,7 +21,7 @@ triggers:
 
 This skill provides automatic orchestration for development and investigation tasks. It detects the task type from keywords and delegates to the appropriate workflow skill (investigation-workflow or default-workflow).
 
-Auto-activation priority is LOW (5) to allow more specific skills to match first. When activated, this orchestrator selects between investigation-workflow (6 phases) and default-workflow (15 steps) based on the user's request keywords.
+Auto-activation priority is LOW (5) to allow more specific skills to match first. When activated, this orchestrator selects between investigation-workflow and default-workflow based on the user's request keywords.
 
 This skill acts as a thin wrapper around the canonical ultrathink command, following the amplihack pattern of single-source-of-truth for command logic.
 
@@ -31,8 +31,8 @@ This skill acts as a thin wrapper around the canonical ultrathink command, follo
 
 - **Primary Command**: `.claude/commands/amplihack/ultrathink.md` (278 lines)
 - **Workflow Sources**:
-  - Development: `.claude/workflow/DEFAULT_WORKFLOW.md` (15 steps)
-  - Investigation: `.claude/workflow/INVESTIGATION_WORKFLOW.md` (6 phases)
+  - Development: `.claude/workflow/DEFAULT_WORKFLOW.md`
+  - Investigation: `.claude/workflow/INVESTIGATION_WORKFLOW.md`
 
 The canonical command contains complete task detection logic, complexity estimation, and orchestration patterns for both investigation and development workflows.
 

.claude/workflow/CONSENSUS_WORKFLOW.md

@@ -1,8 +1,8 @@
 ---
 name: CONSENSUS_WORKFLOW
 version: 1.0.0
-description: Enhanced 15-step workflow with multi-agent consensus at critical decision points
-steps: 15
+description: Enhanced workflow with multi-agent consensus at critical decision points
+steps: 21
 phases:
   - requirements-with-debate
   - design-with-consensus
@@ -11,7 +11,7 @@ phases:
   - expert-panel-review
   - final-consensus-validation
 success_criteria:
-  - "All 15 steps completed with consensus validation"
+  - "All steps completed with consensus validation"
   - "Multi-agent debate for ambiguous requirements"
   - "Expert panel approval at critical gates"
   - "N-version programming for critical code"
@@ -37,7 +37,6 @@ This workflow enhances the default coding workflow with consensus mechanisms at
 
 > **DEPRECATION WARNING**: Markdown workflows deprecated. See `docs/WORKFLOW_TO_SKILLS_MIGRATION.md`
 
-
 - Requirements are ambiguous or complex
 - Design decisions have significant architectural impact
 - Multiple valid implementation approaches exist
@@ -71,7 +70,7 @@ Use this workflow for:
 - Performance-critical components
 - Public APIs with long-term commitments
 
-## The 15-Step Consensus-Augmented Workflow
+## The Consensus-Augmented Workflow
 
 ### Step 1: Rewrite and Clarify Requirements with Consensus