phuryn/product-engineering / agent-harness/skills/agent-instructions
agent-instructions
VerifiedWriting 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.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 19.0 KB |
| receipts.md | markdown | 3.6 KB |
| references/agents-md-skeleton.md | markdown | 22.4 KB |
| references/maintenance.md | markdown | 9.6 KB |
| references/prose-vs-code.md | markdown | 5.9 KB |
| references/router.md | markdown | 7.1 KB |
| references/working-rules.md | markdown | 7.0 KB |
| scripts/check_budgets.py | script | 2.6 KB |
| scripts/check_reachable.py | script | 6.5 KB |
receipts.md
View on GitHub# agent-instructions: receipts
Each heading is a rule from `SKILL.md`, with the case that taught it.
## Use the entry file to route every session's context.
- `Undated`: It was learned on SaaS repositories built with coding agents on Next.js + Supabase + Clerk + Netlify — a starter repository and the products built from it — and on a content repository run day to day by agents, whose instructions had grown to hundreds of thousands of words of doctrine.
## Give every reviewer a fallback, never “none”.
- `2026-11-06`, owner: a reviewer always has a fallback, never "none"; the pass rewrites "a model never reviews its own family's work" as *prefer another family*, with a fresh session of the builder's family when no other can run.
## After installing packs, record choices, a docs index and their router rows once.
- `2026-11-06`, a live Q&A product built before a billing rule: reading the rule against the code found both reads it forbids while every unit test passed; its development instance then confirmed that every API-token and MCP call from a paid workspace had been getting the free plan's AI allowance.
## Every new task opens its rows again.
- `2026-10-29`, the owner's call: a content repository run by agents already reloaded its matching files after every compaction, and once a session was not enough.
## File a rule at the fire point, not at its topic home.
- `2026-08-07`, a content repository: a rule governing a drafting-time decision was filed in the strategy file, loaded only in strategy sessions; the owner had to ask "when is strategy read?" before it moved.
## Script repeated product work and route each command from the entry file.
- `2026-11-05`, a remote-control product: its production smoke, auth canary, update-feed and UI checks are scripts beside its tests, each with its command.
## Each instruction and area file has a word budget, held by a check that runs.
- `2026-10-25`, a content repository run by agents: its rules had grown to about 330,000 words that no session could read, rules competed for attention and almost none was ever removed. It was rebuilt with a word budget per file, a checker and a write-time hook.
## Ask whether compliance depends on memory at the decisive moment before encoding a rule.
- `Undated`: In one agent-run repository the evidence was one-sided — everything implemented as code worked, everything implemented as a prose obligation decayed — and its sharpest instance was a two-line code bug answered with a convention, which killed a scheduled job for five days five weeks later.
## Keep status in the plan and at most three entry-file lines.
- `Undated`: A live Q&A product's status section grew until it was most of the file every session reads, and had to be moved out at least four times in four days.
## Keep a repository's own skills general, with products as examples named by kind.
- `2026-10-23`: Owner's rule.
## Keep must-follow rules within Codex’s entry-file context budget.
- `2026-11-16`, Codex CLI 0.169.0 on Windows logged a 32,768-byte project-document budget. A 104,297-byte instruction file lost its role table. Keep required rules in the first 32 KiB or raise `project_doc_max_bytes`; explicitly open needed sections beyond the budget.
## Name a code row's moment as a diff shows it.
- `2026-11-17`, the Claude Code team's account of how it verifies changes (Addy Osmani, "How the Claude Code team thinks about verification", claude.dev, 2026-11-16, read `2026-11-17`): a change runs only the reliability checks whose trigger its diff matches, usually 3 to 10 of 39, and each check names the incidents behind it.
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: 471k | 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 |