ambient-code · jeremyeder · Jan 7, 2026 · Jan 7, 2026 · Jan 7, 2026
diff --git a/PRESENTATION-ambient-code-reference.md b/PRESENTATION-ambient-code-reference.md
@@ -29,7 +29,7 @@ This reference repository provides useful patterns you can review / adopt increm
 A pre-configured AI agent definition that knows how to work with your codebase safely and consistently.
 The idea behind a CBA is to use an agent to eventually proxy 100% of the interaction with a codebase through this agent.
 
-**cba = codebase system prompt**
+(cba = codebase system prompt)
 
 ### The Problem It Solves
 
@@ -107,7 +107,7 @@ What's important is that your team has collected and agrees upon the context sin
 
 ### Loading Context On-Demand
 
-Instead of loading everything, you load what's relevant. 
+Instead of loading everything, you load what's relevant.
 
 "Load the security-standards context and help me review this authentication PR"
 
@@ -131,7 +131,7 @@ For relation between elements, load these files into e.g. the local Anthropic Me
 ### Issue-to-PR Overview
 
 A pattern where well-defined GitHub issues can be automatically converted into pull requests by the CBA.
-Example: https://github.com/ambient-code/agentready/pull/242
+Example: <https://github.com/ambient-code/agentready/pull/242>
 
 ### Routine Fix Overhead
 

diff --git a/docs/patterns/codebase-agent.md b/docs/patterns/codebase-agent.md
@@ -4,73 +4,83 @@
 
 ---
 
-## Overview
-
-!!! note "Section Summary"
-    What a CBA is: a markdown file that defines how AI works in your project. Problem it solves: inconsistent AI behavior across developers. Key benefit: every AI interaction follows the same process.
-
----
-
 ## Quick Start
 
-!!! note "Section Summary"
-    Copy-paste the CBA definition from `.claude/agents/codebase-agent.md`. Minimal customization: your linting commands, your test commands. Done in 15 minutes.
+Create `.claude/agents/codebase-agent.md`:
 
+```markdown
+---
+name: codebase-agent
+description: Autonomous codebase operations for [your-project]
 ---
 
-## Agent Definition Structure
-
-### Capability Boundaries
-
-!!! note "Section Summary"
-    What the agent can do autonomously vs what requires human approval. Examples: formatting changes (auto), architecture changes (human approval). How to define your own boundaries.
-
-### Workflow Definitions
+# Codebase Agent
 
-!!! note "Section Summary"
-    Step-by-step processes for common tasks: issue-to-PR, code review, refactoring. Template workflows provided. How to customize for your process.
+## Quality Gates (run before presenting code)
+1. Lint: `npm run lint`
+2. Test: `npm test`
+3. Fix failures before showing code
 
-### Quality Gates
+## Safety Rules
+- NEVER commit directly to main
+- ALWAYS create feature branches
+- ASK before breaking changes
+```
 
-!!! note "Section Summary"
-    Linting, testing, and review requirements. Which tools to run, in what order. What constitutes a passing gate. Error handling.
+---
 
-### Safety Guardrails
+## Agent Structure
 
-!!! note "Section Summary"
-    When to stop and ask for human input. Risk categories: low/medium/high. Examples of each. How to configure alert thresholds.
+| Section | Purpose | Example |
+|---------|---------|---------|
+| **Capability Boundaries** | What agent can do autonomously | Formatting: auto. Architecture: human approval |
+| **Workflow Definitions** | Step-by-step processes | Issue→PR, code review steps |
+| **Quality Gates** | Tools to run, in order | `black . && isort . && pytest` |
+| **Safety Guardrails** | When to stop and ask | >10 files changed, security code, DB schema |
 
 ---
 
 ## Autonomy Levels
 
-!!! note "Section Summary"
-    Level 1 (Conservative): PR creation only, wait for human approval. Level 2 (Moderate): Auto-merge for low-risk changes. Level 3 (Aggressive): Auto-deploy after tests pass. How to graduate between levels.
+| Level | Behavior | Use When |
+|-------|----------|----------|
+| **1: Conservative** | Create PRs only, wait for human approval | Starting out, high-risk projects |
+| **2: Moderate** | Auto-merge docs/deps/lint fixes after CI passes | Established trust, good test coverage |
+| **3: Aggressive** | Auto-deploy after tests pass | Mature codebase, comprehensive CI |
 
----
+Start at Level 1. Graduate as you build trust.
 
-## Memory System Integration
+---
 
-!!! note "Section Summary"
-    How CBA uses context files from `.claude/context/`. Loading context on-demand. When to reference which context file.
+## Memory System
 
----
+Context files in `.claude/context/` provide persistent knowledge:
 
-## Real-World Examples
+```text
+.claude/
+├── agents/
+│   └── codebase-agent.md
+└── context/
+    ├── architecture.md      # Code structure patterns
+    ├── security-standards.md
+    └── testing-patterns.md
+```
 
-!!! note "Section Summary"
-    CBA configurations for different stacks: Python/FastAPI, TypeScript/Express, Go. What's different, what's the same.
+Reference in your agent: "Load `.claude/context/architecture.md` for code placement decisions."
 
 ---
 
 ## Troubleshooting
 
-!!! note "Section Summary"
-    Common issues: agent ignores boundaries, agent is too conservative, agent makes up conventions. Solutions for each.
+| Problem | Fix |
+|---------|-----|
+| Agent ignores boundaries | Make rules explicit: "NEVER delete files without asking" |
+| Agent too conservative | Define allowed autonomous actions explicitly |
+| Agent invents conventions | Provide code examples in context files |
 
 ---
 
 ## Related Patterns
 
-- [Self-Review Reflection](self-review-reflection.md) - Add quality gates to CBA output
-- [Memory System](../getting-started/first-cba.md) - Persistent context across sessions
+- [Self-Review Reflection](self-review-reflection.md)
+- [Autonomous Quality Enforcement](autonomous-quality-enforcement.md)
diff --git a/docs/patterns/dependabot-auto-merge.md b/docs/patterns/dependabot-auto-merge.md
@@ -4,54 +4,90 @@
 
 ---
 
-## Overview
-
-!!! note "Section Summary"
-    When Dependabot creates a PR for a patch version update, auto-merge after CI passes. Keep dependencies current without manual effort. Minor/major updates still require human review.
-
----
-
 ## Quick Start
 
-!!! note "Section Summary"
-    Copy the workflow YAML. No additional secrets needed. Enable Dependabot in your repo. Watch patch updates auto-merge.
+Create `.github/workflows/dependabot-auto-merge.yml`:
+
+```yaml
+name: Dependabot Auto-Merge
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  auto-merge:
+    if: github.actor == 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Fetch metadata
+        id: metadata
+        uses: dependabot/fetch-metadata@v2
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Auto-merge patch updates
+        if: steps.metadata.outputs.update-type == 'version-update:semver-patch'
+        run: gh pr merge --auto --squash "$PR_URL"
+        env:
+          PR_URL: ${{ github.event.pull_request.html_url }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+Enable Dependabot in `.github/dependabot.yml`. Set up branch protection requiring CI to pass.
 
 ---
 
 ## How It Works
 
 ```mermaid
 flowchart TD
-    A[Dependabot PR] --> B{Patch Version?}
-    B -->|No| C[Require Human Review]
-    B -->|Yes| D{CI Passes?}
-    D -->|No| C
-    D -->|Yes| E[Auto-Merge]
+    A[Dependabot PR] --> B{Author is dependabot?}
+    B -->|No| C[Normal Review]
+    B -->|Yes| D[Fetch Metadata]
+    D --> E{Patch Version?}
+    E -->|No| C
+    E -->|Yes| F{CI Passes?}
+    F -->|No| C
+    F -->|Yes| G[Auto-Merge]
 ```
 
 ---
 
-## Safety Conditions
+## Update Types
 
-!!! note "Section Summary"
-    Only auto-merge when ALL conditions met: author is dependabot[bot], update is patch version, all CI checks pass, no merge conflicts. Why each condition matters.
+| Type | Value | Risk | Default Action |
+|------|-------|------|----------------|
+| Patch | `version-update:semver-patch` | Low | Auto-merge |
+| Minor | `version-update:semver-minor` | Medium | Human review |
+| Major | `version-update:semver-major` | High | Human review |
 
 ---
 
-## Workflow YAML
+## Options
 
-!!! note "Section Summary"
-    Complete workflow file. Dependabot metadata action. Conditional auto-merge. Squash and delete branch.
+| Option | Add to workflow |
+|--------|-----------------|
+| **Also merge minor** | Add step with `if: steps.metadata.outputs.update-type == 'version-update:semver-minor'` |
+| **Only dev deps** | Add `&& steps.metadata.outputs.dependency-type == 'direct:development'` |
+| **Exclude packages** | Check `steps.metadata.outputs.dependency-names` doesn't contain package |
 
 ---
 
-## Customization
+## Troubleshooting
 
-!!! note "Section Summary"
-    Auto-merge minor versions too. Exclude specific packages. Custom merge strategy. Notifications.
+| Problem | Fix |
+|---------|-----|
+| Auto-merge not triggering | Use `pull_request_target` event for fork PRs |
+| Permission denied | Add `contents: write` permission |
+| Doesn't wait for CI | Enable branch protection with required status checks |
 
 ---
 
 ## Related Patterns
 
-- [Stale Issue Management](stale-issues.md) - Another proactive cleanup pattern
+- [Stale Issue Management](stale-issues.md)
diff --git a/docs/patterns/index.md b/docs/patterns/index.md
@@ -1,58 +1,50 @@
 # Patterns Index
 
-**All AI-assisted development patterns in one place.**
+Each pattern is standalone—adopt what you need.
 
 ---
 
-## Overview
+## Agent Behavior
 
-!!! note "Section Summary"
-    Patterns are organized into three categories: Agent Behavior (how AI works), GHA Automation (proactive CI/CD), and Foundation (enabling patterns). Each pattern is standalone - adopt what you need.
+| Pattern | Effort | Impact |
+|---------|--------|--------|
+| [Codebase Agent](codebase-agent.md) | Medium | High |
+| [Self-Review Reflection](self-review-reflection.md) | Low | High |
+| [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) | Medium | High |
+| [Multi-Agent Code Review](multi-agent-code-review.md) | High | Very High |
 
 ---
 
-## Agent Behavior Patterns
+## GHA Automation
 
-How AI agents behave during development.
-
-| Pattern | Effort | Impact | Description |
-|---------|--------|--------|-------------|
-| [Codebase Agent](codebase-agent.md) | Medium | High | Single source of truth for AI behavior |
-| [Self-Review Reflection](self-review-reflection.md) | Low | High | Agent reviews own work before presenting |
-| [Autonomous Quality Enforcement](autonomous-quality-enforcement.md) | Medium | High | Validate code before delivery |
-| [Multi-Agent Code Review](multi-agent-code-review.md) | High | Very High | Parallel specialized reviews |
-
----
-
-## GHA Automation Patterns
-
-Proactive CI/CD workflows that reduce toil.
-
-| Pattern | Trigger | Effort | Impact |
-|---------|---------|--------|--------|
-| [Issue-to-PR](issue-to-pr.md) | `issues.opened` | High | Very High |
-| [PR Auto-Review](pr-auto-review.md) | `pull_request` | Medium | High |
-| [Dependabot Auto-Merge](dependabot-auto-merge.md) | `pull_request` | Low | Medium |
-| [Stale Issue Management](stale-issues.md) | `schedule` | Low | Medium |
+| Pattern | Trigger | Effort |
+|---------|---------|--------|
+| [Issue-to-PR](issue-to-pr.md) | `issues.opened` | High |
+| [PR Auto-Review](pr-auto-review.md) | `pull_request` | Medium |
+| [Dependabot Auto-Merge](dependabot-auto-merge.md) | `pull_request` | Low |
+| [Stale Issue Management](stale-issues.md) | `schedule` | Low |
 
 ---
 
-## Foundation Patterns
+## Foundation
 
-Patterns that make AI more effective.
-
-| Pattern | Purpose | Effort | Impact |
-|---------|---------|--------|--------|
-| [Layered Architecture](layered-architecture.md) | Code structure AI can reason about | Low | Medium |
-| [Security Patterns](security-patterns.md) | Practical protection | Low | Medium |
-| [Testing Patterns](testing-patterns.md) | Test pyramid approach | Medium | High |
+| Pattern | Purpose |
+|---------|---------|
+| [Layered Architecture](layered-architecture.md) | Code structure AI can reason about |
+| [Security Patterns](security-patterns.md) | Validate at boundaries |
+| [Testing Patterns](testing-patterns.md) | Test pyramid approach |
 
 ---
 
-## Adoption Matrix
+## Start Here
 
-!!! note "Section Summary"
-    Decision tree for which patterns to adopt based on your situation. Pain point → recommended pattern mapping. Effort/impact quadrant visualization.
+| Pain Point | Pattern |
+|------------|---------|
+| AI gives inconsistent answers | [Codebase Agent](codebase-agent.md) |
+| AI misses obvious bugs | [Self-Review Reflection](self-review-reflection.md) |
+| PRs take forever to create | [Issue-to-PR](issue-to-pr.md) |
+| Code reviews are bottleneck | [PR Auto-Review](pr-auto-review.md) |
+| Dependency updates pile up | [Dependabot Auto-Merge](dependabot-auto-merge.md) |
 
 ---
 
@@ -61,24 +53,29 @@ Patterns that make AI more effective.
 ```mermaid
 flowchart TD
     CBA[Codebase Agent] --> SR[Self-Review]
-    CBA --> MEM[Memory System]
     CBA --> AQE[Autonomous Quality]
-
     AQE --> ITP[Issue-to-PR]
     SR --> ITP
-
     ITP --> PAR[PR Auto-Review]
-
     LA[Layered Architecture] -.-> CBA
     SEC[Security Patterns] -.-> CBA
     TEST[Testing Patterns] -.-> AQE
 ```
 
-Solid arrows: recommended order. Dashed arrows: optional dependencies.
-
 ---
 
 ## Quick Reference
 
-!!! note "Section Summary"
-    One-page cheat sheet of all patterns with key commands and file paths. Printable format.
+| File | Location |
+|------|----------|
+| CBA definition | `.claude/agents/codebase-agent.md` |
+| Context files | `.claude/context/*.md` |
+| Issue-to-PR | `.github/workflows/issue-to-pr.yml` |
+| PR Review | `.github/workflows/pr-review.yml` |
+| Dependabot | `.github/workflows/dependabot-auto-merge.yml` |
+| Stale | `.github/workflows/stale.yml` |
+
+| Secret | Used By |
+|--------|---------|
+| `ANTHROPIC_API_KEY` | Issue-to-PR, PR Review |
+| `GITHUB_TOKEN` | All workflows (auto-provided) |