pi-compound-engineering

Pi Compound Engineering

A Pi-native Compound Engineering package for iterative development workflows in Pi.

Install

Local development install

pi install /absolute/path/to/pi-compound-engineering

Project-local install

pi install /absolute/path/to/pi-compound-engineering -l

Published install

pi install npm:pi-compound-engineering

Phase 1 commands

• ce-help — explain which workflow step to use
• ce-status — inspect repo-local workflow state
• ce-next — get a recommendation for the next workflow step
• ce-worktree — create and manage git worktrees for isolated feature development
• ce-brainstorm — create requirements artifacts in docs/brainstorms/
• ce-plan — create implementation plans in docs/plans/
• ce-work — execute plan-driven work in Phase 1 mode
• ce-review — review changes with structured findings
• ce-compound — capture reusable learnings in docs/solutions/

Package shape

• skills/ — workflow semantics
• extensions/ce-core/ — runtime tools for artifact handling, questions, and subagents

Artifact conventions

This package uses repo-local workflow artifacts:

• docs/brainstorms/
• docs/plans/
• docs/solutions/
• .context/compound-engineering/

Phase 1 scope

Phase 1 intentionally ships a basic but working CE loop:

• explicit skill entry points
• repo-local artifacts as durable state
• basic ce-work and ce-review
• ce-core runtime tools for artifact handling, structured questions, and serial subagents

It does not yet include richer review autofix flows, worktree orchestration, session-history integrations, or ce-next style navigation.

Changelog

0.12.0

• Extended session_checkpoint with fail and retry operations for error recovery
• fail records error context (failed unit, error message) on a checkpoint
• retry returns a retry strategy based on error type (timeout, permission, syntax, file-not-found)
• Updated ce-work SKILL.md with error recovery workflow
• 104 tests passing

0.11.0

• Added pattern_extractor extension tool: extract recurring patterns from artifacts and categorize them
• Supports extract (keyword-based pattern detection) and categorize (group patterns by type) operations
• Updated ce-compound SKILL.md to use pattern_extractor for smarter solution generation
• 98 tests passing

0.10.0

• Added session_history extension tool: record, query, and list CE skill execution history
• History persisted in .context/compound-engineering/history/ as lightweight JSON files
• Updated ce-status and ce-next to leverage session history for smarter recommendations
• 93 tests passing

0.9.0

• Added plan_diff extension tool: compare and patch plan units for incremental plan updates
• Supports compare (detect added/removed/modified/unchanged units) and patch (apply changes) operations
• Updated ce-plan SKILL.md with incremental update workflow using plan_diff
• 88 tests passing

0.8.0

• Added brainstorm_dialog extension tool: manage multi-round brainstorm conversations with start/refine/summarize operations
• Updated ce-brainstorm SKILL.md with iterative refinement workflow using brainstorm_dialog
• Dialog state persisted in .context/compound-engineering/dialogs/
• 83 tests passing

0.7.0

• Added task_splitter extension tool: file-based dependency analysis with union-find algorithm
• Outputs parallel-safe execution groups and identifies shared file dependencies
• Updated ce-work to use task_splitter for intelligent parallel vs serial execution decisions
• 75 tests passing

0.6.0

• Added session_checkpoint extension tool: save, load, and list plan execution checkpoints for resume-from-checkpoint behavior
• Updated ce-work to use session_checkpoint for automatic resume on interrupted plan execution
• Checkpoints stored in .context/compound-engineering/checkpoints/ as lightweight JSON files
• 69 tests passing

0.5.0

• Added parallel_subagent extension tool: run multiple independent skill-based tasks concurrently with Promise.allSettled
• Graceful failure handling: reports which tasks succeeded and which failed
• Updated ce-work to recommend parallel execution for independent implementation units
• 63 tests passing

0.4.0

• Added review_router extension tool: analyzes diff metadata (file types, change size, paths) and recommends reviewer personas
• Updated ce-review skill to use review_router for automatic reviewer routing
• Added autofix loop guidance: autofixable findings are automatically applied and re-reviewed (max 3 iterations)
• Updated findings-schema.md with autofix tracking fields
• Updated reviewer-selection.md with richer persona definitions and review_router integration
• Updated handoff.md with autofix loop support
• 59 tests passing

0.3.0

• Added worktree_manager extension tool: git worktree lifecycle (create, detect, merge, cleanup) with dependency injection
• Added ce-worktree skill: standalone worktree management using worktree_manager
• Updated ce-work to detect and recommend worktree isolation
• 53 tests passing

0.2.0

• Added workflow_state extension tool: scans artifact directories and returns structured workflow state
• Added ce-next skill: uses workflow_state to recommend the single best next skill
• Updated ce-status to reference workflow_state tool
• 46 tests passing

0.1.2

• Added GitHub Actions CI/CD: test.yml (push/PR to main) and publish.yml (tag-triggered npm publish)
• Fixed npm publish authentication: added setup-node with registry-url and permissions: contents: read
• Added workflow tests to package-structure test suite
• Added CI/CD documentation and release process to README
• First full CE demo: brainstorm → plan → work → review → compound producing real artifacts
• 41 tests passing

0.1.1

• Added references/ directories to ce-help and ce-status for structural consistency
• Fixed artifact_helper run-type ensureDir to create the parent directory, not the run path itself
• Cleaned up index.ts exports to only expose public API functions
• Added bun.lock to version control
• Strengthened test suite: subagent edge cases, run-type ensureDir, explicit exports check

0.1.0

• Initial release
• Phase 1 skills: ce-brainstorm, ce-plan, ce-work, ce-review, ce-compound, ce-help, ce-status
• ce-core extension with artifact_helper, ask_user_question, and subagent tools
• Repo-local artifact conventions
• 32 tests passing

Repository

• GitHub: https://github.com/leing2021/pi-compound-engineering
• npm: https://www.npmjs.com/package/pi-compound-engineering

Development

bun test
npm publish --dry-run

CI/CD

Test workflow

test.yml runs bun test on every push and pull request to main.

Publish workflow

publish.yml runs bun test then npm publish when a version tag (v*) is pushed.

Release process

• Bump version in package.json
• Update README.md Changelog
• Commit: git commit -m "chore: bump to x.y.z"
• Tag: git tag vx.y.z
• Push: git push origin main --tags
• GitHub Actions runs tests and publishes to npm

Required secrets

Set NPM_TOKEN in GitHub repo settings → Secrets → Actions.