You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Document project principles in docs/principles.md #18
Capture the principles that have emerged from design work, to serve as a reference for future decisions and for contributors.
Draft principles to document
Composability: schemas are built from shared building blocks; teams compose rather than fork; schemas can be assigned per space
Flexible page/embedding: entities can be expressed as full pages or as embedded headings/sections within a parent page — both are valid expressions of the same entity type (once Support "embedding" of subitems at any level #10 lands)
Quality scaffolding: the tool provides scaffolding that helps improve the quality of planning tree content, not just validate structure — through descriptive rules, templates, and agent skill integration
Reduce toil: automate the mechanical aspects of managing planning content (validation, diagram generation, sync, templates)
Terminology flexibility: type aliases allow teams to use their own vocabulary while still getting schema validation
Fail loudly: prefer explicit errors over silent fallbacks; the tool should surface problems clearly so they can be fixed
These are draft — the doc should expand and refine them, add rationale and examples, and note where they inform specific design decisions.
When to do this
Best written after the schema reorganization (#13) and strict_ost (#15) work is complete, since those decisions will make the principles more concrete.
One to ponder and add - convention over configuration - for this project that probably means: sweat the details on schemas and parsing rules so that content authoring is intuitive and natural once configured - follow common and natural paths (eg natural heading/page/path hierarchies, linking, tagging and metadata structures, content types like tables, lists and databases)
Activity
mindsocket commentedon Mar 23, 2026
One to ponder and add - convention over configuration - for this project that probably means: sweat the details on schemas and parsing rules so that content authoring is intuitive and natural once configured - follow common and natural paths (eg natural heading/page/path hierarchies, linking, tagging and metadata structures, content types like tables, lists and databases)