Agent skill
openspec-to-beads
Convert OpenSpec artifacts (proposal.md, design.md, tasks.md, specs/) into self-contained Beads issues for implementation tracking. Use when you have completed OpenSpec planning artifacts and need to create trackable implementation tasks, or when converting any specification or design document into actionable Beads issues.
Install this agent skill to your Project
npx add-skill https://github.com/moogah/claude_skills/tree/main/openspec-to-beads
SKILL.md
OpenSpec to Beads Conversion
Convert OpenSpec design artifacts into self-contained Beads issues for implementation.
Critical Principle
Beads must be self-contained. Extract and embed relevant context from OpenSpec rather than referencing it. Agents need complete context within the bead description.
What to Include in Each Bead
Every bead description should contain:
- Implementation steps - Specific files to modify, code patterns to follow
- Design context - Architectural rationale, technology choices
- Acceptance criteria - How to verify completion
- Related context - Background needed to understand the task
Simple Task Example
bd create "Add TypeScript strict mode to stack config" \
-t task -p 2 -l typescript,oncall-background-processes
bd update beads-xxx --description "Enable TypeScript strict mode for oncall-background-processes-stack.
Files to modify:
- stacks/oncall-background-processes-stack/tsconfig.json
Changes:
1. Add 'strict: true' to compilerOptions
2. Add 'strictNullChecks: true' (redundant but explicit)
3. Ensure 'noImplicitAny: true' is present
Design rationale: Strict mode catches type errors early and improves code quality. This stack uses CDK infrastructure code where type safety is critical for preventing runtime deployment errors.
Verification:
- Run bash scripts/type-check.sh
- Confirm no new type errors introduced
- Existing type errors in this stack are acceptable (document count if any)"
Complex Task Example
bd create "Implement dual-write for ShiftUpdate Lambda" \
-t task -p 1 -l migration,lambda,apollo
bd update beads-xxx --description "Add Apollo dual-write support to ShiftUpdateIntegration Lambda.
Files to modify:
- dynamodb-event-functions/ShiftUpdateIntegration/index.js
- dynamodb-event-functions/ShiftUpdateIntegration/shift-update-integration-stack.ts
Implementation steps:
1. Import layer modules in index.js:
const { executeAssignmentDayOperation } = require('/opt/nodejs/assignment-day-migration-manager');
const { updateAssignmentDayInApollo } = require('/opt/nodejs/apollo-assignment-day-mutations');
2. Wrap existing updateAssignmentDay() with dual-write pattern:
- appSyncOperation: existing GraphQL call
- apolloOperation: call updateAssignmentDayInApollo() with companyId
- Pass to executeAssignmentDayOperation()
3. Update stack file bundling config:
- Add layer modules to externalModules array
- Ensure amplifyLayer is attached
Design pattern: Use established dual-write migration pattern (see NotifyAdminsOnAccept for reference). The migration manager handles feature flag logic for routing to AppSync vs Apollo based on APOLLO_OPERATIONS env var.
Environment behavior:
- NONE: AppSync only
- DUALWRITE: Both APIs, prefer AppSync result (except company 8)
- APPLOI_QA: Company 8 → Apollo, others → AppSync
- ON: All companies → Apollo
Verification:
- Confirm Lambda builds without errors
- Check CloudWatch logs for dual-write execution
- Run bash scripts/type-check.sh"
Label Conventions
Use the OpenSpec change name as a label:
# If OpenSpec change is "refresh-dev-cycle-docs"
bd create "Update README with new workflow" \
-t task -p 2 -l refresh-dev-cycle-docs,docs
# Makes querying easy
bd list --label refresh-dev-cycle-docs
Dependency Handling
Add dependencies when tasks must be sequenced:
# Task Y depends on X completing first
bd dep add beads-yyy beads-xxx
Common dependency patterns:
- Infrastructure before application code
- Data migrations before feature rollout
- Shared utilities before dependent features
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
moogah/claude_skills
characterization-testing
Guide for characterization testing - capturing current system behavior to enable safe refactoring. Use when working with legacy code, undocumented systems, or code that needs modification but lacks tests. Helps create a safety net before making changes by testing what the code actually does (not what it should do).
moogah/claude_skills
bead-implementation
Execute on a Beads issue with proper discovery workflow and mandatory session close protocol. Use when starting work on a bead, during implementation when discovering new work that should be externalized, or when completing a session to ensure all work is properly committed.
moogah/claude_skills
architecture-analyzer
Perform in-depth architectural analysis of codebases through iterative dialog and visual diagrams. Use when users want to understand their software architecture, explore design patterns and anti-patterns, evaluate potential architectural changes, or gain deep insights into code structure and relationships. Particularly valuable for onboarding to unfamiliar codebases, assessing technical debt, planning refactoring efforts, or understanding how components interact across system boundaries.
moogah/claude_skills
github-actions-troubleshooting
Troubleshoot and fix failing GitHub Actions pipeline steps. Use when user reports a failing pipeline with error output.
moogah/claude_skills
skill-learner
Reviews conversation context to identify learnings and patterns that should be captured in skills. Use when the user asks to review the session for skill creation or updates.
moogah/claude_skills
writing-elisp
Comprehensive guidance for writing high-quality, idiomatic, modern Emacs Lisp code with incremental validation. Use when writing or modifying elisp functions, especially complex nested forms with cl-loop, multiple let* bindings, or lambdas. Covers modern features, naming conventions, documentation standards, error handling, code quality, and performance.
Didn't find tool you were looking for?