201 lines
5.5 KiB
Markdown
201 lines
5.5 KiB
Markdown
# 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
|