Validate that an active workflow's state is consistent, complete, and ready to continue. Catches issues before they cause problems and offers to auto-fix simple issues.
/plugin marketplace add marcel-Ngan/ai-dev-team/plugin install marcel-ngan-ai-dev-team@marcel-Ngan/ai-dev-teamThis skill inherits all available tools. When active, it can use any tool Claude has access to.
Validate that an active workflow's state is consistent, complete, and ready to continue. Catches issues before they cause problems and offers to auto-fix simple issues.
Check that required files exist and are readable.
| Check | Required | Auto-Fix |
|---|---|---|
workflow/active/{name}/ folder exists | Yes | No |
workflow.md exists | Yes | No |
state.json exists and valid JSON | Yes | Create from template |
decisions.md exists | Yes | Create from template |
stories/ folder exists (dev workflows) | Yes | Create empty folder |
Check that state.json matches workflow.md.
| Check | Type | Auto-Fix |
|---|---|---|
current_step matches "Current Focus" in workflow.md | Error | No (manual review needed) |
workflow_type matches folder naming convention | Error | Update state.json |
status is valid enum | Error | No |
completed_steps count matches workflow.md checkmarks | Warning | No |
| Check | Type | Auto-Fix |
|---|---|---|
All stories in workflow.md have stories/{key}.md | Error | Create from template |
| No orphaned story files | Warning | No (may be intentional) |
| Current story has "Assignment" section | Warning | No |
| Current story has "Tests to Pass" section | Warning | No |
| Current story has "What Was Done" (if iteration > 1) | Warning | No |
| Check | Type | Auto-Fix |
|---|---|---|
pending_sync items < 10 | Warning | No (offer to sync) |
last_synced_at within last 4 hours | Warning | No (offer to sync) |
| No unresolved blockers older than 24h | Warning | No |
| Check | Type | Auto-Fix |
|---|---|---|
last_updated within last 24 hours | Warning | Update timestamp |
| Current step not stuck (same step > 5 iterations) | Warning | No |
| No gate failing > 3 times consecutively | Warning | No |
| Check | Type | Auto-Fix |
|---|---|---|
| Story status in Jira matches local state | Error | Offer to update |
| Assignee matches expected | Warning | No |
| Sprint matches workflow context | Warning | No |
┌─────────────────────────────────────────────────────────────────┐
│ VALIDATION PROCESS │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────┐
│ 1. Find Active │
│ Workflow │
└────────┬────────┘
│
┌──────────────┴──────────────┐
▼ ▼
Found Not Found
│ │
▼ ▼
┌─────────────────┐ "No active workflow"
│ 2. Structure │
│ Validation │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 3. State │
│ Consistency │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 4. Story │
│ Validation │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 5. Sync Status │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 6. Health │
│ Checks │
└────────┬────────┘
│
▼ (if user approves)
┌─────────────────┐
│ 7. Jira │
│ Verification │
└────────┬────────┘
│
▼
┌─────────────────┐
│ 8. Report & │
│ Auto-Fix │
└─────────────────┘
## Workflow Validation: development-EPIC-45
### Structure
- workflow.md: Valid
- state.json: Valid JSON
- decisions.md: Present
- stories/: 3 files
### State Consistency
- Current Step: 3 (Implementation - TDD Green)
- Agent: Junior Developer
- Status: in_progress
- Completed: 2/9 steps
### Stories
| Story | Status | Sections |
|-------|--------|----------|
| PROJECT-123 | Complete | All present |
| PROJECT-124 | Complete | All present |
| PROJECT-125 | In Progress | Assignment, Tests, Guidance |
### Sync Status
- Pending items: 2 decisions, 0 blockers
- Last synced: 45 minutes ago
### Health
- Last updated: 12 minutes ago
- Current step iterations: 1
- Gate failures: 0
---
**Status: VALID**
Workflow is ready to continue.
## Workflow Validation: development-EPIC-45
### Structure
[...]
### State Consistency
[...]
### Warnings (2)
1. **Pending sync items accumulating**
- 8 decisions pending (threshold: 10)
- Last synced: 3 hours ago
- Consider syncing before next milestone
2. **Missing optional section**
- stories/PROJECT-125.md missing "What Was Done"
- Junior Dev should update before PR
### Stories
[...]
---
**Status: VALID (with warnings)**
Workflow can continue. Address warnings when convenient.
## Workflow Validation: development-EPIC-45
### Errors (2)
1. **State mismatch**
- state.json says: Step 4 (Code Review)
- workflow.md says: Step 3 (Implementation)
- Manual review required - which is correct?
2. **Missing story file**
- PROJECT-126 listed in workflow.md but no stories/PROJECT-126.md
- **Auto-fix available:** Create from template? [y/n]
### Warnings (1)
1. **Stale workflow**
- Last updated: 3 days ago
- Consider if this workflow is still active
---
**Status: INVALID**
Fix 2 errors before continuing workflow.
### Auto-Fix Available
The following issues can be auto-fixed:
- [ ] Create stories/PROJECT-126.md from template
Would you like to apply auto-fixes?
| Issue | Auto-Fix Action |
|---|---|
Missing state.json | Create from templates/state.template.json |
Missing decisions.md | Create from templates/decisions.template.md |
Missing stories/ folder | Create empty folder |
| Missing story file | Create from templates/development/story.template.md |
Stale last_updated | Update to current timestamp |
workflow_type mismatch | Update state.json to match folder name |
Auto-fix will NOT:
Before checking Jira, always ask:
Would you like to verify against Jira? This will make API calls to check story statuses.
[y/n]
When user approves:
### Jira Verification
Checking Jira status for stories in scope...
| Story | Local Status | Jira Status | Match |
|-------|--------------|-------------|-------|
| PROJECT-123 | Done | Done | Yes |
| PROJECT-124 | Done | Done | Yes |
| PROJECT-125 | In Progress | In Progress | Yes |
**Jira Status: Synced**
Or with issues:
### Jira Verification
| Story | Local Status | Jira Status | Match |
|-------|--------------|-------------|-------|
| PROJECT-123 | Done | Done | Yes |
| PROJECT-124 | Done | In Review | No |
| PROJECT-125 | In Progress | To Do | No |
**Jira Status: Out of Sync**
Issues found:
- PROJECT-124: Local says "Done" but Jira says "In Review"
- PROJECT-125: Local says "In Progress" but Jira says "To Do"
Would you like to:
1. Update Jira to match local state
2. Update local to match Jira state
3. Skip (manual review needed)
Before resuming a workflow:
**Orchestrator Action:** Validate workflow before resuming
1. Run validation skill (skip Jira verification for speed)
2. If VALID: Continue with workflow
3. If VALID with warnings: Continue, note warnings
4. If INVALID: Report errors, offer auto-fix, wait for user
User runs /validate-workflow:
1. Find active workflow (or use provided name)
2. Run all validations
3. Display report
4. Offer auto-fixes if available
5. Ask about Jira verification
| Argument | Description | Default |
|---|---|---|
[workflow-name] | Specific workflow to validate | Auto-detect active |
--fix | Apply auto-fixes without prompting | false |
--jira | Include Jira verification (still asks for confirmation) | false |
--quiet | Only show errors and warnings | false |
skills/workflow/workflow-tracking/ - Workflow state managementskills/workflow/workflow-archival/ - Archive completed workflows| Agent | Usage |
|---|---|
| Orchestrator | Validate before resuming or spawning agents |
| User (via /validate-workflow) | Manual validation check |
This skill should be used when the user asks to "create a slash command", "add a command", "write a custom command", "define command arguments", "use command frontmatter", "organize commands", "create command with file references", "interactive command", "use AskUserQuestion in command", or needs guidance on slash command structure, YAML frontmatter fields, dynamic arguments, bash execution in commands, user interaction patterns, or command development best practices for Claude Code.
This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.
This skill should be used when the user asks to "create a hook", "add a PreToolUse/PostToolUse/Stop hook", "validate tool use", "implement prompt-based hooks", "use ${CLAUDE_PLUGIN_ROOT}", "set up event-driven automation", "block dangerous commands", or mentions hook events (PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification). Provides comprehensive guidance for creating and implementing Claude Code plugin hooks with focus on advanced prompt-based hooks API.