Skip to content

AGENTS.md

Latest commit

 

History

History
75 lines (56 loc) · 3.18 KB

AGENTS.md

File metadata and controls

75 lines (56 loc) · 3.18 KB
Raw

Knowledge Base

A compiled knowledge wiki is available at docs/wiki/.

Session startup: Read wiki/INDEX.md for a topic overview, then read specific topic articles relevant to your current task.

Using coverage indicators: Each section has a coverage tag:

  • [coverage: high] -- trust this section, skip the raw files.
  • [coverage: medium] -- good overview, check raw sources for granular questions.
  • [coverage: low] -- read the raw sources listed in that section directly.

When you need depth: Check the article's Sources section for links to raw files. Only read raw sources for medium/low coverage sections or when you need very specific detail.

Never modify wiki files directly -- they are regenerated by /wiki-compile.

Yggdrasil Coordination

This project uses Yggdrasil (ygg) for cross-session memory and coordination. Hooks fire at Claude Code lifecycle events; you do not invoke them manually. Above each user prompt you will see [ygg memory | ... ] lines — those are real prior context surfaced by similarity.

Quick Reference

ygg task ready                              # Unblocked tasks in this repo
ygg task list [--all] [--status <...>]      # All tasks in this repo (or everywhere)
ygg task create "title"                     # New task
ygg task claim <ref>                        # Take a task
ygg task close <ref>                        # Complete a task
ygg task dep <task> <blocker>               # Record dependency
ygg remember "..."                          # Durable note; retriever can surface later

ygg status                                  # Agents + outstanding locks
ygg lock acquire <key> / release <key> / list
ygg spawn --task "..."                      # Parallel agent in a new tmux window
ygg interrupt take-over --agent <name>      # Take over another agent
ygg logs --follow                           # Live event stream

Rules

  • Acquire a lock before editing a resource another agent might touch. Release when done.
  • Prefer ygg spawn over a native Task/Agent tool for parallel work.
  • Read [ygg memory | ...] hints — real prior context.
  • Check ygg status before assuming you're working alone.
  • Use ygg task for cross-session work tracking; ygg remember for durable notes.
  • Do NOT use bd / beads.

PRs to main

Every PR to main is a release promotion. Title MUST start with feat: / fix: / perf: / revert: (optional (scope), optional ! for breaking) — these are the only types semantic-release acts on. Other prefixes (Release:, chore:, docs:, bare Bump…) are blocked by .github/workflows/pr-title-gate.yml and would otherwise leave releases/latest stale.

Session Completion

Work is not complete until git push succeeds. Release held locks, run quality gates, rebase, push, verify git status shows up-to-date.

Non-Interactive Shell Commands

Some systems alias cp/mv/rm to interactive mode which hangs agents. Use:

cp -f src dst     mv -f src dst     rm -f file     rm -rf dir     cp -rf src dst
# scp / ssh: -o BatchMode=yes         apt-get: -y         brew: HOMEBREW_NO_AUTO_UPDATE=1