Skip to content

AGENTS.md

Latest commit

 

History

History
173 lines (139 loc) · 11.7 KB

AGENTS.md

File metadata and controls

173 lines (139 loc) · 11.7 KB
Raw

Repository Guidelines

Rhizome (vault + agent CLI) guidelines

  • This repo uses Rhizome to load local docs, note context, and typed-note contracts before you change code or markdown.
  • rzm init injects this guidance as a managed block inside AGENTS.md and CLAUDE.md. Do not edit the managed block directly. Put repo-specific instructions outside managed fences in those files.

Start here

  • Use rzm agent start as the default bootstrap for real work. It already returns sessionId, surface, and vaultContext.
  • Prefer: 
    rzm agent start --profile code --ontology --file <dir-or-file> --submodule-depth 1
  • Reuse the returned sessionId across later rzm agent calls in the same conversation.
  • You usually do not need a separate rzm agent surface call at session start. If you want to refresh the exact command/flag contract later in the session, call rzm agent surface then.
  • Run rzm agent validate before handoff.

Default loop

  1. Run rzm agent start once.
  2. Run rzm agent file-context on the key files or directories you will edit or call into.
  3. Run rzm agent semantic-query for missing "how/why/where" context, design docs, runbooks, and prior art.
  4. Run rzm agent files when you need exact note lookup by path, tag, property, or backlinks.
  5. Run rzm agent query-recipe when a skill or repo guide names a saved typed-note query.
  6. Run rzm agent validate --check broken-links --check link-hygiene --check ontology --check query-recipes --check companion-docs --check code-frontmatter --check code-anchors --max-issues 40 before handoff.

Use the right tool

  • rzm agent file-context: entry points, orchestration, complex files, and dependencies you are about to change or depend on.
  • rzm agent semantic-query: discovery, design/rationale lookup, runbooks, and broad "what explains this?" questions.
  • rzm agent files: exact note discovery, frontmatter/property lookup, backlinks, and small graph expansion.
  • rzm agent vault-context: only when you intentionally skip start and just need vault text context.
  • rzm agent report / rzm agent vault-health: audits, coverage checks, and note hygiene.
  • rzm agent find-connections / rzm agent graph-path: relationship tracing between notes and code.
  • rzm note move: rename or move markdown files and attachments. Do not move them directly on disk.
  • rzm note rename-heading: rename a heading that may have inbound note#Heading Text references.

Markdown work

  • Prefer repo skills over ad hoc command sequences when a markdown task matches one:
    • rhizome-note-authoring: create or edit typed markdown notes.
    • rhizome-ontology: change .rhizome/ontology/*.graphql.
    • Template-specific skills such as code-docs, specify, plan, or implement when they are installed for this repo.
  • If a typed markdown task is not already covered by a skill:
    1. Run rzm agent ontology-inspect --input <note-or-finder> to confirm the resolved type.
    2. Run rzm agent ontology-query-schema before writing typed queries.
    3. Run rzm agent ontology-query to pull the typed neighborhood the note must align with.
    4. Run rzm agent ontology-authoring-guide --type <TypeName> before drafting or restructuring the note.
  • Never guess typed roots, field names, or relation names from memory. Use the live SDL from rzm agent ontology-query-schema.
  • Typed roots require one of path, find, property, or semantic.

Graph link maintenance

  • Link to the smallest durable graph node that explains the reference. Prefer top-level identifier aliases such as SPEC-0001 for whole notes, and identifier-backed block targets such as some-spec#^SPEC-0007-US1 for embedded nodes.
  • Do not hand-author new durable links to embedded nodes as note#Heading Text when a block target or node link target is available. Use rzm agent node-link --target <path#fragment> --ensure plan to get the target and proposed fix, or use node_link from read-write MCP with ensure=apply when you are authorized to make the target linkable.
  • Use rzm note move for note/file moves so vault links are rewritten with the move.
  • Use rzm note rename-heading <path> "<old>" "<new>" for heading text changes that may have inbound heading-fragment links. Plain text heading edits can strand existing links.
  • After link-target moves, heading renames, or manual markdown surgery, run rzm validate --check fragile-external or rzm agent validate --check fragile-external to find surviving heading-only links that should be upgraded or repaired.
  • Keep structured data keyed by canonical node refs. Treat wikilinks and Markdown links as author-facing renderings, not the durable internal identity.

Retrieval hygiene

  • Do not rerun rzm agent start if you already have a sessionId from earlier in the conversation.
  • Do not run blanket rzm agent file-context over trivial helpers or areas you already contextualized.
  • Pass precise intent strings to rzm agent start, rzm agent file-context, and rzm agent files.
  • For rzm agent semantic-query, use --mode; do not treat freeform intent as a search mode.
  • --mode overview is the default no-seed discovery mode.
  • --mode subsystem_overview prefers explicit --path, but query-only module/symbol-shaped prompts now attempt local target resolution before downgrading to overview.
  • Targeted fetch modes still work best with --path; when query-only resolution is ambiguous or unresolved, Rhizome returns structured warnings rather than broad false-confidence matches.
  • Treat docs surfaced by file-context, vault-context, and semantic-query as operational constraints. Adjust code, plan, and validation accordingly.
  • If you change behavior, update the nearest doc surface and rerun file-context when you need to confirm the docs still surface correctly.
  • Notes surfaced automatically through coderefs or code anchors are context-window real estate. Keep them short, concrete, and operational.

Repo configuration

  • Rhizome config: .rhizome/config.yml
  • Ignore rules: .rhizome/ignore (preferred)
  • Notes: includes docs/**/*.md
  • Links mode: both
  • Code scanning globs: **/*.cs, **/*.js, **/*.jsx, **/*.ts, **/*.tsx
  • Code anchors: enabled

Core Identity

  • Use note-backed Person nodes for accountable humans.
  • Configure the local user with rzm agent current-user set "<Person title>"; validate with rzm agent current-user validate.
  • Use rzm agent current-user show when you need to inspect the configured identity.
  • Do not infer the current user from chat context, OS usernames, Git authors, or vault names.

Start Here

Process

Agent Redirect Policy

  • /AGENTS.md is the canonical instruction source for AI coding agents in this repository.
  • Tool-specific config files are redirect adapters only. Keep normative project guidance in AGENTS.md and linked process specs.
  • Start with /docs/specs/process/agent-workflow.md; normative workflow rules live in the linked process specs.

Loop Rules

  • Treat behavior-changing, high-risk, or ambiguous work as loop-driven.
  • For loop-driven work, create or update the relevant spec and effort before planning implementation.
  • For loop-driven work, run plan before implementation edits.
  • Request explicit in-chat approval before implementation edits on loop-driven work, and record that approval in the effort when an effort exists.
  • Check off each checklist item immediately after implementation satisfies it.

Foundation Review Loop

  • When planning implementation, identify critical schema changes, types, modules to reuse/adapt/create, contracts, API changes, and other design decisions that shape later work or have long-term implications.
  • Make Phase 1 establish these formative patterns, then pause for review after Phase 1 completes before continuing into the larger build.
  • If later logical stages introduce different architectural changes, add another foundation phase before that implementation work begins.
  • When the user is ready to proceed with the plan, build Phase 1, then use .codex/skills/foundation-review to work with the user and confirm the key decisions are correct.

Agent Modes

  • Agent Partnership fits ambiguous, judgment-heavy synthesis. Keep it conversational: short turns, one tension at a time, targeted questions, compact synthesis, and no long memo-style dumps early.
  • Agent Delegation fits bounded drafting and production. Once the brief is clear, produce the artifact directly and let the human review it.
  • Start in Partnership when ambiguity or tradeoffs materially affect the artifact. Switch to Delegation once the brief is stable enough to execute without inventing hidden decisions.

Team Skills

  • alignment-audit: .agents/skills/alignment-audit/SKILL.md
  • backport: .agents/skills/backport/SKILL.md
  • code-docs: .agents/skills/code-docs/SKILL.md
  • compound: .agents/skills/compound/SKILL.md
  • debugging: .agents/skills/debugging/SKILL.md
  • development-loop: .agents/skills/development-loop/SKILL.md
  • effort-new: .agents/skills/effort-new/SKILL.md
  • foundation-review: .agents/skills/foundation-review/SKILL.md
  • implement: .agents/skills/implement/SKILL.md
  • ingest-transcript: .agents/skills/ingest-transcript/SKILL.md
  • plan: .agents/skills/plan/SKILL.md
  • quality-gates-check: .agents/skills/quality-gates-check/SKILL.md
  • refactor-planning: .agents/skills/refactor-planning/SKILL.md
  • rhizome-review-feedback: .agents/skills/rhizome-review-feedback/SKILL.md
  • specify: .agents/skills/specify/SKILL.md

Action Items

  • Use .agents/skills/action-items/SKILL.md whenever creating, finding, updating, completing, assigning, or summarizing action items.
  • Query action items through direct ActionItem recipes/roots, not through a conversation or meeting type.
  • Use rzm agent current-user validate before answering "my action items"; configure with rzm agent current-user set "<Person title>" when missing.
  • Add action items to the note where the commitment belongs, using #action-item, assignee::, and optional ISO due:: YYYY-MM-DD.