Skip to content

Finish ystack public rebrand with pstack compatibility #5

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Go7hic merged 2 commits into from
Aug 9, 2026
Merged

Finish ystack public rebrand with pstack compatibility #5

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
bef78ed
Finish ystack public rebrand with compatibility aliases
Go7hic Aug 9, 2026
051f6f7
Use ystack branding in living-spec
Go7hic Aug 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 3 additions & 2 deletions .github/workflows/portable-audit.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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}")
Expand Down
63 changes: 27 additions & 36 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,78 +2,69 @@

## 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/<name>/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/<name>/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
python3 scripts/validate_model_override.py scripts/fixtures/model-override/valid.md
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.
46 changes: 28 additions & 18 deletions COVERAGE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
98 changes: 63 additions & 35 deletions INSTALL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 |
| --- | --- |
Expand All @@ -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/<pack-id> -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.
2 changes: 1 addition & 1 deletion LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down
8 changes: 5 additions & 3 deletions NOTICE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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`.
Loading
Loading