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.
- Installs
- 141
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/siviter-xyz/dot-agent --skill psi- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads psi automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
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.mdfile
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/reviewreferences/spec-phase.md- Spec generation and applicationreferences/implement-phase.md- Test-first implementationreferences/review-protocol.md- Reviewing plans/specs/designreferences/research-management.md- Research file handlingreferences/docs-structure.md- Documentation organization rulesreferences/file-paths.md- Storage paths and conventions
FAQ
What does the psi 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.
How do I install psi?
Run npx skills add https://github.com/siviter-xyz/dot-agent --skill psi in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/psi/ (personal) or .claude/skills/psi/ (project).
Which AI agents can use psi?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is psi safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains psi?
It is published by siviter-xyz in siviter-xyz/dot-agent. It has 141 recorded installs.
More from siviter-xyz/dot-agent
create-skill
siviter-xyz/dot-agent
Guide for creating effective skills following best practices. Use when creating or updating skills that extend agent capabilities.
cursor-best-practices
siviter-xyz/dot-agent
Best practices for working with Cursor. Use when learning how to effectively use Cursor features or optimizing your workflow.
software-engineer
siviter-xyz/dot-agent
Core software engineering principles for code style, documentation, and development workflow. Applies when editing code, working in software repositories, or performing software development tasks.
backend-engineer
siviter-xyz/dot-agent
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.
frontend-engineer
siviter-xyz/dot-agent
Open the skill to read its SKILL.md instructions.
Popular code quality & workflow skills
grill-me
mattpocock/skills
A relentless interview to sharpen a plan or design.
improve-codebase-architecture
mattpocock/skills
Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
handoff
mattpocock/skills
Compact the current conversation into a handoff document for another agent to pick up.
domain-modeling
mattpocock/skills
Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.
codebase-design
mattpocock/skills
Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.
diagnosing-bugs
mattpocock/skills
Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.