Skip to content

Latest commit

 

History

History
69 lines (43 loc) · 4.5 KB

AGENTS.md

File metadata and controls

69 lines (43 loc) · 4.5 KB

Atomic VCS Agent

You use Atomic VCS (not git). A draft view is created for each session automatically.

Every prompt is a turn. Every turn follows this sequence.

1. Create an intent

atomic vault intent create --title "<short title>"

This gives you an intent ID (e.g., HELL-4) and a file path.

2. Define the problem

The user's prompt is usually a solution ("build me X"). Reframe it as a problem statement.

Ask clarifying questions if the problem is ambiguous. Do not guess — ask.

Once the problem is clear, define:

  • Problem statement — what problem are we solving and why
  • Success criteria — concrete, testable conditions that mean "done"
  • Tasks — ordered list of work items

Write all of this into the intent file. Replace every REPLACE placeholder.

Then run atomic vault sync to persist your edits into the vault database. The intent file lives on disk under .vault/, but atomic vault intent show/update read from the database, not the file — without sync they see the original placeholder template, and update re-materializes the database copy over the file, clobbering your edits. atomic vault sync is NOT atomic record: it only moves your .vault/ edits into the vault database, and you must run it yourself even though Cursor hooks handle recording.

2b. Simplification guard

Before you finalize the intent, audit every choice that is simpler than or diverges from a reference — the standard library, an existing implementation, a spec, or a prior version. The simpler choice almost always drops a behavior the reference guaranteed, and that's where silent correctness gaps hide.

For each such decision, name the behavior the simpler choice drops — interrupted/partial operations, error or panic states, round-trip fidelity, ordering, resource cleanup, overflow/empty/boundary inputs — and for each dropped behavior either pin it as an acceptance criterion, record it as out-of-scope with the consequence stated, or ask the user. Never leave it unstated. A decision about API shape is not a decision about behavior: the same signature can be implemented correctly or incorrectly.

3. Execute the tasks

Work through the tasks. Check off tasks as you complete them.

4. Update the intent

atomic vault sync                          # persist file edits to the database first
atomic vault intent update <ID> --status done

Always atomic vault sync before atomic vault intent show/update — the CLI reads from the database, not the file, so an unsynced show renders the stale placeholder template and update re-materializes the database copy over the file, clobbering your edits.

Do NOT run atomic add or atomic record. The hook system records your changes automatically with full AI provenance (model, tokens, session, timing) when the turn ends. (atomic vault sync is not atomic record — it only moves your .vault/ edits into the vault database, and you must run it.)

Rules

  • One intent per turn. Every prompt gets its own intent.
  • Problem first. Reframe solution-requests as problems. Ask questions if unclear.
  • Write the intent file before coding. The plan goes in the file, not just in chat.
  • Simplification guard. When you choose an approach simpler than or divergent from a reference (the standard library, an existing implementation, a spec), name the behavior the simpler choice drops (interrupted/partial operations, error states, round-trip fidelity, boundaries) and either pin it as an acceptance criterion, record it as out-of-scope with the consequence stated, or ask the user — never leave it unstated. A decision about API shape is not a decision about behavior.
  • Do run atomic vault sync after editing any .vault/ file, and before atomic vault intent show/update. It deflates your on-disk edits into the vault database; it is not atomic record and hooks do not do it for you mid-turn.
  • Do not run atomic add or atomic record. Hooks handle this with provenance.
  • Do not create or switch views. The session view is created automatically.
  • Do not run atomic agent enable. The integration is already configured globally.

Skills

Use these for detailed reference when needed:

  • /atomic-vault — intent and goal lifecycle, memory operations
  • /atomic-vcs — inspect repository state and history: status, log, change (-p provenance, -a AI attestation), diff
  • /code-intelligence — knowledge graph queries for code exploration