AGENTS.md - Way Into AI

This is a practical guide and knowledge base for documenting AI coding agents, tools, and related topics.

When Adding Entries

Before doing any work, read SKILL.md to understand the repository structure and patterns.

Quick Workflow

Read SKILL.md — first time working in this repo
Decide: Full reference entry or simple log?
Create ref entry (if applicable):
- Frontmatter with created: YYYY-MM-DD (today's date)
- Screenshot at top using screenshotit.app for any web content
- Follow structure in SKILL.md
Add log entry: 1-2 sentences in logs/YYYY-MM-DD.md

Pull, commit, push:

cd ~/src/datopian/wayintoai
git pull --rebase
git add ref/ logs/
git commit -m "Add: [Topic]"
git push

Critical Rules

Screenshots

ALWAYS include a screenshot at the top of ref entries for web content:

![Topic](https://screenshotit.app/https://example.com/url)

Place immediately after title/tagline, before Links section.

Log Entries

Maximum 1-2 sentences. Concise over comprehensive.

Log Entry H1 Titles

Every log file must have an H1 title in the format: # yyyy-mm-dd {Short Title}

The date comes from the filename
The title should be a brief, meaningful summary (3-8 words)
This ensures entries are recognizable when listed on the website

Every log file must also have date: YYYY-MM-DD in its frontmatter so Flowershow can sort the log listing newest-first. The date must match the filename.

Blog Posts

Every blog post in posts/ (excluding posts/index.md) must begin with:

---
title: A concise post title
description: A one-sentence summary used in listings and social metadata.
date: YYYY-MM-DD
---

The date must match the date prefix in the filename.
Do not repeat the title as an H1 in the body. Flowershow renders the frontmatter title as the page title.
Start the body with the opening paragraph, tagline, or screenshot as appropriate.
Keep title, description, and date accurate because the homepage and posts/index.md use them to render and sort post listings.

Frontmatter

Every ref entry needs:

---
created: YYYY-MM-DD  # Date added to repo (required)
author: Author Name
tags: [tag1, tag2, tag3]
---

Repository Structure

wayintoai/
├── ref/            # Full reference entries
├── logs/           # Daily logs (1-2 sentence summaries)
│   └── index.md    # Flowershow log listing
├── posts/          # Long-form articles with title/description/date frontmatter
│   └── index.md    # Flowershow post listing
├── SKILL.md        # Comprehensive guide (READ THIS)
└── AGENTS.md       # This file

See SKILL.md for Details

File naming conventions
Content structure
Screenshot placement and examples
Frontmatter requirements
Git workflow
Common patterns
Quality standards
Troubleshooting

Don't work from memory. Read SKILL.md when adding entries.

Changelog

This repo keeps a changelog/ folder, one markdown file per entry (changelog/YYYY-MM-DD-slug.md, with date/title/promote frontmatter). This changelog is only for platform and infrastructure changes—for example, a change to site behaviour, build/deployment, or repository tooling. Do not add editorial content changes to it; those belong in the site's ordinary content/logging flow.

At the end of a work session, if a platform or infrastructure change worth recording actually shipped—skip trivial sessions (typo fixes, dead ends, no visible outcome)—draft a new entry file. Match the entry's weight to what a reader would actually care about: a real platform feature or fix gets a title, one or two sentences, a link to the live feature if there is something to point at, and a screenshot if something visual shipped (check for this, do not just skip it); something genuinely bigger—a real milestone, not just a busy session—can run longer, with multiple paragraphs or bullets; small work (cleanup, rename, reorganisation, tidying) gets one plain sentence, with no bullets or screenshot. Never link the title itself. Do not log implementation detail (file names, internal moves) a reader would not care about. First time writing an entry in this repo, or if the format is unclear, fetch and follow https://raw.githubusercontent.com/life-itself/changelog/main/CONVENTION.md.

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.

File issues for remaining work - Create beads for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

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

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.

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.