Skip to content

README.md

Latest commit

 

History

History
354 lines (263 loc) · 12.2 KB

README.md

File metadata and controls

354 lines (263 loc) · 12.2 KB

SpecBeads

SpecBeads

Connecting specification-driven development with agent memory

Spec Kit Beads Research-Backed AI Optimization Experimental MIT License

Spec Kit     ⟷     Beads

🧪 This is an Experiment

This is an experimental project exploring how two incredible open-source tools can work together. The concepts here could be applied to any AI agent that supports GitHub Spec Kit — not just Claude Code.

🙏 Standing on the Shoulders of Giants

🌱 GitHub Spec Kit

The Brain — Planning & Principles

  • 📋 Spec-first — Focus on what and why before how
  • ⚖️ Constitution management — Define project principles once
  • 🔄 Multi-step refinement — Not one-shot code generation
  • 🤖 Agent agnostic — Works with 15+ AI agents
  • 🚀 90+ releases — Active development by GitHub

🔗 Beads by Steve Yegge

The Memory — Execution & Tracking

  • 🧠 Agent memory — No more forgotten context between sessions
  • 🔗 4 dependency types — blocks, related, parent-child, discovered-from
  • ⚡ Ready work detection — bd ready finds unblocked tasks
  • 📦 Git-distributed — No server needed, syncs via git
  • 🛡️ Multi-agent safe — Hash-based IDs prevent merge conflicts

What is SpecBeads?

SpecBeads is a thin orchestration layer that connects these two tools:

  • Spec Kit provides the planning — specs, plans, tasks, and constitutional principles
  • Beads provides the execution — issue tracking, dependencies, and agent memory
  • SpecBeads provides bidirectional sync — keeping both in harmony
flowchart LR
    subgraph SPECKIT["🌱 SPEC KIT"]
        direction TB
        SPEC["spec.md"]
        PLAN["plan.md"]
        TASKS["tasks.md"]
    end

    subgraph BRIDGE["🌉 SPECBEADS"]
        direction TB
        SYNC["Bidirectional Sync"]
        MAP[".beads-mapping.json"]
        CONST["constitution.md"]
    end

    subgraph BEADS["🔗 BEADS"]
        direction TB
        ISSUES["issues.jsonl"]
        READY["bd ready"]
        CLOSE["bd close"]
    end

    TASKS <-->|"/speckit.taskstobeads"| SYNC
    SYNC <--> MAP
    MAP <-->|"Task ↔ Issue IDs"| ISSUES
    CONST -->|"Enforces principles"| IMPL
    READY --> IMPL["/speckit.implementwithbeads"]
    IMPL --> CLOSE
    CLOSE -->|"Status sync"| SYNC

    style BRIDGE fill:#2d4a22,stroke:#4ade80,stroke-width:2px
    style SPECKIT fill:#1e3a5f,stroke:#60a5fa,stroke-width:2px
    style BEADS fill:#5c2d1a,stroke:#fb923c,stroke-width:2px
Loading

🔄 Bidirectional Sync: Create issues from tasks, OR sync completed Beads issues back to update tasks.md. Run /speckit.taskstobeads anytime to reconcile both directions.

Why Build This?

Gap SpecBeads Solution
Spec Kit lacks execution tracking taskstobeads converts tasks → Beads issues
Beads lacks specification context implementwithbeads loads spec/plan/constitution
Neither enforces project principles Constitutional compliance checks after each task
Disconnected planning and execution taskstobeads provides bidirectional task ↔ issue sync

🧠 Research-Backed AI Optimization

SpecBeads uses psychological prompting techniques proven to improve AI performance by 40-115% on complex tasks:

Technique Impact Research
Detailed Personas 23% → 84% accuracy ExpertPrompting (Xu et al., 2023)
Challenge Framing +115% on hard tasks EmotionPrompt (Li et al., 2023)
Stakes & Consequences +10% avg performance EmotionPrompt Study
Step-by-Step Reasoning 34% → 80% accuracy OPRO (Google DeepMind, 2023)
Self-Evaluation Forces internal validation Confidence Scoring (Tian et al., 2023)

How it works:

  • Commands use senior engineer personas with 15+ years experience
  • Challenge prompts trigger competitive framing ("I bet you can't...")
  • Clear stakes with quantified consequences ("blocks ${N} downstream tasks")
  • Deep breath triggers for deliberate step-by-step reasoning
  • 0.9 confidence threshold with calibration examples prevents overconfident outputs

Example prompt enhancement:

You are a senior software architect with 15+ years in distributed systems.

**CRITICAL**: This blocks 5 downstream tasks if it fails.
**CHALLENGE**: Implement with 80%+ test coverage and <300 lines.

Take a deep breath and work through this step-by-step.

See PROMPTING_ENHANCEMENT_PLAN.md for implementation details.

✨ Key Features

🔄 Bidirectional Synchronization

  • Convert tasks.md to Beads issues with full context
  • Sync completed Beads issues back to update tasks.md
  • Maintain .beads-mapping.json for task ↔ issue relationships

🧠 AI Performance Optimization

  • Research-backed prompting techniques (+40-115% performance)
  • Detailed expert personas (senior engineers with 15+ years experience)
  • Challenge framing and quantified stakes
  • Self-evaluation with 0.9 confidence threshold
  • Calibrated confidence ratings prevent overconfident outputs

📋 Rich Context in Issues

Beads issues include:

  • Relevant spec & plan sections (agents don't need to read full docs)
  • Extracted file paths from task descriptions
  • Acceptance criteria from task markdown
  • Dependency counts ("blocks N downstream tasks")
  • Persona labels (persona:test, persona:feature, etc.)
  • Challenge framing to trigger higher-quality implementation

⚖️ Constitutional Compliance

  • Automatic validation after each task
  • TDD ordering enforcement (tests before implementation)
  • SOLID principles checking
  • Commit size validation (300-600 lines)

🔗 Dependency Management

  • Phase-based dependencies (Foundational → User Stories → Polish)
  • Explicit task dependencies from tasks.md
  • Related links for context (tasks in same user story)
  • bd ready shows only unblocked work

Prerequisites

1. Claude Code (or your preferred AI agent)

npm install -g @anthropic-ai/claude-code

Or use any supported agent

2. GitHub Spec Kit

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify init . --ai claude

3. Beads

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
bd init

Installation

Copy all three components to your project:

1. Slash Commands

cp -r .claude/commands/* /your/project/.claude/commands/

2. Bash Scripts (Required!)

The commands depend on these automation scripts:

cp -r .specify/scripts/bash/* /your/project/.specify/scripts/bash/

Scripts included:

  • check-prerequisites.sh — Validates feature directory and tasks.md
  • startup-checks.sh — Verifies Beads is installed and initialized
  • config-loader.sh — Loads automation preferences
  • check-constitutional-compliance.sh — Post-implementation compliance checks
  • detect-already-implemented.sh — Smart detection of existing implementations
  • common.sh — Shared utilities

3. Constitution & Prompt Templates (Optional but Recommended)

# Constitution template
cp .specify/memory/constitution.md /your/project/.specify/memory/

# Psychological prompting templates (reference documentation)
cp -r .specify/prompts /your/project/.specify/

Templates included:

  • personas.md — Role definitions (architect, test engineer, DevOps, reviewer)
  • framing.md — Stakes and challenge templates
  • self-eval.md — Confidence rating scales with calibration examples

Note: Prompts are inlined in command files for performance. These templates serve as reference documentation and customization starting points.

Restart your AI agent to load the new commands.

Quick Start

# 1. Create specification (Spec Kit)
/speckit.specify "Add user authentication"

# 2. Generate plan (Spec Kit)
/speckit.plan

# 3. Break into tasks (Spec Kit)
/speckit.tasks

# 4. Convert to Beads issues (SpecBeads!)
/speckit.taskstobeads

# 5. Implement with compliance (SpecBeads!)
/speckit.implementwithbeads

Commands

Command Description
/speckit.taskstobeads Convert tasks.md ↔ Beads issues (bidirectional)
/speckit.implementwithbeads Implement next ready task with constitutional compliance

Project Structure

your-project/
├── .specify/
│   ├── memory/
│   │   └── constitution.md          # Project principles
│   ├── prompts/                       # Psychological prompting templates
│   │   ├── README.md                  # Template usage guide
│   │   ├── personas.md                # Role definitions
│   │   ├── framing.md                 # Stakes & challenge templates
│   │   └── self-eval.md               # Confidence calibration examples
│   └── scripts/bash/                  # SpecBeads automation scripts
│       ├── check-prerequisites.sh
│       ├── startup-checks.sh
│       ├── config-loader.sh
│       ├── check-constitutional-compliance.sh
│       ├── detect-already-implemented.sh
│       └── common.sh
├── .claude/commands/
│   ├── speckit.taskstobeads.md       # Tasks ↔ Beads sync
│   └── speckit.implementwithbeads.md # Implement with compliance
├── .beads/
│   └── issues.jsonl                  # Beads database
└── specs/[feature]/
    ├── spec.md
    ├── plan.md
    ├── tasks.md
    └── .beads-mapping.json           # Task ↔ Issue mapping

📚 Research Foundation

SpecBeads' psychological prompting techniques are based on peer-reviewed research:

  • EmotionPrompt — Li et al. (2023). "Large Language Models Understand and Can be Enhanced by Emotional Stimuli." ICLR 2024. arXiv:2307.11760

  • OPRO ("Deep Breath") — Yang et al. (2023). "Large Language Models as Optimizers." Google DeepMind. arXiv:2309.03409

  • 26 Prompting Principles — Bsharat et al. (2023). "Principled Instructions Are All You Need for Questioning LLaMA-1/2, GPT-3.5/4." arXiv:2312.16171

  • ExpertPrompting — Xu et al. (2023). "ExpertPrompting: Instructing Large Language Models to be Distinguished Experts." arXiv:2305.14688

See PROMPTING_ENHANCEMENT_PLAN.md for full implementation details.

License

MIT License — see LICENSE

Specification-first. Memory-enabled. Constitution-governed. AI-optimized.

Built with appreciation for Spec Kit and Beads