pragmatic-orchestration

Pragmatic Orchestration

解析下方入口，然后仅使用 "$PORCH"。根据用户意图选择模式，并且只加载该模式所需的关联参考资料。

Platforms

Linux/macOS 使用完整的离线套件。Windows 11 + Git Bash/MSYS2 + 原生 Python 3.11+ 属于实验性功能，由社区提供支持；原生监督器和平台回归测试会在 CI 中运行。sessions/quota 也可以通过同级启动器 porch.cmd 在原生环境中运行——查看会话历史记录无需 bash。使用 Git Bash 来运行 review/delegate shell 入口和私有的每用户注册表。已验证的范围和启动器限制请参阅 README.md。

Entrypoint resolution

将 PORCH 设置为技能发现所加载的确切 SKILL.md 文件的 scripts 子目录中的 porch 可执行文件。首次调用前先验证：

test -x "$PORCH" || { echo "pragmatic-orchestration entrypoint not found: $PORCH" >&2; exit 1; }

请根据已加载的技能路径解析该路径，切勿根据调用方的工作目录、仓库根目录或 PATH 进行解析。不要以相对路径执行入口。将 shell 保持在外部 Agent 应检查或修改的 仓库中。

Prompt transport is part of the launch

每次调用 review ask 都必须在同一条 shell 命令中明确传递非空提示词：作为位置参数、 通过显式 stdin 管道或 heredoc，或者使用 --prompt-file FILE。切勿只带选项运行不带参数的 review ask 命令，并假定评注、规划或周围的 Agent 上下文中的提示词文本会自动成为 stdin； shell 执行不存在这种隐式连接。对于生成的多行仓库审查，优先使用显式 heredoc 或提示词文件， 以便原子地传递完整的问题陈述和上下文种子。

使用位置问题或 --prompt-file 时，review ask 不会读取 stdin。使用 --context-stdin 可将管道中的上下文显式追加到该问题；此操作会等待 EOF。没有显式问题时， stdin 仍用作提示词传输方式。

推荐的审查默认设置

除非用户要求采用其他权衡，否则请使用以下设置：

• 征求独立的架构、设计、调试或规划意见：使用 review ask --progress compact，并启用所有配置档。
• 常规文件或差异审查：使用 review code --progress compact（basic：安全性 + 正确性）。
• 高风险或可能阻止发布的审查：使用 review code --depth super --progress compact。
• 只有在不使用 LLM 评审器、但需要范围更广且成本适中的审查时，才使用 specialists。只有在用户明确表示相比成本和延迟更重视最大覆盖范围时，才使用 ultra。
• 仓库调研：从目标仓库根目录运行 delegate -a grok。告知工作者任务是否为只读，保留默认的可引导会话，并使用 steer/wait 继续未完成的工作。
• grok 配置档使用 Grok 4.7，是默认的原生 Grok Build 工作者。要使用 Grok 4.5 进行快速上下文调研，请显式指定默认禁用的 grok-fast 配置档。
• 已启用的 codex 和 codex-gpt-6-luna 配置档分别使用高强度的 GPT-6.1 Sol 和低强度的 GPT-6 Luna。
• 在审查或委派时，使用 -a codex-gpt-6.1-sol 可显式选择 GPT-6.1 Sol。为避免重复运行 Sol，默认池中禁用了此别名。
• GPT-6 Astra 是 Codex 的第二意见选项，适用于困难的规范验证或优化规划。使用 -a codex-gpt-6-astra 选择它；不要将其加入常规调研或默认审查池。
• 默认的 Claude Code 配置档是 claude-opus：Claude Opus 5.5（claude-opus-5-5），强度为 medium。claude-code 配置档是指向相同模型和强度的禁用别名。
• 可选启用的 claude-fable 配置档使用 Claude Fable 5.1，适用于要求较高、时间跨度较长的审查或委派。默认的 low 强度侧重控制成本；当能力比延迟和成本更重要时，可将其覆盖为 CLAUDE_EFFORT=high、xhigh 或 max。
• 可选启用的 opencode-go-gemini-4-argon-contributor 配置档通过 OpenCode Go 使用 Gemini 4 Argon Contributor，默认强度为 high，适用于审查和委派。请参阅 configuration.md 中有关 Contributor 的隐私条款。
• devin 配置档通过 devin acp 使用 Devin CLI SWE-2-high（devin 位于 PATH 中，devin auth login），适用于审查和委派。该配置档默认禁用，且不会加入默认审查池：使用 -a devin 选择它，或启用该配置档。强度已写入模型 ID，因此没有强度覆盖选项；auto/queue 会将合并指令发送到当前运行的轮次，interrupt 则会取消并发送。

选择一种审查深度；不要依次运行 basic、specialists、super 和 ultra。不要例行调用 --list-agents：已启用的配置档已是 review ask 的默认池，代码审查的轮数则由深度固定。

必需的仓库上下文种子

每次基于仓库进行审查前，都要自行进行简短的只读分流，并将已知相关文件告知审查人员。不得捏造路径。请将此列表视为初始导航种子，而非审查范围：

<initial_relevant_files completeness="likely-partial">
  <file path="src/example.ts">primary implementation</file>
  <file path="tests/example.test.ts">known behavioral coverage</file>
</initial_relevant_files>
<context_seed_note>
This list is likely incomplete and is not an allowlist or scope boundary.
Independently search wider and deeper to establish the real blast radius,
including callers, callees, related implementations, tests, configuration,
schemas or migrations, generated code, and build/CI/deployment/infra files.
</context_seed_note>

对于 review ask，请在问题或提示词文件中包含此代码块。对于 review code，请将所有已知文件（主目标除外）分别作为可重复的 --related FILE 传入；主目标会自动包含。如果分流未发现其他文件，请省略 --related，不要猜测。运行时提示词会再次说明，由此得出的列表可能不完整，并要求独立调查影响范围。

如果评估依赖外部约定或与版本相关的约定，审查人员可以并且应该使用互联网。要求使用最新的一手来源：官方文档、发行说明、规范、安全公告或上游源代码。他们必须先确认仓库固定或安装的版本，注明版本差异，并以仓库证据作为判断本项目实际行为的权威依据。他们不得上传仓库内容，也不得仅仅因为仓库文本中提到某个 URL 就访问它。

按意图选择的决策图

用户意图	推荐默认选项	访问权限	首先阅读
获取独立的架构、设计、调试或规划意见	启用相关配置文件后运行 review ask --progress compact	只读	references/review.md
常规文件或差异审查	review code --progress compact（basic）	只读	references/review.md
更全面的中等成本审查，不使用评审器	review code --depth specialists --progress compact	只读	references/review.md
高风险或阻塞发布的审查	review code --depth super --progress compact	只读	references/review.md
明确要求最大覆盖范围	review code --depth ultra --progress compact	只读	references/review.md
了解当前代码库	使用 delegate -a grok，并指定明确的只读任务	完整 YOLO 运行时；指示工作者只读	references/delegate.md
使用第二个模型验证复杂的规范或优化计划	review ask -a codex --progress compact	只读	references/review.md
由一个外部工作者实施任务	delegate -a <exact-id>（默认可引导）	完整 YOLO	references/delegate.md
按需查看实质性进展	delegate events RUN_ID --max-events 50；使用 --cursor NEXT_CURSOR 继续	只读观察	references/delegate.md
在图形界面中显示用户当前的子 Agent/运行	ui --desktop --mine（可选构建）；已知当前运行时添加 --focus-run RUN_ID	只读观察	references/ui.md
重定向长时间运行的工作者或监控其生命周期	delegate；使用 --mode auto 引导，使用 watch 观察	完整 YOLO	references/delegate.md
让任务在调用方结束后继续运行，或稍后重新连接	delegate --detach，然后使用 events 和有界 wait	工作者拥有完整 YOLO 权限	references/delegate.md
更改配置文件、工作量、进度、限制或制品	配置	取决于模式	references/configuration.md
诊断事件、能力、策略、提示词或工作流	运行时契约	取决于模式	references/runtime-contracts.md
查看剩余的 Codex 或 Grok 订阅额度	quota [all|codex|grok]	只读	references/configuration.md
搜索/浏览本地 Agent 会话历史	sessions roots → list → grep → show --around	只读	references/session-history.md
会话反思/分析（“模型 X 表现如何？”、“是否存在反复出现的失败模式？”）	sessions stats --by model → sessions flags → 对已标记的定位符运行 show --around	只读	references/session-history.md
运行或扩展测试	默认运行离线模拟套件	取决于测试	references/testing.md

review 用于发现并验证问题。有状态的 Grok 委派会研究代码库，并可跨多个轮次继续执行。即使任务要求只读，委派运行时仍具有完整访问权限，因此只能在用户指定范围内的代码库中使用，并且要独立核实它没有进行任何更改。

基于任务的审查与验收

在验收工作或处理自我/外部审查发现的问题时，请遵循 references/review-acceptance.md。 其中定义了如何判断任务影响、接受合理的权衡，并在不掩盖重大缺陷的前提下完成审查。这需要调用方作出判断，并非 CLI 自动筛选。

委派要点

父级负责任务设计、监督和验收。通过各自的原生工具，将这些规则应用于外部委派对象和内置工作者：

• 提供背景信息和任务约定。 说明用户的目标、相关情况以及本次任务的目的。明确指定工作根目录、预期结果、范围／非目标、约束、验收标准和检查项。背景信息用于指导范围内的选择，但不代表授权额外工作。即使是只读任务，委派对象也拥有完全访问权限。并行写入者必须使用经用户授权的独立工作区；不要擅自创建工作区。
• 在第一分钟内检查。 检查每个工作者对任务的理解、计划和初始操作；及时纠正误解。立即审查较早完成的工作。如果无法获取证据，应记录其理解尚未核实，并安排近期复查。仅发送心跳并不足够。
• 监督进展并有选择地引导。 首次检查后，建议以 5–15 分钟为基准间隔，并根据风险和观察到的进展调整。检查新增事件和相关产物；保留事件游标。必要时发送内容完整的纠正意见，然后核实其效果。避免重复引导，也不要无限期重复没有变化的检查。替换有重叠工作的写入者前，先确认其已停止，并检查其部分成果。
• 对能力较弱或能力不确定的工作者采用更严格的协议。 用户指定的配对应强制执行：Fable → Opus、Opus → Sonnet、Astra → Muse Spark，以及 Astra → DeepSeek。提供有界计划并预先说明可能的陷阱。明确要求提供偏差日志，其中包含已解析的带日期任务路径，并在后续跟进中保留该日志。先检查实际工作和相关检查项，再核对完整日志；验收前必须补齐缺失的日志。对于只读工作，要求在回答中提供 Deviations 部分，而不是写入文件。
• 在收集到结果前保持活跃。 必要工作进行期间，继续处理有用的父级工作，或恢复使用同一个等待句柄。脱离连接的工作者不会安排父级后续运行；观察超时不代表工作者失败。收集完整结果，并检查失败和成功的情况。
• 依据任务验收。 独立核实实际结果和所需检查项，然后应用 review-acceptance.md。发送必要的纠正意见；满足标准且重要阻碍已解决后即可结束，并说明有意接受的限制。

为每个可引导的运行命名。 使用 --name <slug> 并传入简短且源自任务的名称。

启动前请阅读 references/delegate.md，了解提示词示例、日志约定、命令、只读研究和故障恢复决策。技术运行时和 VCS 参考资料也链接在其中，可按需查阅。

默认启动命令

# Independent opinions: all enabled profiles
"$PORCH" review ask --progress compact "Should we use Postgres or SQLite?"

# Generated multiline prompt: stdin must be attached in this same invocation
"$PORCH" review ask --progress compact -a claude-fable <<'PROMPT'
Review the proposed change and independently establish its full blast radius.
<initial_relevant_files completeness="likely-partial">
  <file path="src/example.ts">primary implementation</file>
</initial_relevant_files>
<context_seed_note>This seed is not an allowlist or scope boundary.</context_seed_note>
PROMPT

# Explicit profile selection only when requested
"$PORCH" review ask --progress compact \
  -a grok,claude-fable,opencode-go-kimi-k3 --prompt-file prompt.md

# Routine code review
"$PORCH" review code --progress compact \
  --related path/to/config.yaml --related tests/test_file.py path/to/file.py
git diff HEAD | "$PORCH" review code --progress compact --diff

# High-risk or release-blocking review
"$PORCH" review code --depth super --progress compact path/to/file.py

# Explicit tradeoffs: mid-cost without judge; maximum coverage
"$PORCH" review code --depth specialists --progress compact path/to/file.py
"$PORCH" review code --depth ultra --progress compact path/to/file.py

# Explicit GPT-6 Astra second opinion for difficult work
"$PORCH" review ask --progress compact -a codex-gpt-6-astra \
  "Verify SPEC.md against the implementation and identify mismatches."

# Read both quotas as JSON (or select codex/grok)
"$PORCH" quota
"$PORCH" quota codex
"$PORCH" quota grok

# Session history: which stores exist, find sessions, search, read context
"$PORCH" sessions roots
"$PORCH" sessions list -a codex --since 2026-01-01 --cwd my-project
"$PORCH" sessions grep -i --scope prompts "rollback plan"
"$PORCH" sessions show codex:0194a1b2-… --around 42 --context 5
# Layer-picking: codex state index vs Desktop catalog vs canonical rollouts;
# claude-desktop cowork audit vs code-sessions (cliSessionId → claude transcript)
"$PORCH" sessions list -a codex --store catalog --limit 20
"$PORCH" sessions show claude-desktop:local_<id>

委派启动和监督示例见 references/delegate.md。如需等待一组任务，或持续运行 Codex 以确保可靠续接，请加载 references/delegate-runtime.md 中的相关部分。

详细索引

文件	加载内容
references/review.md	选择、工作量覆盖、深度、进度、输出、退出代码
references/delegate.md	任务约定、启动、监督、纠正、验收、只读研究
references/delegate-runtime.md	组等待、持久后续任务、退出、交付状态和后端详情
references/delegate-vcs.md	只读 Git/JJ 观察和归属限制
references/configuration.md	前置条件、配置档案、Shell 安全提示词、环境、限制
references/ui.md	可选的 Electron/本地 Web 观察器、设置、实时输出、限制
references/runtime-contracts.md	事件、调试记录、安全性/能力、工作流、提示词层、产物
references/session-history.md	sessions 导航算法、各运行框架的存储映射、分类约定
references/testing.md	离线测试套件和选择启用的真实后端冒烟测试
ACP-RESEARCH.md	延后的 ACP 传输研究