generated from eblume/project-template
Erich Blume
d36ed18590
Some checks failed
Build / validate (pull_request) Failing after 1m12s
The Neovim plugin now lives at eblume/hephaestus.nvim (plugin at the repo root). Remove heph.nvim/ from the monorepo and the build/test wiring that referenced it: - Dagger: drop the test_nvim function + the pinned-Neovim NVIM_VERSION - build.yaml: drop the `dagger call test-nvim` step - drop the mise run test-nvim task and .stylua.toml + the stylua prek hook (no Lua remains in the monorepo) - install-heph.md: install via a plain lazy.nvim spec pointing at the plugin repo over SSH (no more local-dir checkout hack) - README / AGENTS / heph-nvim.md: note the surface lives in its own repo The CLI/TUI -> nvim integration is unchanged (they shell out to `nvim` expecting the heph plugin installed). The v1-prototype tech-spec §14 build record and prior changelog fragments are left as frozen history. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
68 lines
4.6 KiB
Markdown
68 lines
4.6 KiB
Markdown
# 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 root) plus repo tooling. Backend feature-complete (all three runtime modes + sync + OIDC); three daily-driver surfaces — `heph` (CLI) and `heph-tui` (agenda/triage) in this workspace, plus the `hephaestus.nvim` Neovim plugin (context/KB) in its own forge repo, [eblume/hephaestus.nvim](ssh://forgejo@forge.ops.eblu.me:2222/eblume/hephaestus.nvim.git).
|
|
|
|
```
|
|
./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
|
|
./docs/ # Diataxis docs (incl. [[design]] + [[v1-prototype-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`
|
|
```
|
|
|
|
**TDD:** failing test first → implement to green → commit on green. `heph-core` is clock-injected (no ambient wall-clock; time is passed in). Spec: [[v1-prototype-tech-spec]] (frozen v1 build record); rationale: [[design]] (living). Other doc paths via `mise run ai-docs`; `[[like-this]]` wiki-links refer to `docs/` cards.
|
|
|
|
## Working state (heph self-hosts its roadmap)
|
|
|
|
Outstanding/future heph work lives as tasks in the **`Hephaestus` project** — inspect it before planning:
|
|
|
|
- `heph list --project Hephaestus` — outstanding tasks (human-readable)
|
|
- `heph list --project Hephaestus --json` — JSON rows: `node_id`, `canonical_context_id`, attention/state/do_date/recurrence (for scripting/agents)
|
|
- `heph task "<title>" --project Hephaestus -a blue` — capture new work (blue = on-deck backlog)
|