Snoozer10/synthesize-skills / .agents/skills/repo-standards-engineer
repo-standards-engineer
VerifiedUse when extracting codebase standards, response envelopes, and error codes via AST, checking architectural compliance, indexing symbols, shaping specs with rich semantic assertions, or verifying contracts in specs directory
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 4.8 KB |
| references/ast_patterns.md | markdown | 644 B |
| scripts/check_compliance.py | script | 20.0 KB |
| scripts/discover_standards.py | script | 19.5 KB |
| scripts/index_standards.py | script | 21.8 KB |
| scripts/inject_standards.py | script | 4.1 KB |
| scripts/shape_spec.py | script | 10.8 KB |
| scripts/verify_spec.py | script | 13.6 KB |
| templates/spec_template.md | markdown | 646 B |
| templates/standard_template.md | markdown | 750 B |
| templates/verification_template.json | config | 1001 B |
SKILL.md
View on GitHub---
name: repo-standards-engineer
description: "Use when extracting codebase standards, response envelopes, and error codes via AST, checking architectural compliance, indexing symbols, shaping specs with rich semantic assertions, or verifying contracts in specs directory"
---
# repo-standards-engineer
## Overview
- AST Standards Discovery: `discover_standards.py` extracts response envelopes, error enums, dataclasses, Pydantic models, and database patterns with SHA-256 caching.
- Standards Compliance & Drift Checker: `check_compliance.py` audits code changes or staged diffs against Rule 1 (Error Code Governance), Rule 2 (Response Envelope Integrity), and Rule 3 (Database Query Governance).
- Symbol & Error Code Reverse Indexer: `index_standards.py` maps symbols and error codes to exact defining source files and line numbers with CLI and API query support.
- JIT Token Bounding: `inject_standards.py` injects repo standards and invariants under a strict token budget (MIP <= 600 tokens).
- Spec Shaper with Auto-Wiring: `shape_spec.py` (`--from-standards`, `--assert-file`, `--assert-contains`, `--assert-regex`, `--assert-json`, `--assert-symbol`) weaves discovered standards into specs and automated verification contracts.
- Contract Verifier: `verify_spec.py` deterministically executes acceptance assertions including rich semantic checks (`file_contains`, `regex_matches`, `json_matches`, `ast_symbol_present`) and automated commands.
## When to Use
- Discovering conventions, schemas, and response envelopes in unfamiliar polyglot codebases.
- Auditing modified or staged files against declared repository error codes and response standards.
- Reverse-querying defining source locations for specific error codes or domain symbols.
- Shaping feature specs auto-wired with repository standards and rich semantic assertions.
- Enforcing deterministic acceptance contracts before claiming task completion.
- When NOT to use: one-line scratch edits, non-code repositories, or purely aesthetic checks.
Keywords: code-standards, ast-extraction, response-envelopes, error-codes, compliance-checker, architectural-drift, symbol-index, reverse-query, rich-assertions, spec-shaper, deterministic-contracts, contract-verification
## Quick Reference
| Task | Command |
| :--- | :--- |
| Discover standards (JSON) | `python scripts/discover_standards.py --json` |
| Force rescan (bypass cache) | `python scripts/discover_standards.py --force` |
| Audit file compliance | `python scripts/check_compliance.py --files src/app.py` |
| Audit git staged diffs | `python scripts/check_compliance.py --staged` |
| Query symbol definition | `python scripts/index_standards.py --query <symbol>` |
| Query error code definition | `python scripts/index_standards.py --error-code <code_name>` |
| Inject standards (<= 600 tokens) | `python scripts/inject_standards.py --max-tokens 600` |
| Shape spec with standards | `python scripts/shape_spec.py --from-standards --slug <slug> --title "<title>" --assert-file <path>` |
| Shape spec with rich assertions | `python scripts/shape_spec.py --slug <slug> --title "<title>" --assert-symbol "file.py:class:MyClass"` |
| Verify spec contract | `python scripts/verify_spec.py --spec specs/<slug>` |
## Verification Example
```bash
python scripts/discover_standards.py --json
python scripts/check_compliance.py --files src/app.py
python scripts/index_standards.py --error-code ERR_UNAUTHORIZED
python scripts/shape_spec.py --from-standards --slug user-feature --title "User Feature" --assert-file src/app.py
python scripts/verify_spec.py --spec specs/user-feature
```
```python
import subprocess
import sys
res = subprocess.run([sys.executable, "scripts/check_compliance.py", "--files", "src/app.py"], capture_output=True, text=True)
print("Compliance check exit code:", res.returncode)
```
## Dual-Axis Subagent Review Pattern
When executing non-trivial feature implementations:
1. Standards Auditor: audits code with `check_compliance.py` to ensure zero undeclared error codes, envelope deviations, or prohibited query patterns.
2. Spec Contract Auditor: executes `verify_spec.py --spec specs/<slug>` to guarantee all file existence, semantic assertions, and command contracts pass deterministically.
## Common Pitfalls
- Assuming API response structures without running discovery. Remediation: run `python scripts/discover_standards.py`.
- Introducing undeclared error codes or rogue envelope keys. Remediation: run `python scripts/check_compliance.py`.
- Manually hunting where error codes or symbols are defined. Remediation: run `python scripts/index_standards.py --error-code <code_name>`.
- Bloating context with multi-page standards docs. Remediation: run `python scripts/inject_standards.py --max-tokens 600`.
- Claiming task completion without automated receipts. Remediation: enforce `python scripts/verify_spec.py --spec specs/<slug>`.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |