Agent skill
verifying-governance
Validates governance file completeness, format compliance, and metric accuracy. Use when auditing governance health, after bulk changes, or ensuring documentation integrity.
Install this agent skill to your Project
npx add-skill https://github.com/bacchus-labs/wrangler/tree/main/skills/verifying-governance
SKILL.md
Verify Governance Framework
Purpose
Governance frameworks can drift over time:
- Directories get renamed or go missing
- Files end up in wrong locations
- .gitignore patterns become incomplete
- Structure diverges from canonical schema
This skill performs systematic verification to detect and fix structural drift using workspace-schema.json as the single source of truth.
What This Skill Checks
IN SCOPE (Structure and Existence):
- Directory structure matches
workspace-schema.json - Subdirectories exist where schema defines them
- Governance files exist at correct paths
- Files are in correct locations (not legacy paths)
.wrangler/.gitignoreexists with all required patterns
OUT OF SCOPE (Content Quality):
- File content/template compliance (future enhancement)
- Governance file sections/structure validation
- Cross-document link validation
- Template version mismatches
- Metrics staleness
This simplification focuses on answering: "Is the structure correct?" not "Is the content good?"
Verification Workflow
Phase 1: Load Schema
Load workspace-schema.json as canonical structure:
# Find wrangler installation (usually in current project or ~/.local/share/wrangler/)
WRANGLER_ROOT=$(pwd)
SCHEMA_PATH="$WRANGLER_ROOT/.wrangler/config/workspace-schema.json"
# Check if schema exists
if [ ! -f "$SCHEMA_PATH" ]; then
echo "ERROR: workspace-schema.json not found at $SCHEMA_PATH"
echo "This project may not have wrangler initialized."
exit 1
fi
# Read schema (you'll parse this to extract directories, files, gitignore patterns)
cat "$SCHEMA_PATH"
Parse key sections:
directories- Canonical directory structuregovernanceFiles- Required governance filesreadmeFiles- Directory README filesgitignorePatterns- Patterns for .wrangler/.gitignore
Phase 2: Detect Directory Drift
Check each directory in schema:
# For each directory in schema.directories:
# Example: .wrangler/issues, .wrangler/specifications, etc.
echo "=== Checking Directories ==="
# From schema, check all directories
for dir in .wrangler/issues .wrangler/specifications .wrangler/ideas .wrangler/memos \
.wrangler/plans .wrangler/docs .wrangler/cache .wrangler/config .wrangler/logs; do
if [ -d "$dir" ]; then
echo "✓ $dir exists"
else
echo "✗ MISSING: $dir"
fi
done
# Check subdirectories (from schema.directories[].subdirectories)
echo "=== Checking Subdirectories ==="
if [ -d ".wrangler/issues/completed" ]; then
echo "✓ .wrangler/issues/completed exists"
else
echo "✗ MISSING: .wrangler/issues/completed"
fi
Detect legacy renamed directories:
Common v1.0 → v1.2 migrations to detect:
.wrangler/issues/complete/→.wrangler/issues/completed/(note: schema uses "completed", user may have "complete").wrangler/specifications/done/→.wrangler/specifications/archived/.wrangler/templates/→ (removed, templates now in skills/)
# Detect renamed directories
echo "=== Detecting Legacy Directory Names ==="
if [ -d ".wrangler/issues/complete" ]; then
echo "⚠️ LEGACY: .wrangler/issues/complete/ should be renamed to .wrangler/issues/completed/"
fi
if [ -d ".wrangler/specifications/done" ]; then
echo "⚠️ LEGACY: .wrangler/specifications/done/ should be renamed to .wrangler/specifications/archived/"
fi
if [ -d ".wrangler/templates" ]; then
echo "⚠️ LEGACY: .wrangler/templates/ no longer used (templates in skills/*/templates/)"
fi
Phase 3: Detect File Drift
Check governance files from schema:
echo "=== Checking Governance Files ==="
# From schema.governanceFiles
for file in .wrangler/CONSTITUTION.md .wrangler/ROADMAP.md .wrangler/ROADMAP_NEXT_STEPS.md; do
if [ -f "$file" ]; then
echo "✓ $file exists"
else
echo "ℹ️ OPTIONAL: $file (not required, but recommended)"
fi
done
# From schema.readmeFiles
for file in .wrangler/issues/README.md .wrangler/specifications/README.md \
.wrangler/memos/README.md .wrangler/plans/README.md; do
if [ -f "$file" ]; then
echo "✓ $file exists"
else
echo "ℹ️ MISSING: $file (consider creating)"
fi
done
Detect files in wrong locations:
Common legacy file locations:
.wrangler/hooks-config.json→.wrangler/config/hooks-config.json.wrangler/workspace-schema.json→.wrangler/config/workspace-schema.json
echo "=== Detecting Legacy File Locations ==="
if [ -f ".wrangler/hooks-config.json" ]; then
echo "⚠️ LEGACY: .wrangler/hooks-config.json should be at .wrangler/config/hooks-config.json"
fi
if [ -f ".wrangler/workspace-schema.json" ]; then
echo "⚠️ LEGACY: .wrangler/workspace-schema.json should be at .wrangler/config/workspace-schema.json"
fi
Phase 4: Detect .gitignore Drift
Check .wrangler/.gitignore:
echo "=== Checking .wrangler/.gitignore ==="
if [ ! -f ".wrangler/.gitignore" ]; then
echo "✗ MISSING: .wrangler/.gitignore"
echo " Required patterns: cache/, config/, logs/"
else
echo "✓ .wrangler/.gitignore exists"
# Check each pattern from schema.gitignorePatterns
echo "=== Checking gitignore patterns ==="
for pattern in "cache/" "config/" "logs/"; do
if grep -q "^${pattern}$" .wrangler/.gitignore; then
echo "✓ Pattern present: $pattern"
else
echo "✗ MISSING PATTERN: $pattern"
fi
done
fi
Phase 5: Report Drift
Compile findings into clear report:
# Governance Structure Verification Report
**Date**: [YYYY-MM-DD HH:MM]
**Schema Version**: [from workspace-schema.json version field]
---
## Summary
- **Status**: [✅ COMPLIANT / ⚠️ DRIFT DETECTED / ❌ CRITICAL ISSUES]
- **Missing Directories**: [N]
- **Missing Files**: [N]
- **Wrong Locations**: [N]
- **Missing Gitignore Patterns**: [N]
---
## Detailed Findings
### Missing Directories ([N])
- `.wrangler/issues/completed/` (required by schema)
- `.wrangler/cache/` (required by schema)
**Fix**: `mkdir -p .wrangler/issues/completed .wrangler/cache`
### Legacy Directory Names ([N])
- `.wrangler/issues/complete/` exists but schema expects `.wrangler/issues/completed/`
- **Impact**: 12 files in old location
- **Fix**: `mv .wrangler/issues/complete .wrangler/issues/completed`
- `.wrangler/specifications/done/` exists but schema expects `.wrangler/specifications/archived/`
- **Impact**: 5 files in old location
- **Fix**: `mv .wrangler/specifications/done .wrangler/specifications/archived`
### Wrong File Locations ([N])
- `.wrangler/hooks-config.json` should be at `.wrangler/config/hooks-config.json`
- **Fix**: `mv .wrangler/hooks-config.json .wrangler/config/hooks-config.json`
### Missing Files ([N])
- `.wrangler/.gitignore` (required for proper git tracking)
- **Fix**: Create with patterns: cache/, config/, logs/
**Note**: Governance files (CONSTITUTION.md, ROADMAP.md) are optional per schema.
### Missing Gitignore Patterns ([N])
- Pattern `sessions/` missing from `.wrangler/.gitignore`
- **Fix**: Add to .gitignore
---
## Recommended Actions
[List specific commands to fix each issue, grouped by type]
Phase 6: Get Permission
Present user with 4 options:
## How would you like to proceed?
1. **Fix all automatically** (recommended)
- I'll apply all fixes shown above
- Affected files will be moved/renamed
- Directories will be created
- .gitignore will be updated
2. **Show me the commands**
- I'll display bash commands
- You run them manually
- Good for reviewing changes first
3. **Let me choose**
- I'll ask about each fix individually
- You approve or skip each one
- Good for selective fixes
4. **Cancel**
- No changes made
- Exit verification
Please choose: [1/2/3/4]
Wait for user response before proceeding.
Phase 7: Apply Fixes
Option 1: Fix All Automatically
echo "=== Applying All Fixes ==="
# Create missing directories
mkdir -p .wrangler/issues/completed
mkdir -p .wrangler/cache
echo "✓ Created missing directories"
# Rename legacy directories (only if they exist)
if [ -d ".wrangler/issues/complete" ]; then
mv .wrangler/issues/complete .wrangler/issues/completed
echo "✓ Renamed .wrangler/issues/complete/ → .wrangler/issues/completed/"
fi
# Move misplaced files
if [ -f ".wrangler/hooks-config.json" ]; then
mkdir -p .wrangler/config
mv .wrangler/hooks-config.json .wrangler/config/hooks-config.json
echo "✓ Moved hooks-config.json to config/"
fi
# Create/update .gitignore
if [ ! -f ".wrangler/.gitignore" ]; then
cat > .wrangler/.gitignore << 'EOF'
cache/
config/
logs/
EOF
echo "✓ Created .wrangler/.gitignore"
else
# Append missing patterns
for pattern in "cache/" "config/" "logs/"; do
if ! grep -q "^${pattern}$" .wrangler/.gitignore; then
echo "$pattern" >> .wrangler/.gitignore
echo "✓ Added pattern to .gitignore: $pattern"
fi
done
fi
echo "=== All Fixes Applied ==="
Option 2: Show Commands
Display the bash commands without executing:
echo "=== Commands to Fix Drift ==="
echo ""
echo "# Create missing directories"
echo "mkdir -p .wrangler/issues/completed"
echo "mkdir -p .wrangler/cache"
echo ""
echo "# Rename legacy directories"
echo "mv .wrangler/issues/complete .wrangler/issues/completed"
echo ""
echo "# Move misplaced files"
echo "mkdir -p .wrangler/config"
echo "mv .wrangler/hooks-config.json .wrangler/config/hooks-config.json"
echo ""
echo "# Create .gitignore"
echo "cat > .wrangler/.gitignore << 'EOF'"
echo "cache/"
echo "config/"
echo "logs/"
echo "EOF"
Option 3: Let Me Choose
Ask about each fix individually:
Fix: Create .wrangler/issues/completed/ directory
Apply this fix? [y/n]: _
[wait for user response]
Fix: Rename .wrangler/issues/complete/ → .wrangler/issues/completed/ (12 files)
Apply this fix? [y/n]: _
[and so on...]
Option 4: Cancel
No changes made. Verification report saved for reference.
Run /wrangler:verifying-governance again when ready to fix drift.
Phase 8: Re-Verify
After applying fixes, run verification again:
echo "=== Re-Running Verification ==="
echo ""
# Run Phases 2-4 again to confirm all drift resolved
echo "=== Final Status ==="
if [ all checks pass ]; then
echo "✅ All drift resolved! Governance structure now compliant."
else
echo "⚠️ Some issues remain:"
# List remaining issues
fi
Legacy Migration Detection
This skill specifically handles v1.0 → v1.2 migration drift:
| Legacy Location | Current Location | Detection Method |
|---|---|---|
.wrangler/issues/complete/ |
.wrangler/issues/completed/ |
Directory exists check |
.wrangler/specifications/done/ |
.wrangler/specifications/archived/ |
Directory exists check |
.wrangler/hooks-config.json |
.wrangler/config/hooks-config.json |
File exists check |
.wrangler/workspace-schema.json |
.wrangler/config/workspace-schema.json |
File exists check |
.wrangler/templates/ |
skills/*/templates/ |
Directory exists check (now unused) |
When detected, offer to migrate automatically.
Edge Cases
No workspace-schema.json
Situation: Schema file doesn't exist
Response:
ERROR: workspace-schema.json not found at .wrangler/config/workspace-schema.json
This project may not have wrangler v1.2+ initialized.
Options:
1. Run /wrangler:initializing-governance to set up governance
2. Manually create .wrangler/config/workspace-schema.json from template
3. Update wrangler to latest version
Partial .wrangler/ Setup
Situation: Some directories exist, others don't
Response: Report exactly what's missing, offer to create all at once.
.gitignore Has Extra Patterns
Situation: .gitignore has more patterns than schema requires
Response: This is fine. Only report MISSING patterns, never complain about extras.
Schema Version Mismatch
Situation: Schema version field doesn't match wrangler version
Response: Report version mismatch as informational only, don't block.
Empty Directories
References
For detailed information, see:
references/detailed-guide.md- Complete workflow details, examples, and troubleshooting
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
locating-code
Finds specific code elements (functions, classes, patterns) using multiple search strategies. Use when searching for implementations, dependencies, or code requiring modification.
using-wrangler
Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage, following brainstorming before coding, and creating TodoWrite todos for checklists
creating-issues
For use when a new issue/task has been identified and needs to be formally captured using the Wrangler MCP issue management system. Use this skill to create new issues via the issues_create MCP tool with appropriate metadata and structured content.
validating-roadmaps
Validates roadmap completeness, phase coherence, and alignment with constitution. Use when creating roadmaps, reviewing planning documents, or ensuring strategic consistency.
refreshing-metrics
Auto-updates status metrics across governance documents from MCP issue counts. Use when governance metrics are stale or after significant issue status changes requiring documentation refresh.
updating-git-hooks
Updates existing git hook configurations for new requirements or tool changes. Use when hook requirements change, adding new quality checks, or modifying test commands.
Didn't find tool you were looking for?