PSI - Plan Spec Implement

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

1. Ephemeral planning - Plans stored in ~/​.dot-agent/ (not committed)
2. Documentation-first - Specs applied to project docs/​READMEs/​AGENTS.md
3. Test-first implementation - Tests for docs/​user journeys before code
4. Design/​review embedded - Design and review integrated into Plan/​Spec phases
5. 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