Skip to content

Guides and resources for AI engineers: an agents course, five handbooks, a hands-on second-brain project and a vetted reading list.

docs: agents

undefined-ui0efd6f279c3a
diff --git a/README.md b/README.md
index 70c6626..b645d2f 100644
--- a/README.md
+++ b/README.md
@@ -115,7 +115,7 @@ you can see exactly what is coming and open a pull request against any of it.
| [Ingestion](docs/03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling | **written** |
| [Structuring](docs/04-structuring/README.md) | page types, linking rules, schema, contradictions | **written** |
| [Graphs](docs/05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | **written** |
-| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails | in progress |
+| [Agents](docs/06-agents/README.md) | roles, schedules, hooks, guardrails | **written** |
| [Retrieval](docs/07-retrieval/README.md) | query patterns, search, context budget | in progress |
| [Outputs](docs/08-outputs/README.md) | writing, reports, publishing, learning | in progress |
| [Maintenance](docs/09-maintenance/README.md) | linting, review cadence, git, privacy, scaling | in progress |
diff --git a/docs/06-agents/README.md b/docs/06-agents/README.md
index 4315d03..e2c3779 100644
--- a/docs/06-agents/README.md
+++ b/docs/06-agents/README.md
@@ -2,16 +2,23 @@
Turning a one-off setup into a system that maintains itself.
-## Planned
+Everything up to here you could do by hand, slowly. This section is where the
+vault stops depending on your discipline, which is the only reason it will still
+be alive in six months.
-Being written. Outlines for each are in the [roadmap](../ROADMAP.md), and pull requests are welcome.
+It is also where the risk lives. An agent with write access to your notes,
+running on a schedule while you sleep, is exactly as useful and exactly as
+dangerous as it sounds. Read [guardrails](safety-and-guardrails.md) before you
+schedule anything.
-- Agent roles
-- Scheduling
-- Subagents and parallel work
-- Hooks
-- Skills and slash commands
-- Guardrails
+## Pages
+
+- [Agent roles](agent-roles.md)
+- [Scheduling](scheduled-maintenance.md)
+- [Subagents and parallel work](subagents.md)
+- [Hooks](hooks.md)
+- [Skills and slash commands](skills-and-commands.md)
+- [Guardrails](safety-and-guardrails.md)
---
diff --git a/docs/06-agents/agent-roles.md b/docs/06-agents/agent-roles.md
new file mode 100644
index 0000000..1a441f1
--- /dev/null
+++ b/docs/06-agents/agent-roles.md
@@ -0,0 +1,72 @@
+# Agent roles
+
+One agent doing everything produces mediocre work at every job. The instructions
+that make a good ingestor are not the ones that make a good reviewer, and stuffed
+into one prompt they dilute each other.
+
+Four roles cover a vault. The definitions are in
+[`agents/`](../../agents/README.md).
+
+## Ingestor
+
+Reads `raw/`, writes wiki pages, links them, updates the index and log. Writes
+more than any other role and is the one whose output quality determines
+everything downstream.
+
+Its instructions are narrow on purpose: it does not answer questions, does not
+restructure existing pages beyond adding links, and does not delete. An ingestor
+that reorganises while ingesting produces runs you cannot review, because content
+changes and structural changes arrive mixed in the same diff.
+
+## Linker
+
+Finds connections between existing pages that ingestion missed.
+
+Runs after imports and weekly. Adds links, creates nothing, rewrites nothing.
+Separating it from the ingestor matters because linking well requires reading
+broadly across the vault, which is a different job from reading one source
+closely.
+
+Its one rule: a link it adds must be one you would agree with on reading both
+pages side by side. A linker optimising for link count degrades the graph while
+appearing productive.
+
+## Reviewer
+
+Read-only. Produces the periodic review: what changed, where attention went,
+what contradicts what, what to read next.
+
+Read-only is not caution, it is what makes the review trustworthy. A reviewer
+that can edit will fix small things as it goes, and then its report describes a
+vault that no longer exists.
+
+## Researcher
+
+Read-only. Answers questions from the vault, cites pages, names what is missing.
+
+Also the role you talk to most, and the one that most needs the rule about not
+falling back on general knowledge. See the
+[query skill](../../skills/README.md).
+
+## Roles not worth creating
+
+**A deleter.** Deletion should be a decision you make, executed with a record.
+
+**A summariser.** Summaries of pages that are already summaries produce a layer
+that is less true than what is under it and gets read instead of it.
+
+**A tagger.** Tagging is a five-second judgement made during ingest with full
+context. A separate pass has less context and produces worse tags.
+
+## Handoffs
+
+Roles communicate through the vault, not through each other. The ingestor writes
+gaps into `index.md`; the linker reads them. The ingestor logs its run; the
+reviewer reads the log.
+
+That is deliberate. Files as the interface means any run is inspectable
+afterwards, and a role can be replaced without touching the others.
+
+## Next
+
+[Scheduling](scheduled-maintenance.md)
diff --git a/docs/06-agents/hooks.md b/docs/06-agents/hooks.md
new file mode 100644
index 0000000..ada833f
--- /dev/null
+++ b/docs/06-agents/hooks.md
@@ -0,0 +1,50 @@
+# Hooks
+
+Hooks fire on events rather than on a schedule. They are the right tool for
+things that must happen every time, which is exactly the set of things a prompt
+instruction will eventually miss.
+
+## Worth hooking
+
+**Validation before a write.** Check frontmatter parses and required fields are
+present. A malformed page caught at write time is a non-event; caught a month
+later it is a page that has been invisible to every query since.
+
+**Lint after a run.** Broken links appear at the moment they are created, which
+is the moment there is enough context to fix them properly.
+
+**Commit after a scheduled run.** Removes the possibility of a run that changed
+forty files and left no commit.
+
+**Notify on deletion.** Any delete, any time, surfaces. Deletions are rare enough
+that a notification costs nothing and matters when it fires.
+
+## Not worth hooking
+
+Anything slow. A hook that runs on every file write and takes two seconds turns a
+forty-page ingest into a ninety-second pause, and you will disable it.
+
+Anything that needs judgement. Hooks are mechanical checks. A hook trying to
+decide whether a page is good enough will be wrong in both directions.
+
+## Keep them fast and quiet
+
+A hook should complete in well under a second and print nothing when it passes.
+Hooks that log on success train you to ignore hook output, which is the same as
+having no hooks the day one fails.
+
+## Failure behaviour
+
+Decide explicitly whether a failing hook blocks the operation.
+
+Validation hooks should block: a page that fails schema validation should not be
+written. Notification hooks should not: a failed notification is not a reason to
+lose the work.
+
+The bad case is a blocking hook that fails for an unrelated reason and silently
+stops your scheduled ingest for a week. Whatever blocks must be simple enough
+that it only fails for the reason it exists.
+
+## Next
+
+[Skills and slash commands](skills-and-commands.md)
diff --git a/docs/06-agents/safety-and-guardrails.md b/docs/06-agents/safety-and-guardrails.md
new file mode 100644
index 0000000..20ac33a
--- /dev/null
+++ b/docs/06-agents/safety-and-guardrails.md
@@ -0,0 +1,79 @@
+# Guardrails
+
+The rule this whole section rests on:
+
+**Keys, not prompts.**
+
+Telling an agent not to do something is a preference. It is not a boundary. If
+the agent technically can delete a file, empty a folder or send an email, then
+one day, in a context you did not anticipate, it will.
+
+Control what is possible at the permission level. Then the instruction in
+`CLAUDE.md` is a preference sitting on top of a boundary, rather than the only
+thing between your notes and a bad run.
+
+## Scope write access
+
+The agent needs write access to the vault. It does not need write access to your
+home directory, and a scheduled task running with broad filesystem permissions is
+a large blast radius for a small convenience.
+
+Same principle for connectors: read-only wherever the option exists. A calendar
+connector that can only read cannot cancel a meeting, no matter what a
+misinterpreted instruction says.
+
+## Never delete without a record
+
+Deletion is the one operation you cannot recover from by reading a diff, because
+the content is gone and only the absence remains.
+
+Rule: no page is deleted without a line in `log.md` naming it and why. Merges
+count as deletions. Applied consistently, a page that vanishes is always
+traceable, and "where did that page go" stops being an unanswerable question.
+
+## Git is the real safety net
+
+Every guardrail above is preventive. Git is what saves you when one fails.
+
+Commit before any run that writes at scale. Scheduled runs commit their own work.
+Then a bad ingest is `git checkout .`, and a bad merge is one revert.
+
+Read the diffs from scheduled runs occasionally, especially in the first weeks.
+That is how you learn what your agent actually does at 7am, which is reliably
+different from what you assumed.
+
+## Dry runs
+
+For anything that touches many files, run it once in report-only mode.
+
+```
+Do a dry run: list every page you would create, update or delete, and the links
+you would add. Write nothing.
+```
+
+The output takes a minute to read and catches misread instructions before they
+become four hundred edits.
+
+## Watch for scope creep
+
+Agents extend the job. Asked to ingest, an agent may also tidy an unrelated page,
+fix formatting, rename something for consistency. Each is defensible; together
+they mean you cannot tell what a run did without reading everything.
+
+Instruct explicitly: do the job asked, list anything else you noticed, change
+nothing else.
+
+## What not to put in the vault
+
+Credentials, API keys, anything you are under obligation to keep confidential,
+other people's private information.
+
+Not because the agent will leak it, but because the vault is a single file tree
+that gets synced, committed, backed up and occasionally shared. Every copy is
+another place that content exists. See
+[privacy](../09-maintenance/privacy-and-secrets.md).
+
+## Next
+
+[Retrieval](../07-retrieval/README.md), for getting answers out of what all this
+built.
diff --git a/docs/06-agents/scheduled-maintenance.md b/docs/06-agents/scheduled-maintenance.md
new file mode 100644
index 0000000..52433a8
--- /dev/null
+++ b/docs/06-agents/scheduled-maintenance.md
@@ -0,0 +1,79 @@
+# Scheduling
+
+Scheduled runs are what make the vault feel alive. You wake up and it has filed
+what you clipped, noticed a contradiction, and left you three lines about what
+changed.
+
+They are also unattended writes to your notes, so the order matters: get the
+[guardrails](safety-and-guardrails.md) right first, then schedule.
+
+## Cadence per job
+
+**Ingest, daily.** Overnight, on whatever accumulated in `raw/` during the day.
+Daily is right because a batch gives the agent a chance to notice that three
+things you saved are about the same idea. Hourly does not.
+
+**Link, weekly.** Connections need material to connect. Run it after a week of
+ingestion.
+
+**Lint, weekly.** After the linker, so it catches what that pass broke.
+
+**Review, weekly.** The one output you actually read. Put it on the morning you
+plan.
+
+**Metrics, monthly.** Four numbers appended to a note. See
+[metrics](../05-graphs/metrics.md).
+
+## Setting one up
+
+In Claude Desktop, the Schedule tab, then a new task:
+
+```
+Frequency: Daily, 7:00am
+Folder: your vault
+Prompt: File anything new in raw/ into the wiki following CLAUDE.md.
+ Link it to existing pages. Update index.md and log.md. Commit
+ with a message naming the run. Then write me three lines on
+ what changed.
+```
+
+Or ask for it in a session: "set up a daily task at 7am that ingests raw/ and
+summarises what changed".
+
+From a terminal, `cron` or Task Scheduler calling Claude Code headless works the
+same way, and is the better option if you want the run inside a git commit
+automatically.
+
+## What a run must produce
+
+Three things, every time.
+
+**A log entry.** Otherwise you cannot audit what happened while you were asleep.
+
+**A commit.** One per run, with the run named in the message. This is what makes
+a bad run revertible in one command instead of an evening.
+
+**A report to you.** Even one line. A scheduled task that produces nothing
+visible is one you stop trusting and then stop reading.
+
+## Detecting silent failure
+
+The failure mode is not a crash. It is a run that completes and does nothing
+useful: the source was empty, the API call failed halfway, the instructions
+matched no files.
+
+Two cheap checks. Have the run report counts, not just completion, so "ingested
+0 sources" is visible. And look at commit frequency once a month: a week with no
+commits from the daily task means it has been failing quietly since Tuesday.
+
+## Start manual
+
+Run each job by hand for a week before scheduling it. You are checking that the
+output is good enough to accept without reading it closely, because that is
+exactly what scheduling means.
+
+Schedule the ingest last. It is the one that writes most.
+
+## Next
+
+[Subagents and parallel work](subagents.md)
diff --git a/docs/06-agents/skills-and-commands.md b/docs/06-agents/skills-and-commands.md
new file mode 100644
index 0000000..99886f1
--- /dev/null
+++ b/docs/06-agents/skills-and-commands.md
@@ -0,0 +1,76 @@
+# Skills and slash commands
+
+Two mechanisms that look similar and do different jobs.
+
+**A skill** teaches repeatable behaviour. It loads when relevant and shapes how
+the agent does something, whether you invoked it explicitly or just described the
+task.
+
+**A command** is a shortcut for a task you run often. It points at a skill and
+saves you typing the instructions.
+
+The behaviour belongs in the skill. That way ingestion works the same whether it
+was triggered by `/ingest`, by a scheduled task, or by you saying "add this to my
+vault".
+
+## What this repo ships
+
+Four skills in [`skills/`](../../skills/README.md): ingest, lint, query, review.
+Five commands in [`commands/`](../../commands/README.md), each a few lines
+pointing at a skill.
+
+Install them inside the vault at `.claude/skills/` and `.claude/commands/` so
+they are versioned alongside your notes and travel with the vault.
+
+## Writing your own
+
+A skill worth writing has three properties: you do it repeatedly, you have
+opinions about how, and the opinions are not obvious enough for the model to
+guess.
+
+Structure that works:
+
+```markdown
+---
+name: skill-name
+description: >-
+ What it does. When to use it, written pushy, because agents under-trigger
+ skills. Do NOT use for the tempting near-misses.
+---
+
+# Name
+
+[Why this skill exists: what failure it prevents. This paragraph is the rubric
+for every case the rules below do not cover.]
+
+## Core rule
+## Workflow
+## Output format
+## Calibration
+## Example
+```
+
+The opening paragraph does more work than the rules. Rules cover the cases you
+thought of; the reason covers the rest.
+
+## Explain the why
+
+"Never overwrite a contradiction" gets applied literally and fails on the edge
+cases. "Never overwrite a contradiction, because the history of what you believed
+is the thing this vault has that a search engine does not" generalises to
+situations you never described.
+
+All-caps NEVER without a reason is usually a missing explanation.
+
+## Versioning
+
+Skills live in the vault, so git tracks them. When output quality changes, the
+skill diff is the first place to look.
+
+Test a skill on three or four real cases before letting a scheduled task use it.
+A flaw in a skill that runs nightly is a flaw in three hundred pages by the end
+of the year.
+
+## Next
+
+[Guardrails](safety-and-guardrails.md)
diff --git a/docs/06-agents/subagents.md b/docs/06-agents/subagents.md
new file mode 100644
index 0000000..28e5ae7
--- /dev/null
+++ b/docs/06-agents/subagents.md
@@ -0,0 +1,55 @@
+# Subagents and parallel work
+
+Subagents run with their own context. That is the whole point: a subagent
+reading thirty pages to answer a question does not fill the main session's
+context with those thirty pages, only with the answer.
+
+## When to fan out
+
+**Research across many pages.** Send a subagent to read a cluster and come back
+with a summary. The main session keeps its budget for the actual work.
+
+**Independent sources.** Ingesting ten unrelated articles parallelises cleanly,
+because none of them touch the same wiki pages.
+
+**Verification.** One agent writes, another checks the pages against the sources.
+Separate context is what makes the check meaningful; the same agent rereading its
+own work mostly agrees with itself.
+
+## When not to
+
+**Related sources.** Three articles about the same topic must be ingested
+sequentially. In parallel, each one creates the concept page independently and
+you get three versions of it, or two of them are overwritten.
+
+**Anything touching the index.** `index.md` and `log.md` are single files that
+every run wants to append to. Parallel writes to them conflict or silently lose
+entries.
+
+**Small jobs.** Spawning a subagent costs a full context setup. For two files it
+is slower than doing it directly.
+
+## Merging parallel work
+
+The rule that avoids most conflicts: subagents write to disjoint paths, the
+parent merges.
+
+Have each subagent report what it would write rather than writing shared files
+directly. The parent applies the index and log updates in one pass, after all
+subagents return. Page files themselves are safe to write in parallel as long as
+two subagents were never given overlapping material.
+
+Commit before any parallel run. When it goes wrong, it goes wrong across many
+files at once.
+
+## Cost
+
+Parallelism does not reduce total token use, it reduces wall-clock time and
+protects the main context. Four subagents cost roughly four times one.
+
+That trade is worth it for a large backfill and pointless for a daily ingest of
+five clipped articles.
+
+## Next
+
+[Hooks](hooks.md)
diff --git a/docs/README.md b/docs/README.md
index 81895a6..511b3da 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -11,7 +11,7 @@ Setup is written in full. The rest is being written section by section; see the
| [Ingestion](03-ingestion/README.md) | articles, video, PDFs, chat exports, voice, backfilling | **written** |
| [Structuring](04-structuring/README.md) | page types, linking rules, schema, contradictions | **written** |
| [Graphs](05-graphs/README.md) | what the graph is for, typed links, GraphRAG, metrics | **written** |
-| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails | in progress |
+| [Agents](06-agents/README.md) | roles, schedules, hooks, guardrails | **written** |
| [Retrieval](07-retrieval/README.md) | query patterns, search, context budget | in progress |
| [Outputs](08-outputs/README.md) | writing, reports, publishing, learning | in progress |
| [Maintenance](09-maintenance/README.md) | linting, review cadence, git, privacy, scaling | in progress |
diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md
index 83a5c03..2bf64ec 100644
--- a/docs/ROADMAP.md
+++ b/docs/ROADMAP.md
@@ -211,36 +211,36 @@ The part most second-brain guides skip: what the graph is for and how to make it
- Clusters as evidence of your real interests
- Tracking metrics over time
-## Agents (outline)
+## Agents (done)
Turning a one-off setup into a system that maintains itself.
-- [ ] **Agent roles**
+- [x] **Agent roles**
- Ingestor, linker, reviewer, researcher
- One job per agent and why
- Handoffs between agents
- Roles that are not worth automating
-- [ ] **Scheduling**
+- [x] **Scheduling**
- Cadence per job: hourly, daily, weekly
- Scheduled tasks, cron and CI options
- What a run should produce
- Detecting silent failures
-- [ ] **Subagents and parallel work**
+- [x] **Subagents and parallel work**
- When to fan out
- Context isolation between subagents
- Merging parallel edits without conflicts
- Cost of parallelism
-- [ ] **Hooks**
+- [x] **Hooks**
- Triggering on file changes in raw/
- Pre-write validation
- Post-run linting
- Keeping hooks fast
-- [ ] **Skills and slash commands**
+- [x] **Skills and slash commands**
- Skills for repeated behavior, commands for repeated tasks
- Where to store them so any agent can use them
- Versioning your skills alongside the vault
- Testing a skill before trusting it with the vault
-- [ ] **Guardrails**
+- [x] **Guardrails**
- Never let an agent delete without a log entry
- Write scopes: which folders are off limits
- Dry-run mode