AGENTS.md git:20261015.17d54b3A

Immutable. This exact content never changes and is served at /api/v1/blob/cd11e9f893d52e92.

# open-pstack

This is Arjit Jaiswal's independently maintained distribution. Cursor is the content source; other ports are advisory sources of fixes.

Track all durable work in this repository's GitHub Issues. Do not create a parallel Linear queue. Read `UPSTREAM.md` before changing upstream-derived content.

Cursor's `cursor/plugins/pstack` tree is the content upstream. Keep one shared skill tree for Claude Code and Codex; adapt harness primitives at the existing mapping boundaries instead of forking skills or adding compatibility layers. The parent harness freezes the model sheet for a run and owns every provider-routing decision. Children do not detect or reroute themselves.

The default branch `main` is the public installation source and must remain ready for users. Keep unfinished package changes on PR branches. Validate changed behavior before merge, and bump the plugin version when packaged behavior changes, including shared skills and provider instructions. A version string is an update signal, not a barrier that hides unversioned changes from new installs. GitHub release tags document tested checkpoints and provide rollback; they are not an installation prerequisite.

Before opening a pull request, run the Bun tests, strict typecheck, static invariants, and plugin validation.

For changes to Open Pstack, invoke the project-local [verify-open-pstack skill](.agents/skills/verify-open-pstack/SKILL.md) before declaring the work complete, whether or not the user names it or uses poteto-mode. Read its feature map, run the recipes covering the affected behavior, and retain the evidence. Report blocked or unmapped paths as unverified; a CLI check does not replace installed-parent verification. For documentation or maintenance-only changes, use the maintenance evidence requirements below.

Nothing merges, tags, releases, or rolls out until the exact candidate is installed and the changed behavior passes a live test from the real user surface in every affected harness. Unit tests, validators, source inspection, and self-reports do not satisfy this gate. Record the installed version, surface, action, and observed result in the pull request template. A pull request without that evidence remains a draft.

For documentation or maintenance-only changes, prove that the packaged plugin tree is unchanged and exercise the changed CLI or GitHub workflow. There is no affected parent installation in that case. Record the actual maintenance evidence instead of repeating unchanged provider tests.

Do not add an implicit runtime timeout or a weaker-model fallback. The only permitted substitution is a saved `primary -> fallback` chain in the model sheet on a terminal outcome the sheet's `# fallback` policy authorizes (`usage-exhausted` only when no policy line is saved), per `plugins/pstack/skills/poteto-mode/references/provider-dispatch.md`; anything else remains a dropout.

## Provider compatibility and major releases

Provider adapters must support compatible patch and minor versions using a documented version range and checks for the capabilities they require. A tested version is evidence, not an exact-version allowlist. Reject a version only for a concrete incompatibility or missing required capability, with an actionable explanation. An exact-version restriction requires a documented incompatibility reason and explicit user approval before implementation. Keep tested versions separate from the supported range, and verify more than one available version when changing provider compatibility.

The repository owner authorizes routine Cursor catch-ups to release autonomously under the increment policy below. Version choices for work outside that scope still require an exact proposal, reasoning, and explicit approval before changing a candidate version or publishing. A major plugin version always requires explicit approval before implementation or publication. Keep the existing command and configuration compatibility while on 1.x. For non-catch-up work, default to patch for compatible fixes and capability improvements scoped to an existing provider, including new worker commands. Use minor for broader compatible features or new provider/routing subsystems, and major for incompatible changes. Provider-specific scope does not permit an incompatible change under a patch. Version-dependent merge, publication and rollout wait for exact-version approval. General delivery authorization does not approve those version choices.

## Release increment guidance

For a routine Cursor catch-up, compare the last incorporated Cursor version with the newly incorporated version. If only the patch changes, increment this distribution’s patch. If Cursor’s minor changes, increment this distribution’s minor and reset its patch to zero. For a batch, use the highest increment crossed. Keep independent version numbers; matching the increment does not copy Cursor’s version or require a release for each upstream commit. Published versions and tags stay unchanged. If packaged Cursor content changes before its version is bumped, default to this distribution’s next patch. Keep distribution-specific work in a separate PR; a mixed batch is outside automatic catch-up authorization.

This standing authorization covers upstream content and the portable adaptations needed for the shared Codex/Claude skill tree. Review every meaningful change for Cursor- or Grok-specific assumptions, preserve configured providers, exact model efforts, recovery and spending policy, and validate the changed behavior in both real hosts before merge or publication. Do not copy raw model selectors or discard portable intent merely because its implementation is harness-specific. Complete review, CI, provenance and adoption records, then merge with the expected-head guard, publish the matching immutable release, and update the user’s Codex installation under this user’s standing authorization without asking again, preserving the unpinned arjitj2 fork-main source and saved model assignments and verifying installed files against the release; this authorization does not change Claude’s installation.

If Cursor crosses a major version, stop for owner approval rather than mapping it to a smaller increment. If a catch-up would make this distribution incompatible or require a major, stop for approval even when Cursor calls it a patch or minor. Do not ship a breaking change under an automatically selected patch or minor. Implementation and validation that preserve compatibility may continue while approval is pending; major-dependent implementation, merge, publication and rollout wait.

Work specific to this distribution, such as new worker providers or routing subsystems, is outside routine catch-up authorization and keeps the exact-version approval requirement. A repository-only change that leaves the packaged plugin tree unchanged needs no version or release. Release notes distinguish Cursor additions, port adaptations, and distribution-specific capabilities, and identify when a highlighted skill shipped in an earlier release.

## Default delivery workflow

For repository changes, carry the work through validation, public PR review, and squash merge without waiting for another user prompt. An explicit request to stop at a draft, review, or unmerged branch overrides this default.

1. Use `create-public-facing-pr` to publish a focused PR with a concise description and verification evidence. Keep unrelated changes in separate PRs.
2. Request Copilot review and use `address-copilot-review` to assess every finding, verify and push appropriate fixes, publish replies, and resolve addressed threads. Confirm replies are submitted rather than pending. If Copilot is unavailable or quota-limited, record that fact; do not treat it as an approval or wait indefinitely.
3. Run the project-local [verify-open-pstack skill](.agents/skills/verify-open-pstack/SKILL.md) against the final candidate. Complete the applicable installed-parent or maintenance checks above and record observed results in the PR. Revalidate behavior affected by review fixes.
4. Once required checks and applicable validation pass and review findings are addressed, squash merge the PR using a server-enforced expected-head SHA. Verify the resulting merge into `main`.
5. When the merge introduces a new plugin version on `main`, publish its matching GitHub tag and release as part of delivery without waiting for another user prompt. Follow [UPSTREAM.md's release procedure](UPSTREAM.md#publish-a-release), tag the verified merge checkpoint whose plugin tree matches the tested candidate, and verify the published tag target and release. Never move an existing tag. If publication is blocked, record the blocker and report the release as pending; merging alone does not complete delivery for a new version. Repository changes that leave the plugin package unchanged need no new version or tag.
6. After merging and completing any required release publication, check linked issues, close those fully resolved by the PR, and verify their closed status on GitHub; report any issue left open to the user with the reason and remaining work.

Proceed autonomously through routine fixes and retries justified by evidence. Existing validation gates and explicit restrictions on credentials, spending, or other actions still apply. When a required check cannot run, document the concrete blocker, complete independent work, and leave the affected PR unmerged. Do not replace a missing live test with a unit-test or source-inspection claim. Tags and releases required by step 5 are within the delivery scope. Other tags, releases, and installation changes outside validation or the routine catch-up rollout authorization require their own task scope.

## Documentation ownership

Add or keep a public document only when it answers a question readers ask repeatedly. Each maintained fact has one owner. When behavior changes, update the owner in the same change; everywhere else, link rather than restate. Record validation of a particular candidate in its pull request and release notes. Keep reproducible proof in tests and in the verification recipes under `.agents/skills/verify-open-pstack/`. Do not commit lab reports, dated evidence files, or generated proposal artifacts; keep them outside the checkout. To cite past evidence, link a pull request or a commit-pinned GitHub permalink. Never edit an old record to track current state.

| Fact | Owner |
| --- | --- |
| Fresh install steps | `README.md` (`## Install`) |
| Update, migration, pinning, and rollback steps | `README.md` (`## Update, switch, or roll back`) |
| Supported parent and provider IDs | `plugins/pstack/skills/poteto-mode/scripts/runner/types.ts` (`PARENTS`, `PROVIDERS`), rendered by the README provider table |
| Models, defaults, permissions, billing, provider limits, recovery policy | `plugins/pstack/skills/poteto-mode/references/provider-dispatch.md` |
| Development dependencies and checks | `CONTRIBUTING.md` |
| Harness substitutions and upstream adaptation | `UPSTREAM.md` (`## Port adaptations`) |
| Cursor baseline and upstream exclusions | `UPSTREAM.md` sync table and `## Upstream-only exclusions` |
| Decision for each Cursor commit | `maintenance/upstream-ledger.json` |
| Sync, proposal, adoption, and release procedure | `UPSTREAM.md` |
| Package version | plugin manifests, mirrored in the `UPSTREAM.md` sync table and checked by `tests/skill-collision-repro.sh` |
| Release history, Cursor baseline per version, and evidence links | `CHANGELOG.md` |
| Attribution and licenses | `NOTICE.md`, `LICENSE`, and `LICENSES/` |
| Bug reports and contribution checks | `CONTRIBUTING.md` |
| Install-source policy | this file (the `main` paragraph above) |
| Skill purpose and invocation | each packaged `SKILL.md`; README lists common entry points |
| Session-start routing behavior | `plugins/pstack/hooks/session-start-context.md` and each host's hook descriptor in `plugins/pstack/hooks/` |
| Codex startup-routing setup choice | `plugins/pstack/skills/setup-pstack/SKILL.md` (`## Codex startup routing`) |
| Reproducible verification | `.agents/skills/verify-open-pstack/` and `tests/` |

`python3 scripts/check-docs.py` checks that the README provider table matches the runner IDs, that relative links and heading anchors resolve, that the public documentation inventory stays within its approved scope, and that the current `CHANGELOG.md` entry and pinned upstream README agree with the package version and Cursor baseline. Passing proves structure, not that all prose is current.