chore: document task tracking workflow with beans

Amp-Thread-ID: https://ampcode.com/threads/T-019cf255-639d-746e-9a46-c88c06cabe75
Co-authored-by: Amp <amp@ampcode.com>

Author: henriquebastos

.gitignore

@@ -34,3 +34,4 @@ dist/
 
 # Beans runtime
 beans.db
+.beans/

AGENTS.md

@@ -259,9 +259,54 @@ uv run ruff check src/ tests/
 The release workflow runs tests, publishes to PyPI, and updates the Homebrew formula.
 The package is `magic-beans` on PyPI, but the CLI is `beans` and the import is `import beans`.
 
+## Task Tracking with Beans
+
+This project uses beans itself for task tracking. Beans is the primary tool for managing
+work — use it to create, track, and close all tasks, bugs, and epics.
+
+### Before starting work
+
+```bash
+uv run beans ready              # see what's unblocked
+uv run beans show <id>          # read the full bean before starting
+```
+
+### Self-contained beans
+
+Every bean body must contain enough context for someone with no prior conversation to
+pick it up. Include: what needs to change, why, which files are involved, and what
+"done" looks like. Never rely on thread context or conversation history.
+
+### Working on a task
+
+```bash
+uv run beans claim <id> --actor <name>   # claim before starting
+# ... do the work ...
+uv run beans close <id>                  # close when done
+```
+
+### Creating beans
+
+Use `--body` to describe the task fully. Use `--parent` for subtasks. Use `beans dep add`
+to express ordering constraints. Choose meaningful types (task, bug, epic).
+
+```bash
+uv run beans create "Title" --body "Full description of what and why"
+uv run beans create "Subtask" --parent <epic-id>
+uv run beans dep add <blocker-id> <blocked-id>
+```
+
+### Bean hygiene
+
+- One bean per deliverable change
+- Close beans when done, don't leave them dangling
+- If a bean is no longer needed, close it with an update explaining why
+- If you discover new work while working on a bean, create a new bean for it
+
 ## Tools
 
 - **uv** — package management, running, building
+- **beans** — task tracking (`uv run beans ready`, `uv run beans list`)
 - **pytest** — testing with coverage (`--cov=beans`)
 - **ruff** — linting (line-length=120, select E,F,I,N,UP,RUF)
 - **git-cliff** — changelog generation from conventional commits

src/beans/templates/AGENTS.md

@@ -1,27 +1,48 @@
 # Beans — Agent Integration
 
-This project uses [beans](https://github.com/henriquebastos/beans) for issue tracking.
+This project uses [beans](https://github.com/henriquebastos/beans) for task tracking.
+Beans is the primary tool for managing work — always use it to create, track, and
+close tasks. Do not track work outside of beans.
 
-## Workflow
+## Before Starting Work
 
-Before starting work, check for available tasks:
+```bash
+beans ready                     # see what's unblocked
+beans show <id>                 # read the full bean before starting
+beans claim <id> --actor <name> # claim it
+```
+
+## Self-Contained Beans
+
+Every bean body must contain enough context for someone with no prior conversation to
+pick it up. Include: what needs to change, why, which files are involved, and what
+"done" looks like. Never rely on thread context or conversation history.
 
 ```bash
-beans ready
+beans create "Title" --body "Full description of what needs to happen and why"
 ```
 
-Claim a task before working on it:
+## Working on a Task
 
 ```bash
-beans claim <bean-id> --actor <your-name>
+beans claim <id> --actor <name>   # claim before starting
+# ... do the work ...
+beans close <id>                  # close when done
 ```
 
-When done, close the task:
+If you discover new work while working on a bean, create a new bean for it:
 
 ```bash
-beans close <bean-id>
+beans create "New task discovered" --body "Description" --parent <epic-id>
+beans dep add <blocker-id> <blocked-id>
 ```
 
+## Bean Hygiene
+
+- One bean per deliverable change
+- Close beans when done, don't leave them dangling
+- If a bean is no longer needed, close it with an update explaining why
+
 ## Commands Reference
 
 | Command | Description |
@@ -32,7 +53,10 @@ beans close <bean-id>
 | `beans create <title>` | Create a new bean |
 | `beans update <id>` | Update bean fields |
 | `beans close <id>` | Close a bean |
-| `beans claim <id>` | Claim a bean |
-| `beans release <id>` | Release a bean |
-| `beans dep add <from> <to>` | Add dependency |
+| `beans claim <id> --actor <name>` | Claim a bean |
+| `beans release <id> --actor <name>` | Release a bean |
+| `beans dep add <from> <to>` | Add dependency (from blocks to) |
 | `beans dep remove <from> <to>` | Remove dependency |
+| `beans schema` | Show JSON schemas for all models |
+
+Use `--json` on any command for structured output. Use `--body` on create/update for descriptions.