# PRISM Workflow Hooks

Python-based Claude Code hooks that enforce story file updates throughout the core-development lifecycle workflow.

## Overview

These hooks ensure:
1. **Story Context is Established**: All workflow commands work on the correct story file
2. **Story Files are Updated**: Required sections are present based on workflow phase
3. **Workflow Integrity**: Steps execute in proper order with proper validation

## Hook Files

### Python Scripts

| Hook | Type | Purpose | Blocks? |
|------|------|---------|---------|
| `enforce-story-context.py` | PreToolUse | Ensure workflow commands have active story | ✅ Yes |
| `track-current-story.py` | PostToolUse | Capture story file as current context | ❌ No |
| `validate-story-updates.py` | PostToolUse | Validate story file updates | ❌ No (warns) |
| `validate-required-sections.py` | PostToolUse | Verify all required PRISM sections | ✅ Yes (critical errors) |

### Configuration

`hooks.json` - Hook event configuration for Claude Code

## How It Works

### Story Context Flow

```
1. *draft command creates story in docs/stories/
   ↓
2. track-current-story.py captures path → .prism-current-story.txt
   ↓
3. All workflow commands check enforce-story-context.py
   ↓
4. Commands blocked if no active story ❌
   OR
5. Commands proceed with story context ✅
```

### Validation Flow

```
Story file Edit/Write
   ↓
validate-story-updates.py
   - Warns if editing non-current story
   - Checks for required base sections
   ↓
validate-required-sections.py
   - Comprehensive section validation
   - Blocks if critical sections missing
```

## Generated Files

### `.prism-current-story.txt`
Contains the path to the currently active story file.

**Example**: `docs/stories/platform-1.auth-improvements-2.md`

**Created by**: `track-current-story.py`

### `.prism-workflow.log`
Audit log of all workflow events.

**Format**: `TIMESTAMP | EVENT_TYPE | DETAILS`

**Example**:
```
2025-10-24T15:30:45Z | STORY_ACTIVE | docs/stories/epic-1.story-2.md
2025-10-24T15:31:12Z | COMMAND | develop-story | docs/stories/epic-1.story-2.md
2025-10-24T15:32:08Z | STORY_UPDATED | docs/stories/epic-1.story-2.md
2025-10-24T15:32:09Z | VALIDATION | PASS | docs/stories/epic-1.story-2.md | In Progress
```

## Workflow Integration

### Core Development Cycle Steps

1. **draft_story** (`*draft`)
   - Creates story file in `docs/stories/`
   - **Hook**: `track-current-story.py` captures file path
   - **Result**: Story context established

2. **risk_assessment** (`*risk {story}`)
   - **Hook**: `enforce-story-context.py` verifies story exists

3. **test_design** (`*design {story}`)
   - **Hook**: `enforce-story-context.py` verifies story exists

4. **validate_story** (`*validate-story-draft {story}`)
   - **Hook**: `enforce-story-context.py` verifies story exists

5. **implement_tasks** (`*develop-story`)
   - **Hook**: `enforce-story-context.py` verifies story exists
   - **Hook**: `validate-story-updates.py` validates Dev Agent Record
   - **Hook**: `validate-required-sections.py` ensures required sections

6. **qa_review** (`*review {story}`)
   - **Hook**: `enforce-story-context.py` verifies story exists
   - **Hook**: `validate-story-updates.py` validates QA Results section

7. **address_review_issues** (`*review-qa`)
   - **Hook**: `enforce-story-context.py` verifies story exists

8. **update_gate** (`*gate {story}`)
   - **Hook**: `enforce-story-context.py` verifies story exists

## Error Messages

### No Active Story

```
❌ ERROR: Command 'develop-story' requires an active story

   No current story found in workflow context

   REQUIRED: Draft a story first using the core-development-cycle workflow:
     1. Run: *planning-review (optional)
     2. Run: *draft

   The draft command will create a story file and establish story context.
```

### Missing Required Sections

```
❌ VALIDATION FAILED: Story file has critical errors

   ERROR: Missing required section for In Progress status: ## Dev Agent Record

   Story file: docs/stories/epic-1.story-2.md
   Status: In Progress

   REQUIRED: Fix these errors before proceeding with workflow
```

## Dependencies

- **Python 3.6+**: All hooks are Python scripts
- **json**: Standard library (built-in)
- **pathlib**: Standard library (built-in)
- **re**: Standard library (built-in)

No external packages required!

## Installation

The hooks are automatically loaded by Claude Code from the `hooks/` directory when the plugin is installed.

## Troubleshooting

### Hook Not Running

**Check**:
1. `hooks.json` is valid JSON
2. Python 3 is in PATH: `python --version`
3. Matcher pattern matches tool being used

### Hook Blocking Unexpectedly

**Debug**:
1. Check `.prism-workflow.log` for error messages
2. Run hook manually:
   ```bash
   echo '{"tool_input":{"command":"*develop-story"}}' | python hooks/enforce-story-context.py
   ```
3. Check if `.prism-current-story.txt` exists and contains valid path

### Story Context Lost

**Fix**:
1. Verify story file exists in `docs/stories/`
2. Manually set current story:
   ```bash
   echo "docs/stories/your-story.md" > .prism-current-story.txt
   ```
3. Or run `*draft` to create new story

## Version

**PRISM Hook System Version**: 1.0.0

**Compatible with**:
- PRISM Core Development Cycle: v1.3.0+
- Claude Code: Latest (hooks feature released June 2025)

## Support

For issues or questions:
1. Check `.prism-workflow.log` for detailed event history
2. Review hook output in Claude Code console
3. File issue at PRISM repository

---

**Last Updated**: 2025-10-24