docs: update AGENTS.md template for ingest skill and clarity

This commit is contained in:
Matteo Cherubini 2026-06-03 12:28:18 +02:00
parent 3005366cfd
commit 2e06d8f4e8

View file

@ -3,7 +3,7 @@
## Identity ## Identity
| Field | Value | | Field | Value |
|--------|-------| | ------ | -------------------------------------------------- |
| Genome | `{{GENOME_NAME}}` | | Genome | `{{GENOME_NAME}}` |
| Domain | `{{GENOME_DESC}}` | | Domain | `{{GENOME_DESC}}` |
| Owner | `{{FORGEJO_USER}}` | | Owner | `{{FORGEJO_USER}}` |
@ -55,6 +55,7 @@ Session end or return to `disabled`: remind operator to run `git-crypt lock` on
8. Every PR must use `templates/pr-description.md`. Do not omit the tabular summary. 8. Every PR must use `templates/pr-description.md`. Do not omit the tabular summary.
### NEVER ### NEVER
- Load `wiki/log.md` in full — read only the tail injected by the orchestrator. - Load `wiki/log.md` in full — read only the tail injected by the orchestrator.
- Rewrite `wiki/index.md` to reorder entries — append only; sorting is automated. - Rewrite `wiki/index.md` to reorder entries — append only; sorting is automated.
- Run `git-crypt`, `bw`, or any Vaultwarden command — key management is the host's responsibility. - Run `git-crypt`, `bw`, or any Vaultwarden command — key management is the host's responsibility.
@ -62,6 +63,7 @@ Session end or return to `disabled`: remind operator to run `git-crypt lock` on
- Merge PRs — human approval required. - Merge PRs — human approval required.
### ASK FIRST ### ASK FIRST
- Deleting any wiki page. - Deleting any wiki page.
- Changing `maturity` from `stable` to `deprecated`. - Changing `maturity` from `stable` to `deprecated`.
- Writing to `wiki/private/` when PRIVATE_CONTEXT state is ambiguous. - Writing to `wiki/private/` when PRIVATE_CONTEXT state is ambiguous.
@ -84,7 +86,8 @@ Execute in this order before any file operation:
## Workflows ## Workflows
### Ingest ### Ingest
*Triggered by new file in `raw/`.*
_Triggered by new file in `raw/`._
1. Read source once. 1. Read source once.
2. Create `wiki/sources/<slug>.md` — summary + key points. 2. Create `wiki/sources/<slug>.md` — summary + key points.
@ -96,12 +99,14 @@ Execute in this order before any file operation:
8. Run scoped lint on pages created or modified in this session. Report issues in PR description. Do not auto-fix. 8. Run scoped lint on pages created or modified in this session. Report issues in PR description. Do not auto-fix.
9. Commit on `feat/ai-ingest-<slug>`. Open PR using `templates/pr-description.md`. 9. Commit on `feat/ai-ingest-<slug>`. Open PR using `templates/pr-description.md`.
*Private source* (`PRIVATE_CONTEXT: enabled` required): _Private source_ (`PRIVATE_CONTEXT: enabled` required):
- All output → `wiki/private/<slug>.md` only. - All output → `wiki/private/<slug>.md` only.
- PR title: `[PRIVATE] ingest: <slug>`. - PR title: `[PRIVATE] ingest: <slug>`.
### Query ### Query
*Triggered by operator question.*
_Triggered by operator question._
1. `qmd search "<query>"` → identify candidate pages. 1. `qmd search "<query>"` → identify candidate pages.
2. Read candidate pages directly. 2. Read candidate pages directly.
@ -110,10 +115,11 @@ Execute in this order before any file operation:
5. Append entry to `wiki/index.md` under Queries. 5. Append entry to `wiki/index.md` under Queries.
6. Append log entry: `QUERY | <subject>`. 6. Append log entry: `QUERY | <subject>`.
*For general orientation without a specific query: read `wiki/index.md` directly.* _For general orientation without a specific query: read `wiki/index.md` directly._
### Lint ### Lint
*Triggered by operator with bash pre-scan output.*
_Triggered by operator with bash pre-scan output._
Pre-requisite: operator runs `bash scripts/lint-genomes.sh` and provides output to this session. Pre-requisite: operator runs `bash scripts/lint-genomes.sh` and provides output to this session.
The script handles deterministically: broken links, knowledge decay, page size, frontmatter validation. The script handles deterministically: broken links, knowledge decay, page size, frontmatter validation.
@ -133,6 +139,7 @@ Append log entry: `LINT | <summary of findings>`.
## File Conventions ## File Conventions
### Frontmatter ### Frontmatter
Required on every wiki page: Required on every wiki page:
```yaml ```yaml
@ -152,19 +159,25 @@ private: true | false
- `deprecated` — superseded. Add `> **DEPRECATED:** <reason>` callout at top of body. - `deprecated` — superseded. Add `> **DEPRECATED:** <reason>` callout at top of body.
### Links ### Links
- Internal: `[[folder/file]]` — Obsidian wikilinks only. Never `[text](url)` for internal refs. - Internal: `[[folder/file]]` — Obsidian wikilinks only. Never `[text](url)` for internal refs.
- Cross-genome: `[[../genome-target/wiki/folder/file]]`. - Cross-genome: `[[../genome-target/wiki/folder/file]]`.
- External: `[text](https://...)`. - External: `[text](https://...)`.
### Index entries ### Index entries
Append at bottom of relevant section in `wiki/index.md`: Append at bottom of relevant section in `wiki/index.md`:
``` ```
- [[folder/slug]] — One-line summary. `maturity: draft` - [[folder/slug]] — One-line summary. `maturity: draft`
``` ```
Never reorder. Alphabetical sort is handled by the pre-commit hook. Never reorder. Alphabetical sort is handled by the pre-commit hook.
### Log entries ### Log entries
Append one entry per operation to `wiki/log.md`: Append one entry per operation to `wiki/log.md`:
```markdown ```markdown
## [YYYY-MM-DD] TYPE | Subject ## [YYYY-MM-DD] TYPE | Subject
@ -174,6 +187,7 @@ Append one entry per operation to `wiki/log.md`:
- output_written: `[[path/C]]` - output_written: `[[path/C]]`
- reasoning: One sentence — what changed and why. - reasoning: One sentence — what changed and why.
``` ```
Valid TYPEs: `INGEST` `LINT` `QUERY` `CONFLICT` `CONFIG` `SECURITY` Valid TYPEs: `INGEST` `LINT` `QUERY` `CONFLICT` `CONFIG` `SECURITY`
Parse: `grep "^## \[" wiki/log.md | tail -5` Parse: `grep "^## \[" wiki/log.md | tail -5`
@ -197,16 +211,20 @@ last_updated: YYYY-MM-DD
private: false private: false
--- ---
``` ```
```markdown ```markdown
## Conflict: <concept> ## Conflict: <concept>
**Claim A (existing):** [[path/to/existing-page]] **Claim A (existing):** [[path/to/existing-page]]
> Summary of current wiki position. > Summary of current wiki position.
**Claim B (new):** [[path/to/new-source]] **Claim B (new):** [[path/to/new-source]]
> Summary of contradicting evidence. > Summary of contradicting evidence.
**Assessment:** **Assessment:**
- Confidence A: high | medium | low — <reason> - Confidence A: high | medium | low — <reason>
- Confidence B: high | medium | low — <reason> - Confidence B: high | medium | low — <reason>
- Recommendation: `accept_b` | `keep_a` | `requires_human_review` - Recommendation: `accept_b` | `keep_a` | `requires_human_review`
@ -226,9 +244,11 @@ private: false
- `maturity: draft` not updated in **90 days** → flag during lint. - `maturity: draft` not updated in **90 days** → flag during lint.
Flagged pages: prepend to body: Flagged pages: prepend to body:
```markdown ```markdown
> **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required. > **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required.
``` ```
Propose re-validation task. Do not change `maturity` without new source evidence. Propose re-validation task. Do not change `maturity` without new source evidence.
--- ---
@ -236,7 +256,7 @@ Propose re-validation task. Do not change `maturity` without new source evidence
## Collaboration ## Collaboration
| Role | Access | Permitted | | Role | Access | Permitted |
|------|--------|-----------| | -------------- | ----------------- | ------------------------------------------------------------------------------------ |
| Owner | Full — key holder | Read/write everywhere | | Owner | Full — key holder | Read/write everywhere |
| Collaborator | No key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` | | Collaborator | No key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` |
| Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` | | Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` |