Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.
JavaScript agent-orchestrationagentic-workflowai-agentsai-codingclaude-codecode-reviewcodebuddycodexcoding-agentscursordeveloper-toolshuman-on-the-loopllmmcpmulti-agentsdlcself-hostedsopworkflow-automationworkflow-engine
feat(portable): add Pi host support (adapter + Portable installer CLI) (#24)
Chen Zhongaf44e5d12384
diff --git a/EDITIONS.md b/EDITIONS.mdindex e1ae6e57..9202cbb2 100644--- a/EDITIONS.md+++ b/EDITIONS.md@@ -6,7 +6,7 @@ DevFlow 有两套独立维护的实现。为避免同一宿主同时加载两套| Edition | 仓库事实源 | 入口 | 维护方式 || --- | --- | --- | --- |-| Portable | `skills/` | CodeBuddy/Cursor/Claude 使用 `/devflow`,Codex 使用 `$devflow` | 修改 canonical Skill 和 adapter manifest |+| Portable | `skills/` | CodeBuddy/Cursor/Claude 使用 `/devflow`,Codex 使用 `$devflow`,Pi 使用 `/skill:devflow` | 修改 canonical Skill 和 adapter manifest || Classic(默认) | `.codebuddy/`、`.codex/`、`.cursor/`、`.claude/` | CodeBuddy/Cursor/Claude 使用 `/start-devflow`,Codex 使用 `$devflow-codex` | 以 `.codebuddy` 为参考行为;Cursor/Claude 由生成器产生 |保留这些顶层目录是有意为之:`.xxx/` 是各宿主的原生项目目录,`skills/` 是@@ -24,3 +24,6 @@ loopforge skills install claude`plan` 只读取安装资产,不修改目标项目。实际安装后,edition 和每个托管文件的摘要记录在项目的 `.devflow/install-state.json` 中。++Portable 的 Pi 适配是声明型的:`skills install pi` 只安装 `.pi/skills/`,isolated+(medium/large)模式还需要公开扩展 `pi install npm:pi-subagents` 提供 `subagent` 工具。diff --git a/README.md b/README.mdindex 7e77971d..2b3531be 100644--- a/README.md+++ b/README.md@@ -179,6 +179,19 @@ Then start a workflow:/devflow "add status filtering to the order list and cover the API with tests"```+### Pi++```bash+npx -y loopforge-cli@latest skills install pi+pi install npm:pi-subagents+```++Then start a workflow:++```text+/skill:devflow "add status filtering to the order list and cover the API with tests"+```+See [`EDITIONS.md`](EDITIONS.md) for the complete boundaries and directory layout.## Update and uninstall@@ -235,6 +248,11 @@ loopforge skills uninstall cursorloopforge skills update claudeloopforge skills status claudeloopforge skills uninstall claude++# Pi+loopforge skills update pi+loopforge skills status pi+loopforge skills uninstall pi```Installation state is stored in `.devflow/install-state.json`. An update stops instead of overwriting user-modified or conflicting files. Use `--force` only when you intend to replace conflicts or switch editions, preferably after inspecting `loopforge plan`.diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 5a6f79b5..ab175c6f 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -178,6 +178,19 @@ npx -y loopforge-cli@latest skills install claude/devflow "为订单列表增加状态筛选,并补充接口测试"```+### Pi++```bash+npx -y loopforge-cli@latest skills install pi+pi install npm:pi-subagents+```++安装后使用:++```text+/skill:devflow "为订单列表增加状态筛选,并补充接口测试"+```+完整边界和目录说明见 [`EDITIONS.md`](EDITIONS.md)。## 更新与卸载@@ -234,6 +247,11 @@ loopforge skills uninstall cursorloopforge skills update claudeloopforge skills status claudeloopforge skills uninstall claude++# Pi+loopforge skills update pi+loopforge skills status pi+loopforge skills uninstall pi```安装状态保存在 `.devflow/install-state.json`。检测到用户修改或文件冲突时,更新会停止而不是覆盖。只有在确认要替换冲突文件或切换 Edition 时才使用 `--force`,建议先运行 `loopforge plan` 检查变更。diff --git a/docs/architecture.md b/docs/architecture.mdindex e985ee7d..b9511f97 100644--- a/docs/architecture.md+++ b/docs/architecture.md@@ -11,7 +11,8 @@## Portable Edition`skills/` 提供独立的新 DevFlow 状态机、模板、规则、测试和 adapter,-支持 CodeBuddy、Codex、Cursor 与 Claude Code。脚本只依赖 Python 3.8++支持 CodeBuddy、Codex、Cursor、Claude Code 与 Pi(Pi 只有声明型 adapter,+isolated 模式依赖公开扩展 `npm:pi-subagents`)。脚本只依赖 Python 3.8+标准库;具体 Agent 调度能力由宿主提供。`skills/manifest.json` 是跨宿主 Skill 集合清单。`skills/` 是这一层的唯一diff --git a/docs/compatibility.md b/docs/compatibility.mdindex 6112b208..dd53a906 100644--- a/docs/compatibility.md+++ b/docs/compatibility.md@@ -8,6 +8,7 @@| Codex | `.codex/` + `.agents/skills` | `.agents/skills/devflow` || Cursor | `.cursor/` 完整包 | `.cursor/skills` + 两个执行器 || Claude Code | `.claude/` 完整包 | `.claude/skills` + 两个执行器 |+| Pi | 无(Portable only) | `.pi/skills` + `subagent` adapter(需 `npm:pi-subagents`) |Classic 的 Cursor/Claude 目录是生成产物;Portable 的事实只保存在 `skills/`。两者只共享显式行为合同和测试,不共享宿主运行文件。@@ -16,7 +17,7 @@ Classic 的 Cursor/Claude 目录是生成产物;Portable 的事实只保存在1. **结构门禁**:校验 JSON/YAML、Skill frontmatter、manifest 引用和链接。2. **漂移门禁**:`build-classic-hosts.py --check` 逐字比较 Classic 生成包。-3. **安装门禁**:统一 CLI 覆盖 4 宿主 × 2 edition,并验证重复安装、更新、卸载、+3. **安装门禁**:统一 CLI 覆盖 5 宿主 × 2 edition(pi 仅 Portable),并验证重复安装、更新、卸载、mixed-edition 拒绝和用户文件保护。4. **流程回归**:标准库单测和 CLI E2E 验证状态机、门禁、产物与恢复协议。5. **真实宿主 canary**:发布前或宿主大版本升级后,在隔离 fixture 仓库用真实diff --git a/scripts/smoke-install.sh b/scripts/smoke-install.shindex 5b180368..46eec94a 100755--- a/scripts/smoke-install.sh+++ b/scripts/smoke-install.sh@@ -68,6 +68,12 @@ DOWNSTREAM_PROJECT="$TMP_DIR/downstream-project"mkdir -p "$CODEBUDDY_PROJECT" "$DOWNSTREAM_PROJECT""$VENV_DIR/bin/loopforge" skills install codebuddy --project-root "$CODEBUDDY_PROJECT"test -f "$CODEBUDDY_PROJECT/.codebuddy/skills/manifest.json"++PI_PROJECT="$TMP_DIR/pi-project"+mkdir -p "$PI_PROJECT"+"$VENV_DIR/bin/loopforge" skills install pi --project-root "$PI_PROJECT"+test -f "$PI_PROJECT/.pi/skills/manifest.json"+test -f "$PI_PROJECT/.pi/skills/devflow/SKILL.md""$VENV_DIR/bin/python" \"$CODEBUDDY_PROJECT/.codebuddy/skills/devflow/scripts/install_adapter.py" \--adapter claude --project-root "$DOWNSTREAM_PROJECT" --copy-skills --refresh-manageddiff --git a/scripts/validate.sh b/scripts/validate.shindex 9c28a1bb..ff77b487 100755--- a/scripts/validate.sh+++ b/scripts/validate.sh@@ -129,12 +129,13 @@ if set(portable) != set(discovered):if DEFAULT_EDITION != "classic" or tuple(EDITION_SPECS) != ("portable", "classic"):raise SystemExit("Edition registry must keep Classic as the explicit default")for edition, metadata in EDITION_SPECS.items():- if set(metadata.get("entrypoints", {})) != set(HOSTS):+ hosts = metadata.get("hosts", HOSTS)+ if set(metadata.get("entrypoints", {})) != set(hosts):raise SystemExit(f"Edition entrypoint drift: {edition}")for source in metadata.get("source_roots", ()):if not (root / source).is_dir():raise SystemExit(f"Edition source does not exist: {edition}: {source}")- for host in HOSTS:+ for host in hosts:source = source_for(edition, host)if not (root / source).is_dir():raise SystemExit(f"Edition host source does not exist: {edition}/{host}: {source}")diff --git a/skills/devflow/adapters/pi/adapter.md b/skills/devflow/adapters/pi/adapter.mdnew file mode 100644index 00000000..47f31b5d--- /dev/null+++ b/skills/devflow/adapters/pi/adapter.md@@ -0,0 +1,42 @@+# Pi 适配器++pi 构建在 Agent Skills 之上,通过 `npm:pi-subagents` 扩展提供 `subagent` 工具。使用前先安装:++```bash+pi install npm:pi-subagents+```++没有该工具时不存在可用的生命周期 API,只能按 [runtime-core.md](../../references/runtime-core.md)+降级为 `single-context`,不得把降级状态标成 `isolated`。++## 能力映射++`subagent` 前台调用(`async: false`)会启动一个独立子会话并在返回前阻塞,属于 `spawn` 拓扑:++1. `spawn(role, prompt) -> executor_id`:调用+ `subagent { agent: "delegate", task: "<完整阶段提示>" }`,返回内容中的+ `Mission: <uuid> (completed)` 就是宿主签发的 `executor_id`。+2. `wait(executor_id)`:前台调用本身就是阻塞的,返回即子会话完成。+3. `close(executor_id)`:前台模式无需显式关闭;异步模式下用 pi-subagents 的 fleet/stop 能力。+4. `spawn_helper(role, bounded_prompt) -> executor_id`:调用只读内置 agent,例如+ `subagent { agent: "scout", task: "<有边界的检索提示>" }`,并把返回的 `Mission` UUID 作为 helper id。+5. `send(executor_id, message)`:前台模式不支持对已结束子会话追加消息。需要补充或重试时,+ 重新 `subagent` 一个全新实例并重新 `assign`,不得复用已结束的 Mission id。++## 使用步骤++1. 确认已安装 `pi-subagents`,且当前会话能看到 `subagent` 工具;缺失时停止并报告,+ 不得自创替代工具。+2. medium/large 使用 `--execution-mode isolated --host-adapter pi` 初始化。+3. REQUIREMENT 执行 `prepare --emit-prompt → start`,由主 Agent 调用 `devflow-clarify-requirements`+ 并填写需求报告,再 `finish`;不得创建需求分析 subagent。+4. route 中其他 Agent 阶段先用 `prepare --emit-prompt` 一次生成完整提示,再调用+ `subagent { agent: "delegate", task: "<提示>" }` 创建全新子会话,从返回的 `Mission: <uuid>`+ 取出 `executor_id`,用 `assign --executor-type dynamic --dispatch-tool subagent` 登记,再 `start`,+ 等待返回后校验产物并 `finish`。协调者不得代写 isolated 阶段产物。+5. 只读检索使用 `subagent { agent: "scout", task: "<有边界提示>" }`,并以 `devflow-code-explorer` 或+ `devflow-knowledge-retriever` 作为审计角色用 `helper --executor-type dynamic --dispatch-tool subagent`+ 登记。REVIEW 前不得使用 `devflow-code-reviewer`。++不同阶段使用不同的 `Mission` UUID。由于前台模式不支持 `send`,同阶段重试必须重新派发新实例并重新登记,+不得在状态里复用已结束的 id。diff --git a/skills/devflow/adapters/pi/manifest.json b/skills/devflow/adapters/pi/manifest.jsonnew file mode 100644index 00000000..037741bd--- /dev/null+++ b/skills/devflow/adapters/pi/manifest.json@@ -0,0 +1,13 @@+{+ "version": "1.0",+ "id": "pi",+ "compatibility": {+ "verified_on": "2026-09-17",+ "documentation": "https://github.com/nicobailon/pi-subagents"+ },+ "dispatch_tool": "subagent",+ "topology": "spawn",+ "stage_executor": "dynamic",+ "research_executor": "dynamic",+ "required_tools": ["subagent"]+}diff --git a/src/devflow_cli/cli.py b/src/devflow_cli/cli.pyindex 24fc3d21..574d967d 100644--- a/src/devflow_cli/cli.py+++ b/src/devflow_cli/cli.py@@ -5,7 +5,7 @@ import sysfrom pathlib import Pathfrom . import __version__-from .core import DevFlowError, apply_install, build_plan, doctor, status_rows, uninstall+from .core import DevFlowError, apply_install, build_plan, doctor, status_rows, uninstall, validate_choicefrom .editions import DEFAULT_EDITION, EDITIONS, HOSTS, entrypoint_for, host_label, source_for, specfrom .targets import load@@ -107,6 +107,7 @@ def main(argv=None) -> int:))return 0if args.command == "plan":+ validate_choice(args.host, args.edition)files = sorted(build_plan(args.host, args.edition))row = {"edition": args.edition,@@ -143,6 +144,8 @@ def main(argv=None) -> int:f"Next: reopen {host_label(args.host)} and run "f"{entrypoint_for(args.edition, args.host)} <你的需求>")+ if args.host == "pi" and args.edition == "portable":+ print("Note: Pi isolated mode also needs the public extension: pi install npm:pi-subagents")return 0if args.command == "skills":if args.skills_command in {"install", "update"}:@@ -163,6 +166,8 @@ def main(argv=None) -> int:f"Next: reopen {host_label(args.host)} and run "f"{entrypoint_for('portable', args.host)} <你的需求>")+ if args.host == "pi":+ print("Note: Pi isolated mode also needs the public extension: pi install npm:pi-subagents")return 0if args.skills_command == "status":rows = [diff --git a/src/devflow_cli/core.py b/src/devflow_cli/core.pyindex b04a8ac0..d40097b7 100644--- a/src/devflow_cli/core.py+++ b/src/devflow_cli/core.py@@ -10,7 +10,7 @@ from pathlib import Pathfrom typing import Dict, List, Optional, Tuplefrom . import __version__-from .editions import EDITIONS, HOSTS, source_for+from .editions import EDITIONS, HOSTS, hosts_for, source_forSTATE_VERSION = 1@@ -134,6 +134,14 @@ def materialize_portable(host: str, stage: Path) -> None:for name in manifest["skill_sets"]["portable"]:copy_skill(skills_root / name, target / name)return+ if host == "pi":+ target = stage / ".pi/skills"+ target.mkdir(parents=True, exist_ok=True)+ manifest = json.loads((skills_root / "manifest.json").read_text(encoding="utf-8"))+ copy_skills_manifest(skills_root, target)+ for name in manifest["skill_sets"]["portable"]:+ copy_skill(skills_root / name, target / name)+ returnraise DevFlowError(f"不支持的宿主: {host}")@@ -173,6 +181,14 @@ def validate_choice(host: str, edition: str) -> None:raise DevFlowError(f"未知宿主 {host};可选: {', '.join(HOSTS)}")if edition not in EDITIONS:raise DevFlowError(f"未知 edition {edition};可选: {', '.join(EDITIONS)}")+ if host not in hosts_for(edition):+ available = [item for item in EDITIONS if host in hosts_for(item)]+ hint = (+ f";Pi 只有 Portable,请运行: loopforge skills install {host}"+ if host == "pi" and "portable" in available+ else f";{host} 可用 edition: {', '.join(available)}"+ )+ raise DevFlowError(f"{edition} edition 不支持宿主 {host}{hint}")def path_present(path: Path) -> bool:diff --git a/src/devflow_cli/editions.py b/src/devflow_cli/editions.pyindex a22b805b..bcc3ead8 100644--- a/src/devflow_cli/editions.py+++ b/src/devflow_cli/editions.py@@ -4,28 +4,32 @@ from typing import Dict, TupleDEFAULT_EDITION = "classic"-HOSTS: Tuple[str, ...] = ("codebuddy", "codex", "cursor", "claude")+HOSTS: Tuple[str, ...] = ("codebuddy", "codex", "cursor", "claude", "pi")HOST_LABELS = {"codebuddy": "CodeBuddy","codex": "Codex","cursor": "Cursor","claude": "Claude Code",+ "pi": "Pi",}EDITION_SPECS: Dict[str, dict] = {"portable": {"description": "Agent Skills based portable workflow","source_roots": ("skills/",),+ "hosts": ("codebuddy", "codex", "cursor", "claude", "pi"),"entrypoints": {"codebuddy": "/devflow","codex": "$devflow","cursor": "/devflow","claude": "/devflow",+ "pi": "/skill:devflow",},},"classic": {"description": "Full host-native workflow derived from .codebuddy behavior","source_roots": (".codebuddy/", ".codex/", ".cursor/", ".claude/"),+ "hosts": ("codebuddy", "codex", "cursor", "claude"),"entrypoints": {"codebuddy": "/start-devflow","codex": "$devflow-codex",@@ -42,6 +46,15 @@ def spec(edition: str) -> dict:return EDITION_SPECS[edition]+def hosts_for(edition: str) -> Tuple[str, ...]:+ """返回某个 edition 支持的宿主集合。++ Classic 只覆盖有完整宿主原生包的宿主;Portable 覆盖所有支持 Agent Skills+ 的宿主,包括只有声明型 adapter 的 pi。+ """+ return tuple(spec(edition).get("hosts", HOSTS))++def source_for(edition: str, host: str) -> str:if edition == "classic":return f".{host}/"diff --git a/src/devflow_cli/targets/pi.py b/src/devflow_cli/targets/pi.pynew file mode 100644index 00000000..08aa628c--- /dev/null+++ b/src/devflow_cli/targets/pi.py@@ -0,0 +1,10 @@+HOST = "pi"+++def describe() -> str:+ return "Pi project workflow target"+++def materialize(edition, stage) -> None:+ from devflow_cli.core import materialize_classic, materialize_portable+ (materialize_portable if edition == "portable" else materialize_classic)(HOST, stage)diff --git a/tests/test_installer.py b/tests/test_installer.pyindex 7c992e87..5dd10c73 100644--- a/tests/test_installer.py+++ b/tests/test_installer.py@@ -154,10 +154,26 @@ class InstallerTests(unittest.TestCase):self.assertEqual("classic", DEFAULT_EDITION)self.assertEqual(("portable", "classic"), tuple(EDITION_SPECS))for edition, metadata in EDITION_SPECS.items():- self.assertEqual(set(HOSTS), set(metadata["entrypoints"]))- for host in HOSTS:+ hosts = metadata.get("hosts", HOSTS)+ self.assertEqual(set(hosts), set(metadata["entrypoints"]))+ for host in hosts:self.assertTrue((ROOT / source_for(edition, host)).is_dir())+ def test_pi_is_portable_only(self):+ self.assertIn("pi", EDITION_SPECS["portable"]["hosts"])+ self.assertNotIn("pi", EDITION_SPECS["classic"]["hosts"])+ self.assertEqual("/skill:devflow", EDITION_SPECS["portable"]["entrypoints"]["pi"])++ def test_pi_installs_portable_skills_and_rejects_classic(self):+ with tempfile.TemporaryDirectory() as td:+ project = Path(td)+ installed, _unchanged = apply_install(project, "pi", "portable")+ self.assertGreater(installed, 0)+ self.assertTrue((project / ".pi/skills/devflow/SKILL.md").is_file())+ self.assertTrue((project / ".pi/skills/manifest.json").is_file())+ with self.assertRaises(DevFlowError):+ apply_install(project, "pi", "classic")+def test_editions_and_plan_make_the_split_visible_without_writing(self):output = StringIO()with redirect_stdout(output):