Skip to content

phuryn/product-engineering / agent-harness/skills/agent-instructions

agent-instructions

Verified

Writing or restructuring AGENTS.md or CLAUDE.md, adding a rule ('remember this'), or after an agent ignored a rule it had: make each rule get met when it applies.

FileKindSize
SKILL.mdskill md19.0 KB
receipts.mdmarkdown3.6 KB
references/agents-md-skeleton.mdmarkdown22.4 KB
references/maintenance.mdmarkdown9.6 KB
references/prose-vs-code.mdmarkdown5.9 KB
references/router.mdmarkdown7.1 KB
references/working-rules.mdmarkdown7.0 KB
scripts/check_budgets.pyscript2.6 KB
scripts/check_reachable.pyscript6.5 KB

scripts/check_budgets.py

View on GitHub
#!/usr/bin/env python3
"""check_budgets.py - word budgets and review dates for an agent's instruction files.

Reads budgets.json at the repository root: {"AGENTS.md": 3000, "docs/payments.md": 1000}. A key is a path or a
glob, relative to the root; a file matched by several keys takes the first. For each file it

  a. counts words (like `wc -w`) and fails when the count is over the budget, or when a key matches no file;
  b. lists every "(review YYYY-MM)" whose month has passed, so the rule is earned again or deleted.

Exit 0 when every file is within its budget, 1 otherwise (past review dates are listed but do not fail, so a pass
can read them in one go). Copy it into the repository and run that copy in the test gate.

    python check_budgets.py [--root DIR] [--today YYYY-MM]
"""
import argparse
import datetime as dt
import json
import re
import sys
from pathlib import Path

REVIEW = re.compile(r"\(review (\d{4})-(\d{2})\)")


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
    ap.add_argument("--root", default=".", help="repository root holding budgets.json")
    ap.add_argument("--today", help="YYYY-MM to check review dates against (default: this month)")
    args = ap.parse_args()
    root = Path(args.root).resolve()
    cfg = root / "budgets.json"
    if not cfg.exists():
        print(f"no budgets.json in {root}", file=sys.stderr)
        return 1
    budgets = json.loads(cfg.read_text(encoding="utf-8"))
    month = args.today or dt.date.today().strftime("%Y-%m")

    seen, over = {}, 0
    for key, limit in budgets.items():
        matched = [p for p in sorted(root.glob(key)) if p.is_file()]
        if not matched:
            print(f"NONE  no file matches {key}")
            over += 1
        for path in matched:
            if path not in seen:
                seen[path] = (key, int(limit))
    if not seen:
        print("budgets.json matches no file", file=sys.stderr)
        return 1

    for path, (key, limit) in seen.items():
        text = path.read_text(encoding="utf-8")
        words = len(text.split())
        rel = path.relative_to(root).as_posix()
        mark = "OVER" if words > limit else "ok"
        over += words > limit
        print(f"{mark:4}  {words:6} / {limit:<6} {rel}")
        for n, line in enumerate(text.splitlines(), 1):
            for y, m in REVIEW.findall(line):
                if f"{y}-{m}" < month:
                    print(f"      past review {y}-{m}: {rel}:{n}")
    print(f"result: {'ok' if not over else f'{over} file(s) over budget or unmatched'}")
    return 1 if over else 0


if __name__ == "__main__":
    sys.exit(main())
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: 470kUpdated Claude CodeCodexVerifiedInstall
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: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
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 availableStars: 322kUpdated Claude CodeCodexVerifiedInstall