wails/AGENTS.md

AI Agent Instructions for Wails v3

Issue Tracking with bd (beads)

IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why bd?

• Dependency-aware: Track blockers and relationships between issues
• Git-friendly: Auto-syncs to JSONL for version control
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)

Claim and update:

bd update bd-42 --status in_progress --json
bd update bd-42 --priority 1 --json

Complete work:

bd close bd-42 --reason "Completed" --json

Issue Types

• bug - Something broken
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature with subtasks
• chore - Maintenance (dependencies, tooling)

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (default, nice-to-have)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Workflow for AI Agents

1. Check ready work: bd ready shows unblocked issues
2. Claim your task: bd update <id> --status in_progress
3. Work on it: Implement, test, document
4. Discover new work? Create linked issue:
   • bd create "Found bug" -p 1 --deps discovered-from:<parent-id>
5. Complete: bd close <id> --reason "Done"
6. Commit together: Always commit the .beads/issues.jsonl file together with the code changes so issue state stays in sync with code state

Auto-Sync

bd automatically syncs with git:

• Exports to .beads/issues.jsonl after changes (5s debounce)
• Imports from JSONL when newer (e.g., after git pull)
• No manual export/import needed!

GitHub Copilot Integration

If using GitHub Copilot, also create .github/copilot-instructions.md for automatic instruction loading. Run bd onboard to get the content, or see step 2 of the onboard instructions.

MCP Server (Recommended)

If using Claude or MCP-compatible clients, install the beads MCP server:

pip install beads-mcp

Add to MCP config (e.g., ~/.config/claude/config.json):

{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

Then use mcp__beads__* functions instead of CLI commands.

Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

• PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
• DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
• TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

Best Practice: Use a dedicated directory for these ephemeral files

Recommended approach:

• Create a history/ directory in the project root
• Store ALL AI-generated planning/design docs in history/
• Keep the repository root clean and focused on permanent project files
• Only access history/ when explicitly asked to review past planning

Example .gitignore entry (optional):

# AI planning documents (ephemeral)
history/

Benefits:

• Clean repository root
• Clear separation between ephemeral and permanent documentation
• Easy to exclude from version control if desired
• Preserves planning history for archeological research
• Reduces noise when browsing the project

CLI Help

Run bd <command> --help to see all available flags for any command. For example: bd create --help shows --parent, --deps, --assignee, etc.

Important Rules

• Use bd for ALL task tracking
• Always use --json flag for programmatic use
• Link discovered work with discovered-from dependencies
• Check bd ready before asking "what should I work on?"
• Store AI planning docs in history/ directory
• Run bd <cmd> --help to discover available flags
• ALWAYS run coderabbit --plain before committing to get code analysis and catch issues early
• Do NOT create markdown TODO lists
• Do NOT use external issue trackers
• Do NOT duplicate tracking systems
• Do NOT clutter repo root with planning documents

For more details, see README.md and QUICKSTART.md.

Implementation Tracking (IMPLEMENTATION.md)

IMPORTANT: The IMPLEMENTATION.md file at the repository root is a persistent tracking document for the WebKitGTK 6.0 / GTK4 implementation work. It is NOT an ephemeral planning document.

Requirements

1. Update with EVERY commit that touches GTK4/WebKitGTK 6.0 related code
2. Track all architectural decisions with context, decision, and rationale
3. Maintain progress status for each implementation phase
4. Document API differences between GTK3 and GTK4
5. Keep file references accurate and up-to-date

What to Update

• Phase completion status (✅ COMPLETE, 🔄 IN PROGRESS, 📋 PENDING)
• New decisions made during implementation
• Files created or modified
• Changelog entries with dates
• TODO items discovered during work

Commit Message Pattern

When updating IMPLEMENTATION.md:

docs: update implementation tracker for [phase/feature]

Landing the Plane (Session Completion)

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues 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. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd sync
   git push
   git status  # MUST show "up to date with origin"
   

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say "ready to push when you are" - YOU must push
• If push fails, resolve and retry until it succeeds