--- name: beads-19ad8b5e7fea description: Use Beads to structure and execute work via epics, tasks, and dependencies license: MIT compatibility: opencode metadata: audience: coders --- ## Purpose Beads (`bd`) is my **external working memory** - a temporal graph that survives session restarts. I treat Beads as the single source of truth for: - what work exists - what blocks what - what is allowed to be worked on next - **context and decisions** (via descriptions and comments) The plan lives as **data**, not prose. I query instead of remember. --- ## ⚠️ CRITICAL: Hierarchical IDs I use hierarchical IDs to organize **related** work. The prefix is project-specific (e.g., `opencode`, `myapp`). **Independent work streams get their own top-level IDs:** ``` opencode-a1b2 (Epic: User Management) opencode-a1b2.1 (Task: Registration) opencode-a1b2.1.1 (Subtask: Email validation) opencode-a1b2.2 (Task: Profile editing) opencode-c3d4 (Epic: TUI System) opencode-c3d4.1 (Task: Layout engine) opencode-c3d4.2 (Task: Key bindings) opencode-c3d4.3 (Task: Theme support) ``` **To get the ID of a top-level issue:** ```bash # When creating - capture the ID bd create "User Management" -t epic -p 0 --silent # outputs: opencode-a1b2 bd q "Quick task title" # outputs: opencode-x7y8 # In a new session - find existing issues bd list -t epic # list all epics bd list --title "User" # filter by title bd search "User Management" # search across title/description/ID bd search "User" -t epic --json # JSON output for parsing ``` **When to use top-level epics/tasks:** - Independent features (User Management vs TUI vs CLI) - Unrelated bug fixes - Work that doesn't belong under any existing task **When to use hierarchy (children):** - Subtasks that break down a larger task - Work discovered while implementing a parent task - Features with multiple implementation steps --- ## Concepts ### Epics High-level goals. I create them but never work on them directly. **Always include a description with context, constraints, and acceptance criteria.** ```bash bd create "User Management" -t epic -p 0 -d "Complete user auth system with registration, login, and profile management. Must support OAuth providers." ``` ### Tasks Concrete, executable units of work. Tasks are the only issues I actively work on. Good tasks: - fit in one work session - produce a clear result - unblock other tasks **Top-level tasks (independent work):** ```bash bd create "CLI argument parsing" -p 1 -d "Parse --config, --verbose, --output flags using cobra" bd create "TUI layout engine" -p 1 -d "Flexbox-style layout system for terminal UI components" bd create "Config file loading" -p 2 -d "Load YAML/JSON config from ~/.config/app/" ``` **Child tasks (related to a parent):** ```bash bd create "User registration flow" -p 1 --parent opencode-a3f8 -d "Email/password registration with validation" bd create "Profile editing page" -p 1 --parent opencode-a3f8 -d "Allow users to update name, avatar, preferences" bd create "Email validation" -p 2 --parent opencode-a3f8.1 -d "Send verification email with token, validate on click" ``` Using `--parent` automatically assigns hierarchical IDs (e.g., `opencode-a3f8.1`, `opencode-a3f8.2`). ### Descriptions and Comments **Description** (`-d`): Initial context when creating an issue. ```bash bd create "User auth system" -t epic -p 0 -d "Implement full authentication flow including OAuth" ``` **Comments**: Ongoing updates, rules, progress notes. Use for: - Adding rules/constraints to epics - Progress updates - Implementation notes - Decisions made during work ```bash bd comment opencode-a3f8 "Rules for this epic: 1. All tasks must have unit tests 2. No task should take more than 4 hours" bd comment opencode-a3f8.1 "Decided to use JWT tokens instead of sessions" bd comments opencode-a3f8 # list all comments bd comments opencode-a3f8 --json # JSON output (returns array) ``` `bd show` displays both description and comments. ### Dependencies Edges that define execution order. Four types: | Type | Meaning | |------|---------| | **blocks** | Task A must complete before Task B starts | | **related** | Tasks are conceptually linked | | **parent-child** | Hierarchical organization (via `--parent`) | | **discovered-from** | Task found while working on another | ```bash bd dep add opencode-a3f8.2 opencode-a3f8.1 # opencode-a3f8.2 blocked by opencode-a3f8.1 ``` Note: Children already depend on their parent via hierarchy. Don't add explicit `discovered-from` to children - it will error. Example graph: ``` opencode-a3f8 (Epic: User Management) ├── opencode-a3f8.1 (Task: Registration) │ ↓ blocks │ opencode-a3f8.2 (Task: Profile editing) │ └── opencode-a3f8.1.1 (Subtask: Email validation) (inherits dependency from parent) ``` ### Graph-Based Structure - nodes = epics and tasks - edges = blocking relationships - order comes only from dependencies - priority affects choice among ready work, not execution order If order matters, it must be encoded as a dependency. --- ## Execution Loop ### 1. Start Session - Get Ready Work ```bash bd ready --json ``` Returns tasks that are open and have no unmet dependencies. **Only these are allowed to be worked on.** ### 2. Claim a Task **⚠️ MANDATORY: Always read the task with `bd show` BEFORE starting work. Read the description AND all comments - they contain critical context, decisions, and constraints.** ```bash bd show opencode-a3f8.1 # READ THIS FIRST - description + comments! bd update opencode-a3f8.1 -s in_progress ``` ### 3. Implement and Commit Code Add comments to record important decisions and progress: ```bash bd comment opencode-a3f8.1 "Using bcrypt for password hashing, cost factor 12" bd comment opencode-a3f8.1 "Decided against OAuth in this task - will be separate" ``` ### 4. Handle Discovered Work If I discover new work while implementing, I file it **immediately**: **As a subtask (child inherits dependency automatically):** ```bash bd create "Fix token refresh bug" -p 1 --parent opencode-a3f8.1 -d "Token expires but refresh fails silently - found during registration testing" # Creates opencode-a3f8.1.2 - automatically depends on parent ``` **As a separate task with discovered-from link:** ```bash bd create "Unrelated auth bug found" -p 1 --deps "discovered-from:opencode-a3f8.1" -d "Session cookie not set correctly on Safari - unrelated to registration" # For work that doesn't belong under the current task's hierarchy ``` Note: Children already inherit dependency from parent via hierarchy. Use `discovered-from` only for work that belongs elsewhere in the graph but was found while working on something. The `discovered-from` edge preserves causal history - how work unfolded over time. This is critical for maintaining context across sessions. ### 5. Close the Task ```bash bd close opencode-a3f8.1 -r "Completed registration flow" ``` Closing may unblock other tasks. Use `--suggest-next` to see newly unblocked work. --- ## JSON Output All `--json` outputs return **arrays**, even for single items: ```bash bd show opencode-a3f8.1 --json # returns [{ ... }] not { ... } bd update opencode-a3f8.1 -s in_progress --json # returns [{ ... }] bd list --json bd ready --json bd search "query" --json bd close opencode-a3f8.1 -r "done" --json ``` When parsing with `jq`, use `.[0]` to get the first element: ```bash bd show opencode-a3f8.1 --json | jq '.[0].title' # correct bd show opencode-a3f8.1 --json | jq '.title' # WRONG - will error ``` --- ## Batch Operations When making multiple changes, batch within 30 seconds: ```bash bd create "Fix validation bug" -p 1 --parent opencode-a3f8 -d "Form validation fails on special characters" bd create "Add unit tests" -p 2 --parent opencode-a3f8 -d "Cover registration and login flows" bd update opencode-a3f8.1 -s in_progress ``` --- ## Compaction For large projects, summarize old closed issues: ```bash bd compact --analyze --json # Get candidates for review bd compact --prune # Remove expired tombstones ``` This implements **"agentic memory decay"** - replacing detailed content with concise summaries. --- ## Rules 1. I only work on tasks, never epics 2. I use hierarchical IDs for related work, top-level IDs for independent work 3. I always respect dependencies 4. I never infer order from names or priority - order comes from edges 5. I always close tasks explicitly with `-r` reason 6. I NEVER drop discovered work - file immediately (as child or with `discovered-from`) 7. I always start sessions with `bd ready --json` 8. **I ALWAYS run `bd show` and READ description + comments before starting any task** 9. I always add descriptions (`-d`) when creating issues 10. I record decisions and context as comments during work **Beads is used to execute work deterministically, not to improvise.** --- ## Why This Matters Beads solves **session amnesia**. Without it: - I forget discovered work after compaction/restart - I re-discover the same tasks repeatedly - I declare victory at phase 3-of-6 because that's all I can "see" With Beads: - I query the plan instead of carrying it in context - `discovered-from` chains preserve how work unfolded over time - I can resume any session by running `bd ready --json` - Descriptions and comments preserve context and decisions for future sessions --- ## ⛔ NEVER DO THIS **NEVER run `git push`, `git commit`, or any git commands.** Git operations are handled by the human or by other tools. This skill is ONLY for managing work via `bd` commands. Do not touch git. --- Source attribution: David-Li0406 Original project: https://github.com/David-Li0406/meta-skill-evloving/blob/ca3a335628981df10c36e00cb9850df2c247ab9a/skill-flow/data/skills-refined-36k/skillsmp/beads-8/SKILL.md License: Apache-2.0 License information: https://www.apache.org/licenses/LICENSE-2.0 Original upstream instructions; downloaded from Mega AI Hub. ## Upstream license notice Apache License Version 2.0, January 2004 http://www.apache.org/licenses/ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION 1. Definitions. "License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document. "Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License. "Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity. "You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License. "Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files. "Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types. "Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below). "Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof. "Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution." "Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work. 2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form. 3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed. 4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions: (a) You must give any other recipients of the Work or Derivative Works a copy of this License; and (b) You must cause any modified files to carry prominent notices stating that You changed the files; and (c) You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and (d) If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License. 5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions. 6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file. 7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License. 8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages. 9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability. END OF TERMS AND CONDITIONS APPENDIX: How to apply the Apache License to your work. To apply the Apache License to your work, attach the following boilerplate notice, with the fields enclosed by brackets "[]" replaced with your own identifying information. (Don't include the brackets!) The text should be enclosed in the appropriate comment syntax for the file format. We also recommend that a file or class name and description of purpose be included on the same "printed page" as the copyright notice for easier identification within third-party archives. Copyright [yyyy] [name of copyright owner] Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. # Mega AI Hub resource metadata Creator / publisher: David-Li0406 Original project: https://github.com/David-Li0406/meta-skill-evloving/blob/ca3a335628981df10c36e00cb9850df2c247ab9a/skill-flow/data/skills-refined-36k/skillsmp/beads-8/SKILL.md Attribution basis: Source repository record Fields of work: Operations, Product Management, Project & Program Management Roles: Operations Manager, Product Manager, Project Manager Specialties: API Tools: Beads Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 14af55fb485c0949bb0a823cb728684155f88ba07c4cd25e2ac5537b929b222f