mcpField
P
psi

psi

github.com/siviter-xyzAgent workflows22141 installsUpdated 32w ago
Repository

About psi

psi is an opt-in skill for planning, specifying, and implementing software changes with documentation kept current. Its independent phases combine review and design with test-first implementation.

Key features

  1. 01Independent plan, spec, and implement phases
  2. 02Plans and research stored outside the repository
  3. 03Specs applied to project documentation
  4. 04Test-first implementation and CI checks
  5. 05Review and design within planning phases

Use cases

  1. 01Planning a change before implementation
  2. 02Documenting APIs, architecture, or user journeys
  3. 03Implementing changes with tests and documentation updates

Install

Copy the command and run it in a terminal.

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

After installing, type/psiin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

LICENSE
README.md
references/
docs-structure.md
file-paths.md
implement-phase.md
plan-phase.md
research-management.md
review-protocol.md
spec-phase.md
scripts/
get-plan-path.js
get-research-path.js
show-plan-location.js

Details

From the project README

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

Comments

Markdown supported