using beans

EXTREMELY IMPORTANT: Beans Usage Guide for Agents

This project uses beans, an agentic-first issue tracker. Issues are called "beans", and you can use the "beans" CLI to manage them.

Whenever you're tempted to use the TodoWrite or similar tool to organize work, consider using beans instead.

All commands support --json for machine-readable output. Use this flag to parse responses easily.

CRITICAL: Track All Work With Beans

BEFORE starting any task the user asks you to do:

1. FIRST: Create a bean with beans create "Title" -t <type> -d "Description..." -s in-progress
2. THEN: Do the work
3. FINALLY: Mark completed with beans update <bean-id> --status completed
4. IF and WHEN you COMMIT: Include both your code changes AND the bean file(s) in the commit!

If you identify something that should be changed or fixed after completing the user's request, create a new bean for that work instead of doing it immediately.

Core Rules

• Use beans query for flexible data access - Supports both queries and mutations via GraphQL
• CLI commands are simpler for common operations - beans create and beans update are easier for single mutations
• After compaction or clear, run beans prime to re-sync
• Lean towards using sub-agents for interacting with beans

Finding work

Use GraphQL to query for actionable beans (not completed, not draft, not blocked):

beans query '{ beans(filter: { excludeStatus: ["completed", "scrapped", "draft"], isBlocked: false }) { id title status type priority } }'

Other useful queries:

# All beans with basic info
beans query '{ beans { id title status type priority } }'

# Find high-priority bugs
beans query '{ beans(filter: { type: ["bug"], priority: ["critical", "high"] }) { id title status body } }'

# Search by text (uses Bleve query syntax)
beans query '{ beans(filter: { search: "authentication" }) { id title } }'

Working on a bean

1. Read the bean using GraphQL to get full details:

   beans query '{ bean(id: "<id>") { title status type body parent { title } children { title status } } }'
   

2. Mark as in-progress: beans update <bean-id> --status in-progress
3. Adhere to the instructions in the bean's body when working on it

If the bean has a checklist:

1. Work through items in order (unless dependencies require otherwise)
2. After completing each checklist item, immediately update the bean file to mark it done:
   • Change - [ ] to - [x] for the completed item
3. When committing code changes, include the updated bean file with checked-off items
4. Re-read the bean periodically to stay aware of remaining work

Relationships

Beans can have relationships to other beans. Use these to express dependencies and hierarchy.

Parent (single value):

• parent - assigns a bean to a parent bean (type-restricted hierarchy: milestone → epic → feature → task/bug)

Blocking (multiple values):

• blocking - this bean is blocking another bean (prevents work on the blocked bean until this one is done)

Managing relationships (CLI):

• beans update <bean-id> --parent <other-id> - Set the parent
• beans update <bean-id> --remove-parent - Remove the parent
• beans update <bean-id> --blocking <other-id> - Add a blocking relationship
• beans update <bean-id> --remove-blocking <other-id> - Remove a blocking relationship

Querying relationships (GraphQL):

# Get a bean with its relationships
beans query '{ bean(id: "abc") { title parent { id title } children { id title status } blockedBy { title } blocking { title } } }'

# Filter children by status (e.g., only incomplete children of a milestone)
beans query '{ bean(id: "abc") { title children(filter: { excludeStatus: ["completed", "scrapped"] }) { id title status } } }'

# Find active blockers (exclude completed ones)
beans query '{ bean(id: "abc") { blockedBy(filter: { excludeStatus: ["completed"] }) { id title } } }'

# Find beans blocked by something
beans query '{ beans(filter: { isBlocked: true }) { id title blockedBy { title } } }'

# Find top-level beans (no parent)
beans query '{ beans(filter: { noParent: true }) { id title type } }'

Creating new beans

• beans create --help
• Example: beans create "Fix login bug" -t bug -d "Users cannot log in when..." -s todo
• Always specify a type with -t. See the "Issue Types" section below for available types and their descriptions.
• When creating a new bean, first see if a similar bean already exists.
• When creating new beans, include a useful description. If you're not sure what to write, ask the user.
• Make the description as detailed as possible, similar to a plan that you would create for yourself.
• If possible, split the work into a checklist of GitHub-Formatted-Markdown tasks. Use a ## Checklist header to precede it.

Cleaning up beans

• beans archive will archive (delete) beans marked as completed or scrapped. ONLY run this when I explicitly tell you to.

GraphQL Reference

The beans query command executes GraphQL queries. This is the preferred way to read bean data.

Command flags:

• --json: Output raw JSON (no formatting)
• --schema: Print the GraphQL schema
• -v, --variables: Query variables as JSON string
• -o, --operation: Operation name for multi-operation documents

Tips:

# Read query from stdin (useful for complex queries or shell escaping)
beans query <<'EOF'
{ beans(filter: { type: ["bug"], excludeStatus: ["completed"] }) { id title priority } }
EOF

# Create a new bean
beans query 'mutation { createBean(input: { title: "Fix bug", type: "bug", status: "todo" }) { id title } }'

# Update a bean's status
beans query 'mutation { updateBean(id: "beans-abc", input: { status: "completed" }) { id status } }'

# Set a bean's parent
beans query 'mutation { setParent(id: "beans-abc", parentId: "beans-xyz") { id parent { title } } }'

# Print the full schema for reference
beans query --schema

GraphQL Schema:

"""
A bean represents an issue/task in the beans tracker
"""
type Bean {
  """
  Unique identifier (NanoID)
  """
  id: ID!
  """
  Human-readable slug from filename
  """
  slug: String
  """
  Relative path from .beans/ directory
  """
  path: String!
  """
  Bean title
  """
  title: String!
  """
  Current status (draft, todo, in-progress, completed, scrapped)
  """
  status: String!
  """
  Bean type (milestone, epic, bug, feature, task)
  """
  type: String!
  """
  Priority level (critical, high, normal, low, deferred)
  """
  priority: String!
  """
  Tags for categorization
  """
  tags: [String!]!
  """
  Creation timestamp
  """
  createdAt: Time!
  """
  Last update timestamp
  """
  updatedAt: Time!
  """
  Markdown body content
  """
  body: String!
  """
  Parent bean ID (optional, type-restricted)
  """
  parentId: String
  """
  IDs of beans this bean is blocking
  """
  blockingIds: [String!]!
  """
  Beans that block this one (incoming blocking links)
  """
  blockedBy(filter: BeanFilter): [Bean!]!
  """
  Beans this one is blocking (resolved from blockingIds)
  """
  blocking(filter: BeanFilter): [Bean!]!
  """
  Parent bean (resolved from parentId)
  """
  parent: Bean
  """
  Child beans (beans with this as parent)
  """
  children(filter: BeanFilter): [Bean!]!
}
"""
Filter options for querying beans
"""
input BeanFilter {
  """
  Full-text search across slug, title, and body using Bleve query syntax.
  
  Examples:
  - "login" - exact term match
  - "login~" - fuzzy match (1 edit distance)
  - "login~2" - fuzzy match (2 edit distance)
  - "log*" - wildcard prefix
  - "\"user login\"" - exact phrase
  - "user AND login" - both terms required
  - "user OR login" - either term
  - "slug:auth" - search only slug field
  - "title:login" - search only title field
  - "body:auth" - search only body field
  """
  search: String
  """
  Include only beans with these statuses (OR logic)
  """
  status: [String!]
  """
  Exclude beans with these statuses
  """
  excludeStatus: [String!]
  """
  Include only beans with these types (OR logic)
  """
  type: [String!]
  """
  Exclude beans with these types
  """
  excludeType: [String!]
  """
  Include only beans with these priorities (OR logic)
  """
  priority: [String!]
  """
  Exclude beans with these priorities
  """
  excludePriority: [String!]
  """
  Include only beans with any of these tags (OR logic)
  """
  tags: [String!]
  """
  Exclude beans with any of these tags
  """
  excludeTags: [String!]
  """
  Include only beans with a parent
  """
  hasParent: Boolean
  """
  Include only beans with this specific parent ID
  """
  parentId: String
  """
  Include only beans that are blocking other beans
  """
  hasBlocking: Boolean
  """
  Include only beans that are blocking this specific bean ID
  """
  blockingId: String
  """
  Include only beans that are blocked by others
  """
  isBlocked: Boolean
  """
  Exclude beans that have a parent
  """
  noParent: Boolean
  """
  Exclude beans that are blocking other beans
  """
  noBlocking: Boolean
}
"""
Input for creating a new bean
"""
input CreateBeanInput {
  """
  Bean title (required)
  """
  title: String!
  """
  Bean type (defaults to 'task')
  """
  type: String
  """
  Status (defaults to 'todo')
  """
  status: String
  """
  Priority level (defaults to 'normal')
  """
  priority: String
  """
  Tags for categorization
  """
  tags: [String!]
  """
  Markdown body content
  """
  body: String
  """
  Parent bean ID (validated against type hierarchy)
  """
  parent: String
  """
  Bean IDs this bean is blocking
  """
  blocking: [String!]
}
type Mutation {
  """
  Create a new bean
  """
  createBean(input: CreateBeanInput!): Bean!
  """
  Update an existing bean
  """
  updateBean(id: ID!, input: UpdateBeanInput!): Bean!
  """
  Delete a bean by ID (automatically removes incoming links)
  """
  deleteBean(id: ID!): Boolean!
  """
  Set or clear the parent of a bean (validates type hierarchy)
  """
  setParent(id: ID!, parentId: String): Bean!
  """
  Add a bean to the blocking list
  """
  addBlocking(id: ID!, targetId: ID!): Bean!
  """
  Remove a bean from the blocking list
  """
  removeBlocking(id: ID!, targetId: ID!): Bean!
}
type Query {
  """
  Get a single bean by ID (supports prefix matching)
  """
  bean(id: ID!): Bean
  """
  List beans with optional filtering
  """
  beans(filter: BeanFilter): [Bean!]!
}
scalar Time
"""
Input for updating an existing bean
"""
input UpdateBeanInput {
  """
  New title
  """
  title: String
  """
  New status
  """
  status: String
  """
  New type
  """
  type: String
  """
  New priority
  """
  priority: String
  """
  Replace all tags (nil preserves existing)
  """
  tags: [String!]
  """
  New body content
  """
  body: String
}

Issue Types

This project has the following issue types configured. Always specify a type with -t when creating beans:

• milestone: A target release or checkpoint; group work that should ship together
• epic: A thematic container for related work; should have child beans, not be worked on directly
• bug: Something that is broken and needs fixing
• feature: A user-facing capability or enhancement
• task: A concrete piece of work to complete (eg. a chore, or a sub-task for a feature)

Statuses

This project has the following statuses configured:

• in-progress: Currently being worked on
• todo: Ready to be worked on
• draft: Needs refinement before it can be worked on
• completed: Finished successfully
• scrapped: Will not be done

Priorities

Beans can have an optional priority. Use -p when creating or --priority when updating:

• critical: Urgent, blocking work. When possible, address immediately
• high: Important, should be done before normal work
• normal: Standard priority
• low: Less important, can be delayed
• deferred: Explicitly pushed back, avoid doing unless necessary

Beans without a priority are treated as normal priority for sorting purposes.