gza AGENTS.md

Gza

A coding AI agent runner for Claude Code. Keep AGENTS.md under 100 lines. Move details to docs/. This file is for critical agent behavioral rules only.

Essential Commands

Always use uv run gza (not gza directly or python -m gza).

gza add "prompt"          # Add a task (default type: implement)
gza work [-b]             # Run next pending task (-b for background)
gza next                  # List pending tasks
gza history               # List recent completed/failed tasks
gza advance               # Progress unmerged tasks through lifecycle
gza lineage <id>          # Show task's ancestor/descendant tree
gza migrate [--status]    # Run manual DB migrations (e.g. v25/v26 task-ID migrations)

See docs/ for detailed documentation:

• docs/configuration.md — full command list, all options, config reference
• docs/skills.md — skill usage and authoring
• docs/docker.md — Docker setup, custom Dockerfiles, provider auth
• docs/merge-policy.md — review severity and merge-gate policy (BLOCKER blocks merge; FOLLOWUP ships with follow-up)
• docs/internal/ — internal architecture, design notes & practices (index); writing/maintaining docs: writing-docs.md

Critical Rules

Task management: When the user mentions "task", "add a task", or asks to track something for later, use uv run gza add "...". NEVER edit etc/todo.txt or other files manually.

Default to filing a gza task: When the user asks for a substantive code change (a feature, fix, or refactor), file it with uv run gza add rather than editing inline — do NOT start editing right away. Work in-line only when the user explicitly says to, or for trivial edits. If unsure which way they want it, ask before implementing.

Config example artifacts: If you change any discoverable config key/default, regenerate src/gza/gza.yaml.example and src/gza/gza.local.yaml.example via uv run gza config example --write and uv run gza config example --local --write, then commit them.