yi-workflow

Production workflow skills for Pi coding agent. The package provides deterministic planning, wave-based execution, code review, debugging, TDD, and verification workflows with strict actor boundaries.

Design

• Simple tasks: the main agent handles small, low-risk work directly.
• Complex tasks: use /skill:to-plan to create a canonical plan, then /skill:execute-plan to execute it.
• Main-agent orchestration: the main agent dispatches subagents, validates outputs, and emits final summaries; it must not inspect product source during planning.
• Canonical plan artifacts: successful plans are written by Planner only under ~/.yi-workflow/docs/plans/ as pure YAML files named plan-YYYYMMDD-HHMMSS-{slug}.md.
• Runtime guard: the Pi extension enforces deterministic planning boundaries, blocks unsafe main-agent operations, and validates fast-path subagent transport output before Planner dispatch.
• Wave execution: approved plans always run through isolated wave worktrees, verification gates, and controlled merge handling; there is no implicit direct execution fallback for /skill:execute-plan.

Quick Start

# Simple task — main agent can do it directly
You: "Remove the obsolete line from README"
Pi: [read → edit → verify → done]

# Complex task — create a canonical plan first
You: /skill:to-plan implement user authentication
Pi: [to-plan] → Explorer/Researcher/Debugger as needed → Planner → ~/.yi-workflow/docs/plans/plan-*.md

# Execute the approved plan
You: /skill:execute-plan <plan path>
Pi: [execute-plan] → wave worktrees → verification → controlled merge

Architecture

to-plan

/skill:to-plan
     ↓
Main Agent (orchestration only)
     ↓
Explorer / Researcher / Debugger (evidence gathering)
     ↓
Planner (synthesis + canonical artifact writer)
     ↓
~/.yi-workflow/docs/plans/plan-YYYYMMDD-HHMMSS-{slug}.md
     ↓
Final YAML summary starting with status:

Important planning contracts:

• The final user-visible summary is raw YAML only and starts with status:.
• Planner must return nextAction directly:
  • status: planned → nextAction: approve-plan
  • status: blocked → nextAction: revise-plan
• The main agent must not patch missing Planner metadata or normalize Planner's planPath.
• For bounded reference-cleanup plans, Explorer is the product-source evidence actor. After non-empty Explorer evidence, Planner must use that evidence only and express uncertainty as risks, verification criteria, sequencing, or decision points.
• The runtime guard may mechanically canonicalize exactly one schema-valid reference-cleanup JSON payload from Pi tool-result transport; ambiguous, malformed, or schema-invalid payloads block the fast path.

execute-plan

/skill:execute-plan
     ↓
Read approved canonical plan
     ↓
Preflight — porcelain check, delegate worktree creation to executer
     ↓
Wave 1 worktree ── executer(s) ── reviewer ── verifier
     ↓
Wave 2 worktree ── executer(s) ── reviewer ── verifier
     ↓
Final verification
     ↓
Controlled merge / conflict handling
     ↓
Cleanup (delegated to executer)

Important execution contracts:

• Every wave must run in a run-owned wave worktree; there is no direct main-tree fallback for approved plans.
• The first worktree-creation action must be dispatching executer with mode: create-wave-worktree, not a main-agent git worktree add probe.
• baseRef must be a branch name (e.g. main), not a commit hash — branch-based worktrees avoid detached HEAD and simplify merge/cleanup.
• Task executers must be dispatched into the shared wave worktree, not with Agent isolation: "worktree".
• Wave-level review and verification must pass before committing; final verification must pass before merging.
• All destructive filesystem operations (rm, rm -rf, git clean -fd) must be delegated to executer subagents.
• The main agent's Read tool can read plan/state/config files; shell operations against the same paths are guard-blocked.
• Final reports are raw YAML starting with status: and include protocolDeviations for any guard-blocked main-agent operations.
• Verification scope must be qualified: do not claim "entire repository" clean unless all artifact classes (tracked source, ignored/cache, untracked, binary) are covered.

Wave-Based Execution

| Concept | Description | |---|---| | Wave | A group of tasks from the approved plan. | | Concurrent wave | Tasks have no dependencies and no file overlap, so multiple executers may run in parallel. | | Sequential wave | Tasks have dependencies or file overlap, so one executer runs them in order. | | Worktree | Each wave runs in an isolated run-owned Git worktree, recorded in execution state before task dispatch; approved plan execution must not fall back to direct main-working-tree edits. | | Verification gate | Every wave and the final merged result must be verified before completion. | | Dirty tree gate | Any non-empty git status --porcelain, including untracked ?? files, is a user-intervention point before execution continues. | | Protocol deviations | Final execution reports are raw YAML and include protocolDeviations for guard blocks or state-machine deviations. |

Skills

| Skill | Purpose | |---|---| | /skill:to-plan | Create a canonical wave-based implementation plan. | | /skill:execute-plan | Execute an approved canonical plan through isolated wave worktrees. | | /skill:review-diff | Review an existing diff, branch, commit, PR, or worktree. | | /skill:verification | Verify an implementation against explicit criteria. | | /skill:tdd | Run a RED/GREEN/REFACTOR workflow. | | /skill:systematic-debugging | Diagnose failures through reproduction, evidence, root cause, fix, and verification. |

Subagents

| Subagent | Purpose | |---|---| | explorer | Read-only repository exploration and dependency/file-scope evidence. | | planner | Plan synthesis, wave classification, and canonical plan artifact writing. | | executer | Task implementation with TDD/review/debug/verification support. | | reviewer | Read-only code review. | | verifier | Wave-level and final verification. | | debugger | Root-cause analysis and merge-conflict resolution. | | researcher | External research when planning requires non-repository facts. |

Configuration

Add the package's Pi extension and skills directory to package.json:

{
  "pi": {
    "extensions": ["./dist/src/guard/extension.js"],
    "skills": ["./src/skills"],
    "config": {
      "planPath": ".yi-workflow/plans",
      "statePath": ".yi-workflow/state",
      "autoCleanup": true,
      "autoMerge": true,
      "maxConcurrent": 4
    }
  }
}

Runtime paths:

• Canonical global plans: ~/.yi-workflow/docs/plans/
• Project execution state: .yi-workflow/state/
• Project execution worktrees: .yi-workflow/worktrees/

Installation

npm install -g @haoyiyin/workflow

Development

npm run build          # Compile TypeScript
npm run dev            # Watch mode
npm test               # Run tests
npm run test:coverage  # Coverage report
npm run sync-to-pi     # Deploy local build/skills/agents to ~/.pi/agent/

License

MIT