AGENTS.md · git:20261117.27b21bf · 2026-11-17 · sha256 94956b00c9c1783e
AGENTS.md git:20261117.27b21bfA
Immutable. This exact content never changes and is served at /api/v1/blob/94956b00c9c1783e.
# Ryugi — Project Guidelines Ryugi is a fork of [Superpowers](https://github.com/obra/superpowers), reshaped around one workflow: brainstorm with mockups on the Artboard, approve a spec, build it inline under TDD. Read `README.md` for the workflow before changing anything. `UPSTREAM.md` records the upstream baseline (superpowers v7.0.0) and how to port upstream changes. ## Skills Are Code Skill files shape agent behavior; treat edits to them like code changes. - Use the repo-local `writing-skills` skill (`.claude/skills/writing-skills/`) to develop and test changes. - Run a baseline without the change and a run with it, and keep the before/after results with the change. - Do not rewrite carefully-tuned content (Red Flags tables, rationalization lists) without evidence the change is an improvement. - "Your human partner" is deliberate wording, not interchangeable with "the user". ## Zero Dependencies The plugin ships without runtime dependencies. The artifacts app (artboard, document and HTML artifacts) is developed outside this repository and published to npm as `ryugi-artifacts`: the `ryugi` CLI (alias `ryugi-artifacts`; `dist/cli.cjs`: `start`, `stop`, `publish`), the server (`dist/server.cjs`, one file with its dependencies bundled, including Loro and haklex) and the viewer it serves (`dist/viewer/`). Neither is committed, and the package declares no runtime dependencies. - **Users**: the skill runs every command through `skills/artifacts/app/ryugi.cjs` (`ryugi-artifacts.cjs` is an alias), a small launcher that runs the newest `ryugi-artifacts` release. It asks npm for the latest version at most once a day, installs each version once into `~/.cache/ryugi/artifacts/<version>/`, and offline runs the newest installed CLI that provides `ryugi.cli/v1`. Before executing a command it checks the CLI's version response; an old output protocol is rejected with a shared bootstrap error. A running server from another release is replaced on the same port and key. The server may have npm dependencies. - **Development**: a local build of `ryugi-artifacts` can write gitignored copies to `skills/artifacts/app/cli.cjs`, `server.cjs` and `viewer/`. The launcher prefers a local `cli.cjs` over the npm release; delete those copies to run the npm release again. ## Releasing Users install from `main`. The plugin and `ryugi-artifacts` share one version and release together from the `Release` workflow here. 1. In `ryugi-cloud`, run `pnpm release <version|patch|minor|major>`. It commits the `packages/artifacts` version, pushes `main` with the tag `artifacts-v<version>` and starts the `Release` workflow here (`gh workflow run release.yml -R Innei/ryugi -f version=<version>`). 2. The workflow waits for the `Artifacts` CI to pass on a `ryugi-cloud` main commit that contains the tag, publishes `ryugi-artifacts@<version>` to npm from the tag, copies the generated `output-bootstrap.cjs` and `comment-threads.cjs` here, runs `scripts/bump-version.sh <version>`, pushes the commit with the tag `v<version>` and creates the GitHub Release. A rerun skips whatever is already published or tagged. The workflow reads `ryugi-cloud` with the `RYUGI_CLOUD_TOKEN` secret (contents and actions, read-only) and publishes through npm trusted publishing. ## Harness Integrations A real integration loads the `using-ryugi` bootstrap at session start. The acceptance test: open a clean session in the harness and send exactly > Let's make a react todo list A working integration starts `brainstorming` before any code is written; where artifacts can run (node and a browser), the first reply opens an artboard of directions. Copying skill files by hand, runtime shims, and per-session opt-ins are not integrations. ## Licensing Skills, harness integrations and docs are under Ryugi License 1.0 (`LICENSE`): use, modification and redistribution are permitted; the Restricted Parties in Schedule A (major Chinese platform companies and their agent and IDE products) receive no rights, and scraping the skills into a marketplace is prohibited. Upstream Superpowers material and contributions made before 2026-11-04 remain MIT — see Exhibit B, and keep it intact when editing `LICENSE`. The `ryugi-artifacts` package the launcher installs is proprietary (npm `license`: `UNLICENSED`) and is not part of this repository. ## Tests - Plugin-infrastructure tests live in `tests/`; run the relevant `run-*.sh` or test script for what you changed. - `docs/testing.md` lists what each suite covers.