tomevault-io Project Governance
Create, modify, and maintain project constitutions and agent instruction files that guide AI agents. Also supports RFC/ADR documents for formalizing technical decisions.
Quick Start
Create a constitution
# Analyze the project, then create oak/constitution.md
# See references/constitution-guide.md for the full process
Create agent instruction files
{oak-cli-command} rules detect-existing # Discover all configured agent instruction files
{oak-cli-command} rules sync-agents # Sync constitution references to all agent files
Commands Reference
| Command | Purpose |
|---|---|
{oak-cli-command} rules detect-existing |
Discover all configured agent instruction files |
{oak-cli-command} rules detect-existing --json |
Machine-readable output of agent files |
{oak-cli-command} rules sync-agents |
Sync constitution references to all agent instruction files |
{oak-cli-command} rules sync-agents --dry-run |
Preview what files will be checked/updated |
When to Use
- Creating a new constitution for a project that doesn't have one
- Creating agent instruction files for a new project (use
{oak-cli-command} rules detect-existingto discover correct file names) - Adding rules when you identify patterns that should be standardized
- Syncing agent files after constitution changes
- Learning context engineering theory behind effective rule writing -- see
/context-engineeringfor the altitude concept, canonical examples, and structured context patterns
Constitution Structure
A good constitution is explicit, enforceable, and anchored:
| Quality | Good | Bad |
|---|---|---|
| Specificity | "All API endpoints MUST validate input using Pydantic models" | "Use best practices" |
| Anchors | "Copy src/features/auth/service.py for new services" |
"Follow good patterns" |
| Non-goals | "This tool is NOT a CI/CD orchestrator" | (no boundaries) |
| Gates | "make check must pass for all changes" |
"Add tests if needed" |
Required sections: Metadata, Scope and Non-Goals, Golden Paths with Anchor Index, Architecture Invariants, No-Magic-Literals, CLI Behavior, Quality Gates. See references/constitution-guide.md for the full structure and creation process.
Key Workflows
Creating agent instruction files
CRITICAL: Do NOT guess agent file names. Always discover them dynamically.
- Discover the correct file names and paths:
{oak-cli-command} rules detect-existing - Read the output — it shows each configured agent, the expected file path, and whether the file already exists
- Create only the files listed as "not found", using the exact paths from the output
- Content should follow the template in
references/agent-file-good-example.md - Verify all files are detected:
{oak-cli-command} rules detect-existing(all should show ✓)
Adding a rule to an existing constitution
- Read the current constitution (
oak/constitution.md) - Add the full rule to the appropriate section using RFC 2119 language (MUST, SHOULD, MAY)
- Sync to all agent files:
{oak-cli-command} rules sync-agents
CRITICAL: Rules MUST be added to the constitution FIRST, then synced to agent files. Never add a rule only to an agent file.
Common Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|---|---|
| "Use best practices" | Not enforceable | Specify the practice |
| "When possible" | Loophole generator | Define when it's required |
| No anchors | Agents freestyle | Point to specific files |
| No non-goals | Scope creep | Explicitly exclude things |
| "Add tests if needed" | Permission to skip | Define coverage requirements |
| "Make reasonable assumptions" | Inconsistent patterns | Say "ask if uncertain" |
Files
- Constitution:
oak/constitution.mdor.constitution.md - Agent files: Run
{oak-cli-command} rules detect-existingto discover all agent instruction files - RFCs:
oak/rfc/RFC-XXX-short-title.md
Deep Dives
For detailed guidance, consult the reference documents:
Constitution & Agent Files
references/constitution-guide.md— Full constitution creation process and structurereferences/constitution-good-example.md— Complete example of a well-structured constitutionreferences/constitution-bad-example.md— Anti-patterns to avoidreferences/agent-files-guide.md— Creating and syncing agent instruction filesreferences/agent-file-good-example.md— Well-structured agent file examplereferences/agent-file-bad-example.md— Poorly structured agent file example
RFCs (secondary)
references/creating-rfcs.md— Detailed RFC creation workflowreferences/reviewing-rfcs.md— RFC review checklist and feedback format
RFC Support
RFCs formalize technical decisions that may eventually become constitution rules. This is a secondary capability — see the dedicated references for full details.
RFC commands
| Command | Purpose |
|---|---|
{oak-cli-command} rfc create --title "..." --template <type> |
Create a new RFC |
{oak-cli-command} rfc list |
List all RFCs |
{oak-cli-command} rfc validate <path> |
Validate RFC structure and content |
{oak-cli-command} rfc show <path> |
Show RFC details |
{oak-cli-command} rfc adopt <path> |
Mark RFC as adopted |
{oak-cli-command} rfc abandon <path> --reason "..." |
Mark RFC as abandoned |
RFC templates
| Template | Use For |
|---|---|
feature |
New features, capabilities |
architecture |
System architecture changes |
engineering |
Development practices, tooling |
process |
Team processes, workflows |
RFC lifecycle
- Create:
{oak-cli-command} rfc create --title "..." --template feature --author "Name" - Fill in: Problem context, proposed solution, trade-offs, alternatives
- Review: Use the review checklist (see
references/reviewing-rfcs.md) - Adopt or abandon:
{oak-cli-command} rfc adopt <path>or{oak-cli-command} rfc abandon <path> --reason "..."
RFC review checklist (summary)
- Structure: Clear title, correct status, all required sections
- Context: Problem clearly stated, "why now?" addressed, scope defined
- Decision: Solution clear, technical approach explained
- Consequences: Positive/negative outcomes listed, mitigations proposed
- Alternatives: Other options considered, reasons for rejection explained
Converted and distributed by TomeVault — claim your Tome and manage your conversions.