From 04b5a8aac71f36b03a8369824708340f6e3ae6cc Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Wed, 14 Jan 2026 16:41:01 -0500 Subject: [PATCH 1/2] docs: update documentation structure and workflow references Reorganize documentation to reflect current repository state: - Move docs/quickstart.md to docs/README.md for better discoverability - Delete redundant docs/index.md - Update CLAUDE.md with accurate repository structure - Document new codebase-agent.yml workflow and automation scripts - Update all cross-references to new doc paths in README and PRESENTATION Changes to CLAUDE.md: - Add .github/scripts/codebase_agent/ automation module - Document all 5 GitHub Actions workflows (was 2) - Update docs/ structure to reflect standalone patterns approach - Remove references to deleted architecture.md, tutorial.md, api-reference.md Co-Authored-By: Claude Sonnet 4.5 --- CLAUDE.md | 45 ++++++++++++++++++-------- PRESENTATION-ambient-code-reference.md | 2 +- README.md | 4 +-- docs/{quickstart.md => README.md} | 0 docs/index.md | 40 ----------------------- 5 files changed, 35 insertions(+), 56 deletions(-) rename docs/{quickstart.md => README.md} (100%) delete mode 100644 docs/index.md diff --git a/CLAUDE.md b/CLAUDE.md index 7f6b60c..ec489ad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -36,10 +36,9 @@ This is a **GitHub template repository** demonstrating AI-assisted development b **Documentation** (`docs/`): -- Quickstart guides for AI-assisted development -- Architecture pattern references -- Tutorial outlines for implementing agentic workflows -- API design patterns +- Quickstart guide (README.md) for AI-assisted development +- Standalone pattern documentation (patterns/) +- ADR scaffolding (adr/) **Codebase Agent Configuration** (`.claude/`): @@ -49,9 +48,16 @@ This is a **GitHub template repository** demonstrating AI-assisted development b **CI/CD** (`.github/workflows/`): -- Documentation validation workflows -- Markdown linting -- Mermaid diagram validation +- Codebase Agent automation (codebase-agent.yml) +- Documentation validation (docs-validation.yml) +- Security scanning (security.yml) +- Documentation deployment (deploy-docs.yml) + +**Automation Scripts** (`.github/scripts/codebase_agent/`): + +- Python module for CBA workflow execution +- AI client with Vertex AI and Anthropic API support +- GitHub event parsing and PR automation ### Working Application Demo @@ -131,10 +137,9 @@ markdownlint docs/**/*.md README.md CLAUDE.md --fix **Core docs** (`docs/`): -1. `quickstart.md` - 5-minute introduction to AI-assisted development -2. `architecture.md` - Common architecture patterns for agentic workflows -3. `tutorial.md` - Step-by-step guide for implementing patterns -4. `api-reference.md` - API design patterns for AI-assisted apps +1. `README.md` - 5-minute quickstart for AI-assisted development patterns +2. `patterns/` - Individual pattern documentation (standalone, independently adoptable) +3. `adr/` - Architecture Decision Records scaffolding (template only) ### Mermaid Diagrams (CRITICAL) @@ -276,17 +281,31 @@ Focus on "why" rather than "what". **Workflows**: -1. **`.github/workflows/docs-validation.yml`** (Documentation) +1. **`.github/workflows/codebase-agent.yml`** (Codebase Agent) + - Issue-to-PR automation + - PR review automation + - Triggered by: @cba mentions, cba-review/cba-help labels + - Supports both Anthropic API and Vertex AI authentication + +2. **`.github/workflows/docs-validation.yml`** (Documentation) - Markdown linting (markdownlint) - Mermaid diagram validation - Link checking - Triggers: on docs/** changes, PRs -2. **`.github/workflows/ci.yml`** (General CI) +3. **`.github/workflows/ci.yml`** (General CI) - Code example linting (if any) - Documentation build test - Triggers: on push, PR +4. **`.github/workflows/deploy-docs.yml`** (Documentation Deployment) + - Deploys documentation to GitHub Pages + - Triggers: on main branch push + +5. **`.github/workflows/security.yml`** (Security Scanning) + - Security vulnerability scanning + - Triggers: on push, PR, schedule + ### Dependabot **File**: `.github/dependabot.yml` diff --git a/PRESENTATION-ambient-code-reference.md b/PRESENTATION-ambient-code-reference.md index 1c3c0a5..65dab1a 100644 --- a/PRESENTATION-ambient-code-reference.md +++ b/PRESENTATION-ambient-code-reference.md @@ -638,7 +638,7 @@ cd reference # Explore the patterns cat .claude/agents/codebase-agent.md cat .claude/context/architecture.md -cat docs/quickstart.md +cat docs/README.md # Copy to your project #commented out on purpose cp -r .claude /path/to/your/project/ diff --git a/README.md b/README.md index 9ef2437..ef804a3 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ AI-assisted development patterns. Each pattern is standalone - adopt what you ne ## Getting Started -See [Quickstart](docs/quickstart.md) for pattern overview and adoption guidance. +See [Quickstart](docs/README.md) for pattern overview and adoption guidance. ## Development Setup @@ -40,7 +40,7 @@ npm install -g markdownlint-cli @mermaid-js/mermaid-cli ```text reference/ ├── docs/ -│ ├── quickstart.md # Pattern overview and adoption path +│ ├── README.md # Quickstart guide │ └── patterns/ # Individual pattern docs ├── .claude/ # Example CBA configuration ├── PRESENTATION-ambient-code-reference.md # 9-feature overview diff --git a/docs/quickstart.md b/docs/README.md similarity index 100% rename from docs/quickstart.md rename to docs/README.md diff --git a/docs/index.md b/docs/index.md deleted file mode 100644 index 2e38567..0000000 --- a/docs/index.md +++ /dev/null @@ -1,40 +0,0 @@ -# Ambient Code Reference - -AI-assisted development patterns for engineering teams. - ---- - -## Patterns - -### Agent Behavior - -| Pattern | What It Does | -|---------|--------------| -| [Codebase Agent](patterns/codebase-agent.md) | Define AI behavior and guardrails | -| [Self-Review Reflection](patterns/self-review-reflection.md) | Agent reviews own work before presenting | -| [Autonomous Quality](patterns/autonomous-quality-enforcement.md) | Run linters/tests automatically | -| [Multi-Agent Review](patterns/multi-agent-code-review.md) | Parallel specialized reviews | - -### GHA Automation - -| Pattern | Trigger | -|---------|---------| -| [Issue-to-PR](patterns/issue-to-pr.md) | Issue labeled `cba` | -| [PR Auto-Review](patterns/pr-auto-review.md) | Pull request opened | -| [Dependabot Auto-Merge](patterns/dependabot-auto-merge.md) | Dependabot PR | -| [Stale Issues](patterns/stale-issues.md) | Weekly schedule | - -### Foundation - -| Pattern | What It Does | -|---------|--------------| -| [Security Patterns](patterns/security-patterns.md) | Validate at boundaries | -| [Testing Patterns](patterns/testing-patterns.md) | Unit, integration, E2E pyramid | - ---- - -## Links - -- **Quickstart**: [quickstart.md](quickstart.md) -- **Demo App**: [demo-fastapi](https://github.com/ambient-code/demo-fastapi) -- **Presentation**: [PRESENTATION-ambient-code-reference.md](https://github.com/ambient-code/reference/blob/main/PRESENTATION-ambient-code-reference.md) From cb75c1862a3c22da36612530db7c81a3ea6b1c0d Mon Sep 17 00:00:00 2001 From: Jeremy Eder Date: Wed, 14 Jan 2026 21:56:51 -0500 Subject: [PATCH 2/2] fix: update CI to check for new documentation structure Update ci.yml to check for docs/README.md instead of docs/quickstart.md and remove check for deleted docs/index.md. Add check for docs/adr/. Co-Authored-By: Claude Sonnet 4.5 --- .github/workflows/ci.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index cbfcfcd..d4c6dee 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -18,6 +18,6 @@ jobs: run: | # Verify patterns documentation exists test -d docs/patterns || { echo "Error: docs/patterns/ missing"; exit 1; } - test -f docs/quickstart.md || { echo "Error: docs/quickstart.md missing"; exit 1; } - test -f docs/index.md || { echo "Error: docs/index.md missing"; exit 1; } + test -f docs/README.md || { echo "Error: docs/README.md missing"; exit 1; } + test -d docs/adr || { echo "Error: docs/adr/ missing"; exit 1; } echo "All required documentation files present"