Skip to content

AGENTS.md

Latest commit

 

History

History
101 lines (70 loc) · 6.92 KB

AGENTS.md

File metadata and controls

101 lines (70 loc) · 6.92 KB
Raw

Codex Instructions

Beads Issue Tracker

Use Beads (bd) for durable task tracking in repositories that include it. Use the beads skill at .agents/skills/beads/SKILL.md (project install) or ~/.agents/skills/beads/SKILL.md (global install) for Beads workflow guidance, then use the bd CLI for issue operations.

Quick Reference

bd ready                # Find available work
bd show <id>            # View issue details
bd update <id> --claim  # Claim work
bd close <id>           # Complete work
bd prime                # Refresh Beads context

Rules

  • Use bd for all task tracking; do not create markdown TODO lists.
  • Run bd prime when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use /hooks to inspect or toggle them.
  • Keep persistent project memory in Beads via bd remember; do not create ad hoc memory files.

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

  • Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
  • Run bd prime for detailed command reference and session close protocol
  • Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Agent Context Profiles

The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.

  • Conservative (default): Use bd for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
  • Minimal: Keep tool instruction files as pointers to bd prime; use the same conservative git policy unless active instructions say otherwise.
  • Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.

Session Completion

This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.

  1. File issues for remaining work - Create beads for anything that needs follow-up
  2. Run quality gates (if code changed) - Tests, linters, builds
  3. Update issue status - Close finished work, update in-progress items
  4. Handle git/sync by active profile: 
    # Conservative/minimal/default: report status and proposed commands; wait for approval.
git status

# Team-maintainer opt-in only, unless current instructions forbid it:
git pull --rebase
bd dolt push
git push
git status
  5. Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step

Critical rules:

  • Explicit user or orchestrator instructions override this Beads block.
  • Do not commit or push without clear authority from the active profile or the current user request.
  • If a required sync or push is blocked, stop and report the exact command and error.

Site architecture

This repository is the source for https://40ants.com/. The active generator is StatiCL (Common Lisp), not Coleslaw. .staticlrc defines the site, navigation, theme, and generation pipeline. qlfile and qlfile.lock define the Qlot environment, including StatiCL. .coleslawrc, plugins-old/, and static/clonify.lisp describe or implement the older Coleslaw setup; do not use them as the source of truth for the current build.

Content lives in *.page and *.post files. English posts are in posts/, Russian posts in ru/posts/, and other pages are at the repository root or under ru/. Each content file begins with metadata between ;;;;; delimiters (title, created-at, format, optional description and tags), followed by the body. Most posts use format: md; some pages use format: spinneret. Images referenced by Russian posts are under ru/posts/images/. The <!--more--> marker appears in some posts and controls the excerpt/“Read more” split used by the index template.

The .staticlrc pipeline loads content, then runs separate ru/ and non-ru/ branches for previous/next links, tag indexes, paginated post indexes, RSS, and Atom. These branches write to ru/posts/ and posts/ respectively; the final sitemap stage generates sitemap.xml. Changes to routing, pagination, feeds, or sitemap generation belong in .staticlrc or the upstream StatiCL implementation, not in individual posts.

The active theme is themes/the40ants/, declared by .staticlrc and themes/the40ants/theme.lisp. Its Closure Templates are the shared HTML layer:

  • base.tmpl: document shell, <head>, page title, description meta tag, language attribute, analytics, navigation, and shared assets. It currently reads {$site.lang} and emits a description only when $content.description exists; there is no canonical link in this template.
  • post.tmpl: individual post heading, body, tags, date, and previous/next links.
  • index.tmpl: archive/index heading, post list, excerpts, “Read more” links, and pagination. It renders each post title as an h1; change this template for archive heading structure, while excerpt length may also require content markers or generator changes.

Theme assets, including robots.txt, CSS, JavaScript, and images, are in the same directory. For site-wide SEO fixes, inspect the generated HTML as well as the relevant template and .staticlrc; a change to a post alone cannot fix a shared <head> or archive layout.

Build and publication

The authoritative build command is the one in .github/workflows/build.yml: after qlot install, run qlot exec .qlot/bin/staticl generate. The generated output is stage/ (ignored by Git). The workflow runs on pushes to develop and on a weekly schedule, then publishes stage/ with the gh-pages tool. Check representative generated English and Russian pages, an archive page, and stage/sitemap.xml after template or pipeline changes. Do not edit generated stage/ files as source.