Psi

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

PSI - Plan Spec Implement

A streamlined workflow for structured development that emphasizes documentation-first specifications and test-first implementation.

Overview

PSI (Plan-Spec-Implement) provides a methodology for managing complex development work through three independent but coordinated phases. Unlike rigid phase-gated workflows, PSI allows you to start with any phase while ensuring documentation stays current throughout.

Methodology

Core Philosophy

Documentation is the source of truth. Specifications live in your project's documentation (docs/, READMEs, AGENTS.md), not in ephemeral planning files. This ensures your team always has access to current specifications and behavior definitions.

Three Independent Phases

1. Plan - Generate detailed implementation plans (stored ephemerally) 2. Spec - Create and apply specifications to project documentation 3. Implement - Test-first implementation that keeps docs current

Each phase can work independently, but all must ensure documentation is up-to-date.

Relationship to OPSX

PSI was inspired by OpenSpec's experimental workflow (OPSX) but takes a different approach:

• OPSX: Artifact-based workflow with dependencies, stored in project
• PSI: Documentation-first workflow with ephemeral plans, specs in project docs

PSI focuses on making project documentation the source of truth, while OPSX uses separate artifact files. Both approaches have merit - PSI is optimized for teams that want specifications integrated into their existing documentation structure.

Key Features

• Ephemeral planning - Plans stored in ~/.dot-agent/ (not committed to repo)
• Documentation-first specs - Specifications live in project docs/READMEs
• Test-first implementation - Tests for docs/user journeys before code
• Embedded design/review - Design and review integrated into Plan/Spec phases
• Research management - Research files with detection patterns
• Phase independence - Start with any phase, all keep docs current

Usage

The PSI skill activates when you:

• Start new features or major changes
• Need architectural planning
• Want structured documentation
• Require test-first development workflows

See the skill documentation for detailed protocols on each phase.

Documentation Structure

PSI organizes documentation across:

• README.md files - Project/package/module documentation (aim for < 1000 lines)
• AGENTS.md files - Custom behavior/commands (< 200 lines, inline)
• docs/ folder - Architecture, roadmap, tech choices, user journeys, design

All specifications become part of your project's living documentation.

Documentation Structure

Organization rules for project documentation.

README.md Files

Placement

• Root level: Project overview, architecture summary, getting started
• Package level: Package-specific documentation
• Module level: Module-specific documentation
• Inline next to code: Only if relevant and useful (not for adding's sake)

Length Guidelines

• Aim for < 1000 lines (not a hard rule)
• Can be longer if comprehensive documentation is needed
• Focus on usefulness over arbitrary limits
• Break into sections for readability

Content

• What the code does
• How to use it
• Architecture and design decisions
• Examples and patterns
• Setup and configuration

AGENTS.md Files

Placement

• Root level: Global project behavior
• Package level: Package-specific behavior
• Module level: Module-specific behavior
• Next to code: File-specific behavior (if relevant)

Length Limit

• < 200 lines (hard limit)
• Must be concise and focused
• Only for custom behavior/commands/workflows
• Not for general documentation

Content

• Custom commands or workflows
• Agent-specific instructions
• Development workflow patterns
• Testing patterns specific to area
• Concise, actionable information only

When NOT to Use

• General documentation → Use README.md
• Large documentation → Use docs/ folder
• Reusable knowledge → Use skills

docs/ Folder Organization

Core Files

• docs/architecture.md - Overall system architecture
• docs/roadmap.md - Project roadmap (keep relevant, < 1000 lines)
• docs/tech-choices.md - Technology decisions and rationale

Subdirectories

• docs/setup/<any-custom-setup-guide>.md - Setup and installation guides
• docs/user-journeys/<feature-group>/<short-description>.md - User journey documentation
• Frontmatter required: name, description, status (live/beta/candidate/deprecated)
• docs/design/ - Design artifacts (if needed in repo)

User Journey Format

---
name: User Registration
description: Complete user registration flow with email verification
status: live
---

## User Journey: Registration

[Detailed journey description]

## E2E Test Requirements
- Test complete flow
- Test email delivery

Documentation Principles

1. READMEs are living docs - Update as code evolves 2. AGENTS.md is for behavior - Custom workflows only, keep concise 3. docs/ is for structure - Architecture, journeys, design 4. Inline when relevant - README next to code only if useful 5. Don't add for adding's sake - Every doc should serve a purpose

Documentation Updates

All phases must keep docs current:

• Plan phase: Update if plan affects existing docs
• Spec phase: Apply specs to docs
• Implement phase: Update as code evolves

Consistency

• Keep docs synchronized with code
• Update related docs when one changes
• Ensure specs in docs match implementation
• Verify user journey status matches reality

File Paths and Conventions

Storage paths and naming conventions for PSI workflow.

Ephemeral Storage

Plan Files

Path: ~/.dot-agent/repo/YYYY-MM-work-name.plan.md

Research Files

Path: ~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md

Working Directory Detection

• Current repository root (if single repo)
• Current folder (if folder of repos)
• Detected automatically by agent

Naming Convention

Format

YYYY-MM-work-name

Examples

• 2025-01-user-auth - User authentication feature
• 2025-01-api-refactor - API refactoring
• 2025-01-database-migration - Database migration
• 2025-02-frontend-redesign - Frontend redesign

Rules

• Use kebab-case for work-name
• Include year and month for organization
• Use descriptive, concise names
• Avoid special characters

Path Generation

Plan Path

~/.dot-agent/repo/YYYY-MM-work-name.plan.md

Research Path

~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md

Repository Detection

• Check if current directory is git repo root
• If not, check parent directories
• Use repo name or folder name in path
• Handle nested repos appropriately

Helper Scripts

Scripts in scripts/ directory:

get-plan-path.js (or .sh)

• Generates plan file path
• Takes work name as input
• Returns full path
• Handles date formatting

get-research-path.js (or .sh)

• Generates research file path
• Takes work name as input
• Returns full path
• Handles date formatting

show-plan-location.js (or .sh)

• Displays plan location to user
• Formats message clearly
• Shows full path
• Provides instructions for accessing

Path Examples

Single Repository

~/.dot-agent/my-project/2025-01-user-auth.plan.md
~/.dot-agent/working-dir/my-project/2025-01-user-auth.research.md

Folder of Repos

~/.dot-agent/dev-folder/2025-01-user-auth.plan.md
~/.dot-agent/working-dir/dev-folder/2025-01-user-auth.research.md

File Management

Creating Files

• Create directory structure if needed
• Use absolute paths for reliability
• Handle path creation errors gracefully

Accessing Files

• Load plan file when referenced
• Load research file on detection patterns
• Handle missing files appropriately

Cleanup

• Plans are ephemeral (not committed)
• User can manually clean up old plans
• Research files can be archived or deleted

Platform Considerations

Windows

• Use %USERPROFILE% or ~ expansion
• Handle path separators correctly
• Test path generation on Windows

Unix/Linux/Mac

• Use ~ expansion
• Handle permissions appropriately
• Test path generation on Unix systems

Implement Phase Protocol

Test-first implementation that keeps documentation current.

Phase Independence

Implement phase can work independently:

• Doesn't require plan file to exist
• Can reference specs from project docs
• Must keep documentation up-to-date

Test-First Approach

1. Write tests for docs/user journeys first

• E2E tests for user journeys
• Integration tests for API specs
• Unit tests for component interfaces

2. Then implement code

• Follow plan if exists
• Reference specs from docs
• Make tests pass

3. Update documentation as code evolves

• Keep docs current with implementation
• Update README.md if behavior changes
• Update AGENTS.md if workflows change

Implementation Process

1. Reference Specifications

• Load specs from project docs (docs/, README.md files)
• Reference plan file if exists (~/.dot-agent/repo/YYYY-MM-work-name.plan.md)
• Understand requirements from documentation

2. Write Tests First

For User Journeys:

• E2E tests that verify complete user flows
• Test happy paths and edge cases
• Reference docs/user-journeys/ files

For API Specs:

• Integration tests for API endpoints
• Test request/response formats
• Reference API schemas in docs

For Components:

• Unit tests for component interfaces
• Test props, state, events
• Reference component specs in docs

3. Implement Code

• Follow plan steps if plan exists
• Make tests pass
• Follow existing codebase patterns
• Reference specs from docs for accuracy

4. CI Verification

Before considering change complete:

• Run CI checks (types, tests, lint)
• Prefer single CI command if available
• If checks fail, stop and report
• Only proceed when all checks pass

5. Atomic Commits

After CI passes:

• Stage atomic changes (code + tests together)
• Suggest semantic commit message
• Confirm with user before committing
• Continue to next atomic change

4. Update Documentation

As implementation evolves, update:

docs/ Files:

• Update architecture.md if architecture changes
• Update user-journeys/ status if feature status changes
• Update design/ if design artifacts change

README.md Files:

• Update if behavior or API changes
• Update if setup/usage changes
• Keep inline with code if relevant

AGENTS.md Files:

• Update if custom workflows change
• Add new workflows if needed
• Keep < 200 lines

Documentation Maintenance

During Implementation

• Update docs when you discover discrepancies
• Update README.md when behavior differs from docs
• Update AGENTS.md when workflows change
• Keep all documentation synchronized

After Implementation

• Verify all docs are current
• Update user journey status if needed
• Archive or update plan file if complete
• Ensure all specs in docs match implementation

Stop and Ask

Stop and ask user before:

• Adding type ignores (@ts-ignore, # type: ignore, etc.)
• Adding suppressions (ESLint disable, pylint disable, etc.)
• Using any type or similar type escapes
• Uncertain how to proceed

Backward Compatibility

• Only consider backward compatibility for public-facing interfaces (APIs, libraries)
• For greenfield/internal refactoring, E2E tests serve as confirmation gate
• Unless explicitly directed otherwise

Best Practices

1. Tests as documentation - Tests should reflect specs in docs 2. Docs as source of truth - Implementation should match docs 3. Update incrementally - Don't wait until end to update docs 4. Verify consistency - Check docs match code regularly 5. Keep AGENTS.md focused - Only custom behavior, < 200 lines 6. CI verification - Always verify CI passes before committing 7. Atomic commits - Group related changes together with tests

Working Without Plan/Spec Files

If starting implement phase without plan or spec files:

• Load specs from project docs
• Understand requirements from README.md files
• Reference existing patterns in codebase
• Still must keep docs up-to-date as you implement

Plan Phase Protocol

Generate detailed implementation plans with embedded design considerations and review.

Storage

Plan file: ~/.dot-agent/repo/YYYY-MM-work-name.plan.md Research file: ~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md

Working directory is the current repo or folder of repos open to the agent.

Plan Generation Process

1. Analyze codebase - Understand current structure, patterns, dependencies 2. Ask clarifying questions - Gather requirements, constraints, preferences 3. Research if needed - Investigate similar patterns, approaches, technologies

• Store findings in research file
• Organize by topic with sources and rationale

4. Embed design considerations - Include UI/UX, architecture, component design in plan 5. Generate detailed plan - File paths, code references, implementation steps, dependencies 6. Review plan - Embedded review before proceeding

• Technical feasibility
• Alignment with existing architecture
• Completeness

7. Store plan - Save to ephemeral location 8. Inform user - Clearly state plan location 9. Allow refinement - Iterative back-and-forth to improve plan

Plan Format

Similar to Cursor/Claude plan mode:

# Work Name - Implementation Plan

## Overview
Brief description of the work.

## Research Findings
(If research was conducted)
- Finding 1
- Finding 2

## Design Considerations
- UI/UX approach
- Architecture decisions
- Component structure

## Implementation Steps

### Step 1: Setup
- Files to create: `path/to/file.ts`
- Dependencies: package1, package2
- Changes needed: ...

### Step 2: Core Implementation
...

Design Integration

Design considerations are embedded in the plan phase:

• UI/UX approach for frontend changes
• Architecture patterns for backend changes
• Component/module structure
• Data flow and state management
• Integration points

If design artifacts are needed in the repo, they can go to docs/design/ after spec phase.

Review Integration

Before proceeding to spec phase:

• Review plan for technical feasibility
• Check alignment with existing codebase patterns
• Verify completeness of approach
• Identify potential issues or edge cases

Documentation Updates

If plan changes affect existing documentation:

• Update relevant README.md files
• Update docs/ files if architecture changes
• Note changes in plan file

Research Management

Research findings stored separately in research file:

• Organized by topic
• Sources and references
• Decision rationale
• Open questions

Research can be loaded/refined using detection patterns:

• "looking at your research" → Load research file
• "refine your research" → Update research file, narrow focus

Research Management

Handling research files and detection patterns.

Research Storage

Location: ~/.dot-agent/working-dir/repo/YYYY-MM-work-name.research.md

Working directory is the current repo or folder of repos open to the agent.

Research File Format

# Research: Work Name

## Research Questions
- [ ] Question 1
- [ ] Question 2

## Findings

### Topic 1
- Finding 1 with source
- Finding 2 with source

### Topic 2
- Finding 1 with source

## Decisions
- Decision 1: Rationale based on findings
- Decision 2: Rationale based on findings

## References
- Source 1: URL or citation
- Source 2: URL or citation

## Open Questions
- Question that needs more research
- Question to clarify with user

Detection Patterns

The skill detects phrases to manage research:

"looking at your research"

Action: Load research file into context Use case: User wants to reference previous research findings Behavior: Read research file and make findings available in context

"refine your research"

Action: Update research file, narrow focus Use case: User wants to improve or focus research Behavior:

• Load existing research
• Update with new findings
• Narrow scope based on user direction
• Remove irrelevant findings

"update research"

Action: Modify research file with new findings Use case: New information discovered Behavior: Add new findings to research file, update decisions if needed

Research Generation

During plan phase, research may be generated: 1. Identify research questions 2. Investigate topics 3. Organize findings by topic 4. Document sources and references 5. Record decisions and rationale 6. Note open questions

Research Usage

Research findings inform:

• Plan generation (technical approach, patterns)
• Spec generation (technology choices, architecture)
• Design considerations (UI/UX patterns, component approaches)

Narrowing Working Memory

When "refine your research" is detected:

• Focus on specific topics
• Remove tangential findings
• Deepen relevant areas
• Update decisions based on refined focus
• Keep only relevant context in working memory

Best Practices

1. Organize by topic - Group related findings 2. Cite sources - Always include references 3. Record decisions - Note why choices were made 4. Keep current - Update as new information emerges 5. Focus when needed - Refine to narrow scope

Review Protocol

Reviewing plans, specs, and design before proceeding.

Review Principles

• Review before commitment - Review plans before spec phase, specs before applying to docs
• Technical feasibility - Ensure approach is technically sound
• Alignment - Check consistency with existing architecture and patterns
• Completeness - Verify all necessary aspects are covered

Plan Review

When: After plan generation, before spec phase

Review Criteria:

• Technical feasibility of approach
• Alignment with existing codebase patterns
• Completeness of implementation steps
• Identification of potential issues or edge cases
• Design considerations adequacy

Review Process: 1. Analyze plan for technical soundness 2. Check alignment with existing architecture 3. Verify all necessary steps are included 4. Identify missing considerations 5. Suggest improvements or clarifications 6. Proceed to spec phase when plan is solid

Spec Review

When: After spec generation, before applying to docs

Review Criteria:

• Completeness of specifications
• Consistency with existing documentation patterns
• Technical accuracy
• Alignment with plan (if exists)
• Design specifications adequacy

Review Process: 1. Check all relevant categories are specified 2. Verify consistency with existing docs 3. Ensure technical accuracy 4. Review design specifications 5. Check alignment with plan 6. Apply to docs when specs are agreed

Design Review

When: Embedded in plan and spec phases

Review Considerations:

• UI/UX consistency
• Component design coherence
• Architecture soundness
• Integration points
• User experience flow

Design Artifacts:

• Can be stored in docs/design/ if needed in repo
• Should align with specs in documentation
• Should be referenced in relevant README.md files

Review Integration

Reviews are embedded in phases, not separate:

• Plan phase: Review plan before proceeding
• Spec phase: Review specs before applying to docs
• Design: Reviewed as part of plan/spec phases

This keeps the workflow streamlined while ensuring quality.

Review Checklist

Plan Review Checklist

• [ ] Technically feasible
• [ ] Aligned with existing architecture
• [ ] Complete implementation steps
• [ ] Design considerations included
• [ ] Edge cases identified
• [ ] Dependencies clear

Spec Review Checklist

• [ ] All relevant categories specified
• [ ] Consistent with existing docs
• [ ] Technically accurate
• [ ] Design specifications complete
• [ ] Aligned with plan (if exists)
• [ ] Ready to apply to docs

Iterative Refinement

Both plan and spec phases allow iterative refinement:

• Ask clarifying questions
• Refine based on feedback
• Update research if needed
• Improve design considerations
• Continue until ready to proceed

Spec Phase Protocol

Generate specifications and apply them to project documentation.

Spec Categories

Generate specs based on change type:

Always Relevant

• Package/project structure - Directory organization, module boundaries
• Tech choices and rationale - Technology decisions with reasoning

API Changes

• API schemas - OpenAPI, GraphQL, REST contracts
• Interfaces/TypeScript types - Type definitions
• DTO models - Data transfer objects

Backend Changes

• Database models/schemas - Entity definitions, relationships
• Config models - Configuration structures
• Environment variables - Per-package env var definitions

Frontend Changes

• Component interfaces - Props, state, events
• User journeys - User flows with E2E test requirements

Large Features

• Architecture diagrams - System design, data flow
• User journeys - Complete user flows

Spec Generation Process

1. Analyze plan (if exists) or requirements 2. Embed design considerations - UI/UX, component design, architecture 3. Generate specs for relevant categories 4. Present to user for review 5. Review specs - Embedded review before applying

• Completeness
• Consistency with existing patterns
• Technical accuracy

6. Iterate until agreed 7. Apply to documentation - Update/create project docs

Design Integration

Design considerations embedded in spec phase:

• UI/UX specifications
• Component design and structure
• Visual hierarchy and interactions
• Design system usage

Design artifacts can be stored in docs/design/ if needed in repo.

Review Integration

Before applying specs to docs:

• Review for completeness
• Check consistency with existing documentation
• Verify technical accuracy
• Ensure alignment with plan (if exists)

Spec Application

Once specs are agreed, apply to:

docs/ Folder

• docs/architecture.md - Overall architecture (update or create)
• docs/tech-choices.md - Technology decisions (update or create)
• docs/user-journeys/<feature-group>/<short-description>.md - User journey docs
• Frontmatter: name, description, status (live/beta/candidate/deprecated)
• docs/design/ - Design artifacts if needed
• docs/setup/<guide>.md - Setup guides if needed

README.md Files

• Root level: Project overview, architecture summary
• Package level: Package-specific specs
• Module level: Module-specific specs
• Inline next to code: Only if relevant and useful
• Length: Aim for < 1000 lines, but can be longer if needed

AGENTS.md Files

• Root/packages/modules/code level: Custom behavior/commands
• Length: < 200 lines (hard limit)
• Only for custom workflows, not general documentation

Spec Format Examples

API Schema

## API Endpoints

### POST /api/users
**Request Body:**

{ "name": "string", "email": "string" }

**Response:**

{ "id": "string", "name": "string", "email": "string" }

User Journey

---
name: User Registration
description: Complete user registration flow with email verification
status: live
---

## User Journey: Registration

1. User visits registration page
2. Fills registration form
3. Submits form
4. Receives verification email
5. Clicks verification link
6. Account activated

**E2E Test Requirements:**
- Test complete flow
- Test email delivery
- Test verification link

Documentation Updates

When applying specs:

• Update existing docs if specs change
• Create new docs if needed
• Ensure all related docs stay consistent
• Update README.md files at appropriate levels
• Create/update AGENTS.md only for custom behavior