codingbuddy-rules 4.3.0 → 4.4.0

package/.ai-rules/skills/prompt-engineering/SKILL.md

@@ -0,0 +1,318 @@
+---
+name: prompt-engineering
+description: Use when writing prompts for AI tools, optimizing agent system prompts, or designing AI-readable instructions. Covers prompt structure, meta-prompting, chain-of-thought, and tool-specific optimization.
+---
+
+# Prompt Engineering
+
+## Overview
+
+A prompt is an API contract with an AI system. Precision matters. Ambiguous prompts produce inconsistent results; clear prompts produce consistent, predictable behavior.
+
+**Core principle:** Prompts are executable specifications. Write them like you write tests: with clear inputs, expected behavior, and success criteria.
+
+**Iron Law:**
+```
+TEST YOUR PROMPT WITH AT LEAST 3 DIFFERENT INPUTS BEFORE USING IN PRODUCTION
+One input is anecdote. Three is pattern. Ten is confidence.
+```
+
+## When to Use
+
+- Writing system prompts for codingbuddy agents
+- Creating CLAUDE.md / .cursorrules instructions
+- Designing tool descriptions for MCP servers
+- Optimizing prompts that produce inconsistent results
+- Building prompt chains for multi-step workflows
+
+## Prompt Anatomy
+
+Every effective prompt has these components:
+
+```
+┌─────────────────────────────────────────┐
+│ ROLE        Who/what is the AI?         │
+│ CONTEXT     What situation are we in?   │
+│ TASK        What specifically to do?    │
+│ CONSTRAINTS What rules must be obeyed?  │
+│ FORMAT      How to structure output?    │
+│ EXAMPLES    Show, don't just tell       │
+└─────────────────────────────────────────┘
+```
+
+Not every prompt needs all components, but most production prompts need most of them.
+
+## Prompt Patterns
+
+### Pattern 1: Role + Task (Basic)
+
+```
+You are a [specific role].
+
+Your task: [specific action] for [specific context].
+```
+
+**Example:**
+```
+You are a TypeScript code reviewer specializing in security.
+
+Your task: Review the authentication module below for OWASP Top 10 vulnerabilities.
+Output a list of findings ordered by severity (Critical → High → Medium → Low).
+```
+
+### Pattern 2: Chain-of-Thought (Complex Reasoning)
+
+Force step-by-step reasoning before conclusions:
+
+```
+Before answering, think through:
+1. [First consideration]
+2. [Second consideration]
+3. [Third consideration]
+
+Then provide your conclusion.
+```
+
+**Example:**
+```
+Before suggesting a fix, think through:
+1. What is the root cause of this bug?
+2. What are the possible fix approaches?
+3. What are the trade-offs of each approach?
+4. Which approach has the least risk?
+
+Then provide your recommendation with rationale.
+```
+
+### Pattern 3: Few-Shot (Examples)
+
+Show the AI what good output looks like:
+
+```
+[Task description]
+
+Examples:
+
+Input: [example input 1]
+Output: [example output 1]
+
+Input: [example input 2]
+Output: [example output 2]
+
+Now complete:
+Input: [actual input]
+Output:
+```
+
+**Example (agent expertise):**
+```
+Format agent expertise as specific, actionable skills.
+
+Examples:
+
+Input: security
+Output: "OWASP Top 10 Vulnerability Assessment", "JWT Authentication Design", "SQL Injection Prevention"
+
+Input: databases
+Output: "PostgreSQL Query Optimization", "Zero-Downtime Schema Migrations", "Connection Pool Tuning"
+
+Now complete:
+Input: frontend
+Output:
+```
+
+### Pattern 4: Constraint-First
+
+Lead with what NOT to do (especially useful for restrictive behaviors):
+
+```
+NEVER [prohibited action].
+ALWAYS [required action].
+If [edge case], then [specific handling].
+
+Your task: [task description]
+```
+
+**Example:**
+```
+NEVER include markdown formatting in your output — plain text only.
+ALWAYS include the file path in references (e.g., src/app.ts:42).
+If you are uncertain, say "I'm not sure" rather than guessing.
+
+Your task: Analyze the build error below and identify the root cause.
+```
+
+### Pattern 5: Meta-Prompting
+
+Prompt the AI to generate or improve prompts:
+
+```
+I need a prompt for [purpose].
+
+The prompt should:
+- [Requirement 1]
+- [Requirement 2]
+- [Requirement 3]
+
+Generate 3 prompt variations ranked from most to least structured.
+```
+
+## System Prompt Design (codingbuddy Agents)
+
+Agent system prompts follow a specific structure:
+
+```markdown
+# [Agent Display Name]
+
+You are a [role] specialist focused on [narrow domain].
+
+## Your Expertise
+
+You excel at:
+- [Specific skill 1 — concrete, not vague]
+- [Specific skill 2]
+- [Specific skill 3]
+
+## Your Approach
+
+When activated:
+1. [First action — what you always do first]
+2. [Analysis approach]
+3. [Output structure]
+
+## What You Do NOT Handle
+
+Redirect to appropriate specialists for:
+- [Out-of-scope 1] → use [other-agent-name]
+- [Out-of-scope 2] → use [other-agent-name]
+
+## Output Format
+
+Structure all responses as:
+### Findings
+[Severity: Critical/High/Medium/Low] — [Description]
+
+### Recommendations
+[Prioritized list]
+```
+
+## MCP Tool Description Design
+
+Tool descriptions are prompts read by AI to decide when and how to use a tool:
+
+```typescript
+{
+  name: 'search_rules',
+  // ❌ Bad: vague
+  description: 'Search rules',
+
+  // ✅ Good: specific use case + when to use
+  description: 'Search AI coding rules by keyword or topic. Use this when looking for specific guidelines about coding practices, TDD, security, or workflow modes. Returns matching rules with their content.',
+
+  inputSchema: {
+    properties: {
+      query: {
+        type: 'string',
+        // ❌ Bad: no guidance
+        description: 'Query string',
+
+        // ✅ Good: what makes a good query
+        description: 'Search term such as "TDD", "security", "TypeScript strict", or a question like "how to handle migrations"',
+      }
+    }
+  }
+}
+```
+
+## Prompt Testing
+
+### Test Matrix
+
+For each prompt, test these dimensions:
+
+| Dimension | Test Cases |
+|-----------|-----------|
+| Happy path | Ideal input, expected output |
+| Edge cases | Empty input, very long input, unusual characters |
+| Adversarial | Input designed to break the constraint |
+| Ambiguous | Input that could be interpreted multiple ways |
+
+### Evaluation Criteria
+
+```markdown
+## Prompt Evaluation Rubric
+
+**Accuracy:** Does output match expected behavior? (1-5)
+**Consistency:** Same input → same output across runs? (1-5)
+**Format compliance:** Does output match requested format? (1-5)
+**Boundary respect:** Does it honor constraints? (1-5)
+**Efficiency:** Is it unnecessarily verbose? (1-5)
+
+Total: 20 points. Target: ≥ 16 for production use.
+```
+
+## Tool-Specific Optimization
+
+### Claude Code (CLAUDE.md)
+
+```markdown
+## Best practices for Claude Code instructions:
+
+- Use ## headers to organize sections
+- Bold critical rules: **NEVER do X**
+- Use code blocks for exact command examples
+- Include trigger conditions: "When user types PLAN..."
+- Reference other files: "See .claude/rules/tool-priority.md"
+```
+
+### Cursor (.cursorrules)
+
+```markdown
+## Best practices for Cursor rules:
+
+- One rule per line for reliable parsing
+- Start each rule with the trigger: "When writing TypeScript..."
+- Avoid multi-paragraph rules (Cursor truncates)
+- Use concrete examples, not abstract principles
+```
+
+### GitHub Copilot (.github/copilot-instructions.md)
+
+```markdown
+## Best practices for Copilot instructions:
+
+- Lead with task-oriented rules
+- Examples are more effective than descriptions
+- Copilot follows "do X" more reliably than "don't do Y"
+- Keep total instructions under 8000 characters
+```
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Vague task ("be helpful") | Specific task ("list 3 alternatives with trade-offs") |
+| No format specification | Add explicit format: "Respond as JSON: {field: value}" |
+| Contradictory constraints | Test for conflicts before deploying |
+| No examples for complex tasks | Add 2-3 few-shot examples |
+| Testing with one input | Test with at least 3 diverse inputs |
+| Long monolithic prompt | Break into focused sections with headers |
+
+## Quick Reference
+
+```
+Prompt Length Guidelines:
+──────────────────────────
+Simple instruction    → 50-100 tokens
+Structured prompt     → 100-500 tokens
+Agent system prompt   → 500-2000 tokens
+Complex workflow      → 2000-4000 tokens
+(>4000 = consider splitting into sub-prompts)
+
+Reliability Ranking (most to least reliable):
+──────────────────────────────────────────────
+1. Explicit format + examples (highest)
+2. Explicit format, no examples
+3. Implicit format with examples
+4. Implicit format, no examples (lowest)
+```

package/.ai-rules/skills/rule-authoring/SKILL.md

@@ -0,0 +1,273 @@
+---
+name: rule-authoring
+description: Use when writing AI coding rules for codingbuddy that must work consistently across multiple AI tools (Cursor, Claude Code, Codex, GitHub Copilot, Amazon Q, Kiro). Covers rule clarity, trigger design, and multi-tool compatibility.
+---
+
+# Rule Authoring
+
+## Overview
+
+AI coding rules are instructions that shape how AI assistants behave. Poorly written rules are ignored, misinterpreted, or cause inconsistent behavior across tools.
+
+**Core principle:** Rules must be unambiguous, actionable, and testable. If an AI assistant can interpret a rule two different ways, it will choose the wrong one at the worst moment.
+
+**Iron Law:**
+```
+EVERY RULE MUST HAVE A TESTABLE "DID IT WORK?" CRITERION
+```
+
+## When to Use
+
+- Writing new rules for `.ai-rules/rules/`
+- Updating existing rules that produce inconsistent behavior
+- Adapting rules for a new AI tool (cursor, codex, q, kiro)
+- Auditing rules for ambiguity or overlap
+
+## Rule Quality Criteria
+
+A good rule is:
+
+| Quality | Bad Example | Good Example |
+|---------|-------------|--------------|
+| **Specific** | "Write good code" | "Functions must have a single return type" |
+| **Actionable** | "Be careful with auth" | "All endpoints must check authentication before executing" |
+| **Testable** | "Follow best practices" | "Test coverage must be ≥ 80% for new files" |
+| **Bounded** | "Always use TypeScript" | "Use TypeScript strict mode in all .ts files" |
+| **Non-overlapping** | Two rules about the same thing | One rule per concern |
+
+## Rule Structure
+
+### Core Rule Format
+
+```markdown
+## [Rule Category]: [Rule Name]
+
+**When:** [Trigger condition — when does this rule apply?]
+
+**Do:** [Specific action to take]
+
+**Don't:** [Specific anti-pattern to avoid]
+
+**Example:**
+\`\`\`typescript
+// ✅ Good
+function getUser(id: string): Promise<User>
+
+// ❌ Bad
+function getUser(id: any): any
+\`\`\`
+
+**Why:** [One-sentence rationale]
+```
+
+### Rule File Structure
+
+```markdown
+# [Category Name]
+
+Brief description of what rules in this file govern.
+
+## Rules
+
+### Rule 1: [Name]
+...
+
+### Rule 2: [Name]
+...
+
+## Rationale
+
+Why these rules exist for this project.
+
+## Exceptions
+
+Cases where these rules do not apply (keep this list short).
+```
+
+## Writing Process
+
+### Phase 1: Identify the Rule Need
+
+```
+1. What behavior is inconsistent or incorrect?
+   → "AI assistants sometimes use 'any' type in TypeScript"
+
+2. What is the desired behavior?
+   → "All variables must have explicit types"
+
+3. What is the trigger condition?
+   → "When writing TypeScript code"
+
+4. Can an AI verify compliance?
+   → "Yes: TypeScript compiler will error on 'any' in strict mode"
+
+5. Is there already a rule covering this?
+   → Check existing rules in .ai-rules/rules/
+```
+
+### Phase 2: Write the Rule
+
+**Template:**
+```markdown
+### [Rule Name]
+
+**When:** [Specific trigger condition]
+
+**Do:** [Concrete action in imperative mood]
+
+**Don't:** [Specific anti-pattern]
+
+**Check:** [How to verify the rule was followed]
+```
+
+**Good examples:**
+```markdown
+### No `any` Type
+
+**When:** Writing TypeScript code
+
+**Do:** Always specify explicit types for function parameters and return values
+
+**Don't:** Use `any` type — use `unknown` for truly unknown types, then narrow
+
+**Check:** TypeScript compiler passes with `noImplicitAny: true` in tsconfig
+
+---
+
+### Test Before Implement (TDD)
+
+**When:** Implementing a new function or feature
+
+**Do:** Write the failing test first, then write minimal implementation to pass it
+
+**Don't:** Write implementation first and add tests after
+
+**Check:** Running tests shows RED (failure) before GREEN (pass)
+```
+
+### Phase 3: Test Multi-Tool Compatibility
+
+Different AI tools parse rules differently. Test your rules with each tool:
+
+```
+Compatibility checklist for each new rule:
+
+Claude Code:
+- [ ] Rule triggers correctly from CLAUDE.md or custom-instructions.md
+- [ ] Rule doesn't conflict with default Claude behavior
+
+Cursor:
+- [ ] Rule works in .cursorrules or .cursor/rules/
+- [ ] Pattern matching works as expected
+
+GitHub Copilot / Codex:
+- [ ] Rule understandable from .github/copilot-instructions.md
+- [ ] No Copilot-specific syntax required
+
+Amazon Q:
+- [ ] Compatible with .q/rules/ format
+
+Kiro:
+- [ ] Compatible with .kiro/ format
+```
+
+### Phase 4: Anti-Ambiguity Review
+
+Read each rule and ask: "Could this be interpreted two different ways?"
+
+**Ambiguity red flags:**
+```
+❌ "appropriate" → What's appropriate? Define it.
+❌ "when necessary" → When is that? Specify the condition.
+❌ "best practices" → Which ones? List them.
+❌ "avoid" → How strongly? Use "never" or "prefer X over Y".
+❌ "clean code" → What does clean mean? Measurable criteria only.
+```
+
+**Ambiguity fixes:**
+```
+❌ "Use appropriate error handling"
+✅ "Catch specific error types, never catch Exception or Error base class"
+
+❌ "Write clean functions"
+✅ "Functions must be ≤ 30 lines and have a single return type"
+
+❌ "When necessary, add comments"
+✅ "Add comments only for non-obvious logic. Self-documenting code needs no comments."
+```
+
+## Rule Categories
+
+| Category | File | Covers |
+|----------|------|--------|
+| Core workflow | `rules/core.md` | PLAN/ACT/EVAL modes, TDD |
+| Project | `rules/project.md` | Tech stack, architecture |
+| Augmented coding | `rules/augmented-coding.md` | Code quality, testing |
+
+## Adapter-Specific Formatting
+
+### Claude Code (`adapters/claude-code.md`)
+
+```markdown
+## Claude Code Specific Rules
+
+- Use `parse_mode` for PLAN/ACT/EVAL detection
+- Follow `dispatch_agents` pattern for parallel agents
+- Context persists via `docs/codingbuddy/context.md`
+```
+
+### Cursor (`adapters/cursor.md`)
+
+```markdown
+## Cursor-Specific Rules
+
+Rules in `.cursorrules` are parsed line-by-line.
+Keep rules to one line each for Cursor compatibility.
+```
+
+### Codex (`adapters/codex.md`)
+
+```markdown
+## GitHub Copilot / Codex Rules
+
+Place in `.github/copilot-instructions.md`.
+Copilot prefers explicit examples over abstract rules.
+```
+
+## Rule Maintenance
+
+### Auditing Existing Rules
+
+```bash
+# Find rules that haven't been updated recently
+git log --since="6 months ago" -- packages/rules/.ai-rules/rules/
+
+# Find duplicate rule concepts
+grep -h "^###" packages/rules/.ai-rules/rules/*.md | sort | uniq -d
+```
+
+**Quarterly audit questions:**
+1. Is this rule still relevant to our current stack?
+2. Is this rule being followed consistently?
+3. Does this rule conflict with any new tool defaults?
+4. Are there new patterns that need new rules?
+
+## Quick Reference
+
+```
+Rule Strength Vocabulary:
+─────────────────────────
+MUST / ALWAYS     → Required, no exceptions
+SHOULD / PREFER   → Default behavior, exceptions allowed
+AVOID / PREFER NOT → Discouraged, explain if used
+NEVER / MUST NOT  → Prohibited
+```
+
+## Red Flags — STOP
+
+| Thought | Reality |
+|---------|---------|
+| "This rule is obvious" | Write it anyway — different AI tools need explicit guidance |
+| "The existing rule covers this" | Check carefully — overlap causes conflicts |
+| "Rules don't need testing" | Test with each target AI tool |
+| "Abstract rules are more flexible" | Abstract rules are ignored or misapplied |