# AGENTS.md

Guidance for Claude Code working in this repository. See also [[ai-assistance-guide]].

## Overview

**hephaestus** — Personal context management system: wiki-style knowledge base and task management.

> **This is a generated repo, not the template source.** C1/C2 changes use feature branches + PRs (`tea pr create`); noteworthy changes get changelog fragments in `docs/changelog.d/`.

## Rules

1. **Always run `mise run ai-docs` at session start**
    This will refresh your context with important information you will be assumed to know and follow.
    **Read the full output** — never truncate, pipe to `head`/`tail`, or skip sections.
2. **Classify the change as C0/C1/C2 before starting** (see below) — this determines branching and PR requirements
3. **Generated repos use feature branches + PRs for C1/C2** — checkout main, pull, create branch, open PR via `tea pr create`. This template source repo usually stays C0/direct-to-main so it remains clean and templatable.
4. **Use changelog fragments in generated repos, not as template residue** — `docs/changelog.d/<name>.<type>.md`
    Types: `feature`, `bugfix`, `infra`, `doc`, `ai`, `misc`
    - **Generated repos:** add fragments for noteworthy changes
    - **This template repo:** keep `docs/changelog.d/` empty except for `.gitkeep`
5. **Never commit secrets**

## Change Classification

Before starting work, classify the change:

| Class | Name | When to use | Key trait |
|-------|------|-------------|-----------|
| **C0** | Quick Fix | Small, low-risk, fix-forward safe | Direct to main, no PR |
| **C1** | Human Review | Moderate complexity or risk | Feature branch + PR, docs-first |
| **C2** | Mikado Chain | Multi-phase, multi-session, high complexity | Mikado Branch Invariant |

**C0** — commit directly to main. No branch or PR needed. Fix forward if problems arise.

**C1** — in generated repos, use a feature branch with an early PR. In this template source repo, prefer direct cleanups unless the user explicitly wants branch-based review. Search related docs first, write documentation changes before code. Upgrade to C2 if complexity spirals.

**C2** — branch `mikado/<chain-stem>` governed by the Mikado Branch Invariant: all card commits first, then code progress, then card closures. Commits use `C2(<chain>): plan/impl/close/finalize` convention. Reset the branch when new prerequisites are discovered. Resume with `mise run docs-mikado --resume`.

See [[agent-change-process]] for the full methodology.

## Project Structure

A Cargo workspace (`Cargo.toml` at the root) plus the Neovim plugin and repo tooling. The build follows the tech-spec §11.1 slice order; the **Rust backend is feature-complete** (all three runtime modes + sync + OIDC auth) — the remaining v1 work is `heph.nvim`. The live progress tracker is **[[tech-spec]] §14**.

```
./Cargo.toml            # workspace manifest (shared deps + members)
./crates/heph-core/     # core lib: data model, Store trait + SQLite store, extraction,
                        #   recurrence, "what is next?" ranking, op-log/HLC/CRDT (yrs) sync
./crates/hephd/         # daemon: local/server/client modes — unix-socket RPC + HTTP sync/rpc + OIDC auth
./crates/heph/          # CLI (thin client of hephd): next/task/doc/get/export/search/journal/auth
./heph.nvim/            # Neovim plugin (planned, next slice): primary surface; replaces obsidian.nvim
./docs/                 # Diataxis docs (incl. [[design]] + [[tech-spec]]), Quartz config, release content
./docs/changelog.d/     # towncrier fragments for noteworthy changes
./.dagger/              # Dagger module (src/hephaestus_ci/) backing docs builds and releases
./.forgejo/workflows/   # build + release workflows
./.forgejo/scripts/     # per-project build/release hooks (build runs cargo test once present)
./mise-tasks/           # repo automation via `mise run`
```

**Development is TDD** (tech-spec §2, §9): failing test first, implement to green, commit on green. `heph-core` is clock-injected — no ambient wall-clock reads; time is always passed in. Canonical spec is [[tech-spec]]; rationale is [[design]].

Other doc paths are listed via `mise run ai-docs`. Wiki-links (`[[like-this]]`) refer to `docs/` cards.