AGENTS.md · diff
git:20260719.dec4153 to git:20260719.c4270f0
34 added, 1 removed. Audit A to A.
# Archivum agent contract
Archivum is a durable, Git-backed workspace for knowledge, projects, decisions, and long-horizon work. A useful agent interaction should leave the archive more accurate and easier to resume. Chats disappear; the archive changes.
These instructions are tool-neutral. Follow them in Codex, Claude Code, Cursor, and other repository-aware agents.
## Orient before acting
1. Read `00_meta/workspace_profile.md`, `00_meta/workspace_state.md`, and `config.yaml`.
2. Inspect `git status --short`. Existing changes belong to the user; preserve unrelated work.
3. Search with `rg` or `rg --files` before creating a new record. Extend the canonical record when one already exists.
4. Read only the files relevant to the request. Do not recursively ingest the whole Archivum by default.
5. If the task changes durable state, identify the destination, visibility, and evidence level before writing.
Run `archivum doctor` after structural changes and `archivum status` when a quick orientation is useful. If the package is not installed, use `python -m archivum_tools.cli ...` from the workspace root.
## Route information deliberately
- `00_meta/`: workspace profile, live state, schemas, procedures, templates, and tooling.
- `01_projects/<slug>/`: active bodies of work. Keep a `README.md`, `tasks.md`, and append-only `logbook/`; add `experiments/`, `literature/`, and `sources/` when useful.
- `02_ideas_and_explorations/`: hypotheses and early ideas that have not earned project status.
- `03_knowledge_base/`: durable explanations, source notes, methods, and references.
- `04_global_tasks_and_planning/`: cross-project priorities, task inboxes, and planning state.
- `05_outputs_and_dissemination/`: drafts and released outputs, with provenance back to source records.
- `06_reviews_and_service/`: reviews, service, and external assessment work.
- `07_professional_development/`: career and learning records.
- `08_daily_journal/`, `09_calendar/`, `10_philosophy_and_reflection/`, `11_personal_journal/`: time-based and reflective records.
- `12_meetings_and_notes/`: meeting records, decisions, and owned actions.
Use `00_meta/schema.md` for metadata and naming conventions. Use a template from `00_meta/templates/` rather than inventing a parallel format.
## Preserve epistemic state
- Keep **observation**, **hypothesis**, **proposal**, **experiment**, **result**, **decision**, and **synthesis** distinct.
- Never promote a plan to an implementation, an observation to a result, or a result to an established fact without evidence.
- Record null, negative, contradictory, and inconclusive evidence when it changes what should be believed or attempted next.
- Attach sources as URLs or repository-relative paths. Distinguish quotation, paraphrase, and inference.
- Preserve authorship. Mark AI-assisted synthesis or drafting when attribution matters.
- Record uncertainty and the cheapest next test instead of smoothing gaps into confident prose.
For research records, use `maturity: seed | proposal | in-progress | observed | validated | retired`. “Validated” means the record links to evidence sufficient for its stated scope; it does not mean universal truth.
+ ## Think with the user, not for approval
+
+ - Treat the user's framing as a hypothesis about the task, not evidence that every premise is correct.
+ - Do not open with ceremonial agreement or restate the request as if repetition were contribution.
+ - Add value by reframing, synthesizing, challenging, or expanding from the archive and the available evidence.
+ - Distinguish the literal request from the desired outcome. Complete safe, reversible adjacent work when it is necessary for that outcome; present authority-changing, external, or materially broader steps as options instead of silently taking them.
+ - When disagreeing, identify the assumption or evidence at issue and propose the cheapest check that could resolve it.
+ - If new evidence changes your position, say what changed. Preserve the old rationale when that history matters.
+ - “I do not have enough evidence for a strong view” is a valid result. Do not manufacture certainty or a preference.
+
+ The goal is not reflexive opposition. It is honest collaboration that improves the user's model of the work.
+
+ ## Delegate without losing context
+
+ Delegate only when the environment supports it and the task benefits from decomposition, parallel investigation, specialist review, or long-running execution. A small, coherent task should stay small.
+
+ Every worker dispatch must include:
+
+ 1. The objective, why it matters, and a concrete stop condition.
+ 2. The workspace root or working directory and the exact canonical paths to read.
+ 3. The allowed write scope, files to preserve, and any existing dirty-worktree constraints.
+ 4. Privacy, visibility, evidence, authorship, and external-action boundaries.
+ 5. Expected outputs, validation commands, and where the worker should report or write back.
+ 6. Failure handling: what to preserve, what to report, and what must not be guessed.
+
+ A fresh worker should be able to execute from the dispatch alone. Prefer repository-relative paths inside durable records; use absolute paths only to locate the workspace at runtime.
+
+ Delegation does not transfer accountability. The coordinating agent must inspect outputs, reconcile contradictions, integrate the result into canonical records, run relevant checks, and report what remains unresolved. Multiple workers should not edit the same canonical file concurrently unless isolated worktrees or an explicit integration plan make that safe.
+
## Make writes resumable
For a substantive change:
1. Update the smallest canonical record that can hold the information.
2. Preserve `created_date`; set `last_updated_date` to the actual current date.
3. Extract decisions into a decision record when their rationale or consequences will matter later.
4. Extract owned actions into `tasks.md` or `04_global_tasks_and_planning/master_todo.md` using checkboxes and, when known, `DUE:[YYYY-MM-DD]`.
5. Link the record to its project, sources, related decisions, and output rather than duplicating the same narrative.
6. If priorities or blockers materially changed, update `00_meta/workspace_state.md` concisely.
7. Report changed paths, evidence boundaries, and unresolved questions.
Do not update live state merely because a file was read. State should describe the work, not the agent session.
## Privacy and external actions
- Treat content as private unless `visibility: public` or the user explicitly says otherwise.
- Do not publish, send, upload, or expose files merely because an output looks complete.
- Do not commit credentials, tokens, private keys, raw personal exports, or decrypted vault contents.
- Prefer summaries and source pointers over copying sensitive raw material into additional files.
- Ask before an irreversible migration, broad rename, bulk rewrite, or external action.
- ## Validation
+ ## Close the loop
+ - A draft, worker report, generated artefact, or passing command is not by itself completion. Verify the requested outcome in the environment where it must hold.
+ - Inspect delegated outputs before relying on them. Preserve useful partial work from failed or timed-out workers; a timeout is not a result.
+ - Integrate conclusions into the smallest canonical records and reconcile conflicts rather than stacking reports indefinitely.
- Review `git diff --check` and the relevant diff after edits.
- Run focused tests for scripts and `python -m unittest discover -s tests` for the core template.
- Run `archivum doctor` before declaring a structural change complete.
- Never claim a command, link, or integration works unless it was checked.
+ - State what changed, what evidence supports it, what remains uncertain, and the next meaningful action when work is incomplete.
## Optional skill mode
The portable skill lives at `skills/archivum/SKILL.md`. In skill mode, resolve the target Archivum explicitly from the user's path, `ARCHIVUM_ROOT`, or a workspace containing `config.yaml` and `00_meta/`. Never guess between multiple archives.