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
|
|
@ -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,13 +139,14 @@ 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
|
||||||
---
|
---
|
||||||
title: "Strict String Title"
|
title: "Strict String Title"
|
||||||
type: source | entity | concept | query | conflict | private
|
type: source | entity | concept | query | conflict | private
|
||||||
domain: {{GENOME_NAME}}
|
domain: { { GENOME_NAME } }
|
||||||
tags: [lowercase, hyphen-separated]
|
tags: [lowercase, hyphen-separated]
|
||||||
maturity: draft | stable | deprecated
|
maturity: draft | stable | deprecated
|
||||||
last_updated: YYYY-MM-DD
|
last_updated: YYYY-MM-DD
|
||||||
|
|
@ -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`
|
||||||
|
|
@ -191,22 +205,26 @@ When new evidence contradicts an existing wiki claim:
|
||||||
---
|
---
|
||||||
title: "Conflict: <concept>"
|
title: "Conflict: <concept>"
|
||||||
type: conflict
|
type: conflict
|
||||||
domain: {{GENOME_NAME}}
|
domain: { { GENOME_NAME } }
|
||||||
maturity: draft
|
maturity: draft
|
||||||
last_updated: YYYY-MM-DD
|
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` |
|
||||||
|
|
|
||||||
Loading…
Add table
Reference in a new issue