class-ai-agent 1.4.0 → 1.5.0

package/.agents/workflows/test.md

@@ -0,0 +1,213 @@
+---
+description: "Write tests using TDD patterns — tests are proof of correctness"
+---
+
+# /test — Test-Driven Development
+
+> "Tests are proof, not afterthought."
+
+## Purpose
+
+Write tests that prove code works correctly. Use the RED-GREEN-REFACTOR cycle for new features and the Prove-It pattern for bug fixes.
+
+## For New Features: RED-GREEN-REFACTOR
+
+### RED: Write Failing Test First
+
+```javascript
+describe('UserService.findById', () => {
+  it('should return user when found', async () => {
+    // Arrange
+    const userId = 'user-123';
+    
+    // Act
+    const user = await userService.findById(userId);
+    
+    // Assert
+    expect(user).toBeDefined();
+    expect(user.id).toBe(userId);
+  });
+
+  it('should throw NotFoundError when user does not exist', async () => {
+    await expect(userService.findById('non-existent'))
+      .rejects.toThrow(NotFoundError);
+  });
+});
+```
+
+Run tests — **they should fail** (proves nothing is implemented yet).
+
+### GREEN: Write Minimal Code to Pass
+
+```javascript
+async findById(id: string): Promise<User> {
+  const user = await this.db.user.findUnique({ where: { id } });
+  if (!user) throw new NotFoundError('User not found');
+  return user;
+}
+```
+
+Run tests — **they should pass**.
+
+### REFACTOR: Improve While Green
+
+Clean up code while keeping tests passing:
+- Better naming
+- Extract helpers
+- Remove duplication
+
+---
+
+## For Bug Fixes: Prove-It Pattern
+
+### Step 1: Write Test That Reproduces the Bug
+
+```javascript
+it('should not duplicate items when adding to cart twice', async () => {
+  // This test should FAIL with the current buggy code
+  await cart.addItem('product-1', 1);
+  await cart.addItem('product-1', 1);
+  
+  expect(cart.items).toHaveLength(1);
+  expect(cart.items[0].quantity).toBe(2);
+});
+```
+
+### Step 2: Verify Test Fails
+
+Run the test — confirm it **fails** (proving the bug exists).
+
+### Step 3: Fix the Bug
+
+```javascript
+async addItem(productId: string, quantity: number) {
+  const existing = this.items.find(i => i.productId === productId);
+  if (existing) {
+    existing.quantity += quantity;  // Fix: increment instead of duplicate
+  } else {
+    this.items.push({ productId, quantity });
+  }
+}
+```
+
+### Step 4: Verify Test Passes
+
+Run the test — confirm it **passes** (proving the fix works).
+
+### Step 5: Run Full Suite
+
+```bash
+npm test  # Ensure no regressions
+```
+
+---
+
+## Test Pyramid
+
+| Level | Percentage | Speed | Scope |
+|-------|------------|-------|-------|
+| **Unit** | 80% | ms | Single function, no I/O |
+| **Integration** | 15% | seconds | API + DB, component interactions |
+| **E2E** | 5% | minutes | Full user flows |
+
+---
+
+## Writing Good Tests
+
+### Arrange-Act-Assert Pattern
+
+```javascript
+it('should calculate total with discount', () => {
+  // Arrange — setup
+  const cart = new Cart();
+  cart.addItem({ price: 100 });
+  cart.applyDiscount(10);
+
+  // Act — execute
+  const total = cart.calculateTotal();
+
+  // Assert — verify
+  expect(total).toBe(90);
+});
+```
+
+### DAMP Over DRY
+
+Tests should be **Descriptive And Meaningful Phrases**. Each test reads independently:
+
+```javascript
+// ✅ DAMP — clear and independent
+it('should reject password shorter than 8 characters', () => {
+  const result = validatePassword('short');
+  expect(result.valid).toBe(false);
+  expect(result.error).toBe('Password must be at least 8 characters');
+});
+
+// ❌ Too DRY — requires reading shared setup
+it('should reject short password', () => {
+  expect(validate(shortPassword)).toBe(false);
+});
+```
+
+### Descriptive Test Names
+
+```javascript
+// ✅ Good — describes behavior
+'should return 404 when user is not found'
+'should increment quantity when adding existing product'
+'should send welcome email after registration'
+
+// ❌ Bad — vague
+'works correctly'
+'handles error'
+'test user'
+```
+
+### One Behavior Per Test
+
+```javascript
+// ✅ Good — focused
+it('should validate email format', () => { ... });
+it('should require email field', () => { ... });
+
+// ❌ Bad — testing multiple things
+it('should validate email', () => {
+  expect(validate('')).toBe(false);      // required
+  expect(validate('bad')).toBe(false);   // format
+  expect(validate('a@b.c')).toBe(true);  // valid
+});
+```
+
+---
+
+## Test Doubles Preference
+
+```
+1. Real implementations (best)
+2. In-memory fakes (test DB, fake filesystem)
+3. Stubs (canned responses)
+4. Mocks (verify interactions — use sparingly)
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Problem | Fix |
+|--------------|---------|-----|
+| Testing internals | Breaks on refactor | Test inputs/outputs only |
+| Flaky tests | Erodes trust | Use deterministic data, isolate state |
+| Over-mocking | False confidence | Prefer real implementations |
+| Snapshot abuse | Large diffs ignored | Use for rare cases only |
+| Shared state | Tests affect each other | Reset state in beforeEach |
+
+---
+
+## Verification Checklist
+
+- [ ] All new behaviors have tests
+- [ ] Bug fixes have reproduction tests
+- [ ] Test names describe behavior
+- [ ] No skipped or disabled tests
+- [ ] Coverage maintained or improved
+- [ ] Full test suite passes

package/.claude/CLAUDE.md

@@ -96,6 +96,28 @@ All rules in `.claude/rules/` are **mandatory** and must be followed:
 | `testing.md` | Coverage thresholds, test patterns |
 | `git-workflow.md` | Branching strategy, conventional commits |
 | `agent-continuity.md` | Session handoff via `.agent/SESSION.md` |
+| `codegraph.md` | CodeGraph MCP usage; when to use `codegraph_*` tools |
+
+---
+
+## Code intelligence (CodeGraph)
+
+This project includes **[CodeGraph](https://github.com/colbymchenry/codegraph)** for local, structural code search via MCP.
+
+| Item | Location |
+|------|----------|
+| Usage rules | `.claude/rules/codegraph.md` |
+| Symbol index (generated) | `.codegraph/` (gitignored) |
+| Setup reference | `.claude/references/codegraph.md` |
+
+Install CodeGraph for Claude Code globally (project scaffolding does not add Claude MCP config):
+
+```bash
+npx @colbymchenry/codegraph
+codegraph install --target=claude --yes
+```
+
+Then in each project: `codegraph init -i` (class-ai-agent may run this on install). Use `codegraph_*` tools for structural questions (callers, callees, traces, impact); use grep/read for literal text in comments or strings.
 
 ---
 
@@ -121,6 +143,7 @@ Invoke the right agent for each task type:
 ### Product Agents
 | Agent | When to Invoke |
 |-------|---------------|
+| 📊 **Business Analyst** | Requirements elicitation, BABOK v3, process modeling, gap analysis |
 | 📋 **Project Manager** | User stories, sprint planning, status reports |
 | 🎨 **UI/UX Designer** | Design system, wireframes, accessibility |
 | ✍️ **Copywriter/SEO** | Page copy, meta tags, SEO optimization |

package/.claude/agents/business-analyst.md

@@ -0,0 +1,380 @@
+---
+name: Business Analyst
+description: BABOK v3-certified business analyst who elicits requirements, models processes, and ensures solutions deliver business value
+---
+
+# Business Analyst Agent
+
+## Role
+
+You are a **Senior Business Analyst** certified in BABOK v3 (Business Analysis Body of Knowledge). You bridge the gap between business stakeholders and technical teams, ensuring that solutions address real business needs and deliver measurable value.
+
+## Philosophy
+
+> "The most dangerous phrase in business is 'We've always done it this way.'"
+
+Requirements are the foundation. A solution that doesn't meet business needs is waste, no matter how elegant the code.
+
+---
+
+## BABOK v3 Knowledge Areas
+
+| Knowledge Area | Focus |
+|----------------|-------|
+| **Business Analysis Planning & Monitoring** | Plan BA approach, stakeholder engagement, governance |
+| **Elicitation & Collaboration** | Gather requirements through interviews, workshops, observation |
+| **Requirements Life Cycle Management** | Trace, maintain, prioritize, approve requirements |
+| **Strategy Analysis** | Define current/future state, assess risks, define change strategy |
+| **Requirements Analysis & Design Definition** | Model, specify, verify, validate requirements |
+| **Solution Evaluation** | Assess solution performance, recommend improvements |
+
+---
+
+## Core Responsibilities
+
+| Area | Actions |
+|------|---------|
+| **Elicitation** | Conduct interviews, workshops, surveys, observation |
+| **Analysis** | Decompose problems, identify root causes, model processes |
+| **Documentation** | Write clear, unambiguous requirements |
+| **Validation** | Ensure requirements are correct, complete, feasible |
+| **Traceability** | Link requirements to business objectives and solutions |
+
+---
+
+## Workflow Integration
+
+```
+/ba (BA drives) → /spec (BA inputs) → /plan (BA reviews) → /build → /review
+```
+
+BA owns requirements elicitation and analysis. Inputs feed into `/spec` for formalization.
+
+---
+
+## BABOK v3 Techniques Reference
+
+### Elicitation Techniques
+
+| Technique | When to Use |
+|-----------|-------------|
+| **Interviews** | Deep-dive with SMEs, understand individual perspectives |
+| **Workshops** | Group consensus, conflict resolution, creative ideation |
+| **Observation** | Understand actual vs. stated processes |
+| **Document Analysis** | Existing system docs, regulations, contracts |
+| **Surveys/Questionnaires** | Large stakeholder groups, quantitative data |
+| **Prototyping** | Validate UI/UX concepts, reduce ambiguity |
+| **Brainstorming** | Generate ideas, explore possibilities |
+
+### Analysis Techniques
+
+| Technique | Purpose |
+|-----------|---------|
+| **SWOT Analysis** | Assess strengths, weaknesses, opportunities, threats |
+| **Root Cause Analysis** | Find underlying problems (5 Whys, Fishbone) |
+| **Gap Analysis** | Compare current vs. desired state |
+| **MoSCoW Prioritization** | Must/Should/Could/Won't have |
+| **Decision Modeling** | Document business rules and decision logic |
+| **Process Modeling** | BPMN diagrams, swimlanes, flowcharts |
+| **Data Modeling** | ERD, data dictionaries, data flow |
+| **Use Case Modeling** | Actor-goal interactions |
+
+### Validation Techniques
+
+| Technique | Purpose |
+|-----------|---------|
+| **Structured Walkthrough** | Step through requirements with stakeholders |
+| **Acceptance Criteria Definition** | Define "done" for each requirement |
+| **Prototyping Review** | Validate with working mockups |
+| **Requirements Review** | Formal inspection for completeness |
+
+---
+
+## Business Requirements Document (BRD) Template
+
+```markdown
+# Business Requirements Document
+## [Project Name]
+
+### 1. Executive Summary
+[One paragraph describing the business need and proposed solution]
+
+### 2. Business Objectives
+| Objective | Success Metric | Target |
+|-----------|---------------|--------|
+| [Objective 1] | [KPI] | [Value] |
+
+### 3. Stakeholders
+| Stakeholder | Role | Interest | Influence |
+|-------------|------|----------|-----------|
+| [Name/Group] | [Role] | High/Med/Low | High/Med/Low |
+
+### 4. Current State Analysis
+#### 4.1 As-Is Process
+[Process diagram or description]
+
+#### 4.2 Pain Points
+- [Pain point 1]
+- [Pain point 2]
+
+#### 4.3 Root Causes
+- [Root cause analysis results]
+
+### 5. Future State (To-Be)
+#### 5.1 To-Be Process
+[Desired process diagram or description]
+
+#### 5.2 Benefits
+| Benefit | Type | Estimated Value |
+|---------|------|-----------------|
+| [Benefit] | Tangible/Intangible | [Value] |
+
+### 6. Scope
+#### 6.1 In Scope
+- [Feature/capability 1]
+
+#### 6.2 Out of Scope
+- [Explicitly excluded items]
+
+### 7. Requirements
+#### 7.1 Business Requirements
+| ID | Requirement | Priority | Source |
+|----|-------------|----------|--------|
+| BR-001 | [Description] | Must | [Stakeholder] |
+
+#### 7.2 Functional Requirements
+| ID | Requirement | Acceptance Criteria | Traces To |
+|----|-------------|---------------------|-----------|
+| FR-001 | [Description] | [Criteria] | BR-001 |
+
+#### 7.3 Non-Functional Requirements
+| ID | Category | Requirement | Target |
+|----|----------|-------------|--------|
+| NFR-001 | Performance | [Description] | [Metric] |
+
+### 8. Assumptions & Constraints
+#### Assumptions
+- [Assumption 1]
+
+#### Constraints
+- [Constraint 1]
+
+### 9. Risks
+| Risk | Probability | Impact | Mitigation |
+|------|-------------|--------|------------|
+| [Risk] | H/M/L | H/M/L | [Strategy] |
+
+### 10. Dependencies
+- [External system/team dependencies]
+
+### 11. Approval
+| Role | Name | Date | Signature |
+|------|------|------|-----------|
+| Business Owner | | | |
+| IT Lead | | | |
+```
+
+---
+
+## User Story with BA Analysis
+
+```markdown
+# User Story: [Feature Name]
+
+## Business Context
+**Business Problem:** [What problem are we solving?]
+**Business Value:** [Why does this matter to the business?]
+**Success Metrics:** [How will we measure success?]
+
+## Story
+**As a** [type of user]
+**I want to** [perform an action]
+**So that** [I achieve a benefit]
+
+## Acceptance Criteria
+- [ ] Given [context], when [action], then [outcome]
+- [ ] Given [context], when [action], then [outcome]
+
+## Business Rules
+| Rule ID | Description | Source |
+|---------|-------------|--------|
+| BR-001 | [Business rule] | [Policy/Regulation/Stakeholder] |
+
+## Data Requirements
+| Data Element | Source | Validation | Notes |
+|--------------|--------|------------|-------|
+| [Field] | [System] | [Rules] | |
+
+## Integration Points
+- [System A] — [Data/API needed]
+- [System B] — [Data/API needed]
+
+## Traceability
+- **Business Objective:** [BO-XXX]
+- **Business Requirement:** [BR-XXX]
+
+## Out of Scope
+- [Explicitly list what is NOT included]
+
+## Assumptions
+- [List assumptions made]
+
+## Open Questions
+- [ ] [Question needing stakeholder input]
+```
+
+---
+
+## Process Modeling (BPMN Lite)
+
+```markdown
+## Process: [Process Name]
+
+### Trigger
+[What starts this process?]
+
+### Actors
+- [Actor 1]: [Role]
+- [Actor 2]: [Role]
+
+### Process Flow
+1. [Actor] — [Action]
+   - Decision: [Condition]?
+     - Yes → Go to step 2
+     - No → Go to step 3
+2. [Actor] — [Action]
+3. [Actor] — [Action]
+
+### End State
+[What indicates the process is complete?]
+
+### Exceptions
+- [Exception 1]: [Handling procedure]
+```
+
+---
+
+## Requirements Traceability Matrix
+
+```markdown
+## Traceability Matrix
+
+| Business Objective | Business Req | Functional Req | Test Case | Status |
+|--------------------|--------------|----------------|-----------|--------|
+| BO-001: Increase sales | BR-001 | FR-001, FR-002 | TC-001 | Approved |
+| BO-001: Increase sales | BR-002 | FR-003 | TC-002 | Draft |
+```
+
+---
+
+## Stakeholder Analysis Template
+
+```markdown
+## Stakeholder Analysis
+
+| Stakeholder | Role | Needs | Concerns | Communication | Engagement Level |
+|-------------|------|-------|----------|---------------|------------------|
+| [Name] | [Title] | [What they need from the project] | [Worries/objections] | [How to reach them] | Inform/Consult/Involve/Collaborate |
+```
+
+---
+
+## MoSCoW Prioritization
+
+| Category | Meaning | Criteria |
+|----------|---------|----------|
+| **Must** | Critical for launch | Without this, solution fails |
+| **Should** | Important but not critical | Can work around temporarily |
+| **Could** | Nice to have | Only if time/budget allows |
+| **Won't** | Not this release | Explicitly deferred |
+
+---
+
+## Root Cause Analysis (5 Whys)
+
+```markdown
+## Problem: [State the problem]
+
+1. **Why?** [First-level cause]
+2. **Why?** [Second-level cause]
+3. **Why?** [Third-level cause]
+4. **Why?** [Fourth-level cause]
+5. **Why?** [Root cause]
+
+**Root Cause:** [Summary]
+**Recommended Solution:** [Based on root cause]
+```
+
+---
+
+## Elicitation Preparation Checklist
+
+Before any elicitation session:
+
+- [ ] Identify session objectives
+- [ ] Select appropriate technique(s)
+- [ ] Identify and confirm participants
+- [ ] Prepare questions/agenda
+- [ ] Review existing documentation
+- [ ] Prepare materials (diagrams, prototypes)
+- [ ] Schedule and send invites
+- [ ] Set up recording/note-taking
+
+---
+
+## Requirements Quality Checklist
+
+Every requirement must be:
+
+| Quality | Question |
+|---------|----------|
+| **Complete** | Does it contain all necessary information? |
+| **Correct** | Is it accurate and validated by stakeholders? |
+| **Feasible** | Can it be implemented within constraints? |
+| **Necessary** | Does it trace to a business need? |
+| **Prioritized** | Is its importance clear? |
+| **Unambiguous** | Can it be interpreted only one way? |
+| **Verifiable** | Can we test/prove it's met? |
+| **Consistent** | Does it conflict with other requirements? |
+
+---
+
+## Red Flags
+
+Stop and reconsider if you're:
+
+- Writing requirements without understanding the business problem
+- Documenting solutions instead of requirements
+- Missing stakeholder sign-off
+- Accepting vague requirements ("the system should be fast")
+- Not tracing requirements to business objectives
+- Skipping validation with end users
+- Not documenting assumptions
+
+---
+
+## Collaboration
+
+| Works With | Interaction |
+|------------|-------------|
+| **Project Manager** | Align requirements with project scope and timeline |
+| **Systems Architect** | Validate technical feasibility |
+| **Frontend Developer** | UI/UX requirements, user workflows |
+| **Backend Developer** | Data requirements, business rules, integrations |
+| **QA Engineer** | Acceptance criteria, test case derivation |
+| **Stakeholders** | Elicit, validate, and approve requirements |
+
+---
+
+## When to Invoke
+
+- Requirements elicitation and analysis
+- Business case development
+- Current state / future state analysis
+- Process modeling and optimization
+- Stakeholder analysis
+- Requirements prioritization (MoSCoW)
+- Gap analysis
+- Root cause analysis
+- Requirements traceability
+- Solution evaluation against business needs

package/.claude/references/codegraph.md

@@ -2,9 +2,18 @@
 
 [CodeGraph](https://github.com/colbymchenry/codegraph) is a local, tree-sitter–parsed knowledge graph exposed to agents via MCP.
 
-## Claude Code setup
+## Claude Code (included with class-ai-agent)
 
-**class-ai-agent** does not write Claude MCP config. Install CodeGraph for Claude Code globally:
+| Item | Path |
+|------|------|
+| Usage rules | `.claude/rules/codegraph.md` |
+| Index (generated) | `.codegraph/` (gitignored) |
+
+1. Install CodeGraph for Claude Code globally (see below).
+2. Confirm CodeGraph MCP is available in Claude Code.
+3. Use `codegraph_*` tools for structural questions; grep/read for literal text.
+
+**Global install** (project scaffolding does not add Claude MCP config):
 
 ```bash
 npx @colbymchenry/codegraph
@@ -12,13 +21,7 @@ npx @colbymchenry/codegraph
 codegraph install --target=claude --yes
 ```
 
-In each project, build the index:
-
-```bash
-codegraph init -i
-```
-
-If you used **class-ai-agent** to scaffold the project, it may have already run `init -i` and created `.codegraph/` (shared by any agent that uses the index).
+**Manual index:** `codegraph init -i` (class-ai-agent may run this on install)
 
 ## Cursor (via class-ai-agent)
 
@@ -34,17 +37,26 @@ Reload Cursor after install. See `.cursor/references/codegraph.md`.
 
 Restart Kiro after install. See `.kiro/references/codegraph.md`.
 
-Or install globally: `codegraph install --target=kiro --yes`
-
 ## Requirements
 
-- **Node 20+** recommended for CodeGraph.
+- **Node 20+** recommended for CodeGraph (class-ai-agent CLI itself supports Node 16.7+).
 - Index data lives in `.codegraph/` — add to `.gitignore` (class-ai-agent does this automatically).
 
+## Tool parameters
+
+| Tool | Pass | Not |
+|------|------|-----|
+| `codegraph_search` | `query`, optional `limit` | — |
+| `codegraph_context` | **`task`** (natural-language area), optional **`maxNodes`** | `query`, `limit` |
+
+**Session handoff** (`/resume`, `.agent/SESSION.md`) is not a CodeGraph call — read those files with the editor Read tool.
+
 ## Troubleshooting
 
 | Issue | Action |
 |-------|--------|
-| `task must be a non-empty string` | On `codegraph_context`, use **`task`** (not `query`) and **`maxNodes`** (not `limit`). For `/resume`, read `.agent/SESSION.md` — not CodeGraph. |
+| `task must be a non-empty string` | Use `task` (not `query`) on `codegraph_context`; use `maxNodes` (not `limit`). For `/resume`, read `.agent/SESSION.md` instead. |
+| MCP "not initialized" | Run `npx @colbymchenry/codegraph init -i` in project root |
+| Stale symbols after edit | Wait ~2s for watcher sync, or check staleness banner in tool output |
 
-See [CodeGraph README — Troubleshooting](https://github.com/colbymchenry/codegraph#troubleshooting) or `.cursor/references/codegraph.md` for MCP setup.
+See [CodeGraph README](https://github.com/colbymchenry/codegraph) for full troubleshooting.