@shiwenbin1617/pstack 0.14.4 → 0.15.0

package/README.en.md

@@ -0,0 +1,373 @@
+<div align="center">
+
+# pstack
+
+**Senior engineering habits, installed into your AI coding agent**
+
+A set of Markdown rules that make an agent understand the problem before it writes, and produce runtime evidence after. Not "done!" with nothing behind it.
+
+[![npm](https://img.shields.io/npm/v/@shiwenbin1617/pstack?color=cb3837&logo=npm)](https://www.npmjs.com/package/@shiwenbin1617/pstack)
+[![license](https://img.shields.io/npm/l/@shiwenbin1617/pstack?color=blue)](./LICENSE)
+[![node](https://img.shields.io/node/v/@shiwenbin1617/pstack)](https://nodejs.org)
+
+[Install](#install) · [Use it](#use-it) · [How it works](#how-it-works) · [Skills](#skills) · [FAQ](#faq)
+
+Works with **Claude Code** and **Codex** · 44 skills · 23 playbooks · 21 engineering principles
+
+[中文](./README.md) · English
+
+```bash
+npx @shiwenbin1617/pstack add
+```
+
+</div>
+
+---
+
+## Why pstack
+
+The default failure mode of AI-written code is that it looks reasonable, does not run, or runs but nobody checked.
+
+| What you get | What it does |
+|---|---|
+| **Understand before you touch** | `/how` and `/why` fan out parallel subagents across the subsystem and its design history. You do not move on until you can state the full call path |
+| **Interfaces before implementation** | `/architect` fixes types, signatures, and module boundaries before any code crosses a function boundary. Skipping it requires a written reason and cannot hide inside the implementation |
+| **Adversarial across models** | `/arena` runs N designs in parallel and grafts the best parts together. `/interrogate` sends different models at your diff in turn |
+| **Evidence, not assertion** | The prove-it-works principle. Green CI is not evidence. An agent saying it passed is not evidence. Only a result observed on the real surface by someone who did not write the code counts |
+| **23 playbooks** | Bug fixes, features, refactors, performance, shipping, and long unattended runs each have fixed steps, exit conditions, and acceptance criteria |
+| **21 engineering principles** | From "pick the core data structure first" to "migrate the callers, then delete the old API". Skills cite them where they apply |
+| **No AI smell** | `/no-comments` strips narrating comments. `/unslop` removes AI tells. `/technical-writing` handles PRs and commit messages |
+| **One install, two hosts** | One body of methodology generates two native trees. Claude Code and Codex keep separate files, agents, and config |
+
+The goal is not more output. It is less output where every line holds up.
+
+---
+
+## Requirements
+
+- Node.js >= 18
+- Claude Code or Codex. Install whichever you use. If both are present, pstack detects them.
+- Bun is optional. Only the full PR watcher in `babysit` and the ledger CLI in `orchestrate` need it. The helpers never install dependencies behind your back.
+
+---
+
+## Install
+
+```bash
+npx @shiwenbin1617/pstack add
+```
+
+First pick the agent: Claude Code, Codex, or both. The cursor starts on whichever host is detected on this machine.
+
+Then pick your skills. Arrow keys move, `space` toggles, `a` selects all, `enter` confirms. Ten core entry points come preselected.
+
+**The set is coupled and only works installed whole.** `poteto-mode` reads all 33 principle skills, so whatever you pick, the installer pulls in what it references. The preselected core lands on 39 of the 44. `pstack add --all` saves you the arithmetic.
+
+Last, it asks once whether to write the pstack block into CLAUDE.md / AGENTS.md. See "Writing into CLAUDE.md / AGENTS.md" below.
+
+To type less, install it globally. The command is then `pstack`.
+
+```bash
+npm i -g @shiwenbin1617/pstack
+```
+
+> The unscoped `pstack` on npm is an unrelated package from 2015. It is not this project.
+
+### Other ways to install
+
+```bash
+pstack add --core            # core entry points plus their dependencies, 39 of them
+pstack add --all             # all 44
+pstack add how why           # named skills only
+pstack add --core --host codex --memory   # Codex only, and write AGENTS.md
+```
+
+### Managing what you installed
+
+```bash
+pstack list                  # what is installed, and where
+pstack find review           # search the catalog
+pstack update                # reinstall what you already have
+pstack remove                # interactive uninstall
+pstack doctor                # installation status for both hosts
+```
+
+Any of these also works as `npx @shiwenbin1617/pstack <command>` without a global install.
+
+### Where files land
+
+Each host always gets **independent copies**. Claude Code and Codex use different invocation syntax, frontmatter, agent formats, and config paths. Editing an installed file on one side never touches the other.
+
+```
+~/.agents/skills/how/          Codex skill, invoked as $how
+~/.codex/agents/*.toml         Codex custom agents
+~/.claude/skills/how/          Claude Code skill, invoked as /how
+~/.claude/agents/*.md          Claude Code custom agents
+```
+
+| Flag | Effect |
+|---|---|
+| `--host claude` / `codex` / `both` | Target one agent. Defaults to whichever hosts are detected on this machine |
+| `--scope user` / `project` | Install into `~/`, or into this repo at `./.claude/` and `./.agents/`. Defaults to user |
+| `--copy` | Ask for independent copies explicitly. Currently the default and the only mode |
+| `--memory` / `--no-memory` | Whether to write the pstack block into CLAUDE.md / AGENTS.md. Without the flag, an interactive install asks and a non-interactive one writes nothing |
+| `--dry-run` | Print what would happen. Write nothing |
+| `-y` / `--yes` | Skip the confirmation |
+
+### Writing into CLAUDE.md / AGENTS.md
+
+Installed skills are not much use if the agent never learns they exist. `--memory` writes a block into the always-loaded instruction file naming what is installed, how to invoke it, and where the model config lives.
+
+Which file depends on host and scope. Claude Code gets `CLAUDE.md`, Codex gets `AGENTS.md`. `--scope project` writes into the repo root, `--scope user` writes `~/.claude/CLAUDE.md` and `~/.codex/AGENTS.md`.
+
+The block sits between two markers, and pstack never touches anything outside them.
+
+```markdown
+<!-- pstack:start -->
+## pstack
+
+Rigorous agent workflows, installed as skills in `~/.claude/skills`.
+Invoke one by name: `/architect`, `/how`, `/interrogate`, ...
+<!-- pstack:end -->
+```
+
+Installing again replaces that block in place rather than appending a second one. `pstack update` refreshes a block that is already there and never introduces one. Removing the last skill removes the block, leaving everything you wrote intact.
+
+### Giving it to your team
+
+One line is all a colleague needs.
+
+```bash
+npx @shiwenbin1617/pstack add --core
+```
+
+To pin a version or serve from an internal mirror, publish this repo to a private registry and run `npx <your-package> add`. There is no Claude Code plugin entry point, because plugin loading would bypass the host adapter. Both hosts install their own artifacts through the CLI and nothing else.
+
+---
+
+## Use it
+
+### 1. Bind your model tiers
+
+This step is optional, but run it once.
+
+```text
+# Claude Code
+/setup-pstack
+
+# Codex
+$setup-pstack
+```
+
+It reads the models your session can actually reach and binds three tiers.
+
+| Tier | Where it goes |
+|---|---|
+| Fast code model | Mechanical changes with a clear spec |
+| Precise-execution model | Work that must follow steps to the letter |
+| Judgment model | Copy, design calls, adversarial review |
+
+Skill text only ever says "use your judgment model". This file decides who that is. Claude Code writes `~/.claude/pstack-models.md` and Codex writes `~/.codex/pstack-models.md`. Neither reads the other. Skip the step and every skill falls back to its own inline tier defaults.
+
+### 2. One entry point covers most days
+
+```text
+# Claude Code
+/poteto-mode There is a strange bug in this PR. Reproduce it, fix it, then verify.
+
+# Codex
+$poteto-mode Add CSV and JSON export to the settings page, with runtime evidence.
+```
+
+### 3. It routes itself
+
+It reads your request, matches a playbook, copies that playbook's steps verbatim into a todo list, and calls the other skills step by step.
+
+On Claude Code, `/poteto-mode` keeps its native sticky mode. Codex has no such mode and pstack does not fake one. Invoke `$poteto-mode` for each new task there, and use the goal, wait, or recurring-monitoring features of your Codex session for long runs.
+
+### 4. Call a skill by name when you want one
+
+```
+/how How do we cancel a run? Is there an N+1 query when cancelling in bulk?
+/why Why was this retry written as exponential backoff with jitter?
+/interrogate Review this PR.
+```
+
+On Codex, replace `/` with `$`, as in `$poteto-mode`.
+
+---
+
+## How it works
+
+### The five-stage loop
+
+```
+  1 Understand     2 Design        3 Build         4 Verify        5 Deliver
+  ────────────    ────────────    ────────────    ────────────    ────────────
+  /how            /architect      write code      /interrogate    /unslop
+  /why            /arena          /tdd            verification    /technical-writing
+  /recall         /blast-radius   /swarm          real evidence   /no-comments
+                                                                  open the PR
+
+       └── every stage has an exit condition and blocks until it is met ──┘
+```
+
+| Stage | Exit condition |
+|---|---|
+| 1 Understand | You can state the full path from input to output without hedging |
+| 2 Design | Interfaces and data shapes are fixed. Implementation is filling in blanks |
+| 3 Build | The code explains itself without comments propping it up |
+| 4 Verify | You hold runtime evidence, not an assertion |
+| 5 Deliver | Nothing a human reads smells like AI wrote it |
+
+### The 23 playbooks
+
+`/poteto-mode` matches one of these.
+
+| Group | Playbooks |
+|---|---|
+| **Find the problem** | `investigation` read-only research · `bug-fix` reproduce, locate, fix, prove · `perf-issue` optimize against a baseline · `hillclimb` push one metric over time · `runtime-forensics` leaks, idle spin, glitches · `trace-forensics` analyze a captured profile |
+| **Write something** | `feature` new behavior built from a data shape · `refactoring` structural change that preserves behavior · `prototype` a throwaway sketch that settles a decision · `visual-parity` pixel-exact match between two implementations |
+| **Deliver** | `opening-a-pr` · `babysit` drive a PR to merge-ready · `shipping` land a verified run after independent checks · `autopilot-full` one owner per PR through merge · `autopilot-stack` build a Graphite stack for a human to land |
+| **Long runs** | `autonomous-run` drive to a predicate without stopping · `orchestrate` a standing multi-day, multi-PR, multi-agent program · `multi-phase-plan` work spanning phases · `session-pickup` take over another agent's in-flight work · `pause-safely` stop cleanly with a checkpoint |
+| **Meta** | `authoring-a-skill` write a SKILL.md · `eval` blind-test the effect of a prompt change · `worktree-cleanup` prune worktrees and reclaim disk |
+
+### What the `feature` playbook actually does
+
+1. `/how` over the subsystem you are about to change.
+2. `/architect` for parallel design exploration. **Skipping requires a written reason.** A design decision may not be folded silently into the implementation.
+3. Write the throughput checkpoint. What must run first, what can run in parallel, and how shared state gets split.
+4. Only now write code. A delegate gets file paths, the **data shape decided up front**, and acceptance criteria. You review the diff yourself.
+5. Verify on the real surface. "Inconclusive" is not a pass, and neither is the wrong surface.
+6. Rebase into small, ordered commits.
+7. If the design is contested, run `/interrogate` before shipping.
+8. Run `opening-a-pr`.
+
+The phrase "data shape decided up front" in step 4 carries the weight. A state machine instead of scattered booleans. A table or registry instead of branching. A typed model instead of the same shape assumption repeated across files. You pick it **before the first line of logic**. This is where new features bury their landmines.
+
+---
+
+## Skills
+
+| Group | Skills |
+|---|---|
+| **Entry point** | `poteto-mode` |
+| **Understand** | `how` `why` `recall` `blast-radius` `teach` |
+| **Design and build** | `architect` `arena` `swarm` `tdd` `typescript-best-practices` `figure-it-out` |
+| **Verify** | `interrogate` `create-verification-skill` `maintain-verification-skill` |
+| **Writing** | `unslop` `no-comments` `technical-writing` `bro` |
+| **Meta** | `setup-pstack` `automate-me` `reflect` `show-me-your-work` |
+| **21 principles** | `principle-*`, cited by the skills above where they apply |
+
+<details>
+<summary>The 21 principles</summary>
+
+`boundary-discipline` `build-the-lever` `encode-lessons-in-structure` `exhaust-the-design-space` `experience-first` `fix-root-causes` `foundational-thinking` `guard-the-context-window` `laziness-protocol` `make-operations-idempotent` `migrate-callers-then-delete-legacy-apis` `minimize-reader-load` `model-the-domain` `never-block-on-the-human` `outcome-oriented-execution` `prove-it-works` `redesign-from-first-principles` `separate-before-serializing-shared-state` `sequence-verifiable-units` `subtract-before-you-add` `type-system-discipline`
+
+</details>
+
+Run `pstack find` for the full list with descriptions.
+
+---
+
+## Resources
+
+| What you want | Where to look |
+|---|---|
+| Install it, or read the version history | [npm: `@shiwenbin1617/pstack`](https://www.npmjs.com/package/@shiwenbin1617/pstack) · [GitHub Releases](https://github.com/shiwenbin1617/pstack/releases) |
+| File an issue or a PR | [github.com/shiwenbin1617/pstack](https://github.com/shiwenbin1617/pstack) |
+| See what the port changed | [`adapters/claude-code.md`](./adapters/claude-code.md) · [`adapters/codex.md`](./adapters/codex.md) |
+| Follow the original author through a full task | [`docs/guide/`](./docs/guide/README.md) |
+| Validate a skill you edited | `node scripts/build.mjs --check` |
+| Generate the distribution trees | `node scripts/build.mjs`, which writes `dist/` |
+| Triage Slack issues automatically | [`automations/benny/`](./automations/benny/README.md), which needs your own Slack MCP and a scheduled agent |
+
+---
+
+## FAQ
+
+<details>
+<summary><b>How is this different from CLAUDE.md, AGENTS.md, or .cursorrules?</b></summary>
+
+Those are **always-resident** project rules. Every session loads all of them into context, so they have to stay short and general. "Use TypeScript." "Tests go in tests/."
+
+pstack skills load **on demand**. Only the description line of each of the 44 skills stays resident. The agent reads the body when it judges the skill relevant. That budget is what lets each skill go deep. The `feature` playbook has 8 steps with named exit conditions. The `refactoring` one demands a behavior fixture before any structural change. You cannot fit that density into an always-resident file.
+
+They do not conflict. CLAUDE.md holds facts about your project. pstack holds general engineering method.
+
+</details>
+
+<details>
+<summary><b>Is it Claude Code only?</b></summary>
+
+No. Claude Code and Codex both work, and the installer detects which you have.
+
+`skills/` holds the shared methodology. The builder generates two independent host trees. The Claude Code tree uses `/skill`, Markdown agents, and Claude frontmatter. The Codex tree uses `$skill`, `agents/openai.yaml`, TOML agents, and Codex paths. `scripts/build.mjs --check` blocks cross-host leakage.
+
+Adding a third host touches none of the 44 skills. Write one adapter and add an entry to `HOSTS` in `scripts/lib.mjs`.
+
+</details>
+
+<details>
+<summary><b>Will installing all 44 blow up my context?</b></summary>
+
+No. Only the `description` line of each skill stays resident. Bodies load on demand.
+
+Codex has a hard limit worth knowing. Its skill index gets 2% of context or 8000 characters, whichever is smaller, and long descriptions get truncated past that. pstack keeps its descriptions tight, but if you also run other skill packs and hit the truncation, install a subset with `pstack add` instead of `--all`.
+
+</details>
+
+<details>
+<summary><b>Does it conflict with Trellis?</b></summary>
+
+They divide differently, and one part does collide.
+
+pstack is **stateless**. It owns the method and the standard for doing one thing. It remembers no project state across sessions. Trellis owns the specs, tasks, and work logs that accumulate in `.trellis/`, which solves the problem of an agent starting from zero every time.
+
+The collision is workflow orchestration. Trellis runs plan, implement, verify, finish. pstack runs playbooks. Their verification bars are far apart. A Trellis check runs lint, type-check, and tests. pstack says none of those count as verification.
+
+To combine them, let Trellis own state and pstack own method. Put the pstack core rules in `.trellis/spec/` so its auto-injection carries the standard into every task.
+
+</details>
+
+<details>
+<summary><b>Does it make simple tasks slow?</b></summary>
+
+It can, which is why `/poteto-mode` is aimed at work that needs rigor rather than at everything. When it cannot match a playbook it backs out instead of forcing a fit.
+
+One principle exists for this specific risk. `laziness-protocol` ships the smallest change that reaches the goal and reverts speculative cleanup that might be useful later.
+
+If it still feels heavy, skip `/poteto-mode` and call `/how` or `/interrogate` directly.
+
+</details>
+
+<details>
+<summary><b>How do I make it ours?</b></summary>
+
+Shared methodology lives in `skills/`. Host differences live in `adapters/claude-code/` and `adapters/codex/`. After editing, run `node scripts/build.mjs --check`, then `pstack update --host claude` and `pstack update --host codex` separately. Installed directories never sync to each other.
+
+That check validates frontmatter, catches directory name collisions, resolves relative links, and finds hardcoded model names or host-specific tool names.
+
+To make an agent work the way you personally do, run `/automate-me`. It reads your past sessions and drafts a `-mode` skill from how you actually work.
+
+</details>
+
+<details>
+<summary><b>What changed in the port?</b></summary>
+
+- Cursor's `readonly` mode strips MCP access. The `Explore` subagent in Claude Code does not, so it keeps MCP and loses file writes instead. The "please do not edit files" convention inside `why` and `reflect` is now enforced by the harness.
+- Skills that depended on `cursor-team-kit`, namely `deslop`, `control-ui`, and `control-cli`, were replaced by the bundled `/unslop` and by project-local verification skills that `/create-verification-skill` generates.
+- `grokbot/make-bot-ui` was deleted. It was tied to Cursor's automation webhook, which neither target host has.
+- Every hardcoded model slug upstream became one of three semantic tiers, bound by `/setup-pstack`.
+
+The full mapping is in [`adapters/`](./adapters/).
+
+</details>
+
+---
+
+## Upstream and license
+
+Forked from [cursor/plugins/pstack](https://github.com/cursor/plugins/tree/main/pstack) by Lauren Tan ([@poteto](https://x.com/poteto), React core team, previously Meta, Netflix, and Cursor). The original [usage guide](./docs/guide/README.md) is preserved. It still uses Cursor as its backdrop, and the methodology carries over unchanged.
+
+MIT License. Improvements and PRs welcome.

package/README.md

@@ -6,10 +6,20 @@
 
 一套 Markdown 规则，逼 AI 在动手前把问题想清楚、动手后拿出运行时证据，而不是写完就说"改好了"。
 
+[![npm](https://img.shields.io/npm/v/@shiwenbin1617/pstack?color=cb3837&logo=npm)](https://www.npmjs.com/package/@shiwenbin1617/pstack)
+[![license](https://img.shields.io/npm/l/@shiwenbin1617/pstack?color=blue)](./LICENSE)
+[![node](https://img.shields.io/node/v/@shiwenbin1617/pstack)](https://nodejs.org)
+
 [安装](#安装) · [使用](#使用) · [工作原理](#工作原理) · [技能清单](#技能清单) · [常见问题](#常见问题)
 
 同时支持 **Claude Code** 和 **Codex** · 44 个技能 · 23 个 playbook · 21 条工程原则
 
+中文 · [English](./README.en.md)
+
+```bash
+npx @shiwenbin1617/pstack add
+```
+
 </div>
 
 ---
@@ -47,7 +57,13 @@ AI 写代码的默认失败模式是：看上去合理、跑不起来、或者
 npx @shiwenbin1617/pstack add
 ```
 
-交互式勾选要装哪些技能：`↑↓` 移动，`空格` 勾选，`a` 全选，`回车` 确认。默认预选 10 个核心入口，安装时自动补齐它们引用的运行依赖。
+先单选装给哪个 agent：Claude Code、Codex，或者两个都装。本机探测到哪个，光标就落在哪个上。
+
+然后勾选要装哪些技能：`↑↓` 移动，`空格` 勾选，`a` 全选，`回车` 确认。默认预选 10 个核心入口。
+
+**这套东西是耦合的，装全了才有效果。** `poteto-mode` 会去读全部 33 个 principle 技能，所以不管你勾几个，安装时都会按引用关系补齐，勾满核心入口最后落在 44 个里的 39 个。省事就直接 `pstack add --all`。
+
+最后问一次要不要把 pstack 那段写进 CLAUDE.md / AGENTS.md，见下面的「写进 CLAUDE.md / AGENTS.md」。
 
 嫌包名长就装成全局，之后命令就是 `pstack`：
 
@@ -60,9 +76,10 @@ npm i -g @shiwenbin1617/pstack
 ### 其他安装方式
 
 ```bash
-pstack add --core            # 核心入口及其自动展开的运行依赖
+pstack add --core            # 核心入口及其自动展开的运行依赖，共 39 个
 pstack add --all             # 全装 44 个
 pstack add how why           # 按名字装指定技能
+pstack add --core --host codex --memory   # 只装 Codex，并写入 AGENTS.md
 ```
 
 ### 管理命令
@@ -93,9 +110,29 @@ pstack doctor                # 检查两端的安装状态
 | `--host claude` / `codex` / `both` | 只装给指定 agent。默认自动探测本机装了哪些 |
 | `--scope user` / `project` | 装到全局 `~/`，还是当前仓库的 `./.claude/`、`./.agents/`。默认 user |
 | `--copy` | 显式使用独立副本；当前也是默认且唯一模式 |
+| `--memory` / `--no-memory` | 写不写 CLAUDE.md / AGENTS.md 里那段 pstack 说明。不给这个选项时，交互安装会问一次，非交互安装默认不写 |
 | `--dry-run` | 只打印会做什么，不写任何文件 |
 | `-y` / `--yes` | 跳过确认 |
 
+### 写进 CLAUDE.md / AGENTS.md
+
+装完技能，agent 未必知道它们存在。`--memory` 会往常驻指令文件里写一段说明：装了什么、怎么调用、模型配置在哪。
+
+写哪个文件由 host 和 scope 决定。Claude Code 写 `CLAUDE.md`，Codex 写 `AGENTS.md`；`--scope project` 写当前仓库根目录，`--scope user` 写 `~/.claude/CLAUDE.md` 和 `~/.codex/AGENTS.md`。
+
+那段内容夹在两个标记之间，标记之外的东西 pstack 不碰：
+
+```markdown
+<!-- pstack:start -->
+## pstack
+
+Rigorous agent workflows, installed as skills in `~/.claude/skills`.
+Invoke one by name: `/architect`, `/how`, `/interrogate`, ...
+<!-- pstack:end -->
+```
+
+重复安装会原地替换这一段，不会越写越长。`pstack update` 只刷新已经存在的那一段，不会给没有的文件新加。卸载完最后一个技能时，这一段会被一起删掉，你自己写的内容原样保留。
+
 ### 分发给同事
 
 同事只需要一行：
@@ -235,6 +272,8 @@ Codex 上把 `/` 换成 `$`，例如 `$poteto-mode`。
 
 | 想做什么 | 看哪里 |
 |---|---|
+| 装包 / 看版本历史 | [npm: `@shiwenbin1617/pstack`](https://www.npmjs.com/package/@shiwenbin1617/pstack) · [GitHub Releases](https://github.com/shiwenbin1617/pstack/releases) |
+| 提 issue 或 PR | [github.com/shiwenbin1617/pstack](https://github.com/shiwenbin1617/pstack) |
 | 了解移植时改了什么 | [`adapters/claude-code.md`](./adapters/claude-code.md) · [`adapters/codex.md`](./adapters/codex.md) |
 | 跟着原作者走一遍完整任务 | [`docs/guide/`](./docs/guide/README.md) |
 | 改技能后做校验 | `node scripts/build.mjs --check` |

package/bin/pstack.mjs

@@ -5,6 +5,7 @@ import { join } from "node:path";
 import {
   REPO_ROOT, HOSTS, findSkills, installSkill, installAgents,
   listInstalled, removeSkill, CORE_SKILLS, expandSkillDependencies,
+  writeMemory, removeMemory, hasMemory,
 } from "../scripts/lib.mjs";
 
 const c = {
@@ -41,6 +42,7 @@ function help() {
   console.log(`    --host <claude|codex|both>     ${paint(c.grey, "Target agent (default: both, detected)")}`);
   console.log(`    --scope <user|project>         ${paint(c.grey, "Install globally or into this repo (default: user)")}`);
   console.log(`    --copy                         ${paint(c.grey, "Install independent host-specific copies (default)")}`);
+  console.log(`    --memory / --no-memory         ${paint(c.grey, "Write the pstack block into CLAUDE.md / AGENTS.md")}`);
   console.log(`    --core                         ${paint(c.grey, "Core entry set plus required dependencies, no prompts")}`);
   console.log(`    --all                          ${paint(c.grey, "Every skill, no prompts")}`);
   console.log(`    -y, --yes                      ${paint(c.grey, "Skip confirmation")}`);
@@ -49,13 +51,15 @@ function help() {
 }
 
 function parseArgs(argv) {
-  const opts = { _: [], host: null, scope: "user", core: false, all: false, yes: false, dryRun: false };
+  const opts = { _: [], host: null, scope: "user", core: false, all: false, yes: false, dryRun: false, memory: null };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--host") opts.host = argv[++i];
     else if (a === "--scope") opts.scope = argv[++i];
     else if (a === "--link") { console.error(paint(c.red, "--link was removed: Claude Code and Codex installs must stay independent.")); process.exit(1); }
     else if (a === "--copy") {}
+    else if (a === "--memory") opts.memory = true;
+    else if (a === "--no-memory") opts.memory = false;
     else if (a === "--core") opts.core = true;
     else if (a === "--all") opts.all = true;
     else if (a === "-y" || a === "--yes") opts.yes = true;
@@ -146,6 +150,49 @@ function multiSelect(items, { preselected = new Set(), title }) {
   });
 }
 
+/** Arrow keys to move, enter to pick one. Returns null on cancel. */
+function singleSelect(items, { title, initial = 0 }) {
+  return new Promise((resolve) => {
+    let cursor = initial;
+    emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+
+    let lastLines = 0;
+    const render = () => {
+      if (lastLines) process.stdout.write(`\x1b[${lastLines}A\x1b[0J`);
+      const lines = [`${paint(c.bold, title)} ${paint(c.grey, "↑↓ move · enter confirm · esc cancel")}`];
+      items.forEach((it, i) => {
+        const pointer = i === cursor ? paint(c.cyan, "❯") : " ";
+        const label = i === cursor ? paint(c.bold, it.label) : it.label;
+        const hint = it.hint ? " " + paint(c.grey, it.hint) : "";
+        lines.push(`${pointer} ${label}${hint}`);
+      });
+      process.stdout.write(lines.join("\n") + "\n");
+      lastLines = lines.length;
+    };
+
+    const done = (result) => {
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      process.stdin.removeListener("keypress", onKey);
+      process.stdout.write("\n");
+      resolve(result);
+    };
+
+    const onKey = (_str, key) => {
+      if (key.name === "up" || key.name === "k") cursor = (cursor - 1 + items.length) % items.length;
+      else if (key.name === "down" || key.name === "j") cursor = (cursor + 1) % items.length;
+      else if (key.name === "return") return done(items[cursor].value);
+      else if (key.name === "escape" || (key.ctrl && key.name === "c")) return done(null);
+      render();
+    };
+
+    process.stdin.on("keypress", onKey);
+    render();
+  });
+}
+
 function confirm(question) {
   return new Promise((resolve) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
@@ -163,13 +210,26 @@ const NAME_COL = Math.max(...findSkills().map((s) => s.name.length)) + 2;
 
 async function cmdAdd(opts) {
   const catalog = findSkills();
-  const hosts = resolveHosts(opts);
+  let hosts = resolveHosts(opts);
   let names;
 
   if (opts.all) names = catalog.map((s) => s.dirName);
   else if (opts.core) names = CORE_SKILLS;
   else if (opts._.length) names = opts._;
   else if (isTTY()) {
+    console.log(paint(c.cyan, BANNER));
+    if (!opts.host) {
+      const detected = detectHosts();
+      const choices = [
+        { value: ["claude"], label: HOSTS.claude.label.padEnd(14), hint: detected.includes("claude") ? "detected" : "not detected" },
+        { value: ["codex"], label: HOSTS.codex.label.padEnd(14), hint: detected.includes("codex") ? "detected" : "not detected" },
+        { value: ["claude", "codex"], label: "Both".padEnd(14), hint: "independent copies for each" },
+      ];
+      const initial = detected.length > 1 ? 2 : Math.max(0, choices.findIndex((ch) => ch.value[0] === (detected[0] || "claude")));
+      const picked = await singleSelect(choices, { title: "Install for which agent?", initial });
+      if (picked === null) { console.log(paint(c.grey, "cancelled.")); return; }
+      hosts = picked;
+    }
     const width = Math.max(20, (process.stdout.columns || 80) - NAME_COL - 10);
     const items = catalog.map((s) => ({
       value: s.dirName,
@@ -177,7 +237,6 @@ async function cmdAdd(opts) {
       hint: truncate(s.description.replace(/\s+/g, " "), width),
     }));
     const preselected = new Set(CORE_SKILLS.filter((n) => catalog.some((s) => s.dirName === n)));
-    console.log(paint(c.cyan, BANNER));
     console.log(`  installing to: ${paint(c.bold, hosts.map((h) => HOSTS[h].label).join(" + "))}  ${paint(c.grey, "(" + opts.scope + " scope)")}\n`);
     const picked = await multiSelect(items, { preselected, title: "Select skills to install" });
     if (picked === null) { console.log(paint(c.grey, "cancelled.")); return; }
@@ -199,10 +258,17 @@ async function cmdAdd(opts) {
   const selected = expandSkillDependencies(requested, catalog);
   const addedDependencies = selected.filter((skill) => !requested.includes(skill));
   if (!opts.yes && !opts.dryRun && isTTY()) {
-    const ok = await confirm(`install ${paint(c.bold, String(selected.length))} skills to ${hosts.map((h) => HOSTS[h].label).join(" + ")}?`);
+    const split = addedDependencies.length ? paint(c.grey, ` (${requested.length} picked, ${addedDependencies.length} referenced)`) : "";
+    const ok = await confirm(`install ${paint(c.bold, String(selected.length))} skills to ${hosts.map((h) => HOSTS[h].label).join(" + ")}${split}?`);
     if (!ok) { console.log(paint(c.grey, "cancelled.")); return; }
   }
 
+  let memory = opts.memory;
+  if (memory === null) {
+    const files = hosts.map((h) => HOSTS[h].memoryFile(opts.scope)).join(" and ");
+    memory = !opts.dryRun && isTTY() && !opts.yes ? await confirm(`add the pstack block to ${paint(c.bold, files)}?`) : false;
+  }
+
   if (addedDependencies.length) console.log(`\n${paint(c.grey, `added ${addedDependencies.length} required skill dependencies`)}`);
   for (const host of hosts) {
     const dir = HOSTS[host].skillsDir(opts.scope);
@@ -213,6 +279,10 @@ async function cmdAdd(opts) {
     }
     const agentsDir = installAgents({ host, scope: opts.scope, dryRun: opts.dryRun });
     if (agentsDir) console.log(`  ${paint(c.green, "✓")} agents ${paint(c.grey, "→ " + agentsDir)}`);
+    if (memory) {
+      const file = writeMemory({ host, scope: opts.scope, skills: selected, dryRun: opts.dryRun });
+      console.log(`  ${paint(c.green, "✓")} memory ${paint(c.grey, "→ " + (file || HOSTS[host].memoryFile(opts.scope) + " (already current)"))}`);
+    }
   }
 
   if (opts.dryRun) { console.log(`\n${paint(c.yellow, "dry run — nothing written.")}`); return; }
@@ -243,6 +313,11 @@ async function cmdRemove(opts) {
       const removed = removeSkill(n, { host, scope: opts.scope, dryRun: opts.dryRun });
       console.log(removed ? `  ${paint(c.green, "✓")} removed ${n}` : `  ${paint(c.grey, "· not installed: " + n)}`);
     }
+    // The block only describes installed skills, so it goes with the last of them.
+    if (!listInstalled({ host, scope: opts.scope }).length) {
+      const file = removeMemory({ host, scope: opts.scope, dryRun: opts.dryRun });
+      if (file) console.log(`  ${paint(c.green, "✓")} removed the pstack block ${paint(c.grey, "→ " + file)}`);
+    }
   }
   console.log("");
 }
@@ -280,6 +355,11 @@ async function cmdUpdate(opts) {
       console.log(`  ${paint(c.green, "✓")} ${s.name}`);
     }
     installAgents({ host, scope: opts.scope, dryRun: opts.dryRun });
+    // Refresh the block only where one already exists; update never introduces it.
+    if (opts.memory !== false && (opts.memory || hasMemory({ host, scope: opts.scope }))) {
+      const file = writeMemory({ host, scope: opts.scope, skills: selected, dryRun: opts.dryRun });
+      if (file) console.log(`  ${paint(c.green, "✓")} memory ${paint(c.grey, "→ " + file)}`);
+    }
   }
   console.log("");
 }
@@ -306,7 +386,8 @@ function cmdDoctor(opts) {
     for (const scope of ["user", "project"]) {
       const dir = HOSTS[host].skillsDir(scope);
       const n = listInstalled({ host, scope }).length;
-      console.log(`      ${scope.padEnd(8)} ${n ? paint(c.green, n + " installed") : paint(c.grey, "0 installed")}  ${paint(c.grey, dir)}`);
+      const memory = hasMemory({ host, scope }) ? paint(c.grey, "  · block in " + HOSTS[host].memoryFile(scope)) : "";
+      console.log(`      ${scope.padEnd(8)} ${n ? paint(c.green, n + " installed") : paint(c.grey, "0 installed")}  ${paint(c.grey, dir)}${memory}`);
     }
   }
   console.log("");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shiwenbin1617/pstack",
-  "version": "0.14.4",
+  "version": "0.15.0",
   "description": "if you want to go fast, go deep first. rigorous agent workflows for Claude Code and Codex. ported from poteto's pstack.",
   "bin": {
     "pstack": "bin/pstack.mjs"

package/scripts/lib.mjs

@@ -1,4 +1,4 @@
-import { readdirSync, readFileSync, statSync, lstatSync, mkdirSync, rmSync, cpSync, existsSync, realpathSync } from "node:fs";
+import { readdirSync, readFileSync, statSync, lstatSync, mkdirSync, rmSync, cpSync, existsSync, realpathSync, writeFileSync } from "node:fs";
 import { join, dirname, relative } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
@@ -16,6 +16,7 @@ export const HOSTS = {
     skillsDir: (scope) => (scope === "project" ? join(process.cwd(), ".claude", "skills") : join(homedir(), ".claude", "skills")),
     agentsDir: (scope) => (scope === "project" ? join(process.cwd(), ".claude", "agents") : join(homedir(), ".claude", "agents")),
     memoryFile: (scope) => (scope === "project" ? join(process.cwd(), "CLAUDE.md") : join(homedir(), ".claude", "CLAUDE.md")),
+    modelConfig: "~/.claude/pstack-models.md",
     invoke: (name) => `/${name}`,
   },
   codex: {
@@ -23,6 +24,7 @@ export const HOSTS = {
     skillsDir: (scope) => (scope === "project" ? join(process.cwd(), ".agents", "skills") : join(homedir(), ".agents", "skills")),
     agentsDir: (scope) => (scope === "project" ? join(process.cwd(), ".codex", "agents") : join(homedir(), ".codex", "agents")),
     memoryFile: (scope) => (scope === "project" ? join(process.cwd(), "AGENTS.md") : join(homedir(), ".codex", "AGENTS.md")),
+    modelConfig: "~/.codex/pstack-models.md",
     invoke: (name) => `$${name}`,
   },
 };
@@ -110,6 +112,74 @@ export function installAgents({ host, scope, dryRun = false }) {
   return dir;
 }
 
+const MEMORY_START = "<!-- pstack:start -->";
+const MEMORY_END = "<!-- pstack:end -->";
+
+/** The managed block pstack owns inside CLAUDE.md / AGENTS.md. Everything else in the file is the user's. */
+export function memoryBlock({ host, scope, skills = [] }) {
+  const h = HOSTS[host];
+  const entries = skills.filter((s) => CORE_SKILLS.includes(s.dirName)).map((s) => h.invoke(s.name));
+  const shown = entries.length ? entries : skills.map((s) => h.invoke(s.name));
+  return [
+    MEMORY_START,
+    "## pstack",
+    "",
+    `Rigorous agent workflows, installed as skills in \`${h.skillsDir(scope)}\`.`,
+    `Invoke one by name: ${shown.slice(0, 6).map((i) => `\`${i}\``).join(", ")}.`,
+    "",
+    `Reach for \`${h.invoke("poteto-mode")}\` on a non-trivial task that wants the full workflow. Mode activation is`,
+    "explicit and scoped to one task, so invoke it again for the next one.",
+    "",
+    `When a pstack skill asks for a per-role model, read \`${h.modelConfig}\`.`,
+    MEMORY_END,
+  ].join("\n");
+}
+
+/**
+ * Write the managed block into the host's memory file, replacing an earlier one so
+ * reinstalls stay idempotent. Returns the path, or null when nothing changed.
+ */
+export function writeMemory({ host, scope, skills = [], dryRun = false }) {
+  const file = HOSTS[host].memoryFile(scope);
+  const block = memoryBlock({ host, scope, skills });
+  const existing = existsSync(file) ? readFileSync(file, "utf8") : "";
+  const start = existing.indexOf(MEMORY_START);
+  const end = existing.indexOf(MEMORY_END);
+
+  let next;
+  if (start !== -1 && end > start) {
+    next = existing.slice(0, start) + block + existing.slice(end + MEMORY_END.length);
+  } else {
+    next = existing.trimEnd();
+    next = next ? `${next}\n\n${block}\n` : `${block}\n`;
+  }
+  if (next === existing) return null;
+  if (dryRun) return file;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, next);
+  return file;
+}
+
+/** Whether the host's memory file already carries a pstack block. */
+export function hasMemory({ host, scope }) {
+  const file = HOSTS[host].memoryFile(scope);
+  return existsSync(file) && readFileSync(file, "utf8").includes(MEMORY_START);
+}
+
+/** Drop the managed block, leaving the rest of the file untouched. */
+export function removeMemory({ host, scope, dryRun = false }) {
+  const file = HOSTS[host].memoryFile(scope);
+  if (!existsSync(file)) return null;
+  const existing = readFileSync(file, "utf8");
+  const start = existing.indexOf(MEMORY_START);
+  const end = existing.indexOf(MEMORY_END);
+  if (start === -1 || end < start) return null;
+  const next = (existing.slice(0, start).trimEnd() + "\n" + existing.slice(end + MEMORY_END.length).trimStart()).trim();
+  if (dryRun) return file;
+  writeFileSync(file, next ? next + "\n" : "");
+  return file;
+}
+
 export function expandSkillDependencies(selected, catalog = findSkills()) {
   const selectedNames = new Set(selected.map((skill) => skill.name));
   const queued = [...selected];

package/scripts/test.mjs

@@ -18,9 +18,13 @@ import {
   REPO_ROOT,
   expandSkillDependencies,
   findSkills,
+  hasMemory,
   installAgents,
   installSkill,
+  removeMemory,
+  writeMemory,
 } from "./lib.mjs";
+import { writeFileSync } from "node:fs";
 
 const scriptsDir = dirname(fileURLToPath(import.meta.url));
 const check = spawnSync(process.execPath, [join(scriptsDir, "build.mjs")], {
@@ -98,6 +102,32 @@ try {
   assert.match(codexSetup, /~\/\.codex\/pstack-models\.md/);
   assert.doesNotMatch(claudeSetup, /~\/\.codex/);
   assert.doesNotMatch(codexSetup, /~\/\.claude/);
+
+  // The memory block appends to whatever the user already wrote, and rewrites in place.
+  const claudeMemory = join(testRoot, "CLAUDE.md");
+  const codexMemory = join(testRoot, "AGENTS.md");
+  writeFileSync(claudeMemory, "# House rules\n\nRun the linter.\n");
+
+  for (const host of ["claude", "codex"]) {
+    assert.equal(hasMemory({ host, scope: "project" }), false);
+    writeMemory({ host, scope: "project", skills: selected });
+    assert.equal(hasMemory({ host, scope: "project" }), true);
+    assert.equal(writeMemory({ host, scope: "project", skills: selected }), null, "rewriting the same block is a no-op");
+  }
+
+  const claudeBody = readFileSync(claudeMemory, "utf8");
+  assert.match(claudeBody, /Run the linter\./);
+  assert.match(claudeBody, /\/poteto-mode/);
+  assert.match(claudeBody, /~\/\.claude\/pstack-models\.md/);
+  assert.equal(claudeBody.match(/pstack:start/g).length, 1);
+
+  const codexBody = readFileSync(codexMemory, "utf8");
+  assert.match(codexBody, /\$poteto-mode/);
+  assert.doesNotMatch(codexBody, /\.claude|Claude Code/);
+
+  removeMemory({ host: "claude", scope: "project" });
+  assert.equal(hasMemory({ host: "claude", scope: "project" }), false);
+  assert.equal(readFileSync(claudeMemory, "utf8"), "# House rules\n\nRun the linter.\n");
 } finally {
   process.chdir(originalCwd);
   rmSync(testRoot, { recursive: true, force: true });