AGENTS.md · diff
git:20261110.d7580ec to git:20261117.27b21bf
5 added, 4 removed. Audit A to A.
What this update changes in the checks
No check changed: every fixed check gives the same answer before and after this update.
A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.
# 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`. `ryugi-artifacts` releases separately on npm; a plugin release only versions the skills and harness manifests.
+ Users install from `main`. The plugin and `ryugi-artifacts` share one version and release together from the `Release` workflow here.
- 1. `scripts/bump-version.sh <version>` and commit.
- 2. `git tag v<version>` and `git push --atomic origin main v<version>`.
- 3. The `Release` workflow checks the versions and creates the GitHub Release.
+ 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.