Agent skill

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.

View SKILL.md on GitHub Repository
Stars 8
Forks 0

Install this agent skill to your Project

npx add-skill https://github.com/siviter-xyz/dot-agent/tree/main/skills/psi

SKILL.md

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

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

siviter-xyz/dot-agent

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.

8 0
Explore
siviter-xyz/dot-agent

debugging

Root cause analysis and debugging protocols. Use when encountering errors, test failures, unexpected behavior, stack traces, or when code behaves differently than expected.

8 0
Explore
siviter-xyz/dot-agent

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.

8 0
Explore
siviter-xyz/dot-agent

cursor-best-practices

Best practices for working with Cursor. Use when learning how to effectively use Cursor features or optimizing your workflow.

8 0
Explore
siviter-xyz/dot-agent

create-skill

Guide for creating effective skills following best practices. Use when creating or updating skills that extend agent capabilities.

8 0
Explore
siviter-xyz/dot-agent

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.

8 0
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results