Skip to content

Document project principles in docs/principles.md #18

Open

Description

@mindsocket

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
  • Separation of concerns: structural validation (schema/AJV), qualitative guidance (descriptive rules in schema), and AI-assisted analysis (Create an agent skill that knows how to work with OST content #2) are distinct, composable layers
  • 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.

Activity

  1. mindsocket commented on Mar 23, 2026

    @mindsocket
    OwnerAuthor

    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)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions