| name | workflow-guard |
| description | Validates Issue-First workflow compliance before execution |
| compatibility | OpenCode, Claude Code |
| metadata | {"category":"workflow","security_level":"critical","version":"1.1"} |
Skill: workflow-guard
Purpose
Validates that all actions comply with the Issue-First development workflow
before execution.
When to Run
Before starting any code change, fix, or feature -- and again before
creating a PR.
Validation Steps
1. Issue Requirements
2. Branch Requirements
3. Commit Requirements
4. Pull Request Requirements
5. Security Requirements
Workflow State Machine
+---------+ +----------+ +---------+ +---------+ +---------+
| Issue |--->| Branch |--->| Commit |--->| PR |--->| Merge |
| Created | | Created | | Pushed | | Opened | | to dev |
+---------+ +----------+ +---------+ +---------+ +---------+
| | | | |
v v v v v
+---------+ +----------+ +---------+ +---------+ +---------+
|validate | |validate | |validate | |validate | |validate |
|issue | |branch | |commit | |PR | |merge |
+---------+ +----------+ +---------+ +---------+ +---------+
Critical Actions Requiring Approval
The following workflow transitions ALWAYS require human approval:
- Pushing to main/dev: Direct push to protected branches
- Merging to main: Final release merges
- Force push: Any
git push --force operation
- Workflow bypass: Skipping required checks
- Emergency changes: Changes to
.security/ or .github/workflows/
Validation Commands
Check Issue Status
gh issue view <number> --json number,title,state,assignees,labels
Check Issue Body Cleanliness (prevent backtick injection)
gbody=$(gh issue view <number> --json body -q '.body')
if echo "$gbody" | grep -Eq '(Error:|Usage:|podman stop|^[a-f0-9]{64}$|20[0-9]{2}-[0-9]{2}-[0-9]{2}T)'; then
echo "REJECT: Issue body appears garbled (backtick command substitution or shell output injected)"
echo "Remediation: Recreate with --body-file or quoted HEREDOC"
exit 1
fi
Check Branch Origin
git log --oneline dev..HEAD | tail -1
git merge-base --is-ancestor dev HEAD || echo "NOT from dev"
Check Commit Format
git log --oneline -1 | grep -E '^(fix|feat|docs|refactor|test|chore|ci):'
git log --oneline -1 | grep -E 'Fixes #[0-9]+'
Check PR Requirements
gh pr view <number> --json assignees,labels,title,body
Failure Handling
If any validation step fails:
- Log the failure with full context
- Block execution of the action
- Provide remediation guidance
- Alert human via @security-gate agent
Example Usage
@orchestrator Please validate the workflow for issue #917
Agent loads this skill and runs validation:
1. Check issue #917 exists [x]
2. Check issue is assigned [x]
3. Check branch issue-917/security-first-agentic-foundation format [x]
4. Check branch from dev [x]
5. Check commits reference #917 [x]
6. Check security-gate approval [x]
Result: All validations passed. Workflow approved.
Integration
This skill is automatically invoked by:
- @orchestrator agent for workflow coordination
- @security-gate agent for compliance validation
- GitHub Actions for CI/CD enforcement
Compliance Rules
| Rule | Source | Enforcement |
|---|
| Issue-first | AGENTS.md | Block execution without valid issue |
| No colons in titles | DEVELOPMENT.md | Reject malformed titles |
| Clean issue body | workflow-guard skill | Reject garbled body (backtick injection) |
| Branch from dev | AGENTS.md | Reject branches from main |
| Component labels required | DEVELOPMENT.md | Reject unlabeled PRs |
| Assignee required | DEVELOPMENT.md | Reject unassigned PRs |
Self-Verification
Before claiming compliance, verify: