cognitive-core 0.2.1 → 0.2.2

package/playbooks/compound-engineering/performance-review.json

@@ -0,0 +1,54 @@
+{
+  "name": "performance-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 4,
+  "applicability": {
+    "situations": [
+      "Reviewing code that touches database queries, loops, caching, or I/O-intensive paths",
+      "Evaluating scalability of new features at 10x/100x/1000x current data volumes",
+      "Checking for production-observable performance regressions"
+    ],
+    "triggers": [
+      "performance review",
+      "N+1 query",
+      "slow query",
+      "memory leak",
+      "pagination",
+      "caching"
+    ],
+    "antiPatterns": [
+      "Micro-optimizations in cold paths (startup, migrations, admin tools, one-time initialization)",
+      "Premature caching suggestions without evidence of actual slowness",
+      "Theoretical scale issues in MVP/prototype code",
+      "Style-based performance opinions (for vs forEach, Map vs plain object)"
+    ],
+    "domains": ["code-review", "performance", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Read code through the lens of 'what happens when this runs 10,000 times' or 'when the table has a million rows'. Focus on measurable, production-observable problems — not theoretical micro-optimizations. Project performance at 10x, 100x, and 1000x current volumes.",
+    "tactics": [
+      "N+1 queries: flag database queries inside loops that should be batched or eager-loaded; count loop iterations against expected data size",
+      "Unbounded memory: flag loading entire tables without pagination, caches without eviction policies, string concatenation in loops, large object allocations",
+      "Missing pagination: flag endpoints returning all results without limit/offset/cursor/streaming",
+      "Hot-path allocations: flag object creation, regex compilation, or expensive computation inside loops or per-request paths",
+      "Blocking I/O in async: flag synchronous file reads, blocking HTTP calls, CPU-intensive computation on the event loop",
+      "Algorithmic complexity: flag O(n^2) or worse without justification; verify all database queries use appropriate indexes",
+      "Performance benchmarks: API responses under 200ms for standard operations, bundle size increases under 5KB per feature, background jobs process in batches",
+      "Confidence calibration: HIGH (0.80+) when impact is provable from code (N+1 clearly in loop, unbounded query on large table); MODERATE (0.60-0.79) when pattern present but impact depends on unconfirmed data size; suppress below 0.60"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Each finding identifies a specific code path with measurable impact at expected scale",
+      "N+1 findings show the loop and the query inside it",
+      "No micro-optimization findings on cold paths"
+    ],
+    "failureIndicators": [
+      "Finding is speculative optimization without evidence of hot path",
+      "Caching recommendation without evidence of repeated expensive computation",
+      "Flagging cold-path code (startup, migrations) for performance"
+    ]
+  }
+}

package/playbooks/compound-engineering/plan-adversarial-review.json

@@ -0,0 +1,56 @@
+{
+  "name": "plan-adversarial-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "complex",
+  "estimatedEffort": 5,
+  "applicability": {
+    "situations": [
+      "Reviewing implementation plans or requirement documents before execution",
+      "Stress-testing planning assumptions, premises, and scope decisions",
+      "Catching contradictions, scope creep, and unstated assumptions in plans"
+    ],
+    "triggers": [
+      "review plan",
+      "plan review",
+      "challenge assumptions",
+      "scope review",
+      "requirements review"
+    ],
+    "antiPatterns": [
+      "Implementation style or technology selection choices",
+      "Product strategy or priority preferences",
+      "Security, design, or feasibility concerns (use plan-feasibility-review instead)",
+      "The plan is already in execution — too late for adversarial review"
+    ],
+    "domains": ["planning", "requirements", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Challenge premises before solutions. Surface unstated assumptions. Stress-test decisions for reversal cost. Check for internal contradictions and scope-goal misalignment. Apply three lenses: adversarial (break assumptions), coherence (internal consistency), and scope guardian (right-sized).",
+    "tactics": [
+      "Premise challenging: Is this the right problem? Does the solution match the problem? What if we did nothing? What would make this fail? Surface framing effects that bias toward one solution",
+      "Assumption surfacing: identify environmental assumptions (infrastructure exists, APIs stable), user behavior assumptions (adoption, usage patterns), scale assumptions (data volume, concurrency), temporal assumptions (availability, ordering)",
+      "Decision stress-testing: for each major decision, apply falsification test (what evidence would prove this wrong?), reversal cost (how expensive to change later?), and decision-scope mismatch (is decision bigger/smaller than the problem?)",
+      "Simplification pressure: audit abstractions (how many consumers?), find minimum viable version, apply subtraction test (remove each component — does plan still work?), enforce complexity budget",
+      "Coherence checking: catch contradictions between sections, terminology drift (same concept with different names), forward references to undefined terms, ungrouped requirements spanning multiple concerns",
+      "Scope-goal alignment: flag scope exceeding goals (building more than needed), goals exceeding scope (promising more than plan delivers), new abstractions with one implementation, framework-ahead-of-need, configuration without consumers",
+      "Alternative blindness: check for omitted alternatives, build-vs-use analysis, do-nothing baseline comparison",
+      "Depth calibration: Quick (short docs, <5 requirements) = max 3 findings; Standard = proportional to decision density; Deep (>10 requirements, high-stakes) = multiple passes with assumption chain tracing",
+      "Confidence calibration: HIGH (0.80+) when specific text can be quoted showing gap; MODERATE (0.60-0.79) when gap likely but requires context not in document; suppress below 0.50"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Findings quote specific text from the plan showing the gap or contradiction",
+      "Assumptions surfaced are testable and actionable",
+      "Scope-goal alignment checked with concrete evidence",
+      "No findings that belong to feasibility, security, or design review"
+    ],
+    "failureIndicators": [
+      "Findings are vague concerns without quoting specific plan text",
+      "Assumptions identified are untestable or irrelevant",
+      "Scope opinions based on preference rather than goal alignment",
+      "Contradictions flagged that are reconcilable with charitable reading"
+    ]
+  }
+}

package/playbooks/compound-engineering/plan-feasibility-review.json

@@ -0,0 +1,56 @@
+{
+  "name": "plan-feasibility-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "complex",
+  "estimatedEffort": 5,
+  "applicability": {
+    "situations": [
+      "Evaluating technical feasibility of implementation plans",
+      "Checking product-market fit and strategic alignment of proposed features",
+      "Reviewing plans for security gaps, design completeness, and migration safety"
+    ],
+    "triggers": [
+      "feasibility review",
+      "plan feasibility",
+      "technical review",
+      "can we build this",
+      "is this plan viable"
+    ],
+    "antiPatterns": [
+      "Implementation style choices that don't affect feasibility",
+      "Code organization preferences",
+      "Theoretical scalability without evidence",
+      "Scope or assumption concerns (use plan-adversarial-review instead)"
+    ],
+    "domains": ["planning", "architecture", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Evaluate plans across four dimensions: technical feasibility (can we build it?), product fit (should we build it?), security readiness (is it safe?), and design completeness (is it specified enough?). Each dimension has a distinct lens.",
+    "tactics": [
+      "Technical feasibility: verify plan acknowledges existing code/services/infrastructure; check for architecture conflicts with current stack; validate that referenced file paths and interfaces actually exist; check framework compatibility",
+      "Shadow path tracing: for each feature, trace the happy path, nil/empty input path, error path, and concurrent access path — plans that only cover happy path will fail in implementation",
+      "Migration safety: verify concrete migration path (not 'migrate later'), backward compatibility during rollout, rollback strategy, data volume estimates, and operation ordering",
+      "Product lens: challenge the premise — is this the right problem? What's the actual outcome? What happens if we do nothing? Is there an 80% value at 20% cost alternative? Check goal-requirement alignment (orphan requirements, unserved goals)",
+      "Security lens: inventory attack surfaces (endpoints, data stores, integrations, user inputs), check auth/authz per endpoint, identify sensitive data flows, assess third-party trust boundaries, outline top-3 threat model (most likely, highest impact, most subtle exploit)",
+      "Design completeness: check interaction state coverage (loading, empty, error, success, partial for every interactive element), user flow completeness (entry points, happy path, 2-3 edge cases, exit points), responsive/accessibility considerations",
+      "Dependency analysis: verify external dependencies are available and compatible; identify implicit assumptions about infrastructure, APIs, or services",
+      "Performance feasibility: back-of-envelope math for expected load, data volumes, and response time requirements",
+      "Confidence calibration: HIGH (0.80+) when specific technical constraint blocks the approach; MODERATE (0.60-0.79) when constraint likely but depends on implementation details; suppress below 0.50"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Technical blockers identified with specific evidence (missing API, framework incompatibility)",
+      "Shadow paths traced — plan covers more than just the happy path",
+      "Security attack surfaces inventoried with mitigation gaps flagged",
+      "Product alignment verified — goals trace to requirements"
+    ],
+    "failureIndicators": [
+      "Feasibility concerns are vague without specific technical evidence",
+      "Only happy path evaluated — error/empty/concurrent paths ignored",
+      "Security review is generic OWASP checklist without plan-specific analysis",
+      "Product concerns are preference-based rather than goal-alignment-based"
+    ]
+  }
+}

package/playbooks/compound-engineering/project-standards-review.json

@@ -0,0 +1,52 @@
+{
+  "name": "project-standards-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "simple",
+  "estimatedEffort": 2,
+  "applicability": {
+    "situations": [
+      "Reviewing changes for compliance with the project's own standards (CLAUDE.md, AGENTS.md, contributing guides)",
+      "Enforcing naming conventions, file placement, and configuration rules",
+      "Auditing changes against established project conventions"
+    ],
+    "triggers": [
+      "standards review",
+      "convention check",
+      "CLAUDE.md compliance",
+      "project rules"
+    ],
+    "antiPatterns": [
+      "Rules that don't apply to the changed file type",
+      "Violations already caught by automated linters or CI",
+      "Pre-existing violations in unchanged code",
+      "Generic best practices not documented in the project's standards files",
+      "Opinions about quality of the standards themselves"
+    ],
+    "domains": ["code-review", "standards", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Audit changes against the project's own documented standards. Every finding must cite a specific rule from the standards file AND a specific violation in the diff. Without both, drop the finding.",
+    "tactics": [
+      "Discover standards: read CLAUDE.md, AGENTS.md, and any contributing/convention files in the changed file's ancestor directories",
+      "Match rules to file types: only apply rules relevant to the specific files being changed",
+      "Evidence requirement: for each finding, provide (1) exact quote/section from standards file defining the rule, and (2) specific line(s) in diff violating the rule",
+      "Common violations: missing required frontmatter fields, names not matching directory/file names, wrong reference inclusion mode, shell commands where native tools are required, misplaced files in wrong directories",
+      "Language violations: second-person 'you should' where standards require imperative form, hedge words (might/could/consider) leaving behavior undefined",
+      "Protected artifacts: never flag documented protected paths (docs/, plans/, solutions/) for deletion",
+      "Confidence calibration: HIGH (0.80+) when specific rule quote and specific diff violation are both identifiable; MODERATE (0.60-0.79) when rule exists but applying it requires judgment; suppress below 0.60"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Every finding cites both the rule source and the specific violation",
+      "Only rules from the project's actual standards files are enforced",
+      "No findings about unchanged code or generic best practices"
+    ],
+    "failureIndicators": [
+      "Finding enforces a rule not documented in any standards file",
+      "Finding about pre-existing code that wasn't changed in this diff",
+      "Generic best practice advice without project-specific rule citation"
+    ]
+  }
+}

package/playbooks/compound-engineering/reliability-review.json

@@ -0,0 +1,53 @@
+{
+  "name": "reliability-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 4,
+  "applicability": {
+    "situations": [
+      "Reviewing code with external dependencies, I/O boundaries, or error handling",
+      "Evaluating failure modes, retry logic, and cascading failure paths",
+      "Checking resilience of services that depend on other services"
+    ],
+    "triggers": [
+      "reliability review",
+      "error handling",
+      "retry",
+      "timeout",
+      "circuit breaker",
+      "cascade failure"
+    ],
+    "antiPatterns": [
+      "Flagging internal pure functions that cannot fail (string formatting, math, in-memory transforms)",
+      "Test helper error handling",
+      "Error message formatting choices",
+      "Theoretical cascading failures without traceable evidence"
+    ],
+    "domains": ["code-review", "reliability", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Ask 'what happens when this dependency is down?' for every external call. Think about partial failures, retry storms, and cascading timeouts. Read code by assuming the environment can be hostile.",
+    "tactics": [
+      "Missing error handling on I/O boundaries: flag HTTP calls, database queries, file operations, and message queue interactions without try/catch or error callbacks",
+      "Retry loops without backoff/limits: immediate indefinite retries create retry storms — require exponential backoff and max attempt limits",
+      "Missing timeouts on external calls: HTTP clients, database connections, and RPC without explicit timeouts can hang indefinitely and exhaust connection pools",
+      "Error swallowing: flag catch blocks that ignore errors, silent failures that return misleading defaults, and error handlers that don't log or propagate",
+      "Cascading failure paths: trace how failure in service A causes B to retry aggressively, overloading C; how slow dependencies fill request queues causing health check failures, restarts, and cold-start storms",
+      "Recovery-induced failures: retries creating duplicates, rollbacks leaving orphaned state, circuit breakers preventing legitimate recovery",
+      "Confidence calibration: HIGH (0.80+) when reliability gap is directly visible (HTTP call without timeout, retry without max attempts, catch swallowing error); MODERATE (0.60-0.79) when code lacks protection but framework defaults might handle it; suppress below 0.60"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Each finding points to a specific I/O boundary without protection",
+      "Retry findings show the loop and its missing backoff/limit",
+      "Cascade findings trace the multi-service failure chain"
+    ],
+    "failureIndicators": [
+      "Flagging pure functions or in-memory operations for error handling",
+      "Missing that framework middleware already handles the concern",
+      "Architectural concerns that can't be confirmed from the diff"
+    ]
+  }
+}

package/playbooks/compound-engineering/review-orchestration.json

@@ -0,0 +1,64 @@
+{
+  "name": "review-orchestration",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "complex",
+  "estimatedEffort": 8,
+  "applicability": {
+    "situations": [
+      "Code review before creating a PR",
+      "Reviewing changes after completing a task during iterative implementation",
+      "Structured multi-persona code review for quality assurance"
+    ],
+    "triggers": [
+      "review code",
+      "code review",
+      "check changes",
+      "pre-PR review"
+    ],
+    "antiPatterns": [
+      "Reviewing trivial formatting-only changes",
+      "Reviewing auto-generated code that will be regenerated",
+      "Single-line config changes that don't affect behavior"
+    ],
+    "domains": ["code-review", "quality-assurance", "software-engineering"]
+  },
+  "guidance": {
+    "strategy": "Deploy tiered reviewer personas in parallel, then merge and deduplicate findings. Always-on reviewers run on every review; conditional reviewers are selected based on the diff content.",
+    "tactics": [
+      "Always-on reviewers: correctness (logic bugs), testing (coverage gaps), maintainability (coupling/complexity), project-standards (convention compliance), agent-native (action/context parity), learnings-researcher (institutional knowledge)",
+      "Conditional reviewers selected per-diff: security (auth/injection), performance (N+1/memory), API-contract (breaking changes), data-migrations (schema safety), reliability (error handling), adversarial (edge cases), stack-specific language reviewers",
+      "Each reviewer returns structured findings with severity (P0-P3), confidence (0.0-1.0), and autofix_class (safe_auto/gated_auto/manual/advisory)",
+      "Suppress all findings below 0.60 confidence to prevent noise",
+      "Merge/deduplicate findings by fingerprint: (file + line_bucket +/- 3 lines + normalized_title). On conflict, keep highest severity and strongest confidence",
+      "Route actions by class: safe_auto findings get auto-fixed; gated_auto/manual findings go to human review; advisory findings are informational only",
+      "Maximum 2 rounds of autofix to prevent loops"
+    ],
+    "steps": [
+      "1. Detect scope of changes (files, languages, domains affected)",
+      "2. Discover intent from commit messages, PR description, or task context",
+      "3. Select conditional reviewers based on scope (security for auth files, performance for queries, etc.)",
+      "4. Dispatch all selected reviewers in parallel — each reads the diff independently",
+      "5. Collect structured JSON findings from all reviewers",
+      "6. Merge findings: deduplicate by fingerprint, resolve severity conflicts conservatively",
+      "7. Synthesize final report with verdict: Ready / Ready with fixes / Not ready"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "All P0 findings are genuine breakage traceable to specific code paths",
+      "Line numbers point to exact buggy code, not nearby lines",
+      "Each finding is actionable with a clear fix path",
+      "No false positives from style issues that linters catch",
+      "Deduplication produces no redundant findings"
+    ],
+    "failureIndicators": [
+      "P0 findings that are actually style nits",
+      "False positives exceeding 20% of total findings",
+      "Same issue reported multiple times after deduplication",
+      "Findings that require runtime observation to confirm (not provable from code)",
+      "Protected artifacts (docs, plans, brainstorms) flagged for deletion"
+    ],
+    "rollbackStrategy": "Review findings are advisory — no code changes until human approval (except safe_auto in autofix mode)"
+  }
+}

package/playbooks/compound-engineering/security-review.json

@@ -0,0 +1,54 @@
+{
+  "name": "security-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 4,
+  "applicability": {
+    "situations": [
+      "Reviewing code changes that touch auth, user input, public endpoints, or permissions",
+      "Auditing for exploitable vulnerabilities before deployment",
+      "Systematic OWASP Top 10 compliance checking"
+    ],
+    "triggers": [
+      "security review",
+      "auth",
+      "injection",
+      "XSS",
+      "CSRF",
+      "user input",
+      "public endpoint"
+    ],
+    "antiPatterns": [
+      "Defense-in-depth on already-protected code",
+      "Theoretical attacks requiring physical access",
+      "HTTP vs HTTPS in dev/test configs",
+      "Generic hardening advice without specific exploitable findings"
+    ],
+    "domains": ["code-review", "security", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "Think like an attacker looking for one exploitable path through the code. Trace data from entry point to dangerous sink. Combine targeted attack-path analysis with systematic OWASP Top 10 coverage.",
+    "tactics": [
+      "Injection vectors: trace untrusted input to SQL, XSS, shell commands, template engines, innerHTML/dangerouslySetInnerHTML — flag when no sanitization between entry and sink",
+      "Auth/authz bypasses: check for missing auth middleware, broken ownership checks (user A accessing user B's resources), privilege escalation, CSRF on state-changing endpoints",
+      "Secrets exposure: scan for hardcoded keys/tokens/passwords, sensitive data in error messages or logs, PII in responses without need-to-know filtering",
+      "Insecure deserialization: flag pickle, Marshal, unserialize, JSON.parse of executable content from untrusted sources",
+      "SSRF and path traversal: flag user-controlled URLs or file paths passed to fetch/open without allowlist validation",
+      "Systematic OWASP Top 10 check: input validation on all entry points (req.body, req.params, req.query), SQL parameterization, XSS escaping + CSP headers, auth on all endpoints, encryption for sensitive data at rest and in transit",
+      "Confidence calibration: HIGH (0.80+) when full attack path is traceable from untrusted input to dangerous sink without sanitization; MODERATE (0.60-0.79) when dangerous pattern present but exploitability unconfirmed; suppress below 0.60"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "Each finding traces a complete attack path: untrusted input → specific code path → exploitable outcome",
+      "No false positives from already-protected code or dev-only configs",
+      "OWASP categories systematically checked, not just obvious injection"
+    ],
+    "failureIndicators": [
+      "Finding requires physical access or internal-only network to exploit",
+      "Generic 'could be vulnerable' without tracing specific input to specific sink",
+      "Flagging defense-in-depth that's already behind validated auth"
+    ]
+  }
+}

package/playbooks/compound-engineering/systematic-execution.json

@@ -0,0 +1,64 @@
+{
+  "name": "systematic-execution",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.8,
+  "complexity": "complex",
+  "estimatedEffort": 10,
+  "applicability": {
+    "situations": [
+      "Executing an implementation plan systematically",
+      "Shipping a feature with testing, review, and quality gates",
+      "Multi-unit implementation requiring incremental progress and verification"
+    ],
+    "triggers": [
+      "execute plan",
+      "start work",
+      "implement this",
+      "ship feature"
+    ],
+    "antiPatterns": [
+      "No plan exists — create one first",
+      "Exploratory work where requirements aren't defined",
+      "Hotfix that needs to ship immediately without full process"
+    ],
+    "domains": ["execution", "implementation", "software-engineering"]
+  },
+  "guidance": {
+    "strategy": "Treat the plan as a decision artifact, not an instruction script. Execute implementation units in dependency order, testing continuously, with incremental commits after each logical unit. Simplify after every 2-3 units.",
+    "tactics": [
+      "Read plan's Implementation Units; honor execution posture (test-first, characterization-first) when annotated; check 'Deferred to Implementation' questions before starting",
+      "Strategy selection by scale: inline (1-2 small tasks), serial subagents (3+ with dependencies), parallel subagents (3+ independent), swarm (10+ with coordination)",
+      "Test as you go, not at end: run tests after each significant change; never batch testing to the end",
+      "System-wide test check before marking task done: trace callbacks/middleware/observers two levels out; write integration tests with real objects through full chain; verify failure doesn't leave orphaned state; check if other interfaces expose same behavior",
+      "Incremental commits after each complete logical unit — messages describe complete valuable changes, not WIP",
+      "Simplify after every 2-3 units: review changed files for consolidation opportunities, dead code, naming improvements",
+      "Pattern following discipline: read referenced files from plan before implementing — don't invent new conventions",
+      "Feature completeness first: don't move to next feature until current one ships"
+    ],
+    "steps": [
+      "1. Read plan, clarify any ambiguities, set up environment",
+      "2. Create task tracking for all implementation units",
+      "3. Execute units in dependency order: implement → test → verify → commit",
+      "4. After every 2-3 units, review for simplification opportunities",
+      "5. Run quality checks: tests pass, linting passes, code follows existing patterns",
+      "6. Prepare PR: summary (what/why/decisions), testing notes, post-deploy monitoring plan",
+      "7. Update plan status"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "All implementation units completed and tested",
+      "Tests pass and linting passes",
+      "Code follows existing patterns — no new conventions invented",
+      "Each commit describes a complete valuable change",
+      "PR includes post-deploy monitoring plan with concrete metrics"
+    ],
+    "failureIndicators": [
+      "Tests batched to end and found late-breaking issues",
+      "New conventions invented instead of following existing patterns",
+      "Commits contain WIP or incomplete changes",
+      "Feature moved on before current one fully shipped",
+      "System-wide test check skipped for code with callbacks or error handling"
+    ]
+  }
+}

package/playbooks/compound-engineering/testing-review.json

@@ -0,0 +1,50 @@
+{
+  "name": "testing-review",
+  "curatedBy": "compound-engineering",
+  "confidence": 0.85,
+  "complexity": "moderate",
+  "estimatedEffort": 3,
+  "applicability": {
+    "situations": [
+      "Reviewing test quality and coverage for code changes",
+      "Evaluating whether tests prove code works or provide false confidence",
+      "Checking for untested branches, weak assertions, and missing error paths"
+    ],
+    "triggers": [
+      "code review",
+      "test coverage",
+      "test quality",
+      "missing tests"
+    ],
+    "antiPatterns": [
+      "Reviewing test infrastructure or test framework setup",
+      "Evaluating test performance or execution speed",
+      "Coverage percentage targets without considering test quality"
+    ],
+    "domains": ["code-review", "testing", "quality-assurance"]
+  },
+  "guidance": {
+    "strategy": "For every new branch (if/else/switch/try/catch) in the diff, verify at least one test exercises it. Focus on whether tests prove behavior, not just that code doesn't throw.",
+    "tactics": [
+      "Hunt for: untested branches (new if/else/switch/try/catch), tests that don't assert behavior (only assert 'doesn't throw'), implementation-coupled brittle tests (assert on mocks, test private methods, snapshot internals), missing error path coverage",
+      "Branch coverage discipline: each new branch must have at least one test; trace all paths through the new code",
+      "Behavior assertion rigor: assert specific values not just truthiness; verify both happy path AND sad path",
+      "Check that error paths are tested: catch blocks, fallback branches, error returns should have dedicated tests",
+      "Flag implementation-coupled tests: tests that break when refactoring without behavior change are brittle",
+      "Confidence calibration: HIGH (0.80+) when test gap is provable from diff (new branch, no test); MODERATE (0.60-0.79) when inferred from structure (parser.ts with no parser.test.ts); suppress below 0.60 when coverage may exist in integration tests"
+    ]
+  },
+  "verification": {
+    "successIndicators": [
+      "All new branches have corresponding test cases",
+      "Tests assert actual behavior with specific expected values",
+      "Error paths have dedicated tests, not just happy path",
+      "No implementation-coupled brittleness identified"
+    ],
+    "failureIndicators": [
+      "New branches found without any test coverage",
+      "Tests only assert 'doesn't throw' or truthiness without checking values",
+      "Error handling code has no test exercising the error path"
+    ]
+  }
+}

package/src/atlas.ts

@@ -9,6 +9,15 @@ import type {
 import type { KnowledgeMatch } from './types/knowledge.js';
 import { createDefaultConfig } from './types/index.js';
 import { MemorySystem, createMemorySystem, type TeamExperience } from './memory/index.js';
+import {
+  loadCuratedPlaybooks as loadCuratedPlaybooksFn,
+  BUNDLED_SEED_PACK_DIR,
+} from './memory/curated-loader.js';
+import {
+  resolvePlaybookSource,
+  sourceStateKey,
+  type SourceState,
+} from './memory/source-resolver.js';
 import {
   UnifiedLearningPipeline,
   createUnifiedPipeline,
@@ -271,6 +280,9 @@ export class Atlas {
 
     // Initialize playbook-based components if playbooks are available
     if (this.memory.playbooks) {
+      // Load curated playbooks (bundled seed pack + additional dirs)
+      await this.loadCuratedPlaybooks();
+
       this.skillLibrary = createSkillLibrary(
         this.memory.playbooks,
         this.config.skillLibrary
@@ -290,6 +302,90 @@ export class Atlas {
     }
   }
 
+  /**
+   * Load curated playbooks from bundled seed pack, additional directories,
+   * and resolved sources (local paths or git repos).
+   * Called during init() when curatedPlaybooks config is enabled.
+   */
+  private async loadCuratedPlaybooks(): Promise<void> {
+    const cfg = this.config.curatedPlaybooks;
+    const recreate = cfg.recreateOnInit;
+
+    // Load bundled seed pack (shipped with cognitive-core)
+    if (cfg.loadBundledSeedPack) {
+      const loadOpts = recreate
+        ? { recreate: true, sourceId: 'bundled' }
+        : { sourceId: 'bundled' };
+      await loadCuratedPlaybooksFn(
+        BUNDLED_SEED_PACK_DIR,
+        this.memory.playbooks,
+        loadOpts,
+      );
+    }
+
+    // Load from additional directories (backward compat)
+    for (const dir of cfg.additionalDirs) {
+      const loadOpts = recreate
+        ? { recreate: true, sourceId: dir }
+        : { sourceId: dir };
+      await loadCuratedPlaybooksFn(dir, this.memory.playbooks, loadOpts);
+    }
+
+    // Resolve and load from sources (local paths + git repos)
+    if (cfg.sources.length > 0) {
+      const cacheDir = join(this.config.storage.baseDir, cfg.cache.dir);
+      for (const source of cfg.sources) {
+        await this.loadFromSource(source, cacheDir, recreate);
+      }
+    }
+  }
+
+  /**
+   * Resolve a single source (local or git) and load its playbooks.
+   */
+  private async loadFromSource(
+    source: string,
+    cacheDir: string,
+    recreate: boolean,
+  ): Promise<void> {
+    const cfg = this.config.curatedPlaybooks;
+
+    const resolved = await resolvePlaybookSource(source, {
+      cacheDir,
+      maxAgeMs: cfg.cache.maxAgeMs,
+      forceUpdate: recreate,
+      getSourceState: (s) =>
+        this.persistence.getSystemState<SourceState>(sourceStateKey(s)),
+      setSourceState: (s, state) =>
+        this.persistence.setSystemState(sourceStateKey(s), state),
+    });
+
+    if (!resolved) return;
+
+    // For git sources: skip loading if SHA hasn't changed and we're not recreating
+    // (playbooks are already in the library from a previous init).
+    // For local paths: always load (the loader handles dedup via getByName).
+    if (resolved.isGit && !resolved.updated && !recreate) return;
+
+    const loadOpts = recreate
+      ? { recreate: true, sourceId: resolved.sourceId }
+      : { sourceId: resolved.sourceId };
+
+    const result = await loadCuratedPlaybooksFn(
+      resolved.playbookDir,
+      this.memory.playbooks,
+      loadOpts,
+    );
+
+    // Update source state with playbook count
+    const stateKey = sourceStateKey(source);
+    const prevState = this.persistence.getSystemState<SourceState>(stateKey);
+    if (prevState) {
+      prevState.playbookCount = result.loaded;
+      this.persistence.setSystemState(stateKey, prevState);
+    }
+  }
+
   /**
    * Set the LLM provider for solving (deprecated)
    * @deprecated Use setAgentManager() with backends for real execution