From bef78edc6b8f15259d0e40225161c8a698970621 Mon Sep 17 00:00:00 2001 From: YiChu Date: Sun, 9 Aug 2026 22:17:30 +0800 Subject: [PATCH 1/2] Finish ystack public rebrand with compatibility aliases Promote ystack as the install target and primary skill entry, add setup-ystack and ystack-named model overrides, retain pstack aliases and legacy config fallbacks, refresh user-facing guides, and add a CI branding guard. Co-authored-by: ChatGPT --- .github/workflows/portable-audit.yml | 5 +- CONTRIBUTING.md | 63 +++++------- COVERAGE.md | 46 +++++---- INSTALL.md | 98 ++++++++++++------- LICENSE | 2 +- NOTICE.md | 8 +- README.md | 77 +++++++++------ UPSTREAM_MANIFEST.json | 12 ++- docs/guide/01-setup.md | 64 +++++------- docs/guide/03-understand.md | 20 ++-- docs/guide/04-design.md | 36 +++---- docs/guide/07-overnight.md | 42 ++------ docs/guide/08-principles.md | 68 ++++++------- docs/guide/README.md | 12 +-- scripts/check_branding.py | 78 +++++++++++++++ scripts/fixtures/model-override/valid.md | 2 +- .../references/adapters/claude-code.md | 31 +++--- .../references/adapters/codex-models.md | 29 +++--- .../poteto-mode/references/adapters/codex.md | 69 ++++++------- .../poteto-mode/references/adapters/droid.md | 34 +++---- .../references/adapters/opencode.md | 34 +++---- .../references/model-override.schema.json | 4 +- skills/pstack/SKILL.md | 88 ++--------------- .../pstack/references/adapters/claude-code.md | 31 +++--- .../references/adapters/codex-models.md | 29 +++--- skills/pstack/references/adapters/codex.md | 69 ++++++------- skills/pstack/references/adapters/droid.md | 34 +++---- skills/pstack/references/adapters/opencode.md | 34 +++---- .../references/model-override.schema.json | 4 +- skills/setup-pstack/SKILL.md | 93 ++---------------- skills/setup-ystack/SKILL.md | 91 +++++++++++++++++ skills/ystack/SKILL.md | 79 +++++++++++++++ 32 files changed, 743 insertions(+), 643 deletions(-) create mode 100755 scripts/check_branding.py create mode 100644 skills/setup-ystack/SKILL.md create mode 100644 skills/ystack/SKILL.md diff --git a/.github/workflows/portable-audit.yml b/.github/workflows/portable-audit.yml index df91246..70c22b8 100644 --- a/.github/workflows/portable-audit.yml +++ b/.github/workflows/portable-audit.yml @@ -26,6 +26,9 @@ jobs: - name: Compile maintenance scripts run: python3 -m compileall -q scripts + - name: Check ystack public branding + run: python3 scripts/check_branding.py + - name: Check mirrors without rewriting the checkout run: python3 scripts/sync_mirrors.py --check @@ -55,8 +58,6 @@ jobs: data = json.loads(Path("UPSTREAM_MANIFEST.json").read_text()) commit = data["upstream"].get("commit") assert commit, "upstream.commit missing" - # UNPINNED is allowed until the first real upstream sync. - # After that, require a full 40-char git SHA. if commit != "UNPINNED" and not re.fullmatch(r"[0-9a-f]{40}", commit): raise SystemExit(f"upstream.commit must be UNPINNED or a 40-char SHA, got {commit!r}") print(f"upstream.commit={commit}") diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fb762be..164eb08 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,42 +2,48 @@ ## Goals -- Keep playbook and principle **intent** aligned with upstream pstack. -- Keep vendor tool names and concrete vendor model slugs out of portable skill bodies. Put runtime mechanics only in `skills/pstack/references/adapters/`. +- Keep ystack's public API and documentation consistent. +- Keep playbook and principle intent aligned with upstream pstack where the fork has not intentionally diverged. +- Keep vendor tool names and concrete vendor model slugs out of portable skill bodies. Put runtime mechanics only in the shared adapter tree. - Every workflow must remain correct under the `generic` adapter when multi-agent tools are unavailable. -- Preserve real parallel fan-out on hosts that expose agent-spawn tools. Portability must not collapse the pack to the lowest common denominator. +- Preserve real parallel fan-out on hosts that expose agent-spawn tools. + +## Naming boundary + +- `ystack` is the public project, repository, install target, and primary entry skill. +- `pstack` identifies the upstream lineage and remains a compatibility alias. +- New user-facing docs and examples should use `/ystack`, `/setup-ystack`, `Go7hic/ystack`, and `ystack-models.*`. +- Do not remove legacy names without a separate migration plan and release note. ## Layout and sources of truth -- Installable skills live under `skills//SKILL.md` and follow the Agent Skills layout used by skills.sh. -- Shared runtime contracts live under `skills/pstack/references/{capability-contract.md,adapters/,agents/,host-lifecycle.md,model-override.schema.json}`. +- Installable skills live under `skills//SKILL.md`. +- `skills/ystack/SKILL.md` is the public entry. +- Shared runtime contracts currently remain under `skills/pstack/references/` for compatibility. - `skills/poteto-mode/playbooks/` is the canonical playbook directory. -- `skills/pstack/references/adapters/` is the canonical adapter directory. -- `skills/pstack/references/capability-contract.md` is canonical. -- Agent rubrics, `principles-summary.md`, `host-lifecycle.md`, and the model-override schema exist only under `skills/pstack/references/`. +- `skills/pstack/references/adapters/` is the canonical adapter directory during the compatibility window. +- Agent rubrics, lifecycle guidance, and model schema are mirrored into poteto-mode as required by its relative references. -Do not edit both sides of a mirror independently. The portable audit rejects drift. +Do not edit both sides of a mirror independently. The audit rejects drift. ## Re-port helpers After pulling newer upstream Cursor pstack sources: ```bash -# Verify mirrors without rewriting (CI uses this). python3 scripts/sync_mirrors.py --check - -# Refresh mirrors after local playbook/adapter/agent edits. python3 scripts/sync_mirrors.py ``` -`UPSTREAM_MANIFEST.json` is the source of truth for hand-maintained `SKILL.md` names. Import still syncs `poteto-mode` playbooks/references while protecting those SKILL files and local adapters/agents. +`UPSTREAM_MANIFEST.json` is the source of truth for hand-maintained skills. Upstream imports must not overwrite ystack entries, compatibility aliases, local adapters, or portable-only workflows. ## Required audit -Run this before every pull request: +Run before every pull request: ```bash python3 -m compileall -q scripts +python3 scripts/check_branding.py python3 scripts/sync_mirrors.py --check python3 scripts/audit_portability.py --strict python3 scripts/check_markdown_links.py @@ -45,35 +51,20 @@ python3 scripts/validate_model_override.py scripts/fixtures/model-override/valid python3 scripts/port_to_portable.py --check-idempotent ``` -The baseline audit checks: - -- skill frontmatter and unique skill names; -- the complete playbook and adapter inventories; -- byte-identical playbook, adapter, and capability-contract mirrors; -- Cursor-only frontmatter keys; -- portability smells (vendor fields, Cursor paths/control surfaces, thin mechanical blocks, rewrite artifacts); -- regression fixtures under `scripts/fixtures/portability/` for every portability pattern. - -Repository-wide non-strict audit should stay at `0 error(s), 0 warning(s)` unless a finding is intentionally introduced and tracked. The strict changed-file scan rejects regressions in files a PR touches. - ## Semantic review after mechanical porting -Regex passes are only the first step. Review every changed skill for meaning: - -1. Replace vendor calls with the narrowest capability verb. Read-only investigation uses `explore`; code changes use `implement`; independent criticism uses `review`. -2. Replace concrete model names with `model_role` and let the active adapter or override resolve a real model. +1. Use the narrowest capability verb: `explore`, `implement`, `review`, `parallel`, `ask_user`, or `verify`. +2. Replace concrete model names with `model_role` and let the adapter resolve them. 3. Keep product decisions in `ask_user`; obtain observable facts through exploration or verification. 4. Keep write scopes disjoint before using `parallel`. -5. State the fallback when the host cannot spawn helpers or drive the real runtime surface. -6. Remove claims that a mode, transcript path, MCP discovery mechanism, or background task API exists on every host. - -A mechanically valid sentence can still be semantically wrong. Phrases such as “`explore` / `implement` helper” are a sign that the port has not chosen the actual capability. +5. State fallbacks when the host cannot spawn helpers or drive the real runtime surface. +6. Preserve the public ystack naming boundary while retaining explicit upstream attribution. ## Host conformance -Live host results belong in `scripts/fixtures/conformance/HOST_MATRIX.md`. CI does not run remote agents; fill the matrix after smoke tests on each supported host. +Live host results belong in `scripts/fixtures/conformance/HOST_MATRIX.md`. CI does not run remote agents; fill the matrix after smoke tests. ## skills.sh -- The `description` frontmatter field is the trigger surface and must stay quoted for reliable parsing. -- Prefer installing the whole pack so the `pstack` entry skill, adapters, playbooks, and leaf skills remain available together. +- The `description` frontmatter field is the trigger surface and must stay quoted. +- Install the whole pack so the `ystack` entry, sibling skills, adapters, playbooks, and compatibility assets remain available together. diff --git a/COVERAGE.md b/COVERAGE.md index 5e96bab..96c4f8c 100644 --- a/COVERAGE.md +++ b/COVERAGE.md @@ -1,36 +1,46 @@ # Coverage -This pack aims for **full upstream pstack capability coverage**, ported to Agent Skills + adapters. +ystack aims for full upstream pstack capability coverage, ported to Agent Skills plus host adapters and extended with portable-only workflows. -## Skills (46) +## Skills (48) -All upstream skills under `skills/` plus the portable additions `pstack` and `living-spec`. +The pack includes the upstream-derived skill set, the public `ystack` entry and `setup-ystack`, the `living-spec` addition, and legacy `pstack` / `setup-pstack` compatibility aliases. ## Playbooks (23) -Mirrored in `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/`. +Mirrored in `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/` during the compatibility window. ## Intentionally adapted (not 1:1 Cursor runtime) -| Upstream | Portable treatment | +| Upstream | ystack treatment | | --- | --- | -| `Task` / `subagent_type` | capability verbs + per-host adapters (parallel by default on modern agents) | -| Claude Code `Agent`/`Task` | `adapters/claude-code.md` (`Explore`, `general-purpose`, multi-spawn one turn) | -| Droid `Task` + custom droids | `adapters/droid.md` (`run_in_background` / `TaskOutput`) | -| OpenCode `task` | `adapters/opencode.md` (`explore` / `general` / `scout`) | +| `Task` / `subagent_type` | capability verbs + per-host adapters | +| Claude Code `Agent`/`Task` | `adapters/claude-code.md` | +| Droid `Task` + custom droids | `adapters/droid.md` | +| OpenCode `task` | `adapters/opencode.md` | | Codex multi-agent | `adapters/codex.md` | -| `poteto-agent` / Comment Sicko types | rubric markdown under `pstack/references/agents/` | -| Cursor model slugs | `model_role` + setup-pstack override file | +| `poteto-agent` / Comment Sicko types | portable rubric markdown | +| Cursor model slugs | `model_role` + `/setup-ystack` override file | | `AskQuestion` | `ask_user` | -| `/loop` | long-run/loop if available, else continue | -| `watch-pr` scripts | optional; babysit falls back to `gh` | -| poteto-mode `scripts/` (orch, watch-pr) | omitted from pack copy (Cursor tooling); playbooks note fallbacks | -| benny automations | kept under `references/automations/benny/skill-templates/` as `INSTRUCTIONS.md` (not discoverable by `npx skills add`) | +| `/loop` | host long-running mechanism when available, otherwise explicit continuation | +| `watch-pr` scripts | optional; Babysit falls back to the active forge interface | +| upstream poteto-mode scripts | omitted when they depend on Cursor-only runtime behavior | +| Benny automations | kept as non-installable source templates under `references/automations/benny/` | ## Portable-only additions -`living-spec` adds an optional current-product-truth workflow for solo projects. It is intentionally not part of upstream pstack and does not replace OpenSpec or another repository-native specification system. +- `ystack` — primary public entry. +- `setup-ystack` — preferred model configuration entry. +- `living-spec` — lightweight current-product-truth convergence for solo projects. +- portability, mirror, model-schema, link, and branding audits. -## External (never in upstream pstack either) +## Compatibility -`deslop`, `control-cli`, `control-ui` from `cursor-team-kit`. +- `/pstack` routes to `/ystack`. +- `/setup-pstack` routes to `/setup-ystack`. +- legacy `pstack-models.*` files remain readable after ystack-named overrides become preferred. +- upstream names remain in credits, lineage metadata, and compatibility paths. + +## External + +`deslop`, `control-cli`, and `control-ui` from `cursor-team-kit` are not bundled; use equivalent host capabilities. diff --git a/INSTALL.md b/INSTALL.md index 3939bd3..92bc189 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,22 +1,26 @@ -# Install +# Install ystack -Use this portable pack on every Agent Skills–compatible coding agent **except** Cursor (keep Cursor’s official pstack plugin there). +ystack supports Agent Skills-compatible coding agents, including Claude Code, Codex, OpenCode, Droid, generic Agent Skills hosts, and Cursor through the included adapter. -## Recommended: GitHub global install +If Cursor's official pstack plugin is already enabled, do not also activate ystack as a competing top-level router in the same session. Choose one router, or keep ystack on your non-Cursor agents. + +## Recommended: global install + +Install the complete pack because `/ystack` coordinates sibling skills and the shared compatibility runtime tree: ```bash -npx skills add Go7hic/pstack -g -s '*' -y +npx skills add Go7hic/ystack -g -s '*' -y ``` -Add `-a` for specific agents if you do not want every discovered agent: +Add `-a` for specific agents when you do not want every discovered agent: ```bash -npx skills add Go7hic/pstack -g \ +npx skills add Go7hic/ystack -g \ -a claude-code -a codex -a opencode -a factory-droid \ -s '*' -y ``` -`-g` installs into each agent’s **global** skills directory (not the current project), for example: +`-g` installs into each agent's global skills directory, for example: | Agent | Typical global skills dir | | --- | --- | @@ -26,77 +30,101 @@ npx skills add Go7hic/pstack -g \ | Droid (Factory) | `~/.factory/skills/` | | Generic / shared | `~/.agents/skills/` | -After install, restart or reload the agent so it rescans skills. +After installation, restart or reload the agent so it rescans skills. -## Optional: skills.sh pack URL +## Public commands and compatibility -If you already have a published skills.sh pack for this repo, you can install from that URL instead. Prefer the GitHub install above when the pack page is stale or the URL does not resolve to a valid skill archive. +Prefer: -```bash -# Replace with your current pack URL only after confirming it installs cleanly. -npx skills add https://skills.sh/p/ -g -s '*' -y +```text +/ystack +/setup-ystack +``` + +The legacy commands remain available: + +```text +/pstack +/setup-pstack ``` -## Optional: wire more agents from the install tree +They route to the ystack workflow so existing prompts and installations continue to work. -If the CLI already installed into one global tree and you need another agent that was not selected, symlink from that install location (not from this git checkout): +## Model override migration + +`/setup-ystack` writes the preferred ystack-named override file for the active host: + +| Host | Preferred path | Legacy fallback | +| --- | --- | --- | +| Cursor | `~/.cursor/rules/ystack-models.mdc` | `~/.cursor/rules/pstack-models.mdc` | +| Codex | `~/.codex/rules/ystack-models.md` | `~/.codex/rules/pstack-models.md`, then `codex-pstack-models.md` | +| Claude Code / generic | `~/.agents/ystack-models.md` or a host rule | `~/.agents/pstack-models.md` | +| Droid / OpenCode | preferred shared file or host-native agent config | legacy shared file | + +Existing legacy files are read as fallback. Re-running `/setup-ystack` writes the new path; it does not silently delete the old file. + +## Optional: wire more agents from one install tree + +If the CLI already installed into one global tree and you need another agent that was not selected, symlink from that install location, not from this git checkout: ```bash -# After a global install, the shared tree is usually: SRC=~/.agents/skills -# If your install only landed under one agent, point SRC there instead, e.g.: -# SRC=~/.claude/skills +# If installation landed under one agent only, point SRC there instead. -# Droid mkdir -p ~/.factory/skills ln -sfn "$SRC"/* ~/.factory/skills/ -# OpenCode mkdir -p ~/.config/opencode/skills ln -sfn "$SRC"/* ~/.config/opencode/skills/ -# Codex (if not installed via -a codex) mkdir -p ~/.codex/skills ln -sfn "$SRC"/* ~/.codex/skills/ ``` -Do **not** use `~/workspace/pstack/skills` as `SRC` unless you are developing this repo itself. +Do not use `~/workspace/ystack/skills` as `SRC` unless you are developing this repository itself. ### Codex cutover checklist -1. Prefer `npx skills add Go7hic/pstack -g -a codex` (or symlink from `SRC` above). -2. Delete the old pack if present: `rm -rf ~/.codex/skills/codex-pstack` -3. Point model overrides at `~/.codex/rules/pstack-models.md` (see `adapters/codex-models.md`). -4. Smoke-test: `/pstack` or `/how` and confirm the agent reads `adapters/codex.md` and spawns via `multi_agent_v1` (or current Codex multi-agent tools). +1. Install with `npx skills add Go7hic/ystack -g -a codex -s '*' -y`. +2. Delete the obsolete standalone pack if present: `rm -rf ~/.codex/skills/codex-pstack`. +3. Run `/setup-ystack` and prefer `~/.codex/rules/ystack-models.md`. +4. Smoke-test `/ystack` or `/how` and confirm the Codex adapter uses current multi-agent tools. ## Adapter selection +The runtime assets currently live under the legacy compatibility namespace while the public project name is ystack: + | Host | Adapter | | --- | --- | -| Cursor | official plugin — do **not** rely on this pack | +| Cursor | `skills/pstack/references/adapters/cursor.md` | | Claude Code | `skills/pstack/references/adapters/claude-code.md` | | Droid | `skills/pstack/references/adapters/droid.md` | | OpenCode | `skills/pstack/references/adapters/opencode.md` | | Codex | `skills/pstack/references/adapters/codex.md` | -| Unknown | `generic.md` (auto-uses spawn tools when present) | +| Unknown | `generic.md` | ## Smoke test In each agent: ```text -/pstack (or /poteto-mode) -fix a tiny reproducible issue in this repo, or explain how X works with /how +/ystack add a --json flag to this command. Keep text output byte-identical and verify both paths. ``` -Confirm it reads the matching adapter and, for arena/how-complex, actually fans out subagents. +You can also invoke `/poteto-mode`. Confirm that the entry skill: + +1. reads the capability contract and matching adapter; +2. creates a todo list from the matched playbook; +3. uses real parallel helpers when the host exposes them; +4. falls back explicitly when spawning is unavailable; +5. verifies the result before declaring completion. -## Developing this repo +## Developing this repository -Local checkout only when editing the pack: +Use a local checkout only when editing ystack: ```bash -SRC=~/workspace/pstack/skills # or your clone path +SRC=~/workspace/ystack/skills # or your clone path ``` -Day-to-day use should go through the GitHub install path above. +Day-to-day use should go through the GitHub installation path above. diff --git a/LICENSE b/LICENSE index f743d15..08440d2 100644 --- a/LICENSE +++ b/LICENSE @@ -1,6 +1,6 @@ MIT License -Copyright (c) 2026 pstack portable contributors +Copyright (c) 2026 ystack contributors Copyright (c) 2026 Lauren Tan (original Cursor pstack) Permission is hereby granted, free of charge, to any person obtaining a copy diff --git a/NOTICE.md b/NOTICE.md index 4f9ac54..e639e11 100644 --- a/NOTICE.md +++ b/NOTICE.md @@ -1,8 +1,10 @@ # Notice -This repository is a **portable Agent Skills** adaptation of [Cursor pstack](https://github.com/cursor/plugins/tree/main/pstack) by [Lauren Tan (poteto)](https://x.com/poteto). +**ystack** began as a portable Agent Skills adaptation of [Cursor pstack](https://github.com/cursor/plugins/tree/main/pstack) by [Lauren Tan (poteto)](https://x.com/poteto). -Upstream pstack is Cursor-oriented (Task tool, poteto-agent, Cursor model slugs, plugin frontmatter). This fork keeps the engineering discipline — principles, playbooks, verification gates — and replaces Cursor-only runtime with a capability contract plus thin adapters for multiple coding agents. +Upstream pstack is Cursor-oriented. ystack preserves its engineering discipline—principles, playbooks, verification gates—and adds a capability contract, host adapters, portability checks, model-role configuration, and portable-only workflows such as `living-spec`. + +The public project name is ystack. References to `pstack` remain where they identify the upstream project or provide compatibility for existing commands, paths, and model configuration. Original work: MIT License, Copyright (c) 2026 Lauren Tan. -Portable adaptation: MIT License, see `LICENSE`. +ystack adaptation: MIT License, see `LICENSE`. diff --git a/README.md b/README.md index b05c3ef..cf6a650 100644 --- a/README.md +++ b/README.md @@ -1,46 +1,67 @@ -# pstack (portable) +# ystack -A portable [Agent Skills](https://agentskills.io) distribution of [Cursor pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan (poteto). +**ystack** is a portable multi-agent engineering skill stack for Agent Skills-compatible coding agents. It began as a portable adaptation of [Cursor pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan (poteto), then grew host adapters, portability audits, long-running playbooks, model-role configuration, and `living-spec` product-documentation convergence. -It preserves the same engineering system—principles, playbooks, `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, verification, and prose cleanup—without hard-coding one vendor runtime. Thin adapters map capability verbs to Claude Code, Codex, Droid, OpenCode, Cursor, and unknown Agent Skills hosts. Modern hosts keep real parallel subagents; single-agent runtimes degrade explicitly and safely. +It preserves the upstream engineering system—principles, playbooks, `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, verification, and prose cleanup—without hard-coding one vendor runtime. Thin adapters map capability verbs to Claude Code, Codex, Droid, OpenCode, Cursor, and unknown Agent Skills hosts. Modern hosts keep real parallel subagents; single-agent runtimes degrade explicitly and safely. ## Install -Use this portable pack on Agent Skills-compatible coding agents other than Cursor. Cursor users should keep the official pstack plugin. +Install the complete pack globally. The `ystack` entry coordinates sibling skills and shared compatibility assets, so keep `-s '*'`: ```bash -npx skills add Go7hic/pstack -g -s '*' -y +npx skills add Go7hic/ystack -g -s '*' -y ``` -See [INSTALL.md](./INSTALL.md) for per-agent selection, optional skills.sh install, model override paths, migration notes, and smoke tests. After global installation, skills usually land under an agent-specific directory such as `~/.claude/skills/`, `~/.codex/skills/`, or the shared `~/.agents/skills/` tree. +See [INSTALL.md](./INSTALL.md) for per-agent selection, model override paths, migration notes, and smoke tests. After installation, restart or reload the coding agent so it rescans skills. + +Cursor users may use ystack through its Cursor adapter or keep Cursor's official pstack plugin. Do not enable both as competing top-level routers in the same session. + +## Public entry points + +- `/ystack` — primary adapter-first router. +- `/poteto-mode` — full upstream-style mode contract. +- `/setup-ystack` — configure role and panel models. +- `/pstack` and `/setup-pstack` — legacy compatibility aliases. ## What is included | Area | Skills and assets | | --- | --- | -| Entry | `pstack`, `poteto-mode` | -| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `living-spec`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` | +| Entry | `ystack`, `poteto-mode`; legacy alias `pstack` | +| Workflow | `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `figure-it-out`, `teach`, `reflect`, `automate-me`, `setup-ystack`, `show-me-your-work`, `living-spec`, `create-verification-skill`, `maintain-verification-skill`, `tdd`, `typescript-best-practices` | | Quality | `unslop`, `no-comments`, `technical-writing`, `bro` | | Principles | all 21 `principle-*` leaf skills | -| Playbooks | 23 mirrored under `skills/poteto-mode/playbooks/` and `skills/pstack/playbooks/` | -| Runtime | `capability-contract.md` plus `generic`, `claude-code`, `codex`, `droid`, `opencode`, and `cursor` adapters | -| Agent rubrics | `skills/pstack/references/agents/{poteto-agent,comment-sicko}.md` | +| Playbooks | 23 mirrored under `skills/poteto-mode/playbooks/` and the legacy runtime tree `skills/pstack/playbooks/` | +| Runtime | capability contract plus `generic`, `claude-code`, `codex`, `droid`, `opencode`, and `cursor` adapters | +| Agent rubrics | Poteto worker and Comment Sicko review rubrics | | Optional | `references/automations/benny`, a Cursor-oriented source pack that is not installed as Agent Skills | ## How portability works 1. Skills express intent with the capability verbs `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, and `model_role`. -2. Before delegation, the lead reads the matching adapter under `skills/pstack/references/adapters/`. +2. Before delegation, the lead reads the matching host adapter from the shared runtime tree. 3. The adapter maps those verbs to the host's actual tools, helper types, model controls, and fallback behavior. 4. Parallel fan-out remains the default when the host exposes agent-spawn tools. The workflow collapses to the lead agent only when spawning is missing or denied. -5. `/setup-pstack` resolves role-appropriate models through a host-specific override file. Portable skills must not require Cursor model slugs. -6. The lead agent always owns synthesis, the final patch judgment, and verification on the narrowest meaningful real surface. +5. `/setup-ystack` resolves role-appropriate models through a host-specific override file. Portable skills must not require another host's model slugs. +6. The lead agent always owns synthesis, final patch judgment, and verification on the narrowest meaningful real surface. + +The portable layer is an instruction protocol, not an emulator. It preserves workflow intent across hosts, but it cannot manufacture features a host does not expose. A runtime without subagents, model selection, browser control, or persistent modes uses the documented fallback and states the limitation. + +## Naming and compatibility + +`ystack` is the public project and repository name. The internal `skills/pstack/` namespace remains temporarily because it is both the upstream lineage name and the compatibility home used by existing installations. New documentation and commands should prefer `ystack`. -The portable layer is an instruction protocol, not an emulator. It preserves workflow intent across hosts, but it cannot manufacture features a host does not expose. A runtime without subagents, model selection, browser control, or persistent modes will use the documented fallback and state the limitation. +Model overrides prefer: + +- Cursor: `ystack-models.mdc` +- Codex: `ystack-models.md` +- shared Agent Skills hosts: `ystack-models.md` + +Adapters continue to honor legacy `pstack-models.*` files so existing users can migrate without losing configuration. ## Living product documentation -`living-spec` is an optional, solo-friendly documentation layer for projects that use pstack without a full specification framework. It keeps three concerns separate: +`living-spec` is an optional, solo-friendly documentation layer for projects that use ystack without a full specification framework. It keeps three concerns separate: - `docs/product/` describes the product's current, verified behavior; - `docs/changes/` holds a temporary brief only for changes that span sessions, pull requests, or several modules; @@ -50,29 +71,21 @@ The skill does not require documentation for internal refactors or trivial edits ## Session and mode behavior -`/poteto-mode` is sticky when the active host supports persistent skill or mode state. On hosts without that lifecycle, treat it as active for the current conversation and invoke it again after a fresh session or a context reset. The engineering rules and playbooks remain portable even when the host cannot provide a native mode flag. +`/poteto-mode` is sticky when the active host supports persistent skill or mode state. On hosts without that lifecycle, treat it as active for the current conversation and invoke `/ystack` or `/poteto-mode` again after a fresh session or context reset. ## Maintenance and audits -The repository contains a structural and portability audit: +The repository contains structural, branding, and portability audits: ```bash -python3 scripts/audit_portability.py -python3 scripts/audit_portability.py --strict --changed-from origin/main -python3 scripts/sync_mirrors.py +python3 scripts/check_branding.py +python3 scripts/audit_portability.py --strict +python3 scripts/sync_mirrors.py --check +python3 scripts/check_markdown_links.py ``` -GitHub Actions runs the structural audit on `main` and on pull requests. It also rejects new vendor leakage in changed files, including concrete Cursor model slugs, Cursor-only tool fields, transcript paths, thin mechanical portability blocks, rewrite artifacts, and drift between mirrored playbooks or adapters. - -See [CONTRIBUTING.md](./CONTRIBUTING.md) and [UPSTREAM_MANIFEST.json](./UPSTREAM_MANIFEST.json) before syncing a newer upstream revision. Mechanical regex porting is followed by a semantic review; capability verbs must describe the actual job rather than merely replacing vendor vocabulary. - -## Not bundled - -Upstream poteto-mode references tools that are not part of pstack itself: - -- `deslop`, `control-cli`, and `control-ui` from Cursor's `cursor-team-kit`; use equivalent cleanup and runtime-control tools available on the active host. -- Cursor's built-in skill-authoring flow; use the active agent's corresponding authoring or validation workflow. +See [CONTRIBUTING.md](./CONTRIBUTING.md) and [UPSTREAM_MANIFEST.json](./UPSTREAM_MANIFEST.json) before syncing a newer upstream revision. Mechanical regex porting is followed by semantic review; capability verbs must describe the actual job rather than merely replacing vendor vocabulary. ## Credits -Adapted from pstack by Lauren Tan. See [NOTICE.md](./NOTICE.md) and [LICENSE](./LICENSE) for attribution and MIT licensing. +ystack is adapted from Cursor pstack by Lauren Tan. See [NOTICE.md](./NOTICE.md) and [LICENSE](./LICENSE) for attribution and MIT licensing. diff --git a/UPSTREAM_MANIFEST.json b/UPSTREAM_MANIFEST.json index 231822c..cf35000 100644 --- a/UPSTREAM_MANIFEST.json +++ b/UPSTREAM_MANIFEST.json @@ -6,13 +6,18 @@ "commit": "UNPINNED", "synced_at": null, "last_import_report": null, - "notes": "Pin commit SHA on each upstream import via scripts/import_upstream.py. Hand-maintained SKILL.md names below are protected; poteto-mode playbooks/references still import. Do not auto-merge sync PRs." + "notes": "Pin commit SHA on each upstream import via scripts/import_upstream.py. Protect public ystack entries, compatibility aliases, portable-only workflows, and local adapters. Do not auto-merge sync PRs." }, "portable": { - "patch_version": "0.2.0", + "public_name": "ystack", + "legacy_names": ["pstack"], + "patch_version": "0.3.0", "capability_contract_version": "1.0.0", "hand_maintained_skills": [ + "ystack", + "setup-ystack", "pstack", + "setup-pstack", "living-spec", "poteto-mode", "how", @@ -24,8 +29,7 @@ "reflect", "recall", "automate-me", - "show-me-your-work", - "setup-pstack" + "show-me-your-work" ] } } diff --git a/docs/guide/01-setup.md b/docs/guide/01-setup.md index 8ec32e9..f443806 100644 --- a/docs/guide/01-setup.md +++ b/docs/guide/01-setup.md @@ -1,76 +1,66 @@ -# Set up portable pstack +# Set up ystack This page installs the pack, selects role-appropriate models, and runs a small smoke test. The exact installation and delegation tools depend on the active coding agent. ## Install on your coding agent -### Cursor - -Use the official Cursor pstack plugin rather than this portable distribution: - -```text -/add-plugin pstack -``` - -The official plugin has native mode metadata and Cursor-specific integrations that the portable pack deliberately does not duplicate. - -### Claude Code, Codex, OpenCode, Droid, and other Agent Skills hosts - -Install the portable pack globally: +Install ystack globally on Claude Code, Codex, OpenCode, Droid, Cursor, or another Agent Skills host: ```bash -npx skills add Go7hic/pstack -g -s '*' -y +npx skills add Go7hic/ystack -g -s '*' -y ``` -To install only for selected agents, add one or more `-a` flags as described in [INSTALL.md](../../INSTALL.md). Restart or reload the coding agent after installation so it rescans its skill directories. +The complete pack is recommended because `/ystack` coordinates sibling skills and shared runtime assets. To install only for selected agents, add one or more `-a` flags as described in [INSTALL.md](../../INSTALL.md). Restart or reload the coding agent afterward so it rescans its skill directories. + +On Cursor, choose between ystack and the official pstack plugin as your top-level router. Do not enable both mode systems simultaneously. ## Pick models by role Run: ```text -/setup-pstack +/setup-ystack ``` -[`/setup-pstack`](../../skills/setup-pstack/SKILL.md) detects the models and helper controls exposed by the current host. It then maps available models to roles such as exploration, feature implementation, bug fixing, judgment, and adversarial review. +[`/setup-ystack`](../../skills/setup-ystack/SKILL.md) detects the models and helper controls exposed by the current host. It maps available models to exploration, feature implementation, bug fixing, judgment, and adversarial-review roles. -The override file belongs to the active agent, not to a universal Cursor path: +The override file belongs to the active agent: -| Host | Typical override path | -| --- | --- | -| Cursor | `~/.cursor/rules/pstack-models.mdc` | -| Codex | `~/.codex/rules/pstack-models.md` | -| Claude Code or a generic Agent Skills host | `~/.agents/pstack-models.md` or a host-supported user rule | +| Host | Preferred override path | Legacy fallback | +| --- | --- | --- | +| Cursor | `~/.cursor/rules/ystack-models.mdc` | `pstack-models.mdc` | +| Codex | `~/.codex/rules/ystack-models.md` | `pstack-models.md`, then `codex-pstack-models.md` | +| Claude Code or generic | `~/.agents/ystack-models.md` or a host-supported rule | `~/.agents/pstack-models.md` | -A role with no override inherits the adapter's default behavior. A value of `inherit-parent` or `auto` tells the adapter to omit an explicit child-model selection and use the parent session model. Panel roles accept a list; the list length controls the number of reviewers or candidates when the host supports parallel helpers. +A role with no override inherits the adapter's default behavior. `inherit-parent` or `auto` tells the adapter to omit explicit child-model selection. Panel lists control reviewer or candidate count when the host supports parallel helpers. -Never copy model identifiers from another coding agent. `/setup-pstack` writes only model identifiers confirmed by the current host. +Never copy model identifiers from another coding agent. `/setup-ystack` writes only identifiers confirmed by the current host. ## Decide whether to create project verification -At the end of setup, pstack checks whether the project has a repeatable way to exercise the real product surface. That may be a project-local `verify-*` skill, a browser or simulator harness, a CLI check, or another host-specific runtime driver. +At the end of setup, ystack checks whether the project has a repeatable way to exercise the real product surface. That may be a project-local `verify-*` skill, browser or simulator harness, CLI check, or another host-specific runtime driver. -When no useful harness exists, setup can route to [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). The generated skill belongs in the active host's project-local skill directory. Do not assume `.cursor/skills/` outside Cursor. +When no useful harness exists, setup can route to [`/create-verification-skill`](../../skills/create-verification-skill/SKILL.md). The generated skill belongs in the active host's project-local skill directory. -A verification skill should prove one real workflow before it is accepted. Compilation and unit tests are valuable, but they do not replace checking the behavior on the surface where the original problem appears. +A verification skill should prove one real workflow before it is accepted. Compilation and unit tests are valuable, but they do not replace checking behavior on the surface where the original problem appears. ## Run the smoke test Choose a real but small task: ```text -/pstack add a --json flag to this command. Keep text output byte-identical and verify both paths. +/ystack add a --json flag to this command. Keep text output byte-identical and verify both paths. ``` -You can also invoke `/poteto-mode`. The entry skill should: +You can also invoke `/poteto-mode`; `/pstack` remains a compatibility alias. The entry skill should: -1. read the capability contract and the adapter for the current host; +1. read the capability contract and adapter for the current host; 2. create a todo list from the matching playbook; -3. use real parallel helpers when the host exposes them; -4. fall back explicitly to the lead agent when helper spawning is unavailable; +3. use real parallel helpers when available; +4. fall back explicitly when helper spawning is unavailable; 5. verify the result before declaring completion. -For a read-only smoke test, try: +For a read-only smoke test: ```text /how explain how configuration reaches the command handler. @@ -80,10 +70,10 @@ On a broad subsystem, confirm the adapter fans out several read-only explorers. ## Understand mode lifetime -See `skills/pstack/references/host-lifecycle.md` for the host-by-host matrix. +See `skills/pstack/references/host-lifecycle.md` for the current compatibility runtime matrix. - When the host preserves skill state, `/poteto-mode` can remain active across turns in the current conversation. -- When the host does not provide persistent mode state, invoke `/pstack` or `/poteto-mode` again after a new session, context reset, or compaction. +- Otherwise invoke `/ystack` or `/poteto-mode` again after a new session, context reset, or compaction. - Never claim sticky mode on a host that cannot enforce it. Next: [Route work through `/poteto-mode`](./02-poteto-mode.md). diff --git a/docs/guide/03-understand.md b/docs/guide/03-understand.md index 5231c6c..7a30582 100644 --- a/docs/guide/03-understand.md +++ b/docs/guide/03-understand.md @@ -1,6 +1,6 @@ # Understand the code before changing it -Editing code you don't understand is how subtle regressions ship. pstack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it's shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic. +Editing code you do not understand is how subtle regressions ship. ystack gives you four ways in. `/how` explains what the code does now. `/why` digs up the reasons it is shaped that way. `/teach` blends both into one explanation. `/recall` rebuilds your own recent context on a topic. ![A detective studies a machine blueprint with a magnifying glass while robots fetch case files; the evidence board behind her links clues under /how and /why.](./images/understanding.jpg) @@ -10,7 +10,7 @@ Editing code you don't understand is how subtle regressions ship. pstack gives y /how do we dedupe notifications? is there an n+1 when we look up subscribers? ``` -Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, the key types, and the non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains. +Ask the question you actually have. [`/how`](../../skills/how/SKILL.md) reads the code and answers at the level of a senior engineer onboarding you onto the subsystem, with the runtime flow, key types, and non-obvious parts. For a big subsystem it fans out two to four read-only explorers first. For a narrow question it just reads and explains. `/how` can also push back on the design. Ask for Critique mode when you suspect the structure itself: @@ -26,9 +26,9 @@ The explanation comes first, so the critique stays grounded in how the thing rea /why was the retry limit set to five? does the reason still hold? ``` -[`/why`](../../skills/why/SKILL.md) works like a detective on a cold case. It starts from source control, then queries whatever evidence categories your MCPs expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics, all in parallel. The report cites everything, separates direct evidence from inference, and says "appears to" when the record is thin. A null result gets reported too, because "nobody wrote down why" is itself an answer. +[`/why`](../../skills/why/SKILL.md) starts from source control, then queries whatever evidence categories your connected tools expose, such as the issue tracker, long-form docs, team chat, observability, error tracking, and analytics. The report cites evidence, separates direct facts from inference, and reports null results too. -The two compose naturally. `do why first then how` is a perfectly good prompt when you suspect the history explains the mess. +The two compose naturally. `do why first then how` is a good prompt when you suspect history explains the structure. ## Actually understand it with `/teach` @@ -36,7 +36,7 @@ The two compose naturally. `do why first then how` is a perfectly good prompt wh /teach me how this PR changes retries. convince me it fixes the cause and not the symptom. ``` -[`/teach`](../../skills/teach/SKILL.md) is for when a summary isn't enough. It runs `/how` and `/why`, for a small change maybe just one of them, and weaves the findings into a plain explanation that builds up diagram by diagram. The "convince me" framing is worth stealing. It turns the explanation into an argument you can poke at instead of a tour. +[`/teach`](../../skills/teach/SKILL.md) is for when a summary is not enough. It runs `/how` and `/why`, then weaves the findings into an explanation you can challenge. ## Rebuild your own context with `/recall` @@ -44,18 +44,18 @@ The two compose naturally. `do why first then how` is a perfectly good prompt wh /recall catch me up on the export work from last week ``` -[`/recall`](../../skills/recall/SKILL.md) mines your own recent chats plus the shared record (issues, prior fixes, errors still firing) and hands back a brief on where things stand and what's next. Use it when you're returning to a topic cold. If you want to resume one specific chat, that's the Session pickup playbook below, not `/recall`. +[`/recall`](../../skills/recall/SKILL.md) mines authorized recent context plus the shared project record and returns a brief on where things stand and what comes next. ## Take over prior work with Session pickup -When another agent (or you, last week) left a branch mid-flight: +When another agent or an earlier session left a branch mid-flight: ```text -/poteto-mode take over this branch. read the decision log, figure out what's done, and continue from there. don't redo finished work. +/ystack take over this branch. read the decision log, figure out what is done, and continue from there. do not redo finished work. ``` -The [Session pickup playbook](../../skills/poteto-mode/playbooks/session-pickup.md) treats the prior trail as authoritative. It reconstructs the branch state and decisions, names the resume point, and verifies inherited claims against the original goal instead of re-deriving everything from scratch. +The [Session pickup playbook](../../skills/poteto-mode/playbooks/session-pickup.md) reconstructs branch state and decisions, names the resume point, and verifies inherited claims against the original goal. -**Pitfall:** don't skip this page's skills because "the agent will read the code anyway." An agent that starts editing without a traced model tends to fix the symptom at the first plausible spot. `/how` first is cheaper than the second bug. +**Pitfall:** do not skip these skills because "the agent will read the code anyway." `/how` first is cheaper than the second bug. Next: [Design the change](./04-design.md). diff --git a/docs/guide/04-design.md b/docs/guide/04-design.md index 681d39c..3cc0540 100644 --- a/docs/guide/04-design.md +++ b/docs/guide/04-design.md @@ -10,9 +10,9 @@ One attempt at a hard design locks in the first shape the model thought of. `/ar /architect design the import pipeline before writing any code. i care most about how callers use it. ``` -[`/architect`](../../skills/architect/SKILL.md) grounds itself first, running `/how` over the code the design touches and `/why` when it moves ownership or layers. Then it runs `/arena` to produce competing design sketches, with the caller's usage written first in each, followed by types, signatures, and a module map. +[`/architect`](../../skills/architect/SKILL.md) grounds itself first, running `/how` over the code the design touches and `/why` when it moves ownership or layers. Then it runs `/arena` to produce competing design sketches, with caller usage first, followed by types, signatures, and a module map. -By default it proceeds straight from the synthesized design into implementation. If you want to see the design first, say so: +By default it proceeds from the synthesized design into implementation. Ask for a checkpoint when you want to review the design first: ```text /architect with checkpoint. stop and show me before implementing. @@ -24,7 +24,7 @@ By default it proceeds straight from the synthesized design into implementation. /arena take my prompt to the arena verbatim. i want to compare their proposals with yours. ``` -[`/arena`](../../skills/arena/SKILL.md) is the general tool underneath. N subagents attempt the same design or code brief in parallel, each writing to its own worktree or directory. A read-only judge, on a different model family when your configuration allows one, scores every candidate against a rubric. The coordinator reads each candidate end to end, picks a base, grafts in the best ideas from the losers, and verifies the result. +[`/arena`](../../skills/arena/SKILL.md) gives N subagents the same design or code brief, each in an isolated output location. A read-only cross-judge scores candidates against a rubric. The lead reads every candidate, picks a base, grafts the strongest parts from the others, and verifies the synthesized result. ```mermaid flowchart LR @@ -40,11 +40,7 @@ flowchart LR H --> I[Verify] ``` -The panel comes from your [`/setup-pstack`](../../skills/setup-pstack/SKILL.md) configuration, and you can adjust it per task. Ask for more candidates when the decision matters, fewer when it doesn't: - -```text -/arena this, 5 candidates. the cache key format is expensive to change later. -``` +The panel comes from your [`/setup-ystack`](../../skills/setup-ystack/SKILL.md) configuration, and you can adjust it per task. ## Cover slices and races with `/swarm` @@ -52,30 +48,24 @@ The panel comes from your [`/setup-pstack`](../../skills/setup-pstack/SKILL.md) /swarm check every package under packages/ against its check.sh. one worker per package. one report. ``` -[`/swarm`](../../skills/swarm/SKILL.md) fans N workers across independent slices, coverage matrices, gauntlet lanes, exploration partitions, or declared race arms. Each worker gets its own scope and check, then reports `PASS`, `ISSUES`, or `BLOCKED`. The parent waits for the workers and returns one compact report with any gaps or dropouts. - -Reach for it when parallelism buys coverage or lets independent checks race. `/arena` gives every worker the same design or code brief, then picks a base and grafts the best parts. `/swarm` covers slices or runs a race with a selection rule declared up front. It does not use the base-selection and grafting ceremony. +[`/swarm`](../../skills/swarm/SKILL.md) fans workers across independent slices, coverage matrices, gauntlet lanes, exploration partitions, or declared race arms. `/arena` gives every worker the same artifact and synthesizes one winner; `/swarm` covers distinct slices or races independently. ## Break it with `/interrogate` ```text -/interrogate the whole branch, but skeptically. no nitpicks unless it's an actual bug or regression. +/interrogate the whole branch, but skeptically. no nitpicks unless it is an actual bug or regression. ``` -[`/interrogate`](../../skills/interrogate/SKILL.md) sends the same diff, intent, and rubric to several reviewers on different model families. Model diversity is the point. Different models have different blind spots, so a finding two models raise independently is high-confidence signal. The lead sorts everything into `Act on`, `Consider`, `Noted`, and `Dismissed`, with a reason for each dismissal, and applies nothing automatically. - -Read the dismissals too. The lead is a pragmatic senior engineer, not an oracle, and you can override it. +[`/interrogate`](../../skills/interrogate/SKILL.md) sends the same diff, intent, and rubric to several reviewers. The lead deduplicates findings and sorts them into `Act on`, `Consider`, `Noted`, and `Dismissed`, with reasons. ## How much design work does a task deserve? -You might be wondering whether every change needs this. No. Most changes need none of it. A rough ladder: - -- A small, finished change you're unsure about needs `/interrogate` alone. -- A change that crosses function boundaries or moves ownership earns `/architect`, which brings `/arena` with it. -- A standalone decision where independent attempts would help, like naming, formats, or an algorithm, is `/arena` directly. -- A coverage matrix, set of parallel checks, or race with declared arms is `/swarm`. -- A contested design that's expensive to reverse gets `/architect`, then `/interrogate` before shipping. +- A small finished change you are unsure about may need `/interrogate` alone. +- Boundary-crossing work earns `/architect`, which brings `/arena` with it. +- A standalone artifact with several valid shapes can use `/arena` directly. +- A coverage matrix or parallel race belongs to `/swarm`. +- A contested, expensive-to-reverse design gets `/architect`, then `/interrogate` before shipping. -`/poteto-mode` already applies this ladder. Boundary-crossing work triggers `/architect` on its own, so you reach for these directly mainly when you want more or less scrutiny than the default. +`/ystack` and `/poteto-mode` apply this ladder automatically. Next: [Build and clean the change](./05-build-and-clean.md). diff --git a/docs/guide/07-overnight.md b/docs/guide/07-overnight.md index 0f9282f..36020eb 100644 --- a/docs/guide/07-overnight.md +++ b/docs/guide/07-overnight.md @@ -1,15 +1,13 @@ # Run work while you sleep -An agent you can trust to verify its own work is an agent you can leave with a bounded hard task. What makes that safe is not hope. It is a checkable finish condition, an isolated workspace, an explicit permission boundary, and a decision trail you can audit afterward. +An agent you can trust to verify its own work is an agent you can leave with a bounded hard task. Safety comes from a checkable finish condition, isolated workspace, explicit permission boundary, and decision trail you can audit afterward. ![She waves goodnight from the door while robots keep the factory running, one updating a DECISION LOG wall board under a BUILD LOOP ACTIVE sign.](./images/overnight.jpg) ## The unattended-run contract -A useful handoff names the goal, finish condition, permissions, and escape hatch: - ```text -/poteto-mode I am going to bed. Migrate every caller to the new parser in a fresh worktree off . +/ystack I am going to bed. Migrate every caller to the new parser in a fresh worktree off . Done means zero old callers, every parser fixture passes, the old API is deleted, and the real command works. Keep a decision trail. You may commit on the task branch. Do not merge, deploy, or force-push. Continue until the predicate passes. If a genuine blocker survives the investigation loop, pause safely and document it. @@ -22,11 +20,11 @@ Each line serves a purpose: - A fresh worktree isolates the run from unrelated local work. - Commit permission avoids a predictable reversible-action pause. - Explicit merge, deploy, and history-rewrite boundaries preserve irreversible checkpoints. -- The escape hatch turns a true dead end into a reviewable handoff rather than hours of goal reinterpretation. +- The escape hatch turns a dead end into a reviewable handoff. -The active coding agent may provide a native long-running or loop mechanism. The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) uses it when available. When the host does not provide one, pstack keeps the same iteration contract in the current session and relies on [Pause safely](../../skills/poteto-mode/playbooks/pause-safely.md) plus [Session pickup](../../skills/poteto-mode/playbooks/session-pickup.md) across session boundaries. +The active coding agent may provide a native long-running mechanism. The [Autonomous run playbook](../../skills/poteto-mode/playbooks/autonomous-run.md) uses it when available. Otherwise ystack keeps the same iteration contract in the current session and relies on [Pause safely](../../skills/poteto-mode/playbooks/pause-safely.md) plus [Session pickup](../../skills/poteto-mode/playbooks/session-pickup.md) across session boundaries. -For broad or unusual unattended work, `/poteto-mode` may route through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md) to design the phases, evidence contract, and decision trail before implementation starts. +For broad or unusual unattended work, ystack may route through [`/figure-it-out`](../../skills/figure-it-out/SKILL.md) to design phases, evidence, and the decision trail before implementation. ## What the loop does @@ -43,42 +41,22 @@ flowchart TD H --> A ``` -One hypothesis, one change, one check, and one decision row per iteration. Changes that do not help are reverted rather than left to ride. A plateau triggers a new mechanism or a safer pause; it does not relax the finish condition. +One hypothesis, one change, one check, and one decision row per iteration. Changes that do not help are reverted. A plateau triggers a new mechanism or a safe pause; it does not relax the finish condition. ## The morning audit -[`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) makes the run reviewable. Each TSV row records the time, phase, decision, reason, evidence pointer, and result. The log stays local by default and is committed only when the work is large or risky enough that reviewers need it. - -When you return, ask for a review-form recap: +[`/show-me-your-work`](../../skills/show-me-your-work/SKILL.md) makes the run reviewable. Each TSV row records the time, phase, decision, reason, evidence pointer, and result. ```text /show-me-your-work catch me up on the unattended run ``` -The skill checks the log against repository state, verification artifacts, and whatever authorized action or session evidence the host exposes. When independent helpers are available, a fresh reviewer looks for weak evidence, wrong-surface verification, scope creep, and risky decisions. Read the resulting **Attention** section first, then inspect the rows it cites. +When independent helpers are available, a fresh reviewer looks for weak evidence, wrong-surface verification, scope creep, and risky decisions. ## One task, a queue, or a program -The contract above drives one task toward one finish predicate. Larger unattended workloads use different playbooks. - -[Autopilot-full](../../skills/poteto-mode/playbooks/autopilot-full.md) handles a queue of independent pull requests. Each pull request has one owner and an independent verification gate. Use it only when the user has explicitly authorized the intended merge behavior: - -```text -/poteto-mode full autopilot on this independent queue. Verify every final head. Merge only under the permissions stated here. -``` - -[Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) builds one ordered stack without landing it. Choose it for coupled changes or when you want to inspect the entire stack before any merge: - -```text -/poteto-mode build these five changes as one verified stack. Do not merge. I will review it in the morning. -``` - -[Orchestrate](../../skills/poteto-mode/playbooks/orchestrate.md) is for a program that outlives one agent session: multiple phases, many pull requests, several owners, and a persistent coordination record. It is deliberately heavier than an overnight task: - -```text -/poteto-mode orchestrate the store migration until every package is converted and reviewable. Keep irreversible actions behind my checkpoint. -``` +[Autopilot-full](../../skills/poteto-mode/playbooks/autopilot-full.md) handles a queue of independent pull requests. [Autopilot-stack](../../skills/poteto-mode/playbooks/autopilot-stack.md) builds one ordered stack without landing it. [Orchestrate](../../skills/poteto-mode/playbooks/orchestrate.md) coordinates a program that outlives one agent session. -**Pitfall:** duration is not a finish condition. “Work for four hours” gives the agent no objective predicate. State what must be true, how it will be checked, which actions are allowed, and when to pause safely. +**Pitfall:** duration is not a finish condition. State what must be true, how it will be checked, which actions are allowed, and when to pause safely. Next: [Steer with principle names](./08-principles.md). diff --git a/docs/guide/08-principles.md b/docs/guide/08-principles.md index 97dc61c..94b5a18 100644 --- a/docs/guide/08-principles.md +++ b/docs/guide/08-principles.md @@ -1,69 +1,63 @@ # Steer with principle names -pstack ships 21 principles as individual skills. `/poteto-mode` reads their index at the start of every multi-step task, applies the ones the task triggers, and names each applied principle in its reply along with the decision it changed. +ystack ships 21 principles as individual skills. `/ystack` and `/poteto-mode` read their index at the start of multi-step work, apply the principles the task triggers, and name each applied principle with the decision it changed. -You don't invoke principles. You use their names to steer. Each name points at a complete rule the agent has already read, so one phrase redirects the work more precisely than a paragraph of instructions. +You do not need to invoke principles directly. Use their names to steer. Each name points at a complete rule the agent has already read, so one phrase can redirect work more precisely than a paragraph. ## Steering in practice -Say the agent is about to bolt a new adapter onto three existing ones: - ```text -use subtract before you add. delete the obsolete adapters first, then design what's left. +use subtract before you add. delete the obsolete adapters first, then design what is left. ``` -Say it claims success because the build passed: - ```text apply prove it works. run the real import flow and show me the written records. ``` -Say two parallel attempts are about to write to the same branch: - ```text separate before serializing shared state. give each attempt its own worktree, no locks. ``` -Each phrase lands because the rule behind it is specific. The agent still has to say, in its reply, which decision the rule changed. A principle citation with no decision behind it is the tell that it name-dropped instead of applying. +A principle citation with no changed decision is decorative, not applied. ## The 21, briefly -The core principles decide how much to build and when to rethink the design: +### Core -- [Laziness Protocol](../../skills/principle-laziness-protocol/SKILL.md) prefers deletion and the smallest change that solves the problem. -- [Foundational Thinking](../../skills/principle-foundational-thinking/SKILL.md) chooses the core data structures before writing logic. -- [Redesign from First Principles](../../skills/principle-redesign-from-first-principles/SKILL.md) integrates a new requirement as if it had been there from day one. -- [Subtract Before You Add](../../skills/principle-subtract-before-you-add/SKILL.md) removes dead weight before building on top of it. -- [Minimize Reader Load](../../skills/principle-minimize-reader-load/SKILL.md) collapses layers and hidden state a reader must hold in their head. -- [Outcome-Oriented Execution](../../skills/principle-outcome-oriented-execution/SKILL.md) converges rewrites on the target design instead of preserving throwaway compatibility states. -- [Experience First](../../skills/principle-experience-first/SKILL.md) chooses the user's result over implementation convenience. -- [Exhaust the Design Space](../../skills/principle-exhaust-the-design-space/SKILL.md) builds two or three competing prototypes when there's no precedent. -- [Build the Lever](../../skills/principle-build-the-lever/SKILL.md) builds the script that does or proves the work, so a reviewer can rerun it. +- [Laziness Protocol](../../skills/principle-laziness-protocol/SKILL.md) +- [Foundational Thinking](../../skills/principle-foundational-thinking/SKILL.md) +- [Redesign from First Principles](../../skills/principle-redesign-from-first-principles/SKILL.md) +- [Subtract Before You Add](../../skills/principle-subtract-before-you-add/SKILL.md) +- [Minimize Reader Load](../../skills/principle-minimize-reader-load/SKILL.md) +- [Outcome-Oriented Execution](../../skills/principle-outcome-oriented-execution/SKILL.md) +- [Experience First](../../skills/principle-experience-first/SKILL.md) +- [Exhaust the Design Space](../../skills/principle-exhaust-the-design-space/SKILL.md) +- [Build the Lever](../../skills/principle-build-the-lever/SKILL.md) -The architecture principles decide where state, validation, and compatibility live: +### Architecture -- [Model the Domain](../../skills/principle-model-the-domain/SKILL.md) encodes repeated rules in one structure, not scattered conditionals. -- [Boundary Discipline](../../skills/principle-boundary-discipline/SKILL.md) validates at the boundary and trusts internal types. -- [Type System Discipline](../../skills/principle-type-system-discipline/SKILL.md) makes illegal states unrepresentable. -- [Make Operations Idempotent](../../skills/principle-make-operations-idempotent/SKILL.md) converges retries on the same end state. -- [Migrate Callers Then Delete Legacy APIs](../../skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) migrates and deletes in one wave. -- [Separate Before Serializing Shared State](../../skills/principle-separate-before-serializing-shared-state/SKILL.md) removes the sharing before adding coordination. +- [Model the Domain](../../skills/principle-model-the-domain/SKILL.md) +- [Boundary Discipline](../../skills/principle-boundary-discipline/SKILL.md) +- [Type System Discipline](../../skills/principle-type-system-discipline/SKILL.md) +- [Make Operations Idempotent](../../skills/principle-make-operations-idempotent/SKILL.md) +- [Migrate Callers Then Delete Legacy APIs](../../skills/principle-migrate-callers-then-delete-legacy-apis/SKILL.md) +- [Separate Before Serializing Shared State](../../skills/principle-separate-before-serializing-shared-state/SKILL.md) -The verification principles define what counts as proof: +### Verification -- [Prove It Works](../../skills/principle-prove-it-works/SKILL.md) verifies the real artifact, not a proxy. -- [Fix Root Causes](../../skills/principle-fix-root-causes/SKILL.md) reproduces and traces to the cause before changing code. -- [Sequence Work into Verifiable Units](../../skills/principle-sequence-verifiable-units/SKILL.md) ends each small unit in a check before starting the next. +- [Prove It Works](../../skills/principle-prove-it-works/SKILL.md) +- [Fix Root Causes](../../skills/principle-fix-root-causes/SKILL.md) +- [Sequence Work into Verifiable Units](../../skills/principle-sequence-verifiable-units/SKILL.md) -The delegation principles keep parallel work sane: +### Delegation -- [Guard the Context Window](../../skills/principle-guard-the-context-window/SKILL.md) routes bulk reading to subagents and keeps findings in the main chat. -- [Never Block on the Human](../../skills/principle-never-block-on-the-human/SKILL.md) proceeds on reversible work and presents the result. +- [Guard the Context Window](../../skills/principle-guard-the-context-window/SKILL.md) +- [Never Block on the Human](../../skills/principle-never-block-on-the-human/SKILL.md) -And one meta principle: +### Meta -- [Encode Lessons in Structure](../../skills/principle-encode-lessons-in-structure/SKILL.md) turns advice you've repeated twice into a lint, check, or script. +- [Encode Lessons in Structure](../../skills/principle-encode-lessons-in-structure/SKILL.md) -Don't memorize the list. Skim it now, then come back when you catch the agent doing something a name here would have prevented. That's how the vocabulary sticks. +Do not memorize the list. Return when you catch the agent doing something a principle name would have prevented. Next: [Make it yours](./09-make-it-yours.md). diff --git a/docs/guide/README.md b/docs/guide/README.md index e376601..41a65b3 100644 --- a/docs/guide/README.md +++ b/docs/guide/README.md @@ -1,10 +1,10 @@ -# The pstack guide +# The ystack guide -pstack works best when you stop micromanaging the agent. You describe what you want and how you'll know it's done. `/poteto-mode` picks the playbook, runs the other skills as the steps need them, and shows you the evidence. This guide teaches that habit with realistic prompts. +ystack works best when you stop micromanaging the agent. You describe what you want and how you'll know it is done. `/ystack` picks the playbook, runs the other skills as the steps need them, and shows you the evidence. `/poteto-mode` remains available when you want the full upstream-style mode contract. Here's what you'll learn: -1. [Set up pstack](./01-setup.md). Install the plugin and pick your models. +1. [Set up ystack](./01-setup.md). Install the pack and pick your models. 2. [Route work through `/poteto-mode`](./02-poteto-mode.md). Give it a goal and watch it pick a playbook. 3. [Understand the code](./03-understand.md). `/how`, `/why`, `/teach`, and `/recall` before you edit anything. 4. [Design the change](./04-design.md). `/architect`, `/arena`, `/swarm`, and `/interrogate` before code locks in a shape. @@ -22,9 +22,9 @@ Read the pages in order the first time. After that, each page stands alone. Give the agent a goal and a way to check it, in your own words: ```text -/poteto-mode the export writes duplicate rows when a retry lands mid-run. repro first, then fix and verify. +/ystack the export writes duplicate rows when a retry lands mid-run. repro first, then fix and verify. ``` -You don't need to name a playbook or list skills. "repro first" and a checkable outcome are all the routing signal `/poteto-mode` needs. It matches the Bug fix playbook, copies the steps into a todo list, and calls the right skills as each step fires. +You do not need to name a playbook or list skills. "repro first" and a checkable outcome are all the routing signal ystack needs. It matches the Bug fix playbook, copies the steps into a todo list, and calls the right skills as each step fires. -Next: [Set up pstack](./01-setup.md). +Next: [Set up ystack](./01-setup.md). diff --git a/scripts/check_branding.py b/scripts/check_branding.py new file mode 100755 index 0000000..2cda211 --- /dev/null +++ b/scripts/check_branding.py @@ -0,0 +1,78 @@ +#!/usr/bin/env python3 +"""Check ystack's public naming boundary and legacy compatibility entries.""" + +from __future__ import annotations + +import json +import sys +from pathlib import Path + +ROOT = Path(__file__).resolve().parents[1] +SELF = Path(__file__).resolve() + +REQUIRED_SNIPPETS = { + "README.md": ("# ystack", "Go7hic/ystack", "`/ystack`"), + "INSTALL.md": ("Go7hic/ystack", "/setup-ystack", "ystack-models"), + "skills/ystack/SKILL.md": ("name: ystack", "# ystack", "../pstack/references"), + "skills/setup-ystack/SKILL.md": ("name: setup-ystack", "# Setup ystack"), + "skills/pstack/SKILL.md": ("Legacy compatibility alias", "../ystack/SKILL.md"), + "skills/setup-pstack/SKILL.md": ("Legacy compatibility alias", "../setup-ystack/SKILL.md"), +} + +# Construct the retired repository slug without embedding it literally in this +# file; the checker scans repository text, including maintenance scripts. +OLD_REPO = "Go7hic" + "/" + "pstack" +STALE_REPO_SLUGS = (OLD_REPO, "github.com/" + OLD_REPO) +TEXT_SUFFIXES = {".md", ".json", ".py", ".yml", ".yaml", ".toml", ".txt"} + + +def text_files() -> list[Path]: + files: list[Path] = [] + for path in ROOT.rglob("*"): + if path.resolve() == SELF: + continue + if not path.is_file() or path.suffix.lower() not in TEXT_SUFFIXES: + continue + if ".git" in path.parts: + continue + files.append(path) + return sorted(files) + + +def main() -> int: + errors: list[str] = [] + + for rel, snippets in REQUIRED_SNIPPETS.items(): + path = ROOT / rel + if not path.is_file(): + errors.append(f"missing required branding file: {rel}") + continue + text = path.read_text(encoding="utf-8") + for snippet in snippets: + if snippet not in text: + errors.append(f"{rel}: missing required snippet {snippet!r}") + + for path in text_files(): + text = path.read_text(encoding="utf-8") + rel = path.relative_to(ROOT).as_posix() + for slug in STALE_REPO_SLUGS: + if slug in text: + errors.append(f"{rel}: stale repository slug {slug!r}") + + manifest_path = ROOT / "UPSTREAM_MANIFEST.json" + if manifest_path.is_file(): + data = json.loads(manifest_path.read_text(encoding="utf-8")) + portable = data.get("portable", {}) + if portable.get("public_name") != "ystack": + errors.append("UPSTREAM_MANIFEST.json: portable.public_name must be 'ystack'") + if "pstack" not in portable.get("legacy_names", []): + errors.append("UPSTREAM_MANIFEST.json: legacy_names must include 'pstack'") + + for error in errors: + print(f"ERROR: {error}") + print(f"branding check: {len(errors)} error(s)") + return 1 if errors else 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/scripts/fixtures/model-override/valid.md b/scripts/fixtures/model-override/valid.md index 34fc655..d973697 100644 --- a/scripts/fixtures/model-override/valid.md +++ b/scripts/fixtures/model-override/valid.md @@ -1,5 +1,5 @@ --- -description: pstack model overrides +description: ystack model overrides alwaysApply: true --- diff --git a/skills/poteto-mode/references/adapters/claude-code.md b/skills/poteto-mode/references/adapters/claude-code.md index eb89975..df08936 100644 --- a/skills/poteto-mode/references/adapters/claude-code.md +++ b/skills/poteto-mode/references/adapters/claude-code.md @@ -1,6 +1,6 @@ # Adapter: Claude Code -Use inside [Claude Code](https://code.claude.com) when the `Agent` tool is available (older builds may still expose it as `Task` — treat them as the same capability). +Use inside [Claude Code](https://code.claude.com) when the `Agent` tool is available. Older builds may expose it as `Task`; treat both as the same capability. ## Detect @@ -12,27 +12,26 @@ Use inside [Claude Code](https://code.claude.com) when the `Agent` tool is avail | Capability | How | | --- | --- | -| `explore` | `Agent` / `Task` with `subagent_type: Explore` (or equivalent explore agent). Prefer thoroughness `medium` unless the slice is tiny (`quick`) or broad (`very thorough`). Read-only; do not edit. | -| `implement` | `Agent` / `Task` with `subagent_type: general-purpose` (or a custom worker). Pass disjoint file scopes. Optionally `isolation: "worktree"` when the runtime supports it and writes would collide. | -| `review` | Separate `Agent` calls with distinct rubrics/models. Prefer read-only tools / deny edits in the prompt. | -| `parallel` | Emit **multiple** `Agent`/`Task` calls in **one** assistant turn. Independent slices only. Use `run_in_background: true` when available and the parent continues non-overlapping work; collect with the runtime’s task-output mechanism if needed. | -| `ask_user` | Plain chat (or Claude’s question UI if present). Facts you can observe → do not ask. | -| `verify` | Bash / browser tools on the matching surface. Prefer the narrowest meaningful command. | -| `model_role` | Pass `model` on the Agent call when the override file names a confirmed slug. Otherwise omit and inherit. Explore often inherits/caps — do not fight the runtime. | +| `explore` | `Agent` / `Task` with `subagent_type: Explore` or an equivalent read-only agent. | +| `implement` | `Agent` / `Task` with `subagent_type: general-purpose` or a custom worker. Pass disjoint file scopes. | +| `review` | Separate calls with distinct rubrics/models. Deny edits in the prompt. | +| `parallel` | Emit multiple `Agent` / `Task` calls in one assistant turn for independent slices. Use background execution only when supported. | +| `ask_user` | Plain chat or the host's question UI. Do not ask for observable facts. | +| `verify` | Bash and browser tools on the matching surface. | +| `model_role` | Pass `model` only when an override names a confirmed slug; otherwise inherit. | ## Policy -- Lead agent owns synthesis, final patch judgment, and verification. -- Do not trust subagent “done” summaries; read the diff / returned paths. -- Keep worker write scopes disjoint. Tell workers not to revert others’ edits. -- Respect spawn / concurrent subagent limits; if spawn fails, finish remaining work locally or sequentially. -- Nested subagents: prefer shallow fan-out from the lead. Do not build deep trees unless the playbook requires it. -- If `Agent`/`Task` is missing, fall back to `generic.md`. +- The lead owns synthesis, final patch judgment, and verification. +- Do not trust helper completion summaries without reading the diff or artifacts. +- Keep worker write scopes disjoint. +- Prefer shallow fan-out from the lead. +- Fall back to `generic.md` when spawning is unavailable. ## Model override file -Prefer `~/.agents/pstack-models.md` or a Claude user rule. `/setup-pstack` should write beside the active agent. +Prefer `~/.agents/ystack-models.md` or a Claude user rule written by `/setup-ystack`. If absent, honor `~/.agents/pstack-models.md` as a legacy fallback. `/setup-pstack` is an alias for the new setup skill. ## Poteto worker rubric -When a playbook wants a full-style worker, spawn `general-purpose` (or a custom droid/agent you configured) and prepend instructions from `../agents/poteto-agent.md`. +When a playbook wants a full-style worker, spawn `general-purpose` or a configured custom agent and prepend `../agents/poteto-agent.md`. diff --git a/skills/poteto-mode/references/adapters/codex-models.md b/skills/poteto-mode/references/adapters/codex-models.md index cf924e1..e41804b 100644 --- a/skills/poteto-mode/references/adapters/codex-models.md +++ b/skills/poteto-mode/references/adapters/codex-models.md @@ -1,26 +1,27 @@ # Codex model notes -Companion to `adapters/codex.md`. Validate every slug against **current** Codex tool metadata before use; this file is illustrative. +Companion to `codex.md`. Validate every model identifier against current Codex tool metadata before use; examples here are structural, not a live catalog. -## Override file +## Override files -Prefer: +Preferred: ```text -~/.codex/rules/pstack-models.md +~/.codex/rules/ystack-models.md ``` -Legacy name from the old pack (still honored if present): +Legacy fallbacks, in order: ```text +~/.codex/rules/pstack-models.md ~/.codex/rules/codex-pstack-models.md ``` -`/setup-pstack` writes the new path using the portable JSON fence from `../model-override.schema.json`: +`/setup-ystack` reads a legacy file when needed and writes the preferred ystack path using the JSON fence from `../model-override.schema.json`: ````markdown --- -description: pstack model overrides +description: ystack model overrides alwaysApply: true --- @@ -42,19 +43,15 @@ alwaysApply: true ``` ```` -Use `inherit-parent` or `auto` to omit `model` on that role. Optional effort can be encoded in the slug string only when Codex requires a combined token; otherwise keep effort in adapter-specific notes beside the override. +Use `inherit-parent` or `auto` to omit an explicit child model. Keep reasoning effort in adapter-supported fields unless the runtime explicitly encodes it in the model identifier. -## Role → intent +## Role intent | Role | Intent | | --- | --- | -| `feature_impl` | everyday implementation / refactoring | +| `feature_impl` | everyday implementation and refactoring | | `bug_impl` | high-stakes reasoning after evidence | -| `judgment` | synthesis, architecture, unslop-sensitive replies | +| `judgment` | synthesis, architecture, and prose | | `fast_explore` | fast read-only or mechanical fan-out | -| `critic` | adversarial / panel diversity | +| `critic` | adversarial and panel diversity | | panel arrays | one helper per entry; prefer diverse families | - -## Effort - -When the API separates reasoning effort from the model slug, set it from host-supported fields. Do not invent effort values the tool rejects. diff --git a/skills/poteto-mode/references/adapters/codex.md b/skills/poteto-mode/references/adapters/codex.md index f410113..0fb8580 100644 --- a/skills/poteto-mode/references/adapters/codex.md +++ b/skills/poteto-mode/references/adapters/codex.md @@ -1,60 +1,61 @@ # Adapter: Codex -Use inside [OpenAI Codex](https://chatgpt.com/codex) (CLI / IDE) when multi-agent tools are available. This is the portable replacement for the old `codex-pstack` pack — install this repo’s skills under `~/.codex/skills/` and delete `codex-pstack`. +Use inside OpenAI Codex CLI or IDE when multi-agent tools are available. This pack replaces the obsolete standalone `codex-pstack` pack; install ystack under the normal Codex skills tree and remove the old standalone pack. ## Detect -- Multi-agent tools such as `multi_agent_v1.spawn_agent` (names may evolve; follow current tool metadata) +- Current Codex multi-agent spawn tools - Skills under `~/.codex/skills/` or project Codex skill paths -- Optional model override at `~/.codex/rules/pstack-models.md` +- Preferred model override at `~/.codex/rules/ystack-models.md` +- Legacy fallback at `~/.codex/rules/pstack-models.md` or `codex-pstack-models.md` ## Capability map | Capability | How | | --- | --- | -| `explore` | `spawn_agent` with `agent_type: explorer`. Explicitly prohibit edits. Prefer local `rg`/reads first for tiny questions; fan out 2–4 explorers for broad subsystems. | -| `implement` | `spawn_agent` with `agent_type: worker` (or `default` when worker is unavailable). Bounded, disjoint file scopes. Prepend the poteto worker rubric from `../agents/poteto-agent.md` when the playbook wants full-style implementation. | -| `review` | Separate agents (`explorer` or `default`) with distinct rubrics. Prohibit edits in the prompt. Diverse `model` / `reasoning_effort` when the panel needs independent judgment. | -| `parallel` | Spawn **multiple** agents in one turn for independent slices. Continue non-overlapping lead work while they run. Do not wait serially unless scopes collide. | -| `ask_user` | Plain chat. Only product/preference forks that no experiment can settle. | -| `verify` | Local shell. Narrowest meaningful check first, then broaden. | -| `model_role` | Set `model` (+ `reasoning_effort` when supported) only from confirmed Codex slugs / the override file. Never copy Cursor model slugs. | +| `explore` | Spawn an explorer agent and explicitly prohibit edits. Use local reads first for tiny questions. | +| `implement` | Spawn a worker or default agent with bounded, disjoint file scope. Include the Poteto worker rubric when requested. | +| `review` | Separate read-only agents with distinct rubrics and, when useful, diverse models or reasoning effort. | +| `parallel` | Spawn multiple independent agents in one turn and continue non-overlapping lead work. | +| `ask_user` | Plain chat for product or preference decisions only. | +| `verify` | Local shell and available runtime tools, narrowest meaningful check first. | +| `model_role` | Set model and optional reasoning effort only from confirmed Codex identifiers or the override file. | -## Cursor → Codex translation +## Cursor to Codex translation -| Cursor / portable concept | Codex | +| Portable concept | Codex | | --- | --- | -| `Task` / `Agent` / `task` | `multi_agent_v1.spawn_agent` (or current equivalent) | -| explore helper | `agent_type: explorer` | -| implement helper | `agent_type: worker` or `default` | -| `run_in_background: true` | spawn and continue local non-overlapping work | -| `readonly: true` | `explorer` + explicit no-edit rule | -| poteto-agent type | `worker`/`default` + `../agents/poteto-agent.md` prompt | -| Comment Sicko | `review` helper + `../agents/comment-sicko.md` rubric | -| Cursor model slug | Codex `model` + optional `reasoning_effort` from override file | +| helper spawn | current Codex multi-agent spawn tool | +| explore helper | explorer agent | +| implement helper | worker or default agent | +| background work | spawn and continue non-overlapping lead work | +| read-only intent | explorer plus explicit no-edit rule | +| Poteto worker | worker/default plus `../agents/poteto-agent.md` | +| Comment Sicko | review helper plus `../agents/comment-sicko.md` | +| model role | confirmed Codex model plus optional reasoning effort | ## Policy -- Prefer real parallel fan-out for how-complex, arena, swarm, interrogate, and playbook delegates. -- Critical-path synthesis stays on the lead agent. You own the final answer, patch, and verification. -- Keep worker write scopes disjoint. Tell workers not to revert or overwrite others’ edits. -- Close / stop completed agents when you no longer need them. -- If multi-agent tools are missing or spawn is denied, fall back to `generic.md` and say so. +- Prefer real parallel fan-out for broad How, Arena, Swarm, Interrogate, and independent playbook delegates. +- Critical-path synthesis stays on the lead. +- Keep worker write scopes disjoint. +- Close completed agents when they are no longer needed. +- Fall back to `generic.md` when multi-agent tools are unavailable or denied. -## Model roles (defaults) +## Model roles -Resolve via `/setup-pstack` → `~/.codex/rules/pstack-models.md`. See `codex-models.md` for override shape and legacy path notes. +Resolve through `/setup-ystack` and `~/.codex/rules/ystack-models.md`. If absent, read legacy pstack paths. See `codex-models.md` for the override shape. | Role | Typical use | | --- | --- | -| `fast_explore` | how explorers, swarm workers, mechanical edits | -| `feature_impl` | feature / refactoring workers | -| `bug_impl` | bug-fix / perf / hillclimb | -| `judgment` | synthesis, prose, hardest design calls | -| `critic` | arena / architect / interrogate / how-critics panels | +| `fast_explore` | broad reading and mechanical work | +| `feature_impl` | feature and refactoring workers | +| `bug_impl` | bug, performance, and hillclimb work | +| `judgment` | synthesis, prose, and hard design calls | +| `critic` | Arena, Architect, Interrogate, and How critique panels | -Omit `model` when the override says `inherit-parent` / `auto`, or when a single parent model is enough. +Omit an explicit child model when the override says `inherit-parent` or `auto`. ## Poteto worker rubric -For playbook code delegates, spawn `worker`/`default` and include the instructions from `../agents/poteto-agent.md` in the agent prompt so style and principles load even without a Cursor `poteto-agent` type. +For code delegates, include `../agents/poteto-agent.md` in the worker prompt so the full engineering discipline loads without a vendor-specific helper type. diff --git a/skills/poteto-mode/references/adapters/droid.md b/skills/poteto-mode/references/adapters/droid.md index e47e620..a4a2dfb 100644 --- a/skills/poteto-mode/references/adapters/droid.md +++ b/skills/poteto-mode/references/adapters/droid.md @@ -1,10 +1,10 @@ # Adapter: Droid (Factory) -Use inside [Factory Droid](https://docs.factory.ai/harness/subagents) when the `Task` tool can spawn subagents / custom droids. +Use inside Factory Droid when the Task tool can spawn subagents or custom droids. ## Detect -- `Task` tool with `subagent_type`, `run_in_background`, `resume`, `complexity` +- Task tool with helper, background, resume, and complexity controls - Skills under `~/.factory/skills/` or `.factory/skills/` - Optional custom droids under `~/.factory/droids/` or `.factory/droids/` @@ -12,27 +12,27 @@ Use inside [Factory Droid](https://docs.factory.ai/harness/subagents) when the ` | Capability | How | | --- | --- | -| `explore` | `Task` with a read-only custom droid if you have one, otherwise the default research/read-oriented subagent. Explicitly forbid edits in the prompt. Prefer `complexity: light` or `medium` for exploration. | -| `implement` | `Task` with a coding subagent / general droid. Bounded file scope. Use `complexity: medium` or `heavy` for hard fixes. Disjoint write scopes across workers. | -| `review` | Separate `Task` reviewers with distinct rubrics. Prefer read-only tool policy on review droids. | -| `parallel` | Multiple `Task` calls in one turn, and/or `run_in_background: true` then collect with `TaskOutput`. Independent slices only. | -| `ask_user` | Plain chat. Only product/preference forks. | -| `verify` | Execute / browser tools on the matching surface. Narrowest meaningful check. | -| `model_role` | Prefer `complexity` routing when it maps to your settings; otherwise set an explicit model if the Task API allows it and the slug is confirmed. | +| `explore` | Use a read-oriented helper and explicitly forbid edits. | +| `implement` | Use a coding helper with bounded file scope and appropriate complexity. | +| `review` | Separate reviewers with distinct rubrics and read-only policy. | +| `parallel` | Issue multiple independent Tasks and collect through the host's task-output mechanism. | +| `ask_user` | Plain chat for product or preference forks only. | +| `verify` | Execute or browser tools on the matching surface. | +| `model_role` | Prefer supported complexity routing or a confirmed explicit model. | ## Policy -- Lead droid owns synthesis, final patch judgment, and verification. -- Background tasks: track `task_id`, wait via `TaskOutput`, stop via `TaskStop` when abandoning work. -- `resume` only when continuing the same helper’s context beats a fresh spawn. -- Keep write scopes disjoint across parallel Tasks. -- Large multi-feature campaigns may use Factory Missions when available; still apply pstack playbook gates (verify, prove-it-works). -- If `Task` is missing, fall back to `generic.md`. +- The lead droid owns synthesis, final patch judgment, and verification. +- Track background task identifiers and stop abandoned work. +- Resume only when preserving the same helper context is valuable. +- Keep parallel write scopes disjoint. +- Missions may coordinate broad campaigns, but ystack verification gates still apply. +- Fall back to `generic.md` when Task is unavailable. ## Model override file -`~/.agents/pstack-models.md` or a Factory-side rule written by `/setup-pstack`. +Prefer `~/.agents/ystack-models.md` or a Factory-side rule written by `/setup-ystack`. Honor `~/.agents/pstack-models.md` as a legacy fallback. ## Poteto worker rubric -Optional: add a custom droid whose system prompt includes `../agents/poteto-agent.md`, then target it as `subagent_type` for playbook implementation steps. +A custom droid may include `../agents/poteto-agent.md` and be used for playbook implementation steps. diff --git a/skills/poteto-mode/references/adapters/opencode.md b/skills/poteto-mode/references/adapters/opencode.md index f3b02c7..ceb4ce9 100644 --- a/skills/poteto-mode/references/adapters/opencode.md +++ b/skills/poteto-mode/references/adapters/opencode.md @@ -1,37 +1,37 @@ # Adapter: OpenCode -Use inside [OpenCode](https://opencode.ai/docs/agents/) when the `task` tool can spawn subagents. +Use inside OpenCode when the task tool can spawn subagents. ## Detect -- `task` tool for subagent invocation -- Built-in subagents: `general` (parallel multi-step / can edit), `explore` (fast read-only), `scout` (external docs / deps, read-only) -- Skills under `~/.config/opencode/skills/`, `~/.agents/skills/`, or `~/.claude/skills/` +- task tool for subagent invocation +- built-in read-only and write-capable subagents +- skills under `~/.config/opencode/skills/`, `~/.agents/skills/`, or another configured root ## Capability map | Capability | How | | --- | --- | -| `explore` | `task` → subagent `explore` (read-only). Use `scout` when the slice is upstream docs/deps rather than the local tree. | -| `implement` | `task` → subagent `general` (or a custom write-capable subagent). Disjoint file scopes across workers. | -| `review` | `task` → read-oriented subagent / custom reviewer with `edit: deny`. Distinct rubrics per reviewer. | -| `parallel` | Issue **multiple** `task` calls for independent slices in one turn when the runtime schedules them concurrently. If the host serializes `task`, still issue the batch as separate tasks and note sequential execution; do not invent a fake parallel API. | -| `ask_user` | Prefer OpenCode `question` tool when available; else plain chat. Facts you can observe → do not ask. | -| `verify` | `bash` / browser tools. Narrowest meaningful check. | -| `model_role` | Set per-subagent `model` in agent config or task override when confirmed available (`provider/model-id`). Otherwise inherit. | +| `explore` | Use a read-only explorer; use an external-docs scout for dependency research. | +| `implement` | Use a write-capable general agent with disjoint file scope. | +| `review` | Use a read-oriented reviewer with an explicit rubric and edit denial. | +| `parallel` | Issue multiple independent task calls in one turn when the runtime schedules them concurrently. | +| `ask_user` | Use the question tool when available, otherwise plain chat. | +| `verify` | Bash and browser tools on the matching surface. | +| `model_role` | Use confirmed per-agent model configuration or inherit. | ## Policy -- Lead (primary Build/Plan) owns synthesis, final patch judgment, and verification. -- Do not enable unbounded recursive `permission.task` on every subagent globally — prefer task permission on the primary only, or specific subagent patterns. +- The primary lead owns synthesis, final patch judgment, and verification. +- Do not enable unbounded recursive task permission globally. - Keep worker write scopes disjoint. -- Hidden custom subagents are fine for programmatic poteto-style workers. -- If `task` is denied or missing, fall back to `generic.md`. +- Hidden custom agents are acceptable for Poteto-style workers. +- Fall back to `generic.md` when task is unavailable or denied. ## Model override file -`~/.agents/pstack-models.md` and/or OpenCode agent model fields. `/setup-pstack` should write the portable override and optionally mirror role models into `opencode.json` agent entries when the user wants sticky per-agent models. +Prefer `~/.agents/ystack-models.md` and/or OpenCode-native agent model fields. `/setup-ystack` writes the portable override and may mirror roles into host config when the user requests it. Honor `~/.agents/pstack-models.md` as a legacy fallback. ## Poteto worker rubric -Create an optional OpenCode subagent (markdown under `~/.config/opencode/agents/`) whose prompt includes `../agents/poteto-agent.md`, then `task` that agent for playbook implementation steps. +An optional OpenCode agent may include `../agents/poteto-agent.md` and be selected for implementation steps. diff --git a/skills/poteto-mode/references/model-override.schema.json b/skills/poteto-mode/references/model-override.schema.json index 448155c..785eec1 100644 --- a/skills/poteto-mode/references/model-override.schema.json +++ b/skills/poteto-mode/references/model-override.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://github.com/Go7hic/pstack/skills/pstack/references/model-override.schema.json", - "title": "pstack model override", + "$id": "https://github.com/Go7hic/ystack/blob/main/skills/pstack/references/model-override.schema.json", + "title": "ystack model override", "type": "object", "additionalProperties": false, "required": ["schema_version", "roles"], diff --git a/skills/pstack/SKILL.md b/skills/pstack/SKILL.md index 2bfbc67..57b91a9 100644 --- a/skills/pstack/SKILL.md +++ b/skills/pstack/SKILL.md @@ -1,90 +1,20 @@ --- name: pstack -description: "Portable pstack engineering system for multiple coding agents. Use for pstack or poteto rigor, non-trivial features, bug fixes, investigations, architecture, parallel exploration, adversarial review, verification, or routing across how, why, architect, arena, swarm, and interrogate." +description: "Legacy compatibility alias for ystack. Use when an existing prompt, installation, or workflow still invokes pstack; new work should prefer ystack." license: MIT -compatibility: Requires an Agent Skills-compatible coding agent. Multi-agent optional. +compatibility: Requires the complete ystack Agent Skills pack. metadata: upstream: https://github.com/cursor/plugins/tree/main/pstack - format: agentskills + deprecated-in-favor-of: ystack --- -# pstack - -Portable entry point for the pstack engineering system. It preserves the upstream principles and playbooks while translating delegation, model selection, verification, and runtime control through host adapters. +# pstack compatibility alias ## Portability (required) -1. Read `references/capability-contract.md`, `references/host-lifecycle.md`, and `references/workflow-quality.md`. -2. Detect the active coding agent and read one matching file under `references/adapters/`. Use `generic.md` when no named adapter fits. -3. Express workflow steps through `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, and `model_role` rather than vendor tool names. -4. Prefer real parallel helpers when the host exposes them. Collapse to the lead agent only when spawning is missing, denied, or unsafe because write scopes overlap. -5. Resolve concrete models through `/setup-pstack` and the active adapter. Never copy model identifiers from another host. Optional overrides should match `references/model-override.schema.json`. -6. Keep synthesis, final diff judgment, and verification on the lead agent. - -## First moves - -1. Create a todo list. The first item reads the Principles index in `poteto-mode` or `references/principles-summary.md`, then opens every leaf principle that affects a real decision. -2. Match a playbook under `playbooks/` and copy its steps into the todo list before adding task-specific work. -3. Route to sibling skills as the playbook requires: `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `living-spec`, `tdd`, `unslop`, and the verification skills. -4. Use `verify` before declaring completion. A passing proxy is not proof when the reported problem appears on another surface. -5. State any degraded capability, such as unavailable helper spawning, model selection, transcript access, or runtime control. - -## Playbooks - -The entry pack includes: - -- investigation; -- bug fix; -- performance issue; -- hillclimb; -- runtime and trace forensics; -- feature and refactoring; -- prototype and visual parity; -- skill authoring and eval; -- Babysit and Shipping; -- autonomous run and Orchestrate; -- full and stacked autopilot; -- session pickup and safe pause; -- multi-phase planning; -- worktree cleanup; -- opening a pull request. - -## Sibling skills - -**Understanding and design:** `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `teach`. - -**Execution and adaptation:** `figure-it-out`, `reflect`, `automate-me`, `setup-pstack`, `show-me-your-work`, `tdd`, `typescript-best-practices`. - -**Documentation and continuity:** `living-spec` maintains current product truth, temporary change briefs, and durable ADRs without forcing a full specification framework. - -**Verification:** `create-verification-skill`, `maintain-verification-skill`. - -**Quality and prose:** `unslop`, `no-comments`, `technical-writing`, `bro`. - -**Mode:** `poteto-mode`, which owns the full router, principles index, autonomy boundaries, delegation contract, and playbook triggers. - -**Agent rubrics:** `references/agents/poteto-agent.md` and `references/agents/comment-sicko.md`. Adapters pass these as prompts when the host has no custom helper type. - -## Optional host tooling - -Some upstream workflows mention cleanup, browser-control, CLI-control, automation, and skill-authoring tools that are not part of pstack itself. Use equivalent capabilities exposed by the active host. When no equivalent exists, apply the documented fallback and report the missing verification or automation surface. - -The optional Benny automation sources live outside the installable skill tree. They remain host-oriented templates and are not loaded as portable Agent Skills. - -## Alias and mode lifetime - -When the user says `/poteto-mode` or requests Poteto style, invoke `poteto-mode` with this entry skill. Use `pstack` for adapter-first routing and `poteto-mode` for the full mode contract. - -Mode persistence depends on the host. When no persistent mode facility exists, treat the mode as active for the current conversation and invoke it again after a fresh session or context reset. - -## Model roles - -| Role | Use | -| --- | --- | -| `fast_explore` | broad read-only exploration and mechanical work | -| `feature_impl` | spec-driven features and refactoring | -| `bug_impl` | evidence-backed bug, performance, and reliability fixes | -| `judgment` | architecture, synthesis, and prose | -| `critic` | independent candidates and adversarial review | +1. Read `../ystack/SKILL.md` in full before taking any action. +2. Treat `/pstack` as `/ystack` and follow the ystack router exactly. +3. Keep this directory's `playbooks/` and `references/` as shared legacy runtime assets until a separately versioned migration removes them. +4. Prefer `/setup-ystack` and ystack-named model overrides; continue honoring legacy configuration through the adapters. -If no role override is available, inherit the parent session model. +Do not present pstack as the public name of this repository. It remains here for upstream attribution and backwards compatibility. diff --git a/skills/pstack/references/adapters/claude-code.md b/skills/pstack/references/adapters/claude-code.md index eb89975..df08936 100644 --- a/skills/pstack/references/adapters/claude-code.md +++ b/skills/pstack/references/adapters/claude-code.md @@ -1,6 +1,6 @@ # Adapter: Claude Code -Use inside [Claude Code](https://code.claude.com) when the `Agent` tool is available (older builds may still expose it as `Task` — treat them as the same capability). +Use inside [Claude Code](https://code.claude.com) when the `Agent` tool is available. Older builds may expose it as `Task`; treat both as the same capability. ## Detect @@ -12,27 +12,26 @@ Use inside [Claude Code](https://code.claude.com) when the `Agent` tool is avail | Capability | How | | --- | --- | -| `explore` | `Agent` / `Task` with `subagent_type: Explore` (or equivalent explore agent). Prefer thoroughness `medium` unless the slice is tiny (`quick`) or broad (`very thorough`). Read-only; do not edit. | -| `implement` | `Agent` / `Task` with `subagent_type: general-purpose` (or a custom worker). Pass disjoint file scopes. Optionally `isolation: "worktree"` when the runtime supports it and writes would collide. | -| `review` | Separate `Agent` calls with distinct rubrics/models. Prefer read-only tools / deny edits in the prompt. | -| `parallel` | Emit **multiple** `Agent`/`Task` calls in **one** assistant turn. Independent slices only. Use `run_in_background: true` when available and the parent continues non-overlapping work; collect with the runtime’s task-output mechanism if needed. | -| `ask_user` | Plain chat (or Claude’s question UI if present). Facts you can observe → do not ask. | -| `verify` | Bash / browser tools on the matching surface. Prefer the narrowest meaningful command. | -| `model_role` | Pass `model` on the Agent call when the override file names a confirmed slug. Otherwise omit and inherit. Explore often inherits/caps — do not fight the runtime. | +| `explore` | `Agent` / `Task` with `subagent_type: Explore` or an equivalent read-only agent. | +| `implement` | `Agent` / `Task` with `subagent_type: general-purpose` or a custom worker. Pass disjoint file scopes. | +| `review` | Separate calls with distinct rubrics/models. Deny edits in the prompt. | +| `parallel` | Emit multiple `Agent` / `Task` calls in one assistant turn for independent slices. Use background execution only when supported. | +| `ask_user` | Plain chat or the host's question UI. Do not ask for observable facts. | +| `verify` | Bash and browser tools on the matching surface. | +| `model_role` | Pass `model` only when an override names a confirmed slug; otherwise inherit. | ## Policy -- Lead agent owns synthesis, final patch judgment, and verification. -- Do not trust subagent “done” summaries; read the diff / returned paths. -- Keep worker write scopes disjoint. Tell workers not to revert others’ edits. -- Respect spawn / concurrent subagent limits; if spawn fails, finish remaining work locally or sequentially. -- Nested subagents: prefer shallow fan-out from the lead. Do not build deep trees unless the playbook requires it. -- If `Agent`/`Task` is missing, fall back to `generic.md`. +- The lead owns synthesis, final patch judgment, and verification. +- Do not trust helper completion summaries without reading the diff or artifacts. +- Keep worker write scopes disjoint. +- Prefer shallow fan-out from the lead. +- Fall back to `generic.md` when spawning is unavailable. ## Model override file -Prefer `~/.agents/pstack-models.md` or a Claude user rule. `/setup-pstack` should write beside the active agent. +Prefer `~/.agents/ystack-models.md` or a Claude user rule written by `/setup-ystack`. If absent, honor `~/.agents/pstack-models.md` as a legacy fallback. `/setup-pstack` is an alias for the new setup skill. ## Poteto worker rubric -When a playbook wants a full-style worker, spawn `general-purpose` (or a custom droid/agent you configured) and prepend instructions from `../agents/poteto-agent.md`. +When a playbook wants a full-style worker, spawn `general-purpose` or a configured custom agent and prepend `../agents/poteto-agent.md`. diff --git a/skills/pstack/references/adapters/codex-models.md b/skills/pstack/references/adapters/codex-models.md index cf924e1..e41804b 100644 --- a/skills/pstack/references/adapters/codex-models.md +++ b/skills/pstack/references/adapters/codex-models.md @@ -1,26 +1,27 @@ # Codex model notes -Companion to `adapters/codex.md`. Validate every slug against **current** Codex tool metadata before use; this file is illustrative. +Companion to `codex.md`. Validate every model identifier against current Codex tool metadata before use; examples here are structural, not a live catalog. -## Override file +## Override files -Prefer: +Preferred: ```text -~/.codex/rules/pstack-models.md +~/.codex/rules/ystack-models.md ``` -Legacy name from the old pack (still honored if present): +Legacy fallbacks, in order: ```text +~/.codex/rules/pstack-models.md ~/.codex/rules/codex-pstack-models.md ``` -`/setup-pstack` writes the new path using the portable JSON fence from `../model-override.schema.json`: +`/setup-ystack` reads a legacy file when needed and writes the preferred ystack path using the JSON fence from `../model-override.schema.json`: ````markdown --- -description: pstack model overrides +description: ystack model overrides alwaysApply: true --- @@ -42,19 +43,15 @@ alwaysApply: true ``` ```` -Use `inherit-parent` or `auto` to omit `model` on that role. Optional effort can be encoded in the slug string only when Codex requires a combined token; otherwise keep effort in adapter-specific notes beside the override. +Use `inherit-parent` or `auto` to omit an explicit child model. Keep reasoning effort in adapter-supported fields unless the runtime explicitly encodes it in the model identifier. -## Role → intent +## Role intent | Role | Intent | | --- | --- | -| `feature_impl` | everyday implementation / refactoring | +| `feature_impl` | everyday implementation and refactoring | | `bug_impl` | high-stakes reasoning after evidence | -| `judgment` | synthesis, architecture, unslop-sensitive replies | +| `judgment` | synthesis, architecture, and prose | | `fast_explore` | fast read-only or mechanical fan-out | -| `critic` | adversarial / panel diversity | +| `critic` | adversarial and panel diversity | | panel arrays | one helper per entry; prefer diverse families | - -## Effort - -When the API separates reasoning effort from the model slug, set it from host-supported fields. Do not invent effort values the tool rejects. diff --git a/skills/pstack/references/adapters/codex.md b/skills/pstack/references/adapters/codex.md index f410113..0fb8580 100644 --- a/skills/pstack/references/adapters/codex.md +++ b/skills/pstack/references/adapters/codex.md @@ -1,60 +1,61 @@ # Adapter: Codex -Use inside [OpenAI Codex](https://chatgpt.com/codex) (CLI / IDE) when multi-agent tools are available. This is the portable replacement for the old `codex-pstack` pack — install this repo’s skills under `~/.codex/skills/` and delete `codex-pstack`. +Use inside OpenAI Codex CLI or IDE when multi-agent tools are available. This pack replaces the obsolete standalone `codex-pstack` pack; install ystack under the normal Codex skills tree and remove the old standalone pack. ## Detect -- Multi-agent tools such as `multi_agent_v1.spawn_agent` (names may evolve; follow current tool metadata) +- Current Codex multi-agent spawn tools - Skills under `~/.codex/skills/` or project Codex skill paths -- Optional model override at `~/.codex/rules/pstack-models.md` +- Preferred model override at `~/.codex/rules/ystack-models.md` +- Legacy fallback at `~/.codex/rules/pstack-models.md` or `codex-pstack-models.md` ## Capability map | Capability | How | | --- | --- | -| `explore` | `spawn_agent` with `agent_type: explorer`. Explicitly prohibit edits. Prefer local `rg`/reads first for tiny questions; fan out 2–4 explorers for broad subsystems. | -| `implement` | `spawn_agent` with `agent_type: worker` (or `default` when worker is unavailable). Bounded, disjoint file scopes. Prepend the poteto worker rubric from `../agents/poteto-agent.md` when the playbook wants full-style implementation. | -| `review` | Separate agents (`explorer` or `default`) with distinct rubrics. Prohibit edits in the prompt. Diverse `model` / `reasoning_effort` when the panel needs independent judgment. | -| `parallel` | Spawn **multiple** agents in one turn for independent slices. Continue non-overlapping lead work while they run. Do not wait serially unless scopes collide. | -| `ask_user` | Plain chat. Only product/preference forks that no experiment can settle. | -| `verify` | Local shell. Narrowest meaningful check first, then broaden. | -| `model_role` | Set `model` (+ `reasoning_effort` when supported) only from confirmed Codex slugs / the override file. Never copy Cursor model slugs. | +| `explore` | Spawn an explorer agent and explicitly prohibit edits. Use local reads first for tiny questions. | +| `implement` | Spawn a worker or default agent with bounded, disjoint file scope. Include the Poteto worker rubric when requested. | +| `review` | Separate read-only agents with distinct rubrics and, when useful, diverse models or reasoning effort. | +| `parallel` | Spawn multiple independent agents in one turn and continue non-overlapping lead work. | +| `ask_user` | Plain chat for product or preference decisions only. | +| `verify` | Local shell and available runtime tools, narrowest meaningful check first. | +| `model_role` | Set model and optional reasoning effort only from confirmed Codex identifiers or the override file. | -## Cursor → Codex translation +## Cursor to Codex translation -| Cursor / portable concept | Codex | +| Portable concept | Codex | | --- | --- | -| `Task` / `Agent` / `task` | `multi_agent_v1.spawn_agent` (or current equivalent) | -| explore helper | `agent_type: explorer` | -| implement helper | `agent_type: worker` or `default` | -| `run_in_background: true` | spawn and continue local non-overlapping work | -| `readonly: true` | `explorer` + explicit no-edit rule | -| poteto-agent type | `worker`/`default` + `../agents/poteto-agent.md` prompt | -| Comment Sicko | `review` helper + `../agents/comment-sicko.md` rubric | -| Cursor model slug | Codex `model` + optional `reasoning_effort` from override file | +| helper spawn | current Codex multi-agent spawn tool | +| explore helper | explorer agent | +| implement helper | worker or default agent | +| background work | spawn and continue non-overlapping lead work | +| read-only intent | explorer plus explicit no-edit rule | +| Poteto worker | worker/default plus `../agents/poteto-agent.md` | +| Comment Sicko | review helper plus `../agents/comment-sicko.md` | +| model role | confirmed Codex model plus optional reasoning effort | ## Policy -- Prefer real parallel fan-out for how-complex, arena, swarm, interrogate, and playbook delegates. -- Critical-path synthesis stays on the lead agent. You own the final answer, patch, and verification. -- Keep worker write scopes disjoint. Tell workers not to revert or overwrite others’ edits. -- Close / stop completed agents when you no longer need them. -- If multi-agent tools are missing or spawn is denied, fall back to `generic.md` and say so. +- Prefer real parallel fan-out for broad How, Arena, Swarm, Interrogate, and independent playbook delegates. +- Critical-path synthesis stays on the lead. +- Keep worker write scopes disjoint. +- Close completed agents when they are no longer needed. +- Fall back to `generic.md` when multi-agent tools are unavailable or denied. -## Model roles (defaults) +## Model roles -Resolve via `/setup-pstack` → `~/.codex/rules/pstack-models.md`. See `codex-models.md` for override shape and legacy path notes. +Resolve through `/setup-ystack` and `~/.codex/rules/ystack-models.md`. If absent, read legacy pstack paths. See `codex-models.md` for the override shape. | Role | Typical use | | --- | --- | -| `fast_explore` | how explorers, swarm workers, mechanical edits | -| `feature_impl` | feature / refactoring workers | -| `bug_impl` | bug-fix / perf / hillclimb | -| `judgment` | synthesis, prose, hardest design calls | -| `critic` | arena / architect / interrogate / how-critics panels | +| `fast_explore` | broad reading and mechanical work | +| `feature_impl` | feature and refactoring workers | +| `bug_impl` | bug, performance, and hillclimb work | +| `judgment` | synthesis, prose, and hard design calls | +| `critic` | Arena, Architect, Interrogate, and How critique panels | -Omit `model` when the override says `inherit-parent` / `auto`, or when a single parent model is enough. +Omit an explicit child model when the override says `inherit-parent` or `auto`. ## Poteto worker rubric -For playbook code delegates, spawn `worker`/`default` and include the instructions from `../agents/poteto-agent.md` in the agent prompt so style and principles load even without a Cursor `poteto-agent` type. +For code delegates, include `../agents/poteto-agent.md` in the worker prompt so the full engineering discipline loads without a vendor-specific helper type. diff --git a/skills/pstack/references/adapters/droid.md b/skills/pstack/references/adapters/droid.md index e47e620..a4a2dfb 100644 --- a/skills/pstack/references/adapters/droid.md +++ b/skills/pstack/references/adapters/droid.md @@ -1,10 +1,10 @@ # Adapter: Droid (Factory) -Use inside [Factory Droid](https://docs.factory.ai/harness/subagents) when the `Task` tool can spawn subagents / custom droids. +Use inside Factory Droid when the Task tool can spawn subagents or custom droids. ## Detect -- `Task` tool with `subagent_type`, `run_in_background`, `resume`, `complexity` +- Task tool with helper, background, resume, and complexity controls - Skills under `~/.factory/skills/` or `.factory/skills/` - Optional custom droids under `~/.factory/droids/` or `.factory/droids/` @@ -12,27 +12,27 @@ Use inside [Factory Droid](https://docs.factory.ai/harness/subagents) when the ` | Capability | How | | --- | --- | -| `explore` | `Task` with a read-only custom droid if you have one, otherwise the default research/read-oriented subagent. Explicitly forbid edits in the prompt. Prefer `complexity: light` or `medium` for exploration. | -| `implement` | `Task` with a coding subagent / general droid. Bounded file scope. Use `complexity: medium` or `heavy` for hard fixes. Disjoint write scopes across workers. | -| `review` | Separate `Task` reviewers with distinct rubrics. Prefer read-only tool policy on review droids. | -| `parallel` | Multiple `Task` calls in one turn, and/or `run_in_background: true` then collect with `TaskOutput`. Independent slices only. | -| `ask_user` | Plain chat. Only product/preference forks. | -| `verify` | Execute / browser tools on the matching surface. Narrowest meaningful check. | -| `model_role` | Prefer `complexity` routing when it maps to your settings; otherwise set an explicit model if the Task API allows it and the slug is confirmed. | +| `explore` | Use a read-oriented helper and explicitly forbid edits. | +| `implement` | Use a coding helper with bounded file scope and appropriate complexity. | +| `review` | Separate reviewers with distinct rubrics and read-only policy. | +| `parallel` | Issue multiple independent Tasks and collect through the host's task-output mechanism. | +| `ask_user` | Plain chat for product or preference forks only. | +| `verify` | Execute or browser tools on the matching surface. | +| `model_role` | Prefer supported complexity routing or a confirmed explicit model. | ## Policy -- Lead droid owns synthesis, final patch judgment, and verification. -- Background tasks: track `task_id`, wait via `TaskOutput`, stop via `TaskStop` when abandoning work. -- `resume` only when continuing the same helper’s context beats a fresh spawn. -- Keep write scopes disjoint across parallel Tasks. -- Large multi-feature campaigns may use Factory Missions when available; still apply pstack playbook gates (verify, prove-it-works). -- If `Task` is missing, fall back to `generic.md`. +- The lead droid owns synthesis, final patch judgment, and verification. +- Track background task identifiers and stop abandoned work. +- Resume only when preserving the same helper context is valuable. +- Keep parallel write scopes disjoint. +- Missions may coordinate broad campaigns, but ystack verification gates still apply. +- Fall back to `generic.md` when Task is unavailable. ## Model override file -`~/.agents/pstack-models.md` or a Factory-side rule written by `/setup-pstack`. +Prefer `~/.agents/ystack-models.md` or a Factory-side rule written by `/setup-ystack`. Honor `~/.agents/pstack-models.md` as a legacy fallback. ## Poteto worker rubric -Optional: add a custom droid whose system prompt includes `../agents/poteto-agent.md`, then target it as `subagent_type` for playbook implementation steps. +A custom droid may include `../agents/poteto-agent.md` and be used for playbook implementation steps. diff --git a/skills/pstack/references/adapters/opencode.md b/skills/pstack/references/adapters/opencode.md index f3b02c7..ceb4ce9 100644 --- a/skills/pstack/references/adapters/opencode.md +++ b/skills/pstack/references/adapters/opencode.md @@ -1,37 +1,37 @@ # Adapter: OpenCode -Use inside [OpenCode](https://opencode.ai/docs/agents/) when the `task` tool can spawn subagents. +Use inside OpenCode when the task tool can spawn subagents. ## Detect -- `task` tool for subagent invocation -- Built-in subagents: `general` (parallel multi-step / can edit), `explore` (fast read-only), `scout` (external docs / deps, read-only) -- Skills under `~/.config/opencode/skills/`, `~/.agents/skills/`, or `~/.claude/skills/` +- task tool for subagent invocation +- built-in read-only and write-capable subagents +- skills under `~/.config/opencode/skills/`, `~/.agents/skills/`, or another configured root ## Capability map | Capability | How | | --- | --- | -| `explore` | `task` → subagent `explore` (read-only). Use `scout` when the slice is upstream docs/deps rather than the local tree. | -| `implement` | `task` → subagent `general` (or a custom write-capable subagent). Disjoint file scopes across workers. | -| `review` | `task` → read-oriented subagent / custom reviewer with `edit: deny`. Distinct rubrics per reviewer. | -| `parallel` | Issue **multiple** `task` calls for independent slices in one turn when the runtime schedules them concurrently. If the host serializes `task`, still issue the batch as separate tasks and note sequential execution; do not invent a fake parallel API. | -| `ask_user` | Prefer OpenCode `question` tool when available; else plain chat. Facts you can observe → do not ask. | -| `verify` | `bash` / browser tools. Narrowest meaningful check. | -| `model_role` | Set per-subagent `model` in agent config or task override when confirmed available (`provider/model-id`). Otherwise inherit. | +| `explore` | Use a read-only explorer; use an external-docs scout for dependency research. | +| `implement` | Use a write-capable general agent with disjoint file scope. | +| `review` | Use a read-oriented reviewer with an explicit rubric and edit denial. | +| `parallel` | Issue multiple independent task calls in one turn when the runtime schedules them concurrently. | +| `ask_user` | Use the question tool when available, otherwise plain chat. | +| `verify` | Bash and browser tools on the matching surface. | +| `model_role` | Use confirmed per-agent model configuration or inherit. | ## Policy -- Lead (primary Build/Plan) owns synthesis, final patch judgment, and verification. -- Do not enable unbounded recursive `permission.task` on every subagent globally — prefer task permission on the primary only, or specific subagent patterns. +- The primary lead owns synthesis, final patch judgment, and verification. +- Do not enable unbounded recursive task permission globally. - Keep worker write scopes disjoint. -- Hidden custom subagents are fine for programmatic poteto-style workers. -- If `task` is denied or missing, fall back to `generic.md`. +- Hidden custom agents are acceptable for Poteto-style workers. +- Fall back to `generic.md` when task is unavailable or denied. ## Model override file -`~/.agents/pstack-models.md` and/or OpenCode agent model fields. `/setup-pstack` should write the portable override and optionally mirror role models into `opencode.json` agent entries when the user wants sticky per-agent models. +Prefer `~/.agents/ystack-models.md` and/or OpenCode-native agent model fields. `/setup-ystack` writes the portable override and may mirror roles into host config when the user requests it. Honor `~/.agents/pstack-models.md` as a legacy fallback. ## Poteto worker rubric -Create an optional OpenCode subagent (markdown under `~/.config/opencode/agents/`) whose prompt includes `../agents/poteto-agent.md`, then `task` that agent for playbook implementation steps. +An optional OpenCode agent may include `../agents/poteto-agent.md` and be selected for implementation steps. diff --git a/skills/pstack/references/model-override.schema.json b/skills/pstack/references/model-override.schema.json index 448155c..785eec1 100644 --- a/skills/pstack/references/model-override.schema.json +++ b/skills/pstack/references/model-override.schema.json @@ -1,7 +1,7 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://github.com/Go7hic/pstack/skills/pstack/references/model-override.schema.json", - "title": "pstack model override", + "$id": "https://github.com/Go7hic/ystack/blob/main/skills/pstack/references/model-override.schema.json", + "title": "ystack model override", "type": "object", "additionalProperties": false, "required": ["schema_version", "roles"], diff --git a/skills/setup-pstack/SKILL.md b/skills/setup-pstack/SKILL.md index 76ba4ca..358c1a0 100644 --- a/skills/setup-pstack/SKILL.md +++ b/skills/setup-pstack/SKILL.md @@ -1,92 +1,19 @@ --- name: setup-pstack -description: "Configure which models pstack uses per role. Detects available models and writes an always-applied override file. Use for /setup-pstack, configure pstack models, or changing pstack model choices on any coding agent." +description: "Legacy compatibility alias for setup-ystack. Use when an existing prompt still invokes /setup-pstack; new work should prefer /setup-ystack." license: MIT -compatibility: Works with Agent Skills-compatible coding agents. Multi-agent optional; see pstack adapters. +compatibility: Requires the complete ystack Agent Skills pack. +metadata: + deprecated-in-favor-of: setup-ystack --- -# Setup pstack +# setup-pstack compatibility alias ## Portability (required) -1. Read the sibling `pstack` skill `references/capability-contract.md`, `references/model-override.schema.json`, and the active adapter. -2. Write the override beside the active agent — do not assume one vendor path: - - Cursor: `~/.cursor/rules/pstack-models.mdc` (or project `.cursor/rules/`) - - Codex: `~/.codex/rules/pstack-models.md` - - Claude Code / generic: project or user rules file named in the adapter, or `~/.agents/pstack-models.md` -3. Never invent model slugs. Only write slugs confirmed available in this session. -4. After writing, validate with `python3 scripts/validate_model_override.py ` when that script is available in the checkout; otherwise self-check against the schema fields below. +1. Read `../setup-ystack/SKILL.md` in full. +2. Treat `/setup-pstack` as `/setup-ystack`. +3. When a legacy `pstack-models.*` file exists, use it as migration input and write the preferred `ystack-models.*` path. +4. Do not delete legacy configuration unless the user explicitly asks. -## Goal - -Write a **pstack model override file** that maps `model_role` values to host models. Skills read the JSON fence and fall back to parent-session defaults when a role is absent or set to `inherit-parent` / `auto`. - -## Steps - -### 1. Detect available models - -Enumerate model slugs you can pass to adapter helpers in this session. If you cannot detect any, ask the user to paste the slugs they have. Never write an unconfirmed real slug. Aliases `inherit-parent` and `auto` are always valid. - -### 2. Load current state - -If a pstack model override file already exists for this runtime, read its JSON fence. Otherwise start from the role table below. - -### 3. Map and confirm - -Show every role with its current model. Mark unavailable slugs. Ask via `ask_user` whether to accept or change. Panel arrays use one helper per entry. Prefer diverse families for panels when available. - -### 4. Validate - -Every real slug must be in the detected set. `inherit-parent` / `auto` always pass. Reject an empty `roles` object. - -### 5. Write the override - -Overwrite the whole file so re-runs stay idempotent. Use this exact shape (replace placeholders with confirmed slugs): - -````markdown ---- -description: pstack model overrides -alwaysApply: true ---- - -```json -{ - "schema_version": 1, - "roles": { - "fast_explore": "", - "feature_impl": "", - "bug_impl": "", - "judgment": "", - "critic": "" - }, - "arena_runners": ["", "", ""], - "arena_cross_judge_pool": ["", ""], - "interrogate_reviewers": ["", "", "", ""], - "architect_runners": ["", "", ""] -} -``` -```` - -Notes: - -- `inherit-parent` or `auto` means omit an explicit child model for that role. -- Panel arrays may be shortened when the host concurrency budget is lower. -- Do not write the old label-line format (`feature, refactoring: ...`). - -### 6. Confirm - -Tell the user where the file was written and that new sessions pick it up. Re-running this skill updates it. - -### 7. Offer a verification skill (optional) - -If the project has no way to drive the real app for proof, offer once to run `create-verification-skill`. On no, move on. - -## Model roles - -| Role | Use | -| --- | --- | -| `fast_explore` | Broad read-only fan-out, mechanical edits | -| `feature_impl` | Spec-driven implementation / refactoring | -| `bug_impl` | High-stakes fixes after evidence | -| `judgment` | Architecture, synthesis, prose | -| `critic` | Adversarial / panel review | +Report both the new path and any legacy path that was read. diff --git a/skills/setup-ystack/SKILL.md b/skills/setup-ystack/SKILL.md new file mode 100644 index 0000000..5e8ccb0 --- /dev/null +++ b/skills/setup-ystack/SKILL.md @@ -0,0 +1,91 @@ +--- +name: setup-ystack +description: "Configure which models ystack uses per role. Detects available models, migrates legacy pstack configuration when present, and writes the preferred ystack override file. Use for /setup-ystack, configure ystack models, or change ystack model choices on any coding agent." +license: MIT +compatibility: Works with Agent Skills-compatible coding agents. Multi-agent optional; see ystack adapters. +--- + +# Setup ystack + +## Portability (required) + +1. Read `../pstack/references/capability-contract.md`, `../pstack/references/model-override.schema.json`, and the active adapter. +2. Prefer the ystack-named override beside the active agent: + - Cursor: `~/.cursor/rules/ystack-models.mdc` or a project `.cursor/rules/` file; + - Codex: `~/.codex/rules/ystack-models.md`; + - Claude Code / generic: a host-supported user rule or `~/.agents/ystack-models.md`. +3. Read legacy files as fallback when the preferred file does not exist: + - `pstack-models.mdc` / `pstack-models.md`; + - Codex may also honor `codex-pstack-models.md`. +4. Never invent model slugs. Write only slugs confirmed available in this session. +5. Validate with `python3 scripts/validate_model_override.py ` when the script is available; otherwise self-check against the schema. + +## Goal + +Write a ystack model override that maps `model_role` values and panel arrays to host models. Missing roles and values set to `inherit-parent` or `auto` inherit the parent session behavior. + +## Steps + +### 1. Detect available models + +Enumerate model identifiers that the active adapter can pass to helper calls. If the host cannot expose a catalog, ask the user to supply the identifiers they actually have. `inherit-parent` and `auto` are always valid aliases. + +### 2. Load current state + +Read the preferred ystack file first. If absent, read the adapter's legacy pstack file and label it as migration input. Do not silently delete the legacy file. + +### 3. Map and confirm + +Show every role with its current model. Mark unavailable identifiers. Ask through `ask_user` whether to accept or change the mapping. Panel arrays use one helper per entry; prefer diverse model families when available. + +### 4. Validate + +Every real model identifier must be confirmed by the host. Reject an empty `roles` object, unknown keys, empty strings, and an unsupported schema version. + +### 5. Write the preferred override + +Overwrite the ystack-named file so reruns remain idempotent: + +````markdown +--- +description: ystack model overrides +alwaysApply: true +--- + +```json +{ + "schema_version": 1, + "roles": { + "fast_explore": "", + "feature_impl": "", + "bug_impl": "", + "judgment": "", + "critic": "" + }, + "arena_runners": ["", "", ""], + "arena_cross_judge_pool": ["", ""], + "interrogate_reviewers": ["", "", "", ""], + "architect_runners": ["", "", ""] +} +``` +```` + +Panel arrays may be shortened when the host concurrency budget is lower. Do not write the old label-line format. + +### 6. Confirm migration state + +Report the preferred path written, any legacy path read, and whether the old file remains. New sessions should prefer the ystack file. + +### 7. Offer a verification skill once + +When the project has no repeatable way to drive the real app, offer once to run `create-verification-skill`. Continue normally if declined. + +## Model roles + +| Role | Use | +| --- | --- | +| `fast_explore` | broad read-only fan-out and mechanical work | +| `feature_impl` | spec-driven implementation and refactoring | +| `bug_impl` | high-stakes fixes after evidence | +| `judgment` | architecture, synthesis, and prose | +| `critic` | adversarial and panel review | diff --git a/skills/ystack/SKILL.md b/skills/ystack/SKILL.md new file mode 100644 index 0000000..5bb71a1 --- /dev/null +++ b/skills/ystack/SKILL.md @@ -0,0 +1,79 @@ +--- +name: ystack +description: "Portable multi-agent engineering system for non-trivial features, bug fixes, investigations, architecture, parallel exploration, adversarial review, verification, long-running work, and product-documentation convergence. Use for ystack, rigorous engineering, or routing across how, why, architect, arena, swarm, interrogate, and living-spec." +license: MIT +compatibility: Requires the complete ystack Agent Skills pack. Multi-agent optional. +metadata: + upstream: https://github.com/cursor/plugins/tree/main/pstack + legacy-alias: pstack + format: agentskills +--- + +# ystack + +Primary public entry for the ystack engineering system. ystack evolved from portable pstack while keeping upstream attribution and legacy compatibility. + +The shared runtime assets currently remain under `../pstack/` so existing installs and upstream synchronization stay stable. Do not treat that internal compatibility path as the public product name. + +## Portability (required) + +1. Read `../pstack/references/capability-contract.md`, `../pstack/references/host-lifecycle.md`, and `../pstack/references/workflow-quality.md`. +2. Detect the active coding agent and read one matching file under `../pstack/references/adapters/`. Use `generic.md` when no named adapter fits. +3. Express workflow steps through `explore`, `implement`, `review`, `parallel`, `ask_user`, `verify`, and `model_role`, not vendor tool names. +4. Prefer real parallel helpers when the host exposes them. Collapse to the lead agent only when spawning is missing, denied, or unsafe because write scopes overlap. +5. Resolve concrete models through `/setup-ystack` and the active adapter. Never copy model identifiers from another host. Optional overrides must match `../pstack/references/model-override.schema.json`. +6. Keep synthesis, final diff judgment, and verification on the lead agent. + +## First moves + +1. Create a todo list. The first item reads the Principles index in `poteto-mode` or `../pstack/references/principles-summary.md`, then opens every leaf principle that changes a real decision. +2. Match a playbook under `../pstack/playbooks/` and copy its steps into the todo list before adding task-specific work. +3. Route to sibling skills as the playbook requires: `how`, `why`, `architect`, `arena`, `swarm`, `interrogate`, `living-spec`, `tdd`, `unslop`, and verification skills. +4. Use `verify` before declaring completion. A passing proxy is not proof when the reported problem appears on another surface. +5. State degraded capabilities such as unavailable helper spawning, model selection, transcript access, or runtime control. + +## Playbooks + +The pack includes investigation, bug fix, performance, hillclimb, runtime and trace forensics, feature, refactoring, prototype, visual parity, skill authoring, eval, Babysit, Shipping, autonomous run, Orchestrate, full and stacked autopilot, session pickup, safe pause, multi-phase planning, worktree cleanup, and opening a pull request. + +## Sibling skills + +**Understanding and design:** `how`, `why`, `recall`, `blast-radius`, `architect`, `arena`, `swarm`, `interrogate`, `teach`. + +**Execution and adaptation:** `figure-it-out`, `reflect`, `automate-me`, `setup-ystack`, `show-me-your-work`, `tdd`, `typescript-best-practices`. + +**Documentation and continuity:** `living-spec` maintains current product truth, temporary change briefs, and durable ADRs without forcing a full specification framework. + +**Verification:** `create-verification-skill`, `maintain-verification-skill`. + +**Quality and prose:** `unslop`, `no-comments`, `technical-writing`, `bro`. + +**Mode:** `poteto-mode` owns the full upstream-style router, Principles index, autonomy boundaries, delegation contract, and playbook triggers. + +**Agent rubrics:** `../pstack/references/agents/poteto-agent.md` and `../pstack/references/agents/comment-sicko.md`. + +## Naming and compatibility + +- `/ystack` is the primary public entry. +- `/setup-ystack` is the preferred model setup command. +- `/pstack` and `/setup-pstack` remain compatibility aliases. +- `ystack-models.*` is preferred; adapters continue reading legacy `pstack-models.*` files. +- `pstack` remains valid when naming the upstream project, compatibility paths, or legacy commands. + +## Alias and mode lifetime + +When the user says `/poteto-mode` or requests Poteto style, invoke `poteto-mode` with this entry skill. Use `ystack` for adapter-first routing and `poteto-mode` for the full mode contract. + +Mode persistence depends on the host. When no persistent mode facility exists, treat the mode as active for the current conversation and invoke it again after a fresh session or context reset. + +## Model roles + +| Role | Use | +| --- | --- | +| `fast_explore` | broad read-only exploration and mechanical work | +| `feature_impl` | spec-driven features and refactoring | +| `bug_impl` | evidence-backed bug, performance, and reliability fixes | +| `judgment` | architecture, synthesis, and prose | +| `critic` | independent candidates and adversarial review | + +If no role override is available, inherit the parent session model. From 051f6f7a7c0141c77947af47bb1299f99d1e4556 Mon Sep 17 00:00:00 2001 From: YiChu Date: Sun, 9 Aug 2026 22:20:34 +0800 Subject: [PATCH 2/2] Use ystack branding in living-spec --- skills/living-spec/SKILL.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/skills/living-spec/SKILL.md b/skills/living-spec/SKILL.md index d903cfb..afcb812 100644 --- a/skills/living-spec/SKILL.md +++ b/skills/living-spec/SKILL.md @@ -1,13 +1,13 @@ --- name: living-spec -description: "Maintain a lightweight, current product-truth layer for pstack projects. Use for /living-spec inspect, draft, or converge; when a feature changes durable user-visible or business behavior; when work spans sessions or pull requests; or when current product docs, change briefs, or ADRs must stay aligned with verified implementation." +description: "Maintain a lightweight, current product-truth layer for ystack projects. Use for /living-spec inspect, draft, or converge; when a feature changes durable user-visible or business behavior; when work spans sessions or pull requests; or when current product docs, change briefs, or ADRs must stay aligned with verified implementation." license: MIT -compatibility: Works with Agent Skills-compatible coding agents. Multi-agent optional; see pstack adapters. +compatibility: Works with Agent Skills-compatible coding agents. Multi-agent optional; see ystack adapters. --- # Living spec -Keep the repository's current product behavior understandable without requiring a full specification framework for every task. +Living spec is ystack's lightweight documentation layer. Keep the repository's current product behavior understandable without requiring a full specification framework for every task. This skill is intentionally small. It distinguishes: @@ -20,7 +20,7 @@ Do not combine those into one ever-growing document. ## Portability (required) -1. Read the [pstack capability contract](../pstack/references/capability-contract.md), [workflow-quality defaults](../pstack/references/workflow-quality.md), and the active host adapter before delegation. +1. Read the [ystack capability contract](../pstack/references/capability-contract.md), [workflow-quality defaults](../pstack/references/workflow-quality.md), and the active host adapter before delegation. The `pstack` path is the temporary compatibility runtime namespace, not the public project name. 2. Use `explore` to discover existing documentation and behavior, `implement` for bounded documentation edits, `review` for independent convergence checks, `ask_user` only for product intent that evidence cannot settle, and `verify` for observable behavior. 3. Keep paths repository-relative. Do not depend on one vendor's session, transcript, or rules directory. 4. Small documentation decisions stay on the lead agent. Use helpers only when independent investigation or review will reduce a real blind spot.