Add agent guidance

.gitignore

@@ -2,3 +2,7 @@
 
 ## Dart
 .dart_tool/
+
+## JetBrains
+.idea/
+*.iml

AGENTS.md

@@ -0,0 +1,91 @@
+# Dew Agent Guidance
+
+This document provides guidelines and rules for agents contributing to the
+Dew project. It outlines the expected behavior, coding standards, and
+collaboration practices to ensure a productive and respectful environment for
+all contributors.
+
+## General Guidelines
+
+- The references directory should be used for storing external resources,
+  temporary files, and other things the agent needs that aren't part of the
+  actual project. This can include things like documentation, clones of other
+  repositories, screenshots, and other resources that may be helpful for
+  development but are not part of the final codebase.
+- Avoid duplicating existing code or functionality. The footprint of the
+  operating system should be as small as possible while still remaining
+  readable and maintainable. Generally this means all features should be
+  implemented as though they will be used by other features, and that code
+  should be reused where possible.
+- All code should be well-documented, with clear comments explaining the
+  purpose and functionality of each component. This is especially important for
+  security-related features, where clarity can help prevent vulnerabilities.
+- Use language-appropriate API documentation comments for public modules,
+  types, and functions (for example Rustdoc in Rust and doc comments in Dart).
+- Follow each language and framework's idiomatic conventions and best practices
+  to ensure consistency and readability across the codebase.
+- Prefer strong, explicit types (for example enums/sealed types) over ad-hoc
+  constants when modeling related sets of values.
+- Use pattern matching and type-system features where available to handle
+  different cases clearly and safely.
+- Constants are acceptable for defining fixed values that are not part of a
+  related set, such as configuration parameters or hardware addresses, but
+  should be used judiciously to avoid cluttering the codebase with unnecessary
+  constants.
+
+## Project Management
+
+- Every task should be clearly defined and documented in the
+  `.project/kanban/` board and managed through Dew.
+- Ticket lifecycle operations (create, list, move, update, comment, archive,
+  links) should be performed through the Dew MCP tools when available.
+- Do not manage ticket state by hand-editing board files unless doing one-off
+  migration, import, or recovery work.
+- If a task is not documented, create a new ticket in Dew before starting work
+  so progress is tracked and visible.
+- Where possible, `TODO` comments should reference a ticket by including the
+  ticket's unique identifier in the comment. This helps maintain a clear
+  connection between the code and the project management system, making it
+  easier to track progress and understand the context of each task.
+- The `.project/kanban/{backlog,doing,done,archive}/` directories are the
+  board columns. Tickets in progress belong in `doing`, and completed work is
+  moved to `done`.
+- Ticket filenames are `<PREFIX>-NNNN.md` and must match the ticket `id` in
+  frontmatter.
+- Frontmatter should contain the following fields:
+  - `id`: A unique identifier for the task.
+  - `title`: A brief title summarizing the task.
+  - `type`: Ticket type identifier (for example `epic`, `story`, `task`,
+    `bug`, or `spike`).
+  - `created`: RFC3339 timestamp for ticket creation.
+- After the front matter comes the markdown content, which should provide a
+  detailed description of the task, including any relevant information,
+  requirements, or context needed for completion.
+- Do not include a `column` field in frontmatter; the column is determined by
+  the ticket file's directory.
+- Comments may be stored in the ticket by appending them to the end of the
+  markdown content, separated from the description and other comments by a
+  horizontal rules (`---`) for clarity. Each comment should include the
+  author's name, and the content of the comment.
+- Tickets that need attachments should have a directory created in
+  `.project/kanban/attachments/` with the same name as the ticket file (without
+  the `.md` extension), and the attachment should be stored in that directory.
+  The attachment can then be referenced in the markdown content of the ticket
+  using a relative path.
+
+## Tooling and Commands
+
+- This repository uses a root `justfile` for common development workflows. Run
+  `just --list` to see the available recipes.
+- Respect the root `.editorconfig` for cross-editor whitespace and line-ending
+  behavior.
+- Treat any analyzer/linter finding (`info`, `warning`, or `error`) as a
+  blocking issue: fix it before merging unless it is objectively impossible.
+  If a finding must remain, ask for explicit approval first and gate the exception
+  with a `TODO` comment that explains why the issue is intentionally deferred.
+- Use `melos run format` to format Dart packages in the workspace.
+- Use `melos run fix` to apply automatic fixes from Dart static analysis.
+- Use `melos run analyze` to run Dart static analysis.
+- Use `melos run test` to run Dart tests across workspace packages.
+- Use `markdownlint-cli2 .` to check for markdown style issues in documentation
+  files so the repo's configured ignores are applied.