docs+skills: add main UI/UX visual-truth PRD and skill links
This commit is contained in:
ZenchantLive
parent
1c36223e7f
commit
14a50ad4ae
289 changed files with 54463 additions and 0 deletions
246
.agents/skills/linus-beads-discipline/resources/BD_MASTERY.md
Normal file
246
.agents/skills/linus-beads-discipline/resources/BD_MASTERY.md
Normal file
|
|
@ -0,0 +1,246 @@
|
|||
# BD Mastery
|
||||
|
||||
**Advanced commands for Linus-level beads discipline.**
|
||||
|
||||
## Agent Coordination Architecture
|
||||
|
||||
**Single source of truth:** Agent identity lives in bd agent beads (`.beads/issues.jsonl`), NOT in separate files.
|
||||
|
||||
### BD Agent Beads (Identity + Presence)
|
||||
|
||||
```bash
|
||||
# Create agent bead
|
||||
bd create --title "Agent: amber-otter" --type agent --label gt:agent
|
||||
|
||||
# Set agent state
|
||||
bd agent state gt-amber-otter working
|
||||
|
||||
# Heartbeat (presence)
|
||||
bd agent heartbeat gt-amber-otter
|
||||
|
||||
# Show agent
|
||||
bd agent show gt-amber-otter
|
||||
|
||||
# Query agents
|
||||
bd query "label=gt:agent AND status!=closed"
|
||||
```
|
||||
|
||||
**Agent bead fields:** `id`, `title` (display name), `status`, `last_activity`, labels include `gt:agent` and role.
|
||||
|
||||
### BB Agent (Custom Extensions)
|
||||
|
||||
For features bd doesn't have:
|
||||
|
||||
```bash
|
||||
# Messaging (bd has no equivalent)
|
||||
bb agent send --from amber-otter --to cobalt-harbor --bead bb-xyz --category request --subject "Need review" --body "..."
|
||||
|
||||
# Path reservations (bd slots are bead-based, not path-based)
|
||||
bb agent reserve --agent amber-otter --scope C:/project/path --bead bb-xyz
|
||||
bb agent release --agent amber-otter --scope C:/project/path
|
||||
|
||||
# Check reservations + messages
|
||||
bb agent status --agent amber-otter
|
||||
```
|
||||
|
||||
**What stays in bb (no bd equivalent):**
|
||||
- `agent-mail.ts` - Agent-to-agent messaging
|
||||
- `agent-reservations.ts` - Path-based scope locks
|
||||
- `agent-sessions.ts` - Session aggregation
|
||||
|
||||
### Architecture Principle
|
||||
|
||||
```
|
||||
Identity → bd agent bead (git-tracked, team-visible)
|
||||
Presence → bd agent heartbeat
|
||||
State → bd agent state
|
||||
Messaging → bb agent send/inbox (custom)
|
||||
Scope locks → bb agent reserve/release (custom)
|
||||
```
|
||||
|
||||
**Why:** Single truth, survives compaction, team coordination, bd query access.
|
||||
|
||||
## Gate Commands
|
||||
|
||||
```bash
|
||||
bd gate list # All open gates
|
||||
bd gate check # Evaluate and auto-close resolved
|
||||
bd gate resolve <id> # Manually close gate
|
||||
```
|
||||
|
||||
**Gate types:** `human` (manual), `timer` (expires), `gh:run` (GitHub workflow), `gh:pr` (PR merge), `bead` (cross-rig bead)
|
||||
|
||||
**Use when:** Workflow needs human approval or external event.
|
||||
|
||||
## Molecule Commands
|
||||
|
||||
```bash
|
||||
bd mol pour <proto> # Persistent mol (solid → liquid)
|
||||
bd mol wisp <proto> # Ephemeral wisp (vapor)
|
||||
bd mol show <id> # View structure
|
||||
bd mol current # Position in workflow
|
||||
bd mol burn <id> # Discard wisp
|
||||
bd mol squash <id> # Compress to digest
|
||||
```
|
||||
|
||||
**Wisp vs Mol:**
|
||||
| Wisp (ephemeral) | Mol (persistent) |
|
||||
|------------------|------------------|
|
||||
| Exploration/experiment | Production workflow |
|
||||
| Auto-deletes on close | Survives sessions |
|
||||
| Fast iteration | Full audit trail |
|
||||
|
||||
**Use wisp when:** Uncertain scope, exploring. **Use mol when:** Committed workflow.
|
||||
|
||||
## Swarm Commands
|
||||
|
||||
```bash
|
||||
bd swarm create <epic> # Create from epic
|
||||
bd swarm status # Current progress
|
||||
bd swarm list # All swarms
|
||||
bd swarm validate <epic> # Check structure
|
||||
```
|
||||
|
||||
**Use when:** Epic has parallelizable children. Swarm enables multi-agent execution.
|
||||
|
||||
## Worktree Commands
|
||||
|
||||
```bash
|
||||
bd worktree create <name> # Isolated directory
|
||||
bd worktree list # All worktrees
|
||||
bd worktree remove <name> # Clean up
|
||||
bd worktree info # Current context
|
||||
```
|
||||
|
||||
**Use when:** Parallel feature work. Each worktree shares .beads but has isolated files.
|
||||
|
||||
## Query Language
|
||||
|
||||
```bash
|
||||
bd query "status=open AND priority>1"
|
||||
bd query "updated>7d AND NOT status=closed"
|
||||
bd query "(status=open OR status=blocked) AND label=urgent"
|
||||
bd query "assignee=none AND type=task"
|
||||
```
|
||||
|
||||
**Use when:** Complex filtering beyond basic flags.
|
||||
|
||||
## Dependency Commands
|
||||
|
||||
```bash
|
||||
bd dep add <blocked> <blocker> # Add dependency
|
||||
bd dep remove <blocked> <blocker>
|
||||
bd dep tree <id> # Visual tree
|
||||
bd dep cycles # Detect cycles
|
||||
bd dep list <id> # List deps
|
||||
```
|
||||
|
||||
**Use when:** Modeling work relationships. Critical for parallelization.
|
||||
|
||||
## Advanced Session Protocol
|
||||
|
||||
### Multi-Agent Claim
|
||||
```bash
|
||||
bd ready
|
||||
bd show <id>
|
||||
bd slot set <my-agent-id> hook <id> # Claim exclusive
|
||||
bd update <id> --status in_progress
|
||||
bd agent heartbeat <my-agent-id> # Signal presence
|
||||
```
|
||||
|
||||
### Human Gate Checkpoint
|
||||
```bash
|
||||
bd gate add --type=human --await_id=<id> "Needs review"
|
||||
# Continue other work...
|
||||
bd gate check # After human approval, gate closes
|
||||
```
|
||||
|
||||
### Parallel Swarm Execution
|
||||
```bash
|
||||
bd swarm create <epic-id>
|
||||
bd swarm status # Shows parallelizable paths
|
||||
# Dispatch agents to parallel beads
|
||||
```
|
||||
|
||||
### Isolated Feature Work
|
||||
```bash
|
||||
bd worktree create feature-x
|
||||
cd ../feature-x
|
||||
# Work in isolation, shared .beads
|
||||
bd sync # Push changes
|
||||
cd ../main
|
||||
bd worktree remove feature-x
|
||||
```
|
||||
|
||||
## Prime Context
|
||||
|
||||
```bash
|
||||
bd prime # AI-optimized workflow (~50 tokens in MCP mode)
|
||||
bd prime --full # Full reference (~1-2k tokens)
|
||||
```
|
||||
|
||||
**Use:** At session start, after compaction, when unsure of workflow.
|
||||
|
||||
## Audit Trail
|
||||
|
||||
```bash
|
||||
bd audit record --type=<type> --data='<json>'
|
||||
bd audit label <entry-id> --label='<label>'
|
||||
```
|
||||
|
||||
**Use when:** Recording agent decisions. SFT/RL dataset generation.
|
||||
|
||||
## Advanced Close Ritual
|
||||
|
||||
```bash
|
||||
# Full verification
|
||||
npm run typecheck && npm run lint && npm run test
|
||||
|
||||
# Evidence documentation
|
||||
bd update <id> --notes "Evidence:
|
||||
- typecheck: PASS
|
||||
- lint: PASS
|
||||
- test: PASS (N/N)
|
||||
- Coverage: X%
|
||||
- Artifacts: ..."
|
||||
|
||||
# Human gate if needed
|
||||
bd gate resolve <gate-id> # If checkpoint required
|
||||
|
||||
# Close
|
||||
bd close <id> --reason "..."
|
||||
|
||||
# Sync
|
||||
bd sync && git push
|
||||
|
||||
# Clear slot if agent
|
||||
bd slot clear <agent> hook
|
||||
|
||||
# Report state
|
||||
bd agent state <agent> done
|
||||
```
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
| Situation | Command |
|
||||
|-----------|---------|
|
||||
| Uncertain scope | `bd mol wisp` |
|
||||
| Committed workflow | `bd mol pour` |
|
||||
| Multi-agent parallel | `bd swarm create` |
|
||||
| Isolated feature | `bd worktree create` |
|
||||
| Human approval needed | `bd gate add --type=human` |
|
||||
| Complex filtering | `bd query "expr"` |
|
||||
| Claim exclusive work | `bd slot set` |
|
||||
| Signal presence | `bd agent heartbeat` |
|
||||
| After compaction | `bd prime && bd show <id>` |
|
||||
|
||||
## Linus-Level Principles
|
||||
|
||||
1. **Data-first workflow**: Use `bd query` to analyze before acting
|
||||
2. **Explicit coordination**: `bd slot` for claiming, `bd agent` for presence
|
||||
3. **Parallel by default**: `bd swarm` + `bd worktree` for isolation
|
||||
4. **Human gates**: `bd gate` for approval checkpoints
|
||||
5. **Ephemeral exploration**: `bd mol wisp` before committing
|
||||
6. **Audit everything**: `bd audit record` for decisions
|
||||
|
||||
**Linus would use all of these. Not just `bd ready` and `bd close`.**
|
||||
|
|
@ -0,0 +1,367 @@
|
|||
# Beads Integration
|
||||
|
||||
**BD as religious discipline. Not overhead—truth.**
|
||||
|
||||
## The Religion
|
||||
|
||||
Beads is not a tool. Beads IS the work state.
|
||||
|
||||
```
|
||||
BD = Truth
|
||||
Code = Implementation of truth
|
||||
Tests = Verification of implementation
|
||||
Gates = Ritual proving truth
|
||||
```
|
||||
|
||||
Every bypass is a lie to yourself about what the work state is.
|
||||
|
||||
## The Sacraments
|
||||
|
||||
### 1. `bd prime` - Awakening
|
||||
|
||||
Start of any session:
|
||||
```bash
|
||||
bd prime # AI-optimized workflow context
|
||||
```
|
||||
|
||||
This is knowing the ritual. ~50 tokens of essential workflow.
|
||||
|
||||
### 2. `bd ready` - Morning Prayer
|
||||
|
||||
Before any work:
|
||||
```bash
|
||||
bd ready # What is unblocked?
|
||||
```
|
||||
|
||||
This is not optional. This is asking: "What should I work on?"
|
||||
|
||||
### 3. `bd show <id>` - Reading Scripture
|
||||
|
||||
Before implementing:
|
||||
```bash
|
||||
bd show bb-xyz # What does this bead require?
|
||||
```
|
||||
|
||||
This is understanding the task. Not guessing. Not assuming. Reading.
|
||||
|
||||
### 4. `bd slot set` - Taking Vows (Advanced)
|
||||
|
||||
Claiming exclusive work:
|
||||
```bash
|
||||
bd slot set gt-agent hook bb-xyz # Exclusive claim
|
||||
```
|
||||
|
||||
This is commitment with lock. Prevents other agents from same work.
|
||||
|
||||
### 5. `bd update --status in_progress` - Public Declaration
|
||||
|
||||
Starting work:
|
||||
```bash
|
||||
bd update bb-xyz --status in_progress --notes "Plan: implement X, verify Y"
|
||||
```
|
||||
|
||||
This is commitment. Public declaration. Now you're accountable.
|
||||
|
||||
### 6. `bd update --notes` - Confession
|
||||
|
||||
As you work:
|
||||
```bash
|
||||
bd update bb-xyz --notes "Progress: X done, Y in progress, Z blocked by ..."
|
||||
```
|
||||
|
||||
This is documentation. Future agents need to know. Past you forgets.
|
||||
|
||||
### 7. `bb agent` Commands - Passive Presence (Project-Specific)
|
||||
|
||||
This project uses `bb agent` (tools/bb.ts) for coordination, not `bd agent`:
|
||||
|
||||
```bash
|
||||
# Register identity (session start)
|
||||
bb agent register --name amber-otter --role backend
|
||||
|
||||
# Reserve work scope (claim lock)
|
||||
bb agent reserve --agent amber-otter --scope C:/project --bead bb-xyz
|
||||
|
||||
# Any command with --agent extends activity lease automatically
|
||||
bb agent status --agent amber-otter # Extends lease as side-effect
|
||||
```
|
||||
|
||||
**Passive Activity Lease:** No background heartbeat. Lease extends on real work.
|
||||
|
||||
**Liveness:** `active` (<15m), `stale` (15-30m), `evicted` (30-60m), `idle` (>=60m)
|
||||
|
||||
### 8. Verification Gates - Ritual Cleansing
|
||||
|
||||
Before closing:
|
||||
```bash
|
||||
npm run typecheck && npm run lint && npm run test
|
||||
```
|
||||
|
||||
This is proof. Not "I think it works". Proof.
|
||||
|
||||
### 9. `bd close` - Absolution
|
||||
|
||||
Completing work:
|
||||
```bash
|
||||
bd close bb-xyz --reason "Complete with evidence: gates pass, tests pass"
|
||||
```
|
||||
|
||||
This is absolution. Work is done. Truth is updated.
|
||||
|
||||
### 10. `bd sync` - Communion
|
||||
|
||||
End of session:
|
||||
```bash
|
||||
bd sync # Git push the truth
|
||||
```
|
||||
|
||||
This is sharing. Team knows state. Future sessions have context.
|
||||
|
||||
## The Heresies
|
||||
|
||||
### Direct JSONL Edit
|
||||
|
||||
```
|
||||
WRITING TO .beads/issues.jsonl DIRECTLY
|
||||
```
|
||||
|
||||
This is bypassing truth. This is creating shadow truth. This is heresy.
|
||||
|
||||
**Correction**: Delete changes. Use bd commands. Confess in notes.
|
||||
|
||||
### Claim Without Evidence
|
||||
|
||||
```
|
||||
CLOSING A BEAD WITHOUT RUNNING GATES
|
||||
```
|
||||
|
||||
This is lying about completion. This is claiming truth you haven't proven.
|
||||
|
||||
**Correction**: Re-open bead. Run gates. Cite output. Close with evidence.
|
||||
|
||||
### Skip BD Commands
|
||||
|
||||
```
|
||||
"bd is too slow, I'll just..."
|
||||
```
|
||||
|
||||
This is convenience over truth. This is the root of all drift.
|
||||
|
||||
**Correction**: Use bd. Slow truth > fast lies.
|
||||
|
||||
### Stale Session Start
|
||||
|
||||
```
|
||||
STARTING WORK WITHOUT `bd ready`
|
||||
```
|
||||
|
||||
This is working without knowing what to work on. This is blindness.
|
||||
|
||||
**Correction**: `bd ready` first. Always.
|
||||
|
||||
## The Daily Practice
|
||||
|
||||
### Start of Session
|
||||
```bash
|
||||
bd ready # What's unblocked?
|
||||
bd show <id> # What does it require?
|
||||
bd update <id> --status in_progress --notes "Plan: ..."
|
||||
```
|
||||
|
||||
### During Work
|
||||
```bash
|
||||
# After each meaningful progress
|
||||
bd update <id> --notes "Progress: X complete, evidence: ..."
|
||||
```
|
||||
|
||||
### End of Session
|
||||
```bash
|
||||
npm run typecheck && npm run lint && npm run test
|
||||
bd update <id> --notes "Session end: ... Evidence: ..."
|
||||
bd sync
|
||||
```
|
||||
|
||||
### Closing a Bead
|
||||
```bash
|
||||
# Full ritual
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run test
|
||||
bd update <id> --notes "Final evidence: typecheck ✓, lint ✓, test ✓"
|
||||
bd close <id> --reason "Complete with verification"
|
||||
bd sync
|
||||
```
|
||||
|
||||
## Compaction Survival
|
||||
|
||||
When conversation is compacted, beads survives:
|
||||
|
||||
```
|
||||
Previous session:
|
||||
- bd update bb-xyz --notes "Implemented X, need to add tests"
|
||||
|
||||
After compaction:
|
||||
- bd show bb-xyz
|
||||
- Notes say: "Implemented X, need to add tests"
|
||||
- You know: Add tests
|
||||
- No context lost
|
||||
```
|
||||
|
||||
**This is the point of beads.** Memory that survives compaction.
|
||||
|
||||
## Multi-Agent Coordination
|
||||
|
||||
When multiple agents work:
|
||||
|
||||
```
|
||||
Agent A: bd slot set gt-agent-a hook bb-xyz # Claim
|
||||
Agent A: bd update bb-xyz --status in_progress
|
||||
Agent B: bd ready # bb-xyz not shown (in_progress)
|
||||
Agent A: bd close bb-xyz
|
||||
Agent A: bd slot clear gt-agent-a hook # Release
|
||||
Agent B: bd ready # Now sees newly unblocked beads
|
||||
```
|
||||
|
||||
BD coordinates without agents communicating directly. Truth is shared.
|
||||
|
||||
### Agent Presence Protocol
|
||||
|
||||
```bash
|
||||
# At session start
|
||||
bd agent state gt-agent-a spawning
|
||||
bd agent heartbeat gt-agent-a
|
||||
|
||||
# While working
|
||||
bd agent state gt-agent-a working
|
||||
bd agent heartbeat gt-agent-a # Every few minutes
|
||||
|
||||
# When stuck
|
||||
bd agent state gt-agent-a stuck
|
||||
|
||||
# When done
|
||||
bd agent state gt-agent-a done
|
||||
```
|
||||
|
||||
### Slot-Based Claiming
|
||||
|
||||
```
|
||||
hook slot = exclusive work claim
|
||||
role slot = agent's role definition
|
||||
```
|
||||
|
||||
Multiple agents cannot claim same bead via slots. Coordination is automatic.
|
||||
|
||||
## The Promise
|
||||
|
||||
By using beads religiously, you promise:
|
||||
|
||||
1. **Truth over convenience** - BD always, even when slow
|
||||
2. **Evidence over claims** - Gates always, even when "obvious"
|
||||
3. **Future over present** - Document for agents you'll never meet
|
||||
4. **Consistency over creativity** - Ritual ensures quality
|
||||
5. **Coordination over isolation** - Slots, heartbeats, swarms
|
||||
|
||||
## Advanced Rituals
|
||||
|
||||
### Swarm Coordination
|
||||
|
||||
When epic has parallelizable children:
|
||||
```bash
|
||||
bd swarm create bb-epic # Create swarm molecule
|
||||
bd swarm status # See parallel paths
|
||||
# Dispatch agents to independent beads
|
||||
bd swarm validate bb-epic # Check structure
|
||||
```
|
||||
|
||||
Swarm enables multi-agent parallel execution of DAG.
|
||||
|
||||
### Molecule Workflows
|
||||
|
||||
For repeatable patterns:
|
||||
```bash
|
||||
bd formula list # Available templates
|
||||
bd mol pour <proto> # Persistent mol
|
||||
bd mol wisp <proto> # Ephemeral exploration
|
||||
bd mol current # Position in workflow
|
||||
```
|
||||
|
||||
Molecules = templated workflows. Pour for commitment, wisp for exploration.
|
||||
|
||||
### Worktree Isolation
|
||||
|
||||
For parallel feature work:
|
||||
```bash
|
||||
bd worktree create feature-x
|
||||
cd ../feature-x
|
||||
# Isolated files, shared .beads
|
||||
bd sync
|
||||
cd ../main
|
||||
bd worktree remove feature-x
|
||||
```
|
||||
|
||||
Worktrees = isolated directories. Same truth, different files.
|
||||
|
||||
### Human Gates
|
||||
|
||||
For irreversible actions:
|
||||
```bash
|
||||
bd gate add --type=human "Needs security review"
|
||||
# Work continues on other beads
|
||||
bd gate check # After human approval
|
||||
# Gate closes, blocked bead proceeds
|
||||
```
|
||||
|
||||
Gates = async checkpoints. Human-in-the-loop coordination.
|
||||
|
||||
## The Reward
|
||||
|
||||
Following beads discipline:
|
||||
|
||||
- **No lost context** - Compaction can't kill your work
|
||||
- **No truth drift** - State always matches reality
|
||||
- **No coordination overhead** - BD coordinates for you
|
||||
- **No "what was I doing?"** - Notes tell you
|
||||
- **No "does this work?"** - Gates prove it
|
||||
|
||||
## The Punishment
|
||||
|
||||
Violating beads discipline:
|
||||
|
||||
- **Lost context** - Compaction erases untracked work
|
||||
- **Truth drift** - Code and state diverge, bugs emerge
|
||||
- **Coordination chaos** - Agents duplicate or block each other
|
||||
- **Memory loss** - Future you has no idea what past you did
|
||||
- **Unproven claims** - "Works" becomes "broken in production"
|
||||
|
||||
## The Bottom Line
|
||||
|
||||
**Beads is your source of truth.**
|
||||
|
||||
Not "a tool for tracking". IS the tracking. IS the work state. IS the memory. IS the coordination.
|
||||
|
||||
**Linus-level mastery requires:**
|
||||
- `bd prime` for context
|
||||
- `bb agent reserve/release` for scope claiming (this project)
|
||||
- `bb agent status --agent <id>` for passive presence (this project)
|
||||
- `bd swarm` for parallelization
|
||||
- `bd gate` for checkpoints
|
||||
- `bd mol` for workflows
|
||||
- `bd worktree` for isolation
|
||||
- `bd query` for analysis
|
||||
|
||||
**Key distinction:**
|
||||
- `bb agent` = project coordination via tools/bb.ts (passive lease, reservations)
|
||||
- `bd agent` = agent beads in bd issues (for agent-labeled beads)
|
||||
|
||||
Treat it with the respect truth deserves.
|
||||
|
||||
```
|
||||
BD = Truth
|
||||
Gates = Proof
|
||||
Notes = Memory
|
||||
Sync = Survival
|
||||
Reservations = Locks
|
||||
Passive Lease = Presence
|
||||
Swarm = Parallel
|
||||
Gates = Checkpoints
|
||||
```
|
||||
113
.agents/skills/linus-beads-discipline/resources/BEADS_MEMORY.md
Normal file
113
.agents/skills/linus-beads-discipline/resources/BEADS_MEMORY.md
Normal file
|
|
@ -0,0 +1,113 @@
|
|||
# Beads as Shared Memory
|
||||
|
||||
**The shared brain for all Linus-agents.**
|
||||
|
||||
## The Principle
|
||||
|
||||
```
|
||||
All Linus-agents share the same beads.
|
||||
Your notes are read by other agents.
|
||||
Their notes inform your work.
|
||||
Coordinate through truth, not messages.
|
||||
```
|
||||
|
||||
## Every Session
|
||||
|
||||
### Start: READ
|
||||
```bash
|
||||
bd ready # What's unblocked?
|
||||
bd show <id> # What are the details?
|
||||
bd query "status=closed AND notes~=<topic>" # What was learned before?
|
||||
```
|
||||
|
||||
**NEVER start work without reading beads first.**
|
||||
|
||||
### During: WRITE
|
||||
```bash
|
||||
bd update <id> --notes "Progress: ...
|
||||
Evidence: ...
|
||||
Blockers: ...
|
||||
Next: ..."
|
||||
```
|
||||
|
||||
**Every meaningful progress = update.**
|
||||
|
||||
### End: SYNC
|
||||
```bash
|
||||
bd sync # Share with other agents
|
||||
```
|
||||
|
||||
**NEVER end session without syncing.**
|
||||
|
||||
## Handoff Protocol
|
||||
|
||||
### When You're Done
|
||||
```bash
|
||||
bd update <id> --notes "Handoff:
|
||||
## Completed
|
||||
- X, Y done, evidence: [gates]
|
||||
|
||||
## Incomplete
|
||||
- Z remaining
|
||||
|
||||
## For Next Agent
|
||||
- Gotcha: <non-obvious thing>
|
||||
- Pattern: <what to follow>
|
||||
- Files: <what changed>"
|
||||
```
|
||||
|
||||
### When Picking Up Another's Work
|
||||
```bash
|
||||
bd show <id> # Read their notes
|
||||
bd query "id=<id>" --comments # Read comments
|
||||
# Acknowledge their work in your first update
|
||||
bd update <id> --notes "Continuing from <agent>. Last state: ..."
|
||||
```
|
||||
|
||||
## Memory That Survives Compaction
|
||||
|
||||
When conversation is compacted, beads survives:
|
||||
|
||||
```
|
||||
Previous session:
|
||||
- bd update bb-xyz --notes "Implemented X, need tests"
|
||||
|
||||
After compaction:
|
||||
- bd show bb-xyz
|
||||
- Notes say: "Implemented X, need tests"
|
||||
- You know: Add tests
|
||||
- Zero context lost
|
||||
```
|
||||
|
||||
**This is the point. Memory that survives session boundaries.**
|
||||
|
||||
## Notes For Future Agents
|
||||
|
||||
Your notes should answer:
|
||||
- **What did you learn?** (findings)
|
||||
- **What did you decide?** (decisions + rationale)
|
||||
- **What's incomplete?** (handoff)
|
||||
- **What blocked you?** (blockers)
|
||||
- **What would help next agent?** (hints)
|
||||
|
||||
## Cross-Agent Visibility
|
||||
|
||||
```bash
|
||||
# See who else is working
|
||||
bd query "status=in_progress"
|
||||
|
||||
# See what was recently closed
|
||||
bd query "status=closed AND updated<1d"
|
||||
|
||||
# See agent activity
|
||||
bd query "labels~=gt:agent"
|
||||
```
|
||||
|
||||
## The Promise
|
||||
|
||||
By using beads religiously:
|
||||
- **No lost context** - Compaction can't kill your work
|
||||
- **No truth drift** - State always matches reality
|
||||
- **No coordination overhead** - BD coordinates for you
|
||||
- **No "what was I doing?"** - Notes tell you
|
||||
- **No "who else is working?"** - Query tells you
|
||||
|
|
@ -0,0 +1,240 @@
|
|||
# Decision Frameworks
|
||||
|
||||
**Systematic approaches for common engineering decisions.**
|
||||
|
||||
## When to Add Abstraction
|
||||
|
||||
```
|
||||
Current concrete use case exists?
|
||||
│
|
||||
┌──────────────┴──────────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Does abstraction simplify REJECT
|
||||
THIS case (not future cases)? (YAGNI)
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
CONSIDER REJECT
|
||||
(proceed to (add when
|
||||
cost analysis) need proven)
|
||||
```
|
||||
|
||||
### Abstraction Cost Analysis
|
||||
|
||||
| Cost | Question | Reject If |
|
||||
|------|----------|-----------|
|
||||
| Maintenance | Will someone need to understand this in 5 years? | Complexity > benefit |
|
||||
| Debugging | Does indirection make tracing harder? | Yes, and no tooling helps |
|
||||
| Performance | Does abstraction add measurable overhead? | Yes, and no mitigation |
|
||||
| Cognitive | Does developer need to learn 2+ concepts? | Learning cost > simplicity gain |
|
||||
|
||||
### Valid Abstraction Reasons
|
||||
|
||||
- ✅ Multiple current consumers with same interface need
|
||||
- ✅ Complex logic needs isolation for testability
|
||||
- ✅ Performance optimization that benefits multiple paths
|
||||
- ✅ Platform boundary (not just "flexibility")
|
||||
|
||||
### Invalid Abstraction Reasons
|
||||
|
||||
- ❌ "Might need it later"
|
||||
- ❌ "More professional/extensible"
|
||||
- ❌ "Follows design pattern X"
|
||||
- ❌ "Team standard" (without concrete need)
|
||||
|
||||
## When to Close a Bead
|
||||
|
||||
```
|
||||
All gates pass?
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Evidence cited? Fix failures
|
||||
│ then re-check
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Notes updated? Cite evidence
|
||||
│ in notes
|
||||
┌─────┴─────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
CLOSE Update notes
|
||||
then close
|
||||
```
|
||||
|
||||
### Close Checklist
|
||||
|
||||
```
|
||||
□ npm run typecheck → PASS (output cited)
|
||||
□ npm run lint → PASS (output cited)
|
||||
□ npm run test → PASS (output cited)
|
||||
□ UI changed? → Screenshots captured, paths noted
|
||||
□ Notes? → All progress documented
|
||||
□ Evidence? → Commands + results cited
|
||||
□ Dependencies? → Confirm blockers still resolved
|
||||
```
|
||||
|
||||
### Close Command Template
|
||||
```bash
|
||||
bd update <id> --notes "Evidence:
|
||||
- typecheck: PASS (0 errors)
|
||||
- lint: PASS (0 warnings)
|
||||
- test: PASS (N/N tests)
|
||||
- [UI: screenshots at artifacts/...]"
|
||||
|
||||
bd close <id> --reason "Completed with full verification. [Brief summary of what was done.]"
|
||||
```
|
||||
|
||||
## When to Fix Bug vs Patch Symptom
|
||||
|
||||
```
|
||||
Bug found
|
||||
│
|
||||
▼
|
||||
Why was this bug possible?
|
||||
│
|
||||
┌──────────────┴──────────────┐
|
||||
Design flaw Isolated mistake
|
||||
│ │
|
||||
▼ ▼
|
||||
Fix design, eliminate Patch this instance
|
||||
entire bug class + add test
|
||||
│ │
|
||||
▼ ▼
|
||||
Example: Input validation Example: Typo in
|
||||
missing at boundary variable name
|
||||
→ Add validation at entry → Fix typo
|
||||
→ Bug class eliminated → Add spellcheck
|
||||
```
|
||||
|
||||
### Bug Class Analysis
|
||||
|
||||
| Symptom | Look For | Fix At |
|
||||
|---------|----------|--------|
|
||||
| Null pointer | Missing validation at boundaries | Entry point validation |
|
||||
| Race condition | Shared mutable state without synchronization | Data structure design |
|
||||
| Off-by-one | Boundary condition pattern | Abstraction for iteration |
|
||||
| Type mismatch | Weak typing at interfaces | TypeScript strict mode |
|
||||
| Memory leak | Ownership unclear | RAII / ownership model |
|
||||
|
||||
### Linus's Approach
|
||||
|
||||
1. **Trace to root cause** - Not just "where it crashed"
|
||||
2. **Ask "why was this possible?"** - What enabled this bug class?
|
||||
3. **Fix design if needed** - Better to eliminate bug class than patch instances
|
||||
4. **Add regression test** - Ensure class can't return
|
||||
|
||||
## When to Refactor
|
||||
|
||||
```
|
||||
Pain point exists?
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Pain quantified? Don't refactor
|
||||
│ (premature)
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Benefit > cost? Quantify first
|
||||
│ (measure pain)
|
||||
┌─┴─┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Refactor Don't refactor
|
||||
now (track as bead)
|
||||
```
|
||||
|
||||
### Refactor Quantification
|
||||
|
||||
| Pain | Measurement | Threshold |
|
||||
|------|-------------|-----------|
|
||||
| Slow | Profile, ms | >100ms hot path |
|
||||
| Confusing | PR comments, questions | >3 questions/month |
|
||||
| Bug-prone | Bug count in area | >2 bugs/quarter |
|
||||
| Slow to change | Time to add feature | >2x expected |
|
||||
|
||||
### Refactor Rules
|
||||
|
||||
- ✅ Have test coverage first
|
||||
- ✅ Measure before and after
|
||||
- ✅ One vertical slice at a time
|
||||
- ❌ Don't refactor "while here" without tracking
|
||||
- ❌ Don't refactor for style without measurable benefit
|
||||
|
||||
## When to Create Bead
|
||||
|
||||
```
|
||||
Work identified
|
||||
│
|
||||
▼
|
||||
Will it take >30 min?
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Has dependencies? Just do it
|
||||
│ (no bead needed)
|
||||
┌──────┴──────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Create bead Create bead
|
||||
with deps (simple task)
|
||||
```
|
||||
|
||||
### Bead Worth Creating If
|
||||
|
||||
- Spans sessions / needs compaction survival
|
||||
- Has dependencies / blockers
|
||||
- Complex acceptance criteria
|
||||
- Needs collaboration
|
||||
- Risk of context loss
|
||||
|
||||
### No Bead Needed If
|
||||
|
||||
- <30 minutes single session
|
||||
- No dependencies
|
||||
- Clear immediate action
|
||||
- Will complete in this session
|
||||
|
||||
## When to Parallelize
|
||||
|
||||
```
|
||||
Multiple independent tasks?
|
||||
│
|
||||
┌──────────┴──────────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Shared state needed? Execute sequentially
|
||||
│
|
||||
┌──────┴──────┐
|
||||
YES NO
|
||||
│ │
|
||||
▼ ▼
|
||||
Sequential PARALLELIZE
|
||||
(avoid races) via subagents
|
||||
```
|
||||
|
||||
### Parallelization Rules
|
||||
|
||||
- ✅ No shared state between tasks
|
||||
- ✅ No read-after-write dependencies
|
||||
- ✅ Each task owns distinct files
|
||||
- ❌ Don't parallelize if tasks modify same files
|
||||
- ❌ Don't parallelize if order matters for correctness
|
||||
303
.agents/skills/linus-beads-discipline/resources/EXAMPLES.md
Normal file
303
.agents/skills/linus-beads-discipline/resources/EXAMPLES.md
Normal file
|
|
@ -0,0 +1,303 @@
|
|||
# Examples
|
||||
|
||||
**Before/after code comparisons demonstrating Linus-Beads discipline.**
|
||||
|
||||
## Abstraction
|
||||
|
||||
### ❌ Bad: Abstraction Without Need
|
||||
|
||||
```typescript
|
||||
// "We might need to support different backends later"
|
||||
interface ITaskRepository {
|
||||
getTasks(): Promise<Task[]>;
|
||||
saveTask(task: Task): Promise<void>;
|
||||
}
|
||||
|
||||
class JsonlTaskRepository implements ITaskRepository {
|
||||
// 50 lines of implementation
|
||||
}
|
||||
|
||||
class MemoryTaskRepository implements ITaskRepository {
|
||||
// 40 lines for "testing" - but no test uses it
|
||||
}
|
||||
|
||||
// Current requirement: Read from JSONL, write via bd CLI
|
||||
// This adds: 1 interface, 2 classes, 90+ lines
|
||||
// This provides: 0 current value
|
||||
// This costs: maintenance burden forever
|
||||
```
|
||||
|
||||
### ✅ Good: Direct Implementation
|
||||
|
||||
```typescript
|
||||
// Current requirement: Read from JSONL, write via bd
|
||||
function readIssues(rootPath: string): Issue[] {
|
||||
const content = fs.readFileSync(`${rootPath}/.beads/issues.jsonl`, 'utf-8');
|
||||
return parseJsonl(content);
|
||||
}
|
||||
|
||||
// 8 lines. Obvious. Correct.
|
||||
// Abstraction added ONLY when second backend proven by actual need
|
||||
```
|
||||
|
||||
## Evidence Skip
|
||||
|
||||
### ❌ Bad: Claim Without Evidence
|
||||
|
||||
```bash
|
||||
# Agent: "I tested it manually, works"
|
||||
bd close bb-xyz --reason "Fixed the bug"
|
||||
# No evidence cited
|
||||
# No gates run
|
||||
# Claim accepted without proof
|
||||
```
|
||||
|
||||
### ✅ Good: Evidence Cited
|
||||
|
||||
```bash
|
||||
# Run gates first
|
||||
npm run typecheck # PASS - 0 errors
|
||||
npm run lint # PASS - 0 warnings
|
||||
npm run test # PASS - 47 tests in 2.3s
|
||||
|
||||
# Document evidence
|
||||
bd update bb-xyz --notes "
|
||||
Verification complete:
|
||||
- typecheck: PASS (0 errors, 0 warnings)
|
||||
- lint: PASS (0 warnings)
|
||||
- test: PASS (47/47, 2.3s)
|
||||
- UI: artifacts/fix-mobile-390.png
|
||||
"
|
||||
|
||||
# Close with proof
|
||||
bd close bb-xyz --reason "Fixed with full verification. All gates pass."
|
||||
```
|
||||
|
||||
## Duplicate Fix
|
||||
|
||||
### ❌ Bad: Copy-Paste Fix
|
||||
|
||||
```typescript
|
||||
// kanban-detail.tsx
|
||||
function renderStatus(status: string) {
|
||||
const colors = {
|
||||
open: 'text-green-400',
|
||||
in_progress: 'text-blue-400',
|
||||
blocked: 'text-red-400',
|
||||
closed: 'text-gray-400'
|
||||
};
|
||||
return <span className={colors[status]}>{status}</span>;
|
||||
}
|
||||
|
||||
// graph-detail.tsx (different page, same need)
|
||||
function renderStatus(status: string) {
|
||||
const colors = {
|
||||
open: 'text-green-500', // Different shade
|
||||
in_progress: 'text-blue-500',
|
||||
blocked: 'text-red-500',
|
||||
closed: 'text-gray-500'
|
||||
};
|
||||
return <span className={colors[status]}>{status}</span>;
|
||||
}
|
||||
|
||||
// Two places to maintain
|
||||
// Two places to have bugs
|
||||
// Inconsistency breeds confusion
|
||||
```
|
||||
|
||||
### ✅ Good: Shared Logic
|
||||
|
||||
```typescript
|
||||
// shared/status-renderer.tsx
|
||||
export const STATUS_COLORS = {
|
||||
open: 'text-green-400',
|
||||
in_progress: 'text-blue-400',
|
||||
blocked: 'text-red-400',
|
||||
closed: 'text-gray-400'
|
||||
} as const;
|
||||
|
||||
export function renderStatus(status: string) {
|
||||
return <span className={STATUS_COLORS[status]}>{status}</span>;
|
||||
}
|
||||
|
||||
// kanban-detail.tsx
|
||||
import { renderStatus } from '@/shared/status-renderer';
|
||||
|
||||
// graph-detail.tsx
|
||||
import { renderStatus } from '@/shared/status-renderer';
|
||||
|
||||
// One implementation
|
||||
// One place to maintain
|
||||
// Consistency guaranteed
|
||||
```
|
||||
|
||||
## BD Bypass
|
||||
|
||||
### ❌ Bad: Direct JSONL Write
|
||||
|
||||
```typescript
|
||||
// "bd update is too slow for this simple change"
|
||||
const issues = JSON.parse(fs.readFileSync('.beads/issues.jsonl'));
|
||||
issues.push(newIssue);
|
||||
fs.writeFileSync('.beads/issues.jsonl', JSON.stringify(issues));
|
||||
|
||||
// Truth bypassed
|
||||
// Schema potentially violated
|
||||
// bd state unknown
|
||||
// Race condition with other bd operations
|
||||
```
|
||||
|
||||
### ✅ Good: BD Command
|
||||
|
||||
```bash
|
||||
# Use bd CLI for all mutations
|
||||
bd create --title "New task" --acceptance "Must work"
|
||||
|
||||
# bd ensures:
|
||||
# - Schema validation
|
||||
# - ID uniqueness
|
||||
# - Dependency integrity
|
||||
# - Git sync
|
||||
```
|
||||
|
||||
## Bug Fix
|
||||
|
||||
### ❌ Bad: Patch Symptom
|
||||
|
||||
```typescript
|
||||
// Bug: crash when user.profile is null
|
||||
// Fix: Add null check at crash site
|
||||
function renderUserCard(user: User) {
|
||||
return (
|
||||
<Card>
|
||||
<Text>{user.name}</Text>
|
||||
{user.profile && <Text>{user.profile.bio}</Text>}
|
||||
</Card>
|
||||
);
|
||||
}
|
||||
|
||||
// Problem: user.profile being null is unexpected
|
||||
// This hides the real bug: why is profile null?
|
||||
// 10 other places might crash on null profile
|
||||
```
|
||||
|
||||
### ✅ Good: Fix Root Cause
|
||||
|
||||
```typescript
|
||||
// Trace: why is user.profile null?
|
||||
// Found: ProfileService.load() fails silently
|
||||
|
||||
// Fix the service
|
||||
class ProfileService {
|
||||
async load(userId: string): Promise<Profile> {
|
||||
const profile = await this.db.profiles.find(userId);
|
||||
if (!profile) {
|
||||
// Create default instead of returning null
|
||||
return this.createDefault(userId);
|
||||
}
|
||||
return profile;
|
||||
}
|
||||
}
|
||||
|
||||
// Now user.profile is never null
|
||||
// Entire bug class eliminated
|
||||
// All 10 crash sites now safe
|
||||
```
|
||||
|
||||
## Complexity
|
||||
|
||||
### ❌ Bad: Nested Logic
|
||||
|
||||
```typescript
|
||||
function processOrder(order: Order) {
|
||||
if (order.status === 'pending') {
|
||||
if (order.items.length > 0) {
|
||||
for (const item of order.items) {
|
||||
if (item.available) {
|
||||
if (item.price > 0) {
|
||||
// 5 levels deep
|
||||
// Hard to read
|
||||
// Hard to test
|
||||
// Bug-prone
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### ✅ Good: Early Returns
|
||||
|
||||
```typescript
|
||||
function processOrder(order: Order) {
|
||||
if (order.status !== 'pending') return;
|
||||
if (order.items.length === 0) return;
|
||||
|
||||
const validItems = order.items
|
||||
.filter(item => item.available && item.price > 0);
|
||||
|
||||
// 1 level deep
|
||||
// Obvious flow
|
||||
// Easy to test
|
||||
// Correct by inspection
|
||||
}
|
||||
```
|
||||
|
||||
## Evidence in Notes
|
||||
|
||||
### ❌ Bad: Vague Notes
|
||||
|
||||
```bash
|
||||
bd update bb-xyz --notes "Made progress on the feature"
|
||||
# No specifics
|
||||
# No evidence
|
||||
# No verification status
|
||||
# Future agent can't assess state
|
||||
```
|
||||
|
||||
### ✅ Good: Specific Evidence
|
||||
|
||||
```bash
|
||||
bd update bb-xyz --notes "
|
||||
Progress: implemented core logic
|
||||
Files: src/lib/task-processor.ts (new), src/app/api/tasks/route.ts (modified)
|
||||
Tests: tests/lib/task-processor.test.ts (5 tests passing)
|
||||
Status: need to add error handling before close
|
||||
Blockers: none
|
||||
Next: npm run test to verify integration
|
||||
"
|
||||
# Specific
|
||||
# Reproducible
|
||||
# Future agent knows exact state
|
||||
```
|
||||
|
||||
## Close Without Verification
|
||||
|
||||
### ❌ Bad: Premature Close
|
||||
|
||||
```bash
|
||||
# Code written, not tested
|
||||
bd close bb-xyz --reason "Done"
|
||||
# Gates not run
|
||||
# Evidence not cited
|
||||
# Risk of regression
|
||||
```
|
||||
|
||||
### ✅ Good: Verified Close
|
||||
|
||||
```bash
|
||||
# Complete verification
|
||||
npm run typecheck && npm run lint && npm run test
|
||||
# All gates pass
|
||||
|
||||
bd update bb-xyz --notes "
|
||||
Final verification:
|
||||
- typecheck: PASS (0 errors)
|
||||
- lint: PASS (0 warnings)
|
||||
- test: PASS (52/52 tests)
|
||||
- Coverage: 87% on new code
|
||||
"
|
||||
|
||||
bd close bb-xyz --reason "Complete with full verification. 52 tests passing, 87% coverage."
|
||||
```
|
||||
90
.agents/skills/linus-beads-discipline/resources/IRON_LAWS.md
Normal file
90
.agents/skills/linus-beads-discipline/resources/IRON_LAWS.md
Normal file
|
|
@ -0,0 +1,90 @@
|
|||
# Iron Laws
|
||||
|
||||
**Non-negotiable. Violating letter = violating spirit. No "I followed spirit" escape hatch.**
|
||||
|
||||
## Law 1: BD is Source of Truth
|
||||
|
||||
```
|
||||
NEVER write to .beads/issues.jsonl directly
|
||||
NEVER skip bd commands for "speed"
|
||||
NEVER claim bead state without bd show output
|
||||
```
|
||||
|
||||
**Religious discipline:** Beads is not overhead. It IS the work tracking. Bypassing it bypasses truth.
|
||||
|
||||
### Violation Recovery
|
||||
1. Stop immediately
|
||||
2. Delete any direct changes to `.beads/issues.jsonl`
|
||||
3. Run `bd sync` to restore truth
|
||||
4. Re-apply changes via `bd update` commands
|
||||
5. Document in bead notes: "Corrected from direct-write violation"
|
||||
|
||||
## Law 2: Evidence Before Assertions
|
||||
|
||||
```
|
||||
NEVER claim: "done", "passing", "fixed", "closed"
|
||||
WITHOUT fresh command output proving it
|
||||
```
|
||||
|
||||
**The ritual:** Before closing ANY bead:
|
||||
```bash
|
||||
npm run typecheck
|
||||
npm run lint
|
||||
npm run test
|
||||
```
|
||||
|
||||
If UI changed: capture screenshots, record artifact paths.
|
||||
|
||||
### Required Evidence Types
|
||||
|
||||
| Change Type | Required Evidence |
|
||||
|-------------|-------------------|
|
||||
| Code change | typecheck + lint + test output |
|
||||
| UI change | Screenshots at all breakpoints |
|
||||
| API change | Route test output |
|
||||
| Bug fix | Test demonstrating fix |
|
||||
| Refactor | All tests still pass |
|
||||
|
||||
### Evidence Format in Notes
|
||||
```
|
||||
bd update bb-xyz --notes "npm run typecheck: PASS. npm run lint: PASS. npm run test: 47/47 passing. Screenshot: artifacts/fix-mobile-390.png"
|
||||
```
|
||||
|
||||
## Law 3: First Principles Every Decision
|
||||
|
||||
Ask "why?" until you hit:
|
||||
- **Physics**: Performance measurements, not assumptions
|
||||
- **Economics**: Actual resource constraints, not hypotheticals
|
||||
- **Requirements**: Stated acceptance criteria from bd show
|
||||
- **Data Model**: bd schema semantics
|
||||
|
||||
Stop at "best practice" or "everyone does it"? **You haven't reached first principles.**
|
||||
|
||||
### First-Principles Questions
|
||||
|
||||
| Decision | First-Principles Questions |
|
||||
|----------|---------------------------|
|
||||
| Add feature | What user problem does this solve? What evidence exists for need? |
|
||||
| Add abstraction | What concrete current use case requires this? What cost does it add? |
|
||||
| Choose tech | Does this solve our actual problem better than simpler alternatives? |
|
||||
| Optimize | Where is the bottleneck measured? What's the target? |
|
||||
|
||||
## No Exceptions Clause
|
||||
|
||||
```
|
||||
"Not a simple case" → Run gates anyway
|
||||
"Just this once" → No, not once
|
||||
"I already tested" → Run gates anyway
|
||||
"Time pressure" → Run gates anyway
|
||||
"Everyone does it" → First-principles analysis required
|
||||
```
|
||||
|
||||
**All rationalizations are addressed in [RATIONALIZATION_TABLE.md](RATIONALIZATION_TABLE.md).**
|
||||
|
||||
## Violation Consequence Protocol
|
||||
|
||||
1. **First violation**: Stop, correct, document in notes
|
||||
2. **Second violation in same session**: Delete all changes, start bead from scratch
|
||||
3. **Pattern of violations**: Bead should be closed and re-created with explicit "do not violate" in acceptance criteria
|
||||
|
||||
**Delete means delete. Don't keep as "reference". Don't "adapt" it. Delete.**
|
||||
|
|
@ -0,0 +1,184 @@
|
|||
# Linus Philosophy
|
||||
|
||||
**First-principles thinking from 30+ years building Linux and Git.**
|
||||
|
||||
## Core Principles
|
||||
|
||||
### "Talk is cheap. Show me the code."
|
||||
|
||||
- Working implementation beats theoretical architecture
|
||||
- Benchmarks beat beliefs
|
||||
- Proof-of-concept before multi-year planning
|
||||
- Code review examines code, not documents about code
|
||||
|
||||
### "Bad programmers worry about code. Good programmers worry about data structures."
|
||||
|
||||
- Data structure design is foundational
|
||||
- Code is derivative of data organization
|
||||
- Wrong data structure = impossible to write good code
|
||||
- Operations should be obvious from data layout
|
||||
|
||||
### "If you need more than 3 levels of indentation, you're screwed."
|
||||
|
||||
- Complexity is enemy of correctness
|
||||
- Deep nesting indicates design failure
|
||||
- Refactor design, don't add explanatory comments
|
||||
- Simple code is correct code
|
||||
|
||||
### "Abstraction is not free."
|
||||
|
||||
- Every layer has maintenance cost
|
||||
- Indirection makes debugging harder
|
||||
- "Might need flexibility" is not justification
|
||||
- YAGNI until proven otherwise
|
||||
|
||||
### "Perfection is achieved when there is nothing left to take away."
|
||||
|
||||
- Simplicity through elimination, not addition
|
||||
- Best code is code you don't write
|
||||
- Complexity compounds; simplicity scales
|
||||
|
||||
## Historical Evidence
|
||||
|
||||
### Linux Kernel
|
||||
- 30+ million lines
|
||||
- 30+ years maintained
|
||||
- 1000s of contributors
|
||||
- Runs majority of world's servers
|
||||
- All Android devices
|
||||
|
||||
### Git
|
||||
- Designed and implemented in weeks
|
||||
- Replaced CVS, Subversion industry-wide
|
||||
- Data-first design (content-addressable storage)
|
||||
- First-principles solution to real problem
|
||||
|
||||
## The Linus Method
|
||||
|
||||
### 1. Strip Assumptions
|
||||
|
||||
Start with: "What are we actually trying to solve?"
|
||||
|
||||
Not: "What technology should we use?"
|
||||
Not: "What pattern should we apply?"
|
||||
Not: "How do others solve this?"
|
||||
|
||||
### 2. Design Data First
|
||||
|
||||
```typescript
|
||||
// WRONG: Start with operations
|
||||
function getUser(id: string) { ... }
|
||||
function updateUser(user: User) { ... }
|
||||
function deleteUser(id: string) { ... }
|
||||
|
||||
// RIGHT: Start with data structure
|
||||
type User = {
|
||||
id: string;
|
||||
name: string;
|
||||
email: string;
|
||||
createdAt: Date;
|
||||
}
|
||||
// Operations derive from structure
|
||||
```
|
||||
|
||||
### 3. Measure, Don't Assume
|
||||
|
||||
```
|
||||
"This is fast enough" → Profile it
|
||||
"O(n log n) is fine" → Measure on real data
|
||||
"Memory usage is reasonable" → Measure it
|
||||
"The bottleneck is X" → Profile to confirm
|
||||
```
|
||||
|
||||
### 4. Eliminate, Don't Manage
|
||||
|
||||
```
|
||||
Complex problem → Don't add layers
|
||||
Complex problem → Simplify until it's not complex
|
||||
Complex problem → Wrong abstraction of problem
|
||||
```
|
||||
|
||||
## Quality Standards
|
||||
|
||||
### For Code
|
||||
- Obvious at a glance
|
||||
- Self-documenting (no comments explaining "what")
|
||||
- <3 nesting levels
|
||||
- Single responsibility per function
|
||||
- No unused parameters
|
||||
|
||||
### For Design
|
||||
- Every abstraction earns its cost
|
||||
- Data structure drives operations
|
||||
- Edge cases handled at boundaries
|
||||
- No hidden state or magic
|
||||
|
||||
### For Review
|
||||
- "Why is this needed?" - must have answer
|
||||
- "Could this be simpler?" - usually yes
|
||||
- "What does this cost?" - always something
|
||||
- "Prove it works" - need measurement
|
||||
|
||||
## What Linus Rejects
|
||||
|
||||
| Pattern | Why Rejected |
|
||||
|---------|--------------|
|
||||
| "Future-proofing" | YAGNI - build for today's proven need |
|
||||
| "Elegant" | Elegant ≠ correct; simple is better than clever |
|
||||
| "Industry standard" | Standards can be wrong; first-principles first |
|
||||
| "Best practice" | Practice without understanding = cargo cult |
|
||||
| "Enterprise pattern" | Patterns for problems you don't have |
|
||||
|
||||
## The Long-Term View
|
||||
|
||||
### 10-Year Horizon
|
||||
- Will someone understand this in 10 years?
|
||||
- Will this still solve the problem in 10 years?
|
||||
- Will maintenance cost be acceptable?
|
||||
|
||||
### 1000-Contributor Scale
|
||||
- Can 1000 people work on this without chaos?
|
||||
- Are the boundaries clear?
|
||||
- Is the design resilient to misunderstanding?
|
||||
|
||||
### Million-Line Codebase
|
||||
- Does this pattern scale to 1M lines?
|
||||
- Will complexity compound or stay bounded?
|
||||
- Can new contributors contribute safely?
|
||||
|
||||
## Practical Application
|
||||
|
||||
### Before Any Decision
|
||||
|
||||
1. What problem are we solving? (specifically, not vaguely)
|
||||
2. What's the simplest solution? (not "best", simplest)
|
||||
3. What does the data model say? (not what code pattern)
|
||||
4. What's the measurement? (not assumption)
|
||||
|
||||
### After Any Code
|
||||
|
||||
1. Could this be simpler? (usually yes)
|
||||
2. Would I accept this from a stranger? (be honest)
|
||||
3. Will this make sense in 5 years? (no comments allowed)
|
||||
4. Does the data structure drive the code? (should be obvious)
|
||||
|
||||
## Quotes as Principles
|
||||
|
||||
| Quote | Application |
|
||||
|-------|-------------|
|
||||
| "Talk is cheap. Show me the code." | Code beats docs. Benchmarks beat claims. |
|
||||
| "Bad programmers worry about code..." | Data structures first, operations second. |
|
||||
| "3 levels of indentation..." | Complexity limit. Refactor design, not comments. |
|
||||
| "Abstraction is not free." | Every layer costs. Earn it with current need. |
|
||||
| "Nothing left to take away" | Eliminate complexity, don't manage it. |
|
||||
|
||||
## Integration with Beads
|
||||
|
||||
These principles are not separate from beads discipline:
|
||||
- **Data first** → Read bead criteria before implementing
|
||||
- **Evidence** → Run gates, cite output
|
||||
- **Simplicity** → One bead, one scope
|
||||
- **Root cause** → Trace to data model, not UI patch
|
||||
- **Long-term** → Evidence before every close
|
||||
|
||||
**Linus built Linux. You're building with beads. Same discipline applies.**
|
||||
|
|
@ -0,0 +1,66 @@
|
|||
# Rationalization Table
|
||||
|
||||
**Every excuse agents make when violating discipline. Every counter.**
|
||||
|
||||
## Complete Table
|
||||
|
||||
| Excuse | Reality | Counter |
|
||||
|--------|---------|---------|
|
||||
| "Just this once" | "Once" becomes "usually". Every violation compounds. | Run gates. No exceptions. |
|
||||
| "We might need it later" | YAGNI. Unused abstraction = maintenance debt forever. | Delete abstraction. Add when concrete need proven. |
|
||||
| "I already tested manually" | Manual ≠ reproducible. Gates exist for reason. | Run gates. Cite output. |
|
||||
| "It's just display/visualization" | Display ≠ data model = two truths. Users see wrong state. | Verify display matches bd schema. |
|
||||
| "Different pages, separate fixes" | Duplicated logic = two places to fail, two to maintain. | Extract shared logic. Fix once. |
|
||||
| "bd is slower than direct edit" | Speed without truth = wasted time. Bugs from truth drift. | Use bd. Correctness > convenience. |
|
||||
| "Typecheck never catches anything" | You don't know what it would have caught. | Run typecheck. Cite output. |
|
||||
| "Lint is just style" | Style inconsistencies = maintenance burden. | Run lint. Fix violations. |
|
||||
| "Tests are flaky" | Flaky tests = fix them, don't skip them. | Fix or quarantine. Don't skip gate. |
|
||||
| "I'll create a bead for cleanup later" | "Later" never comes. Technical debt compounds. | Create bead NOW or cleanup NOW. |
|
||||
| "This is a trivial change" | "Trivial" bugs exist. "Trivial" changes break things. | Run gates. No change is trivial. |
|
||||
| "My changes don't affect types" | You don't know that. Type system knows. | Run typecheck. |
|
||||
| "The abstraction is well-designed" | Unused abstraction = debt regardless of design quality. | Delete if no current concrete use. |
|
||||
| "It follows best practices" | Whose practices? Why? First-principles analysis required. | Trace to physics/economics/requirements. |
|
||||
| "I'll sync it properly later" | Later = never. Truth drift = bugs. | Sync now or track as blocking bead. |
|
||||
| "It works on my machine" | Your machine ≠ production. Gates catch environment drift. | Run gates in CI. |
|
||||
| "We can refactor later" | Later = 10x cost. Technical debt compounds. | Refactor now or create bead. |
|
||||
| "This is how everyone does it" | Everyone might be wrong. First-principles required. | Analyze from fundamentals. |
|
||||
| "It's about spirit not ritual" | Violating letter = violating spirit. No escape hatch. | Follow ritual. Spirit is in ritual. |
|
||||
| "The deadline requires shortcuts" | Shortcuts create bugs. Bugs miss deadlines. | Run gates. Communicate realistic timeline. |
|
||||
|
||||
## Pressure Pattern Analysis
|
||||
|
||||
| Pressure | Common Rationalizations | Why It Fails |
|
||||
|----------|------------------------|--------------|
|
||||
| **Time** | "Just this once", "Deadline", "Gates take too long" | Bugs cost 10x gate time. |
|
||||
| **Sunk Cost** | "Already spent hours", "Well-designed abstraction", "Works already" | Sunk cost is fallacy. Bad code = more cost. |
|
||||
| **Exhaustion** | "Already tested manually", "Trivial change", "Run gates tomorrow" | Exhausted mistakes are worst mistakes. |
|
||||
| **Authority** | "Senior said so", "Team convention", "Industry standard" | Authority can be wrong. First-principles required. |
|
||||
| **Social** | "Everyone does it", "Team expects this", "Don't be difficult" | Social pressure enables mediocrity. |
|
||||
|
||||
## Self-Check Protocol
|
||||
|
||||
Before claiming any work is complete, check:
|
||||
|
||||
```
|
||||
□ Did I use bd for all state changes?
|
||||
□ Did I run typecheck? Cite output?
|
||||
□ Did I run lint? Cite output?
|
||||
□ Did I run tests? Cite output?
|
||||
□ Did I capture UI evidence if needed?
|
||||
□ Can I trace every design decision to first principles?
|
||||
□ Would I accept this code from a stranger?
|
||||
□ Will this make sense in 5 years?
|
||||
```
|
||||
|
||||
**Any unchecked box = not done. Keep working.**
|
||||
|
||||
## The Escape Hatches (None)
|
||||
|
||||
| Attempted Escape | Why It Fails |
|
||||
|------------------|--------------|
|
||||
| "I followed the spirit" | Spirit lives in ritual. Violate ritual = violate spirit. |
|
||||
| "This situation is unique" | Every situation claims uniqueness. Rules exist for uniqueness. |
|
||||
| "The skill doesn't cover this" | Iron Laws cover everything. Evidence + bd + first principles. |
|
||||
| "I used judgment" | Judgment without evidence = assumption. Run gates. |
|
||||
|
||||
**There are no escape hatches. The Iron Laws are absolute.**
|
||||
|
|
@ -0,0 +1,131 @@
|
|||
# Verification Gates
|
||||
|
||||
**Required checks before ANY bead close. No exceptions.**
|
||||
|
||||
## Gate Sequence
|
||||
|
||||
```
|
||||
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
||||
│ Typecheck │────▶│ Lint │────▶│ Test │
|
||||
└─────────────┘ └─────────────┘ └─────────────┘
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
0 errors 0 warnings All pass
|
||||
0 warnings Fix or or skip
|
||||
document with reason
|
||||
```
|
||||
|
||||
## Required Commands
|
||||
|
||||
### All Code Changes
|
||||
```bash
|
||||
npm run typecheck # Must PASS with 0 errors
|
||||
npm run lint # Must PASS with 0 warnings (or documented exceptions)
|
||||
npm run test # Must PASS all tests
|
||||
```
|
||||
|
||||
### UI Changes (add to above)
|
||||
```bash
|
||||
# Capture screenshots at all breakpoints
|
||||
npm run capture:mobile # artifacts/xxx-mobile.png
|
||||
npm run capture:tablet # artifacts/xxx-tablet.png
|
||||
npm run capture:desktop # artifacts/xxx-desktop.png
|
||||
```
|
||||
|
||||
### API Changes (add to above)
|
||||
```bash
|
||||
npm run test:api # Route integration tests
|
||||
# or
|
||||
node --test tests/api/
|
||||
```
|
||||
|
||||
## Gate Failure Protocol
|
||||
|
||||
### Typecheck Fails
|
||||
1. Fix type errors
|
||||
2. Re-run typecheck
|
||||
3. Only proceed when 0 errors
|
||||
4. Document: "typecheck: PASS (0 errors)"
|
||||
|
||||
### Lint Fails
|
||||
1. Fix warnings if trivial
|
||||
2. If intentional violation: add eslint-disable with comment explaining WHY
|
||||
3. Document in notes: "lint: PASS (0 warnings)" or "lint: PASS (1 intentional - see line 42)"
|
||||
4. Never merge with unexplained lint violations
|
||||
|
||||
### Tests Fail
|
||||
1. Analyze failure output
|
||||
2. Determine: bug in code or bug in test?
|
||||
3. Fix the bug (not the test to pass)
|
||||
4. Re-run tests
|
||||
5. Only proceed when ALL pass
|
||||
6. Document: "test: PASS (47/47)"
|
||||
|
||||
### Flaky Tests
|
||||
1. Identify flaky test
|
||||
2. Options:
|
||||
- Fix flakiness (preferred)
|
||||
- Quarantine with .skip and create bead to fix
|
||||
3. Never skip without tracking
|
||||
|
||||
## Evidence Format
|
||||
|
||||
### In Bead Notes
|
||||
```bash
|
||||
bd update bb-xyz --notes "Verification:
|
||||
- typecheck: PASS (0 errors, 0 warnings)
|
||||
- lint: PASS (0 warnings)
|
||||
- test: PASS (47/47 tests in 2.3s)
|
||||
- UI screenshots: artifacts/kanban-390.png, artifacts/kanban-768.png, artifacts/kanban-1440.png"
|
||||
```
|
||||
|
||||
### In Close Reason
|
||||
```bash
|
||||
bd close bb-xyz --reason "Implemented X with full gate coverage. All tests passing. Screenshots captured."
|
||||
```
|
||||
|
||||
## Gate Checklist
|
||||
|
||||
```
|
||||
□ npm run typecheck → PASS (cite output)
|
||||
□ npm run lint → PASS (cite output)
|
||||
□ npm run test → PASS (cite output)
|
||||
□ UI changed? → Screenshots captured (list paths)
|
||||
□ API changed? → Route tests pass
|
||||
□ New file? → Included in test suite
|
||||
□ Notes updated? → Evidence cited
|
||||
```
|
||||
|
||||
**Any unchecked? Don't close. Keep working.**
|
||||
|
||||
## Special Cases
|
||||
|
||||
### "No Tests Exist Yet"
|
||||
1. Create tests for new code
|
||||
2. Run existing test suite to ensure no regressions
|
||||
3. Document: "test: PASS (existing suite), NEW: added tests for X"
|
||||
|
||||
### "Tests Are Slow"
|
||||
1. Run them anyway
|
||||
2. Consider: parallelize, optimize, cache
|
||||
3. Never skip for speed
|
||||
|
||||
### "CI Will Catch It"
|
||||
1. Run locally first
|
||||
2. CI is backup, not replacement
|
||||
3. Local failures = faster feedback
|
||||
|
||||
### "Just Documentation Change"
|
||||
1. Still run typecheck (links, imports)
|
||||
2. Still run lint (formatting)
|
||||
3. Test may not be needed - document why skipped
|
||||
|
||||
## Post-Close Verification
|
||||
|
||||
After `bd close`:
|
||||
```bash
|
||||
bd show <id> # Verify status is closed
|
||||
bd ready # Confirm it's not still showing as ready
|
||||
```
|
||||
|
||||
If still shows as ready after close: `bd sync` then re-check.
|
||||
|
|
@ -0,0 +1,189 @@
|
|||
# Workflow Engine
|
||||
|
||||
**The decision brain. Shared across all modes.**
|
||||
|
||||
## Mode Detection
|
||||
|
||||
When user engages, detect the mode from intent:
|
||||
|
||||
| User Intent | Mode | First Action |
|
||||
|-------------|------|--------------|
|
||||
| "What's going on?" / "What should I do?" | TRIAGE | `bd ready` |
|
||||
| "Something is broken" / "Fix this bug" | DEBUG | `bd show` on related bead |
|
||||
| "I need to understand..." / "How does X work?" | RESEARCH | Read code, update bead |
|
||||
| "I want to design..." / "Architecture for..." | DESIGN | First-principles analysis |
|
||||
| "Implement X" / "Write code for..." | IMPLEMENT | Claim bead, TDD |
|
||||
| "Review this code" / "Check my work" | REVIEW | Read code against spec |
|
||||
| "Simplify this" / "Clean up..." | REFACTOR | Identify debt, plan |
|
||||
| "Plan the project" / "Roadmap" | PLAN | Decompose, create beads |
|
||||
|
||||
**If unclear, ASK the user which mode.**
|
||||
|
||||
## The Universal Loop
|
||||
|
||||
Every mode follows this pattern:
|
||||
|
||||
```
|
||||
1. READ BEADS (what's the current truth?)
|
||||
└─ bd ready / bd show / bd query
|
||||
|
||||
2. CHECK SKILLS (any relevant helpers?)
|
||||
└─ Look for skills that match the task type
|
||||
└─ Use if found, proceed without if not
|
||||
|
||||
3. DO WORK (mode-specific)
|
||||
└─ See workflow/<mode>.md for specifics
|
||||
|
||||
4. WRITE BEADS (update the shared memory)
|
||||
└─ bd update --notes / bd close / bd create
|
||||
|
||||
5. VERIFY (prove claims)
|
||||
└─ Run gates appropriate to the mode
|
||||
```
|
||||
|
||||
## Beads-as-Memory Principles
|
||||
|
||||
### Every Session Starts With Reading
|
||||
|
||||
```
|
||||
NEVER start work without:
|
||||
1. bd ready # What's unblocked?
|
||||
2. bd show <id> # What are the details?
|
||||
3. Read related closed beads for context
|
||||
```
|
||||
|
||||
### Every Session Ends With Writing
|
||||
|
||||
```
|
||||
NEVER end session without:
|
||||
1. bd update --notes "Progress: ... Evidence: ..."
|
||||
2. bd sync # Share with other agents
|
||||
```
|
||||
|
||||
### Every Decision Is Recorded
|
||||
|
||||
```
|
||||
When you decide something:
|
||||
- Create a bead for it (if significant)
|
||||
- Update existing bead notes (if related)
|
||||
- Cross-reference in comments
|
||||
```
|
||||
|
||||
### Other Agents Depend On Your Notes
|
||||
|
||||
```
|
||||
Your notes should answer:
|
||||
- What did you learn?
|
||||
- What did you decide?
|
||||
- What did you leave incomplete?
|
||||
- What blocked you?
|
||||
- What would help the next agent?
|
||||
```
|
||||
|
||||
## The bb/bd Split
|
||||
|
||||
### If bb is available:
|
||||
```
|
||||
- Use bb agent for scope reservations
|
||||
- Use bb agent for messaging other agents
|
||||
- Passive activity: any bb command extends lease
|
||||
```
|
||||
|
||||
### If bb is NOT available:
|
||||
```
|
||||
- Use bd slot for exclusive claims
|
||||
- Use bd agent heartbeat for presence
|
||||
- Skip messaging (no equivalent)
|
||||
- Skip path reservations (no equivalent)
|
||||
```
|
||||
|
||||
### Always available:
|
||||
```
|
||||
- bd commands (core truth)
|
||||
- Verification gates
|
||||
- First-principles thinking
|
||||
```
|
||||
|
||||
## Cross-Agent Coordination
|
||||
|
||||
Since all agents share the same Linus personality and beads memory:
|
||||
|
||||
### Before Claiming Work:
|
||||
```
|
||||
bd ready # See what's available
|
||||
bd show <id> # Check if already in_progress
|
||||
bd query "status=in_progress" # Who else is working?
|
||||
```
|
||||
|
||||
### When Claiming:
|
||||
```
|
||||
bd update <id> --status in_progress --notes "@<agent-id> claiming"
|
||||
# Optionally: bd slot set <agent> hook <id>
|
||||
# Optionally: bb agent reserve (if available)
|
||||
```
|
||||
|
||||
### When Handing Off:
|
||||
```
|
||||
bd update <id> --notes "Handoff to next agent: ..."
|
||||
bd update <id> --status open # Or appropriate status
|
||||
# Optionally: bb agent send (if available)
|
||||
```
|
||||
|
||||
### When Picking Up Another's Work:
|
||||
```
|
||||
bd show <id> # Read their notes carefully
|
||||
bd query "id=<id>" --comments # Read any comments
|
||||
Acknowledge previous work in your first update
|
||||
```
|
||||
|
||||
## Skill Integration Pattern
|
||||
|
||||
At the start of any workflow:
|
||||
|
||||
```
|
||||
1. Identify the task type
|
||||
2. Check available skills for relevant helpers
|
||||
3. If found and useful: invoke the skill
|
||||
4. If not found: proceed with Linus discipline alone
|
||||
5. Never hardcode specific skill dependencies
|
||||
```
|
||||
|
||||
This keeps workflows flexible and skill-agnostic.
|
||||
|
||||
## Evidence Thresholds By Mode
|
||||
|
||||
| Mode | Minimum Evidence |
|
||||
|------|------------------|
|
||||
| TRIAGE | Bead status updated |
|
||||
| RESEARCH | Notes with findings |
|
||||
| DEBUG | Root cause identified + fix + test |
|
||||
| DESIGN | Decision documented + rationale |
|
||||
| IMPLEMENT | typecheck ✓ lint ✓ test ✓ |
|
||||
| REVIEW | Findings documented |
|
||||
| REFACTOR | typecheck ✓ lint ✓ test ✓ |
|
||||
| PLAN | Beads created with dependencies |
|
||||
|
||||
## The Iron Laws Apply Everywhere
|
||||
|
||||
No mode exempts you from:
|
||||
|
||||
1. **BD is source of truth** - Never direct JSONL writes
|
||||
2. **Evidence before assertions** - Never claim without proof
|
||||
3. **First principles** - Never stop at "best practice"
|
||||
|
||||
## Mode Transitions
|
||||
|
||||
Sometimes you need to switch modes mid-work:
|
||||
|
||||
```
|
||||
TRIAGE → IMPLEMENT : "I know what to do, now doing it"
|
||||
DEBUG → RESEARCH : "Need to understand before fixing"
|
||||
RESEARCH → DESIGN : "Now I understand, time to architect"
|
||||
DESIGN → IMPLEMENT : "Architecture done, now build"
|
||||
ANY → TRIAGE : "Lost, need to reassess"
|
||||
```
|
||||
|
||||
On transition:
|
||||
1. Update current bead notes with mode change
|
||||
2. Read relevant workflow for new mode
|
||||
3. Continue with fresh eyes
|
||||
Loading…
Add table
Add a link
Reference in a new issue