pi-crew AGENTS.md

pi-crew Development Notes

This package is a Pi extension for team orchestration.

Source of Truth

Read in this order:

1. This file (AGENTS.md) for operating rules and paths.
2. docs/HARNESS.md for the human-agent collaboration model.
3. docs/FEATURE_INTAKE.md before turning any request into work.
4. docs/product/ for current product contracts.
5. docs/architecture.md for implementation shape.
6. docs/stories/ for story packets and backlog.
7. docs/TEST_MATRIX.md for proof status.
8. docs/decisions/ for why important choices were made.

Task Loop

For every task:

1. Classify the request with docs/FEATURE_INTAKE.md.
2. Identify affected modules and risk level.
3. Choose lane: tiny, normal, or high-risk.
4. Implement the change.
5. Run validation: npm test + npm run typecheck.
6. Update docs, stories, test matrix, decisions as needed.
7. Report what changed and what was not attempted.

Rules

• Keep index.ts minimal; register functionality from src/extension/register.ts.
• Prefer small modules over large orchestrator files.
• Do not copy source from SUL-licensed projects. oh-my-openagent is concept-only inspiration.
• MIT sources such as pi-subagents and oh-my-claudecode may be adapted with attribution in NOTICE.md.
• Avoid any; use unknown plus validation for tool/config inputs.
• Avoid dynamic inline imports, EXCEPT at documented lazy-load boundaries to defer heavy runtime cost (mark with // LAZY: <reason>).
• Do not hardcode global keybindings without user configurability.
• Default execution uses child Pi workers. Keep it safe through runtime limits, depth guards, and explicit disable controls (executeWorkers=false, runtime.mode=scaffold, PI_CREW_EXECUTE_WORKERS=0, or PI_TEAMS_EXECUTE_WORKERS=0).
• Worktree cleanup must preserve dirty worktrees unless force is explicitly set.
• Management deletes must require confirm: true; referenced resources should be blocked unless force: true.
• After code changes, run npm test from pi-crew/ unless explicitly told not to.