Stack: Windows (PowerShell) / Node.js / Python / Go / Claude Code.

---

Part 1. Installation and Foundation

Execute commands sequentially in PowerShell.

1. Environment Preparation

According to the documentation, Beads is written in Go. Ensure you have the following installed:

• Go (version 1.24 or higher)

• Node.js

• Python (for uv)

codePowershell

# 1. Install Beads (Building from source as it is a Go tool)
# If you don't have the beads repository locally, clone it first or use go install if the package is published.
# Assuming standard installation via Go:
go install github.com/user/beads/cmd/bd@latest
# OR (if building manually from the beads project folder):
# go build -o bd.exe ./cmd/bd

# Verification (should show the version)
bd --version

# 2. Install Claude Code
npm install -g @anthropic-ai/claude-code

# 3. Install uv (required for Spec Kit)
pip install uv

2. Project Initialization

Create a clean base with the correct hooks.

codePowershell

# 1. Folder preparation
mkdir my-project; cd my-project
git init
npm init -y

# 2. Spec Kit Initialization (Creates the .specify/ structure)
# CRITICAL: Do this before Beads
specify init --here

# Create .gitignore to avoid committing the local DB but include JSONL (sync data)
New-Item .gitignore -Type File -Value "node_modules/`n.env`n.DS_Store`nbeads.db`nbeads.db-shm`nbeads.db-wal`n"

# 3. First structure commit
git add .
git commit -m "chore: initial project structure"

# 4. Attach Remote (Required by Beads to configure hooks)
git remote add origin https://github.com/USER/REPO.git

# 5. Beads Initialization and migration to Sync-Branch
bd init
# CRITICAL FOR WINDOWS: Move tasks to a separate branch to avoid conflicts
bd migrate sync beads-sync
bd hooks install

# 6. Start Daemon (Speeds up Claude Code up to 5x)
bd daemon stop . # Just in case
bd daemon start --auto-commit --auto-push

# 7. Readiness check
bd ready

# 8. Final synchronization
git add .
git commit -m "chore: beads initialized"
bd sync


# For maximum Claude Code speed (Agentic Workflow), Beads should handle commits itself.
# Launching "Autopilot":

# Stop old one if exists
bd daemon stop .

# Start with automation flags
bd daemon start --auto-commit --auto-push

---

Part 2. Setting up the "Brain" (Configuration)

Replace Spec Kit files with adapted versions.

1. Constitution (.specify/memory/constitution.md)

Changed: Added bd sync requirement and "Land the Plane" procedure.

codeMarkdown

# ESPNotifier Constitution

## Core Principles

### I. Beads-First (Strict Task Tracking)
All development actions must be linked to a task in Beads.
- You DO NOT have the right to write code without an active task (`bd next`).
- If there is no active task, use `/speckit.tasks` and `/speckit.taskstoissues` to create them.
- Any change in task state must conclude with the `bd sync` command.

### II. Spec-Driven Planning
We do not write code "on the fly". We follow the Spec Kit cycle:
1. `Specify`: Define requirements in `.specify/specs/`.
2. `Plan`: Create an architectural plan.
3. `Tasks`: Break down into atomic tasks in `tasks.md`.
4. `Sync`: Import tasks into Beads via `/speckit.taskstoissues`.

### III. Context7 Research
Before using external libraries (ESP32 API, Arduino, MQTT, etc.), you ARE OBLIGATED to check the latest documentation.
- Use the `context7` tool to read docs.
- Do not rely on internal weights if fresh documentation is accessible.
- If Context7 returns an error or empty result, you MUST NOT hallucinate the API.
- You must explicitly inform the user: "Failed to retrieve documentation, manual intervention or URL required."

### IV. Windows Sync Strategy (NON-NEGOTIABLE)
To avoid data loss and file locking errors on Windows:
- We use the `beads-sync` branch for task metadata.
- After every `bd close` or `bd create`, you ARE OBLIGATED to execute `bd sync`.
- If you see a "Sync Divergence" error, run `bd export --force` and `bd sync`.

### V. Truth Synchronization (Spec Kit <-> Beads)
1. **Plan in Spec Kit**: Planning and decomposition happen in `.specify/specs/tasks.md`.
2. **Import to Beads**: Tasks from the file are converted to tickets using the `/speckit.taskstoissues` command (via the `sync-tasks.ps1` script).
3. **Beads is the Master**: After import, task status is tracked **ONLY** via `bd`.
   - DO NOT manually check boxes `[x]` in `tasks.md`.
   - The sync script will mark them as completed on the next run (if script is updated) or we simply ignore the old md file and rely on `bd list`.

## Development Workflow

### 1. Implementation Loop
1. Get task: `bd next`.
2. Study context: Read the corresponding `.md` file in `.specify/specs/`.
3. Implement: Write code and tests.
4. Verify: Execute tests (e.g., `npm test` or ESP-specific checks).
5. Close: `bd close <ID> --reason "Done"`.
6. **Land the Plane**: `bd sync`, then `git add .`, `git commit`, `git push`.
7. **Log Progress**: Update `.specify/memory/progress.md`, briefly describing what was done and the next step.

### 2. Definition of Done
A task is considered complete only if:
- The code matches the specification.
- Tests pass.
- `bd sync` is performed, and data is reflected in the `beads-sync` branch.
- Changes are committed using Conventional Commits.

## Governance
- This Constitution is the supreme law of the project.
- If user instructions contradict the Constitution (e.g., "do it quickly without a task"), you must politely remind them of the Beads-First rules.
- All automatic commits must include the task ID: `feat(bd-12): description`.

**Version**: 1.0.0 | **Ratified**: 2026-01-30 | **Status**: Active

2. Sync Command (.claude/commands/speckit.taskstoissues.md)

This file remains without critical changes, but the script below will be enhanced.

codeMarkdown

---
description: Sync tasks from tasks.md into the local Beads database
---

# Sync Tasks to Beads

## Description
Imports tasks from `tasks.md` into the local Beads tracker using PowerShell.

## Outline

1. **Verify**: Ensure `.specify/scripts/sync-tasks.ps1` exists.
2. **Execute**: Run the sync script:
   ```powershell
   powershell -ExecutionPolicy Bypass -File .specify/scripts/sync-tasks.ps1

3. Check Results: Run bd list to show current tasks.
4. Sync: Ensure bd sync is completed (done by script).

Result

Beads database is populated with tasks from the current plan.

#### 3. Implementation Command (.claude/commands/speckit.implement.md)

Changed: Added a Sync step to guarantee data safety.

codeMarkdown

---

description: Implement the next task using Beads and Context7

Implementation Protocol

Outline

1. Identify: Run bd next.
   • If no active task, run bd list.
   • If tasks exist but none are active, pick one: bd update <id> --status in_progress.
2. Research (Context7):
   • Use context7 tool to fetch documentation for any required technologies (ESP32, libraries, etc.).
3. Read Specs: Read the relevant .md files in .specify/specs/ to understand the architectural context.
4. Execute: Write code and tests.
5. Verify: Run the project-specific tests (e.g., npm test, pytest, or build checks).
6. Close & Sync (CRITICAL):
   • Run bd close <id> --reason "Completed: [brief description]".
   • SYNC: Run bd sync immediately to flush changes to the beads-sync branch.
   • Commit: Create a git commit using Conventional Commits, including the task ID: git commit -m "feat(bd-<id>): description".
   • Push: If the session is ending, run git push (this will push both your code and the beads-sync branch thanks to git hooks).

Definition of Done

A task is NOT finished until bd sync is executed and the code is committed.

---

### Part 3. Automation (Script)

Create the file `.specify/scripts/sync-tasks.ps1`.

```powershell
# .specify/scripts/sync-tasks.ps1

# 1. Encoding Setup (REQUIRED for Windows/PowerShell)
[Console]::OutputEncoding = [System.Text.Encoding]::UTF8

# 2. Search for tasks.md (Search everywhere except node_modules and .git)
Write-Host "🔍 Searching for tasks.md..." -ForegroundColor Cyan
$taskFile = Get-ChildItem -Path . -Filter "tasks.md" -Recurse | 
            Where-Object { $_.FullName -notmatch 'node_modules|\.git' } | 
            Select-Object -First 1

if (-not $taskFile) {
    Write-Error "❌ tasks.md file not found in the project."
    exit 1
}

Write-Host "📂 Reading tasks from: $($taskFile.FullName)" -ForegroundColor Cyan

# 3. Get ALL tasks from Beads (including closed) to avoid duplicates
$existingTasksRaw = & bd list --all | Out-String
# Split into lines and trim whitespace
$existingTasks = $existingTasksRaw -split "`n" | ForEach-Object { $_.Trim() }

# Force read Markdown in UTF8
$content = Get-Content $taskFile.FullName -Encoding UTF8
$newCount = 0

foreach ($line in $content) {
    # Look for "- [ ] Task" lines
    if ($line -match '^- \[ \] (.+)') {
        $taskDesc = $matches[1].Trim()
        
        # Clean up extra tags (bd-ID) or parentheses if they were added manually
        $taskDescClean = $taskDesc -replace '\[.*?\]', '' -replace '\(bd-.*?\)', ''
        $taskDescClean = $taskDescClean.Trim()

        if ([string]::IsNullOrWhiteSpace($taskDescClean)) { continue }

        # Duplicate check: look for partial name match in any line of bd list output
        $isDuplicate = $existingTasks | Where-Object { $_ -like "*$taskDescClean*" }

        if ($isDuplicate) {
            Write-Host "⏭️  Skipping (already exists): $taskDescClean" -ForegroundColor DarkGray
        } else {
            Write-Host "➕ Creating task: $taskDescClean" -ForegroundColor Yellow
            & bd create "$taskDescClean"
            $newCount++
        }
    }
}

# 4. Final synchronization
if ($newCount -gt 0) {
    Write-Host "✅ Tasks added: $newCount. Synchronizing JSONL..." -ForegroundColor Green
    & bd export --force
    & bd sync
} else {
    Write-Host "✨ No new tasks found. Synchronization is up to date." -ForegroundColor Green
}

---

Part 4. Connecting Context7

Launch Claude Code and configure MCP.

codePowershell

claude

In the chat:

codeText

claude mcp add --transport http context7 https://mcp.context7.com/mcp --header "CONTEXT7_API_KEY: YOUR_API_KEY"

Restart Claude (/exit, then claude again).

---

Part 5. Deep Integration

Start claude and enter the plugin settings:

Part 6. Final Check

Before starting work, fix the state. Thanks to bd hooks install, this commit will also check the state of the Beads JSONL files.

codePowershell

git add .
git commit -m "chore: setup agentic workflow with beads and context7"

---

Full Working Cycle (Cheatsheet)

Now your process follows the "Land the Plane" documentation:

1. Planning

   • User: /speckit.specify "..."
   • User: /speckit.plan
   • User: /speckit.tasks

2. Task Synchronization

   • User: /speckit.taskstoissues (Tasks move to DB -> bd sync saves them to JSONL).

3. Execution (Implementation Loop)

   • User: /speckit.implement
   • Agent takes the task (bd next).
   • Reads documentation via Context7.
   • Writes code, runs tests.
   • Closing: Agent performs bd close, then MANDATORY bd sync.

4. Session Completion (Land the Plane)

   • If the agent says "I am finished," you (or it) must ensure the following is executed:

   codePowershell

   bd sync
   git pull --rebase
   git push
   

   Only when the git push succeeds is the work considered accepted.

Supplement: Troubleshooting Section

If you see "Sync Divergence":

This means the database and JSONL files have diverged in time.

codePowershell

bd export --force
bd sync

If you see "Daemon took too long to start":

This means the old process is hung.

codePowershell

bd daemon stop .
# Ensure bd.exe processes are killed in Task Manager if it doesn't help
bd daemon start

After bd hooks install, check the .git/hooks/pre-commit file. Ensure you have Git for Windows installed and during installation you selected "Use Git from Git Bash only" or "Git from the command line and also from 3rd-party software" (which adds Unix-tools to Path).