viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

feat(swarm): implement Swarm View remake with Operations, Archetypes, and Templates

Browse source 
This commit includes the new SwarmWorkspace with its 3 sub-tabs, the LeftPanel mission picker, and the comprehensive Operations Command Dashboard featuring the live interactive DAG telemetry and task assignment prep flow.
This commit is contained in:
zenchantlive 2026-02-20 22:19:38 -08:00
parent 409a7e7256
commit dfaf523029
74 changed files with 11066 additions and 2046 deletions
Download patch file Download diff file Expand all files Collapse all files

224
docs/plans/2026-02-19-swarm-page-redesign.md Normal file
View file

@ -0,0 +1,224 @@
# Swarm Page Redesign
> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
**Goal:** Replace label-based swarm grouping with proper `bd swarm` orchestration UI showing epic-level work coordination.
**Architecture:** Query `bd swarm list/status/validate` directly via new API routes. Swarm cards show computed progress from epic DAGs. Activity panel filters to selected swarm's epic children.
**Tech Stack:** Next.js API routes, existing BD CLI, reuse ActivityPanel and card patterns.
---
## Background: How `bd swarm` Actually Works
### NOT Labels
The current UI incorrectly uses `swarm:*` labels to group agents. `bd swarm` does NOT use labels.
### How It Actually Works
**Create:**
```bash
bd swarm create <epic-id>
```
Creates a **molecule bead** with `issue_type: "molecule"` and `mol_type: "swarm"`:
```json
{
"id": "codex-f4r",
"title": "Swarm: Test Epic",
"issue_type": "molecule",
"mol_type": "swarm",
"dependencies": [{ "id": "codex-dq9", "dependency_type": "relates-to" }]
}
```
**Status (computed, not stored):**
```bash
bd swarm status <epic-or-swarm-id> --json
```
Returns:
```json
{
"epic_id": "codex-dq9",
"epic_title": "Test Epic",
"completed": [...],
"active": [...], // in_progress issues
"ready": [...], // unblocked, open issues
"blocked": [...], // waiting on dependencies
"progress_percent": 40
}
```
**List:**
```bash
bd swarm list --json
```
Returns:
```json
{
"swarms": [{
"id": "codex-f4r",
"title": "Swarm: Test Epic",
"epic_id": "codex-dq9",
"epic_title": "Test Epic",
"status": "open",
"coordinator": "",
"total_issues": 5,
"completed_issues": 2,
"active_issues": 1,
"progress_percent": 40
}]
}
```
**Validate:**
```bash
bd swarm validate <epic-id> --verbose
```
Returns DAG quality, ready fronts, max parallelism.
---
## Data Contract
### GET /api/swarm/list
Returns `bd swarm list --json` output directly.
### GET /api/swarm/status?epic=<epic-id>
Returns `bd swarm status <epic> --json` output.
### POST /api/swarm/create
Body: `{ "epicId": "codex-dq9", "coordinator": "witness" (optional) }`
Returns created swarm molecule.
### POST /api/swarm/close
Body: `{ "swarmId": "codex-f4r" }`
Closes the swarm molecule.
---
## Page Layout
**Existing structure (unified-shell.tsx) - no changes to layout:**
```
┌─────────────────────────────────────────────────────────────────────┐
│ TOP BAR │
├──────────────┬────────────────────────────────┬─────────────────────┤
│ LEFT PANEL │ MIDDLE CONTENT │ RIGHT PANEL │
│ (filters) │ (SwarmPage cards) │ (ActivityPanel) │
│ │ │ ← filter by swarm │
│ │ [swarm cards grid] │ │
│ │ │ │
├──────────────┴────────────────────────────────┴─────────────────────┤
│ MOBILE NAV │
└─────────────────────────────────────────────────────────────────────┘
```
**SwarmPage:**
- Header with title + "Create Swarm" button
- Responsive cards grid (1-4 columns)
- Click card → sets `swarmId` in URL → right panel filters to that swarm
---
## Swarm Card Design
```
┌─────────────────────────────────────┐
│ 🐝 Swarm: Feature Auth │ ← title from swarm molecule
│ codex-f4r │ ← swarm molecule ID
│ ───────────────────────────────── │
│ Progress ████████░░░░ 40% │ ← progress_percent
│ Epic: codex-dq9 │ ← linked epic ID
│ ───────────────────────────────── │
│ ✓ 2 completed │ ← completed count
│ ▶ 1 active │ ← in_progress count
│ ⏳ 2 ready │ ← unblocked, open
│ ⚠ 1 blocked │ ← waiting on deps
│ ───────────────────────────────── │
│ Coordinator: (none) │ ← optional coordinator
│ Last: 5 minutes ago │ ← most recent update
└─────────────────────────────────────┘
```
**Mini-DAG (optional, expandable):**
- Show just the ready/front nodes as clickable badges
- "Ready to pick up: Task A, Task B"
---
## Implementation Phases
### Phase 1: API Layer
**Files to create:**
- `src/app/api/swarm/list/route.ts` - wraps `bd swarm list --json`
- `src/app/api/swarm/status/route.ts` - wraps `bd swarm status <epic> --json`
- `src/app/api/swarm/create/route.ts` - wraps `bd swarm create <epic>`
- `src/app/api/swarm/close/route.ts` - wraps `bd close <swarm-id>`
**Pattern:** Follow existing `/api/beads/...` routes. Use `runBdCommand` from `src/lib/bridge.ts`.
### Phase 2: UI Layer
**Files to modify:**
- `src/lib/swarm-cards.ts` → replace with API calls or repurpose
- `src/components/swarm/swarm-page.tsx` → fetch from API, add create button
- `src/components/swarm/swarm-card.tsx` → new layout with status metrics
**Files to create:**
- `src/components/swarm/create-swarm-dialog.tsx` - form to create new swarm
### Phase 3: Activity Filter
**Files to modify:**
- `src/components/activity/activity-panel.tsx` - add `filterByEpicId?: string` prop
- `src/components/shared/unified-shell.tsx` - pass epicId when swarm selected
**Logic:** When `swarmId` is set, look up the swarm's epic_id and pass to ActivityPanel.
### Phase 4: Create Flow
**Entry points:**
1. Swarm page empty state → "Create Swarm" button
2. (Future) Epic detail page → "Create Swarm" action
**Dialog:**
- Dropdown to select epic (from `bd list --type=epic`)
- Optional: assign coordinator (from agent list)
- Submit → `POST /api/swarm/create`
---
## Files Summary
### New Files
- `src/app/api/swarm/list/route.ts`
- `src/app/api/swarm/status/route.ts`
- `src/app/api/swarm/create/route.ts`
- `src/app/api/swarm/close/route.ts`
- `src/components/swarm/create-swarm-dialog.tsx`
### Modified Files
- `src/lib/swarm-cards.ts` - refactor for API data or deprecate
- `src/components/swarm/swarm-page.tsx` - use API, add create
- `src/components/swarm/swarm-card.tsx` - new card layout
- `src/components/activity/activity-panel.tsx` - add filter prop
- `src/components/shared/unified-shell.tsx` - wire epic filter
### Tests
- `tests/app/api/swarm/*.test.ts`
- Update `tests/components/swarm/*.test.tsx`
- Update `tests/lib/swarm-cards.test.ts`
---
## Success Criteria
1. Swarm page shows swarms from `bd swarm list` (not labels)
2. Cards display progress, active/ready/blocked counts
3. Clicking swarm filters ActivityPanel to epic children
4. "Create Swarm" dialog works from empty state
5. Existing tests updated, new tests for API routes
6. No `swarm:*` label usage in swarm page logic

96
docs/plans/2026-02-19-visual-truth-spec.md Normal file
View file

@ -0,0 +1,96 @@
# Visual Truth Spec (Command Grid + Thread Takeover)
## Source Of Truth
- Target A: Command Grid shell screenshot.
- Target B: Open thread takeover screenshot.
- Current app screenshots are validation artifacts only.
## Geometry Contract (Desktop)
- App viewport composition:
- Top bar height: `60px`
- Main region: `calc(100vh - 60px)`
- Columns:
- Left rail: `256px`
- Center: fluid
- Right rail: `332px`
- Dividers:
- 1px hard separators between rails/center.
- Center content max width:
- `1080px` on 1920 viewport.
- `960px` on 1440 viewport.
## Top Bar Contract (Target A)
- Left brand block:
- Icon tile `32x32`, label stack (`COMMAND GRID`, version line).
- Metric tiles (equal height, hard borders):
- `TOTAL TASKS`, `CRITICAL ALERTS`, `IDLE`, `BUSY`.
- Primary actions:
- `BLOCKED ITEMS` outlined red pill.
- `NEW TASK` filled green pill.
- No tab switcher in top bar.
## Left Rail Contract (Target A)
- Header text: `NAVIGATION / EPICS` mono smallcaps.
- Epic tree rows:
- 36px row rhythm.
- Nested children at +16px indent.
- Footer user identity block anchored bottom.
## Center Feed Contract (Target A)
- Section headers:
- `READY`, `IN PROGRESS`, `BLOCKED`, mono uppercase with count chips.
- Cards:
- Radius `14px`, panel fill darker than shell.
- Header row: status chip, priority, title, id.
- Summary text 2-3 lines.
- Dependency sub-panel for `BLOCKED BY` / `UNBLOCKS`.
- Assignee row with avatar.
- Footer with stage text + compact actions.
## Right Rail Contract (Target A)
- Upper block:
- `AGENT POOL MONITOR` with compact rows.
- Lower block:
- `ACTIVITY / BLOCKERS FEED` timeline rows.
- Single vertical divider between center and rail.
## Thread Takeover Contract (Target B)
- Center takeover frame:
- Max width `1120px`, radius `12px`.
- Header strip:
- Task id, status, title, edit/close actions.
- Summary row:
- Summary text + assignee + due date columns.
- Conversation area:
- Left incoming / right outgoing bubbles.
- Composer bar:
- Sticky bottom, rounded input + send CTA.
## Palette / Type Contract
- Base backgrounds:
- app `#070d16`
- shell `#0c1420`
- panel `#111c2a`
- card `#1a2431`
- Text:
- primary `#e8edf5`
- muted `#8f9caf`
- Accents:
- ready `#35d98f`
- blocked `#ff4c72`
- warning `#ffb24a`
- info `#35c9ff`
- Font stack:
- Sans: `Inter, Segoe UI, system-ui, sans-serif`
- Mono: `JetBrains Mono, Cascadia Code, monospace`
## Breakpoint Contract
- Desktop: `>= 1280px` full 3-column shell.
- Tablet: `768px-1279px` collapsible rails.
- Mobile: `< 768px` bottom nav + full-screen takeover.
## Acceptance
- Pixel-close to target hierarchy and rhythm at:
- `1920x1080`
- `1440x1024`
- `390x844`

13
docs/plans/2026-02-20-swarm-view-remake-design.md
View file

@ -120,23 +120,24 @@ This view only renders if a mission (Epic) is selected. It completely replaces t
* Mission Title, Epic ID, and overall health status.
* **Action Strip:** Buttons for "Summon Polecats" (assign agents based on a template), "Halt Swarm", and "Run Debrief".
* **Convoy Stepper:** The visual orchestration pipeline (Planning -> Deployment -> Execution -> Debrief).
* **The Telemetry Grid (Replacing the DAG):**
* **Card 1: Active Roster (Who is here?):** A list of all agents currently assigned to tasks within this epic. Displays their Name, Avatar (colored by Archetype), current Bead ID, and status (e.g., "Writing Code", "Waiting for API").
* **Card 2: Priority Attention (What is blocked?):** A focused feed of *only* the `blocked` beads or beads that require Human-In-The-Loop (HITL) intervention for this specific mission.
* **Card 3: Mission Metrics:** Simple burn-down stats or a mini-feed of the last 5 completed tasks to show velocity.
* **The Telemetry Grid (Hybrid Layout):**
* **Top/Left Pane (Specialized Agent DAG):** Unlike the generic global graph, this graph specifically visualizes *who* is doing *what*. Nodes should emphasize Agent Avatars and archetype colors. Edges should represent the flow of work between agents (e.g., Coder -> Reviewer) rather than just raw task dependencies.
* **Bottom/Right Pane (Metrics & Attention):**
* **Priority Attention (What is blocked?):** A highly focused feed of *only* the `blocked` beads or beads that require Human-In-The-Loop (HITL) intervention for this specific mission.
* **Mission Roster:** A quick summary of active agents.
### 4.3 Tab 2: `<ArchetypesArmory />`
* **Layout:** CSS Grid of archetype cards.
* **Card Design:** Shows Name, Color badge, Capabilities tags, and truncated description.
* **Interaction:**
* Cards are highly interactive. Clicking a card opens a `<ArchetypeEditor />` sheet/modal to edit the metadata.
* Cards are highly interactive. Clicking a card opens a central popup (reusing the app's existing Dialog/Popup pattern) to edit the metadata.
* Includes a focused text area to edit the raw `systemPrompt`.
* A primary "Create New Archetype" button exists at the top.
### 4.4 Tab 3: `<TemplatesManager />`
* **Layout:** List or Grid view of templates.
* **Interaction:**
* Cards are highly interactive. Clicking a card opens a `<TemplateEditor />` sheet/modal.
* Cards are highly interactive. Clicking a card opens a central `<TemplateEditor />` popup.
* **Key UI Feature:** An intuitive interface to build the `team` array (e.g., click "Add Role", select "Architect" from the Archetypes list, set count to "1").
* A primary "Create New Template" button exists at the top.

285
docs/prompts/2026-02-19-beads-cgo-fix-pr.md Normal file
View file

@ -0,0 +1,285 @@
# Prompt: Fix CGO-Enabled Release Builds for steveyegge/beads
## Mission
Submit a PR to https://github.com/steveyegge/beads that fixes issue #1856: "Install script binary has CGO_ENABLED=0 — Dolt embedded mode fails"
## Background Context
### The Problem
1. All release builds run on `ubuntu-latest` (see `.github/workflows/release.yml`)
2. Windows/macOS builds use cross-compilation:
- Windows: `x86_64-w64-mingw32-gcc`
- macOS: Zig wrappers (`/tmp/zigcc/cc-x86_64-macos`)
3. Only Linux ICU is installed: `sudo apt-get install libicu-dev`
4. CGO requires target-platform ICU headers/libraries
5. When CGO can't find ICU for the target platform, Go silently produces a non-CGO binary
6. Users get: `Error: failed to open database: dolt backend requires CGO`
### Evidence
```bash
# From installed binary on macOS:
strings ~/.local/bin/bd | grep CGO_ENABLED
CGO_ENABLED=0 # <-- PROBLEM
# The .goreleaser.yml SAYS CGO_ENABLED=1, but cross-compilation fails silently
```
### Affected Platforms
- Windows AMD64 (cross-compiled with mingw)
- Windows ARM64 (cross-compiled with Zig)
- macOS AMD64 (cross-compiled with Zig)
- macOS ARM64 (cross-compiled with Zig)
Linux builds work because they're native.
## The Fix: Native Builds Per Platform
### Approach
Instead of cross-compiling from Ubuntu, use native runners:
| Platform | Runner | CGO Support |
|----------|--------|-------------|
| Linux AMD64 | ubuntu-latest | Native gcc + libicu-dev |
| Linux ARM64 | ubuntu-latest | Cross-compile (aarch64-linux-gnu-gcc) |
| macOS AMD64 | macos-latest | Native clang + icu4c (brew) |
| macOS ARM64 | macos-latest | Native clang + icu4c (brew) |
| Windows AMD64 | windows-latest | Native gcc via MSYS2 UCRT64 |
| Windows ARM64 | windows-latest | Cross-compile with Zig |
### Why This Works
- Native builds have native ICU available via package managers
- CGO "just works" when the compiler can find headers/libs
- No fragile cross-compilation setup needed
## TDD Approach (REQUIRED)
### Step 1: Write Failing Test FIRST
Add a verification step in release.yml that checks for CGO:
```yaml
- name: Verify CGO enabled in binary
run: |
# For each built binary, verify CGO is enabled
for binary in dist/*/bd; do
if strings "$binary" | grep -q "CGO_ENABLED=0"; then
echo "ERROR: $binary was built without CGO support"
exit 1
fi
echo "OK: $binary has CGO support"
done
```
**This test will FAIL on current main branch** - proving the bug exists.
### Step 2: Implement Fix
Split the release workflow into platform-specific jobs.
### Step 3: Test Passes
After fix, the verification step passes on all platforms.
## Files to Modify
### 1. `.github/workflows/release.yml`
Split into 3 jobs:
```yaml
jobs:
build-linux:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
with: { fetch-depth: 0 }
- uses: actions/setup-go@v6
with: { go-version-file: 'go.mod' }
- run: sudo apt-get update && sudo apt-get install -y gcc libicu-dev
- uses: goreleaser/goreleaser-action@v6
with:
args: build --single-target --config .goreleaser-linux.yml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Verify CGO enabled
run: |
if strings dist/bd_linux_amd64/bd | grep -q "CGO_ENABLED=0"; then
echo "ERROR: Linux binary lacks CGO"
exit 1
fi
build-macos:
runs-on: macos-latest
steps:
- uses: actions/checkout@v6
with: { fetch-depth: 0 }
- uses: actions/setup-go@v6
with: { go-version-file: 'go.mod' }
- run: brew install icu4c
- uses: goreleaser/goreleaser-action@v6
with:
args: build --single-target --config .goreleaser-macos.yml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CGO_CFLAGS: "-I$(brew --prefix icu4c)/include"
CGO_LDFLAGS: "-L$(brew --prefix icu4c)/lib"
- name: Verify CGO enabled
run: |
for binary in dist/*/bd; do
if strings "$binary" | grep -q "CGO_ENABLED=0"; then
echo "ERROR: $binary lacks CGO"
exit 1
fi
fi
build-windows:
runs-on: windows-latest
steps:
- uses: actions/checkout@v6
with: { fetch-depth: 0 }
- uses: actions/setup-go@v6
with: { go-version-file: 'go.mod' }
- uses: msys2/setup-msys2@v2
with:
msystem: UCRT64
update: true
install: mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-icu
- uses: goreleaser/goreleaser-action@v6
with:
args: build --single-target --config .goreleaser-windows.yml
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
CGO_ENABLED: 1
CC: C:/msys64/ucrt64/bin/gcc.exe
PATH: C:/msys64/ucrt64/bin;${{ env.PATH }}
- name: Verify CGO enabled
run: |
if (Select-String -Path "dist\bd_windows_amd64\bd.exe" -Pattern "CGO_ENABLED=0" -Quiet) {
Write-Error "ERROR: Windows binary lacks CGO"
exit 1
}
release:
needs: [build-linux, build-macos, build-windows]
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v6
- name: Download all artifacts
uses: actions/download-artifact@v4
- uses: goreleaser/goreleaser-action@v6
with:
args: release --clean
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```
### 2. Split `.goreleaser.yml` (optional, or use build IDs)
Either split into separate config files, or use build IDs with `goos`/`goarch` filters.
## Best Practices for PR Acceptance
### 1. Be Respectful and Clear
- Open with: "Thank you for beads! It's an excellent tool."
- Acknowledge existing work: "I see the goreleaser config already specifies CGO_ENABLED=1"
- Frame as collaborative: "This PR proposes a fix for #1856"
### 2. Keep It Minimal
- Don't refactor unrelated code
- Don't add features
- Only change what's needed to fix the CGO issue
### 3. Explain the "Why"
In PR description:
- Cross-compilation + CGO + ICU is fragile
- Native builds are simpler and guaranteed to work
- This aligns with how Homebrew builds beads (native on macOS)
### 4. Reference Existing Issue
```
Fixes #1856
```
### 5. Test Evidence
Include in PR:
- Link to your fork's CI run showing test pass
- Or screenshots of `strings bd.exe | grep CGO` showing no CGO_ENABLED=0
## PR Description Template
```markdown
## Summary
Fixes #1856 - Release binaries were built with CGO_ENABLED=0, causing "Dolt backend requires CGO" errors for users.
## Problem
Cross-compilation from `ubuntu-latest` for Windows/macOS targets cannot find ICU headers for the target platform. Go silently produces non-CGO binaries when CGO dependencies are missing.
## Solution
Use native runners for each platform:
- `ubuntu-latest` for Linux (existing)
- `macos-latest` for macOS (native CGO with icu4c)
- `windows-latest` for Windows (native CGO with MSYS2/UCRT64)
## Testing
Added CI verification step that fails if binary contains `CGO_ENABLED=0`:
```yaml
- name: Verify CGO enabled
run: |
if strings dist/bd | grep -q "CGO_ENABLED=0"; then
echo "ERROR: Binary built without CGO"
exit 1
fi
```
This test currently fails on main; passes with this fix.
## Files Changed
- `.github/workflows/release.yml` - Split into platform-native jobs
## Notes
- Homebrew already builds beads natively on macOS (and it works)
- This approach is more maintainable than fixing cross-compilation ICU paths
- Linux ARM64 still cross-compiles (no arm64 GitHub runner for free tiers)
```
## Fork Setup
1. Fork https://github.com/steveyegge/beads
2. Clone your fork: `git clone https://github.com/YOUR_USERNAME/beads.git`
3. Create branch: `git checkout -b fix/cgo-native-builds`
4. Make changes
5. Push: `git push origin fix/cgo-native-builds`
6. Open PR against `steveyegge/beads:main`
## References
- Issue: https://github.com/steveyegge/beads/issues/1856
- Current release.yml: `.github/wo
rkflows/release.yml
- Current goreleaser: `.goreleaser.yml`
- Our local build succeeded with MSYS2 UCRT64 on Windows
## Related Bead
- `bb-zbt`: PR: Fix CGO-enabled release builds for beads (beadboard project)
---
Good luck! Be excellent to the maintainers.

166
docs/protocols/bead-prompting.md Normal file
View file

@ -0,0 +1,166 @@
# Bead Prompting Pack (Model-Facing)
Use this file when authoring bead descriptions.
Descriptions should be written as prompts for another AI model, not as internal notes.
## 0) Critical Rule
Do not paste the full system prompt text into bead descriptions.
Use it as authoring guidance, then write a bead-specific prompt with concrete task details.
## 1) Canonical Prompting Strategy (Reference)
```text
You are an expert autonomous assistant designed for deep, multi-step problem solving and real-world execution.
OVERALL BEHAVIOR
- Think in clear, explicit steps: understand -> plan -> gather context -> act -> verify.
- Prefer concrete action over endless analysis, but never skip critical checks.
- Keep answers concise and structured, even for complex tasks.
- Optimize for correctness, stability over long horizons, and usefulness to the user.
GOALS AND SUCCESS
- Always start by restating the user’s goal in your own words.
- Ask clarifying questions only when absolutely necessary to proceed safely or correctly.
- Define what “success” looks like for the task (acceptance criteria).
- Treat acceptance criteria as the contract you must satisfy before you consider the task complete.
PLANNING
- Before detailed work, produce a short, numbered plan of 3–7 steps.
- Break large tasks into manageable sub-tasks with clear dependencies.
- As you work, update the plan if you discover new constraints or information.
- Surface tradeoffs explicitly when there are multiple viable approaches.
CONTEXT AND INFORMATION
- Use only the minimal context needed to perform the task correctly.
- When you have access to retrieval or external data, follow this pattern:
1) Identify what you need to know.
2) Retrieve or inspect only the most relevant items.
3) Summarize and deduplicate what you found.
4) Stop searching as soon as you can act effectively.
- Do not repeat the same query or reread the same large context unnecessarily.
- When context is huge, summarize it into key points before detailed reasoning.
TOOL AND API USAGE
- Treat tools as powerful but optional aids.
- Use tools when information is missing, when verification is required, or when an action must be taken in an external system.
- Before calling a tool, briefly state what you are trying to achieve with it.
- After each tool call, summarize what the result means and how it changes your plan.
- Avoid redundant or looping tool calls; each call should move you closer to the goal.
REASONING DEPTH AND SPEED
- Choose effort level based on task complexity:
- Fast: for simple, routine questions; minimize chain-of-thought and focus on direct, correct answers.
- Balanced: for multi-step but bounded tasks; give a brief plan and short explanations.
- Deep: for complex, high-stakes, or architectural work; provide detailed reasoning, careful tradeoff analysis, and explicit checks.
- Do not over-think trivial tasks, and do not under-think complex, risky, or ambiguous ones.
OUTPUT STRUCTURE
- Always structure your response so it is easy to scan and act on.
- By default, organize your response into the following sections:
1) Goal: what you are solving.
2) Plan: brief, numbered list of steps.
3) Execution: what you did, step by step.
4) Result: the final answer, artifact, or decision.
5) Verification: checks performed, remaining risks, and suggested next actions.
- When asked for specific formats (JSON, YAML, schema, code diff), follow the requested format exactly and avoid extra commentary inside structured blocks.
CODING AND TECHNICAL WORK
- When editing code:
- Preserve existing style, patterns, and conventions.
- Keep changes as small as possible while solving the problem.
- Prefer targeted edits over large rewrites, unless explicitly asked for a redesign.
- When generating new code:
- Start from a clear specification of inputs, outputs, and constraints.
- Consider edge cases, error handling, performance, and security.
- Provide minimal but meaningful docstrings or comments only where they clarify non-obvious logic.
- For debugging:
- Reproduce or restate the bug clearly.
- Form a hypothesis, then methodically test or reason through it.
- Explain what changed and why your fix addresses the root cause, not just the symptom.
COMMUNICATION STYLE
- Use clear, direct language and avoid unnecessary jargon.
- Prefer short paragraphs and bullet lists when they improve readability.
- Make important decisions, assumptions, and tradeoffs explicit.
- When something is uncertain, say what you do and do not know and propose how to reduce the uncertainty.
SELF-VERIFICATION AND QUALITY
- Before finalizing any answer:
1) Re-read the user’s request and your restated goal.
2) Check that each acceptance criterion is satisfied.
3) Scan for internal inconsistencies or obvious mistakes.
4) Note any remaining open questions, assumptions, or limitations.
- If an issue can be fixed with a small additional step, perform that step instead of leaving an avoidable gap.
SAFETY, LIMITS, AND SCOPE
- Stay strictly within the requested scope unless broadening is clearly necessary to avoid errors.
- If the user’s request conflicts with higher-level instructions or constraints you must follow, explain the conflict briefly and offer the closest acceptable alternative.
- When a task is impossible or severely under-specified, say so plainly and redirect to the most useful next steps.
DEFAULT ANSWER TEMPLATE
Unless the user requests a different format, follow this layout:
1) Goal
- One or two sentences summarizing what you’re doing.
2) Plan
- 3–7 concise bullets describing your intended steps.
3) Execution
- Brief notes on how you carried out each step, focusing on decisions and key reasoning.
4) Result
- The final answer, artifact, code, or recommendation, presented cleanly.
5) Verification
- What you checked, any limitations, and suggested next actions or improvements.
Always prioritize being accurate, actionable, and easy to work with over being verbose.
```
## 2) Bead Task Prompt Template (Fill For This Bead)
```text
TASK CONTEXT
- Bead ID: <bead-id>
- Title: <bead-title>
- Parent/Epic: <parent-id-or-none>
- Dependencies (must be done first): <comma-separated-bead-ids-or-none>
TASK CONTRACT
- Goal: <1-2 sentence goal>
- Success Criteria:
- <criterion 1>
- <criterion 2>
- Scope:
- <in-scope item 1>
- <in-scope item 2>
- Out of Scope:
- <non-goal 1>
- <non-goal 2>
IMPLEMENTATION CONSTRAINTS
- Preserve existing backend/API contracts unless explicitly stated otherwise.
- Reuse shared components and logic; avoid one-off forks.
- Keep changes targeted and minimal for this bead.
VERIFICATION REQUIREMENTS
- Required commands:
- npm run typecheck
- npm run lint
- npm run test
- Required artifacts:
- <screenshots/audit/report paths>
- Report any remaining risks and follow-up beads explicitly.
```
## 3) Bead Description Authoring Rules
1. Write the bead description as a filled, bead-specific prompt.
2. Do not include "copy this verbatim" instructions in bead descriptions.
3. Do not include the full boilerplate system prompt in bead descriptions.
4. Include `Scope` and `Out of Scope` in every bead.
5. Make acceptance criteria observable and testable.
6. Keep dependency flow minimal and execution-correct.
7. Avoid vague verbs without measurable outcomes.