pi-engineering-workflow

Personal Pi package for an agentic engineering workflow: persistent goals, evidence-guided engineering methods, OpenSpec-oriented planning, native Pi code review, and finalization prompts.

This is intended to be the "dotfiles" layer for Giuseppe's engineering agent setup. It now fully migrates the source for pi-goals, pi-review, and Skill Foundry into this package instead of depending on node_modules packages or the old @atlas.labs published packages.

What it installs

• In-repo pi-goals extension from src/extensions/goal/
  • /goal
  • goal tools such as get_goal, create_goal_from_template, queue tools, budgets, and widgets
• In-repo pi-review extension and skill/helper from src/extensions/review/ and src/skills/pi-review/
  • /review
  • run_pi_review and get_pi_review
  • pi-review skill/helper fallback
• In-repo Skill Foundry skills under src/skills/
  • engineer-methods, audits, finishers, initializers, init-maintenance, research, scaffolding, pi-utilities
• This package's workflow extension
  • /workflow status
  • /workflow install [--force]
  • /workflow start <phase-or-template> [args]
  • /workflow review [review args]
  • tools: workflow_status, install_workflow_templates, start_workflow_goal, queue_workflow_review
• Pi prompt templates in src/prompts/
• Reusable goal templates in src/goal-templates/, installable into any workspace with /workflow install

Install after publish

pi install npm:@giuseppecrj/pi-engineering-workflow

Project-local install after publish:

pi install -l npm:@giuseppecrj/pi-engineering-workflow

Install for local development

cd /Users/g/code/pi-packages/pi-engineering-workflow
npm install
pi install -l .

Restart Pi or run /reload, then:

/workflow status
/workflow install
/goal research-brief -- research this feature idea

If you previously installed standalone pi-goals, pi-review, or the Skill Foundry package, remove those package entries before loading this one; duplicate /goal, /review, or tool registrations will conflict.

One-run test without saving settings

pi -e /Users/g/code/pi-packages/pi-engineering-workflow

Core workflow

research/explore
  -> design method selection
  -> prototype when uncertainty is high
  -> OpenSpec proposal/change
  -> implementation through pi-goal
  -> tests/finalize
  -> pi-review loop
  -> OpenSpec archive
  -> improve templates/docs when friction repeats

The workflow is intentionally action-oriented rather than phase-locked. Use /workflow status at boundaries and choose the smallest next action that reduces risk.

/workflow commands

/workflow status

Shows a compact status report:

• current pi-goal objective/status
• goal queue size and next item
• pi-review state
• git status
• OpenSpec active change summary when initialized
• package/workspace goal-template counts

/workflow install [--force]

Copies packaged templates from src/goal-templates/ into the current workspace's .pi-goals/ directory.

By default, existing templates are skipped. Use --force only when you intentionally want packaged copies to overwrite workspace versions.

/workflow start <phase-or-template> [args]

Queues a /goal ... command for a common phase or explicit template.

Common phase aliases:

| Phase | Template | | --- | --- | | research | research-brief | | design | engineering-design | | prototype | prototype-decision | | propose / openspec-propose | openspec-propose | | implement / apply | openspec-apply | | verify | openspec-verify | | review | pi-review-closeout | | finalize | finalize-and-archive | | archive | openspec-archive |

Examples:

/workflow start research -- compare SQLite vs Postgres for this CLI app
/workflow start design -- add plugin API for workflow phases
/workflow start prototype -- sanity-check the state machine
/workflow start propose -- add native template installation UX
/workflow start apply --change add-native-template-installation
/workflow review --tests "npm run quality"

Development

npm install
npm run quality

npm run quality runs:

1. package-shape validation that rejects old @atlas.labs/external package dependencies
2. pi-goals slop/security probes
3. pi-review extension tests
4. TypeScript validation for pi-goals, pi-review, and workflow extensions
5. npm pack --dry-run
6. Pi offline package-load smoke test

Design notes

• This package does not auto-initialize OpenSpec in downstream workspaces. OpenSpec is project-local and should be opt-in.
• Goal templates are copied into .pi-goals/ instead of being loaded directly because pi-goals intentionally discovers workspace-local templates only.
• The workflow extension reads pi-goals and pi-review session state from their custom session-entry shapes for status display only. Mutation stays delegated to /goal, /review, and their own tools.
• Migrated source docs are kept under src/docs/pi-goals/ and src/docs/pi-review/; migrated pi-goals reusable-template examples are under src/examples/pi-goals/.