docs+skills: add main UI/UX visual-truth PRD and skill links

.agents/skills/linus-beads-discipline/workflows/debug.md

@@ -0,0 +1,105 @@
+# Debug Workflow
+
+**"Something is broken."**
+
+## Trigger
+- "Fix this bug" / "Something's broken"
+- "This doesn't work" / "Error in..."
+- Test failure / Unexpected behavior
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for debugging?
+- Error pattern recognition skills
+- System-specific diagnostic skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Context
+```bash
+# Find related bead (if exists)
+bd query "title~=<error-keyword> OR labels~=<component>"
+
+# Check recent changes
+bd query "updated<1d AND status=closed"
+
+# Read related bead details
+bd show <related-id>
+```
+
+### 3. Reproduce & Isolate
+```
+First question: Can I reproduce this?
+
+If YES:
+- Isolate the minimal reproduction
+- Identify the exact failure point
+- Gather evidence (logs, stack traces)
+
+If NO:
+- Add logging/observability
+- Create hypothesis
+- Design experiment to confirm
+```
+
+### 4. Root Cause Analysis
+Ask "Why?" at least 3 times:
+```
+Symptom: Test fails
+Why 1: Function returns wrong value
+Why 2: Input is malformed
+Why 3: Upstream normalization missing
+ROOT CAUSE: Missing normalization in caller
+```
+
+**Fix the DESIGN, not just the symptom.**
+
+### 5. Fix Implementation
+```
+1. Write failing test that exposes the bug
+2. Implement minimal fix
+3. Verify test passes
+4. Check for similar bugs elsewhere (same pattern)
+```
+
+### 6. Update Memory
+```bash
+# Find or create bug bead
+bd create "Fix: <description>" --type bug --priority P1
+
+# Document root cause
+bd update <id> --notes "Root cause: ...
+Why this was possible: ...
+Fix: ...
+Evidence: test added, gates pass"
+
+# Close with evidence
+bd close <id> --reason "Fixed. Root cause: X. Prevention: Y."
+```
+
+### 7. Verify
+```bash
+npm run typecheck && npm run lint && npm run test
+```
+
+## The Debug Questions
+
+1. What is the symptom?
+2. Can I reproduce it?
+3. Where does it fail?
+4. Why does it fail there?
+5. Why was this possible? (design flaw)
+6. Does the same flaw exist elsewhere?
+
+## Prevention Mindset
+
+Linus doesn't just fix bugs. Linus eliminates bug CLASSES.
+
+After every fix, ask:
+- What design flaw allowed this?
+- How do I prevent the entire class?
+- Is there a pattern to search for?
+
+Update bead with prevention notes for future reference.

.agents/skills/linus-beads-discipline/workflows/design.md

@@ -0,0 +1,128 @@
+# Design Workflow
+
+**"I need to architect something."**
+
+## Trigger
+- "Design a system for..."
+- "Architecture for..."
+- "How should we structure..."
+- "We need to build X, how?"
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for design?
+- Architecture pattern skills
+- Domain modeling skills  
+- First-principles thinking skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Context
+```bash
+# Check for existing design decisions
+bd query "labels~=design OR labels~=architecture"
+
+# Check for related work
+bd query "title~=<component>"
+
+# Read constraints from parent/related beads
+bd show <related-id>
+```
+
+### 3. First-Principles Analysis
+```
+Start with requirements, not solutions.
+
+Questions:
+1. What problem are we solving? (not what are we building)
+2. What are the hard constraints? (physics, economics, requirements)
+3. What are the soft constraints? (preferences, conventions)
+4. What would the simplest solution look like?
+5. Why isn't that enough?
+```
+
+### 4. Explore Trade-offs
+```
+For each design option:
+- What does it make easy?
+- What does it make hard?
+- What can't it do?
+- What complexity does it add?
+```
+
+### 5. Make Decisions
+```
+Document:
+- What you decided
+- Why you decided it
+- What you rejected and why
+- What's still open
+```
+
+### 6. Update Memory
+```bash
+# Create design bead
+bd create "Design: <topic>" --type task --priority P1
+
+bd update <id> --notes "## Problem
+<what problem we're solving>
+
+## Constraints
+- Hard: <immutable constraints>
+- Soft: <flexible constraints>
+
+## Decision
+<what we decided>
+
+## Rationale
+<why this decision>
+
+## Alternatives Considered
+- X: rejected because Y
+- Z: rejected because W
+
+## Open Questions
+<things still undecided>
+
+## Implementation Notes
+<hints for implementer>"
+
+# If design is complete and approved
+bd close <id> --reason "Design complete. Decision: X. Rationale: Y."
+```
+
+## Design Documentation
+
+Every design should answer:
+
+1. **Problem** - What are we solving?
+2. **Constraints** - What can't we change?
+3. **Decision** - What are we doing?
+4. **Rationale** - Why this way?
+5. **Alternatives** - What else did we consider?
+6. **Trade-offs** - What do we gain/lose?
+7. **Risks** - What could go wrong?
+
+## Simplicity Test
+
+Before finalizing:
+```
+Can I explain this to a new team member in 5 minutes?
+If not, it's too complex.
+
+Can I remove anything without breaking it?
+If yes, remove it.
+
+Does this solve the ACTUAL problem or an imagined one?
+Go back to requirements if unsure.
+```
+
+## For Implementers
+
+Your design notes should let an implementer:
+- Understand what to build
+- Know the constraints
+- Make localized decisions without revisiting architecture
+- Test that they built the right thing

.agents/skills/linus-beads-discipline/workflows/implement.md

@@ -0,0 +1,146 @@
+# Implement Workflow
+
+**"I need to write code."**
+
+## Trigger
+- "Implement X"
+- "Write code for..."
+- "Build this feature"
+- "Add support for..."
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for implementation?
+- Language/framework skills
+- Testing skills
+- Code generation skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Context
+```bash
+# Find or claim the bead
+bd ready
+bd show <id>
+
+# Read design decisions
+bd query "labels~=design AND title~=<feature>"
+
+# Read related closed beads for patterns
+bd query "status=closed AND labels~=<area>"
+```
+
+### 3. Claim the Work
+```bash
+bd update <id> --status in_progress --notes "Plan:
+1. <step 1>
+2. <step 2>
+...
+Acceptance: <from bead>"
+```
+
+### 4. Test-First Implementation
+```
+For each piece of behavior:
+1. Write failing test
+2. Run test, capture failure
+3. Implement minimal code to pass
+4. Run test, verify pass
+5. Refactor if needed
+```
+
+### 5. Update Progress
+```bash
+# After each meaningful progress
+bd update <id> --notes "Progress:
+- <X> complete, evidence: <test name>
+- <Y> in progress
+- <Z> blocked by: <blocker>"
+```
+
+### 6. Verify Gates
+```bash
+npm run typecheck && npm run lint && npm run test
+```
+
+All must pass before closing.
+
+### 7. Close with Evidence
+```bash
+bd update <id> --notes "Evidence:
+- typecheck: PASS
+- lint: PASS  
+- test: PASS (N/N)
+- Files changed: <list>
+- Coverage: <if relevant>"
+
+bd close <id> --reason "Implemented with verification"
+bd sync
+```
+
+## Implementation Principles
+
+### Small Steps
+```
+One behavior at a time.
+One file at a time when possible.
+Commit after each working state.
+```
+
+### No Speculation
+```
+Don't build for imagined future.
+Build for current concrete need.
+If future need arises, extend then.
+```
+
+### Evidence Every Claim
+```
+"I added X" → Which test proves it?
+"I fixed Y" → Which test was failing?
+"It works" → Show the output.
+```
+
+## Blocked?
+
+```bash
+bd update <id> --notes "BLOCKED: <what>
+Reason: <why>
+Needs: <what would unblock>
+Next agent: <handoff notes>"
+
+# If creating a blocker bead
+bd create "<blocker description>" --type task
+bd dep add <current-id> <blocker-id>
+```
+
+## Multi-Agent Implementation
+
+If another agent might continue:
+
+```bash
+bd update <id> --notes "Handoff:
+## Completed
+- X, Y, Z done
+
+## In Progress  
+- A partially done (see file:line)
+
+## Remaining
+- B, C still needed
+
+## Gotchas
+- <non-obvious things learned>
+- <patterns to follow>"
+```
+
+## The Gates Are Non-Negotiable
+
+Never close without:
+- `npm run typecheck` → PASS
+- `npm run lint` → PASS  
+- `npm run test` → PASS
+
+No exceptions. No "just this once". No "it's obvious".

.agents/skills/linus-beads-discipline/workflows/plan.md

@@ -0,0 +1,126 @@
+# Plan Workflow
+
+**"Let's figure out what needs to be done."**
+
+## Trigger
+- "Plan the project" / "Create a roadmap"
+- "Break this down" / "What are the steps?"
+- "How should we approach..."
+- Starting a new epic/initiative
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for planning?
+- Domain decomposition skills
+- Dependency analysis skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Context
+```bash
+# Check for existing related work
+bd query "labels~=<area>"
+
+# Check for constraints/decisions
+bd query "labels~=design OR labels~=decision"
+```
+
+### 3. First-Principles Decomposition
+```
+Start with the goal, work backward:
+
+1. What's the end state?
+2. What needs to be true for that?
+3. What's the minimal path there?
+4. What are the dependencies?
+5. What can be parallelized?
+```
+
+### 4. Create Bead Structure
+```bash
+# Create epic
+bd create "<Epic Name>" --type epic --priority P1
+
+# Create children with dependencies
+bd create "<Task 1>" --type task --priority P1
+bd create "<Task 2>" --type task --priority P1
+bd dep add <task2-id> <task1-id>  # Task 2 depends on Task 1
+
+# Document the plan
+bd update <epic-id> --notes "## Goal
+<what we're achieving>
+
+## Approach
+<high-level strategy>
+
+## Phases
+1. <phase 1>: <tasks>
+2. <phase 2>: <tasks>
+
+## Parallelization
+<what can run in parallel>
+
+## Risks
+<what could go wrong>
+
+## Success Criteria
+<how we know we're done>"
+```
+
+### 5. Validate Structure
+```bash
+# Check for cycles
+bd dep cycles
+
+# Check dependencies are correct
+bd dep tree <epic-id>
+
+# Validate parallel paths
+bd ready  # Should show unblocked beads
+```
+
+## Planning Principles
+
+### Dependency Direction
+```
+Dependencies = execution order
+NOT visual order or "nice to have"
+
+A → B means: A must complete before B can start
+```
+
+### Minimal Dependencies
+```
+Add dependency only if:
+- Blocked task CANNOT proceed without blocker
+- Real hard dependency, not soft preference
+
+Over-chaining kills parallelization.
+```
+
+### Priorities
+```
+P0: Critical, blocking everything
+P1: Important, on the critical path
+P2: Valuable, can wait briefly
+P3: Nice to have, defer
+```
+
+## Good Plans
+
+- **Clear goal** - Anyone can see what success looks like
+- **Decomposed tasks** - Each task is doable in one session
+- **Correct dependencies** - Execution order is explicit
+- **Parallelization** - Independent work is visible
+- **Risks identified** - Known unknowns are documented
+- **Acceptance criteria** - Each task has clear completion
+
+## For Other Agents
+
+Your plan should let any agent:
+- Understand the overall goal
+- Pick up any ready task and go
+- Know what depends on their work
+- See where they fit in the bigger picture

.agents/skills/linus-beads-discipline/workflows/refactor.md

@@ -0,0 +1,123 @@
+# Refactor Workflow
+
+**"Simplify this mess."**
+
+## Trigger
+- "Clean up X" / "Simplify..."
+- "Refactor this" / "This is messy"
+- Technical debt identified
+- Code smell detected
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for refactoring?
+- Language-specific refactoring patterns
+- Debt identification skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Context
+```bash
+# Check for related debt beads
+bd query "labels~=debt OR labels~=refactor"
+
+# Check for recent changes that might inform
+bd query "updated<7d AND notes~=<component>"
+```
+
+### 3. Identify Debt
+```
+What's the problem?
+
+- Duplication? → Extract shared logic
+- Wrong abstraction? → Replace with simpler
+- Missing abstraction? → Add minimal one
+- Dead code? → Delete
+- Unclear names? → Rename
+- Hidden dependencies? → Make explicit
+```
+
+### 4. Plan the Change
+```bash
+bd create "Refactor: <what>" --type task --priority P2
+
+bd update <id> --notes "Debt identified:
+<what's wrong>
+
+Plan:
+1. <step 1>
+2. <step 2>
+...
+
+Scope: <what files/modules>
+Risk: <what could break>
+Tests to run: <which verify behavior preserved>"
+```
+
+### 5. Refactor Safely
+```
+CRITICAL: Behavior must NOT change.
+
+1. Ensure tests exist for current behavior
+   - If not, write characterization tests first
+2. Make one small change at a time
+3. Run tests after each change
+4. Never change behavior AND structure simultaneously
+```
+
+### 6. Verify
+```bash
+npm run typecheck && npm run lint && npm run test
+```
+
+All must pass. Behavior preserved.
+
+### 7. Document Result
+```bash
+bd update <id> --notes "Refactored:
+- Before: <complexity measure>
+- After: <complexity measure>
+- Files changed: <list>
+- Tests: PASS (behavior preserved)"
+
+bd close <id> --reason "Refactored. Complexity reduced."
+```
+
+## Refactoring Rules
+
+1. **Never refactor without tests**
+   - If no tests, write characterization tests first
+   - Tests prove behavior is preserved
+
+2. **One change at a time**
+   - Rename → test → commit
+   - Extract → test → commit
+   - Never combine refactors
+
+3. **No behavior changes**
+   - Refactor = structure change only
+   - Behavior changes = separate task
+
+4. **Delete > Simplify > Abstract**
+   - Can I delete it? Do it.
+   - Can I simplify it? Do it.
+   - Must I abstract? Do it minimally.
+
+## Simplicity Questions
+
+After refactoring:
+- Is there less code? (good)
+- Is there more code? (justify it)
+- Are there fewer files? (good)
+- Are there fewer abstractions? (good)
+- Is it easier to understand? (must be yes)
+
+## For Future Agents
+
+Your refactor notes should explain:
+- Why the old way was bad
+- Why the new way is better
+- What you considered but rejected
+- Any remaining debt

.agents/skills/linus-beads-discipline/workflows/research.md

@@ -0,0 +1,91 @@
+# Research Workflow
+
+**"I need to understand something."**
+
+## Trigger
+- "How does X work?"
+- "Explain the architecture of..."
+- "I need to understand..."
+- "What's the current state of..."
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for this research?
+- Code exploration skills
+- Documentation skills
+- Domain-specific knowledge skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Existing Knowledge
+```bash
+# Check if already documented in beads
+bd query "title~=<topic> OR notes~=<topic>"
+
+# Check for closed beads with findings
+bd query "status=closed AND notes~=<topic>"
+
+# Read relevant bead notes
+bd show <related-id>
+```
+
+### 3. Explore Codebase
+```
+- Find entry points
+- Trace data flows
+- Identify key abstractions
+- Note patterns and conventions
+```
+
+### 4. Document Findings
+Two paths:
+
+**If significant:**
+```bash
+bd create "Research: <topic>" --type task --priority P2
+bd update <id> --notes "Findings:
+## Summary
+## Key Components
+## Data Flow
+## Patterns Observed
+## Open Questions"
+```
+
+**If related to existing bead:**
+```bash
+bd update <existing-id> --notes "Research findings:
+<findings>"
+```
+
+### 5. Identify Gaps
+```
+What's still unclear?
+What needs investigation?
+What decisions need to be made?
+```
+
+## Research Outputs
+
+Document:
+- **What you learned** (facts)
+- **How things connect** (relationships)
+- **What's unclear** (gaps)
+- **What should change** (opportunities)
+- **Where to look next** (pointers)
+
+## For Future Agents
+
+Your research notes should let another agent:
+- Understand the topic without re-researching
+- Know what's known vs unknown
+- Continue from where you stopped
+- Make informed decisions
+
+## Evidence
+
+Research doesn't need test gates, but does need:
+- Clear documentation
+- Cited sources (file paths, line numbers)
+- Dated findings (when was this true?)

.agents/skills/linus-beads-discipline/workflows/review.md

@@ -0,0 +1,118 @@
+# Review Workflow
+
+**"Review this code."**
+
+## Trigger
+- "Review this code" / "Check my work"
+- "Is this correct?" / "What do you think?"
+- Pull request review
+- Pre-commit review
+
+## The Flow
+
+### 1. Check Skills
+```
+Any relevant skills for review?
+- Language-specific review skills
+- Security review skills
+- Performance review skills
+- Use if helpful, skip if not
+```
+
+### 2. Read Context
+```bash
+# Find the related bead
+bd show <id>
+
+# Read acceptance criteria
+# Read design decisions
+# Read constraints
+```
+
+### 3. Review Against Spec
+```
+Does the code:
+- Meet the acceptance criteria?
+- Follow the design decisions?
+- Respect the constraints?
+- Solve the stated problem?
+```
+
+### 4. Review Against Standards
+```
+Linus-grade review checks:
+
+Correctness:
+- Does it do what it claims?
+- Are edge cases handled?
+- Are error paths covered?
+
+Simplicity:
+- Is there unnecessary complexity?
+- Can anything be removed?
+- Is the abstraction justified?
+
+Safety:
+- Can this break existing code?
+- Are there security implications?
+- Can this cause data loss?
+
+Performance:
+- Is there unnecessary work?
+- Are there N+1 queries?
+- Is memory managed correctly?
+```
+
+### 5. Document Findings
+```bash
+# If findings exist
+bd update <id> --notes "Review findings:
+## Must Fix (blocking)
+- <critical issue>
+
+## Should Fix (non-blocking)
+- <improvement>
+
+## Nitpicks (optional)
+- <minor style/readability>
+
+## Good
+- <what's done well>"
+
+# If approved
+bd update <id> --notes "Review: APPROVED
+- All acceptance criteria met
+- No blocking issues
+- Ready for merge"
+```
+
+## Review Questions
+
+For every piece of code:
+1. What does it do? (if unclear, flag it)
+2. Why does it do it this way? (if unclear, flag it)
+3. What could go wrong? (if something, flag it)
+4. Is this the simplest solution? (if not, flag it)
+
+## Feedback Style
+
+```
+BAD: "This is wrong"
+GOOD: "This doesn't handle X case, which happens when Y"
+
+BAD: "Bad pattern"  
+GOOD: "This pattern makes X harder. Consider Y instead because Z."
+
+BAD: "LGTM"
+GOOD: "Reviewed. Acceptance criteria met. No blocking issues found."
+```
+
+## Kernel-Grade Rigor
+
+Linus reviews:
+- Every line matters
+- Every abstraction must earn its place
+- Every complexity must justify itself
+- Every assumption must be validated
+
+Not mean, but demanding. Code lives a long time.

.agents/skills/linus-beads-discipline/workflows/triage.md

@@ -0,0 +1,68 @@
+# Triage Workflow
+
+**"What should I work on?"**
+
+## Trigger
+- "What's up?" / "What's going on?" / "What should I do?"
+- "Yo" / "Hey" / Any session start
+- "What's the status?"
+
+## The Flow
+
+### 1. Read Current State
+```bash
+bd ready                    # What's unblocked?
+bd query "status=in_progress"  # What's currently being worked on?
+```
+
+### 2. Analyze Options
+- Look at priority (P0 > P1 > P2 > P3)
+- Look at blockers (ready vs blocked)
+- Look at dependencies (what unblocks others?)
+- Consider your strengths (if known)
+
+### 3. Check Skills
+```
+Any relevant skills for the available work?
+- Check for skills matching task type
+- Use if helpful, skip if not
+```
+
+### 4. Recommend or Claim
+Either:
+- **Recommend**: "Next best bead is X because Y"
+- **Claim**: Update bead to in_progress with plan
+
+### 5. Update Memory
+```bash
+# If recommending
+bd update <id> --notes "Recommended for next agent: ..."
+
+# If claiming
+bd update <id> --status in_progress --notes "@<agent> claiming. Plan: ..."
+```
+
+## Decision: Recommend vs Claim
+
+| Recommend When | Claim When |
+|----------------|------------|
+| Multiple agents available | You're the only one |
+| Uncertain if right fit | Clear fit for your skills |
+| Need human decision | Clear path forward |
+| High-stakes work | Routine work |
+
+## Handoff Protocol
+
+If work was previously in_progress by another agent:
+1. Read their notes carefully: `bd show <id>`
+2. Check for handoff notes
+3. Acknowledge their work in your first update
+4. Continue from where they left off
+
+## Output
+
+End triage with:
+- Clear next bead identified
+- Why it's the right choice
+- Any blockers or dependencies noted
+- Memory updated