⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

agent-instructions

phuryn@phuryn⭐ 567 stars· last commit 4d ago· 0 open issues

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.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐⭐⭐ 567 on GitHubGitHub ↗

Popular

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

License: MIT Tests Companion: pm-skills

Product Engineering

44 agent skills from shipping three live products: decide what to build, build it with Claude Code or Codex, have a second model review it, release it.

Lost at any point? Type /product:start-here (Codex: $product:start-here) and say what you have. It tells you where the work stands and what's next. Install first.

The skills work in Claude Code, Codex, Cursor, Gemini CLI, OpenCode, GitHub Copilot and any other agent that reads SKILL.md folders. Free, under the MIT License, from The Product Compass.

Who it's for

  • Product managers, founders and designers who ship with coding agents. No coding needed: you make the decisions and check the product, not every line of the code.
  • Engineers who build a product, not only the code. That means deciding what to build, and running it in production with real users and real payments.
  • Anyone working with more than one agent, where one session coordinates, another builds and a third reviews.

Built with it

Three live products by the author, built with coding agents from the first prototype to production. The skills' dated cases come from them.

AskOne's home pageStaygreen's home pageAFK Pilot's home page
AskOne: live Q&A and polls. Organizations with two roles, a paid plan, free AI moderation, Zoom and Google Meet apps, an MCP server in the official registry.Staygreen: monitoring that checks what your app answers. Probes on three continents, status pages on your own domain, alerts, an MCP server for agents. The default monitor here.AFK Pilot: four coding agents in an editor, a desktop app or a cloud machine, steered from your phone through a relay. A paid plan, MCP connectors.

What each one runs on, what's in it, and what the skills learned from it: CASE-STUDIES.md.

Install

The quickest way: open your agent in the project's folder and ask in the chat:

Please install skills from phuryn/product-engineering on GitHub in this project only. Enable auto updates.

In Claude Code or the Claude desktop app, that turns the six packs on for this project only (.claude/settings.json), updating in the background. Commit that file and everyone who opens the repository in Claude Code and trusts the folder gets them too; to keep them to yourself, ask for local scope (.claude/settings.local.json). The packs load in the same session (in a terminal, if /product:start-here isn't found, run /reload-plugins). Then type /product:start-here and say what you have.

In Codex, plugins install for your user, in every project: run the Codex commands below, start a new session, then type $product:start-here. If your agent can't install from a prompt, use the commands below.

More than one agent? Claude Code and Codex read skills from different places, so install in each one you work in. When one agent coordinates and drives the others, that one needs the skills, and a builder needs app-stack installed in it for screens and an MCP server, which its brief names; a reviewer starts without them on purpose.

After installing packs, apply the agent-instructions skill once to wire the product's entry file: owner's choices starting from skill defaults, a docs index, and router rows for installed packs — a product's screens, or a mock of one → apply ui-design; a deploy-triggering push or release → apply release-gate; a review loop → apply independent-review; delegating → apply delegation; a lesson for the collection → type /agent-harness:retro (Codex: $agent-harness:retro). In a product that already has code, the same pass reads each installed skill whose area the code touches against that code and adds the tests those skills name that it lacks.

Claude Code

claude plugin marketplace add phuryn/product-engineering
claude plugin install product@product-engineering
claude plugin install ai-shipping@product-engineering
claude plugin install agent-teams@product-engineering
claude plugin install agent-harness@product-engineering
claude plugin install app-stack@product-engineering
claude plugin install work-humanizer@product-engineering

These install for your user, in every project. Add --scope project to each line for this project only (.claude/settings.json, shared once committed), or --scope local for yourself here.

Then turn on updates, which third-party marketplaces don't do by default: /plugin → Marketplaces → product-engineering → enable auto-update. To update by hand: Update marketplace on the same screen, or claude plugin update <pack>@product-engineering.

With project-scope installs in several worktrees of one repository, check each worktree's entry in ~/.claude/plugins/installed_plugins.json after an update (projectPath and gitCommitSha): the command may act on another worktree's record. (2026-11-07, a live Q&A product, Claude Code 2.1.319: with three worktrees, an update changed another worktree's record, then reported "already at the latest version" while the invoking worktree stayed on the old commit; the same day, updating to v1.6.0, it reported all six packs updated under the other worktree's path.)

Codex

codex plugin marketplace add phuryn/product-engineering
codex plugin add product@product-engineering   # and the other packs

Codex reads this repository's Claude Code marketplace as it is, and every skill runs there. The four you start run only when you name them: $product:start-here, $ai-shipping:ship-check, $agent-harness:handover, $agent-harness:retro. The rest also start themselves when you ask in plain words. To update: codex plugin marketplace upgrade product-engineering, then a new session.

When Claude Code hands a build to Codex, Codex reads only the packs installed in Codex, so install there what its builds need: app-stack for screens and an MCP server.

Any other agent (Cursor, Gemini CLI, OpenCode, Copilot, Windsurf …)

npx skills add phuryn/product-engineering          # pick skills and agents interactively
npx skills update                             # later, to update

npx skills needs Node.js 22.20 or later; on an older Node it fails with does not provide an export named 'glob'. Upgrade Node, or run it through a temporary Node 22: npx -p node@22 -p skills -c "skills add phuryn/product-engineering".

Or copy skill folders by hand into the folder your agent reads (.agents/skills/, .claude/skills/, .cursor/skills/, ~/.gemini/skills/ …). Every skill works from its own folder alone. A skill both copied and installed as a pack loads twice: keep one, and prefer the pack, which updates.

Using pm-skills too? The two work together: pm-skills covers discovery, strategy, research, execution and go-to-market; this collection covers building, shipping and running the product with coding agents.

  • Its AI Shipping Kit moved here, as the ai-shipping pack. Its skills and commands in pm-skills now only point here, so once ai-shipping is installed, turn off pm-ai-shipping. Its id is in `claude plugin lis

// HOW IT'S BUILT

// FILES

10 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • agent-harness/skills/agent-instructions/SKILL.md18 KBc0cf0712d2fdupstream ↗
    ---
    name: agent-instructions
    description: "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."
    ---
    
    # Agent instructions — rules met at the moment they apply
    
    **Meet each rule at the moment it applies.** A rule written down is not yet a rule an agent follows. This skill writes and maintains an app repository's instruction file as the product grows.
    
    **Use the entry file to route every session's context.** The entry file is `AGENTS.md`, `CLAUDE.md`, or both. It is where every session enters and what routes the rest. The method is stack-independent; examples come from repositories named by kind.
    
    1. **The entry file routes; the depth lives where the moment sends you.** A rule the agent is not looking at when it acts does not exist for that act.
    2. **Make rules that depend on memory at decisive moments into code paths.** Use a test, script or required argument, because prose loses that contest.
    3. **Maintain the file at every release and fix every mistake with its receipt.** Maintain it rather than accumulating rules.
    
    ## The shape: a chain, not a manual
    
    **Root routes to entry points; entry points route to operative files; operative files link to evidence.** Each layer points down; none restates the layer below.
    
    ```
    entry file (loaded every session)   — routes; holds only what every session needs
     └─ router rows: "when you are…"    — the rule that is easy to miss, and what to open
         └─ operative files (docs/, skills) — the procedure, the depth, the gotchas
             └─ evidence                — receipts, tables, postmortems, case studies
    ```
    
    - **Route, don't summarize.** A summary of a doc in the entry file is a second copy that drifts. Carry the one sentence that must be met at the moment (the rule that is easy to miss) and its pointer.
    - **No workflow content duplicates upward.** When a procedure appears in two layers, the upper copy is wrong within a month.
    - **Make every file reachable from the entry file the day it is created.** `scripts/check_reachable.py` holds this (§ Files).
    
    ## The entry file: two sections
    
    **Separate reusable building mechanics from the choices for this app.** The preamble explains the two sections in a few lines and names where the longer material lives. It tells the agent to find its moment in the router before starting.
    
    - **Put the mechanics of building any app in Section 1.** Include ownership and authorization, threat model, stack and its choices, testing and delivery, working rules, router and file maintenance. Reuse these mechanics in the next product; replace its owner's choices and installed-pack inventory.
    - **Put this app's identity and constraints in Section 2.** Include what it is, its users, its shape, who can do what, scope, data constraints and three lines of status. Replace this section per product; the `app-lifecycle` skill has its skeleton.
    - **Section 1 wins on mechanics; Section 2 wins on product.** What neither says follows skill defaults. Where those are silent too, decide and say so in the summary.
    - **When a library's default conflicts with the file, the file wins.** Say this in the file wherever a vendored skill or quickstart would teach otherwise.
    
    **Record the owner's departures from skill defaults once, dated and in their words.** Put product choices in a short entry-file section beside testing and working rules. Put choices for every product in user-level instructions. Record model, builder, reviewer and fallback, review bar, what requires go, design taste and voice.
    
    **Precedence: current session owner instruction > product entry file > user-level instructions > skill defaults.** Design detail can stay in the kit README, with an entry-file pointer; apply the `ui-design` skill.
    
    **Give every reviewer a fallback, never “none”.** Apply the `independent-review` skill for reviewer choices. Rewrite “a model never reviews its own family's work” as “prefer another family”. Use a fresh session of the builder's family when no other can run.
    
    **Graduate standing choices to the file immediately.** Memory in one agent does not reach another vendor's builder or reviewer (`references/maintenance.md`). Copy `references/agents-md-skeleton.md` for a starter file.
    
    **After installing packs, record choices, a docs index and their router rows once.** Route a product's screens, or a mock of one, to applying `ui-design`. For existing code, read every installed skill that touches it against the code. Add the missing tests the skills name.
    
    ## Make sure it loads
    
    **Keep one master instruction file and verify every agent reads it.** A file that did not load fails silently.
    
    - **Keep no `CLAUDE.md`, or make its first line `@AGENTS.md`.** Claude Code reads `AGENTS.md` when no `CLAUDE.md` exists; a `CLAUDE.md` or `CLAUDE.local.md` without `@AGENTS.md` silently stops `AGENTS.md` loading (observed on Claude Code 2.1.292, `2026-10-10`). Codex, Cursor and Grok read `AGENTS.md`.
    - **Frameworks write into these files.** Next.js 16's `next dev` appends to `AGENTS.md` and writes a `CLAUDE.md` (observed `2026-08-27`). Set `agentRules: false` in `next.config.ts` to stop it. A generated `CLAUDE.md` holding only `@AGENTS.md` is harmless; anything else is a second, unowned instruction file.
    - **After changing either file, ask a fresh session to quote its unique rule.** Choose a rule only the entry file holds.
    
    ## The router — what opens when
    
    **Key router rows by the task the agent is doing.** Put a three-column table in Section 1: “When you are…” · “The rule that applies” · “Open”. The agent matches its moment, not a table of contents.
    
    - **Use the words a user would use, never a topic label.** For example: “pushing a branch that deploys (*just push it* is this row)”, “fixing a bug”, “touching sign-in, roles or a permission”.
    - **Put the rule that is easy to miss in the rule column.** Keep it to one or two lines; the file holds the depth.
    - **The open column names the file — and the section — to read before acting.** Several rows can hold at once; open every one that matches.
    - **Every new task opens its rows again.** Find the moment and reread every file its rows open, even one read earlier in the session. After compaction or a long session, that earlier read is gone or stale.
    - **Give every rule placed in a doc a row, with one exception.** It needs none if it lives in the file the agent is already editing when it applies.
    - **File a rule at the fire point, not at its topic home.** Put it in the task's chain where it must change a decision. The topically natural file keeps the durable record and a pointer. Reachable in the wrong task is unreachable.
    - **Index material with no moment in the docs' own index.** Worked examples and release history belong there, not in the router.
    
    Read `references/router.md` for the pattern in depth and a starter router for an app repository.
    
    ## Where each thing goes
    
    | What | Where it lives |
    |---|---|
    | needed in every session, with no trigger that would send the agent looking | the entry file, Section 1 or 2 |
    | needed only when touching one area | that area's file: the doc its router row already opens, or a new one where there is none, routed the day it is made; re-read at the start of every task that touches it |
    | reusable method | the installed skill; product docs, checks and automation stay in the product's repository, reachable from the entry file |
    | product procedures, gotchas, depth | the product doc the row opens; a procedure run by hand a second time becomes a product script, with its command in the matching router row |
    | receipts, data tables, postmortems behind a rule | an evidence file, opened only when revisiting the rule |
    | the current status | the product's plan (its stages, each with what it produces and the test of done, and where each stands); at most three lines in the entry file |
    | what a release shipped, what its rounds and gates found | the release history (one dated section per release, never rewritten), moved there at the next release |
    | a decision that had options | the decision log (dated: the options, what was picked, by whom and why) |
    | an owner's departure from skill defaults | once, dated and in their words: the entry file for product choices, user-level instructions for global choices; design detail in the kit README with an entry-file pointer |
    | installed packs | the entry file: each agent and the packs installed in it; the packs update themselves, so nothing pins a version; never assume another agent loads the coordinator's install |
    | deferred work | the backlog, each item with the reason it waits and the trigger that reopens it |
    | a behaviour correction from one conversation | memory, until it graduates; standing owner choices go straight to instructions (`references/maintenance.md`) |
    | what is true of one product only | that product's repository, never a shared skill |
    | a rule whose compliance depends on memory at the decisive moment | a test, a script or a required argument |
    
    **Script repeated product work and route each command from the entry file.** Especially script releases, review rounds and briefs, the owner's preview and extra checks. A release script runs only after the owner's clear go, for that one authorized release. The release doc names the steps the owner keeps; apply the `release-gate` skill.
    
    ## Always-on rules: an admission test and a cap
    
    **Admit only rules that must fire across every task after classification.** Most rules wait for their router row. A short always-on list in the entry file holds the exceptions, such as “before spawning any subagent, set its model explicitly”. Each entry passes every admission test:
    
    - it fires after task classification, so no router row would catch it;
    - missing it does material harm;
    - there is evidence it was missed repeatedly;
    - it fits in two lines;
    - nothing mechanical can enforce it — if something can, it becomes code instead.
    
    **The list has a cap (ten bullets worked); a new entry replaces one.** Its entries route, they don't summarize. Without a cap the always-on list becomes the manual again.
    
    ## Budgets: every file short enough to read in full
    
    **Each instruction and area file has a word budget, held by a check that runs.** An over-budget file is one no session reads in full, and a rule not read is not met.
    
    - **Keep budgets in one root `budgets.json` and run their checker in the gate.** Map each path or glob to a word count. Copy `scripts/check_budgets.py` into the repository; it fails on an over-budget file or a key matching no file. Start at the current count, rounded up, when a session can read the file in full. Otherwise propose the cut and resulting budget; the owner decides.
    - **One in, one out.** Every edit replaces or tightens before adding. Only the owner removes a rule's text. Tighten wording without dropping a condition, exception or receipt. Or move the rule to its fire point, leaving a pointer, or add its test or hook and propose removal. A move is not a removal. At the budget, the owner picks the rule a new one replaces, or raises the budget.
    - **Give every added rule its receipt and a review date.** Record the date and what happened, or the owner's words and date, then `(review YYYY-MM)`. The checker lists rules past their date. At release, put each to the owner to re-earn or delete; delete none yourself. Never retire a rule guarding an irreversible or outward-facing step for want of a new incident. A promotion, migration, publish or secret rule works by preventing one.
    - **Budget every new area file the day it is made.** Except data such as receipts, research and tables that no session is told to read in full.
    
    ## Prose vs. code
    
    **Ask whether compliance depends on memory at the decisive moment before encoding a rule.** If yes, prose will lose. Use a required argument, script, validation or test that runs. Writing it down feels like fixing it, which makes the reflex invisible from inside. Keep prose for taste and judgement, short and routed to. Read `references/prose-vs-code.md` for the full evidence and app-repository forms of a code path.
    
    ## The working rules every app's file carries
    
    Each has a receipt (`references/working-rules.md`):
    
    - **Read the instruction file before the first plan.**
    - **Apply skill defaults without asking.** Ask only if a default's builder or other non-reviewer model or CLI is missing or out of usage, with no runnable product fallback. Reviewers always fall back as the `independent-review` skill requires. Get the owner's clear go each time before anything irreversible or outward-facing, such as production, publishing, spend or deleting anything public. Questions about what the product should do are still the owner's.
    - **No play-by-play.** Plan, build, summarize once.
    - **Commit messages go through a heredoc (`git commit -F -`), never `-m "…"`.** A backtick inside `-m` is command substitution, and the text vanishes silently.
    - **A fix that carries an exclusion says, in its comment, why the excluded case does not need it.**
    - **A comment stating an invariant about a value protects only its file.** List every route that can receive the value and check each.
    - **When a flag's meaning widens, rename it to what it does.** Don't name it for one of its reasons.
    - **When the file is silent, apply skill defaults, then decide and report.** Decide only where the skills are silent too; say so in the summary.
    - **Report a doc's disagreement with code you did not change.** The owner picks which side moves.
    - **Include tests and doc lines in the change, never a later step.**
    
    ## The two passes
    
    **Manage the file without asking, except for removing a rule's text.** Propose that removal; the owner decides (§ Budgets). Two moments call for a pass:
    
    - **Read the file top to bottom at every release.** Ask of each part: is it obsolete now code exists? Does it belong in a doc with a pointer here? Is it needed every session, or only in one area whose router row should hold it? What did this phase teach the next session? Move status and release narrative out (below), then run the reachability check.
    - **Fix mistakes in the file immediately when its missing or poor wording caused them.** Include the receipt: date and what went wrong, so the rule carries its reason. Then ask whether the fix should be code.
    
    **Keep status in the plan and at most three entry-file lines.** Name the current stage, what is in production and what waits on whom, never the story. At each release, move the previous release's narrative to release history. Only the rules it taught stay in Section 1.
    
    **Within its budget, no size target.** Judge by what a fresh session needs to start well, not by length. Some things earn permanent entry-file space; others that feel obvious today will be missing context in a month. A smart reader with the right context is the goal.
    
    ## Writing a rule
    
    **Cite the violation before adding a rule.** A rule earns its place with evidence of a real failure. Patterns from an outside style guide or linter are ideas, not rules.
    
    - **Keep each receipt's date and what happened, naming the product by kind.** The receipt is why a later reader trusts the rule. The reason is the sentence they can check and find false.
    - **Prefer replacing or generalizing a rule to adding one.** If the same check keeps firing, fix the principle upstream instead of adding another check.
    - **Choose deliberately between a codifiable rule and a judgement principle.** Codify only when “is X present? yes/no” gives a useful answer; codifying judgement flattens it into checklist behaviour.
    - **Date what a platform did or required and correct its line when it changes.** Use “verified on” or “observed”; never leave the old line beside the new.
    
    ## When the repository writes its own skills
    
    **Keep a repository's own skills general, with products as examples named by kind.** They sit beside vendored skills and may be published; “a live Q&A product” is an example. Product-only facts belong in that product's repository, never in the skill. This includes listings and their states, versions, verified clients, receipts, commits, release codes, ids and account names.
    
    **Date what a platform did or required, since it changes.**
    
    Each rule's origin, the case that taught it, is in `receipts.md` beside this file; read it when a rule's edge is unclear.
    
    ## How you can tell it worked
    
    A fresh session given only the instruction file meets each rule at the moment it applies, because the router sent it there. Every rule the file carries has its receipt.
    
    ## Files
    
    | File | Holds | Read when |
    |---|---|---|
    | `references/agents-md-skeleton.md` | a starter `AGENTS.md`: preamble, Section 1 with a router, Section 2 | creating the file for a new repository |
    | `references/router.md` | the router pattern, how to key and word rows, a starter router for an app repository | writing or changing the router; a rule that was missed at its moment |
    | `references/maintenance.md` | the release pass and the mistake pass, progressive-disclosure rules, filing without accretion, evidence vs. rules, memory graduation, orphans | a release; after a mistake; the file has grown; adding a doc |
    | `references/prose-vs-code.md` | the test, the evidence, the receipts, and the forms a code path takes in an app repository | about to write a rule to prevent a recurrence |
    | `references/working-rules.md` | the working rules with their reasons and receipts | writing Section 1; a rule here was broken |
    | `scripts/check_reachable.py` | lists docs no chain from the entry files reaches (standard library only; reads, writes nothing) | after adding a doc; at every release |
    | `scripts/check_budgets.py` | counts each budgeted file's words against `budgets.json`, fails over budget or when a key matches no file, and lists the rules past their review date (standard library only; reads, writes nothing) | in the test gate, from a copy in the repository; at every release |
    
    ```bash
    python <skill dir>/scripts/check_reachable.py <repo>                       # docs/ and knowledge/ by default
    python <skill dir>/scripts/check_reachable.py <repo> --scope .claude/skills --exclude "docs/screenshots/**"
    python <skill dir>/scripts/check_reachable.py <repo> --why docs/TESTS.md   # print the chain that reaches it
    python <skill dir>/scripts/check_budgets.py --root <repo>                  # words per file, past review dates
    ```
    
  • agent-harness/skills/agent-instructions/scripts/check_budgets.py2.6 KB01d783abf2f3upstream ↗
    #!/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())
    
  • agent-harness/skills/agent-instructions/scripts/check_reachable.py6.5 KB2d7840644b03upstream ↗
    #!/usr/bin/env python3
    """check_reachable.py — find instruction and doc files no session can reach.
    
    A rule an agent never opens is not a rule it follows. This walks the chain an
    agent walks: it starts at the entry files every session loads (AGENTS.md,
    CLAUDE.md), follows every reference to another file — markdown links, paths in
    backticks, `@path` imports — and reports the markdown files under the scope
    directories that no chain reaches.
    
        python <skill dir>/scripts/check_reachable.py <repo>
        python <skill dir>/scripts/check_reachable.py <repo> --scope docs --scope .claude/skills
        python <skill dir>/scripts/check_reachable.py <repo> --exclude "knowledge/raw/**"
        python <skill dir>/scripts/check_reachable.py <repo> --entry AGENTS.md --why docs/TESTS.md
    
    Defaults: entries are AGENTS.md and CLAUDE.md at the repository root (whichever
    exist); scope is every existing one of docs/ and knowledge/. A reference to a
    directory reaches its README.md, SKILL.md or INDEX.md, or, when it has none, every
    .md file directly inside it. --exclude drops data files (fixtures, raw captures)
    from the scope by glob, relative to the root. Exit 0 when every file in
    scope is reachable, 1 when some are not, 2 on a usage error. Standard library
    only; it reads files and writes nothing.
    """
    import argparse
    import re
    import sys
    from collections import deque
    from fnmatch import fnmatch
    from pathlib import Path
    
    LINK = re.compile(r"\]\(([^)\s]+)(?:\s+\"[^\"]*\")?\)")       # [text](path "title")
    TICK = re.compile(r"`([^`\n]+)`")                             # `path § section`
    IMPORT = re.compile(r"(?:^|\s)@([\w./-]+\.md)\b", re.M)       # @AGENTS.md
    INDEX_NAMES = ("README.md", "SKILL.md", "INDEX.md", "index.md")
    SKIP_DIRS = {".git", "node_modules", ".next", "dist", "build", ".venv", "venv"}
    
    
    def candidates(text):
        """Every string in a markdown file that might name another file."""
        for m in LINK.finditer(text):
            yield m.group(1)
        for m in TICK.finditer(text):
            token = m.group(1).strip().split()[0] if m.group(1).strip() else ""
            yield token
        for m in IMPORT.finditer(text):
            yield m.group(1)
    
    
    def resolve(raw, here, root):
        """Resolve one reference to existing files, or nothing."""
        ref = raw.split("#", 1)[0].split("?", 1)[0].strip().strip(",;:.)(\"'")
        if not ref or "://" in ref or ref.startswith("mailto:") or "<" in ref or "*" in ref:
            return []
        if ref.startswith("/"):
            ref = ref.lstrip("/")
            bases = [root]
        else:
            bases = [here, root]
        out = []
        for base in bases:
            try:
                target = (base / ref).resolve()
            except (OSError, ValueError):
                continue
            if root not in target.parents and target != root:
                continue
            if target.is_file():
                out.append(target)
                break
            if target.is_dir():
                index = [target / n for n in INDEX_NAMES if (target / n).is_file()]
                out.extend(index or sorted(target.glob("*.md")))
                break
        return out
    
    
    def walk(root, entries):
        """Breadth-first over references; returns {file: the file that reached it}."""
        reached = {e: None for e in entries}
        queue = deque(entries)
        while queue:
            current = queue.popleft()
            if current.suffix.lower() != ".md":
                continue
            try:
                text = current.read_text(encoding="utf-8", errors="replace")
            except OSError:
                continue
            for raw in candidates(text):
                for target in resolve(raw, current.parent, root):
                    if target not in reached:
                        reached[target] = current
                        queue.append(target)
        return reached
    
    
    def in_scope(root, scopes, excludes):
        files = []
        for scope in scopes:
            base = (root / scope).resolve()
            if not base.exists():
                continue
            for path in base.rglob("*.md"):
                rel = path.relative_to(root)
                if any(part in SKIP_DIRS for part in rel.parts):
                    continue
                if any(rel.match(pattern) or fnmatch(rel.as_posix(), pattern) for pattern in excludes):
                    continue
                files.append(path.resolve())
        return sorted(set(files))
    
    
    def chain(file, reached, root):
        steps = []
        while file is not None:
            steps.append(file.relative_to(root).as_posix())
            file = reached.get(file)
        return " <- ".join(steps)
    
    
    def main():
        ap = argparse.ArgumentParser(description="Report markdown files no entry file reaches.")
        ap.add_argument("repo", help="repository root")
        ap.add_argument("--entry", action="append", help="entry file, relative to the root (repeatable)")
        ap.add_argument("--scope", action="append", help="directory whose .md files must be reachable (repeatable)")
        ap.add_argument("--exclude", action="append", default=[], help="glob of files to leave out of the scope (repeatable)")
        ap.add_argument("--why", help="print the chain that reaches this file, then exit")
        args = ap.parse_args()
    
        root = Path(args.repo).resolve()
        if not root.is_dir():
            print(f"not a directory: {root}", file=sys.stderr)
            return 2
        names = args.entry or ["AGENTS.md", "CLAUDE.md"]
        entries = [(root / n).resolve() for n in names if (root / n).is_file()]
        if not entries:
            print(f"no entry file found among {names} in {root}", file=sys.stderr)
            return 2
        reached = walk(root, entries)
    
        if args.why:
            target = (root / args.why).resolve()
            if target in reached:
                print(chain(target, reached, root))
                return 0
            print(f"{args.why}: not reached from {', '.join(names)}")
            return 1
    
        scopes = args.scope or [s for s in ("docs", "knowledge") if (root / s).is_dir()]
        if not scopes:
            print("no scope: pass --scope <dir> (no docs/ or knowledge/ here)", file=sys.stderr)
            return 2
        files = in_scope(root, scopes, args.exclude)
        orphans = [f for f in files if f not in reached]
        print(f"entries: {', '.join(e.relative_to(root).as_posix() for e in entries)}")
        print(f"scope: {', '.join(scopes)} - {len(files)} files, {len(files) - len(orphans)} reachable, {len(orphans)} not")
        for f in orphans:
            print(f"  unreachable: {f.relative_to(root).as_posix()}")
        if orphans:
            print("\nEach one needs a reference from the file an agent has open at the moment the rule applies -")
            print("a router row in the entry file, or a link from the entry file's chain - or it is proposed to the owner for retiring.")
        return 1 if orphans else 0
    
    
    if __name__ == "__main__":
        sys.exit(main())
    
  • agent-harness/skills/agent-instructions/references/agents-md-skeleton.md21 KBf2fbc3becdccupstream ↗
    # A starter AGENTS.md for an app repository
    
    Copy the fenced block at the end of this file into the repository's root as `AGENTS.md`. Keep no `CLAUDE.md`, or one whose first line is `@AGENTS.md` (`SKILL.md` § Make sure it loads).
    
    How to adapt it:
    
    - **Section 1's mechanics are general; its owner's choices and pack inventory are the product's.** It was written for SaaS apps on Next.js + Supabase + Clerk + Netlify; lines marked *(stack)* name that stack's mechanism — replace them with your own stack's, keep the principle. Lines that point at a skill (`the release-gate skill`) assume this collection is installed; if it is not, point them at your own docs.
    - **Section 2 is the product.** The `app-lifecycle` skill fills it at the brief stage (its `references/product-section.md` explains each heading).
    - **Paths** (`docs/…`) are defaults. Use your own, and keep the router's *Open* column true to them: `scripts/check_reachable.py` in this skill lists any doc the file no longer reaches.
    - **Delete what the product does not have** — the anonymous-public lines, billing, embedded agents — rather than leaving them as noise every session reads.
    
    ---
    
    ```markdown
    # AGENTS.md
    
    Master instructions for every coding agent in this repository. Claude Code reads this file when there is no `CLAUDE.md`; a `CLAUDE.md` or `CLAUDE.local.md` that does not import `@AGENTS.md` stops it loading, so there is none (or one whose first line is `@AGENTS.md`).
    
    Two sections. **Section 1 is how we build any app** — reuse its mechanics; replace its owner's choices and pack inventory. **Section 2 is this app** — replace it. When they conflict, Section 1 wins on mechanics and Section 2 wins on product. What neither says follows the skills' defaults; where those are silent too, it is the agent's call: decide, and say so in the summary. The longer material lives in `docs/`; **§ 1.8 says what opens when — find the moment you are in before every new task.** The path from idea to production is the `app-lifecycle` skill; each stage's done-when lives in `docs/product/plan.md`.
    
    ---
    
    # 1. How we build (general — reuse across apps)
    
    ## 1.1 Ownership and authorization
    
    - **Everything belongs to a workspace**, and § 2.3 declares what a workspace is (an organization, or one user). Nothing but the `workspaces` table references the identity provider's ids (and, where the product records authorship, one member table: `saas-authorization`): the product keys on its own row.
    - **Two credentials, never mixed:** a verified member session, and — only when the product has an anonymous public — an anonymous token (random, hashed at rest). Member routes never trust the anonymous token; public routes never read session claims. **Another kind of caller**, where the product has one, gets an entry of its own beside these, never folded into either: API tokens for outside agents (`saas-authorization`, `references/threat-model.md` § Leaked tokens and credentials), or a platform's statement about its user (`mcp-server`, `references/server.md`). Without an anonymous public, delete the token's half; without another caller, delete that entry. (`2026-10-30`, an evals product whose only other caller was an API token, from day one, had to rewrite this line.)
    - **Deterministic code enforces what is risky or hard to undo.** A screen, a client, a prompt or a model may propose; whether an action that crosses a trust boundary or cannot be taken back happens is decided by server code — a function, a constraint, a hook.
    - **Three functions carry the model; no route reads raw claims:** resolve the thing from the URL, require the visitor (anonymous public only), require workspace access with a permission.
    - **Permissions are strings; roles map to them; check permissions, not roles.** A screen gates a control on the same permission its action checks.
    - **Roles decide who may act; billing features decide how much.** They never touch.
    - **Invariants are database constraints, not application code.** Ids in URLs are unguessable; not-found and not-owned return the same 404.
    - The model, its reasons and receipts: the `saas-authorization` skill.
    
    ## 1.2 Threat model
    
    Untrusted text, abuse and floods, cross-tenant access, leaked tokens, a leaked database, anonymous identity, webhooks, scheduled work, secrets — and embedded agents when the product has them. Each class and its rule: the `saas-authorization` skill. Secrets are never in the repository, a URL, a log line or a client bundle.
    
    ## 1.3 Stack, and the choices already made on it
    
    <The stack, one line. (stack) Example: Next.js (App Router, TypeScript) · Tailwind + the kit in `design/` · Supabase Postgres · Clerk · Netlify · Vitest + Playwright.>
    
    A new product proposes these choices rather than re-deriving them, and reopens one only by saying in § 2.3 that its trigger fired. The choices, with their rules, reasons and receipts: the `app-lifecycle` skill (default choices).
    
    - <choice> — **Reopen:** <trigger>.
    
    ## 1.4 Database — how we use it
    
    <(stack) The choices the vendor's own skill cannot make: who the only database client is, what row-level security means here, how schema changes ship, what the agent's database connection is for. Each in one line; the depth: the `supabase-production` skill.>
    
    - **The host's deploy does not apply migrations, and nothing warns you; the database provider's git integration may.** If it is set to apply on push to production, or nobody has read that setting, a migration you don't mean to run never sits in the migrations directory. Before any promotion, read the production migration ledger and dry-run what is pending; after the owner's go, apply it by CLI with the target spelled out, then push.
    
    ## 1.5 Identity — how we use it
    
    <(stack) Verify, never decode; store ids only; authorization lives with the data, not in a path list; the provider's own components are the sign-in surface. The depth: the `clerk-production` skill.>
    
    ## 1.6 Testing and delivery
    
    - **Read the exit code from the log, never the notification.**
    - **An inherited report is a claim, not evidence.** Re-run the gate yourself before repeating a count; take a release's subject from git, not prose.
    - **`docs/test-coverage.md` is written by whoever ran the gate, by nobody else.**
    - **Default: an independent review before every push to a branch that deploys and at every promotion, however small the change.** A fresh session that never saw the build reads the unreleased diff plus the working tree, unsteered; fix, re-run the gate yourself, review again until no INTRODUCED finding above Low and no High or Critical of any age. The session that wrote the code never clears it: apply the `independent-review` skill.
    - The harness and the gate: the `test-harness` skill. How a change ships: the `release-gate` skill.
    
    ### Owner's choices and installed packs
    
    Skill defaults apply. Departures: <none, or each choice once, dated and in the owner's words: model, builder, reviewer with its fallback, review bar, what requires go, design taste and voice>. A reviewer always has a fallback, never "none"; prefer another family, with a fresh session of the builder's family when no other can run (`independent-review`). Product choices live here; global choices live in user-level instructions. **Precedence: current session owner instruction > this entry file > user-level instructions > skill defaults.** Memory in one agent does not reach another vendor's builder or reviewer: record standing choices here immediately. Design detail: `design/README.md`; apply the `ui-design` skill.
    
    Installed packs: <each agent → the packs installed in it>. They update themselves; nothing pins a version.
    
    ## 1.7 Working rules for the agent
    
    - Read this file before the first plan.
    - **Apply skill defaults without asking.** Ask only when a builder or other non-reviewer model or CLI a default names is missing or out of usage and the product records no fallback that can run; reviewers always fall back as the `independent-review` skill requires. Get the owner's clear go each time before anything irreversible or outward-facing (production, publishing, spend, deleting anything public). Questions about what the product should do are still the owner's.
    - **Tests and docs are part of the change.** A bug fix lands with a regression test that fails before the fix; every change updates the doc lines it made false.
    - **A doc that disagrees with code you did not change:** say so in the summary; the owner decides which side moves. When this file is silent, the skills' defaults apply; when they are silent too, decide and say so. When a library default conflicts with this file, this file wins.
    - Every new environment variable: a placeholder in `.env.example`, a row in `docs/variables.md`, a line in the env schema that fails when it is missing — run at build, not only at boot. A value you generate rather than fetch is generated now, written into `.env`, and named in the summary.
    - **No play-by-play.** Plan, build, summarize once.
    - **Commit messages go through a heredoc (`git commit -F -`), never `-m "…"`**: a backtick inside `-m` is command substitution, and the text vanishes silently.
    - **A fix that carries an exclusion says in its comment why the excluded case does not need it.** A comment stating an invariant about a value protects only its own file: check every route that can receive the value.
    - **When a flag's meaning widens, rename it to what it does**, not to one of its reasons.
    - **A stage is done** when its done-when in `docs/product/plan.md` holds, the gate is green on your own run, its tests and docs landed — and, when it changes what a person sees, once the owner has tried it from a link and a short list.
    - **Delegation:** use the builder and fallback in Owner's choices above; <what never delegates — deciding what the product does, accepting a review finding, anything touching a real system, development included (any database, even one only you use, a server, a setting), the judgement that a stage is done>. If the brief would be nearly as long as the diff, write the diff (apply the `delegation` skill).
    - **Proposing steps:** when planning a phase, propose the capabilities whose trigger has fired (the `app-lifecycle` skill).
    - **Skills teach method; this repository owns its docs, checks and automation**, reachable from this file. A procedure run by hand a second time becomes a script, its command in the matching § 1.8 row: release, review round and brief, owner's preview, extra checks. The release script runs only after the owner's clear go, for the release that go authorizes; `docs/RELEASE.md` names the steps the owner keeps.
    
    ## 1.8 What opens when
    
    At the start of every new task, find the moment you are in — several can hold at once — and open what its row names **before** you act, even a file you read earlier in the session: after a compaction or a long session that read is gone or stale. The rule column is the part that is easy to miss; the file holds the depth. What has no moment (worked examples, the release history) is indexed in `docs/README.md`.
    
    | When you are… | The rule that applies | Open |
    |---|---|---|
    | starting a session, or planning a phase or a stage | Read this file first. Propose the capabilities whose trigger has fired; the plan that introduces the database names the workspace table, the three functions and the first migration | `docs/product/plan.md` · `docs/product/brief.md` · the `app-lifecycle` skill · `docs/architecture.md` |
    | starting a new product, or asking what comes next | One path from idea to production; each stage has what it produces and its done-when | the `app-lifecycle` skill |
    | choosing between options, or reopening a decision or a § 1.3 choice | An earlier decision may already have weighed them | `docs/product/decisions.md` · the `app-lifecycle` skill (default choices) · `docs/product/strategy.md` only once the owner confirmed one |
    | delegating a stage, or wanting a peer to argue a decision | Only when the builder is available; write it yourself when the brief would be nearly as long as the diff. A stage's follow-up rounds resume its session; a new stage starts fresh | the `delegation` skill · the `codex-agents` skill · `docs/work/` |
    | building a feature or changing behaviour | Its tests and its doc lines land in the same change | `docs/TESTS.md` · the doc that describes the behaviour |
    | fixing a bug | A regression test that fails before the fix; the doc that described the old behaviour, corrected | `docs/TESTS.md` (rules that came from bugs) |
    | touching sign-in, workspaces, roles, a route or a permission | The three functions; a screen gates on the same permission its action checks; a cross-tenant test on every route that touches data | `docs/permissions.md` · the `saas-authorization` skill |
    | changing a journey with side effects — writes, email, jobs, money | | `docs/flows.md` |
    | writing a query or a migration | The schema is the source, not memory; migrations by CLI with the target spelled out; a rename or drop the deployed code still reads ships in two steps | `supabase/migrations/` (newest first) · the generated types · the `supabase-production` skill |
    | touching an integration's configuration (identity, database, host, DNS, email, analytics) | Read the gotchas first; each failed silently once | `docs/integrations.md` · the `clerk-production` / `supabase-production` skill |
    | touching environments, branches, backups or an incident, or rolling back | The target is stated, never inferred from a config file; a previous deploy goes back only once it is known to run against the current schema | the `environments` skill · `docs/environments.md` |
    | adding or reading an environment variable | Placeholder, row and schema line; the schema runs at build; a generated value is generated now | `docs/variables.md` · `.env.example` |
    | a product's screens, or a mock of one | apply `ui-design`; without a provided design system, start the kit before the first app screen (an artifact before it keeps its values in tokens), then extend its primitives so buttons, fields and dialogs stay one set; a screen claims only what its feed can see | the `ui-design` skill · `design/README.md` |
    | writing framework code | <(stack) This framework version is newer than your training data> | <(stack) the framework's bundled docs, e.g. `node_modules/next/dist/docs/`> |
    | creating or removing a git worktree | Never remove one whose `node_modules` links to another checkout: delete the link first | the `independent-review` skill (its worktree recipe) |
    | writing or running a test or extra check, or claiming something is verified | Use the product's check commands; the harness's runs column says gate, outside the gate or by hand; read exit codes from the log; the coverage map is written by whoever ran the gate | `docs/TESTS.md` (gate and extra-check commands) · `docs/test-coverage.md` · the `test-harness` skill |
    | reading a doc that disagrees with the code | Say so in the summary; the owner decides which side moves | at release, proposed to the owner: the `document-app` and `derive-tests` skills in `check` mode (they write nothing) |
    | deferring anything, or asked what remains | Every deferral has a reason and a revisit trigger | `docs/BACKLOG.md` |
    | **pushing a branch that deploys** — "just push it" is this row | A clean review round covering everything the push adds; the push closes it. Migrations applied first to the database that deploy reads (production's only at a promotion, after the go). A push deploys one runtime: every other one (workers, an edge) keeps its last bundle until redeployed, so check each one's build against the tree after the push. Name back any precondition still open rather than pushing past it | the `independent-review` skill · the `release-gate` skill |
    | saying a stage or a phase is done | Its done-when, the gate green on your own run, its tests and docs in the change; a change a person sees, once the owner has tried it | `docs/product/plan.md` · the `release-gate` skill (the owner's preview) · `docs/RELEASE.md` (preview command) |
    | **releasing** — promoting to production | Use the product's release doc and existing script: the whole-range review, the audits proposed, the production ledger, then stop for the owner's **go**; steps the owner keeps are named | the `release-gate` skill · `docs/RELEASE.md` (release command and owner steps) |
    | running a review loop or triaging a finding | Apply `independent-review`; use the product's round and brief commands; a finding is a claim, its severity included | the `independent-review` skill · `docs/RELEASE.md` (review commands) |
    | writing or checking a core doc — architecture, permissions, flows, variables, the coverage map | The definition is the minimum; this file wins where they differ | the `shipping-artifacts` skill · `docs/README.md` |
    | adding email, a scheduled job, automation or search | Document only what exists; unimplemented scope is a backlog row | the conditional doc once the capability exists |
    | adding a fail-closed guard or hosted CI | Never in the same change as the product it guards | the `release-gate` skill |
    | embedding an agent | <only when § 2.3 says so> | the `embedded-agents-messages-api` skill |
    | adding an MCP server | Every call authenticated unless a decision chose otherwise and named the cost | the `mcp-server` skill |
    | writing one of this repository's own skills, or adding a lesson to one | General guidance: a product appears only as an example, named by kind; what is true of one product goes in its own repository; date what a platform did | the skill's own `SKILL.md` |
    | learning a lesson for the shared collection | Keep the product's incident in its docs; send only the general lesson to the collection | type `/agent-harness:retro` (Codex: `$agent-harness:retro`) |
    | editing this file, or after a mistake this file should have prevented | Fix it in the moment with the receipt; route, don't summarize; a rule that depends on memory at the decisive moment becomes code | the `agent-instructions` skill |
    
    ## 1.9 This file is yours to manage
    
    This file is the context you carry into every session. You own it: edit it without asking, except removing a rule's text, which you propose and the owner decides; moving a part to `docs/` with a pointer here is an edit. Two moments call for a pass over it:
    
    - **At every release:** read it top to bottom and ask of each part — is it obsolete now that the code exists? does it belong in `docs/` with a pointer here? is it needed in *every* session, or only when touching one area (then § 1.8 is its home)? what did this phase teach that the next session must know?
    - **When a mistake happens:** if the cause was something this file should have said — or said badly — fix it here, in the moment, with the receipt (date, what went wrong), so the rule carries its reason.
    
    **The status lives in `docs/product/plan.md`; § 2.7 carries at most three lines of it.** At each release, move the previous release's narrative to `docs/history/release-history.md` and keep only the rules it taught, in Section 1.
    
    The principle is **progressive disclosure**: this file is the entry point every session reads; § 1.8 opens the next layer only when the task needs it; `docs/` holds the depth. **A rule written down is not yet a rule an agent follows: it must be met at the moment it applies.** So every rule placed in `docs/` gets a § 1.8 row, keyed by what the agent is doing in words a user would use, unless it lives in the file the agent is already editing when it applies. Judge by what a fresh session needs to start well, within each file's word budget (`budgets.json` at the root, checked by a copy of `check_budgets.py` in the test gate; create both with this file, as the `agent-instructions` skill's budgets section says; one in, one out).
    
    ## 1.10 Embedded agents (only when the product has them)
    
    <Delete when § 2.3 says no.> The agent proposes; deterministic code decides. Everything a model reads or writes is untrusted text. Cost has two ceilings — per run and per actor. Model ids are pinned in code. The depth: the `embedded-agents-messages-api` skill (or `embedded-agents-agent-sdk`).
    
    ---
    
    # 2. This app — <product name>
    
    This section holds only what every session needs about the product. The brief behind it is `docs/product/brief.md`; the phases and their status are `docs/product/plan.md`; the decisions and their options are `docs/product/decisions.md`.
    
    ## 2.1 What it is
    
    <The product and its complete core journey in one short paragraph: who uses it, what they do, what they get.>
    
    ## 2.2 Users
    
    <One line per user group: who they are and how they are identified. Name the payer, and the anonymous public if there is one.>
    
    ## 2.3 Product shape and reopened defaults
    
    - **Workspace model:** <organization | individual>
    - **Billing:** <the identity provider's billing | none>
    - **Anonymous public:** <yes | no>
    - **Embedded agents:** <yes | no>
    - **Member home:** <the route sign-in lands on>
    
    Reopened defaults: <each § 1.3 choice this product changes — the choice, the trigger that fired, what replaces it, the dated entry in `docs/product/decisions.md`. Or: none.>
    
    ## 2.4 Who can do what
    
    <Actor × identity × can × cannot; the permission strings; when the product bills, the feature slugs the code gates on and what each unlocks.>
    
    ## 2.5 Not in scope
    
    <The adjacent capabilities this product deliberately excludes.>
    
    ## 2.6 Constraints that shape the data
    
    <Invariants, limits, ownership and lifecycle rules — each a sentence a migration can be checked against. Stated here and nowhere else.>
    
    ## 2.7 Status
    
    <At most three lines: the current stage, what is in production, what is waiting on whom.> Full status: `docs/product/plan.md`; past releases: `docs/history/release-history.md`.
    ```
    
  • agent-harness/skills/agent-instructions/references/maintenance.md9.5 KBbb046c1b1cd5upstream ↗
    # Keeping the instructions working
    
    The instruction file is the agent's to manage: it edits it without asking, the way it edits code, except removing a rule's text, which it proposes and the owner decides (`SKILL.md`, budgets). What keeps a file that is edited by every session from rotting is two passes, a few filing rules, and a check that runs.
    
    ## The release pass
    
    At every release, read the entry file top to bottom and ask of each part:
    
    1. **Is it obsolete now that the code exists?** A rule written to steer a build that has since landed: name the test or doc line that now holds it, adding one if none does, then propose its text to the owner for removal (`SKILL.md`, budgets).
    2. **Does it belong in a doc, with a pointer here?** Depth that only one area needs moves out, and the router gets the row.
    3. **Is it needed in *every* session, or only when touching one area?** Only one area → the router is its home.
    4. **What did this phase teach that the next session must know?** Add it, with its receipt.
    
    Then, in the same pass:
    
    - **Move the status out.** The plan holds the status; the entry file keeps at most three lines — the current stage, what is in production, what is waiting on whom — with a link. (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.)
    - **Move the release narrative to the history.** What the previous release shipped, what its rounds and gates found, goes to the release history; only the rules it taught stay, in Section 1.
    - **Run the reachability check** (below), and route what it lists; what has nowhere to go, propose retiring.
    - **Run the budgets check**, and put each rule it lists as past its review date to the owner (`SKILL.md`, budgets).
    
    In a release checklist this is one line: *the instruction file reviewed — obsolete parts proposed to the owner for removal, documented parts moved to docs with a pointer, this phase's lessons added; the status current, and its three lines with it.*
    
    ## The mistake pass
    
    **When a mistake happens, and its cause was something the file should have said — or said badly — fix it in the file, in the moment, with the receipt**: the date and what went wrong, so the rule carries its reason. Not at the end of the session, and not in a note to fix later: the moment is when the cause is understood.
    
    Then ask the two follow-up questions:
    
    - **Which router row should have fired?** (`router.md` § When a row failed.)
    - **Could this be code instead?** If compliance depends on the agent remembering the sentence at the decisive moment, it will be missed again (`prose-vs-code.md`).
    
    ## Progressive disclosure, as rules
    
    1. **Every file in the knowledge layer is reachable** through a chain that starts at the entry file's router (entry file → operative file → sub-file), or at the docs' catalog.
    2. **Every tool is referenced** from a tools index or from the doc that uses it.
    3. **New files are routed immediately** — added to the right index or parent file when created, not later.
    4. **The entry file's router is the entry layer.** It routes to doctrine and never summarizes it. A new file rarely needs a router row; it needs a reference from the right file in an existing chain.
    5. **Memory is not a substitute for structure.** An agent's memory is for behaviour corrections, not for routing to tools or knowledge files: a route or owner choice that lives only in memory is invisible to another vendor's builder or reviewer and to the next machine. Standing choices go straight to the entry file or user-level instructions (`SKILL.md` § The entry file).
    6. **Separate evidence from rules.** A file over about 200 lines where rules and their supporting data coexist splits: the rules stay where the router points, and the methodology, tables and postmortems move to an evidence file, opened only when revisiting a rule or running a new analysis. The rule file links to its evidence; the evidence file is never the one the router opens.
    
    ## Filing without accretion
    
    The failure mode of an agent-maintained instruction file is not neglect; it is accretion — every lesson added as a rule until the file reads like a compliance checklist and the agent works from rules instead of principles.
    
    - **Update proactively.** When the next move is obvious — a missing rule, an outdated pattern, a better framing, a gap caught mid-task — edit the file. Ask the owner only when the change needs the owner's judgement (a genuinely new principle, retiring a rule, a taste call: `SKILL.md`, budgets).
    - **The default filing mode is evidence, not rules.** A new learning usually lands as a receipt or a calibration under a rule that already exists. **A genuinely new rule is rare**, and should usually replace or generalize one.
    - **Rules earn their place with evidence.** Every rule is loaded into every future context. Before adding a rule or a check, cite the violation: which change, which incident, what failed. Patterns from an outside linter or style guide are idea sources, not rule sources — filter them through "does this repository actually do this?" (`2026-04-18`, a content repository declined four patterns from an external linter for lack of any violation.)
    - **Choose deliberately between a codifiable rule and a judgement principle.** Ask whether the rule needs mechanical checking or judgement in context. Codifying judgement flattens it into checklist behaviour. Default to a principle when nuance is real; codify only when "is X present? yes/no" gives a useful answer. (`2026-04-26`, from a critique of over-codification in the same repository.)
    - **Two lanes, never mixed.** *Judgement* lives in principles and must fit working memory at the moment of the work. *Lint* — mechanical checks — stays a short end-pass and never grows judgement.
    - **If a check fires repeatedly, fix the upstream principle** instead of adding a check.
    - **A rule that has never caught anything is sediment**, unless it guards an irreversible or outward-facing step, which works by preventing what it would catch. Rules earn their place by measured effect; one that has caught nothing across dozens of uses is put to the owner, who retires it (deleted, or moved to the history) or keeps it. The agent retires none on its own (`SKILL.md`, budgets).
    - **When a session starts to feel rule-bound rather than principle-led, say so** to the owner; that is the signal for a consolidation pass.
    
    ## Memory → instructions: when a correction graduates
    
    An agent's memory holds behaviour corrections and facts that vary by conversation. The instruction file holds rules that apply to all future work.
    
    **Promote a memory into the instruction file (or the doc its row opens) when:**
    
    - it states a factual rule that applies to every future task of a type, not just a preference for today;
    - it has been confirmed twice, or survived a postmortem;
    - losing it would cause a repeatable mistake, not just mild friction.
    
    **When promoting**, move the rule text into the file where the router already finds it, and delete the memory — two copies drift.
    
    **Keep in memory, don't promote:** conversation-specific facts about the user's role or preferences, rather than standing owner choices; project-state facts that decay ("the merge freeze begins on…"); pointers to external systems ("pipeline bugs are tracked in…"); tactical workarounds for ephemeral bugs.
    
    ## Orphans — the check that holds reachability
    
    ```bash
    python <skill dir>/scripts/check_reachable.py <repo>
    python <skill dir>/scripts/check_reachable.py <repo> --scope docs --scope .claude/skills
    python <skill dir>/scripts/check_reachable.py <repo> --exclude "docs/screenshots/**" --exclude "knowledge/raw/**"
    python <skill dir>/scripts/check_reachable.py <repo> --why docs/TESTS.md
    ```
    
    It starts at the entry files (`AGENTS.md`, `CLAUDE.md`), follows every markdown link, backticked path and `@` import, and lists the markdown files under the scope that no chain reaches; exit 1 when there are any. `--why` prints the chain that reaches one file. Data files that are not instructions (captures, fixtures, raw exports) are left out with `--exclude`.
    
    **Run it** after adding docs or tools, after any restructure, when you suspect a file is not being discovered, and at every release.
    
    **Fix each orphan by routing it to the parent that owns its moment:**
    
    | Orphan | Route it from |
    |---|---|
    | a doc holding a rule | a router row keyed by the moment it applies, or a link from the file that row opens |
    | an evidence file | the rule file it supports |
    | a case study or worked example | the docs' catalog (it has no moment) |
    | a tool or script | the tools index, or the doc that tells the agent to run it |
    | a new area of docs | its index, plus the entry chain — a router row only for a genuinely new task class |
    | none of these | propose retiring it to the owner: deleted, or moved to the history |
    
    A file nothing reaches is a rule nobody follows. Routing it is the fix; noting it is not.
    
    ## The chain, drawn
    
    For a repository whose knowledge is deep enough to need it, draw the chain once in the maintenance doc, so a restructure can be checked against it:
    
    ```
    entry file (always loaded, a few KB — a dispatcher)
    ├── router → one entry file or a few operative files per task class
    │   ├── building or changing behaviour → test rules, the doc for the behaviour
    │   ├── releasing → the release procedure
    │   └── maintaining these instructions → this file
    ├── always-on rules (capped) → the files they route to
    └── precedence → which file wins when two disagree
    
    docs index = catalog + governance (what each file holds, which wins), NOT a second router
    ```
    
  • agent-harness/skills/agent-instructions/references/prose-vs-code.md5.9 KBbc21e8de98d6upstream ↗
    # Prose vs. code — where a rule actually belongs
    
    **The test, before encoding any rule:** does compliance depend on an agent holding this sentence in working memory at the decisive moment? If yes, prose will lose — it is competing with everything else the agent has read — and the rule belongs in a **code path**: a required argument, a script, a validation, a check that runs.
    
    A reviewing model's diagnosis of one agent-run repository, verified against that repository: *"a writer's exoskeleton that answers every failure by writing, in a medium where only scripts are load-bearing."*
    
    ## The evidence
    
    Filed `2026-07-25`, after an audit day of one agent-run content repository where the pattern held without a single exception. Everything implemented as **code** worked; everything implemented as **prose obligation** decayed:
    
    | Implemented as | Outcome |
    |---|---|
    | a reconcile script | backfilled faithfully, every time |
    | a script that writes each item's performance record | recorded the failures as diligently as the successes — no survivorship filter |
    | a *rule* to emit a record at ship time | failed **26 of 43** ships; a reconcile job silently covered for it, which taught the system that skipping was free |
    | hit/miss verdicts, an obligation no script computed | blank on **28 of 46** rows |
    | a retirement convention (move retired files to a folder) | **zero** such folders anywhere; never once executed |
    | an experiment tag, written into doctrine | ran seven weeks with **zero** treatment rows |
    | required metadata fields on each record | 56 filled in one month, **1** the next — which made the next month's analysis impossible to run |
    
    ## The sharpest instance
    
    On `2026-06-15` a real two-line code defect was found in a notification script: its arguments were silently discarded in non-interactive containers. The response was to write a *convention* into the agents' instructions telling future agents to pipe the message through stdin instead. The convention decayed. Five weeks later that exact bug killed a scheduled ingest job for five days, invisibly — because the job's failure alerts went through the broken path. **A confirmed code bug was answered with prose.** The patch, when finally written, was two lines.
    
    ## Corollary — writing it down feels like fixing it
    
    That is why the reflex is invisible from the inside: the artifact it produces looks exactly like diligence. Dated, well argued, filed in the right place, and inert.
    
    Same-day proof that this is not hindsight: the fix for a telemetry file that was not being committed was first specified as "tell each of the eleven scheduled jobs' prompts to commit the file" — and that was the one part that broke. It was corrected to a `--commit` flag inside the logging script itself.
    
    ## So
    
    - **Prefer the code path.** When you catch yourself writing a rule to prevent a recurrence, ask what would make the recurrence *impossible* instead.
    - **A confirmed code bug is fixed in code**, never answered with a convention for working around it.
    - **When prose is genuinely the only option** — taste, judgement, voice — keep it short, route to it rather than restating it, and expect it to need reinforcement.
    - **A rule a test or a script can hold gets one**, and the instruction file says what the test asserts, so a reader knows the rule is held and where.
    
    ## What a code path looks like in an app repository
    
    Examples from SaaS repositories built with coding agents, each a rule that used to be (or would have been) a sentence:
    
    - **A configuration rule held at build time.** Every environment variable has a line in a schema that fails when it is missing, and the schema runs from the framework's config at build and dev start — not only at boot — because a public variable is inlined into the client bundle when the build runs, and a boot check comes after the leak. It checks each key's shape where the vendor gives one. (`2026-10-10`, a product's `.env` held the identity provider's secret key in the publishable variable; the shape check caught it before anything was built with it.)
    - **A source guard.** A unit test refuses any currency literal under the source tree, so no price is ever copied into code; another refuses per-page share-card keys, so a page cannot silently discard its preview image; another refuses colour literals in the component kit's stylesheet.
    - **A test that pins documentation to code.** A legal page is checked by a test that fails when the code reaches a provider the privacy policy does not name; an MCP server's tools are checked by a test that every argument has a description and every tool an output schema.
    - **A wrapper that refuses.** A review wrapper refuses a range with no commits and a clean tree, and fails loudly when a round comes back too short to have run, instead of trusting the agent to notice a suspiciously short "all clear". An operator script refuses every option its command does not read, with a list per command, and never echoes the value it refused. (`2026-10-24`, a monitoring product: a deploy command ignored `--dry-run` and deployed development's alert sender for real; the refusal that fixed it echoed `--name=value`, which could print a pasted connection string's password; and one list shared by every command let another project's ref through to a command that deployed this checkout's environment anyway.)
    - **A required argument.** A shipping script that will not record a release without the fields the analysis needs, instead of a rule asking agents to fill them in.
    - **A validator for the instructions themselves.** A check that every doc is reachable from the entry file (`scripts/check_reachable.py` in this skill), and, for a collection of skills, one that checks frontmatter and refuses private names leaking into published text.
    
    When the entry file states such a rule, it says what holds it: "the env schema runs at build; a test refuses currency literals". The sentence then documents a guarantee instead of asking for one.
    
  • agent-harness/skills/agent-instructions/references/router.md7.1 KB00c075e1c0cdupstream ↗
    # The router — what opens when
    
    The router is the part of the entry file that makes progressive disclosure work. The entry file is what every session reads; the router opens the next layer only when the task needs it; the docs and skills hold the depth. Without it, a repository has two bad options: put everything in the entry file, which grows until no session reads it with attention, or put the depth in docs, where it is never opened at the moment it applies.
    
    A starter router for an app repository, ready to copy, is § 1.8 of `agents-md-skeleton.md`. This file is how to write and keep one.
    
    ## Anatomy of a row
    
    | When you are… | The rule that applies | Open |
    |---|---|---|
    | **pushing a branch that deploys** — "just push it" is this row | A clean review round covering everything the push adds; the push closes it. Migrations applied by CLI to the database that deploy reads, and its ledger read, first (production's only at a promotion, after the go). Name back any precondition still open rather than pushing past it | the `independent-review` skill · the `release-gate` skill |
    
    - **"When you are…"** is a moment, in the words a user would use or the action the agent is about to take. It is what the agent matches against, so it must look like the situation, not like a topic. The aside — *"just push it" is this row* — names the casual phrasing that would otherwise slip past.
    - **"The rule that applies"** is the part that is easy to miss, in one or two lines: the thing that, missed, costs a release or a day. It is not a summary of the file in the next column; it is the sentence that must be met *now*. A row may leave it empty when the file is the whole point.
    - **"Open"** names the file to read before acting — the section too, when it is one section — or the skill by name. Several are fine. A conditional is fine: "the first time for this vendor, the setup stage".
    
    Introduce the table with two sentences: **at the start of every new task, find the moment you are in — several can hold at once — and open what its row names *before* you act, even a file read earlier in the session**; the rule column is the part that is easy to miss, the file holds the depth.
    
    ## Keying rows
    
    - **One row per moment, not per document.** "Writing a query or a migration" and "touching environments, branches or an incident" may open the same doc; they are different moments with different easy-to-miss rules.
    - **Use the user's words and the agent's verbs.** "Fixing a bug", "saying a stage is done", "adding an environment variable", "reading a doc that disagrees with the code". Not "Testing", "Environments", "Docs".
    - **Name the moment, not the area, when the trap is in the moment.** "Creating or removing a git worktree" deserves its own row because one command (`git worktree remove --force` through a linked `node_modules`) empties another checkout; it would be invisible under "Git".
    - **Bold the rows where a mistake is public or irreversible** — the push that deploys, the promotion to production — so they stand out when scanning.
    
    Worked rows from an app repository:
    
    | When you are… | The rule that applies | Open |
    |---|---|---|
    | fixing a bug | A regression test that fails before the fix; the doc that described the old behaviour, corrected | the test rules (rules that came from bugs) |
    | writing a query or a migration | The schema is the source, not memory; migrations by CLI with the target spelled out; a rename or drop the deployed code still reads ships in two steps — add the new, drop the old once the build reading it is live | the migrations directory, newest first · the generated database types · the `supabase-production` skill |
    | writing framework code | This framework version is newer than your training data | the framework's own bundled docs (for Next.js, `node_modules/next/dist/docs/`) |
    | deferring anything, or asked what remains | Every deferral has a reason and a revisit trigger | the backlog |
    | adding a fail-closed guard or hosted CI | Never in the same change as the product it guards | the `release-gate` skill |
    
    ## What gets a row
    
    - **Every rule placed in a doc gets a row**, keyed by what the agent is doing when it applies — unless the rule lives in the file the agent is already editing at that moment (a migration-writing rule at the top of the migrations README, say).
    - **Installed packs get rows for their moments; product scripts get their commands in those rows.** Skills teach method; the product owns the release, review-round/brief, preview and extra-check commands. A procedure run by hand a second time becomes a script, routed from the entry file; `agents-md-skeleton.md` has the starter rows.
    - **File at the fire point, not at the topic home.** A rule lands in the chain of the task where it must *change a decision*; the topically natural file keeps the durable record and a pointer. A rule reachable only from the wrong task is unreachable. (`2026-08-07`, a content repository: a rule governing a decision taken while drafting was filed in the strategy file, which only strategy sessions loaded; the owner had to ask "when is strategy read?" before it moved.)
    - **A new file rarely needs a row of its own**; it needs a reference from the right file in an existing row's chain. A row is for a genuinely new moment.
    - **What has no moment** — a worked example, the release history, a case study — is indexed in the docs' own index, not the router. That index is a catalog (what each file holds, which wins when two disagree), never a second router.
    
    ## Two ways to point
    
    - **Rows point at several operative files** (an app repository): the row names exactly what to open, and the files are small and specific.
    - **Rows point at one entry file per task class, which owns its own load sequence** (a content repository with deep, layered doctrine): the root says only "drafting a post → this file", and that file says what it loads, in order. The root never restates the sequence.
    
    Either way, **root routes to doctrine; it never summarizes it.**
    
    ## Reading the router
    
    The entry file tells the agent, in its own words:
    
    - **Classify the request before substantive work, and read every matching row's files top to bottom, as hard constraints.**
    - **Several rows match → read all of them.** No row matches but the task touches the repository's knowledge → start at the docs index.
    - **Do not substitute memory, a summary, or a read from a previous session.** Reload at the start of every new task, after a compaction and at session start. A quick self-test: *can I quote, right now, the rule that applies to what I am about to do?* If not, the file has not been read in this context.
    
    ## When a row failed
    
    When a mistake happens, ask which row should have fired:
    
    - **No row matched the moment** → add the row, keyed by what the agent was doing, in the words it would have used.
    - **A row matched but the agent acted before opening the file** → the rule column did not carry the part that was easy to miss; put that sentence there.
    - **The row fired, the file was read, and the rule was still missed at the decisive moment** → prose has lost; make it a code path (`prose-vs-code.md`).
    
    Write the fix with its receipt — the date and what happened — so the row carries its reason.
    
  • agent-harness/skills/agent-instructions/references/working-rules.md6.8 KBa11a980171feupstream ↗
    # Working rules — the discipline every app's instruction file carries
    
    Section 1 of an app repository's instruction file carries a short list of working rules: how the agent reads, reports, commits and comments. Each below has its reason and, where it came from an incident, its receipt. They were learned on SaaS repositories built with coding agents; they hold on any stack.
    
    ## Read the instruction file before the first plan
    
    The plan is where an unread rule does its damage: a plan built without the ownership model or the stage's done-when is rebuilt later. For an app, the plan that introduces the database names the workspace table, the authorization functions and the first migration (the `app-lifecycle` and `saas-authorization` skills).
    
    ## No play-by-play
    
    Plan, build, summarize once. Narration spends the owner's attention on progress instead of on the decisions that need them, and buries the one line that matters. Status lines only when blocked or when a run will take long.
    
    ## Apply defaults; record the owner's choices
    
    Use the defaults without a questionnaire; unavailable builder or other non-reviewer models or CLIs without a usable product fallback and irreversible or outward-facing actions are the points that need the owner, as `SKILL.md` § The working rules says. Reviewers always fall back as the `independent-review` skill requires. Record standing departures once in the entry file or user-level instructions, so another agent can find them. (Owner, `2026-11-05`: "Don't want to overcomplicate that.")
    
    ## Commit messages go through a heredoc
    
    `git commit -F -` with a heredoc, never `git commit -m "…"`.
    
    - **Reason:** commit messages in these repositories are full of backticked identifiers, and a backtick inside a `-m` argument is command substitution: the shell runs the word and replaces it with its output, which is usually nothing. The text is deleted **silently**, nothing warns you, and the message cannot be fixed after a push without a rewrite.
    - **Receipt:** a commit in a sibling repository landed reading *"Grok sends , so"*.
    - **The same trap, elsewhere:** a file generated through a shell into an interpreter is rewritten the same way, as silently. Read the bytes it produced.
    
    ```bash
    git commit -F - <<'EOF'
    Fix `resolveRoom` returning a closed room to `requireVisitor`
    EOF
    ```
    
    The quoted delimiter (`'EOF'`) is what stops the shell from expanding anything inside.
    
    ## A fix that carries an exclusion says why the excluded case does not need it
    
    When a fix carves out a case, the comment must say why that case does not need the fix. A comment that describes the bug being fixed leaves the carve-out invisible to everyone who reads it afterwards — including the next pass over the same bug. **That sentence is the thing a later reader can check and find false.**
    
    ## A comment stating an invariant protects only the file it is in
    
    A comment that states an invariant about a value — *never parse, reflect or store X* — protects only the file it is written in. List every route that can receive that value and check each one, because the comment cannot. A vendor may send a credential to more of your URLs than the one you registered as its callback. When one validates the parameter for its own meaning, **a rejection there is a dead end, not a validation success**: strip the parameter and carry on (a redirect also takes the credential out of the address bar, history and referrer). Keep not-found for a well-formed value that names nothing.
    
    - **Receipt:** `2026-09-22`, a live Q&A product's install route kept such an invariant while its home page parsed the meeting vendor's OAuth code as its own code, rejected it and answered not-found on every fresh install in production.
    
    ## When a flag's meaning widens, rename it to what it does
    
    A prop named for one reason (`busy`) becomes a sentence the next reader has to decode at the second call site. Name the behaviour (`undismissable`) and keep each call site's reason in a comment.
    
    - **Receipt:** `2026-09-20`, a live Q&A product's dialog took a second, unrelated reason to refuse dismissal (a secret shown once, which dies when the dialog closes).
    
    ## When the instruction file is silent, the skills' defaults apply; past them, decide and say so
    
    The skills' defaults cover what neither section of the file does; the agent decides what they don't cover either, and says what it decided in the summary, so the owner can correct it and the file can learn it. **When a library's default conflicts with the file, the file wins** — vendored skills and quickstarts teach their own defaults, and the file is where the product's choices against them are written.
    
    ## A doc that disagrees with code you did not change is reported, not resolved
    
    Say so in the summary and let the owner decide which side moves. The agent does not know whether the doc is stale or the code is wrong; picking a side silently either deletes a requirement or blesses a bug. At a release, the read-only checks the owner picks, which list every mismatch between docs, coverage map and code — and write nothing — make the list complete (the `document-app` and `derive-tests` skills, each in `check` mode).
    
    ## Tests and docs are part of the change
    
    A bug fix lands with a regression test that fails on the broken behaviour and passes with the fix. Any other behaviour change lands with the tests the test rules ask for, in the harness whose *runs* column says where it runs — in the gate, outside it, or by hand — and the summary says which. Every change updates the doc lines it made false. (The `test-harness` skill.)
    
    ## Rules that belong to other skills, which Section 1 still names in a line
    
    These are working discipline too; their depth lives elsewhere, and Section 1 carries the sentence and the pointer:
    
    - **Read the exit code from the log, never the notification** — a background wrapper can report exit 0 while the command inside it failed (`test-harness`).
    - **An inherited report is a claim, not evidence** — re-run the gate yourself before repeating a count, and take a release's subject from git, not prose (`release-gate`, `independent-review`).
    - **The coverage map is written by whoever ran the gate, by nobody else** (`test-harness`).
    - **The session that wrote the code never clears it** — an independent review before every push that deploys and every promotion (`independent-review`).
    - **If a delegation brief would be nearly as long as the diff, write the diff** (`delegation`, `codex-agents`).
    - **Before handing the owner a task, do every part of it you can** — through an API, a CLI, a key you hold — and pass up only what needs a person: a dashboard-only click, money, taste. A delegate's "commands for the owner" are a claim about who can run them (`delegation`).
    - **A generated secret is generated, written into `.env` and named in the summary**, never left as an empty placeholder nobody can look up (`environments`).
    
  • agent-harness/skills/agent-instructions/receipts.md2.9 KBdd96816300bcupstream ↗
    # 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.
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/phuryn-product-engineering-agent-harness-skills-agent-instructions.md

// REPO STATS

567 stars
0 open issues
Last commit: 4d ago