Beans Skill

Agent constraints (must-follow)

• Always create or switch to the bean's branch before editing code or files.

  • If a branch exists for the bean, checkout it first. If not, create and push a new branch following the repository branch naming rules.
  • Record the branch in the bean frontmatter immediately after creating or checking out the branch.

• Do not keep an internal agent todo list.

  • All task state and subtasks must live in the bean's ## Todo checklist in the bean body. The agent must update the bean ## Todo via MCP or extension commands and commit the bean to persist progress.

• Do not create or edit bean files by hand.

  • Use the MCP or extension commands for bean creation and edits; never write .md bean files directly to the repository.
  • The agent must not add custom frontmatter keys except branch and pr (PR number). Adding other custom fields is forbidden.

Starting work on a bean

1. Orient yourself first: @beans /next (what should I work on?) or @beans /search <keywords> (does a bean already exist?). Use beans.search if you know what you are looking for.
2. If none found, create one: beans.create → fill title, type, priority, description.
3. Set status to in-progress: beans.setStatus.
4. Create a branch named feature/<bean-id>-<slug> and push it.
5. Edit the bean to add branch: <name> to its frontmatter: beans.edit.
6. Commit the bean file with message: chore(beans): start <bean-id> — set branch.

During work

• Add a ## Todo checklist to the bean body on first edit.
• After each completed step: check off the item, beans.edit to save, commit bean with related code.
• If scope grows, create child beans with beans.create → beans.setParent to link them.

Completing or scrapping a bean

Complete:

1. Add ## Summary of Changes section to bean body via beans.edit.
2. beans.setStatus → completed.
3. Commit: chore(beans): complete <bean-id>.

Scrap:

1. Add ## Reasons for Scrapping section via beans.edit.
2. beans.setStatus → scrapped.
3. Commit: chore(beans): scrap <bean-id>.

VS Code extension command reference

Bean operations

Search and navigation

AI and workflow

beans.copilotStartWork templates: assess status, remaining steps, close/commit, export to GitHub issue, set in-progress, flesh out specs.

Configuration and help

Chat participant (@beans) guidance

@beans is the human-facing conversational interface. Use it for orientation, guidance, and structured workflows — especially when you need to reason about what to work on next, confirm an epic plan before acting, or draft a commit message. It reads beans and returns natural-language responses; it does not mutate state. To create, edit, or change status, use extension commands or MCP tools.

When to reach for @beans:

• Before starting work: /next or /priority to orient yourself
• Before creating an epic: use it to propose the issue map (step 3 of planning mode) and confirm with the user before creating anything
• After finishing a step: /commit to draft a conventional commit message with the right bean reference
• At any time: /summary or /stale for a workspace health check

Slash commands:

Follow-up suggestions — after any @beans response, VS Code surfaces quick-pick follow-ups for /summary, /priority, /stale, /create, and /commit. Use them to stay in flow without typing commands.

MCP tool guidance

Use MCP tools when automation is needed outside the VS Code UI:

1. Read context first — call beans_query with operation: "llm_context" (or equivalent view/search/filter/sort tools) before mutating anything.
2. Mutate with explicit intent — create, edit, set status/type/priority, manage relationships.
3. Destructive actions — delete and archive require explicit user confirmation.
4. Prefer MCP over the CLI for any scripted or agent-driven operation.

Planning mode: epic decomposition

When the user asks to plan an epic or decompose a feature:

Step 1 — Clarify

Ask (or confirm from context):

• What is the end goal?
• Are there known constraints (deadline, stack, scope limits)?
• What is the definition of done?
• Does an epic/milestone bean already exist, or should one be created?

Step 2 — Create the epic bean (if needed)

Use beans.create:

• Type: milestone
• Status: todo
• Title: concise epic name
• Body: goal statement + constraints + definition of done

Step 3 — Propose the issue map

Group proposed child issues by outcome phase. Present a compact checklist for user approval before creating anything:

- [ ] <title> — type=<task|feature|bug>, priority=<①–⑤>, depends_on=<bean-ids or none>

Child beans for an epic typically use task, feature, or bug types. epic and milestone are valid bean types in Beans, but reserve them for higher-level work or nested structures when the user explicitly asks for additional epics or milestones.

Example phases: Foundation, Implementation, Validation, Documentation, Deployment.

For each child issue include:

• Concise title (action-oriented)
• Type and priority
• One-line rationale
• Dependency chain (what must be done first)

Step 4 — Get approval

Do not create any beans until the user approves the plan. Present the issue map as a chat reply (this is an @beans conversation step, not a mutation). Ask for a quick pass:

• "Does the issue map look right? Any changes before I create these?"

Step 5 — Create child beans

For each approved child issue:

1. beans.create — set title, type, priority, and description.
2. beans.setParent — link to the epic bean.
3. beans.setStatus — set to todo (or in-progress for the first one the user wants to start immediately).

Step 6 — Commit the hierarchy

Commit the epic bean and all child bean files together:

chore(beans): plan <epic-bean-id> — <N> child issues

Step 7 — Return a summary

Reply with:

Epic:    <epic-id> <epic-title>
Created: <id> <title> [depends_on: <ids>]
         <id> <title>
         ...
Start with: <id> <title> — <one-line reason why>

CLI fallback (last resort only)

Use CLI only when extension, @beans, and MCP tools are all unavailable.

Hard constraints:

• Always use --json; never parse plain-text output.
• Never pass large body text as a shell argument; use GraphQL variables or pipe the query into beans graphql.
• One operation at a time; no chained destructive commands.

Allowed CLI command:

• beans graphql --json "<query>" [--variables <json>] (strictly use the GraphQL API for all data operations)
• beans archive <id> — only with explicit user request

Beans baseline

The following baseline is derived from beans graphql --schema and provides comprehensive guidance for working with beans in this project.

""" A bean represents an issue/task in the beans tracker """ type Bean { """ Unique identifier (NanoID) """