psi
Plan-spec-implement workflow for structured development. Only use when explicitly directed by user or when mentioned in project AGENTS.md file. Generates ephemeral plans in ~/.dot-agent/, applies specs to project docs, then implements test-first.
Best use case
psi is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Plan-spec-implement workflow for structured development. Only use when explicitly directed by user or when mentioned in project AGENTS.md file. Generates ephemeral plans in ~/.dot-agent/, applies specs to project docs, then implements test-first.
Teams using psi should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/psi/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How psi Compares
| Feature / Agent | psi | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Plan-spec-implement workflow for structured development. Only use when explicitly directed by user or when mentioned in project AGENTS.md file. Generates ephemeral plans in ~/.dot-agent/, applies specs to project docs, then implements test-first.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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
Related Skills
typescript
TypeScript standards and best practices with modern tooling. Use when working with TypeScript or TypeScript React files.
software-engineer
Core software engineering principles for code style, documentation, and development workflow. Applies when editing code, working in software repositories, or performing software development tasks.
semantic-git
Manage Git commits using conventional commit format with atomic staging. Always generate plain git commands before running them and offer to let the user run them manually.
python
Python development guidelines and best practices. Use when working with Python code.
media-processing
Media processing utilities for images, audio, and video using FFmpeg and ImageMagick. Use when working with media conversion, optimization, or batch processing tasks.
frontend-engineer
Frontend development guidelines for React/TypeScript applications. Modern patterns including Suspense, lazy loading, useSuspenseQuery, file organization with features directory, MUI v7 styling, TanStack Router, performance optimization, and TypeScript best practices. Use when creating components, pages, features, fetching data, styling, routing, or working with frontend code.
create-skill
Guide for creating effective skills following best practices. Use when creating or updating skills that extend agent capabilities.
create-agents-md
Create AGENTS.md files for project-specific inline rules. Use when adding small, project-specific instructions that should be committed in repos.
context-engineering
Master context engineering for AI agent systems. Use when designing agent architectures, debugging context failures, optimizing token usage, implementing memory systems, building multi-agent coordination, evaluating agent performance, or developing LLM-powered pipelines. Covers context fundamentals, degradation patterns, optimization techniques, compression strategies, memory architectures, multi-agent patterns, evaluation, tool design, and project development.
code-review
Code review practices emphasizing technical rigor, evidence-based claims, and verification. Use when receiving code review feedback, completing tasks requiring review, or before making completion claims.
cli-building
Build command-line interfaces with async-first design, composable commands, and proper output formatting. Use when creating CLI tools, commands, or interactive terminal applications.
backend-engineer
Build robust backend systems with modern technologies (Node.js, Python, Go, Rust), frameworks (NestJS, FastAPI, Django), databases (PostgreSQL, MongoDB, Redis), APIs (REST, GraphQL, gRPC), authentication (OAuth 2.1, JWT), testing strategies, security best practices (OWASP Top 10), performance optimization, scalability patterns (microservices, caching, sharding), DevOps practices (Docker, Kubernetes, CI/CD), and monitoring. Use when designing APIs, implementing authentication, optimizing database queries, setting up CI/CD pipelines, handling security vulnerabilities, building microservices, or developing production-ready backend systems.