Skip to content

CONVENTIONS.md

Latest commit

 

History

History
160 lines (132 loc) · 7.39 KB

CONVENTIONS.md

File metadata and controls

160 lines (132 loc) · 7.39 KB
Raw

CONVENTIONS — repo layout & operating conventions

Short, load-bearing conventions everyone working in this repo must respect. The frozen spec (docs/agentic_brain_spec.md) is authoritative; this file is the operating agreement so nothing has to be guessed. agentman is an independent, external task substrate with its own repository and documentation.

1. Repo layout

The synced vault repo (private remote) has this tree. Three context levels only — master, category, project; everything else is a navigation folder.

agentic-brain/                     # synced repo root; ALL paths are vault-root-relative
  Master_Context.md                # master context
  CONVENTIONS.md                    # this file
  README.md
  .gitignore                        # synced-repo ignore rules (§5)
  docs/
    context-schema.md               # Context.md schema contract (§6)
    packet-format.md                # context packet contract (§7)
    proposal-format.md              # proposal contract (§9)
  Work/
    Context.md                      # category context
    skills/                         # category-level skills (canonical home, §8)
    journal/                        # dated, append-only EOD digests (§10)
    proposals/                      # proposals from non-project-scoped sessions (rare)
    engineering/                    # grouping folder — NO Context.md, NO skills
    confidential/                   # ALWAYS-IGNORED subtree (§5); its own local-only repo
  Research/
    Context.md  skills/  journal/  proposals/
  Personal/
    Context.md  skills/  journal/  proposals/
  tools/                            # hook, setup, packet-alloc, linter
  tests/                            # test harness

Per-project tree (inside a category, e.g. under Work/confidential/projects/001_apollo/):

<NNN_codename>/
  Context.md
  skills/                           # project-level OVERRIDES only (§8)
  artifacts/
    artifact_map.md
    packets/                        # NNNN_<objective-slug>.md (§7)
    proposals/                      # NNNN_<change-slug>.md (§9)
    notes/  scripts/  tools/  reports/  screenshots/  blobs/  sensitive/
    archive/

.gitkeep files hold otherwise-empty tracked dirs. Never add a .gitkeep under any confidential/ subtree — that subtree is never tracked by the synced repo.

2. Path convention — vault-root-relative, always

Every durable path — packet paths, artifact_map.md entries, task meta values (packet=, proposal=), skill source references, citations — is vault-root-relative (relative to the synced vault's root, e.g. Work/confidential/projects/001_apollo/artifacts/packets/0007_recon.md), regardless of which git repo owns the file. This is the one path convention. Slugs are display-only; correlation is by *_id (§4).

3. The two-repo model & the commit rule

  • The vault root is a git repo with a private remote (the synced repo).
  • Each category's confidential/ subtree is its own local-only git repo (git init, never given a remote). It is ignored wholesale by the synced repo (**/confidential/).
  • Commit rule: commit in the repo that owns the file. A vault-root git add -A silently excludes the ignored confidential subtree — that is by design, not an error. Files inside confidential/ are committed by the confidential repo; everything else by the synced repo.

Constraint: do NOT run git add, git commit, or any git-index mutation. Write working-tree files only — concurrent agents share this repo and the main loop commits later.

Never run git clean -ffdx at the vault root — it destroys the local-only confidential repos (§5). The guardrail hook cannot save you from it.

4. Where each kind of thing lives

Thing Location
Context (durable knowledge) Master_Context.md, <Category>/Context.md, <project>/Context.md
Skills (procedural memory) <Category>/skills/<name>/ (canonical); <project>/skills/<name>/ (overrides only)
Journal (dated digests) <Category>/journal/YYYY-MM-DD.md (append-only)
Packets (dispatch audit) <project>/artifacts/packets/NNNN_<slug>.md (§7)
Proposals (lessons-as-diffs) <project>/artifacts/proposals/NNNN_<slug>.md; rarely <Category>/proposals/ (§9)
Artifacts (raw output) <project>/artifacts/<typed-dir>/ + a line in artifact_map.md
Confidential everything under <Category>/confidential/... (local-only repo)
Tools (hook/setup/alloc/linter) tools/
Tests tests/ (entrypoint tests/run-all.sh)
Docs (contracts) docs/
Secrets nowhere by value — referenced by store location only (§5)

5. Fixed tooling

  • Python 3, stdlib only for the guardrail hook and the test harness. No third-party pip packages — the vault must run anywhere.
  • POSIX shell for trivial glue (setup, packet allocation noclobber claim, tests/run-all.sh).
  • The guardrail pre-commit hook is a vault skeleton install (§5): in the synced repo (full: packet immutability + journal dating + leak scan + binary warning) and in each confidential repo (reduced: packet immutability + journal dating; the leak scan is pointless where nothing syncs).

6. Skills: levels & v1 instantiation (§8)

  • skills/ exists only at the category level (canonical home) and the project level (specialized overrides that shadow the category skill of the same name, for that project only). Nowhere else — not at master, not in grouping folders. Overrides graduate to the category via a proposal (§9), then the project copy is archived.
  • Operational skills are category-level and, for v1, instantiated in Work/skills/:
    • worker-loop (pull execution, §3/§7)
    • retrospective (proposal generation, §9)
    • end-of-day (the §10 order)
  • Research/ and Personal/ get a Context.md and a skills/ directory, but for v1 only project-init (the per-category planner skill, §3). They do not get the operational worker/retrospective/end-of-day skills in v1.
  • project-init is per-category (<Category>/skills/project-init/) with its templates inside the skill. Work's templates: project (default confidential), adhoc.

7. Confidentiality is the highest-stakes rule (§5)

  • A confidential project's subject identity must never reach a synced surface — not content, not via a path or filename. When in doubt, fail safe. (This model originates in sensitive-work contexts, where keeping project detail off a synced remote is the highest-stakes concern.)
  • Confidential projects use non-identifying codenames for folder name and agentman slug (e.g. 001_apollo / apollo); the real name/scope lives only inside the confidential project's Context.md and its denylist.txt.
  • Synced surfaces (journal, category proposals, commit messages): codename + task # + packet NNNN only — never the vault_project_id of a confidential project, never the subject name, never a content excerpt, never an outcome characterization.
  • The guardrail hook enforces the hook-guarded rules only (packet immutability, journal dating, leak scan). The discipline rules (artifact_map same-change, commit-in-owning-repo, skill-use reporting, Invariant vs Preference) are compliance, checked post-hoc — honestly accident-prevention, not security.