Skip to content

docs: streamline agent instructions and design documentation#83

Merged
gricha merged 1 commit intomainfrom
improve-documentation
Jan 10, 2026
Merged

docs: streamline agent instructions and design documentation#83
gricha merged 1 commit intomainfrom
improve-documentation

Conversation

@gricha
Copy link
Copy Markdown
Owner

@gricha gricha commented Jan 10, 2026

Summary

This PR streamlines Perry's core documentation to improve clarity and reduce redundancy:

AGENTS.md: Refactored from 159 to 100 lines with clearer structure and validation requirements
DESIGN.md: Updated from vision document to current implementation status with concrete architecture details

Key Improvements

AGENTS.md Changes

  • Added architecture reference pointing to DESIGN.md for comprehensive specs
  • Simplified validation workflow with clear manual testing requirements
  • Streamlined task management and testing guidelines
  • Removed redundant sections while preserving critical implementation patterns

DESIGN.md Changes

  • Added implementation status checklist showing current vs planned features
  • Clarified component descriptions and data models
  • Improved API specifications with concrete oRPC examples
  • Better session management and workspace lifecycle documentation

Impact

  • For developers: Clearer onboarding and validation processes
  • For contributors: Better understanding of current architecture vs future plans
  • For maintenance: Reduced documentation drift between files

The documentation now provides a clearer path from high-level design (DESIGN.md) to implementation guidelines (AGENTS.md) while eliminating redundant information.

- Refactor AGENTS.md from 159 to 100 lines with clearer structure
- Add architecture reference and validation requirements
- Simplify task management workflow and testing guidelines
- Update DESIGN.md from vision to current implementation status
- Add implementation status checklist and clearer API specs
- Improve component descriptions and session management docs
@gricha gricha merged commit eabc6bc into main Jan 10, 2026
8 checks passed
@gricha gricha deleted the improve-documentation branch January 10, 2026 23:04
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant