ramstack 0.1.0 → 0.1.1

package/README.md

@@ -1,29 +1,43 @@
-# rstack
+# ramstack
 
-rstack is a set of agent skills for Claude Code, Codex, and [pi](https://github.com/badlogic/pi-mono). It is a port of [pstack](https://github.com/cursor/plugins/tree/main/pstack) by [Lauren Tan](https://x.com/poteto).
+ramstack is a set of agent skills for Claude Code, Codex, and [pi](https://github.com/badlogic/pi-mono). It is a port of [pstack](https://github.com/cursor/plugins/tree/main/pstack) by [Lauren Tan](https://x.com/poteto).
 
-New to the repo? Follow [Get rstack running](docs/tutorials/get-started.md).
+## Quick start
+
+Install the skills into every host on your machine:
+
+```bash
+npx ramstack install
+```
+
+You need Node.js 18 or newer. The installer detects your hosts, shows the plan, and links the skills after you confirm. Then open a host and run:
+
+```
+/setup-ramstack
+```
+
+That writes the model config. You are ready. To try it on a real task, follow [Your first ramstack task](docs/tutorials/get-started.md). For other install paths (a clone, or a single host), see [How to install ramstack](docs/how-to/install.md).
 
 ## Tutorials
 
 Learn by doing.
 
-- [Get rstack running](docs/tutorials/get-started.md)
+- [Your first ramstack task](docs/tutorials/get-started.md)
 
 ## How-to guides
 
 Do a job you already understand.
 
-- [How to install rstack](docs/how-to/install.md)
+- [How to install ramstack](docs/how-to/install.md)
 - [How to configure models](docs/how-to/configure-models.md)
-- [How to update rstack](docs/how-to/update.md)
-- [How to uninstall rstack](docs/how-to/uninstall.md)
+- [How to update ramstack](docs/how-to/update.md)
+- [How to uninstall ramstack](docs/how-to/uninstall.md)
 
 ## Explanation
 
 Understand the design.
 
-- [About rstack](docs/explanation/about-rstack.md)
+- [About ramstack](docs/explanation/about-ramstack.md)
 - [About the pstack port](docs/explanation/about-the-pstack-port.md)
 - [About model routing](docs/explanation/about-model-routing.md)
 - [About poteto-mode](docs/explanation/about-poteto-mode.md)

package/cli/{rstack.mjs → ramstack.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// The rstack installer. Links the skills and agents into host discovery
+// The ramstack installer. Links the skills and agents into host discovery
 // directories, so one install serves every host. Two modes: run from a git
 // clone and links point into the clone (update pulls it); run from the npm
 // package (npx ramstack) and the payload copies to ~/.ramstack first, so the
@@ -14,7 +14,7 @@ import { fileURLToPath } from 'node:url';
 import readline from 'node:readline/promises';
 
 const REPO = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
-const CONFIG_PATH = path.join(REPO, '.rstack', 'config.local.json');
+const CONFIG_PATH = path.join(REPO, '.ramstack', 'config.local.json');
 
 // Package mode stores its payload copy and saved choices here, so links
 // never point into the npm cache.
@@ -37,11 +37,11 @@ const HOSTS = {
 const HOST_NAMES = Object.keys(HOSTS);
 const SCOPES = ['global', 'project'];
 
-const USAGE = `usage: rstack [install|update|uninstall] [options]
+const USAGE = `usage: ramstack [install|update|uninstall] [options]
 
 commands
-  install                  Link this clone's skills and agents into host directories (default)
-  update                   Pull this clone, then link any new skills
+  install                  Link the skills and agents into host directories (default)
+  update                   Fetch new files (git pull or npm package), then link again
   uninstall                Remove only the links this installer owns
 
 options
@@ -162,7 +162,7 @@ function saveConfig(clone, config) {
   const file = configPath(clone);
   fs.mkdirSync(path.dirname(file), { recursive: true });
   fs.writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
-  say('save', clone ? '.rstack/config.local.json' : file);
+  say('save', clone ? '.ramstack/config.local.json' : file);
 }
 
 function plan(hosts, base) {
@@ -415,7 +415,7 @@ async function main() {
     if (command === 'install') {
       if (wizard) {
         stageTotal = 2 + (hosts ? 0 : 1) + (scope ? 0 : 1);
-        await banner('rstack install');
+        await banner('ramstack install');
         if (!hosts) {
           stage('Hosts');
           hosts = await promptHosts(saved?.hosts ?? detectedOrAll());
@@ -442,7 +442,7 @@ async function main() {
           ...(counts.skip > 0
             ? [`${counts.skip} name(s) skipped. Rename or remove the real files, then run install again.`]
             : []),
-          'next: run /setup-rstack in each host to configure models',
+          'next: run /setup-ramstack in each host to configure models',
         ]);
         return;
       }
@@ -457,7 +457,7 @@ async function main() {
       if (counts.skip > 0) {
         say('note', `${counts.skip} name(s) skipped. Rename or remove the real files, then run install again.`);
       }
-      say('next', 'run /setup-rstack in each host to configure models');
+      say('next', 'run /setup-ramstack in each host to configure models');
       return;
     }
 
@@ -467,7 +467,7 @@ async function main() {
       const base = resolveBase(scope, values['project-dir'] ?? saved?.projectDir);
       if (wizard) {
         stageTotal = clone && !values['no-pull'] ? 3 : 2;
-        await banner('rstack update');
+        await banner('ramstack update');
         stage('Review');
         showPlan(hosts, scope, base, clone);
         note(
@@ -507,7 +507,7 @@ async function main() {
     const base = resolveBase(scope, values['project-dir'] ?? saved?.projectDir);
     if (wizard) {
       stageTotal = 2;
-      await banner('rstack uninstall');
+      await banner('ramstack uninstall');
       stage('Review');
       showPlan(hosts, scope, base, clone);
       note(
@@ -520,7 +520,7 @@ async function main() {
       runUnlink(hosts, base, src);
       finish(`links removed for ${hosts.join(', ')} (${scope})`, [
         clone
-          ? 'the clone, .rstack/config.local.json, and core.hooksPath stay'
+          ? 'the clone, .ramstack/config.local.json, and core.hooksPath stay'
           : `the store at ${STORE} stays; delete it to remove the copied skills`,
       ]);
       return;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ramstack",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Agent skills for Claude Code, Codex, and pi",
   "author": "Justin Ramos <justinramos@outlook.com>",
   "license": "MIT",
@@ -16,7 +16,7 @@
     "skills"
   ],
   "bin": {
-    "rstack": "cli/rstack.mjs"
+    "ramstack": "cli/ramstack.mjs"
   },
   "engines": {
     "node": ">=18"

package/skills/arena/SKILL.md

@@ -25,7 +25,7 @@ The N candidates will receive the same prompt, so the prompt is the contract. Ge
 
 1. State the artifact each candidate is producing.
 2. Derive the rubric. State what success looks like for *this* task, then turn it into 3-6 concrete gradeable criteria. Concrete: `Adds a --dry-run flag that skips writes`. Vague: `code is correct`. The rubric is the picker's tool in Phase D; candidates only see the task.
-3. Pick the runners. Use `arena runners` from your host's `## <host>` section of `~/.agents/rstack-models.md` when present. Otherwise default to one each on `fable`, `opus`, `sonnet`. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive.
+3. Pick the runners. Use `arena runners` from your host's `## <host>` section of `~/.agents/ramstack-models.md` when present. Otherwise default to one each on `fable`, `opus`, `sonnet`. Spawn more when the arena covers multiple design directions. Same model N times when the work is generation-bound rather than judgment-sensitive.
 4. Assign output paths. Each candidate writes to its own location (a git worktree where possible, otherwise `/tmp/arena-<slug>/candidate-<n>/`). N candidates writing to the same path is shared mutable state and fails the the **separate-before-serializing-shared-state** principle skill test.
 
 ## Phase B: Fan out
@@ -38,7 +38,7 @@ If a candidate fails to produce output, proceed with N-1 and note the dropout in
 
 ## Phase C: Cross-judge
 
-After all Phase B candidates complete, choose one model from the `arena cross-judge pool` in your host's `## <host>` section of `~/.agents/rstack-models.md` when present. Otherwise use `fable`, `opus`, `sonnet`. Prefer a different model family from the parent's. Spawn one readonly judge subagent on that model. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's reading in Phase D, not with the candidates themselves. Spawning while candidates are still writing means the judge sees partial or empty outputs and reports them as dropouts.
+After all Phase B candidates complete, choose one model from the `arena cross-judge pool` in your host's `## <host>` section of `~/.agents/ramstack-models.md` when present. Otherwise use `fable`, `opus`, `sonnet`. Prefer a different model family from the parent's. Spawn one readonly judge subagent on that model. It sees the rubric and the candidates by path label, scores each criterion, and recommends a base with rationale. It runs in parallel with the parent's reading in Phase D, not with the candidates themselves. Spawning while candidates are still writing means the judge sees partial or empty outputs and reports them as dropouts.
 
 ## Phase D: Pick a base
 

package/skills/interrogate/SKILL.md

@@ -33,7 +33,7 @@ Write one clear paragraph. Reviewers challenge whether the work achieves the int
 
 ## Step 3, Spawn Reviewers
 
-Launch all reviewers in a single message using the subagent tool. Use the `interrogate reviewers` list from your host's `## <host>` section of `~/.agents/rstack-models.md` when present, one reviewer per entry, extending or shrinking the Reviewer A/B/C labels below to the configured entry count; otherwise use the table defaults.
+Launch all reviewers in a single message using the subagent tool. Use the `interrogate reviewers` list from your host's `## <host>` section of `~/.agents/ramstack-models.md` when present, one reviewer per entry, extending or shrinking the Reviewer A/B/C labels below to the configured entry count; otherwise use the table defaults.
 
 | Subagent | Default model |
 |----------|---------------|

package/skills/poteto-mode/SKILL.md

@@ -88,7 +88,7 @@ Read the leaf skill in full for any principle you apply. Each entry names when i
 
 **Use `subagent_type: "poteto-agent"` for any subagent you spawn inside a playbook step** (code-writing delegates, ad-hoc helpers). `/poteto-mode` and `poteto-agent` route through the same wrapper. Routed workflow skills (`how`, `why`, `interrogate`, `reflect`, `swarm`) set their own `subagent_type` for diverse-model review; respect what the skill prescribes, don't override to `poteto-agent`.
 
-**Defaults for every subagent call.** Run in the background when the host supports it, file pointers not inlined context, explicit model per role (configurable via `/setup-rstack`; defaults `sonnet` for code, `fable` for prose and judgment). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (`fable`) when the task needs judgment or the intent is vague, and to your strongest instruction-following model (`opus`) when the work is a precisely specified sequence of steps to execute to the letter; trivial mechanical edits go to your fast code model. Per-role lines in your host's section of the `/setup-rstack` config (`~/.agents/rstack-models.md`) override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`); a role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model (omit the subagent `model` param).
+**Defaults for every subagent call.** Run in the background when the host supports it, file pointers not inlined context, explicit model per role (configurable via `/setup-ramstack`; defaults `sonnet` for code, `fable` for prose and judgment). Code delegates tier by difficulty. The hardest changes (cross-cutting design, gnarly concurrency, subtle algorithms) go to your strongest judgment model (`fable`) when the task needs judgment or the intent is vague, and to your strongest instruction-following model (`opus`) when the work is a precisely specified sequence of steps to execute to the letter; trivial mechanical edits go to your fast code model. Per-role lines in your host's section of the `/setup-ramstack` config (`~/.agents/ramstack-models.md`) override these defaults and the model choices in the routed skills (`how`, `why`, `arena`, `swarm`, `architect`, `interrogate`, `reflect`); a role with no line keeps its default, and a role line of `inherit-parent` or `auto` runs that role on the parent chat model (omit the subagent `model` param).
 
 You own every subagent's work. Review the diff and write your own summary, don't pass through what it said. Interrupt-chained resumes silently drop directives, so fire a fresh subagent with consolidated scope rather than trusting a "done" summary. A second opinion is the same prompt against a different model. Agreement is high-signal.
 

package/skills/poteto-mode/playbooks/autonomous-run.md

@@ -3,7 +3,7 @@
 **You own the exit condition. Define done, then drive to it without stopping.** For "going to bed" / "run until done" / "/loop until X".
 
 1. State the exit condition as a checkable predicate before the first iteration (tests green, repro fixed, all N PRs merged, pixel-diff zero). A vague goal stalls; a predicate lets you stop.
-2. Pick the wake mechanism using the host's `/loop` command when it has one (a built-in, not a rstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking.
+2. Pick the wake mechanism using the host's `/loop` command when it has one (a built-in, not a ramstack skill). An event to watch (CI, a merge, a ref advancing) gets a watcher subagent that wakes you on the event, with a long time-based heartbeat as fallback. No event gets a fixed-interval heartbeat sized to when the result is worth re-checking.
 3. Each iteration makes the smallest change the evidence justifies, verifies it against the predicate, commits if it advanced, discards changes that didn't help. Belt-and-suspenders that "might help" gets reverted, not left to ride.
    Sequence the work via the **sequence-verifiable-units** principle skill, verifying each unit before the next instead of batching checks at the end.
 4. Mid-run discoveries are yours. Address broken skills, related bugs, flaky verifiers, review noise, tooling failures, orphaned follow-ups, and fixable drift yourself via poteto-mode. Put out-of-band fixes in their own PR. Do not park reversible work for the human or use `AskUserQuestion`. Surface only irreversible actions, genuine product or preference calls no experiment can settle, or a real dead end. Keep the predicate as the main drive, and return to it after each side fix.

package/skills/poteto-mode/scripts/package.json

@@ -1,5 +1,5 @@
 {
-  "name": "@rstack/poteto-mode-tools",
+  "name": "@ramstack/poteto-mode-tools",
   "private": true,
   "type": "module",
   "scripts": {

package/skills/{setup-rstack → setup-ramstack}/README.md

@@ -1,16 +1,16 @@
-# Setup rstack
+# Setup ramstack
 
-Write the current host's section of `~/.agents/rstack-models.md`, the config file that sets a model per role for rstack skills.
+Write the current host's section of `~/.agents/ramstack-models.md`, the config file that sets a model per role for ramstack skills.
 
 ## When to use
 
-- `/setup-rstack` or "configure rstack models"
-- After installing rstack on a new host
+- `/setup-ramstack` or "configure ramstack models"
+- After installing ramstack on a new host
 - After model availability changes
 
 ## What it produces
 
-A `## <host>` section in `~/.agents/rstack-models.md` with one line per role. Other host sections in the file stay unchanged. Creates the file with a header comment if it does not exist.
+A `## <host>` section in `~/.agents/ramstack-models.md` with one line per role. Other host sections in the file stay unchanged. Creates the file with a header comment if it does not exist.
 
 ## How it works
 

package/skills/{setup-rstack → setup-ramstack}/SKILL.md

@@ -1,11 +1,11 @@
 ---
-name: setup-rstack
-description: Configure which models rstack uses per role, for the host you're running in (Claude Code, Codex, or pi). Detects your available models and writes your host's section of the shared config file. Use for /setup-rstack, "configure rstack models", or changing rstack's model choices.
+name: setup-ramstack
+description: Configure which models ramstack uses per role, for the host you're running in (Claude Code, Codex, or pi). Detects your available models and writes your host's section of the shared config file. Use for /setup-ramstack, "configure ramstack models", or changing ramstack's model choices.
 ---
 
-# Setup rstack
+# Setup ramstack
 
-Write your host's section of `~/.agents/rstack-models.md`, a config file that sets rstack's model per role. The skills read it at run time and fall back to their inline defaults when a section or line is absent, so this is an override layer, not a requirement.
+Write your host's section of `~/.agents/ramstack-models.md`, a config file that sets ramstack's model per role. The skills read it at run time and fall back to their inline defaults when a section or line is absent, so this is an override layer, not a requirement.
 
 The file is shared across hosts on purpose. Model slugs differ per host (`sonnet` means something in Claude Code and nothing in Codex or pi), so the file holds one `## <host>` section per tool, and every skill reads only the section for the host it is running in. Someone who switches between Claude Code, Codex, and pi runs this skill once in each and the tools stop stepping on each other.
 
@@ -25,7 +25,7 @@ If the host has a models API or CLI that lists the user's entitled models, prefe
 
 ### 2. Load current state
 
-If `~/.agents/rstack-models.md` exists and has a section for this host, read it and treat its values as the current choices. Otherwise start from the defaults in step 5. Never treat another host's section as current state; its slugs are not valid here.
+If `~/.agents/ramstack-models.md` exists and has a section for this host, read it and treat its values as the current choices. Otherwise start from the defaults in step 5. Never treat another host's section as current state; its slugs are not valid here.
 
 ### 3. Map and confirm
 
@@ -37,12 +37,12 @@ Every real slug written must be in the detected set; `inherit-parent` and `auto`
 
 ### 5. Write the config
 
-Rewrite this host's `## <host>` section of `~/.agents/rstack-models.md` with one line per role, using the same labels poteto-mode uses. Preserve every other host's section byte for byte; create the file with the header comment below if it doesn't exist. Re-runs stay idempotent by replacing the whole section.
+Rewrite this host's `## <host>` section of `~/.agents/ramstack-models.md` with one line per role, using the same labels poteto-mode uses. Preserve every other host's section byte for byte; create the file with the header comment below if it doesn't exist. Re-runs stay idempotent by replacing the whole section.
 
 Shape, with the Claude Code defaults filled in (another host substitutes its own detected slugs under its own heading, keeping the same roles):
 
 ```
-# rstack model configuration. One `## <host>` section per tool; skills read only
+# ramstack model configuration. One `## <host>` section per tool; skills read only
 # the section for the host they run in. One line per role. Delete a line (or a
 # section) to fall back to the skill defaults.
 # `inherit-parent` or `auto` as a value: the role runs on the parent chat model
@@ -74,8 +74,8 @@ The role split follows the upstream design: fast mechanical code goes to the fas
 
 ### 6. Confirm
 
-Tell the user which host section was written and that skills read it on their next run. If the file has sections for other hosts, say so; if it doesn't, suggest running `/setup-rstack` inside each other tool they use so every host gets valid slugs.
+Tell the user which host section was written and that skills read it on their next run. If the file has sections for other hosts, say so; if it doesn't, suggest running `/setup-ramstack` inside each other tool they use so every host gets valid slugs.
 
 ### 7. Offer a verification skill (optional)
 
-Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke `/create-verification-skill` (resolves wherever rstack is installed — workspace, user, or plugin). On no, move on without pushing.
+Check whether the project has a way to drive the real app for proof (a `verify-*` skill, or an existing harness). If not, offer once: "want a project-local verification skill, so agents can drive the app the way a user does and prove changes work? I can generate one with /create-verification-skill." On yes, invoke `/create-verification-skill` (resolves wherever ramstack is installed — workspace, user, or plugin). On no, move on without pushing.

package/skills/setup-ramstack/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "Setup ramstack"
+  short_description: "Configure ramstack models per host"

package/skills/swarm/SKILL.md

@@ -22,7 +22,7 @@ Open a todolist with one entry per phase before launching anything.
 1. State the done predicate and the artifact or report the swarm must return.
 2. Choose the shape. Partition into slices, race N workers on identical briefs, or mix both. For a race or mixed shape, declare `first pass`, `rank all`, or `best-of` before spawning.
 3. Set N from the user or derive it from the shape. N is total workers, not the cloud concurrency limit.
-4. Pick the worker model from `swarm workers` in your host's `## <host>` section of `~/.agents/rstack-models.md` when present. Otherwise use `sonnet`. For a model race, name each arm's model up front.
+4. Pick the worker model from `swarm workers` in your host's `## <host>` section of `~/.agents/ramstack-models.md` when present. Otherwise use `sonnet`. For a model race, name each arm's model up front.
 5. Give each worker its own writable output when it writes. Use a worktree, branch, or `/tmp/swarm-<slug>/worker-<n>/`.
 
 ## Phase B: Fan out

package/skills/setup-rstack/agents/openai.yaml

@@ -1,3 +0,0 @@
-interface:
-  display_name: "Setup rstack"
-  short_description: "Configure rstack models per host"