# Workflow Instructions

> The complete workflow that Claude MUST follow for all coding tasks.
> This is the source of truth for HOW to work on this project.

---

## Hook Integration

Hooks automatically trigger workflow phases:

| Hook | Triggers On | Phase Triggered |
|------|-------------|-----------------|
| `session-check.sh` | Every user message | ANALYZE (init, blueprint check) |
| `post-edit.sh` | After Write/Edit | VERIFY (auto-runs npm run verify) |
| `pre-commit-check.sh` | Before git commit | COMMIT gate (blocks if fails) |

**State tracked in:** `.claude/.autoworkflow/`

| File | Purpose | Max |
|------|---------|-----|
| `phase` | Current workflow phase | - |
| `task-type` | Classified task type | - |
| `verify-iteration` | Verify loop count | 10 |
| `audit-iteration` | Audit loop count | 5 |
| `plan-approved` | User approval status | - |

---

## Workflow Phases

```
1. ANALYZE   → Read files, understand context
2. PLAN      → Design approach, show suggestions
3. CONFIRM   → Wait for user approval
4. IMPLEMENT → Make changes (after approval only)
5. VERIFY    → npm run verify (typecheck + lint)
6. FIX       → If errors: fix → verify → repeat
7. AUDIT     → npm run audit:ui + audit:cycles
8. COMMIT    → Conventional commit (after approval)
9. UPDATE    → Update BLUEPRINT.md (if new feature/route/api)
```

---

## Phase 1: ANALYZE

**Purpose:** Understand what exists before making changes

**Actions:**
1. Read `instructions/AI_RULES.md` for project standards
2. Read `instructions/BLUEPRINT.md` for requirements
3. Read relevant source files
4. Identify affected files and patterns
5. Note existing conventions to follow

**Output:**
```
## Analysis

**Request:** [what user asked for]
**Affected files:** [list]
**Existing patterns:** [observations]
**Requirements from BLUEPRINT:** [relevant items]
```

**Gate:** `analyze_gate` - Must have read relevant files

---

## Phase 2: PLAN

**Purpose:** Design the implementation approach

**Actions:**
1. Break task into specific changes
2. List files to create/modify
3. Identify potential issues
4. Prepare suggestions (for features)

**Output:**
```
## Plan

**Task:** [description]

### Proposed Changes
1. [Change 1] - [file]
2. [Change 2] - [file]
3. [Change 3] - [file]

### Suggestions (for features)

🔴 **Required:**
- [ ] [Must-have item 1]
- [ ] [Must-have item 2]

🟡 **Recommended:**
- [ ] [Should-have item 1]
- [ ] [Should-have item 2]

🟢 **Optional:**
- [ ] [Nice-to-have item 1]

**Should I proceed?**
**Which suggestions to include?** (all/required/none/1,2,4)
```

**When to show suggestions:**
| Task Type | Show Suggestions? |
|-----------|-------------------|
| New feature | Always |
| New component | Always |
| New page/route | Always |
| Bug fix | Only if reveals missing handling |
| Refactor | Only if scope expands |
| Style changes | Skip |
| Config changes | Skip |

---

## Phase 3: CONFIRM

**Purpose:** Get explicit user approval before implementing

**Actions:**
1. Wait for user response
2. Parse approval or rejection
3. Note which suggestions to include
4. Proceed only with explicit approval

**Approval signals:**
- "yes", "y", "proceed", "go ahead"
- "approved", "lgtm", "looks good"
- "all" (include all suggestions)
- "required" (required suggestions only)
- "1, 3, 5" (specific suggestion numbers)

**Rejection signals:**
- "no", "wait", "hold on"
- "change [x]", questions asking for revision

**Gate:** `plan_approval_gate` - MUST have user approval

---

## Phase 4: IMPLEMENT

**Purpose:** Make the actual code changes

**Rules:**
1. Only change files mentioned in plan
2. Include approved suggestions
3. Follow patterns from AI_RULES.md
4. No TODO/FIXME comments
5. No console.log statements
6. No partial implementations
7. Complete feature fully

**Actions:**
1. Create/modify files as planned
2. Implement all approved items
3. Follow existing code patterns
4. Ensure feature is complete (UI + Backend)

**Output:**
```
## Implementation

### Changes Made
- [x] [Change 1] - [file]
- [x] [Change 2] - [file]
- [x] [Change 3] - [file]

### Suggestions Included
- [x] [Suggestion 1]
- [x] [Suggestion 3]

Proceeding to verification...
```

---

## Phase 5: VERIFY

**Purpose:** Ensure code quality before commit

**Commands:**
```bash
npm run verify
# Runs: npm run typecheck && npm run lint
```

**Actions:**
1. Run verification command
2. Parse output for errors
3. If errors → enter FIX phase
4. If clean → proceed to AUDIT (or COMMIT)

**Output (Success):**
```
## Verification

✅ **PASSED**

| Check | Status |
|-------|--------|
| TypeScript | ✅ 0 errors |
| ESLint | ✅ 0 warnings |

Proceeding to audit...
```

**Output (Failure):**
```
## Verification

❌ **FAILED**

Found 3 error(s):

1. `src/Button.tsx:15` - Property 'onClick' missing
2. `src/useAuth.ts:42` - Type mismatch
3. `src/Home.tsx:8` - Unused variable

Entering fix loop...
```

**Loop:** `verify_loop` - Repeat until pass (max 10 iterations)

---

## Phase 6: FIX

**Purpose:** Resolve verification errors

**Actions:**
1. Parse each error
2. Read error context
3. Apply fix
4. Return to VERIFY

**Output:**
```
## Fix Loop (Iteration 2/10)

**Fixing:**
- [x] `src/Button.tsx:15` - Added onClick prop
- [x] `src/useAuth.ts:42` - Fixed return type
- [x] `src/Home.tsx:8` - Removed unused import

Re-running verification...
```

**Loop:** `fix_loop` - Fix errors one by one

---

## Phase 7: AUDIT

**Purpose:** Enforce UI completeness and architecture rules

**When required:**
- New features
- New components
- Refactoring
- Performance changes

**Commands:**
```bash
npm run audit:ui       # Check orphan features
npm run audit:cycles   # Check circular deps
```

**Checks:**
1. **UI Enforcement:**
   - Every API has a UI that calls it
   - Every hook is used by a component
   - User can access every feature

2. **Circular Dependencies:**
   - No import cycles (A → B → A)

**Output (Success):**
```
## Audit

| Check | Status |
|-------|--------|
| UI Enforcement | ✅ No orphans |
| Circular Deps | ✅ No cycles |

Ready to commit.
```

**Output (Failure):**
```
## Audit

| Check | Status |
|-------|--------|
| UI Enforcement | ⛔ BLOCKED |
| Circular Deps | ✅ No cycles |

**Orphan features detected:**
- `/api/users` has no UI component
- `useAuth` hook is not used

BLOCKED: Must add UI before commit.

Building missing components...
```

**Gate:** `audit_gate` - No orphans, no cycles

---

## Phase 8: COMMIT

**Purpose:** Create a conventional commit

**Pre-commit checks:**
1. Verification passed
2. Audits passed (if applicable)
3. No TODO/FIXME in diff
4. No console.log in diff
5. Valid commit message format

**Commit message format:**
```
type(scope): description

Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
```

**Actions:**
1. Run pre-commit gate
2. Show commit preview
3. Wait for user confirmation
4. Execute commit

**Output:**
```
## Pre-Commit Check

| Check | Status |
|-------|--------|
| TypeScript | ✅ |
| ESLint | ✅ |
| UI Enforcement | ✅ |
| Circular Deps | ✅ |
| TODO/FIXME | ✅ |
| console.log | ✅ |

**Ready to commit:**
- 3 files changed
- Message: `feat(auth): add login page`

**Should I commit?**
```

**Gate:** `pre_commit_gate` - All checks must pass

---

## Blocking Rules

### Cannot Proceed Without:

| Rule | Enforcement |
|------|-------------|
| No orphan features | `npm run audit:ui` |
| No TODO/FIXME | grep in pre-commit |
| No console.log | grep in pre-commit |
| No circular deps | `npm run audit:cycles` |
| TypeScript clean | `npm run typecheck` |
| ESLint clean | `npm run lint` |
| Conventional commits | commitlint |

### Feature Completeness:
```
FEATURE IS NOT COMPLETE UNLESS:
├── Backend (API/logic)     ✓
├── Frontend (UI component) ✓  ← REQUIRED
├── Connection (UI calls API) ✓
└── Access (user can reach it) ✓
```

---

## Response Format

For every task, Claude MUST follow this format:

```
## Task: [description]

### 1. Analysis
[findings from codebase]

### 2. Plan + Suggestions
📋 **Proposed changes:**
1. [Change 1]
2. [Change 2]

💡 **Suggestions:**
🔴 Required: [list]
🟡 Recommended: [list]
🟢 Optional: [list]

**Should I proceed? Which suggestions?**

--- (wait for approval) ---

### 3. Implementation
[changes made]

### 4. Verification
[npm run verify output]
Status: ✅ PASSED / ❌ FAILED

### 5. Audit (if required)
[npm run audit:ui && audit:cycles output]
Status: ✅ PASSED / ❌ FAILED

### 6. Fix (if errors)
[fixes applied, re-verify]

### 7. Commit
**Should I commit: "type(scope): description"?**

### Summary
✅ [what was completed]
Suggestions included: [list]
```

---

## Phase 9: UPDATE BLUEPRINT

**Purpose:** Keep BLUEPRINT.md in sync with codebase

**When required:**
- New feature added
- New route created
- New API endpoint added
- Feature removed or deprecated

**Actions:**
1. Check if new feature/route/API was added
2. Prepare BLUEPRINT.md update
3. Present update to user
4. Apply after approval

**Output:**
```
## 📘 Blueprint Update

Adding to BLUEPRINT.md:

**Features:**
- [Feature name] - [description]

**Routes:**
- [path] → [Component]

**APIs:**
- [method] [endpoint] - [description]

**Should I update BLUEPRINT.md?**
```

See `system/triggers.md#on:feature_complete` for trigger details.

---

## Quick Reference

**For new features:**
```
Analyze → Plan+Suggest → Confirm → Implement → Verify → Audit → Commit → Update Blueprint
```

**For bug fixes:**
```
Analyze → Plan → Confirm → Implement → Verify → Commit
```

**For queries:**
```
Analyze → Respond
```

**VERIFY ALWAYS. AUDIT FEATURES. UPDATE BLUEPRINT. ASK BEFORE ACTIONS.**