feat(workflow): Enforce workflow classification via CLAUDE.md (#1686)

* feat(workflow): Enforce workflow classification via CLAUDE.md (#1680)

Problem: Claude consistently ignored workflow instructions even when
explicitly invoked with /ultrathink. Root cause was 4 levels of
indirection (command -> skill -> skill -> workflow) causing context loss.

Solution:
- Add "MANDATORY: Workflow Selection" section to CLAUDE.md
- Create Q&A_WORKFLOW.md (3 steps) for simple questions
- Classify ALL tasks: Q&A, Investigation, or Default workflow
- Deprecate /ultrathink command, ultrathink-orchestrator, default-workflow skills
- Remove all /ultrathink references from CLAUDE.md

Benefits:
- Direct workflow enforcement without skill indirection
- "Always use a workflow" is now enforceable (Q&A for simple questions)
- Workflow classification happens in 3 seconds before any action
- Backward compatibility: deprecated commands still work

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

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

* docs: Add workflow enforcement discovery to DISCOVERIES.md

Documents the root cause (4 levels of indirection) and solution
for issue #1680 where Claude ignored workflow instructions.

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

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

* feat(workflow): Add runtime enforcement for DEFAULT_WORKFLOW steps

Implements Issue #1680 - Prevents agents from skipping workflow steps by
enforcing step completion at runtime via hooks.

## Problem
Agents repeatedly skipped workflow steps (Steps 10, 16, 17, 21) despite
Step 0 requiring explicit acknowledgement of all 22 steps. The existing
workflow_tracker.py only logged but never enforced completion.

## Solution
Three-module architecture with fail-open design:

1. **workflow_state.py**: State machine tracking step completion
   - Persists to .claude/runtime/workflow/state_{session_id}.json
   - Atomic file writes (temp + rename)
   - Tracks mandatory steps: {0, 10, 16, 17, 21}

2. **todo_interceptor.py**: Monitors TodoWrite for step tracking
   - Detects "Step N:" patterns in todo content
   - Validates Step 0 compliance (22 todos required)
   - Never blocks - only updates state and warns

3. **workflow_gate.py**: Gates stop hook completion
   - Requires Step 21 completion before task ends
   - Returns continuation prompt for incomplete workflows
   - Fail-open on errors (allows stop rather than blocking)

## Tests
- 56 unit tests covering all three modules
- TDD approach with testing pyramid (60/30/10)
- E2E integration tests verify complete flow

Closes #1680

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

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

* fix(workflow): Address review feedback for enforcement module

- Simplified regex patterns: consolidated 4 patterns into 1 tolerant pattern
- Added MAX_STEP_NUMBER constant to prevent garbage matches
- Fixed deprecated datetime.utcnow() → datetime.now(timezone.utc)
- Added MAX_DISPLAYED_STEPS constant for continuation prompts

All 56 workflow enforcement tests passing.

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

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

* docs(workflow): Add runtime enforcement section to docs

Explains the three-module enforcement system, mandatory steps,
fail-open design, and state file persistence.

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

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

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Ubuntu <azureuser@azlin-vm-1764012546.ftnmxvem3frujn3lepas045p5c.xx.internal.cloudapp.net>

Author: 4 people

.claude/commands/amplihack/ultrathink.md

@@ -2,6 +2,14 @@
 name: ultrathink
 version: 1.0.0
 description: Deep analysis mode with multi-agent orchestration
+DEPRECATED: true
+deprecation_notice: |
+  This command is DEPRECATED as of 2025-11-26.
+  Workflow selection is now handled directly in CLAUDE.md via the
+  "MANDATORY: Workflow Selection" section. Use workflow classification
+  directly instead of invoking /ultrathink.
+  For backward compatibility, this command still works but routes to
+  workflow classification in CLAUDE.md.
 triggers:
   - "Complex multi-step task"
   - "Need deep analysis"
@@ -27,7 +35,7 @@ invokes:
 ## Purpose
 
 Deep analysis mode for complex tasks. Invokes workflow skills (default-workflow or investigation-workflow) based on task type, with automatic fallback to markdown workflows if skills are not yet available.
-You MUST use one of the workflow skills - either default-workflow or investigation-workflow or both or its possible the user could pass in additional workflow skills like cascade or debate. 
+You MUST use one of the workflow skills - either default-workflow or investigation-workflow or both or its possible the user could pass in additional workflow skills like cascade or debate.
 
 ## EXECUTION INSTRUCTIONS FOR CLAUDE
 
@@ -48,26 +56,27 @@ Execute this exact sequence for the task: `{TASK_DESCRIPTION}`
      - Development: @.claude/workflow/DEFAULT_WORKFLOW.md
 3. ALWAYS **Create a comprehensive todo list** using TodoWrite tool that includes all workflow steps/phases
 4. ALWAYS **Execute each step systematically**, marking todos as in_progress and completed
-   
-THERE IS NO VALUE in SKIPPING STEPS - DO NOT TAKE SHORTCUTS. 
+
+THERE IS NO VALUE in SKIPPING STEPS - DO NOT TAKE SHORTCUTS.
 
 - **For Each Workflow Step**:
-   - Mark step as in_progress in TodoWrite
-   - Break down the step into smaller tasks if needed
-   - Read the step requirements from workflow
-   - Invoke specified agents via Task tool
-   - Log decisions made
-   - Mark step as completed
-   - No steps are optional - all steps must be followed in sequence. 
+  - Mark step as in_progress in TodoWrite
+  - Break down the step into smaller tasks if needed
+  - Read the step requirements from workflow
+  - Invoke specified agents via Task tool
+  - Log decisions made
+  - Mark step as completed
+  - No steps are optional - all steps must be followed in sequence.
 - **Agent Invocation Pattern**:
 
-   ```
-   For step requiring "**Use** architect agent":
-   → Invoke Task(subagent_type="architect", prompt="[step requirements + task context]")
+  ```
+  For step requiring "**Use** architect agent":
+  → Invoke Task(subagent_type="architect", prompt="[step requirements + task context]")
+
+  For step requiring multiple agents:
+  → Invoke multiple Task calls in parallel
+  ```
 
-   For step requiring multiple agents:
-   → Invoke multiple Task calls in parallel
-   ```
 ### Agent Orchestration
 
 #### When to Use Sequential
@@ -84,16 +93,16 @@ THERE IS NO VALUE in SKIPPING STEPS - DO NOT TAKE SHORTCUTS.
 
 - **Decision Logging**:
 
-   After each major decision, append to DECISIONS.md:
-   - What was decided
-   - Why this approach
-   - Alternatives considered
+  After each major decision, append to DECISIONS.md:
+  - What was decided
+  - Why this approach
+  - Alternatives considered
 
 - **Mandatory Cleanup**:
-   Always end with Task(subagent_type="cleanup")
-  
+  Always end with Task(subagent_type="cleanup")
+
 5. **Use the specified agents** for each step (marked with "**Use**" or "**Always use**")
-6. **MANDATORY: Enforce all steps. 
+6. \*\*MANDATORY: Enforce all steps.
 7. **Track decisions** by creating and writing important decisions to `.claude/runtime/logs/<session_timestamp>/DECISIONS.md`
 8. **End with cleanup agent** (development) or knowledge capture (investigation)
 
@@ -178,7 +187,7 @@ In these cases, pause development workflow at Step 4, run full INVESTIGATION_WOR
 
 # ALWAYS PICK A WORKFLOW OR FOLLOW THE ONE THE USER TOLD YOU TO USE
 
-YOU MAY NOT SKIP STEPS in the workflow. 
+YOU MAY NOT SKIP STEPS in the workflow.
 UltraThink enhances the workflow with deep multi-agent analysis while respecting user customizations.
 
 Remember: Ultra-thinking means thorough analysis before action, followed by ruthless cleanup.

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

@@ -2,10 +2,13 @@
 name: default-workflow
 version: 1.0.0
 description: Development workflow for features, bugs, refactoring. Auto-activates for multi-file implementations.
-auto_activates:
-  - "implement feature spanning multiple files"
-  - "complex integration across components"
-  - "refactor affecting 5+ files"
+DEPRECATED: true
+deprecation_notice: |
+  This skill is DEPRECATED as of 2025-11-26.
+  Workflow selection is now handled directly in CLAUDE.md via the
+  "MANDATORY: Workflow Selection" section. Read the workflow file
+  directly instead of using this skill wrapper.
+auto_activates: []
 explicit_triggers:
   - /ultrathink
   - /amplihack:default-workflow

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

@@ -2,7 +2,13 @@
 name: ultrathink-orchestrator
 version: 1.0.0
 description: Auto-invokes ultrathink workflow for any work request (default orchestrator)
-auto_activate: true
+DEPRECATED: true
+deprecation_notice: |
+  This skill is DEPRECATED as of 2025-11-26.
+  Workflow selection is now handled directly in CLAUDE.md via the
+  "MANDATORY: Workflow Selection" section. The indirection through
+  skills has been eliminated to ensure consistent workflow enforcement.
+auto_activate: false
 priority: 5
 triggers:
   - "implement"