ant

Files (2)

• BACKFILL_FOUNDATION.md
• SKILL.md

SKILL.md (first lines)

# AIT (`ant`) — Agent Notebook Tool

`ant` is the *why* companion to [ait](../../ait)'s *what*. Where ait tracks
open issues and dependencies, ant captures the durable record of decisions
made, alternatives evaluated, and pivots taken — the context a future
session needs to pick up where the last one left off.

The database lives at `.ant/ant.db`, gitignored by default. Notes are
developer-personal working memory; they can be promoted to project
documentation later via `ant export`.

## At the start of every session

If the project has an `ant` database, run `ant foundation` early. It
returns the project's single load-bearing vision entry — what the
project is, what it isn't, the spirit you're meant to be working in.
Read it before you start making judgement calls about design, wording,
or trade-offs.

If `ant foundation` reports no foundation recorded *and* the project
shows signs of being established (a populated `CLAUDE.md`, a real
`README.md`, non-trivial git history), offer to backfill one with the
user. If they agree, read
[BACKFILL_FOUNDATION.md](./BACKFILL_FOUNDATION.md) and follow the Q&A
flow there. If they'd rather not — or the project is brand new and
hasn't had its ideation discussion yet — drop it and carry on. Most
projects won't have a foundation and that's fine.

Then run `ant handover`. It returns the newest handover note in full:
where the last session got to and what's next. If it reports none,
carry on.

After a project ideation/vision discussion that produced a shared sense
of what the project is and isn't, offer to capture it as the foundation
entry: `ant add --kind foundation --body @path/to/notes.md`. There can
only be one — `add` will refuse a second, and you revise the existing
one with `ant edit` instead.

## When to reach for it

Lean conservative — capture entries when the *why* would be hard to
reconstruct from the code alone:

- **The user asks**: "let's make a note of this", "record this", "ADR this".
- **A load-bearing decision was made**: a choice that constrains future
  work and isn't obvious from reading the code.
- **An evaluation between options ended in a pick**: "we tried X but went
  with Y because…".
- **A pivot or library swap**: moving away from one approach to another.
- **A project ideation phase wrapped up**: the moment after you've
  agreed on what the project is, before any code is written, is the
  right time to capture a `foundation` entry.

You don't need to capture every small detail — favour fewer high-value
entries over a stream-of-consciousness log. If in doubt, ask the user.

## Conventional kinds

The schema doesn't enforce these — `kind` is a free string — but starting
with three named conventions keeps the notebook navigable:

- **`adr`** — Architecture Decision Record. A load-bearing choice worth
  recording properly: title, context, options considered, the decision,
  the consequences. Longer-form by convention.
- **`note`** — A captured thought, observation, or short rationale. The
  default and the bulk of entries.
- **`pivot`** — A change of direction: "we tried X for Y reason, it
  didn't pan out, here's why we moved on". Often shorter than an ADR but
  worth distinguishing because pivots tell future-you "don't reconsider this
  unless conditions changed".
- **`foundation`** — The project's single vision document (one per
  project, enforced). What this project is and isn't, in the spirit of
  a design doc agreed before code was written. Read it at session
  start; capture one only after a clear ideation/vision discussion.
- **`handover`** - Where a session got to and what the next one should
  pick up. Written with `ant handover create`, read with `ant handover`.
  See below.

Promote a `note` to an `adr` later (`ant edit --kind adr <id>`) if it turns
out to matter.

## Capturing entries

```bash
ant init                                  # one-time, sets up .ant/ant.db
ant init --prefix myproject               # override the inferred prefix

ant add --body "rationale text"           # literal body
ant add --body @path/to/file.md           # body from file
echo "rationale" | ant add                # implicit stdin
ant add --human --title "Why X"           # body written in $EDITOR (for a person)
ant add --body - <<'EOF'                  # explicit stdin via heredoc
Multi-line body. Single-quoted 'EOF' means no shell expansion —
backticks and $vars stay literal.
EOF

ant add --title "Choose sqlite" --kind adr --issue ait-AbCdE.2 \
        --body "we picked modernc/sqlite over CGO bindings because…"
```

`--issue` is free-form; if you use ait it'll match an ait id, but Jira /
Linear / GitHub ids work just as well — ant doesn't validate the value.

For non-trivial bodies, the safest options are `--body @file` or a
single-quoted heredoc (`<<'EOF' ... EOF`). The single-quoted delimiter
disables shell expansion, so backticks, `$variables`, and apostrophes
all survive untouched.

### When a new entry overturns an older one

If what you are writing replaces any part of an earlier entry, say so
with `--supersedes`. Readers of the older entry then see a warning
before they act on it. Nobody goes back and edits old entries, so this
is the only way they find out.

```bash
ant add --kind adr --title "Grouping, second wave" \
        --supersedes x-Ed6UZ --supersedes-reason "a story is no longer one folder" \
        --body @path/to/notes.md

From ohnotnow/agentic-stuff, MIT.

More from ohnotnow/agentic-stuff