pi-coding-workflow

项目简介

pi-coding-workflow 是一个面向 Pi 的通用编码工作流包。它通过 TypeScript 引擎管理任务状态、PRD gate、manifest 校验、上下文预算、缓存、遥测、压缩摘要和自适应路由，同时保持 LLM 可见工具面简洁稳定。

核心目标

• 只暴露两个 LLM 可见工具：workflow_next 和 workflow_run。
• 将复杂工作流逻辑放在本地确定性引擎中，减少模型往返和 token 消耗。
• 默认返回轻量上下文，通过证据引用按需展开详情。
• 支持通用项目与 Unity 项目的 .workflow 初始化。
• 不恢复旧 wrapper、旧 Python engine 或大量 LLM 可见命令。

Pi package 资源

{
  "pi": {
    "extensions": ["./src/index.ts"],
    "skills": ["./skills"]
  }
}

安装

发布到 npm 后可通过以下方式安装：

npm install @leo-yjl/pi-coding-workflow

如果在 Pi 项目中使用，请按照 Pi 的 package 加载方式引入该 npm 包；工作流运行时数据会写入目标项目的 .workflow/**。

LLM 可见工具

workflow_next

语义只读的工作流路由工具。它不会修改项目源码、Git、task 状态或配置；但可能更新 .workflow/.runtime 下的 cache、telemetry 等运行时产物。

主要返回：

• 当前 task 状态
• 下一步建议
• blocker / warning
• evidenceRefs
• omitted
• tokenBudget
• adaptiveControl
• meta

默认：

{ "includeContext": "lite" }

需要更多详情时再显式请求：

{ "includeContext": "task" }

workflow_run

受控的工作流执行工具。

支持动作：

create_from_grill
create_child
start_checked
checkpoint
finish_run
archive
batch

规则：

• 默认 mode: "dry_run"。
• 修改 task 状态需要 mode: "execute"。
• start_checked 和 finish_run 会执行确定性 preflight。
• batch 可顺序执行多个动作，并返回 transaction、artifact 和 rollback hints。

Pi 命令

/workflow-init --dry-run
/workflow-init --execute
/workflow-init-spec --profile generic --dry-run
/workflow-init-spec --profile unity --dry-run
/workflow-init-spec --execute --plan <plan-id>
/workflow-prd-confirm --task <task-id> --message "confirmed" --execute

说明：

• /workflow-init 创建基础 .workflow 结构。
• /workflow-init-spec 生成或执行 spec 初始化计划。
• /workflow-prd-confirm 通过 Pi UI 写入 PRD 最终确认 gate，避免让 LLM 代为转述人工确认。

工作流能力

PRD / Manifest / Preflight

引擎支持：

• 解析 .workflow/tasks/<task>/prd.md。
• 提取 PRD kernel。
• 检测 TODO / TBD。
• 检测阻塞性开放问题。
• 检测最终确认 gate。
• 检查 Acceptance Criteria、Validation Plan、Definition of Done。
• 校验 implement.jsonl / check.jsonl。
• 执行 checkpoint，例如 git diff --check。

上下文预算与缓存

workflow_next 默认返回 lite context，并通过以下字段降低重复上下文成本：

• evidenceRefs
• omitted
• tokenBudget
• meta
• fingerprint-backed workflow cache

Adaptive Control

workflow_next 返回 adaptiveControl，用于指导下一步策略：

deterministic_preflight | subagent_brief | ask_user | none

推荐 agent 类型：

research | implement | check | finish | user | none

它只生成简短 brief，不新增额外 LLM 可见 subagent 工具。

Telemetry

工具调用会写入 schema-versioned telemetry JSONL：

.workflow/.runtime/telemetry/

用于记录 token 估算、cache hit、blocker/warning、artifact refs、transaction 和耗时。

Compaction

扩展注册了 session_before_compact hook。当 Pi session 中存在 workflow 状态时，会生成 workflow-aware summary，保留 active task、下一步、artifact refs、文件操作和近期对话信号。

初始化产物边界

目标项目中会使用以下结构：

.workflow/
  config.json
  tasks/
  spec/
  .runtime/

约定：

• .workflow/spec/** 保存长期项目知识。
• .workflow/tasks/** 保存任务数据。
• .workflow/.runtime/** 保存 cache、telemetry、checkpoint、transaction 等运行时产物。
• 初始化不会复制 engine，也不会创建旧 wrapper。

Profile

generic

通用项目 spec 骨架。

unity

通用 Unity 项目 spec 骨架。

当前生成：

.workflow/spec/modules/unity-project.md
.workflow/spec/modules/unity-assets.md

Unity profile 不默认假设具体资源系统；只有扫描到项目事实时才记录相关候选。

本地开发

npm test
npm run smoke:unity-scanner

历史任务回放：

npm run replay:history -- <project-root> --variants as_is,planning,in_progress

回放工具会复制历史任务到临时 workspace 中执行，不会修改源项目。

开源协议

本项目采用 MIT License 开源。

你可以自由使用、复制、修改、合并、发布、分发、再授权或销售本项目代码，但需要在副本或主要部分中保留版权声明和许可声明。

当前限制

• 不执行 Git 自动 commit / push。
• 不提供旧 Python workflow wrapper。
• 不增加额外 LLM 可见 subagent 工具。
• rollback hints 目前是建议信息，不自动执行回滚。

Overview

pi-coding-workflow is a generic coding workflow package for Pi. It keeps task state, PRD gates, manifest validation, context budgeting, caching, telemetry, compaction summaries and adaptive routing inside a TypeScript engine while keeping the LLM-visible tool surface small and stable.

Goals

• Expose only two LLM-visible tools: workflow_next and workflow_run.
• Move complex workflow behavior into a deterministic local engine to reduce model round trips and token usage.
• Return lightweight context by default and expose detailed evidence only when requested.
• Support .workflow initialization for generic and Unity projects.
• Avoid restoring legacy wrappers, legacy Python engines or a large LLM-visible command surface.

Pi package resources

{
  "pi": {
    "extensions": ["./src/index.ts"],
    "skills": ["./skills"]
  }
}

Installation

After the package is published to npm, install it with:

npm install @leo-yjl/pi-coding-workflow

When used in a Pi project, load this npm package through Pi's package mechanism. Runtime workflow data is written under .workflow/** in the target project.

LLM-visible tools

workflow_next

A semantic read-only workflow router. It does not mutate project source files, Git state, task status or configuration; it may update runtime cache and telemetry artifacts under .workflow/.runtime.

Main fields returned:

• current task state
• recommended next action
• blockers / warnings
• evidenceRefs
• omitted
• tokenBudget
• adaptiveControl
• meta

Default request:

{ "includeContext": "lite" }

Request more detail only when needed:

{ "includeContext": "task" }

workflow_run

A controlled workflow actuator.

Supported actions:

create_from_grill
create_child
start_checked
checkpoint
finish_run
archive
batch

Rules:

• Defaults to mode: "dry_run".
• Task mutations require mode: "execute".
• start_checked and finish_run run deterministic preflight checks first.
• batch runs multiple actions in order and returns transaction artifacts plus rollback hints.

Pi commands

/workflow-init --dry-run
/workflow-init --execute
/workflow-init-spec --profile generic --dry-run
/workflow-init-spec --profile unity --dry-run
/workflow-init-spec --execute --plan <plan-id>
/workflow-prd-confirm --task <task-id> --message "confirmed" --execute

Notes:

• /workflow-init creates the base .workflow structure.
• /workflow-init-spec creates or executes a spec initialization plan.
• /workflow-prd-confirm records the PRD final confirmation gate through Pi UI, so the LLM does not need to relay human confirmation text.

Workflow capabilities

PRD / Manifest / Preflight

The engine supports:

• reading .workflow/tasks/<task>/prd.md
• extracting the PRD kernel
• detecting TODO / TBD markers
• detecting blocking open questions
• detecting the final confirmation gate
• checking Acceptance Criteria, Validation Plan and Definition of Done
• validating implement.jsonl and check.jsonl
• running checkpoints such as git diff --check

Context budget and cache

workflow_next returns lite context by default and reduces repeated context cost through:

• evidenceRefs
• omitted
• tokenBudget
• meta
• fingerprint-backed workflow cache

Adaptive Control

workflow_next returns adaptiveControl to guide the next strategy:

deterministic_preflight | subagent_brief | ask_user | none

Recommended agent types:

research | implement | check | finish | user | none

It emits compact briefs only and does not add extra LLM-visible subagent tools.

Telemetry

Tool calls write schema-versioned telemetry JSONL under:

.workflow/.runtime/telemetry/

Telemetry records token estimates, cache hits, blockers/warnings, artifact refs, transactions and elapsed time.

Compaction

The extension registers a session_before_compact hook. When workflow state exists in a Pi session, it emits a workflow-aware summary that preserves the active task, next action, artifact refs, file operations and recent conversation signals.

Initialization boundaries

Target projects use this structure:

.workflow/
  config.json
  tasks/
  spec/
  .runtime/

Conventions:

• .workflow/spec/** stores durable project knowledge.
• .workflow/tasks/** stores task data.
• .workflow/.runtime/** stores cache, telemetry, checkpoints, transactions and other runtime artifacts.
• Initialization does not copy the engine and does not create legacy wrappers.

Profiles

generic

Generic project spec skeleton.

unity

Generic Unity project spec skeleton.

Generated files:

.workflow/spec/modules/unity-project.md
.workflow/spec/modules/unity-assets.md

The Unity profile does not assume a specific resource system by default. Resource-system candidates are recorded only when project facts are detected.

Local development

npm test
npm run smoke:unity-scanner

Historical task replay:

npm run replay:history -- <project-root> --variants as_is,planning,in_progress

The replay tool copies historical tasks into temporary workspaces and does not mutate the source project.

License

This project is released under the MIT License.

You may use, copy, modify, merge, publish, distribute, sublicense and sell copies of the software, provided that the copyright and license notice are included in copies or substantial portions of the software.

Current limits

• No automatic Git commit / push.
• No legacy Python workflow wrapper.
• No extra LLM-visible subagent tools.
• Rollback hints are advisory and are not executed automatically.