Plan: Reorganize documentation structure and consolidate agent configs

[jeduden]

Summary

This PR adds a planning document for reorganizing the project's documentation structure. The plan outlines moving reference content out of CLAUDE.md into dedicated files and establishing a single source of truth using mdsmith's include directives to keep agent configurations in sync across multiple files.

Key Changes

• New planning document (plan/68_reorganize-docs.md) that details:

  • Moving development workflow, CLI design spec, and background material from CLAUDE.md into dedicated files
  • Creating a new DEVELOPMENT.md file to consolidate development-related sections
  • Reorganizing docs into a clearer structure: docs/design/, docs/guides/, docs/background/
  • Establishing CLAUDE.md as the primary source document with mdsmith include directives syncing AGENTS.md and copilot-instructions.md

• Structured approach with 21 implementation tasks covering:

  • File creation and reorganization
  • Content migration and rewording
  • Include directive implementation
  • Documentation link updates (both outbound from moved files and inbound from non-moved files)
  • Validation and linting

• Clear acceptance criteria (16 checkpoints) ensuring:

  • All include directives are properly implemented
  • Documentation is moved to appropriate locations
  • Build and lint checks pass
  • mdsmith validation succeeds

Implementation Details

The plan uses mdsmith's processing-instruction syntax (<?include / <?/include?>) to maintain a single source of truth while keeping multiple documentation files in sync. This approach eliminates manual duplication and ensures consistency across CLAUDE.md, AGENTS.md, and .github/copilot-instructions.md.

https://claude.ai/code/session_01UYSXHUyo9LLpoZjADkcaj9

[Copilot]

Pull request overview

This PR adds a new planning document (plan/68_reorganize-docs.md) that outlines a reorganization of the project's documentation structure. The plan proposes moving reference content from CLAUDE.md into dedicated files (DEVELOPMENT.md, docs/design/, docs/guides/, docs/background/) and using mdsmith's <?include / <?/include?> processing-instruction directives to keep agent configuration files (AGENTS.md, .github/copilot-instructions.md) automatically in sync with the primary source in CLAUDE.md.

Changes:

• New planning document with 21 implementation tasks covering file creation, content migration, include directive implementation, and validation
• Acceptance criteria (16 items) defining observable completion checkpoints for the reorganization