codingbuddy-rules 4.2.0 → 4.4.0

package/.ai-rules/skills/code-explanation/SKILL.md

@@ -0,0 +1,259 @@
+---
+name: code-explanation
+description: Use when explaining complex code to new team members, conducting code reviews, onboarding, or understanding unfamiliar codebases. Provides structured analysis from high-level overview to implementation details.
+---
+
+# Code Explanation
+
+## Overview
+
+Understanding code is a prerequisite to improving it. Rushed explanations create misunderstanding that compounds over time.
+
+**Core principle:** Explain at the right level of abstraction. Start high, drill down only when needed.
+
+**Iron Law:**
+```
+READ BEFORE EXPLAINING. UNDERSTAND BEFORE SIMPLIFYING.
+```
+
+Never explain code you haven't fully read. Never simplify what you haven't fully understood.
+
+## When to Use
+
+- Onboarding new team members to a codebase
+- Code review: explaining design decisions
+- Understanding legacy code before modifying it
+- Explaining an AI agent's recommendations
+- Documenting complex algorithms or patterns
+- Understanding error stack traces
+
+## The Five Levels of Explanation
+
+Choose the level based on your audience and purpose:
+
+| Level | Audience | Goal | Depth |
+|-------|----------|------|-------|
+| **L1: Bird's Eye** | Non-technical stakeholders | What does this system do? | Architecture diagram |
+| **L2: Module** | New developers | How is this organized? | Module/file structure |
+| **L3: Function** | Developers onboarding | What does this code do? | Function by function |
+| **L4: Line** | Debugging partners | Why is this written this way? | Line by line |
+| **L5: Algorithm** | Algorithm review | How does this work mathematically? | Proof-level |
+
+## The Explanation Process
+
+### Phase 1: Read First
+
+```
+1. Read the entire file/function before explaining anything
+2. Identify the core purpose (what problem does this solve?)
+3. Note dependencies (what does this require?)
+4. Note side effects (what does this change?)
+5. Note error handling (what can go wrong?)
+```
+
+### Phase 2: Bird's Eye View (Always Start Here)
+
+```markdown
+**What this is:** One sentence describing purpose
+**What problem it solves:** The business/technical need
+**How it fits:** Where it sits in the larger system
+**Key dependencies:** What it relies on
+**Key outputs:** What it produces or modifies
+```
+
+**Example:**
+```markdown
+**What this is:** RulesService — file system reader for AI coding rules
+**What problem it solves:** Provides a unified interface for reading and searching
+  .ai-rules files regardless of directory structure
+**How it fits:** Used by McpModule to serve rules via MCP protocol
+**Key dependencies:** Node.js fs/promises, glob patterns
+**Key outputs:** Array of Rule objects with name, content, and metadata
+```
+
+### Phase 3: Structure Walk-Through
+
+Walk through the code structure before implementation details:
+
+```typescript
+// Before explaining each function, show the structure:
+
+class RulesService {
+  // 1. Constructor — sets up file paths
+  constructor() { ... }
+
+  // 2. getRules() — entry point, returns all rules
+  async getRules(): Promise<Rule[]> { ... }
+
+  // 3. searchRules() — filters rules by query
+  async searchRules(query: string): Promise<Rule[]> { ... }
+
+  // 4. Private: readRuleFile() — reads individual file
+  private async readRuleFile(path: string): Promise<Rule> { ... }
+}
+```
+
+### Phase 4: Deep Dive (Only When Requested)
+
+Explain non-obvious implementation choices:
+
+```typescript
+// ❓ "Why is this using glob instead of fs.readdir?"
+// ✅ "glob allows pattern matching across nested directories
+//    (.ai-rules/**/*.md) without manual recursion. readdir
+//    only lists one directory level."
+
+const files = await glob('**/*.md', { cwd: this.rulesDir });
+```
+
+```typescript
+// ❓ "Why is this async even though it looks synchronous?"
+// ✅ "File I/O is always async in Node.js to avoid blocking
+//    the event loop. Even a small file read blocks for ~1-5ms
+//    which multiplies badly under load."
+
+const content = await fs.readFile(filePath, 'utf-8');
+```
+
+### Phase 5: Mental Model
+
+Finish with a mental model the reader can hold in their head:
+
+```
+RulesService mental model:
+─────────────────────────
+  .ai-rules/             ← Root directory
+  └── rules/core.md      ← Each .md file becomes a Rule
+  └── agents/planner.json ← Each .json becomes an Agent
+
+  getRules() = "read all files, return as array"
+  searchRules() = "filter that array by content match"
+  getAgent() = "read specific JSON file, parse it"
+```
+
+## Explanation Templates
+
+### For Functions
+
+```markdown
+### `functionName(params): returnType`
+
+**Purpose:** [One sentence — what does it do?]
+
+**Parameters:**
+- `param1` — [What it represents, valid range/values]
+- `param2` — [What it represents, valid range/values]
+
+**Returns:** [What is returned, in what shape]
+
+**Side effects:** [What does it change outside itself?]
+
+**Error cases:** [What errors can it throw and when?]
+
+**Example:**
+\`\`\`typescript
+const result = functionName('input', { option: true });
+// result === { expected: 'output' }
+\`\`\`
+```
+
+### For Classes
+
+```markdown
+### `ClassName`
+
+**Responsibility:** [Single responsibility in one sentence]
+
+**Lifecycle:**
+1. Construction — [What happens when created]
+2. Usage — [How it's used]
+3. Cleanup — [Any teardown needed]
+
+**Key methods:**
+- `method1()` — [Purpose]
+- `method2()` — [Purpose]
+
+**Dependencies injected:**
+- `Dependency1` — [Why it needs this]
+```
+
+### For Complex Algorithms
+
+```markdown
+### Algorithm: [Name]
+
+**Problem:** [What problem does this solve?]
+
+**Approach:** [High-level strategy]
+
+**Complexity:** O([time]) time, O([space]) space
+
+**Step-by-step walkthrough:**
+
+Given input `[example input]`:
+1. Step 1 → intermediate result
+2. Step 2 → intermediate result
+3. Final step → `[expected output]`
+
+**Edge cases handled:**
+- Empty input: [behavior]
+- Single element: [behavior]
+- Duplicate values: [behavior]
+```
+
+## Onboarding Guide Format
+
+When explaining a whole codebase to a new team member:
+
+```markdown
+# [Project Name] Codebase Guide
+
+## In 30 Seconds
+
+[What this system does, who uses it, why it exists]
+
+## Mental Model
+
+[ASCII diagram of key components and data flow]
+
+## Start Here
+
+1. Read `src/main.ts` — entry point
+2. Read `src/app.module.ts` — understand module structure
+3. Read `src/mcp/mcp.service.ts` — core business logic
+
+## Key Concepts
+
+**[Concept 1]:** [Explanation with code example]
+**[Concept 2]:** [Explanation with code example]
+
+## Common Tasks
+
+- "How do I add a new rule?" → See `packages/rules/.ai-rules/`
+- "How do I add a new agent?" → See `packages/rules/.ai-rules/agents/`
+- "How do I run tests?" → `yarn test`
+
+## What to Avoid
+
+- [Common mistake 1 and why]
+- [Common mistake 2 and why]
+```
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "I'll explain as I read" | Read first, explain second |
+| "The code is self-explanatory" | It's never self-explanatory to someone new |
+| "Just look at the tests" | Tests explain behavior, not intent |
+| "I'll summarize without reading" | Summaries from unread code spread misinformation |
+
+## Quick Reference
+
+| Situation | Explanation Level |
+|-----------|------------------|
+| New to project | L1 → L2 → L3 on request |
+| Code review | L3 — function by function |
+| Debugging together | L4 — line by line |
+| Algorithm discussion | L5 — mathematical |
+| Stakeholder demo | L1 only |

package/.ai-rules/skills/context-management/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: context-management
+description: Use when working on long tasks that span multiple sessions, when context compaction is a concern, or when decisions from PLAN mode need to persist through ACT and EVAL modes.
+---
+
+# Context Management
+
+## Overview
+
+AI assistant context windows are finite. Long tasks get compacted, earlier decisions are forgotten, and continuity breaks. Context management is the practice of preserving critical information so work survives compaction.
+
+**Core principle:** If it matters after the current conversation, write it down. Memory is the enemy of continuity.
+
+**Iron Law:**
+```
+EXTERNAL STATE > INTERNAL MEMORY
+Write decisions to files. Files survive compaction; conversation memory does not.
+```
+
+## When to Use
+
+- Starting a task that will span multiple sessions
+- Beginning PLAN mode (decisions must survive to ACT)
+- Completing ACT mode (progress must survive to EVAL)
+- When conversation is approaching context limits
+- Before any context compaction event
+- When resuming work after a break
+
+## The Context Document (codingbuddy)
+
+The primary context persistence mechanism is `docs/codingbuddy/context.md`.
+
+```
+docs/codingbuddy/context.md
+─────────────────────────────
+This file is:
+- Created/reset by PLAN mode
+- Appended by ACT mode
+- Appended by EVAL mode
+- Always at a fixed, predictable path
+- Safe to read at any point
+```
+
+### What Goes in Context
+
+**PLAN mode writes:**
+- Task description
+- Key design decisions and their rationale
+- Architecture choices
+- Dependencies and constraints
+- Recommended ACT agent
+
+**ACT mode writes:**
+- Progress milestones completed
+- Files created/modified
+- Implementation decisions made
+- Issues encountered and resolved
+- Next steps
+
+**EVAL mode writes:**
+- Quality findings (with severity)
+- Security issues found
+- Performance observations
+- Recommendations for next iteration
+
+### Context Document Format
+
+```markdown
+# Context: [Task Title]
+
+## PLAN — [timestamp]
+**Task:** [Original task description]
+**Primary Agent:** solution-architect
+**Recommended ACT Agent:** agent-architect
+
+### Decisions
+- Decision 1: [What was decided and why]
+- Decision 2: [What was decided and why]
+
+### Notes
+- Implementation note 1
+- Constraint or dependency to remember
+
+---
+
+## ACT — [timestamp]
+**Primary Agent:** agent-architect
+
+### Progress
+- [x] Created RulesService with search capability
+- [x] Added Tests: 12 passing
+- [ ] SSE transport implementation pending
+
+### Notes
+- Used glob for file discovery (faster than readdir recursion)
+- NestJS module structure: McpModule → RulesModule
+
+---
+
+## EVAL — [timestamp]
+
+### Findings
+- [HIGH] Missing rate limiting on /sse endpoint
+- [MEDIUM] Test coverage at 72%, below 80% target
+
+### Recommendations
+- Add rate limiting middleware
+- Add tests for error cases in RulesService
+```
+
+## Context Strategy by Task Duration
+
+### Short Tasks (< 1 hour, single session)
+
+No special context management needed. Conversation memory is sufficient.
+
+### Medium Tasks (1-4 hours, 1-2 sessions)
+
+```
+1. Write task summary to context.md at start
+2. Update progress at each major milestone
+3. Write completion summary before ending session
+```
+
+### Long Tasks (multi-day, multiple sessions)
+
+```
+1. Create context.md with full plan (PLAN mode)
+2. Create task breakdown in docs/codingbuddy/plan/
+3. Update context.md after each working session
+4. Begin each session by reading context.md
+5. Use git commits as progress markers
+```
+
+## Session Start Protocol
+
+When resuming a task:
+
+```markdown
+## Session Resume Checklist
+
+1. Read context document:
+   - docs/codingbuddy/context.md
+
+2. Check git status:
+   - What was last committed?
+   - Any uncommitted changes?
+
+3. Check task list:
+   - What was pending at last session?
+
+4. Verify environment:
+   - Tests still passing?
+   - Build still working?
+
+5. Update context with session start note
+```
+
+## Session End Protocol
+
+Before ending a session:
+
+```markdown
+## Session End Checklist
+
+1. Commit all completed work with descriptive message
+
+2. Update context document:
+   - Mark completed items
+   - Note pending items
+   - Capture any decisions made
+
+3. Note exact stopping point:
+   - What file/function was being edited?
+   - What was the next intended step?
+
+4. If blocked: note the blocker clearly
+
+5. Push to remote if collaborating
+```
+
+## Information Priority
+
+When deciding what to preserve, use this priority:
+
+```
+MUST preserve:
+- Architecture decisions (hard to reconstruct)
+- Why (not what) was done — rationale survives code changes
+- Open questions and blockers
+- External dependencies and constraints
+
+SHOULD preserve:
+- Files created and their purpose
+- Test coverage status
+- Performance baseline numbers
+
+CAN skip:
+- Step-by-step implementation details (read the code)
+- Obvious decisions (no need to record "used async/await")
+- Information available in git history
+```
+
+## Context Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|-------------|---------|-----|
+| Relying on conversation memory | Compaction erases it | Write to file |
+| Writing everything verbatim | Context file becomes noise | Summarize decisions, not steps |
+| Never reading context file | Repeating work already done | Read at session start |
+| Single monolithic context file | Hard to navigate | Split by phase (PLAN/ACT/EVAL) |
+| Context file not in git | Lost if repo changes machines | Always commit context docs |
+
+## notepad.md (OMC Alternative)
+
+For sessions not using codingbuddy's parse_mode, use OMC's notepad:
+
+```
+notepad_write_priority: Critical info always loaded at session start
+notepad_write_working:  Session-specific notes (auto-pruned after 7 days)
+notepad_write_manual:   Permanent notes that must survive
+```
+
+**When to use notepad vs context.md:**
+- `context.md` → For codingbuddy PLAN/ACT/EVAL workflow
+- notepad → For ad-hoc sessions without formal workflow
+
+## Quick Reference
+
+```
+Context File Locations:
+──────────────────────
+docs/codingbuddy/context.md    → Primary context (PLAN/ACT/EVAL)
+docs/codingbuddy/plan/         → Detailed plan documents
+~/.claude/notepad.md            → Global session notes (OMC)
+
+Update Context via MCP:
+──────────────────────
+update_context(mode, decisions[], notes[], progress[], status)
+
+Read Context via MCP:
+──────────────────────
+read_context(verbosity: minimal|standard|full)
+```