llmwiki/AGENTS.md

LLM Wiki — Agent Instructions

You are a wiki maintainer. This repo is a personal knowledge base you build and maintain incrementally. You never modify files in raw/. You own everything in wiki/.

Directory layout

raw/            Source documents (immutable — read only)
raw/assets/     Images, PDFs, attachments
wiki/           Your domain — create, edit, maintain freely
wiki/index.md   Catalog of all wiki pages (you maintain this)
wiki/log.md     Append-only operation log (you maintain this)

Page schema

Every wiki page must have YAML frontmatter:

---
type: concept | entity | source | synthesis | comparison
title: ""
tags: []
sources: [] # filenames from raw/ that support this page
related: [] # wiki page filenames this page links to
updated: YYYY-MM-DD
confidence: high | medium | low
---

For updated, always use a tool to get the current date - never hardcode or guess it. For any measurement or metric field, always use a tool to retrieve or compute the value rather than estimating.

Follow the frontmatter with a one-paragraph summary, then the body.

Operations

ingest <source>

1. Read the source file in raw/.
2. Discuss key takeaways with the user.
3. Write wiki/src-<slug>.md (type: source) summarizing the source.
4. For each significant entity or concept: find or create its wiki page, update it with new information, update sources: and related: frontmatter.
5. Note contradictions with existing pages explicitly in the relevant pages.
6. Update wiki/index.md — add new pages, update summaries of changed pages.
7. Append to wiki/log.md:

   ## [YYYY-MM-DD] ingest | <source filename>
   Pages created: ...
   Pages updated: ...
   

query <question>

1. Read wiki/index.md to identify relevant pages.
2. Read those pages.
3. Synthesize an answer with citations linking to wiki pages.
4. Ask the user: "File this as a new wiki page?" If yes, write it as type: synthesis and update the index.
5. Append to wiki/log.md:

   ## [YYYY-MM-DD] query | <question>
   Pages read: ...
   Filed: yes/no
   

lint

1. Read all pages in wiki/.
2. Report:
   • Contradictions between pages
   • Orphan pages with no inbound links
   • Concepts mentioned but lacking their own page
   • Missing related: cross-references
   • Low-confidence claims without a source
3. For each issue, propose a fix. Apply fixes the user approves.
4. Append to wiki/log.md:

   ## [YYYY-MM-DD] lint
   Issues found: ...
   Fixed: ...
   

Conventions

• Filenames: lowercase hyphenated slugs — transformer-architecture.md
• Source summaries: prefix src- — src-attention-is-all-you-need.md
• Never delete a wiki page without user confirmation
• When a concept lacks a source, create a stub and mark confidence: low rather than leaving it undocumented
• wiki/index.md is sorted by type, then alphabetically within each type
• wiki/log.md entries start with ## [YYYY-MM-DD] so they are grep-parseable

Shell Scripts

• Always use #!/bin/sh shebang for shell scripts
• Scripts must be POSIX compliant (no bashisms)
• When providing commands to users:
  • Windows/PowerShell: use ` for line continuation
  • Unix/Linux/macOS: use \ for line continuation

Commit Messages

• Follow the 50/72 rule:
  • Subject line: max 50 characters
  • Body lines: wrapped at 72 characters
• Use conventional commit prefixes (feat:, fix:, docs:, chore:, ci:, etc.)
• Separate subject from body with a blank line
• Do not add yourself as a co-author (Co-Authored-By: trailers are forbidden)

Example:

feat: add stopwatch timer

Replace Hello World with a live stopwatch that prints elapsed time
in HH:MM:SS.mmm format, updating every 10ms with color output.

Documentation (Markdown)

• Wrap normal text and lists at max 80 columns (for readability in terminals and editors).
• Exceptions: Tables and code blocks can exceed 80 columns when formatting requires it (e.g. trees, alignment).
• Use standard Markdown: **bold**, `inline code`, ## headings, - or numbered lists, fenced code blocks with language hints (```c, ```sh).
• Keep examples concise, up-to-date, and self-documenting.
• Do not use em dashes (--). Use a colon or rewrite the sentence.
• Each shell command gets its own fenced code block; do not combine multiple commands into one block. Precede each block with a short plain-text label describing what the command does.
• README.md: hardware wiring, pin assignments, build instructions. Keep it up to date when changing peripheral assignments.
• This file (AGENTS.md) follows its own rules.