@zigrivers/scaffold 2.1.2 → 2.38.0

package/knowledge/core/adr-craft.md

@@ -4,6 +4,8 @@ description: Writing effective architecture decision records including technolog
 topics: [adr, architecture-decisions, tech-stack, decision-documentation, technology-selection]
 ---
 
+## Summary
+
 ## What Warrants an ADR
 
 An Architecture Decision Record captures a decision that is architecturally significant — one that affects the system's structure, non-functional characteristics, dependencies, interfaces, or construction techniques. Not every decision needs an ADR. The litmus test: would a new team member need to know why this choice was made to work effectively?
@@ -61,6 +63,8 @@ Each technology choice should compare the top 2-3 realistic options, state the s
 - Temporary decisions (experiment with X for a spike) — not architectural
 - Decisions that have no realistic alternatives — if there's only one viable option, just use it
 
+## Deep Guidance
+
 ## ADR Structure
 
 ### Title
@@ -251,6 +255,55 @@ Technology decisions often cluster. Rather than 20 individual ADRs for each pack
 
 Each group ADR can cover multiple decisions if they are tightly coupled and were evaluated together.
 
+## Example ADR
+
+The following shows a complete ADR following the structure and quality guidelines above:
+
+```markdown
+# ADR-003: Use PostgreSQL for Persistent Storage
+
+## Status
+Accepted
+
+## Context
+The application (per PRD Section 2) manages financial transaction data with strict
+consistency requirements, flexible metadata per transaction type, and projected volume
+of 500K transactions/month within the first year. The team has strong SQL experience
+and the project is AI-built, favoring well-documented technologies.
+
+## Decision
+We will use PostgreSQL 16 for all persistent storage in this application.
+
+## Alternatives Considered
+
+### SQLite
+- **Why considered:** Zero operational overhead, embedded, excellent for small-to-medium
+  read-heavy workloads.
+- **Why rejected:** Single-writer limitation is incompatible with concurrent transaction
+  processing. No built-in network access for multi-instance deployment.
+
+### MongoDB
+- **Why considered:** Flexible schema matches variable transaction metadata. Strong
+  horizontal scaling story.
+- **Why rejected:** Weaker ACID guarantees for multi-document transactions. Team has
+  limited MongoDB experience. Less well-represented in AI training data than PostgreSQL,
+  increasing hallucination risk for query patterns.
+
+## Consequences
+
+### Benefits
+- JSONB columns provide flexible metadata storage without sacrificing relational integrity
+- Strong ACID compliance for financial transaction consistency
+- Most widely adopted open-source RDBMS — extensive AI training data coverage
+- Rich ecosystem: pg_stat_statements for monitoring, pg_dump for backups, mature ORMs
+
+### Costs and Risks
+- Operational overhead: requires backup configuration, connection pooling, and monitoring
+- JSONB queries are less performant than MongoDB's native document queries for deeply
+  nested structures
+- Schema migrations require planning for zero-downtime deployments
+```
+
 ## Common Pitfalls
 
 **Recording decisions without alternatives.** An ADR that says "We'll use React" without mentioning Vue or Svelte provides no insight into the decision process. When a new team member asks "why not Vue?", there's no answer. Fix: always document at least one alternative and why it was rejected.
@@ -279,3 +332,7 @@ An ADR set is likely complete when:
 - **The ADR set covers all layers.** Backend, frontend (if applicable), database, infrastructure, developer tooling, deployment, testing, and security all have decisions recorded.
 - **Status is current.** No accepted ADRs that actually describe how things used to work. Superseded and deprecated ADRs are marked.
 - **Cross-references are complete.** Related ADRs link to each other. ADRs link to the requirements they address.
+
+## See Also
+
+- [tech-stack-selection](../core/tech-stack-selection.md) — Technology selection as ADRs

package/knowledge/core/ai-memory-management.md

@@ -0,0 +1,246 @@
+---
+name: ai-memory-management
+description: AI memory and context management patterns for Claude Code projects including modular rules, MCP memory servers, lifecycle hooks, decision logging, and external context integration
+topics: [ai-memory, claude-code, claude-rules, mcp-servers, lifecycle-hooks, context-management, session-handoff, decision-logging, mcp-knowledge-graph, context7]
+---
+
+# AI Memory Management
+
+AI coding agents forget everything between sessions. Memory management is the practice of making that forgetting graceful — ensuring the right context is available at the right time without drowning the agent in irrelevant information. This knowledge covers the full spectrum from lightweight rule files to persistent memory servers.
+
+## Summary
+
+### The Memory Hierarchy
+
+AI memory operates in layers, each with different persistence and token cost:
+
+| Layer | Persistence | Token Cost | Examples |
+|-------|------------|------------|----------|
+| **Context window** | Current session only | High (1:1) | Files read, conversation history |
+| **CLAUDE.md / rules** | Permanent (git-tracked) | Medium (loaded at start) | Conventions, commands, workflow |
+| **Auto-memory** | Cross-session (local) | Low (loaded on demand) | User preferences, project patterns |
+| **MCP memory server** | Cross-session (structured) | Low (queried on demand) | Decisions, lessons, error patterns |
+| **External docs** | Always current | Zero until queried | Library APIs, framework docs |
+
+### Core Principle: Signal Over Volume
+
+ETH Zurich research (2026) found that dumping context into AI sessions hurts more than it helps — 3% performance decrease with 20% cost increase for LLM-generated context files. The key insight: **only store what cannot be derived from the code itself.** Custom build commands, project-specific conventions, decision rationale, and team agreements are high-signal. Code patterns, file structure, and API shapes are low-signal (the agent can read the code).
+
+### The Three-Tier Memory Stack
+
+**Tier 1 — Modular Rules** (`.claude/rules/`): Path-scoped convention files loaded automatically based on what files the agent is working with. Zero manual effort after setup. Keeps CLAUDE.md lean.
+
+**Tier 2 — Persistent Memory** (MCP server + hooks): Structured cross-session memory that captures decisions, lessons, and error patterns automatically via lifecycle hooks. Survives session boundaries.
+
+**Tier 3 — External Context** (library doc servers): Version-specific documentation for project dependencies, queried on demand. Prevents API hallucination.
+
+## Deep Guidance
+
+### Tier 1: Modular Rules
+
+#### `.claude/rules/` Architecture
+
+Claude Code loads rule files from `.claude/rules/` based on path-scoping defined in YAML frontmatter. This replaces the pattern of stuffing everything into CLAUDE.md.
+
+**File structure:**
+```
+.claude/
+  rules/
+    code-style.md          # Always active — naming, formatting, imports
+    testing.md             # Active when working in test files
+    api-endpoints.md       # Active when working in API route files
+    database.md            # Active when working with schema/migration files
+    frontend.md            # Active when working in UI component files
+    memory-hygiene.md      # Always active — what to save/not save in memory
+```
+
+**Rule file format:**
+```markdown
+---
+description: TypeScript naming and import conventions
+globs: ["src/**/*.ts", "src/**/*.tsx"]
+---
+
+- Use camelCase for variables/functions, PascalCase for types/classes
+- Import order: external packages, then internal modules, then relative imports
+- Prefer named exports over default exports
+```
+
+**Key principles:**
+- Each rule file targets a specific concern and file pattern
+- Rules activate only when the agent works on matching files — no wasted tokens
+- Total rule content across all files should stay under 500 lines
+- Rules state what to do differently from defaults — don't restate obvious conventions
+- Extract rules from existing docs (coding-standards.md, tech-stack.md, git-workflow.md) rather than writing from scratch
+
+#### CLAUDE.md Optimization
+
+After creating rules, CLAUDE.md should use the pointer pattern:
+
+```markdown
+## Coding Conventions
+See `docs/coding-standards.md` for full reference. Key rules in `.claude/rules/code-style.md`.
+```
+
+This replaces inline convention blocks, keeping CLAUDE.md under 200 lines (the empirically-validated adherence threshold).
+
+### Tier 2: Persistent Memory
+
+#### MCP Memory Servers
+
+**Recommended: MCP Knowledge Graph** (`@modelcontextprotocol/server-memory`)
+- Official MCP server from the Model Context Protocol project
+- Stores entities, relations, and observations in a local JSON file
+- Zero setup: `npx -y @modelcontextprotocol/server-memory`
+- Entities persist across sessions — decisions, patterns, project facts
+- Best for: All projects (stable, official, zero dependencies beyond Node)
+
+**Alternative: Custom MCP server**
+- If the user has a preferred MCP memory server already installed, use it
+- The key requirement is that it exposes MCP tools for storing and retrieving structured memory
+- Examples from the ecosystem: Engram (if installed), hmem (if installed), ContextVault
+
+**Configuration pattern** (`.claude/settings.json`):
+```json
+{
+  "mcpServers": {
+    "memory": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-memory"],
+      "env": {
+        "MEMORY_FILE_PATH": ".claude/memory-graph.json"
+      }
+    }
+  }
+}
+```
+
+#### Lifecycle Hooks
+
+Hooks automate memory capture at key session events:
+
+**PreCompact** (highest value) — Triggers before context compression. Logs when compaction occurs for debugging context loss.
+
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      "type": "command",
+      "command": "echo \"$(date '+%Y-%m-%d %H:%M:%S') — Context compacting\" >> .claude/compaction-log.txt",
+      "timeout": 5000
+    }]
+  }
+}
+```
+
+File-logging for compaction events:
+```json
+{
+  "hooks": {
+    "PreCompact": [{
+      "type": "command",
+      "command": "date '+%Y-%m-%d %H:%M' >> .claude/compaction-log.txt && echo 'Context compacted' >> .claude/compaction-log.txt",
+      "timeout": 5000
+    }]
+  }
+}
+```
+
+**Stop** — Triggers when a session ends. Good for capturing session-level summaries.
+
+**PreToolUse** — Triggers before tool calls. Can log decisions about file modifications. Use sparingly — high frequency means high overhead.
+
+**Hook selection guidance:**
+- Start with PreCompact only — it captures the most value with least noise
+- Hook commands must produce a side effect (write to MCP server, append to file) — echoing to `/dev/null` provides zero value
+- Add Stop if sessions frequently end with unrecorded decisions
+- Avoid PreToolUse unless you have a specific logging need — it fires constantly
+
+#### Decision Logging
+
+Decisions are the highest-value memory type because they cannot be derived from code. A decision log captures what was chosen, what was rejected, and why.
+
+**Structure:**
+```
+docs/decisions/
+  DECISIONS.md          # Index of all decisions
+  001-auth-strategy.md  # Individual decision records
+  002-database-choice.md
+```
+
+**Decision entry format:**
+```markdown
+## DEC-001: JWT over session cookies for auth
+
+**Date:** 2026-03-27
+**Context:** Need stateless auth for API-first architecture
+**Decision:** Use JWT with short-lived access tokens + refresh tokens
+**Rejected:** Session cookies (requires sticky sessions), OAuth-only (too complex for MVP)
+**Consequences:** Need token refresh logic in frontend, need secure token storage
+```
+
+This complements ADRs (which cover architecture-level decisions) by capturing day-to-day implementation decisions that would otherwise be lost between sessions.
+
+#### Session Handoff Patterns
+
+When context hits limits, structured handoff preserves continuity:
+
+1. **Before compaction**: Save current task state, open questions, and recent decisions
+2. **After compaction**: Claude Code auto-reloads CLAUDE.md and auto-memory, but loses working context
+3. **Recovery**: Agent reads decision log and memory server to reconstruct working state
+
+The `/compact` command is the natural handoff point. A PreCompact hook that saves session state ensures nothing critical is lost.
+
+### Tier 3: External Context
+
+#### Library Documentation Servers
+
+AI agents hallucinate APIs — they generate plausible but incorrect function signatures, especially for rapidly-evolving libraries. External doc servers solve this by providing current, version-specific documentation on demand.
+
+**Context7** (by Upstash) — Most popular, fetches current library docs via MCP
+- Covers major frameworks (React, Next.js, Vue, Angular, etc.)
+- Free tier: 1,000 requests/month
+- Caution: had a security vulnerability (patched) — review before enabling
+
+**Nia** (by Nozomio) — Indexes codebases + 3,000+ pre-indexed packages
+- Cross-session context persistence
+- Deep research agent for complex questions
+- Y Combinator backed, more comprehensive than Context7
+
+**Docfork** — 9,000+ libraries, MIT license
+- "Cabinets" for project-specific documentation isolation
+- Self-hostable
+
+**Configuration pattern:**
+```json
+{
+  "mcpServers": {
+    "context7": {
+      "command": "npx",
+      "args": ["-y", "@upstash/context7-mcp@latest"]
+    }
+  }
+}
+```
+
+**When to enable:** Projects with 3+ external dependencies, especially rapidly-evolving frameworks (React, Next.js, Svelte). Skip for standard library-only projects or well-established stable APIs.
+
+### Anti-Patterns
+
+| Anti-Pattern | Why It Fails | Instead |
+|-------------|-------------|---------|
+| Dumping entire codebase into context | Drowns signal in noise, costs tokens | Let the agent read files on demand |
+| Storing code patterns in memory | Duplicates what's in the code; goes stale | Store decisions and rationale only |
+| Huge CLAUDE.md (500+ lines) | Adherence drops sharply above 200 lines | Use .claude/rules/ for specifics |
+| Memory without structure | Unstructured notes become unsearchable noise | Use categories (decision, lesson, error) |
+| Capturing everything | Token cost with diminishing returns | Capture what can't be derived from code |
+| Multiple overlapping memory tools | Conflicting context, duplicated entries | Pick one MCP server, use it consistently |
+
+### Integration with Beads
+
+When Beads is configured, memory complements task tracking:
+- **Beads** tracks what work to do (tasks, dependencies, status)
+- **Memory** tracks how to do work better (patterns, decisions, lessons)
+- Decision log entries can reference Beads task IDs for traceability
+- `tasks/lessons.md` remains the cross-session learning file; MCP memory adds structured queryability
+- Don't duplicate: if a pattern is in `tasks/lessons.md`, don't also store it in the MCP server

package/knowledge/core/api-design.md

@@ -4,6 +4,8 @@ description: API design principles for REST, GraphQL, and inter-service communic
 topics: [api, rest, graphql, endpoints, contracts, versioning, error-handling, authentication]
 ---
 
+## Summary
+
 ## API-First Development
 
 Design the API contract before writing implementation code. The contract defines what the API does; the implementation fulfills that contract. This order matters because:
@@ -81,6 +83,8 @@ POST /api/v1/order-submissions       # Create an "order submission" resource
 POST /api/v1/password-resets         # Create a "password reset" resource
 ```
 
+## Deep Guidance
+
 ### HTTP Methods
 
 | Method | Semantics | Idempotent | Safe |
@@ -499,3 +503,7 @@ Design APIs so that transient failures can be safely retried:
 **Missing rate limiting.** No protection against abusive or buggy clients sending excessive requests. Fix: implement rate limiting on all public endpoints. Return 429 with `Retry-After` header.
 
 **Ignoring CORS.** Frontend can't call the API because CORS headers are missing. Fix: configure CORS at API design time. Be specific about allowed origins — don't use `*` in production.
+
+## See Also
+
+- [testing-strategy](../core/testing-strategy.md) — Contract testing and API test patterns

package/knowledge/core/automated-review-tooling.md

@@ -0,0 +1,203 @@
+---
+name: automated-review-tooling
+description: Patterns for setting up automated PR code review using AI models (Codex, Gemini) via local CLI, including dual-model review, reconciliation, and CI integration
+topics: [code-review, automation, codex, gemini, pull-requests, ci-cd, review-tooling]
+---
+
+# Automated Review Tooling
+
+Automated PR review leverages AI models to provide consistent, thorough code review without manual reviewer bottlenecks. This knowledge covers the local CLI approach (no GitHub Actions), dual-model review patterns, and integration with the PR workflow.
+
+## Summary
+
+### Architecture: Local CLI Review
+
+The scaffold approach uses local CLI review rather than GitHub Actions:
+- **No CI secrets required** — models run locally via CLI tools
+- **Dual-model review** — run Codex and Gemini (when available) for independent perspectives
+- **Agent-managed loop** — Claude orchestrates the review-fix cycle locally
+
+Components:
+- `AGENTS.md` — reviewer instructions with project-specific rules
+- `docs/review-standards.md` — severity definitions (P0-P3) and criteria
+- `scripts/cli-pr-review.sh` — dual-model review script
+- `scripts/await-pr-review.sh` — polling script for external bot mode
+
+### Review Severity Levels
+
+Consistent with the pipeline's review step severity:
+- **P0 (blocking)** — must fix before merge (security, data loss, broken functionality)
+- **P1 (important)** — should fix before merge (bugs, missing tests, performance)
+- **P2 (suggestion)** — consider fixing (style, naming, documentation)
+- **P3 (nit)** — optional (personal preference, minor optimization)
+
+### Dual-Model Review Pattern
+
+When both Codex CLI and Gemini CLI are available:
+1. Run both reviewers independently on the PR diff
+2. Collect findings from each
+3. Reconcile: consensus findings get higher confidence
+4. Disagreements are flagged for the implementing agent to resolve
+
+### Integration with PR Workflow
+
+The review step integrates into the standard PR flow:
+1. Agent creates PR
+2. Agent runs `scripts/cli-pr-review.sh` (or review runs automatically)
+3. Review findings are posted as PR comments or written to a local file
+4. Agent addresses P0/P1 findings, pushes fixes
+5. Re-review until no P0/P1 findings remain
+6. PR is ready for merge
+
+## Deep Guidance
+
+### AGENTS.md Structure
+
+The `AGENTS.md` file provides reviewer instructions:
+
+```markdown
+# Code Review Instructions
+
+## Project Context
+[Brief description of what this project does]
+
+## Review Focus Areas
+- Security: [project-specific security concerns]
+- Performance: [known hot paths or constraints]
+- Testing: [coverage requirements, test patterns]
+
+## Coding Standards Reference
+See docs/coding-standards.md for:
+- Naming conventions
+- Error handling patterns
+- Logging standards
+
+## Known Patterns
+[Project-specific patterns reviewers should enforce]
+
+## Out of Scope
+[Things reviewers should NOT flag]
+```
+
+### CLI Review Script Pattern
+
+The `cli-pr-review.sh` script follows this structure:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+# 1. Get the PR diff
+diff=$(gh pr diff "$PR_NUMBER")
+
+# 2. Run Codex review (if available)
+if command -v codex &>/dev/null; then
+  codex_findings=$(echo "$diff" | codex review --context AGENTS.md)
+fi
+
+# 3. Run Gemini review (if available)
+if command -v gemini &>/dev/null; then
+  gemini_findings=$(echo "$diff" | gemini review --context AGENTS.md)
+fi
+
+# 4. Reconcile findings
+# - Findings from both models: HIGH confidence
+# - Findings from one model: MEDIUM confidence
+# - Contradictions: flagged for human review
+```
+
+### Review Standards Document
+
+`docs/review-standards.md` should define:
+- Severity levels with concrete examples per project
+- What constitutes a blocking review (P0/P1 threshold)
+- Auto-approve criteria (when review can be skipped)
+- Review SLA (how long before auto-approve kicks in)
+
+### Fallback When Models Unavailable
+
+If neither Codex nor Gemini CLI is available:
+1. Claude performs an enhanced self-review of the diff
+2. Focus on the AGENTS.md review criteria
+3. Apply the same severity classification
+4. Document that the review was single-model
+
+### Updating Review Standards Over Time
+
+As the project evolves:
+- Add new review focus areas when new patterns emerge
+- Remove rules that linters now enforce automatically
+- Update AGENTS.md when architecture changes
+- Track false-positive rates and adjust thresholds
+
+### Review Finding Reconciliation
+
+When running dual-model review, reconcile findings systematically:
+
+```
+Finding Classification:
+┌─────────────────┬──────────┬──────────┬───────────────────┐
+│                 │ Codex    │ Gemini   │ Action            │
+├─────────────────┼──────────┼──────────┼───────────────────┤
+│ Same issue      │ Found    │ Found    │ HIGH confidence   │
+│ Unique finding  │ Found    │ -        │ MEDIUM confidence │
+│ Unique finding  │ -        │ Found    │ MEDIUM confidence │
+│ Contradiction   │ Fix X    │ Keep X   │ Flag for agent    │
+└─────────────────┴──────────┴──────────┴───────────────────┘
+```
+
+HIGH confidence findings are always addressed. MEDIUM confidence findings are addressed if P0/P1. Contradictions require the implementing agent to make a judgment call and document the reasoning.
+
+### Security-Focused Review Checklist
+
+Every automated review should check:
+- No secrets or credentials in the diff (API keys, passwords, tokens)
+- No `eval()` or equivalent unsafe operations introduced
+- SQL queries use parameterized queries (no string concatenation)
+- User input is validated before use
+- Authentication/authorization checks are present on new endpoints
+- Dependencies added are from trusted sources with known versions
+
+### Performance Review Patterns
+
+Look for these performance anti-patterns:
+- N+1 queries (loop with individual DB calls)
+- Missing pagination on list endpoints
+- Synchronous operations that should be async
+- Large objects passed by value instead of reference
+- Missing caching for expensive computations
+- Unbounded growth in arrays or maps
+
+### Integration with CLAUDE.md
+
+The workflow-audit step should add review commands to CLAUDE.md:
+
+```markdown
+## Code Review
+| Command | Purpose |
+|---------|---------|
+| `scripts/cli-pr-review.sh <PR#>` | Run dual-model review |
+| `scripts/await-pr-review.sh <PR#>` | Poll for external review |
+```
+
+This ensures agents always know how to trigger reviews without consulting separate docs.
+
+### Common False Positives
+
+Track and suppress recurring false positives:
+- Test files flagged for "hardcoded values" (test fixtures are intentional)
+- Migration files flagged for "raw SQL" (migrations must use raw SQL)
+- Generated files flagged for style issues (generated code has its own conventions)
+
+Add suppressions to AGENTS.md under "Out of Scope" to prevent repeated false findings.
+
+### Review Metrics and Continuous Improvement
+
+Track these metrics over time to improve review quality:
+- **False positive rate** — findings that are dismissed without action
+- **Escape rate** — bugs that reach production despite review
+- **Time to resolve** — average time between finding and fix
+- **Coverage** — percentage of PRs that receive automated review
+- **Model agreement rate** — how often Codex and Gemini agree
+
+Use these metrics to calibrate severity thresholds and update AGENTS.md focus areas.