PSI - Plan Spec Implement
Structured workflow for planning, specifying, and implementing changes with documentation-first approach.
When to Use
Only use when:
Explicitly directed by the user Mentioned in project AGENTS.md file
Do not use automatically - this is an opt-in workflow, not a default.
Core Workflow
Plan → Spec → Implement
Phases are independent - you can start with any phase, but all must ensure documentation stays up-to-date.
Key Principles Ephemeral planning - Plans stored in ~/.dot-agent/ (not committed) Documentation-first - Specs applied to project docs/READMEs/AGENTS.md Test-first implementation - Tests for docs/user journeys before code Design/review embedded - Design and review integrated into Plan/Spec phases Phase independence - Each phase can work standalone, all update docs Phase Overview Plan Phase Generates detailed plans in ~/.dot-agent/repo/YYYY-MM-work-name.plan.md Research stored in ~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md Embeds design considerations Includes review before proceeding Spec Phase Generates specs for: API schemas, interfaces, DTOs, database models, config, env vars, architecture, user journeys, package structure, tech choices Embeds design considerations Reviews specs before applying Applies to: docs/, README.md files, AGENTS.md files Implement Phase Test-first: tests for docs/user journeys before code CI verification: verify types, tests, lint pass before committing Atomic commits: group related changes with tests Updates docs, README.md, AGENTS.md as code evolves Can work independently if specs exist in docs Research Management
Detects phrases like:
"looking at your research" → Loads research file "refine your research" → Updates research file, narrows focus Documentation Structure README.md: Aim for < 1000 lines (not hard rule), can be longer if needed AGENTS.md: < 200 lines, inline at root/packages/modules/code level docs/: Architecture, roadmap, tech-choices, setup/, user-journeys/, design/ References
For detailed protocols, see:
references/plan-phase.md - Plan generation with embedded design/review references/spec-phase.md - Spec generation and application references/implement-phase.md - Test-first implementation references/review-protocol.md - Reviewing plans/specs/design references/research-management.md - Research file handling references/docs-structure.md - Documentation organization rules references/file-paths.md - Storage paths and conventions