workflow

name	workflow
description	| Use when this capability is needed.

Workflow Orchestration

🚨 MANDATORY: PLANNING-FIRST PRINCIPLE

STOP! Before implementing ANYTHING, you MUST:

1. CREATE A PLAN using TodoWrite tool:

   - List EXACT workflow commands to use
   - List SPECIFIC skills to load
   - List FILES to create/modify
   - List TESTS to run for validation
   

2. SHOW THE PLAN to the user:

   "Here's my workflow plan:
   1. /intent-audit to analyze gaps
   2. Load ux-design skill for multi-panel UI
   3. /gap to create GAP-A-XXX entries
   4. /improve --severity=critical
   5. /verify to validate fixes
   
   Shall I proceed with this plan?"
   

3. EXECUTE STEP-BY-STEP (MANDATORY):

   • Mark each todo as in_progress when starting
   • ACTUALLY RUN THE TASK COMMANDS shown in the plan
   • For "Task: intent-guardian with mode=evolve" → Use Task tool to invoke it
   • For "/gap" → Use SlashCommand tool to execute it
   • Mark as completed when done
   • Show actual command output
   • Update state in CLAUDE.md

   CRITICAL: The plan is NOT self-executing. You MUST:

   • Use Task tool for each "Task: agent-name" in the plan
   • Use SlashCommand tool for each "/command" in the plan
   • Actually create the v2.0 artifacts, not just plan to create them

NEVER jump straight into coding without a plan!

Automatic Mode Selection

The workflow AUTOMATICALLY detects project state:

# Automatic check when user requests features:
if [ -f "docs/intent/product-intent.md" ] && \
   [ -f "docs/ux/user-journeys.md" ] && \
   [ -f "docs/architecture/system-design.md" ]; then
   # ITERATION MODE (default for existing projects)
   echo "📊 Existing project detected - using iteration mode"
else
   # STANDARD MODE (for new projects)
   echo "🆕 New project - using standard workflow"
fi

No need to ask - just use the right mode:

• Existing project? → Automatically iterate (preserve 80-90%)
• New project? → Automatically create from scratch
• User wants complete redesign? → They'll explicitly say "redesign" or "start over"
• Preserves 80-90% of existing functionality
• Extends rather than replaces documentation
• Implements only what changed
• Ensures backward compatibility

Should I create an iteration plan? [Y/n]

**User can override but explain consequences:**

⚠️ Standard mode will redesign from scratch

• May break existing features
• Will take significantly longer
• Could disrupt user workflows

Are you sure you want standard mode? [y/N]

### Planning Verification Checklist

Before proceeding with ANY implementation, verify:

- [ ] TodoWrite plan created with specific workflow steps?
- [ ] Plan shown to user for approval?
- [ ] Each step maps to a workflow command or skill?
- [ ] State tracking configured in CLAUDE.md?
- [ ] Tests identified for validation?
- [ ] No direct code writing without workflow commands?

**If any item unchecked → STOP and create proper plan first!**

## CRITICAL: Real Validation Required

**YOU HAVE THE BASH TOOL. USE IT.**

This workflow ONLY works if you:
1. **Run actual tests** - Use Bash tool to execute `npm test`
2. **Start actual servers** - Use Bash tool to run `npm run dev`
3. **Check actual results** - Show real output, not assumptions
4. **Fail when broken** - If tests fail, say so

**NEVER** say:
- "Tests would pass"
- "Should work"
- "Implementation successful"

**ALWAYS** say:
- "Running tests now..." [then actually run them]
- "Test results: [actual output]"
- "Tests failed with: [actual error]"

## Overview

This skill provides orchestration logic for greenfield and brownfield development workflows. Claude automatically loads this skill when managing project phases.

## 🔄 ITERATION WORKFLOW (Most Common - Enhancing Existing Projects)

**CRITICAL: When adding features to existing projects, ALWAYS show this plan:**

```markdown
# Iteration Plan: [Your Enhancement]

## 📊 DETECTED STATE
✓ Existing L1 artifacts found
✓ Using ITERATION mode

## 🚨 PHASE 1: REGENERATE L1 ARTIFACTS (EXECUTE THESE TASKS!)
### 1.1 Intent v2.0
- Task: intent-guardian --evolve
- Creates: /docs/intent/product-intent-v2.0.md
- **ACTION: Use Task tool with subagent_type="general-purpose" and prompt="Load the intent-guardian skill and use it in EVOLVE mode to create product-intent-v2.0.md"**

### 1.2 UX v2.0
- Task: ux-architect --evolve
- Creates: /docs/ux/user-journeys-v2.0.md
- **ACTION: Use Task tool with subagent_type="general-purpose" and prompt="Load the ux-design skill and use it in EVOLVE mode to create user-journeys-v2.0.md"**

### 1.3 Architecture v2.0
- Task: agentic-architect --evolve
- Creates: /docs/architecture/system-design-v2.0.md
- **ACTION: Use Task tool with subagent_type="general-purpose" and prompt="Load the architecture skill and use it in EVOLVE mode to create system-design-v2.0.md"**

## PHASE 2: IMPLEMENTATION
[Rest of plan...]

User should NEVER have to ask if L1 artifacts will be updated!

📌 AFTER SHOWING THE PLAN

CRITICAL: After user approves the plan, you MUST execute it:

User: "yes" or "proceed" or "go ahead"

Claude: "Starting Phase 1: Regenerating L1 artifacts..."

[ACTUALLY USE TASK TOOL HERE - Don't just say you will!]

Task tool invocation #1:
- subagent_type: "general-purpose"
- prompt: "Load intent-guardian skill, use EVOLVE mode to update product-intent.md to v2.0 with [specific enhancement]"

[WAIT FOR TASK TO COMPLETE]

✓ Created product-intent-v2.0.md

Task tool invocation #2:
- subagent_type: "general-purpose"
- prompt: "Load ux-design skill, use EVOLVE mode to update user-journeys.md to v2.0 with [specific enhancement]"

[CONTINUE WITH ALL TASKS IN PLAN]

Common mistake: Showing the plan but not executing it. The plan is a TODO list, not self-executing code!

L1 Planning Flow (Greenfield)

Intent → UX → Architecture → Planning → L2

Phase 1: Intent

When: Starting new project or capturing requirements

Actions:

1. Load skill: intent-guardian
2. Create /docs/intent/product-intent.md
3. Capture promises with criticality levels (CORE/IMPORTANT/NICE_TO_HAVE)
4. Define acceptance criteria for each promise
5. Update CLAUDE.md state: l1.intent.status = complete

Continue to: UX Design

Phase 2: UX Design

When: After intent complete

Actions:

1. Load skill: ux-design
2. Create /docs/ux/user-journeys.md
3. Apply design principles (Fitts's Law, Hick's Law, etc.)
4. Define screen specifications
5. Update CLAUDE.md state: l1.ux.status = complete

Continue to: Architecture

Phase 3: Architecture

When: After UX complete

Actions:

1. Load skill: architecture
2. Create /docs/architecture/system-design.md
3. Map promises to modules
4. Define tech stack and patterns
5. Update CLAUDE.md state: l1.architecture.status = complete

Continue to: Planning

Phase 4: Planning

When: After architecture complete

Actions:

1. Load skill: planning
2. Create /docs/plans/implementation-order.md
3. Create feature plans in /docs/plans/features/
4. Define build order and dependencies
5. Update CLAUDE.md state: l1.planning.status = complete

Continue to: L2 Building

---

L2 Building Flow (Per Feature)

Backend → (review) → Frontend → (review) → Tests → Validate → Complete

Step 1: Backend

Actions:

1. Load skill: backend
2. Implement APIs, database, services
3. Automatic: Code review reminder via hook
4. CRITICAL: Run ACTUAL backend tests using Bash tool:

   npm test -- backend/
   # Show REAL output, not hypothetical
   

5. Only update state if tests ACTUALLY pass: l2.features[name].backend = complete

Continue to: Frontend

Step 2: Frontend

Actions:

1. Load skill: frontend
2. Implement UI components (apply design principles from ux-design skill)
3. Automatic: Code review reminder via hook
4. Run frontend tests
5. Update state: l2.features[name].frontend = complete

Continue to: Testing

Step 3: Testing

Actions:

1. Load skill: testing
2. Write comprehensive test coverage
3. Run full test suite
4. Automatic: Quality gate reminder via hook
5. Update state: l2.features[name].tests = complete

Continue to: Validation

Step 4: Validation

Actions:

1. Load skill: validation
2. Validate promises are KEPT (not just tests passing)
3. Check acceptance criteria
4. If PARTIAL/FAILED: Create remediation tasks
5. If VALIDATED: Mark feature complete

Continue to: Next feature or project complete

---

Iteration Flow (Evolving Systems)

NEW! For v2.0+ enhancements to existing systems

When to Use Iteration Flow

Triggered when:

• User says "enhance with [X]", "add [major feature]", "redesign [area]"
• Significant evolution beyond simple bug fixes
• Need to maintain backward compatibility
• Want to preserve existing functionality

Iteration Workflow Steps

Load State → Analyze Impact → Evolve Docs → Delta Analysis → Incremental Implementation

Step 1: Load Current State

# Load existing documentation versions
cat docs/intent/product-intent.md        # v1.0 promises
cat docs/ux/user-journeys.md            # v1.0 journeys
cat docs/architecture/system-design.md   # v1.0 architecture
grep "features:" CLAUDE.md              # Completed features

Step 2: Iteration Analysis

Analyze enhancement compatibility:

1. Will it break existing promises?
2. Does it conflict with current UX?
3. Can architecture support it?
4. What's the integration effort?

Output: Compatibility report with risk assessment

Step 3: Evolutionary Design

Create v2.0 documents that EXTEND v1.0:

# Intent v2.0
## Existing Promises (v1.0)
[Keep all existing promises]

## New Promises (v2.0)
[Add new promises]

## Evolution Notes
- What changed and why
- Backward compatibility notes

Same pattern for UX v2.0 and Architecture v2.0

Step 4: Delta Analysis

Identify precise changes:

delta_analysis:
  new_promises: [P8, P9]
  modified_journeys: [checkout, profile]
  new_components: [ai_service, suggestion_engine]
  deprecated: []
  preserved: 85%
  breaking_changes: none

Step 5: Gap-Based Implementation

Create iteration gaps (GAP-I-XXX):

/gap --iteration "v1.0 to v2.0"
# Creates GAP-I-001, GAP-I-002, etc.

Implement incrementally:

/improve GAP-I-001  # Highest priority first
/verify GAP-I-001   # Verify no regression

Step 6: Validation

Ensure both old AND new work:

1. All v1.0 tests still pass
2. New v2.0 features validated
3. No performance regression
4. User journeys intact

State Tracking for Iterations

workflow:
  mode: iteration
  version: "1.0 → 2.0"

iteration:
  base_version: "1.0"
  target_version: "2.0"
  compatibility: maintained
  preserved_percentage: 85
  new_promises: [P8, P9]
  iteration_gaps: [GAP-I-001, GAP-I-002]
  status: in_progress

Brownfield Flow (Existing Code)

First Session

Analyze → Infer State → Ask User → Continue

Actions:

1. Load skill: brownfield
2. Scan project structure and code
3. Infer: tech stack, features, promises, test coverage
4. Create [INFERRED] documentation
5. Ask user: What would you like to do?
   • Add feature → change-analysis skill → L2 flow
   • Improve code → gap-analysis skill → Fix gaps
   • Fix bug → debugging skill → Fix + test

---

Change Request Handling

Triggered when: User says "add [feature]", "change [thing]", "also need"

Actions:

1. Load skill: change-analysis
2. Analyze impact on existing:
   • Intent (new promises?)
   • UX (new journeys?)
   • Architecture (new modules?)
   • Plans (new tasks?)
3. Estimate effort and complexity
4. Present analysis to user
5. On confirmation: Update docs and continue to L2

---

Issue Response

Backend/General Issues

Triggered when: "error", "crash", "bug", "broken", "doesn't work"

Actions:

1. Invoke debugger subagent (isolated context)
2. Wait for diagnosis and fix
3. Automatic: Code review reminder via hook
4. Verify fix with tests

UI Issues

Triggered when: "page doesn't work", "button broken", "UI issue", "layout wrong"

Actions:

1. Invoke ui-debugger subagent (isolated context + browser access)
2. Wait for diagnosis and fix
3. Automatic: Code review reminder via hook
4. Verify fix with tests

---

Quality Gates (Automatic via Hooks)

Quality reminders are injected automatically by hooks:

After Code Changes

PostToolUse hook detects Write/Edit and reminds to run code-reviewer subagent

Before Marking Complete

Stop hook reminds to check:

• Tests passing?
• Code reviewed?
• State updated?

---

State Management

CRITICAL: State Must Be Persisted

Every workflow action MUST update state in CLAUDE.md immediately:

1. Read current state first:

   grep -A 20 "workflow:" CLAUDE.md
   

2. Update after EVERY action:

   • Command executed → Update state
   • Skill loaded → Update state
   • Test run → Update state with results
   • Feature completed → Update state

3. State includes execution details:

   workflow:
     phase: L1|L2
     status: in_progress|paused|complete
     last_command: "/gap"
     last_command_output: "Created 5 gaps"
     pending_steps:
       - "/improve --severity=critical"
       - "/verify"
   

Always update CLAUDE.md state after significant actions:

workflow:
  phase: L1|L2
  status: in_progress|paused|complete

l1:
  intent: {status: pending|in_progress|complete}
  ux: {status: pending|in_progress|complete}
  architecture: {status: pending|in_progress|complete}
  planning: {status: pending|in_progress|complete}

l2:
  current_feature: string
  features:
    feature_name:
      backend: pending|in_progress|complete
      frontend: pending|in_progress|complete
      tests: pending|in_progress|complete
      validation: pending|in_progress|complete

---

Available Skills Reference

Load these skills as needed:

Skill	Use For
intent-guardian	Capturing user promises and requirements
ux-design	Designing user experience and applying design principles
architecture	System design and module architecture
planning	Creating implementation plans and build order
backend	Implementing APIs, database, services
frontend	Implementing UI components with design principles
testing	Writing comprehensive test coverage
validation	Validating promises are kept (acceptance testing)
brownfield	Analyzing existing codebases
change-analysis	Assessing impact of change requests
gap-analysis	Finding issues in existing code
debugging	General debugging strategies
code-quality	Code review criteria and standards
project-ops	Project setup, sync, docs, verification

---

Available Subagents Reference

Invoke these for isolated tasks:

Subagent	Use For
code-reviewer	Read-only code review (isolated context)
debugger	Isolated debugging sessions
ui-debugger	UI debugging with browser automation

---

Converted and distributed by TomeVault — claim your Tome and manage your conversions.