Imported from sagemoyi/moagent (docs/features/quality/AGENTS.md). Install upstream with npx skills add sagemoyi/moagent --skill quality. Copyright stays with the author.

Feature: Agent quality packages

Name: quality
Author: sagemoyi

Session owner: agent quality / precision
Status: shipped (install wire-up; no dedicated setup wizard step).
Global rules: root ../../../AGENTS.md.

Purpose

Raise task precision and long-run reliability for the moagent personal profile by reusing community Pi packages already proven on coding Pi — moagent home only, not coding ~/.pi/agent.

Stack intent:

ask (clarify) → plan (read-only design) → todo / goal (execute) 
  + subagents (parallel research/review)
  + mcp-adapter (MCP without context bloat)
  + rtk / cache / fff (context efficiency + better search)
  + btw (side questions without polluting the main thread)

Owns / does not own

Owns	Does not own
Install list + skip/override envs in `scripts/install.sh`	Third-party package internals（除 subagents fork 集成）
This feature doc + CHANGELOG notes for the batch	Wizard framework (no per-package Q&A by default)
Host dependency hints (`rtk` optional)	Coding profile package set
Isolation: install only under `PI_CODING_AGENT_DIR`	Web UI re-implementation of TUI dialogs
Pinned subagents fork selection + legacy npm migration	Fork source development（在独立 `sagemoyi/pi-subagents` 仓库）

Package set (default)

#	Spec	Role
1	`npm:@juicesharp/rpiv-ask-user-question`	Structured clarifying questions (`ask_user_question`)
2	`npm:@narumitw/pi-plan-mode`	`/plan` read-only plan mode → `plan_mode_complete`
3	`npm:@juicesharp/rpiv-todo`	Persistent todo tool + overlay (`todo` / `/todos`)
4	`npm:@narumitw/pi-goal`	`/goal` autonomous completion + `goal_complete` / `goal_blocked`
5	`npm:pi-mcp-adapter`	Lazy MCP proxy (`/mcp`) — one tool instead of full schemas
6	`git:github.com/sagemoyi/pi-subagents@7e1dbab57a9e94404cf7bddc616f50ad809f1e4d`	Isolated subagents + Web direct control-v1 + in-process running steer
7	`npm:pi-rtk-optimizer`	Bash→rtk rewrite (if `rtk` present) + tool output compaction (`/rtk`)
8	`npm:pi-cache-optimizer`	Prompt/KV cache friendliness + footer stats
9	`npm:@ff-labs/pi-fff`	FFF-backed fuzzy find/grep (`fffind` / `ffgrep`)
10	`npm:@narumitw/pi-btw`	`/btw` side thread (does not append to main conversation)

Override the whole list at install time:

MOAGENT_QUALITY_PACKAGES="npm:@juicesharp/rpiv-todo npm:@narumitw/pi-plan-mode" ./scripts/install.sh

Primary paths (repo)

Path	Role
`scripts/install.sh` → `install_quality_packages`	Batch `pi install` into moagent agent dir
`docs/features/quality/AGENTS.md`	This file
`docs/features/README.md`	Index link
`sagemoyi/pi-subagents`	独立 fork 源码；上游 `pi-extensions/extensions/pi-subagents` 0.45.0，MIT；当前仓库为 private

moagent 仓库不复制 fork 源码；除 subagents 使用固定 Git commit 外，其余质量能力继续复用 npm 包。fork 的唯一编辑源是 sagemoyi/pi-subagents，不要在 $PI_CODING_AGENT_DIR 安装树内开发。

Runtime (moagent home only)

Path / env	Role
`~/.moagent/agent/settings.json` → `packages`	Should list npm specs plus the pinned subagents Git spec after install
`~/.moagent/agent/npm/node_modules/…`	Installed trees
`~/.moagent/agent/git/github.com/sagemoyi/pi-subagents/`	Pinned fork runtime checkout（仅运行/测试）
Package-local config under `$PI_CODING_AGENT_DIR`	e.g. `pi-plan-mode.json`, `pi-goal.json`, `pi-btw.json`, rtk optimizer settings — optional, packages create/read when used
`MOAGENT_SKIP_QUALITY=1`	Skip entire batch in `install.sh`
`MOAGENT_QUALITY_PACKAGES`	Space-separated override of install specs

Host prerequisite: `rtk` (rtk-ai/rtk)

Item	Detail
Binary	`rtk` from rtk-ai/rtk (Rust Token Killer)
Used by	`pi-rtk-optimizer` → `rtk rewrite` for bash command rewriting
Install	`scripts/install.sh` → `ensure_rtk` (before quality npm packages)
Default dir	`$MOAGENT_BIN_DIR` / `~/.local/bin` (same as moagent launcher)
Skip	`MOAGENT_SKIP_RTK=1`
Pin	`RTK_VERSION=vX.Y.Z` (passed through to official installer)
Override dir	`MOAGENT_RTK_INSTALL_DIR=/path`
Not	npm package named `rtk` (unrelated release tool) — install detects via `rtk rewrite`
Not	`rtk init --agent pi` — moagent relies on pi-rtk-optimizer, not global agent hooks

If install fails or is skipped: pi-rtk-optimizer still loads; output compaction works, bash rewrite stays off until a real rtk is on PATH.

UX notes

Surface	Notes
TUI `moagent`	Full experience (dialogs, overlays, `/plan` `/goal` `/btw` `/rtk` `/mcp` `/todos`)
`moagent-web`	RPC may forward some extension UI; TUI-native panels can be limited — prefer TUI for plan/ask/todo overlay
No setup wizard step	Packages work after install; optional configs are package-owned slash commands / JSON files

Recommended workflow for multi-step personal tasks:

ask_user_question when preferences/constraints are unclear
/plan for non-trivial work
todo or /goal for execution tracking / autonomous loop
subagent for parallel research or review when scale justifies cost
/btw for side questions that should not pollute the main thread

Install / reinstall

# full bootstrap (includes quality batch unless skipped)
./scripts/install.sh

# skip quality batch
MOAGENT_SKIP_QUALITY=1 ./scripts/install.sh

# quality packages only (example single package)
PI_CODING_AGENT_DIR=~/.moagent/agent pi install npm:@narumitw/pi-plan-mode

# reinstall this repo (does not remove already-installed npm packages)
PI_CODING_AGENT_DIR=~/.moagent/agent pi install .

Test checklist

PI_CODING_AGENT_DIR=~/.moagent/agent pi list
# expect 9 npm specs + the pinned subagents Git spec (plus memory / web / browser / this repo)

# coding profile should be unchanged by this path
# pi list  # leave alone

moagent
# smoke: /plan help · /goal · /todos · /btw hello · /rtk show · /mcp
# model can call ask_user_question instead of guessing

Decisions

Reuse community packages from coding experience; only subagents uses a fork because Web needs an extension-owned direct-control protocol.
Batch + one skip flag (MOAGENT_SKIP_QUALITY) — not 10 individual env vars.
No default wizard steps — zero-config packages; advanced JSON is package-owned.
Do not dual-install @heyhuynhgiabuu/pi-search (overlap with pi-web-access).
rtk host CLI is installed by default with the quality batch (ensure_rtk); skip with MOAGENT_SKIP_RTK=1. Failures warn only (do not fail bootstrap).
Do not npm install -g rtk (wrong package). Use official rtk-ai installer / ensure_rtk.
Subagents Web control is a first-class integration：RPC-only control envelope is handled inside the extension without invoking the parent LLM or appending a transcript turn; in-process supports immediate steer, subprocess falls back to mailbox. Other quality package Web UX remains best-effort/TUI-first.

Refactor status

2026-08-03：从上游 pi-subagents 0.45.0（MIT）抽取独立 fork，固定 7e1dbab57a9e94404cf7bddc616f50ad809f1e4d。新增 RPC-only control-v1 request/receipt、follow-up/message/steer/interrupt/close 直连，以及 in-process retained child AgentSession.steer()；177 tests + Biome + tsc --noEmit 通过。install 仅在 fork 成功后移除旧 npm spec，隔离 profile 已验证安装与无 LLM 的 RPC receipt。
2026-07-29：仓库包与 memory/web/browser/quality 安装已统一走 install_pi_pkg，静态测试禁止新增直接 PI_CODING_AGENT_DIR=… pi install 漂移。
2026-07-29：quality 包逐条安装并汇总失败，不再因单包抖动中断 bootstrap；rtk installer 的 RTK_INSTALL_DIR / RTK_VERSION 已传到管道下游。

Open issues / debt

Pin remaining non-subagents packages in default list for reproducible boots
Optional thin setup step: “quality packages installed ✓” status only
Web: map ask_user_question / plan ready actions to React modals if Moyi wants parity
Subagents token cost guardrails / default thinking levels
Document ordered-goal experimental flag for pi-goal if Moyi enables queues

Related modules

Module	Relation
Root `AGENTS.md`	Isolation, intake
Web search	External info; quality packages consume it
Memory	Long-term facts; todo/goal are session execution
配置向导	No step yet for this batch
`scripts/install.sh`	Package install only

quality

About

Feature: Agent quality packages

Purpose

Owns / does not own

Package set (default)

Primary paths (repo)

Runtime (moagent home only)

Host prerequisite: `rtk` (rtk-ai/rtk)

UX notes

Install / reinstall

Test checklist

Decisions

Refactor status

Open issues / debt

Related modules

Use it

Manifest

Reviews

About

Feature: Agent quality packages

Purpose

Owns / does not own

Package set (default)

Primary paths (repo)

Runtime (moagent home only)

Host prerequisite: rtk (rtk-ai/rtk)

UX notes

Install / reinstall

Test checklist

Decisions

Refactor status

Open issues / debt

Related modules

Use it

Manifest

Reviews

Host prerequisite: `rtk` (rtk-ai/rtk)