omne — SSOT skeleton (cookiecutter template)

What this is

A cookiecutter template that scaffolds the 10-bucket Single Source of Truth (SSOT) skeleton used by omne-style projects. The buckets are: buf, cfg, grad, rem, schemas, agents, obs, archive, prompts, skills. The output is a minimal, project-agnostic .omne/ tree with frontmatter-validated IDX.md placeholders, the canonical validate.py / build_index.py tooling, and the conduct rules / workflow doc preserved from the source layout.

Usage

cookiecutter gh:egoisth777/omne

You will be prompted for:

• project_name — human-readable name (e.g. My Project).
• project_slug — derived from project_name (lowercase + dash). Override if needed.
• ssot_repo_url — the SSOT git remote (e.g. git@github.com:USER/PROJECT-inst.git). Stored for your reference; not wired into any file by default.

After populate, the post-generation hook regenerates .omne/INDEX.yaml and chmods the shell scripts on POSIX.

Layout overview

<project_slug>/
└── .omne/
    ├── INDEX.yaml                    # generated by scripts/build_index.py
    ├── .gitignore
    ├── buf/                          # alignment buffer (user<->agent dialogues)
    ├── cfg/                          # canonical config (the active source of truth)
    │   ├── architecture/             # file/module/function map + wiring
    │   ├── algos/                    # load-bearing algorithms
    │   ├── behaviors/                # input -> output behavior pairs
    │   ├── knows/                    # distilled long-term concepts
    │   ├── linter/                   # mechanical rules
    │   ├── proof/                    # Lean4 / formal verification
    │   └── tests/                    # language-neutral executable specs
    ├── grad/                         # active gradient (in-flight work)
    │   └── changes/                  # openspec triplets
    ├── rem/                          # residual = cfg - current
    │   └── tech-debts/               # deferred work with resolve_by tags
    ├── schemas/
    │   ├── conduct/                  # global agent-conduct rules
    │   └── protocol/                 # inter-agent contracts
    ├── agents/                       # MAS role registry
    ├── obs/                          # observability schemas
    ├── archive/                      # durable history
    │   ├── buf-history/
    │   ├── retros/
    │   ├── specs/                    # promoted+shipped openspec triplets
    │   └── stale/                    # superseded decisions
    ├── prompts/                      # reusable prompt templates
    ├── skills/                       # Claude Code-style skill packages
    ├── scripts/                      # validate.py, build_index.py, etc.
    └── wt/                           # canonical worktree storage

Next steps after populate

• Populate cfg/architecture/, cfg/algos/, cfg/behaviors/, etc. with project-specific design docs.
• Write cfg/knows/<concept>.md entries (each requires ## what and ## why H2 sections).
• Define agents/<role>.md for project-specific roles (capability / tools / forbidden frontmatter required).
• Install the pre-commit hook: cd .omne && bash scripts/install-hooks.sh.
• Link .claude/agents/ to your roles: run scripts/setup-claude-agents.ps1 (Windows: junction / symlink) or scripts/setup-claude-agents.sh (POSIX: symlink).

Authority

Authority is layered. The role-level primary contract lives in agents/<role>.md (capability, tools, forbidden globs). Doc-level refinement comes from per-doc frontmatter owners: / readers: keys when finer-grained access control is required. When the two disagree, the more restrictive wins.

Origin

Derived from the grex SSOT (egoisth777/grex-inst); see that repo for a concrete populated instance of this skeleton.