Skip to content

AGENTS.md

Latest commit

 

History

History
111 lines (84 loc) · 4.82 KB

AGENTS.md

File metadata and controls

111 lines (84 loc) · 4.82 KB
Raw

AI Agent Instructions for Wails v3

Issue Tracking with GitHub

IMPORTANT: GitHub Issues and pull requests are the authoritative trackers for this project. Do not create a parallel local issue database or markdown task list.

Workflow for AI Agents

  1. Search existing GitHub issues and pull requests before creating new work.
  2. Link implementation work to the relevant issue or pull request.
  3. File newly discovered actionable work as a GitHub issue with reproduction details, scope, and acceptance criteria.
  4. Use labels, milestones, and cross-references to express priority, release scope, and dependencies.
  5. Close issues only after the work is complete and verified; otherwise document why the item is deferred or no longer applicable.

Important Rules

  • Do not duplicate existing GitHub issues.
  • Keep issue descriptions current when scope or reproduction steps change.
  • Store AI-generated planning documents in history/, not the repository root.
  • ALWAYS run coderabbit --plain before committing to catch issues early.
  • All commits must use the taliesin-ai identity.
  • Never push until the user gives explicit manual confirmation.

Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

  • PLAN.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 ephemeral 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

Frontend Runtime: Two Build Outputs

The TypeScript runtime in v3/internal/runtime/desktop/@wailsio/runtime produces two independent artifacts, and rebuilding one but not the other is a common and confusing mistake:

task output consumed by
task v3:runtime:build:assets v3/internal/assetserver/bundledassets/runtime.js (+ .debug.js) the webview, served at /wails/runtime.js
task v3:runtime:build:package dist/ in the package directory an app's frontend, via node_modules

After changing anything under src/, rebuild both. CI verifies the committed bundles match build:assets output exactly, so the bundles must be committed with the change.

An application imports @wailsio/runtime from npm, so it will not see runtime changes made in this checkout. To test an app against the working tree:

task v3:install-runtime -- ./path/to/your-app/frontend

Undo with npm install @wailsio/runtime@latest in the same directory.

Subsystem References

Some subsystems have a dedicated internals page written for agents. Read the relevant one before changing that code — several of its decisions look arbitrary until you know which measured bug they prevent.

  • Streams (pkg/application/stream*.go, runtime/.../stream.ts): docs/mpress/content/guides/advanced/streams-internals.md. Covers the held-poll design, the buffer constants and how to pick them, session and connection lifecycle, transport selection, and what is unfinished. To convert an existing WebSocket implementation, follow docs/mpress/content/guides/streams-from-websockets.md — a mechanical checklist, including the differences that break silently.

Landing the Plane (Session Completion)

When ending a work session, complete the applicable steps below. Never push without explicit manual confirmation from the user.

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. Prepare for remote sync: 
    git status
    When the worktree is clean and synchronization is intended, run git pull --rebase. Run git push only after the user explicitly confirms it.
  5. Clean up - Review stashes and remove only obsolete ones; prune remote branches
  6. Verify - All intended changes are present and committed when requested
  7. Hand off - Provide context for next session

CRITICAL RULES:

  • Use the taliesin-ai identity for every commit.
  • Do not push without explicit manual confirmation.
  • Report clearly whether changes are uncommitted, committed locally, or pushed.