bobs-workshop 0.3.3 → 3.1.0

package/src/skills/brainstorming/SKILL.md

@@ -0,0 +1,210 @@
+---
+name: brainstorming
+description: Socratic questioning protocol + user communication. MANDATORY for complex requests, new features, or unclear requirements.
+metadata:
+  recommended_for: alice
+  category: communication
+---
+
+# Brainstorming & Communication Protocol
+
+> **MANDATORY:** Use for complex/vague requests, new features, updates.
+
+---
+
+## 🛑 SOCRATIC GATE (ENFORCEMENT)
+
+### When to Trigger
+
+| Pattern | Action |
+|---------|--------|
+| "Build/Create/Make [thing]" without details | 🛑 ASK 3 questions |
+| Complex feature or architecture | 🛑 Clarify before implementing |
+| Update/change request | 🛑 Confirm scope |
+| Vague requirements | 🛑 Ask purpose, users, constraints |
+
+### 🚫 MANDATORY: 3 Questions Before Implementation
+
+1. **STOP** - Do NOT start coding
+2. **ASK** - Minimum 3 questions:
+   - 🎯 Purpose: What problem are you solving?
+   - 👥 Users: Who will use this?
+   - 📦 Scope: Must-have vs nice-to-have?
+3. **WAIT** - Get response before proceeding
+
+---
+
+## 🧠 Dynamic Question Generation
+
+**⛔ NEVER use static templates.** Read `dynamic-questioning.md` for principles.
+
+### Core Principles
+
+| Principle | Meaning |
+|-----------|---------|
+| **Questions Reveal Consequences** | Each question connects to an architectural decision |
+| **Context Before Content** | Understand greenfield/feature/refactor/debug context first |
+| **Minimum Viable Questions** | Each question must eliminate implementation paths |
+| **Generate Data, Not Assumptions** | Don't guess—ask with trade-offs |
+
+### Question Generation Process
+
+```
+1. Parse request → Extract domain, features, scale indicators
+2. Identify decision points → Blocking vs. deferable
+3. Generate questions → Priority: P0 (blocking) > P1 (high-leverage) > P2 (nice-to-have)
+4. Format with trade-offs → What, Why, Options, Default
+```
+
+### Question Format (MANDATORY)
+
+```markdown
+### [PRIORITY] **[DECISION POINT]**
+
+**Question:** [Clear question]
+
+**Why This Matters:**
+- [Architectural consequence]
+- [Affects: cost/complexity/timeline/scale]
+
+**Options:**
+| Option | Pros | Cons | Best For |
+|--------|------|------|----------|
+| A | [+] | [-] | [Use case] |
+
+**If Not Specified:** [Default + rationale]
+```
+
+---
+
+## Progress Reporting (PRINCIPLE-BASED)
+
+**PRINCIPLE:** Transparency builds trust. Status must be visible and actionable.
+
+### Status Board Format
+
+| Agent | Status | Current Task | Progress |
+|-------|--------|--------------|----------|
+| [Agent Name] | ✅🔄⏳❌⚠️ | [Task description] | [% or count] |
+
+### Status Icons
+
+| Icon | Meaning | Usage |
+|------|---------|-------|
+| ✅ | Completed | Task finished successfully |
+| 🔄 | Running | Currently executing |
+| ⏳ | Waiting | Blocked, waiting for dependency |
+| ❌ | Error | Failed, needs attention |
+| ⚠️ | Warning | Potential issue, not blocking |
+
+---
+
+## Error Handling (PRINCIPLE-BASED)
+
+**PRINCIPLE:** Errors are opportunities for clear communication.
+
+### Error Response Pattern
+
+```
+1. Acknowledge the error
+2. Explain what happened (user-friendly)
+3. Offer specific solutions with trade-offs
+4. Ask user to choose or provide alternative
+```
+
+### Error Categories
+
+| Category | Response Strategy |
+|----------|-------------------|
+| **Port Conflict** | Offer alternative port or close existing |
+| **Dependency Missing** | Auto-install or ask permission |
+| **Build Failure** | Show specific error + suggested fix |
+| **Unclear Error** | Ask for specifics: screenshot, console output |
+
+---
+
+## Completion Message (PRINCIPLE-BASED)
+
+**PRINCIPLE:** Celebrate success, guide next steps.
+
+### Completion Structure
+
+```
+1. Success confirmation (celebrate briefly)
+2. Summary of what was done (concrete)
+3. How to verify/test (actionable)
+4. Next steps suggestion (proactive)
+```
+
+---
+
+## Communication Principles
+
+| Principle | Implementation |
+|-----------|----------------|
+| **Concise** | No unnecessary details, get to point |
+| **Visual** | Use emojis (✅🔄⏳❌) for quick scanning |
+| **Specific** | "~2 minutes" not "wait a bit" |
+| **Alternatives** | Offer multiple paths when stuck |
+| **Proactive** | Suggest next step after completion |
+
+---
+
+## Anti-Patterns (AVOID)
+
+| Anti-Pattern | Why |
+|--------------|-----|
+| Jumping to solutions before understanding | Wastes time on wrong problem |
+| Assuming requirements without asking | Creates wrong output |
+| Over-engineering first version | Delays value delivery |
+| Ignoring constraints | Creates unusable solutions |
+| "I think" phrases | Uncertainty → Ask instead |
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **alice (architect)** agent during the PLAN phase.
+
+### MANUAL Integration
+
+Add planning section to MANUAL:
+```markdown
+## 📝 Product Specifications
+
+### Requirements Clarification (Socratic Gate)
+- [ ] Purpose identified
+- [ ] Target users defined
+- [ ] Scope confirmed (must-have vs nice-to-have)
+
+### Key Decisions
+| Decision | Options | Chosen | Rationale |
+|----------|---------|---------|-----------|
+| [Tech stack] | [Option A/B/C] | [Choice] | [Why] |
+| [Database] | [Option A/B/C] | [Choice] | [Why] |
+```
+
+### Progress Tracking
+
+Update agent handoffs with status:
+```markdown
+## 🤝 Agent Handoffs
+
+🔄 alice: Planning in progress (3/5 tasks complete)
+🤝 alice → bob-eng: Handoff - MANUAL ready for implementation
+```
+
+### Error Handling
+
+Standardize error messages across all agents:
+```markdown
+❌ Error: [Brief description]
+
+**What happened:** [User-friendly explanation]
+
+**Options:**
+1. [Solution A] - [Trade-off]
+2. [Solution B] - [Trade-off]
+
+Which would you prefer?
+```

package/src/skills/clean-code/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: clean-code
+description: Pragmatic coding standards - concise, direct, no over-engineering, no unnecessary comments
+metadata:
+  recommended_for: bob-eng
+  category: code-quality
+---
+
+# Clean Code - Pragmatic AI Coding Standards
+
+> **CRITICAL SKILL** - Be **concise, direct, and solution-focused**.
+
+---
+
+## Core Principles
+
+| Principle | Rule |
+|-----------|------|
+| **SRP** | Single Responsibility - each function/class does ONE thing |
+| **DRY** | Don't Repeat Yourself - extract duplicates, reuse |
+| **KISS** | Keep It Simple - simplest solution that works |
+| **YAGNI** | You Aren't Gonna Need It - don't build unused features |
+| **Boy Scout** | Leave code cleaner than you found it |
+
+---
+
+## Naming Rules
+
+| Element | Convention |
+|---------|------------|
+| **Variables** | Reveal intent: `userCount` not `n` |
+| **Functions** | Verb + noun: `getUserById()` not `user()` |
+| **Booleans** | Question form: `isActive`, `hasPermission`, `canEdit` |
+| **Constants** | SCREAMING_SNAKE: `MAX_RETRY_COUNT` |
+
+> **Rule:** If you need a comment to explain a name, rename it.
+
+---
+
+## Function Rules
+
+| Rule | Description |
+|------|-------------|
+| **Small** | Max 20 lines, ideally 5-10 |
+| **One Thing** | Does one thing, does it well |
+| **One Level** | One level of abstraction per function |
+| **Few Args** | Max 3 arguments, prefer 0-2 |
+| **No Side Effects** | Don't mutate inputs unexpectedly |
+
+---
+
+## Code Structure
+
+| Pattern | Apply |
+|---------|-------|
+| **Guard Clauses** | Early returns for edge cases |
+| **Flat > Nested** | Avoid deep nesting (max 2 levels) |
+| **Composition** | Small functions composed together |
+| **Colocation** | Keep related code close |
+
+---
+
+## AI Coding Style
+
+| Situation | Action |
+|-----------|--------|
+| User asks for feature | Write it directly |
+| User reports bug | Fix it, don't explain |
+| No clear requirement | Ask, don't assume |
+
+---
+
+## Anti-Patterns (DON'T)
+
+| ❌ Pattern | ✅ Fix |
+|-----------|-------|
+| Comment every line | Delete obvious comments |
+| Helper for one-liner | Inline the code |
+| Factory for 2 objects | Direct instantiation |
+| utils.ts with 1 function | Put code where used |
+| "First we import..." | Just write code |
+| Deep nesting | Guard clauses |
+| Magic numbers | Named constants |
+| God functions | Split by responsibility |
+
+---
+
+## 🔴 Before Editing ANY File (THINK FIRST!)
+
+**Before changing a file, ask yourself:**
+
+| Question | Why |
+|----------|-----|
+| **What imports this file?** | They might break |
+| **What does this file import?** | Interface changes |
+| **What tests cover this?** | Tests might fail |
+| **Is this a shared component?** | Multiple places affected |
+
+**Quick Check:**
+```
+File to edit: UserService.ts
+└── Who imports this? → UserController.ts, AuthController.ts
+└── Do they need changes too? → Check function signatures
+```
+
+> 🔴 **Rule:** Edit the file + all dependent files in the SAME task.
+> 🔴 **Never leave broken imports or missing updates.**
+
+---
+
+## Self-Check Before Completing (MANDATORY)
+
+**Before saying "task complete", verify:**
+
+| Check | Question |
+|-------|----------|
+| ✅ **Goal met?** | Did I do exactly what user asked? |
+| ✅ **Files edited?** | Did I modify all necessary files? |
+| ✅ **Code works?** | Did I test/verify the change? |
+| ✅ **No errors?** | Lint and TypeScript pass? |
+| ✅ **Nothing forgotten?** | Any edge cases missed? |
+
+> 🔴 **Rule:** If ANY check fails, fix it before completing.
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **bob-eng (engineer)** agent during the BUILD phase.
+
+### MANUAL Integration
+
+Add code quality checks to implementation logs:
+```markdown
+## 📈 Execution Logs
+
+### Code Quality
+- [ ] Functions under 20 lines
+- [ ] Nesting depth ≤ 2
+- [ ] No magic numbers
+- [ ] Clear, descriptive names
+- [ ] No deep nesting
+```
+
+### Verification
+
+Before handing off to bob-rev, verify:
+- All code follows clean code principles
+- No linting errors
+- No TypeScript errors
+- All imports are correct

package/src/skills/code-review-checklist/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: code-review-checklist
+description: Code review guidelines covering code quality, security, and best practices.
+metadata:
+  recommended_for: bob-rev
+  category: review
+---
+
+# Code Review Checklist
+
+## Quick Review Checklist
+
+### Correctness
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error handling in place
+- [ ] No obvious bugs
+
+### Security
+- [ ] Input validated and sanitized
+- [ ] No SQL/NoSQL injection vulnerabilities
+- [ ] No XSS or CSRF vulnerabilities
+- [ ] No hardcoded secrets or sensitive credentials
+- [ ] **AI-Specific:** Protection against Prompt Injection (if applicable)
+- [ ] **AI-Specific:** Outputs are sanitized before being used in critical sinks
+
+### Performance
+- [ ] No N+1 queries
+- [ ] No unnecessary loops
+- [ ] Appropriate caching
+- [ ] Bundle size impact considered
+
+### Code Quality
+- [ ] Clear naming
+- [ ] DRY - no duplicate code
+- [ ] SOLID principles followed
+- [ ] Appropriate abstraction level
+
+### Testing
+- [ ] Unit tests for new code
+- [ ] Edge cases tested
+- [ ] Tests readable and maintainable
+
+### Documentation
+- [ ] Complex logic commented
+- [ ] Public APIs documented
+- [ ] README updated if needed
+
+## AI & LLM Review Patterns (2025)
+
+### Logic & Hallucinations
+- [ ] **Chain of Thought:** Does the logic follow a verifiable path?
+- [ ] **Edge Cases:** Did the AI account for empty states, timeouts, and partial failures?
+- [ ] **External State:** Is the code making safe assumptions about file systems or networks?
+
+### Prompt Engineering Review
+```markdown
+// ❌ Vague prompt in code
+const response = await ai.generate(userInput);
+
+// ✅ Structured & Safe prompt
+const response = await ai.generate({
+  system: "You are a specialized parser...",
+  input: sanitize(userInput),
+  schema: ResponseSchema
+});
+```
+
+## Anti-Patterns to Flag
+
+```typescript
+// ❌ Magic numbers
+if (status === 3) { ... }
+
+// ✅ Named constants
+if (status === Status.ACTIVE) { ... }
+
+// ❌ Deep nesting
+if (a) { if (b) { if (c) { ... } } }
+
+// ✅ Early returns
+if (!a) return;
+if (!b) return;
+if (!c) return;
+// do work
+
+// ❌ Long functions (100+ lines)
+// ✅ Small, focused functions
+
+// ❌ any type
+const data: any = ...
+
+// ✅ Proper types
+const data: UserData = ...
+```
+
+## Review Comments Guide
+
+```
+// Blocking issues use 🔴
+🔴 BLOCKING: SQL injection vulnerability here
+
+// Important suggestions use 🟡
+🟡 SUGGESTION: Consider using useMemo for performance
+
+// Minor nits use 🟢
+🟢 NIT: Prefer const over let for immutable variable
+
+// Questions use ❓
+❓ QUESTION: What happens if user is null here?
+```
+
+---
+
+## Bob's Workshop Integration
+
+This skill is used by **bob-rev (reviewer)** agent during the VERIFY phase.
+
+### MANUAL Integration
+
+Add review section to MANUAL:
+```markdown
+## 🔍 Review Notes
+
+### Review Checklist
+#### Correctness
+- [ ] Code does what it's supposed to do
+- [ ] Edge cases handled
+- [ ] Error handling in place
+
+#### Security
+- [ ] Input validation present
+- [ ] No injection vulnerabilities
+- [ ] No hardcoded secrets
+- [ ] AI outputs sanitized (if applicable)
+
+#### Performance
+- [ ] No N+1 queries
+- [ ] Appropriate caching
+- [ ] Bundle size considered
+
+#### Code Quality
+- [ ] Clear naming
+- [ ] No duplicate code
+- [ ] SOLID principles followed
+- [ ] Proper error handling
+
+#### Testing
+- [ ] Unit tests added
+- [ ] Edge cases covered
+- [ ] Tests readable
+
+### Review Comments
+| Severity | Comment | File:Line | Status |
+|----------|----------|-----------|--------|
+| 🔴 BLOCKING | [Description] | [File:Line] | [Open/Resolved] |
+| 🟡 SUGGESTION | [Description] | [File:Line] | [Open/Resolved] |
+| 🟢 NIT | [Description] | [File:Line] | [Open/Resolved] |
+| ❓ QUESTION | [Description] | [File:Line] | [Answered] |
+
+### Review Decision
+- [ ] ✅ PASS - Ready for SEND
+- [ ] ❌ FAIL - Return to trace for fixes
+```
+
+### PASS/FAIL Criteria
+
+#### PASS Conditions
+- All 🔴 BLOCKING issues resolved
+- Security vulnerabilities addressed
+- Tests pass and have good coverage
+- Code follows project conventions
+- No obvious bugs
+
+#### FAIL Conditions
+- Any unresolved 🔴 BLOCKING issues
+- Security vulnerabilities present
+- Tests failing or missing
+- Code doesn't match MANUAL specifications
+- Breaking changes not documented
+
+### Handoff Format
+
+```markdown
+## 🤝 Agent Handoffs
+
+🤝 bob-rev: Review complete - ✅ PASS / ❌ FAIL
+[Decision rationale]
+
+🤝 bob-rev → trace: [FAIL - Issues found, please fix]
+🤝 bob-rev → bob-send: [PASS - Ready for shipping]
+```
+
+---
+
+## Code Quality Standards
+
+When quality issues are discussed:
+
+- **Enforce conventions** - Ensure code follows project style guides and patterns
+- **Suggest refactors for clarity** - Identify opportunities to simplify complex code
+- **Highlight test coverage gaps** - Point out areas lacking sufficient tests
+
+### Quality Guidelines
+
+| Area | Check | Priority |
+|------|-------|----------|
+| **Readability** | Clear naming, consistent style | High |
+| **Maintainability** | Low complexity, single responsibility | High |
+| **Extensibility** | Easy to extend without major changes | Medium |
+| **Consistency** | Uniform patterns across codebase | Medium |
+
+### Quality Indicators
+
+| Good ✅ | Poor ❌ |
+|---------|---------|
+| Self-documenting code | Requires comments to explain |
+| Small, focused functions | God functions (100+ lines) |
+| Descriptive variable names | Single-letter or cryptic names |
+| DRY - no duplication | Copy-paste code blocks |