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 |
scripts/shape_spec.py
View on GitHub"""Spec Shaper engine. Stdlib only.
Shapes structured specifications into specs/<slug>/SPEC.md and VERIFICATION.json.
Supports non-interactive CLI flags and interactive interview mode.
"""
import argparse
import datetime
import json
import re
import sys
from pathlib import Path
# Safe Windows console stream configuration
if hasattr(sys.stdout, "reconfigure"):
sys.stdout.reconfigure(encoding="utf-8", errors="replace")
if hasattr(sys.stderr, "reconfigure"):
sys.stderr.reconfigure(encoding="utf-8", errors="replace")
_script_dir = Path(__file__).resolve().parent
if str(_script_dir) not in sys.path:
sys.path.insert(0, str(_script_dir))
try:
from discover_standards import discover_standards
except ImportError:
import importlib.util
_disc_path = _script_dir / "discover_standards.py"
if _disc_path.is_file():
_spec = importlib.util.spec_from_file_location("discover_standards", _disc_path)
_mod = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(_mod)
discover_standards = _mod.discover_standards
def shape_spec(
root: Path,
slug: str,
title: str,
problem: str = "",
solution: str = "",
criteria: list[str] = None,
assert_files: list[str] = None,
assert_commands: list[str] = None,
assert_contains: list[dict] = None,
assert_regex: list[dict] = None,
assert_json: list[dict] = None,
assert_symbols: list[dict] = None,
from_standards: bool = False,
require_envelope: bool = False,
) -> Path:
criteria = list(criteria or [])
assert_files = list(assert_files or [])
assert_commands = list(assert_commands or [])
assert_contains = list(assert_contains or [])
assert_regex = list(assert_regex or [])
assert_json = list(assert_json or [])
assert_symbols = list(assert_symbols or [])
if not re.match(r"^[a-z0-9]+(-[a-z0-9]+)*$", slug):
raise ValueError(f"Invalid slug '{slug}': must match ^[a-z0-9]+(-[a-z0-9]+)*$")
envelope_keys = []
if from_standards or require_envelope:
standards = discover_standards(root)
envelope = standards.get("response_envelope", {})
if envelope:
envelope_keys = sorted(envelope.keys()) if isinstance(envelope, dict) else sorted(envelope)
env_crit = f"Code adheres to discovered response envelope: {', '.join(envelope_keys)}"
if env_crit not in criteria:
criteria.append(env_crit)
if from_standards:
if standards.get("error_codes"):
err_count = len(standards["error_codes"])
err_crit = f"Error handling adheres to declared error code standards ({err_count} declared codes)."
if err_crit not in criteria:
criteria.append(err_crit)
if standards.get("database_patterns"):
db_str = ", ".join(sorted(standards["database_patterns"]))
db_crit = f"Database interactions follow approved query methods: {db_str}"
if db_crit not in criteria:
criteria.append(db_crit)
comp_crit = "Passes repository standards compliance check without drift."
if comp_crit not in criteria:
criteria.append(comp_crit)
if assert_files:
comp_cmd = f"python scripts/check_compliance.py --files {' '.join(assert_files)}"
else:
comp_cmd = "python scripts/check_compliance.py"
if comp_cmd not in assert_commands:
assert_commands.append(comp_cmd)
spec_dir = root / "specs" / slug
spec_dir.mkdir(parents=True, exist_ok=True)
date_str = datetime.date.today().isoformat()
spec_md_content = f"""# Specification: {title}
- **Slug:** `{slug}`
- **Date:** {date_str}
- **Status:** Draft / Active
## 1. Problem Statement
{problem or "Provide a clear description of the problem being solved."}
## 2. Proposed Solution
{solution or "High-level architectural approach and key invariants."}
## 3. Acceptance Criteria
"""
if criteria:
for c in criteria:
spec_md_content += f"- [ ] {c}\n"
else:
spec_md_content += "- [ ] All acceptance criteria pass deterministic verification.\n"
spec_md_content += """
## 4. Execution & Verification Boundaries
- Read-only directories must not be modified.
- Standard libraries only; zero unvetted dependencies.
- Evidence-based completion: code is complete only when `scripts/verify_spec.py` exits 0.
"""
if require_envelope and envelope_keys:
spec_md_content += f"- Discovered API response envelope adherence required: {', '.join(envelope_keys)}.\n"
(spec_dir / "SPEC.md").write_text(spec_md_content, encoding="utf-8")
verification_data = {
"slug": slug,
"title": title,
"created_at": date_str,
"assertions": {
"files_exist": assert_files,
"file_contains": assert_contains,
"regex_matches": assert_regex,
"json_matches": assert_json,
"ast_symbol_present": assert_symbols,
"commands": assert_commands
}
}
(spec_dir / "VERIFICATION.json").write_text(
json.dumps(verification_data, indent=2), encoding="utf-8"
)
return spec_dir
def _parse_file_colon_rest(arg: str) -> tuple[str, str]:
"""Splits <file>:<rest>, safely handling Windows drive letters like C:\\path:rest."""
if len(arg) >= 3 and arg[1] == ":" and (arg[2] == "\\" or arg[2] == "/"):
next_colon = arg.find(":", 2)
if next_colon != -1:
return arg[:next_colon], arg[next_colon + 1:]
return arg, ""
else:
parts = arg.split(":", 1)
if len(parts) == 2:
return parts[0], parts[1]
return parts[0], ""
def interactive_interview(root: Path) -> Path:
print("=== Spec Shaper Interactive Mode ===")
slug = input("Enter spec slug (kebab-case, e.g. user-auth): ").strip()
title = input("Enter feature title: ").strip()
problem = input("Enter problem description: ").strip()
solution = input("Enter proposed solution summary: ").strip()
from_std_in = input("Auto-wire repository standards? (y/N): ").strip().lower()
from_standards = from_std_in in ("y", "yes")
print("Enter acceptance criteria (blank line to stop):")
criteria = []
while True:
c = input(" - ").strip()
if not c:
break
criteria.append(c)
print("Enter required files to assert existence (blank line to stop):")
assert_files = []
while True:
f = input(" file path: ").strip()
if not f:
break
assert_files.append(f)
print("Enter shell verification commands to assert exit 0 (blank line to stop):")
assert_commands = []
while True:
cmd = input(" command: ").strip()
if not cmd:
break
assert_commands.append(cmd)
return shape_spec(
root=root,
slug=slug,
title=title,
problem=problem,
solution=solution,
criteria=criteria,
assert_files=assert_files,
assert_commands=assert_commands,
from_standards=from_standards
)
def main():
parser = argparse.ArgumentParser(description="Shape structured specifications.")
parser.add_argument("--dir", default=".", help="Project root directory")
parser.add_argument("--slug", help="Spec slug (kebab-case)")
parser.add_argument("--title", help="Human-readable feature title")
parser.add_argument("--problem", default="", help="Problem description")
parser.add_argument("--solution", default="", help="Proposed solution summary")
parser.add_argument("--criterion", action="append", help="Acceptance criterion text")
parser.add_argument("--assert-file", action="append", help="File path to assert existence")
parser.add_argument("--assert-command", action="append", help="Command to assert exit 0")
parser.add_argument("--interactive", action="store_true", help="Run interactive interview")
parser.add_argument("--from-standards", action="store_true", help="Auto-wire repository standards into spec")
parser.add_argument("--require-envelope", action="store_true", help="Require response envelope adherence")
parser.add_argument("--assert-contains", action="append", help="Assert file contains text (<file>:<text>)")
parser.add_argument("--assert-regex", action="append", help="Assert file matches regex (<file>:<pattern>)")
parser.add_argument("--assert-symbol", action="append", help="Assert AST symbol present (<file>:<name>[:type])")
parser.add_argument("--assert-json", action="append", help="Assert JSON matches subset (<file>:<json_string>)")
args = parser.parse_args()
root = Path(args.dir).resolve()
if args.interactive:
spec_dir = interactive_interview(root)
else:
if not args.slug or not args.title:
parser.error("--slug and --title are required when not using --interactive")
parsed_contains = []
if args.assert_contains:
for item in args.assert_contains:
f, txt = _parse_file_colon_rest(item)
existing = next((c for c in parsed_contains if c["file"] == f), None)
if existing:
existing["contains"].append(txt)
else:
parsed_contains.append({"file": f, "contains": [txt]})
parsed_regex = []
if args.assert_regex:
for item in args.assert_regex:
f, pat = _parse_file_colon_rest(item)
parsed_regex.append({"file": f, "pattern": pat})
parsed_json = []
if args.assert_json:
for item in args.assert_json:
f, j_str = _parse_file_colon_rest(item)
parsed_json.append({"file": f, "subset": json.loads(j_str)})
parsed_symbols = []
if args.assert_symbol:
for item in args.assert_symbol:
f, rest = _parse_file_colon_rest(item)
if ":" in rest:
name, sym_type = rest.split(":", 1)
else:
name, sym_type = rest, "ClassDef"
parsed_symbols.append({"file": f, "name": name, "type": sym_type or "ClassDef"})
spec_dir = shape_spec(
root=root,
slug=args.slug,
title=args.title,
problem=args.problem,
solution=args.solution,
criteria=args.criterion,
assert_files=args.assert_file,
assert_commands=args.assert_command,
assert_contains=parsed_contains,
assert_regex=parsed_regex,
assert_json=parsed_json,
assert_symbols=parsed_symbols,
from_standards=args.from_standards,
require_envelope=args.require_envelope
)
print(f"Spec successfully shaped at: {spec_dir}")
return 0
if __name__ == "__main__":
sys.exit(main())
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: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | 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: 322k | 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: 322k | Updated | Claude CodeCodex | Verified | Install |