diegosouzapw/awesome-omni-skill / skills/ai-agents/agent-ops-validation
agent-ops-validation
VerifiedPre-commit and pre-merge validation checks. Use before committing changes or declaring work complete to ensure all quality gates pass.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 9.5 KB |
| metadata.json | config | 1.4 KB |
SKILL.md
View on GitHub---
name: agent-ops-validation
description: "Pre-commit and pre-merge validation checks. Use before committing changes or declaring work complete to ensure all quality gates pass."
license: MIT
compatibility: [opencode, claude, cursor]
metadata:
category: core
related: [agent-ops-tasks, agent-ops-api-review, agent-ops-implementation, agent-ops-state, agent-ops-baseline, agent-ops-critical-review, agent-ops-git]
---
# Validation Workflow
**Works with or without `aoc` CLI installed.** Issue tracking can be done via direct file editing.
## Purpose
Ensure all quality gates pass before committing changes or declaring work complete. This skill consolidates all validation checks into a single, consistent procedure.
## Validation Commands (from constitution)
```bash
# Example commands — read actual commands from .agent/constitution.md
build: npm run build # or: uv run python -m build
lint: npm run lint # or: uv run ruff check .
test: npm run test # or: uv run pytest
format: npm run format # or: uv run ruff format .
```
## Issue Operations After Validation (File-Based — Default)
| Operation | How to Do It |
|-----------|--------------|
| Create regression issue | Append to `.agent/issues/high.md` with BUG type |
| Update issue status | Edit `status:` field directly in priority file |
| List blocking issues | Search priority files for `status: blocked` |
### Example: Post-Validation Issue Creation (File-Based)
1. Read `.agent/issues/.counter`, increment, write back
2. Generate new ID: `BUG-{counter}@{hash}`
3. Append issue to `.agent/issues/high.md`:
```yaml
## BUG-NNNN@HHHHHH — New test failure: UserService.login
id: BUG-NNNN@HHHHHH
type: BUG
status: todo
priority: high
description: Regression detected during validation
### Log
- YYYY-MM-DD: Created from validation failure
```
## CLI Integration (when aoc is available)
When `aoc` CLI is detected in `.agent/tools.json`, these commands provide convenience shortcuts:
| Operation | CLI Command |
|-----------|-------------|
| Create regression issue | `aoc issues create --type BUG --priority high --title "..."` |
| Update issue status | `aoc issues update <ID> --status done` |
| List blocking issues | `aoc issues list --status blocked` |
## API Detection
**Before running validation, check if project contains APIs:**
```yaml
api_indicators:
- OpenAPI/Swagger spec (openapi.yaml, swagger.json, openapi.json)
- API framework patterns (FastAPI, Flask, Express, ASP.NET controllers)
- Route decorators (@app.route, @router.get, [HttpGet], etc.)
```
**If API detected during Tier 3 validation:**
1. Note: "API endpoints detected"
2. After standard validation, invoke `agent-ops-api-review` for contract alignment check
3. Include API review findings in validation report
## When to Use
- Before any git commit
- Before declaring a task complete
- Before critical review
- After recovery actions
- On explicit user request
## Preconditions
- `.agent/constitution.md` exists with confirmed commands
- `.agent/baseline.md` exists for comparison
## Validation Tiers
### Tier 1: Fast Checks (always run)
Run duration: < 30 seconds
1. **Syntax validation**: Files parse without errors
2. **Lint (fast mode)**: Style and obvious issues
3. **Type check** (if applicable): Static type errors
4. **Format check**: Code formatting consistent
### Tier 2: Standard Checks (before commit)
Run duration: < 5 minutes
1. All Tier 1 checks
2. **Unit tests**: Fast, isolated tests
3. **Build**: Project compiles/builds successfully
4. **Lint (full)**: Complete lint analysis
### Tier 3: Comprehensive Checks (before merge/complete)
Run duration: varies (can be slow)
1. All Tier 2 checks
2. **Integration tests**: Component interaction tests
3. **Coverage check**: Ensure coverage thresholds met
4. **Security scan** (if configured): Vulnerability detection
5. **Documentation**: Verify docs are updated
## Procedure
### Quick Validation (Tier 1)
```
1. Run lint command (fast mode if available)
2. Run type check command (if applicable)
3. Check for syntax errors in changed files
4. Report: PASS / FAIL with details
```
### Standard Validation (Tier 2)
```
1. Run Tier 1 checks
2. Run build command from constitution
3. Run unit test command from constitution
4. Compare results to baseline
5. Report: PASS / FAIL / REGRESSION
```
### Comprehensive Validation (Tier 3)
```
1. Run Tier 2 checks
2. Run full test suite
3. Run coverage analysis
4. Run security checks (if configured)
5. Verify documentation updated
6. Compare all results to baseline
7. Report: PASS / FAIL / REGRESSION with full details
```
## Validation Report Format
```markdown
## Validation Report - [timestamp]
### Summary
- Tier: [1|2|3]
- Result: [PASS|FAIL|REGRESSION]
- Duration: [time]
### Checks Performed
| Check | Status | Details |
|-------|--------|---------|
| Lint | ✅ PASS | 0 errors, 2 warnings (baseline: 2) |
| Build | ✅ PASS | Exit code 0 |
| Tests | ⚠️ REGRESSION | 1 new failure (see below) |
### Failures (if any)
#### Test Failure: test_feature_x
- File: tests/test_feature.py:42
- Error: AssertionError: expected X, got Y
- Baseline: PASS (new regression)
### Warnings (if any)
- lint: unused variable 'foo' in file.py:10 (pre-existing)
### Recommendation
[PROCEED | FIX REQUIRED | INVESTIGATE]
```
## Baseline Comparison Rules
### New Finding Categories
| Category | Action |
|----------|--------|
| New error | **BLOCK** - must fix before proceeding |
| New warning | **INVESTIGATE** - fix or document why acceptable |
| New test failure | **BLOCK** - must fix or prove pre-existing |
| Improved (fewer issues) | **PASS** - note improvement |
| Same as baseline | **PASS** - no change |
### Handling Regressions
1. Identify if regression is from agent's changes
2. If yes: fix before proceeding
3. If no (pre-existing): document and escalate as task
4. Never ignore regressions silently
## Integration Points
### With agent-ops-git
Before committing:
```
1. Run Tier 2 validation
2. If PASS: proceed with commit
3. If FAIL: abort commit, report issues
```
### With agent-ops-critical-review
During review:
```
1. Run Tier 3 validation
2. Include validation report in review
3. Block completion if FAIL or REGRESSION
```
### With agent-ops-implementation
After each step:
```
1. Run Tier 1 validation (fast feedback)
2. After final step: run Tier 2 validation
```
## Quality Gate Configuration
### Confidence-Based Coverage Thresholds
**Coverage requirements vary by confidence level:**
| Confidence | Line Coverage | Branch Coverage | Gate Type |
|------------|---------------|-----------------|----------|
| LOW | ≥90% on changed code | ≥85% on changed code | HARD (blocks) |
| NORMAL | ≥80% on changed code | ≥70% on changed code | SOFT (warning) |
| HIGH | Tests pass | N/A | None |
**During Tier 3 validation, check coverage against confidence threshold:**
```
🎯 COVERAGE VALIDATION — {CONFIDENCE} Confidence
| Metric | Required | Actual | Status |
|--------|----------|--------|--------|
| Line coverage | ≥{threshold}% | {actual}% | {PASS/FAIL} |
| Branch coverage | ≥{threshold}% | {actual}% | {PASS/FAIL} |
{If FAIL for LOW confidence:}
⛔ COVERAGE THRESHOLD NOT MET — Cannot proceed
Options:
1. Add more tests to reach threshold
2. Document why threshold is unachievable (requires justification)
```
### Constitution-Based Configuration
Read from `.agent/constitution.md`:
```markdown
## Quality gates
- lint_must_pass: true | false
- build_must_pass: true
- tests_must_pass: true
- coverage_threshold: 80% | none
- allow_warnings: true | false
- security_scan: true | false
```
If not configured, defaults:
- lint_must_pass: true
- build_must_pass: true
- tests_must_pass: true
- coverage_threshold: none
- allow_warnings: true
- security_scan: false
## Commands
All validation commands MUST come from constitution. Never guess or assume commands.
```markdown
## From constitution:
- build: [constitution build command]
- lint: [constitution lint command]
- test: [constitution test command]
- format: [constitution format command]
```
## Output
Update `.agent/focus.md` with validation results:
```markdown
## Just did
- Ran Tier 2 validation: PASS
- lint: 0 errors, 2 warnings (baseline match)
- build: success
- tests: 45 pass, 0 fail
```
## Issue Discovery After Validation
**After validation, invoke `agent-ops-tasks` discovery procedure for new findings:**
1) **Collect regressions and new issues:**
- New test failures → `BUG` (high/critical)
- New lint errors → `BUG` (medium)
- New warnings → `CHORE` (low)
- Coverage drops → `TEST` (medium)
- Security findings → `SEC` (high/critical)
2) **Present to user:**
```
📋 Validation found {N} new issues vs baseline:
Critical:
- [BUG] New test failure: UserService.login
High:
- [SEC] New security warning from npm audit
Medium:
- [BUG] 2 new lint errors in PaymentController
Create issues to track these? [A]ll / [S]elect / [N]one
Note: These MUST be fixed before commit/merge.
```
3) **After creating issues:**
```
Created {N} issues. These block commit/merge.
1. Start fixing highest priority (BUG-0024@abc123)
2. View all blocking issues
3. Abort current work
```
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness. | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is available | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |