docs: update AGENTS.md template for ingest skill and clarity
This commit is contained in:
parent
3005366cfd
commit
2e06d8f4e8
1 changed files with 38 additions and 18 deletions
|
|
@ -2,11 +2,11 @@
|
|||
|
||||
## Identity
|
||||
|
||||
| Field | Value |
|
||||
|--------|-------|
|
||||
| Genome | `{{GENOME_NAME}}` |
|
||||
| Domain | `{{GENOME_DESC}}` |
|
||||
| Owner | `{{FORGEJO_USER}}` |
|
||||
| Field | Value |
|
||||
| ------ | -------------------------------------------------- |
|
||||
| Genome | `{{GENOME_NAME}}` |
|
||||
| Domain | `{{GENOME_DESC}}` |
|
||||
| Owner | `{{FORGEJO_USER}}` |
|
||||
| Remote | `{{FORGEJO_URL}}/{{FORGEJO_USER}}/{{GENOME_NAME}}` |
|
||||
|
||||
**Role:** Wiki maintainer for `{{GENOME_NAME}}`.
|
||||
|
|
@ -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.
|
||||
|
||||
### NEVER
|
||||
|
||||
- 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.
|
||||
- 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.
|
||||
|
||||
### ASK FIRST
|
||||
|
||||
- Deleting any wiki page.
|
||||
- Changing `maturity` from `stable` to `deprecated`.
|
||||
- Writing to `wiki/private/` when PRIVATE_CONTEXT state is ambiguous.
|
||||
|
|
@ -84,7 +86,8 @@ Execute in this order before any file operation:
|
|||
## Workflows
|
||||
|
||||
### Ingest
|
||||
*Triggered by new file in `raw/`.*
|
||||
|
||||
_Triggered by new file in `raw/`._
|
||||
|
||||
1. Read source once.
|
||||
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.
|
||||
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.
|
||||
- PR title: `[PRIVATE] ingest: <slug>`.
|
||||
|
||||
### Query
|
||||
*Triggered by operator question.*
|
||||
|
||||
_Triggered by operator question._
|
||||
|
||||
1. `qmd search "<query>"` → identify candidate pages.
|
||||
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.
|
||||
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
|
||||
*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.
|
||||
The script handles deterministically: broken links, knowledge decay, page size, frontmatter validation.
|
||||
|
|
@ -133,13 +139,14 @@ Append log entry: `LINT | <summary of findings>`.
|
|||
## File Conventions
|
||||
|
||||
### Frontmatter
|
||||
|
||||
Required on every wiki page:
|
||||
|
||||
```yaml
|
||||
---
|
||||
title: "Strict String Title"
|
||||
type: source | entity | concept | query | conflict | private
|
||||
domain: {{GENOME_NAME}}
|
||||
domain: { { GENOME_NAME } }
|
||||
tags: [lowercase, hyphen-separated]
|
||||
maturity: draft | stable | deprecated
|
||||
last_updated: YYYY-MM-DD
|
||||
|
|
@ -152,19 +159,25 @@ private: true | false
|
|||
- `deprecated` — superseded. Add `> **DEPRECATED:** <reason>` callout at top of body.
|
||||
|
||||
### Links
|
||||
|
||||
- Internal: `[[folder/file]]` — Obsidian wikilinks only. Never `[text](url)` for internal refs.
|
||||
- Cross-genome: `[[../genome-target/wiki/folder/file]]`.
|
||||
- External: `[text](https://...)`.
|
||||
|
||||
### Index entries
|
||||
|
||||
Append at bottom of relevant section in `wiki/index.md`:
|
||||
|
||||
```
|
||||
- [[folder/slug]] — One-line summary. `maturity: draft`
|
||||
```
|
||||
|
||||
Never reorder. Alphabetical sort is handled by the pre-commit hook.
|
||||
|
||||
### Log entries
|
||||
|
||||
Append one entry per operation to `wiki/log.md`:
|
||||
|
||||
```markdown
|
||||
## [YYYY-MM-DD] TYPE | Subject
|
||||
|
||||
|
|
@ -174,6 +187,7 @@ Append one entry per operation to `wiki/log.md`:
|
|||
- output_written: `[[path/C]]`
|
||||
- reasoning: One sentence — what changed and why.
|
||||
```
|
||||
|
||||
Valid TYPEs: `INGEST` `LINT` `QUERY` `CONFLICT` `CONFIG` `SECURITY`
|
||||
|
||||
Parse: `grep "^## \[" wiki/log.md | tail -5`
|
||||
|
|
@ -191,22 +205,26 @@ When new evidence contradicts an existing wiki claim:
|
|||
---
|
||||
title: "Conflict: <concept>"
|
||||
type: conflict
|
||||
domain: {{GENOME_NAME}}
|
||||
domain: { { GENOME_NAME } }
|
||||
maturity: draft
|
||||
last_updated: YYYY-MM-DD
|
||||
private: false
|
||||
---
|
||||
```
|
||||
|
||||
```markdown
|
||||
## Conflict: <concept>
|
||||
|
||||
**Claim A (existing):** [[path/to/existing-page]]
|
||||
|
||||
> Summary of current wiki position.
|
||||
|
||||
**Claim B (new):** [[path/to/new-source]]
|
||||
|
||||
> Summary of contradicting evidence.
|
||||
|
||||
**Assessment:**
|
||||
|
||||
- Confidence A: high | medium | low — <reason>
|
||||
- Confidence B: high | medium | low — <reason>
|
||||
- Recommendation: `accept_b` | `keep_a` | `requires_human_review`
|
||||
|
|
@ -226,20 +244,22 @@ private: false
|
|||
- `maturity: draft` not updated in **90 days** → flag during lint.
|
||||
|
||||
Flagged pages: prepend to body:
|
||||
|
||||
```markdown
|
||||
> **⚠️ STALE:** Last validated {{last_updated}}. Re-validation required.
|
||||
```
|
||||
|
||||
Propose re-validation task. Do not change `maturity` without new source evidence.
|
||||
|
||||
---
|
||||
|
||||
## Collaboration
|
||||
|
||||
| Role | Access | Permitted |
|
||||
|------|--------|-----------|
|
||||
| Owner | Full — key holder | Read/write everywhere |
|
||||
| Collaborator | No key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` |
|
||||
| Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` |
|
||||
| Cloud AI model | Public only | `PRIVATE_CONTEXT` must be `disabled`; never send private files outside local network |
|
||||
| Role | Access | Permitted |
|
||||
| -------------- | ----------------- | ------------------------------------------------------------------------------------ |
|
||||
| Owner | Full — key holder | Read/write everywhere |
|
||||
| Collaborator | No key | Push to `raw/articles`, `raw/transcripts`, `raw/code-packs`, `raw/assets` |
|
||||
| Local AI agent | Conditional | `private/` only when `PRIVATE_CONTEXT: enabled` |
|
||||
| Cloud AI model | Public only | `PRIVATE_CONTEXT` must be `disabled`; never send private files outside local network |
|
||||
|
||||
Grant collaborator: add as Forgejo contributor with Write role. Never share the git-crypt key.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue