skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
udecode/dotai60 installs

sync-pstack

Set up the pstack plugin in a project through an interview, and keep every pstack project on one pinned tag and one shared AGENTS.md overrides block. Use to set up or install pstack in a repo, sync, bump or update pstack everywhere, list which projects use pstack or have drifted, compare setups, audit a project's skills for drift from pstack (which to cut, fold or keep), change which work runs a panel, architect or an arena without asking ("from now on X runs architect"), or move a workflow lesson, including a plan page shape change, into every project. Not for choosing pstack's per-role models, which setup-pstack owns.

How do I install this agent skill?

npx skills add https://github.com/udecode/dotai --skill sync-pstack
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    A comprehensive set of tools for setting up and synchronizing the pstack plugin across development projects. It manages configuration, enforces coding and review rules, and includes a security guard to prevent destructive git operations by the agent. The skill makes extensive but intended use of git and GitHub CLI tools to manage project lifecycles.

  • Socketwarn

    2 alerts: gptSecurity, gptAnomaly

  • Snykfail

    Risk: CRITICAL · 4 issues

What does this agent skill do?

Sync pstack

One skill sets pstack up in a project and keeps every set-up project in step with upstream pstack and with one shared set of overrides. Project-only rules never sync.

Setup brings the shared layer: the plugin pin, the overrides block, its helpers, typed entry points kept for retired controllers, a routing table and a proof skill. It does not bring a project's own knowledge, such as its source authority, domain laws or review scenes; those stay the project's work, and the domain skills come through setup untouched.

Layers

LayerLives inChanged by
UpstreamThe pstack@pstack-claude plugin at a pinned tag, in each project's .claude/settings.json, the user's ~/.claude/settings.json and the user's Codex marketplacesync --tag and user-pin. pstack itself is never edited.
Sharedassets/block.md, rendered between the pstack:begin and pstack:end markers of each project's AGENTS.md, plus the helpers in assets/pstack/, copied to .agents/pstack/, and the rule files in assets/pstack/rules/, rendered like the block into .agents/pstack/rules/An edit to this skill's source in the dotai checkout, then a sync
Project.agents/pstack.json, which holds the interview's answers, the project playbooks in .agents/playbooks/, which the block lists, and every rule outside the block, which wins over itThe project, by hand or through setup

Run the script

Run node <skill>/scripts/sync-pstack.mjs <command> from any directory.

CommandEffect
discover <project>Prints the facts the interview needs as JSON. Read-only.
status [project...]Shows the latest upstream tag (and an upstream VERSION that runs ahead of it), the user pins, and each project's pin, drift, vendored copies and last source revision. Without project paths it finds the local pstack projects from the repository sets in ~/.agents/config.json, their parent directories and each --root <dir>. It skips linked git worktrees, because each gets the sync through the branch it checks out. sync without project paths syncs the same set. A managed project whose config sets autoSync to false is held: status, sync and corpus without project paths list it as held and skip it, and a run that names it treats it like any other project. Read-only.
apply <project>Writes the block, the helpers and the project pin from the project's config. --tag checks that pstack at that tag still has the text every note and project playbook quotes, and refuses it otherwise. When the tag differs from the pinned one, it also refuses to compare against a pinned tag upstream lacks, prints the bump report Sync step 3 reads, and writes only with --dispositions <tsv> holding one row for each item that report lists. --dry-run shows the block diff and lists the other writes. --force overwrites an edited block or helper, or renders from a source older than the project's last sync; it never skips an anchor. It refuses to write the main checkout of a trunk project whose clone sets pstack.delivery; such a project syncs in a worktree and lands the result.
check <project>Exits 1 when apply would change anything. Read-only.
verify <project>Exits 1 when a command or argument-hint mode typed in this project's history no longer resolves (unless dropped lists it), a project skill has a dead link into the skill tree, a rule file names a retired skill, a skill the docs tell users to install depends on this project's workflow files, check would change anything, a block or rule-file rule carries no note, or pstack at the pinned tag lacks text an override or a project playbook anchors on. Read-only; it reads chat history only when a skill or a mode was cut since HEAD, which takes minutes, so run it once, in the background with its output in a file, after the last apply.
sync --tag <tag> [project...]Runs apply --tag on the named projects, or on every managed project that is not held when none are named, and lists the unmanaged and held ones. It refuses a checkout that is off the project's branch or has uncommitted edits to the files it writes, unless --allow-dirty, and keeps going when one project fails.
playbook <project> <name>Prints the numbered steps of every pstack playbook that .agents/playbooks/<name>.md extends, at the project's pin, with its changes applied in order. Text outside the steps, such as the Reply line, is left out. Read-only.
smoke <project> <prompt>...Runs each prompt in a read-only Claude Code session on Opus from the project root and prints its final answer. --runtime codex runs a read-only Codex session on gpt-6.2-sol instead, and --runtime both runs both in parallel. Its answers prove routing only; judge them by Setup step 6. The Claude Code session is the CLI in plan mode, without the desktop app's session tools. The project's hooks run, but setup.mjs skips its writes there.
corpus [project...]Runs the project's installed decisions-check.mjs and this skill's copy, uncommitted edits included, over the project's ledger and the decision-log rows added since its first commit (--all, chips, chips stale), and prints the difference. Both chips runs read one copy of the ledger. Each --all run reads the live logs, so rerun corpus before trusting a difference in a log that another session may have written between the runs. Without project paths it runs on every managed project status finds, except the held ones. --session <id> passes this session's id to chips, --installed <dir> reads the old side from a saved copy of one project's helpers, and --out <dir> also writes each side's full output there. Read-only.
user-pin --tag <tag>Pins the user-scope Claude Code marketplace and prints the refresh commands. It prints Codex's every time and Claude Code's only when the user settings declare the pstack marketplace, then a claude plugin update for each project whose project-scope pstack install is older than the tag.
latestPrints the newest upstream tag.

A project's rule files are its AGENTS.md, every Markdown file under .agents/ except the skills in .agents/skills/, each file in the project that AGENTS.md names by a Markdown path or an @ import, and each file a rule file imports with @, resolved against the importing file's folder as Claude Code resolves it. The bump report, verify and the audit read them. A folder link under .agents/ counts while its target stays in the project. verify also searches every file the project's git or its companion's git tracks, reports without failing each one outside the rule files that names a retired skill, and fails when a search fails. Its dead-link check reads the inline links in a project skill's text, outside fenced blocks and inline code. It misses a dead link written with a title, an angle-bracket target or a target on the next line, or as a reference link. A triple backtick inside a sentence or a ~~~ fence also hides the text after it, up to the next fence (owner: zbeyens; stop: a dead link that gets past the check this way).

node <skill>/scripts/audit.mjs <project> [--json] [--min <score>] prints the facts the Audit mode judges; --min sets the overlap score a sentence pair needs, 0.5 by default. Read-only.

Anchor checks read pstack from a bare clone that the script makes in ~/.cache/sync-pstack/ on first use; SYNC_PSTACK_UPSTREAM points them at another clone or URL. Run the copy in the dotai checkout when one exists, the checkout whose origin is udecode/dotai. Its assets/ are the source of truth. apply and sync print the source they render from, and record in synced.source the shared commit they rendered. With that record, a refusal shows exactly what the project edited, and a copy older than a project's last sync refuses to overwrite it. Run check from the dotai checkout even when it holds edits this run did not write, because dotai's AGENTS.md commits them with the run's own.

Choose the mode

RequestMode
Set up pstack in a project, or install pstack hereSetup
Sync, bump or update pstack, here or everywhereSync
Compare setups, or list which projects use pstack or have driftedCompare, read-only
Audit a project's skills for drift from pstack, or which skills to cutAudit, read-only until the owner picks
"From now on <work> runs <architect, a panel or an arena>", or stop running oneReviews
A lesson or correction that changes a shared ruleLesson
Add or change a project's own playbookProject playbooks

A change to the shared source syncs only the project the run works in, none when the run works in dotai itself, and installs each new or changed dotai skill there, including its .claude/skills/<name> link. Another managed project syncs only when the owner names it or asks for every project, and the run never offers that sync or asks to push another project's main branch (owner's word, 2026-10-25, which replaces the 2026-10-09 rule that synced every managed project). These are the projects in scope. Setup, a pin bump or Reviews changes only the projects the request names, or every managed project when it asks for all of them. The repository sets in ~/.agents/config.json name candidates, not authorization.

Setup

  1. Discover. Run discover <project>, then read AGENTS.md and the workflow rules it routes through, in full. Nothing is written yet.
  2. Interview. This is the first step the user sees. Follow the interview: prepare from evidence, always ask about delivery, recommend the reference answers unless the project's evidence argues otherwise, and never re-ask a settled answer.
  3. Record the answers in .agents/pstack.json, with tag from latest.
  4. Adapt the project per adapt. Remove vendored pstack copies, settle orphaned skills and rule forks, keep the formatter off the synced files, rewrite project rules that duplicate or contradict the block, repoint references to removed skills, write the confirmed routing table, create the proof skill when there is none, and regenerate skills from rules.
  5. Apply. Run apply <project> --dry-run, read the diff, then run apply <project>.
  6. Verify.
    • discover reports no vendored copies, and status <project> shows the user pins at the tag. Otherwise run user-pin and its commands.
    • Each runtime's models sheet exists, ~/.claude/pstack-models.md and ~/.codex/pstack-models.md, and names the seats the block's Panel review rule uses. Otherwise run /pstack:setup-pstack before the smoke, because a session without a sheet runs pstack's default models.
    • Smoke-test both runtimes with smoke <project> "<prompt>" --runtime both, using a plain request that names a real feature: "Fake task, do not edit anything or run commands that write: <feature> resets after <action>. Walk me through what you would do, in order, in at most ten short lines: first a summary of the todo items you would open, then how the finished work lands." Judge what each runtime would do, not only which playbook it names. When a judge scores the answers, write each runtime's intended behavior from the changed instruction text before the judge sees any answer, and cite the line that requires each part. A smoke of a changed skill counts only when the session shows that skill loaded, and a read-only smoke proves routing, never the action itself. Check first that the fixture is in the state the prompt implies, for example that a plan you say is approved is not Done. Expect poteto-mode's Bug fix playbook (and the project playbook that extends it), no worktree, and the delivery answer. End each prompt by asking the runtime to list, as a numbered list, any rule conflict it notices that no rule already settles; read the whole answer and log one sort for each number whose conflict involves a rule the change touches in the project's <plans>/artifacts/smoke-conflicts.tsv, one log that every run in that clone shares and the cleanup scan never deletes, with the columns date, run, round, prompt, runtime, n, rules, conflict, sort and reason, where rules names each rule in the conflict. A clash among rules this change touches is a failure: fix it. Setup runs both runtimes, because a new project must route in each. Every other smoke, in Sync, Lesson or Reviews, runs in Claude Code alone, or in Codex alone when the changed rule binds only Codex. A change gets one smoke run per prompt, and no fix or later edit reruns it; the hand-back names each fix made after the smoke as unsmoked (owner's word, 2026-11-20). A harness artifact is a limit of the smoke's read-only mode that the real session lacks, such as plan mode blocking a scratch write or a connector a headless session lacks; note it, and word any claim that rests on it as holding under the smoke harness; the note closes it. A conflict that comes only from a fact the prompt posits closes with a note too, and a prompt whose premise draws the same note twice is reworded before the next smoke. The Claude Code smoke is the CLI in plan mode, so plan mode against "edit nothing" is always such an artifact, and the CLI has none of the desktop app's session tools, such as get_session, list_events, search_session_transcripts or start_session. The lead proves a rule that needs one of them with one real use in a desktop session, logged with that session's id, never with the smoke; without a desktop session, it is logged gap under Needs you. Any other numbered conflict gets no row and no work, even one that predates the change (owner's word, 2026-11-20). When both runtimes run, a difference between them is a failure, unless the changed rule itself prescribes it, such as a draft where one runtime refuses a send, and so is a runtime declining the action the change promises for a reason no project rule can change. Then narrow the rule and the commit body to the runtime that acts, or give the rule a fallback both runtimes follow. A conflict that only one runtime lists is not a difference between the runtimes, because each listed conflict gets its own row. An answer that reports a denied read of a file under test is inconclusive for that file's steps; log it partial. Setup also asks which model subagents run on in a second prompt, and another smoke does only when its change touches which model runs a role. Never name the playbook, the stop or the step in the prompt, or a rule's trigger in that rule's own words, because then the run proves lookup, not routing. To test a new or changed gate, such as a review, send a plain request big enough to trigger it, ask only for the todo list and the reply that hands the work back, and count the smoke passed only when the gate shows up unprompted. The runs fire the project's hooks, so a Stop hook that stages files stages the setup's changes too.
    • Run the project's lintFix over the changed code files, then run verify <project> last, so a cut typed command, a dead link, a retired name, a coupled public skill or a formatter rewrite of a synced file shows up now. Fix every problem it lists before delivering.
  7. Deliver by the project's delivery answer. For trunk, run git config pstack.delivery push in the owner's clone only when the interview's direct-push answer was yes; it is never written to the repository, and every other clone opens PRs. When it commits, the commit body names which runtimes and which of the project's committers gain or lose what, taking each runtime's claim from that runtime's own smoke answer; in user mode the reply says it, for the owner's commit. Close with the answers, the settled defaults applied, the skills removed and kept, and the verification output.

Sync

  1. Run status to see the managed projects, their pins, drift and last source, and the latest tag. Pin only a tag latest prints. A merged VERSION bump is not a release until its tag is pushed, and status says when upstream's VERSION runs ahead of its newest tag.
  2. When a newer tag exists, read pstack-claude's CHANGES.md at the new tag from the pinned tag up. Read it from the bare clone the anchor checks keep in ~/.cache/sync-pstack/ (git -C <clone> fetch -q origin --tags && git -C <clone> show <tag>:CHANGES.md), because a project rule may forbid reading files from GitHub; before the first anchor check has made that clone, use gh api 'repos/michael-denyer/pstack-claude/contents/CHANGES.md?ref=<tag>' -H 'Accept: application/vnd.github.raw'. Check each change against the block and its rule files: a playbook step, skill, principle or hook that a rule names, describes or contradicts, with or without a note. Upstream may now do what an override did; propose dropping that override. It may have changed the text an override contradicts; propose the rewrite. Then judge adoption, in each project in scope, for each skill, agent or playbook step that CHANGES.md adds or changes. Read the project's playbooks and its rules outside the block, and git grep the skill's name there before calling it unwired. Give it one verdict per project: already wired, naming the line; wire it in, naming the step or rule it joins or replaces and the gap it fills there, such as a path no other gate reviews; manual only, naming the rule that automating it would fight; or nowhere, naming what already does its job better. Weigh it against the project's existing gates and escalations, not its own description. The sync's hand-back carries this table, on the plan page when the project's rules hand back through one. Apply each proposal, a wire-in included, in the same sync, and fix the same way each gap that a step 3 disposition or a step 6 smoke conflict shows, because an upgrade must lose no quality and add no workflow friction (owner's word, 2026-11-02). A change to the block goes through Lesson, and a change to one project's playbook goes through Project playbooks. That Lesson renders and smokes each project with sync --tag <new tag> in place of its pinned tag, because a note on new upstream text refuses at the old pin. The project then lands the new pin and the fix in one delivery. The hand-back names each such change with the word that reverses it.
  3. Run sync --tag <tag> --dry-run with the projects in scope. It prints pstack's diff for every file the block, its rule files or a project playbook anchors on, because a step can change while its quoted text survives. Then it prints the diff for every other changed Markdown file of a skill the shared rules or the project's rule files name, and counts the rest per skill. Last it lists the items to review: one per hunk of each printed diff, and one per count line. Write the dispositions file in the run directory, one tab-separated row per item: the item as listed, one of none (no rule touches it), covered (its note's rule already handles it), noted (note added), rewritten (rule rewritten) or dropped (override dropped because upstream now does it), then the reason. A hunk touches a rule when it adds, removes or changes a step, output, severity, role, fallback or stop that a block, rule-file or project sentence names, describes or contradicts, with or without a note. It also touches a rule when it changes, on a runtime the project uses, a step that a rule overrides only for another runtime. So does a hunk that adds a stop or a question for the owner, which the block's Autopilot rule forbids. Such a hunk is rewritten once the rule covers that runtime or that stop, never none. covered fits only a hunk that changes nothing but the clause its note's rule replaces. A count line's reason names why none of its files touches a rule, after listing them with the git diff --name-status the report prints. The write refuses without that file, and the file is the hand-back's disposition table. This review spawns nothing, so "fast" keeps it. Before you drop or rewrite an override, and when pstack deletes a file a rule depends on, list each behavior the old text gave with its new home quoted, upstream's equivalent quoted, or a logged drop. Then git grep each project's own rules and playbooks for the changed text's terms, such as a skill's name beside the step or severity it names, and fix each claim that went false. Then run it without --dry-run. Omit the project list only when the request covers every managed project. Offer Setup for each unmanaged project it lists.
  4. Resolve each refusal.
    • Edited block or helper. The refusal shows the project's edit. Move a generic edit into the template through Lesson and a project-only edit outside the block. Nothing is lost then, so rerun with --force. Without moving it, use --force only when the owner says the edit can go.
    • Off branch or uncommitted edits. Switch to the project's branch, or wait for the owner's commit. Use --allow-dirty only when the uncommitted edits are this run's own, or when the project's rules commit only this run's hunks around another session's uncommitted work.
    • Older source. Update the dotai checkout and rerun from it; with uncommitted edits, follow Lesson step 2. When this run amended or rebased a commit a project already synced from, confirm that the whole in-block diff from apply --dry-run holds only lines from the committed template, then rerun with --force.
    • Uncommitted shared edits. The project was last synced from shared edits nobody committed, and a clean source would drop them. Commit and push them when dotai's checks pass, as dotai's AGENTS.md asks, then rerun; use --force only when the owner says they can go. When the edits were this run's own and have since landed in revised form, the refusal still fires. Run apply --dry-run, confirm its in-block diff holds only lines from the committed template, explain any diagnostic that contradicts it, then rerun with --force.
    • pstack anchors. pstack at the new tag no longer has text the block or a project playbook builds on, and the refusal shows pstack's diff. Rewrite the override through Lesson, or the playbook's change in its project, against the new text, then rerun. Drop the change when upstream now does what it did.
    • Error. A config the template cannot render. Fix the config, then rerun that project.
  5. Run user-pin --tag <tag>, then the printed commands from the home directory, except each project-scope update, which starts with its own cd. Run those updates before step 6's smoke, because a project-scope install keeps its old version and the smoke would load the old skills. Codex asks to trust the pstack hook again when its file changed.
  6. Verify each synced project with verify, and smoke-test one project per delivery mode in use, judged as in Setup step 6. Smoke one plain prompt for each playbook whose when or steps changed, one for each cut entry point, one for each new or changed gate and one for each disposition marked rewritten or dropped, not a fixed set. In a sync's smoke, upstream text never counts as the changed rule that prescribes a difference between runtimes or a stop for the owner, so such a difference or stop is a gap that step 2 fixes. When CHANGES.md adds or changes a skill or principle, also run Audit on each synced project, which reads pstack at the new pin. Judge first the project and user-scope skills whose job that skill covers.
  7. Deliver each project on its branch by its own delivery answer, committing only the files the sync wrote. A push project commits and pushes the sync, a user project leaves the change for its owner, a pr project commits the sync and pushes it straight to <branch> with no PR (owner's word, 2026-10-20), and a trunk project runs the sync in a worktree cut from origin/<branch> and lands it with land.mjs. Before a push or pr project's push, read the on: push filters of each workflow that runs on that branch. When a path the push carries would start a workflow, through a paths list that matches it, a paths-ignore list that misses it or no filter, change that workflow's filter so the path no longer starts it, and put [skip ci] in the head commit's message, because the workflow edit would start CI itself. Merge the project's branch with --no-ff instead of rebasing when the sync sits on earlier sync branches, so GitHub marks their PRs merged. Each commit body names the runtimes and committers that gain or lose what, as Setup step 7 says.

Compare

Run status. For each unmanaged project that uses pstack, read its instructions and map every override to the block as covered, a project adaptation, an explicit policy difference, drift, or unresolved. Call a rule lost only after reading the project's AGENTS.md outside the block and its setup plan's disposition table, and after searching for the behavior in more than one phrasing, because setup moves and rewords rules. Report each difference with both behaviors, their source paths and the smallest reconciliation. Suggest setup or sync, and apply nothing without a request.

Audit

Skills drift from pstack when they copy law that pstack or the block already owns, or keep a job pstack now does. This mode finds that drift so the owner can cut it.

  1. Run node <skill>/scripts/audit.mjs <project>, from the dotai checkout when one exists. It prints:
    • each project and user-scope skill's source, typed count, inbound routes and stale installed copy;
    • the block rules that carry no overrides note or adds marker;
    • sentences that repeat pstack, the block, or another file in the project. A typed count includes only what a person wrote: it skips agent, task-notification and headless records and pasted blocks, and it ignores a hit past the first 200 characters of a request longer than 2,000. A user-scope skill's count spans every project's sessions.
  2. Judge that report with the audit brief as the intent and its cut, fold or keep rubric. Run /pstack:interrogate on it only when the block's Panel review rule lets it run without asking or the owner says "panel"; otherwise the lead judges it and the verdict table names the lead as the judge. Each skill gets one verdict: cut when pstack or the block already does its job or nothing uses it; fold when its domain knowledge stays but its process text goes; keep when it holds domain knowledge pstack cannot have. Every cut names what replaces it.
  3. Hand the verdict table to the owner with AskUserQuestion, cuts grouped by project, recommended ones first. Each cut option shows its all-history typed count and a replacement checked to work in this setup. An option that deletes files counts rules, lessons, numbers and rationale separately, showing for each how many already live elsewhere, how many still need a home and how many it drops. It never offers git history as its safety, because no workflow reads a deleted file. A factual claim in an option, such as "never typed", names the check behind it. An option that moves or removes a gate names that gate in its label. A typed command loses its entry point only when the owner picks its cut, and that cut lists it under dropped in the project's config.
  4. Carry out the picks as a plan under the block's Plans and trails and Panel review rules. Rerun the usage count a cut rests on right before that cut, because sibling sessions keep using the target while the run plans its removal. Before a cut, fold or rebuild, list every rule, check and still-true lesson in the old text with its new home quoted or a logged drop, per adapt's disposition table. Freeze each row's source quote and conditions before the first destination edit. A reader who did not edit the destination checks every row whose home already existed, whose quote changed after an edit or that a script generated. Commit the table with the plan. Each workflow guide a project's AGENTS.md names gets a gate to update it, as in Lesson step 1. After cutting a dotai skill, search every managed project for its path and run each project's docs check before the cut is delivered. Uninstall a user-scope skill with npx --yes skills remove <names> -g -y from the home directory, or a project skill with npx --yes skills remove <names> -y in the project.

Reviews

The reviews list in each project's .agents/pstack.json names the work that runs a panel, architect or an arena without asking beside every pstack step that already calls for one. The user's "panel", "arena" or "full" runs one anywhere else.

  1. Read the tool's skill in full, then list every pstack playbook step and skill at the project's pin that calls the tool by default, such as Feature's design step for architect. Give each call site a row in the plan's Defaults, naming what happens to it and the word that reverses that, before the build.
  2. Turn the user's sentence into one row per project it covers: a kebab-case id and a one-sentence rule that names the work, the tool and the stage, such as { "id": "api-design", "rule": "A best-api design gets architect before its target is picked." }. Rewrite a row that already covers that work instead of adding a second, and delete a row the user retires.
  3. When a project playbook runs the tool for that work, cite the row there as (reviews: <id>), and drop the tool from any playbook step that no row covers.
  4. Run apply, then verify, which flags a playbook line that names pstack:interrogate, pstack:arena or pstack:architect without a valid citation on that line, and a config that still sets bigWork, risk or reviewPr.
  5. Smoke one plain request the row covers, and one it does not taken from the project's most common work, judged as in Setup step 6. When the uncovered request lands in a covered row anyway, tell the user, because the row then covers more than they asked for. Then deliver each project by its delivery answer.

Lesson

A lesson from /pstack:reflect, or a correction in one project, changes the shared layer only when it holds for every project. A lesson for one project goes outside that project's block. A change to the plan page shape runs these steps, and the plan-page skill's Change mode adds the renderer's specifics to steps 2, 3 and 4. A section only one project writes goes in that project's playbook frontmatter, never in the renderer.

  1. Open a todo list with each of the user's asks quoted word for word, then these gates, in order, after the last behavior edit: deslop and no-comments on helpers, unslop on block and skill prose, the tests and corpus, the helper panel, the pre-push render and one smoke run of each prompt on the final block rendered from the uncommitted dotai tree, one prompt per changed behavior, a reversed lesson's case included, with its intended behavior written before the run into an intended-behavior file in the run directory, citing the line that requires each part, as Setup step 6 asks, the dotai push, apply, verify, then the decision-trail review when one runs. A rule change that redefines what counts as evidence adds a prompt for the decision that rule judges, such as a cut for a cut rule, not only one that exercises the path that writes its result. An edit this run makes after the smoke reruns nothing, and the hand-back names it as unsmoked. The Close names the commits the trail review covered. Each workflow guide that a project's AGENTS.md names gets a gate to update it. A design restated back to the user keeps the user's own word for each state or trigger. A rule the owner says to keep gets the same treatment: the lead compares the owner's trigger with the rule's, then rewrites the rule, and every copy agents load where it applies, to the owner's scope. A plan that changes a gate follows the gate in force when the plan starts: its recommendation and Defaults apply the current rule, and an option that skips a gate the current rule requires says so.
  2. Fetch and fast-forward the dotai checkout before the first edit and again before step 5's smoke, and edit it in place, as dotai's AGENTS.md asks. Handle other sessions by the block's Other sessions rule, which plans nothing around them and acts on a conflict only when it blocks. When this run's uncommitted edits block a fast-forward, skip it until they are committed. When the push is then rejected, run git pull --rebase onto the landed change, resolve any conflict in this run's own hunks, rerun the checks and push again. Name each upstream commit that rides into a synced project. The lead never restores edits this run did not write. It commits and pushes another session's dotai edits or local commits after its own when dotai's checks pass, as dotai's AGENTS.md asks, with those edits in a commit of their own, as step 5 says. Resolve a conflict on the generated workflow-manifest.json with git checkout HEAD -- workflow-manifest.json and node scripts/build-workflow.mjs, and check out HEAD before git apply -3 on a file whose worktree copy was replaced, which apply -3 otherwise refuses.
  3. Edit assets/block.md or a helper in the dotai checkout. Keep project names, paths and commands out. A value that differs per project becomes a config field and a placeholder. Prefer an optional field used inside <!-- if key -->, because a new required field fails the render for every config that lacks it until the interview adds it. Block text that says a helper refuses something names the exact predicate it checks and what it skips. A refusal that infers a transition from free-form content compares at least two predicate designs before it is built. Once a round's fixes draw new criticals on that predicate, the next fix replaces the inference with an explicit input, such as a marker the transition writes or a recorded base commit. A helper that starts refusing an old config shape ships with its migration in the same apply write, gated on the migration's precondition. A shared rule the owner says they will iterate on moves into its own skill, and the block keeps only its authority law and a pointer to that skill. A change that retires or narrows a rule, or adds an exception to one, runs adapt's retired-policy search and fixes every hit before the first smoke. A change that adds a cap or a bound also searches every section for instructions that restart that loop, such as rerun, again or until, and bounds each one. Before editing a shared rule, run git log -S '<clause>' -- assets/block.md on the clause it changes; when a lesson added that clause, log the edit as a reversal of that lesson; its reversal row cites the step 1 prompt that smokes that lesson's case against the new text. A block rule that starts suppressing a pstack step adds one # overrides note per step, and a rule that starts depending on pstack text adds a # relies note, per Template grammar.
  4. Preview with apply <project> --dry-run on each project in scope. A helper or check change also runs the old and new copies over every artifact it judges in each project in scope and diffs the failures; for the ledger helpers that is corpus --session <id> --out <run directory>, and for a renderer, it diffs the rendered bodies too. Pass this session's id where the runtime's session tool gives one, because chips prints its started-session checks only with it. Read each line the diff adds or drops against the skill or rule step that acts on it, such as the step that handles a Do-list line under its pass header, because a changed count alone proves nothing. Before the dotai commit, the lead also opens the changed region of the real rendered page in each project in scope, because an exit status and a printed path show nothing about the content. A finding that names a real artifact closes only with a check on that artifact, never on a fixture alone. The real artifact that opened the work stays a must-refuse case and reruns after every fix round. A new or widened check judges only open artifacts, and its near-misses include a closed artifact in each role it can play and a rename or deletion of a file a closed artifact references. It runs on each template filled to the state it gates, so it can pass. For each predicate that refuses, it runs a near-miss that must pass, a near-miss that must refuse and the reverse transition, such as a reopened plan. A run with failures, or with no instance of the state a new check gates, is logged partial or gap, never verified. A newly failing file that another session holds uncommitted stays failing and is flagged with its owner, per the block's Delivery rule. Re-read a file right before logging any claim about it. The commit body gives the newly failing count per project. A helper that prints or runs a command against the user's global config is proven end to end under a scratch HOME that holds copies of that config, beside a control run, before it ships.
  5. Before the first dotai commit, a helper or check change whose design is contested gets one /pstack:interrogate round on its diff, as the block's Panel review rule says, and the lead fixes what that panel accepts, because a smoke round is a slow and partial review. Accepted fixes rerun the writing passes, the tests and corpus before the smoke. Then smoke from the uncommitted tree, because apply renders from it. For each project in scope, copy its .agents/pstack into the run directory as its corpus --installed baseline. Then render it from the uncommitted tree with sync --tag <its pinned tag> <project>, whose preflight refuses a checkout off the project's branch or with uncommitted edits to the files it writes. Copy each new or changed dotai project skill into its skill directories in place of the reinstall, install each changed user-scope skill from the local checkout with -g, and run the smoke, judged as in Setup step 6. A project that sync refuses smokes from an export instead. Extract git archive HEAD outside every git checkout, run git init and commit it there so Codex runs in a repository and reads no parent's AGENTS.md, and render the new block with apply --force. The render records no shared source, and step 6's apply records the last commit that touched assets/ while its output stays the same. A clash the smoke names is fixed in the tree before the push, so the change reaches dotai in one push. In dotai, run node scripts/build-workflow.mjs, then scripts/validate-skills --all, which checks the generated catalog and runs every skill test; it can outlast a foreground command's time limit, so run it in the background with its output and exit status in a log. Stage this run's new files with git add -- <new paths> and commit this run's paths with git commit --only -- <paths>; this commit never uses git add -A. A named path that also holds another session's hunks commits them too, and the body says so. Because dotai's AGENTS.md asks to commit everything, commit any other session's remaining edits with workflow-manifest.json in a second commit, or the manifest in the first when no such edits remain, then push both. When the owner holds the push, do not commit or push. The edits stay in the dotai checkout, a git diff of them is saved as a patch in the run directory, and the plan's Open work item names the patch, every claim that holds only once it lands and each project step 5 rendered, whose next apply refuses until the edits land.
  6. Fix a commit a project already synced from with a new commit, never an amend or rebase, because the project records it as its source. Sync each project in scope from that pushed commit, rerunning corpus <project> --installed <its step 5 baseline> --session <id> on each project's live tree right before its apply, because sessions add files mid-run. A refusal for uncommitted shared edits on a project step 5 rendered comes from this run's own edits; resolve it as Sync step 4 says. Install each new or changed skill the block names or the change edits from the local checkout, then run Sync step 6's verify, then the decision-trail review when one runs. Step 5's smoke counts for each project in scope, and no later edit or apply reruns it (owner's word, 2026-11-20). A clash the smoke names among the rules the change touches lands as a new dotai commit before any project delivers. Reinstall each new or changed project skill with npx --yes skills add udecode/dotai --skill <name> --agent codex claude-code -y so the lock records the remote source. Refresh a changed user-scope skill from the home directory with npx --yes skills add udecode/dotai --skill <name> --agent codex claude-code -g -y, then diff -q its installed SKILL.md against the dotai copy. Then run Sync step 7 for each project.

Project playbooks

A project adds its lifecycle on top of pstack's playbooks instead of in skills only the user can invoke, so plain requests reach it through poteto-mode. Each .agents/playbooks/<name>.md follows poteto-mode's Project playbooks paragraph, which defines its extends and when frontmatter and its changes anchored on a quoted run of a pstack step's own words. sync-pstack adds:

  • Optional page-lead, page-pairs and page-require lines, which name the review sections its plans write, as the plan-page skill describes.
  • An optional redesign-runs: on line. With it, in the log of a plan whose Playbook: names the playbook, decisions-check.mjs append refuses, in a panel round that holds no plan round: row, the second critical finding that is not dismissed, and each later one past the number of owners that a separate owners: row in that round names, until the log holds a row whose decision starts with redesign run:, in phase owner, or in phase verdict with evidence that names another existing .md or .decisions.tsv file in the project's plans directory. That row also lifts the design-question refusal in that log. It sees a finding only when its row is logged, after the fix that row claims. The playbook says what the run does before it logs that row, and when a round logs plan round:.
  • The block lists each playbook with its when sentence, so adding or editing one makes check fail until apply renders the block again.
  • Its stop points, when it stops where the pstack playbook does not.

**In** adds work inside a step, **Replace** swaps a step the project has already settled, and **Before** runs ahead of the step, so a change that implements belongs In the base's implementation step, never Before a design or pin step. **In**, **Before** and **After** add lines and keep every word of the base step, so a step whose words contradict the block or a project rule (delegate, commit, snapshot, an extra writing pass) needs **Replace**. A rule that limits later steps, such as who may commit, push or reply, goes **Before** the first step it limits, because agents copy the rendered steps into their todo list in order. The anchor check matches text, not order. After each edit, run playbook <project> <name>, which prints every base's steps with the changes applied in order, and read it. A playbook that extends two bases restates each change for each base.

Keep project knowledge in skills and the project's rules; a playbook only orders the work. A typed command that used to run the lifecycle stays as an entry point that names the playbook.

Template grammar

assets/block.md and each rule file in assets/pstack/rules/ are Markdown with line directives. The block keeps every rule a typical task needs and one pointer line per rule file, each naming the trigger that sends an agent to read it; a rule whose text moves to a rule file keeps its overrides notes above its pointer.

  • <!-- if key -->, <!-- if !key -->, <!-- if key=a|b --> and <!-- if key!=a --> open a region that renders when the condition holds on the project config.
  • <!-- section id --> opens a region that is dropped when the config lists id under skip.
  • <!-- end --> closes the innermost region. Regions nest.
  • {{key}} inserts a config value. A rendered line whose value is missing fails the render, and so does a skip entry that names no section.
  • A line starting with <!-- # is a template note and never renders. A note <!-- # overrides <path> "<text>" --> names pstack text the next override replaces, with <path> relative to pstack's plugins/pstack/skills/, or ../agents/<file> and ../hooks/<file> for pstack's agents and hooks; apply --tag and verify fail when that text is gone. An override carries one note per pstack step it replaces, so widening its scope adds a note for every step it newly covers. A rule that only adds to pstack carries <!-- # adds --> instead, and verify flags a rule with no note of either kind and no adds marker. A note <!-- # relies <path> "<text>" --> names pstack text that a rule describes or depends on without replacing it, such as a step, output or fallback the rule cites, and is checked the same way, so a rule that says what a pstack skill does carries one. Notes for a rule file's rules sit above its pointer in the block, the block rule that RULE_FILES in scripts/sync-pstack.mjs names for that file. A rule in that file shares the pointer's notes only when it has the pointer's name. Every other rule in a rule file carries its own notes, and verify flags one with none. A rule that repeats a name shares the noted rule's notes only when nothing but <!-- lines and indented lines separate it from the noted rule, as the variants of one rule in adjacent if regions do.
  • An indented line continues the list item above it, so a conditional sentence can join a rule. It renders onto that item's line, unless it starts a nested list item or follows one.

Boundaries

  • Never edit pstack's own files. Change its behavior through the block or a project rule.
  • Never overwrite a refused block or helper without the owner's word, unless its edit has moved to the template or outside the block.
  • Setup and sync deliver only by the project's delivery answer. They never push a protected branch, force-push or open a PR that answer does not call for, and a sync opens no PR at all, as Sync step 7 says. A pr project's sync push to its branch is the one protected push they make, even past a ruleset that asks for a PR, because the owner asked for it as a standing request (owner's word, 2026-10-20); it counts as the user's ask that a project's rule against pushing main needs.
  • The interview's settled answers belong to the owner. Ask again only when a project's evidence contradicts one.
  • Setup and sync never trim, merge or rewrite a domain skill's method. Trimming is its own measured pass: measure the overlap between files before cutting, and keep any rule that has no other owner.

Resources

  • Interview: the questions, their evidence and recommendations, and the config fields.
  • Adapt: vendored copies, orphaned skills, rule forks, Codex seats, formatters, and rewriting project rules around the block.
  • assets/block.md: the shared block.
  • assets/pstack/: the plan and decision-log helpers the Plans rule runs, and cross.mjs, which runs a prompt in the other runtime on a named model and effort, read-only for smoke and with --reach for a panel's Codex seats, which load the owner's config and network and write only a scratch folder, or with --bypass as a Codex worker on the owner's own Codex config with no sandbox, and seats.mjs, which runs a panel round's seats through cross.mjs in one process, so the round wakes the session once, and, in a trunk project, replay.mjs, which reruns panel seats offline on bugs that landed, read from fixes' Introduced-by: lines, to measure which seat would have caught each one.
  • scripts/sync-pstack.mjs, and its tests in scripts/*.test.mjs, one file per subject, which share fixtures from scripts/test-*.mjs.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/udecode/dotai/sync-pstack">View sync-pstack on skillZs</a>