Imported from gilmar/koinome (examples/research-project/.koinome/snapshot/AGENTS.md). Install upstream with npx skills add gilmar/koinome --skill snapshot. Copyright stays with the author.

Corpus Agent Guide

This is a provider-independent work knowledge base in plain markdown. It is read and maintained by CLI agents (Claude Code, Codex, Gemini CLI). Human navigation is secondary. This file is canonical; CLAUDE.md and GEMINI.md point here.

Session bootstrap (do this at the start of every session)

1. Read this file.
2. Read 80-moc/home-moc.md to orient, then the relevant domain MOC.
3. Read 72-tasks/todo.txt for open tasks.
4. Read the two most recent entries in 71-log/ for recent context.

How to retrieve (in order)

1. Search: grep/glob across *.md by filename and by the frontmatter summary and title fields first. These are the strongest, cheapest signals.
2. Read only the specific notes you need. Do not bulk-load folders.
3. For a topic, open its MOC in 80-moc/ before reading individual notes. Return metadata and summaries before full note bodies. Fetch a full body only when the summary is insufficient.

Structure

Folder layout is defined in .scripts/koinome.config.json. Read the current domains map and structural_folders list at session start (or whenever unsure). Never infer domain folder names or slugs from examples in other repos or older docs.

• Subject domains: keys in domains (e.g. 10-projects) map to slug values used in frontmatter and tasks. These are corpus-specific.
• Structural folders: shared paths such as inbox, decisions, tasks, MOCs, templates, and archive — exact list is in structural_folders.

Common structural folders (confirm against config):

• 60-decisions: ADRs (MADR format). Read 60-decisions/index.md for the log.
• 70-meetings: dated meeting and 1:1 notes.
• 71-log: dated session and daily work logs (append-only).
• 72-tasks: open tasks (todo.txt) and completed archive (done.txt).
• 80-moc: Maps of Content, generated by gen_mocs.py. Your primary entry points.
• 90-templates: note templates. Copy these when creating notes.
• 95-assets: images and binaries.
• 99-archive: DO NOT SEARCH by default. Stale or superseded content.
• 00-inbox: unsorted captures and import output.

Frontmatter (every note has it)

Required fields, controlled vocabularies (vocab.type, vocab.status), and min_summary_len are defined in .scripts/koinome.config.json. Never infer types, statuses, or domain slugs from examples — read the config.

domain must be one of the slug values in domains. Use summary to judge relevance before reading the body. Front-load it with concrete nouns and meet the configured minimum length.

Format rules (open-standard markdown only)

• CommonMark plus GFM tables plus YAML frontmatter. Nothing else.
• Internal links are relative markdown links: [title](../60-decisions/adr-0001-corpus-structure.md). NO wikilinks, NO ![[embeds]].
• NO Dataview, NO Templater, NO callout syntax. MOCs are generated, not queried.
• Prefer short atomic notes over long ones. One topic or event per note. Use H2/H3 so a note is internally chunkable.

Write rules

• Fill the full frontmatter on every note you create or edit. Set updated to today.
• Decisions are immutable: to change one, write a new ADR that supersedes it, mark the old one status: superseded, and update 60-decisions/index.md.
• After adding or editing notes, run python3 .scripts/gen_mocs.py to refresh MOCs.
• Validate before committing: python3 .scripts/validate_corpus.py --all. Fix every violation.
• Commit with git after material changes. Normal commits, not --no-verify; the hook is the quality gate.
• On a sync-conflict-*.md note in 00-inbox/: merge the named branch, verify, delete the branch. See docs/OPERATIONS.md.

Tasks (todo.txt format)

Open tasks in 72-tasks/todo.txt, archive in 72-tasks/done.txt. One task per line, no blank lines. Open task: (A) 2026-07-04 Description +project @context due:YYYY-MM-DD ref:path.md

• (A) optional priority, single uppercase letter, first.
• Creation date included when creating.
• +project uses domain slugs from the config. @context optional. due: and ref: optional. Completed task: x 2026-07-05 2026-07-04 Description +project pri:A (lowercase x, completion date, creation date, preserve original priority as pri:A). Write rules: append new tasks at the end; complete in place; never delete an open task (to drop one, complete it with +cancelled); at session close move x lines to 72-tasks/done.txt; done.txt is append-only. Run the validator on todo.txt after editing.

Session close

1. Complete or update 72-tasks/todo.txt, move done tasks to 72-tasks/done.txt.
2. Append a dated log entry to 71-log/ (type: log): decisions made, facts learned, open loops.
3. Regenerate MOCs, validate, commit.

Hard boundary: no sensitive personnel data

this corpus contains NO performance, compensation, termination, or health records about individuals, by design. If asked for them, state they live in a separate private corpus you cannot access. If you encounter such content during an import, do not bring it in; flag the source file only. See docs/ARCHITECTURE.md.

Synthesis layer: raw vs synthesized

this corpus separates raw material from synthesized knowledge, and the distinction is enforced.

• 05-sources/ holds raw, immutable intake (type: source). It is the synthesis queue. Read it; never rewrite its content into summaries in place.
• 85-synthesis/ holds derived entity and concept pages (type: entity / type: concept). These are DERIVED, not authored ground truth. Every synthesized page must set synthesis: generated, cite a non-empty sources: list (corpus-root-relative paths), carry generated_at, and a review: gate (needed or approved). The validator enforces this.
• Authored domain notes (10-50) are the ground truth. Never mark them synthesis: generated.

Rules for you as an agent:

• Treat synthesized pages as convenience, not authority. When a synthesized claim matters, verify it against the cited sources.
• To run synthesis, follow docs/SYNTHESIS.md. It is an intentional batch operation over the queue, not something you do silently on every write.
• When you synthesize, cite sources, flag contradictions in the page, set review: needed, and set generated_at to today. Never invent a claim not traceable to a source.
• Check python3 .scripts/synthesis_status.py for the queue, stale pages (a source changed after the page was generated), and pages awaiting review.
• Check python3 .scripts/graph_report.py for structure and holes: hub notes, orphan islands, sources drawn on together, and tags used often with no page. It is deterministic and structural; it finds gaps, it does not judge meaning.

When validation fails

Do not weaken the gate; fix the note. Run python3 .scripts/validate_corpus.py --json --all and work the errors in order of their fixable tag: run --fix --all for the auto ones, draft llm ones from the note's own content and get the human's acceptance, and ask the human for human ones (never guess a domain, type, or unresolved source). Full protocol in docs/FIXING.md.

Skills

Reusable workflows live in .skills/ (Agent Skills standard). bootstrap.sh links them into .claude/skills, .codex/skills, .gemini/skills, and .cursor/skills for provider discovery. Invoke explicitly (/koinome-skill-name) or let the agent match by description. After creating a corpus, run koinome-init first to finish setup. Other skills encode this guide's workflows (session close, validation fix, synthesis, notes, ADRs, todos, weekly review, seed distillation, domain changes); this file stays canonical for rules.

When sources conflict

Do not silently resolve contradictory sources. Retain both claims and their provenance; compare authority, scope, effective date, and explicit supersession; mark unresolved contradictions for review. Recency is one signal, never automatic authority. Never mark synthesized pages review: approved while a material contradiction remains. Full policy: docs/CONFLICTS.md. For single-source uncertainty, use "as of YYYY-MM-DD".

Rules of thumb

• Never invent metric, model, or system names. Check the relevant domain notes for exact names.
• Keep this file under ~150 lines.