A GitHub template demonstrating AI-assisted development best practices using a buffet approach - adopt features independently, no forced linear path.
This template provides pure infrastructure and patterns (NO application code). Bring your own application and apply these practices:
- Dual Documentation System: Every topic in standard (developer-focused) + Terry (accessible) versions with side-by-side comparison
- Codebase Agent Configuration: AI agent setup for issue-to-PR automation, code reviews, maintenance workflows
- CI/CD Patterns: GitHub Actions workflows for linting, testing, security scanning, documentation validation
- Mermaid Diagram Validation: Automated syntax checking prevents broken architecture diagrams
- Asciinema Tutorials: Auto-rebuilt workflow demonstrations (setup, first feature, agent workflow)
- Quickstart: 10-minute setup guide (Terry version)
- Architecture: Template structure and design patterns (Terry version)
- Tutorial: Build your first feature (Terry version)
- Development Workflow: Local testing and validation (Terry version)
- Deployment: Containerization patterns (Terry version)
- Contributing: How to contribute (Terry version)
- Codebase Agent: Issue-to-PR automation, code review (Terry version)
- Context Modules: Modular knowledge (architecture, security, testing)
- Commands: Slash commands for common workflows
scripts/setup.sh- One-command template setup (<10 minutes)scripts/validate-mermaid.sh- Diagram syntax validationscripts/check-doc-pairs.sh- Verify Terry versions existscripts/lint-all.sh- Run all linters (markdown, shell scripts)
Click the "Use this template" button above to create your repository.
git clone <your-repo-url>
cd <your-repo-name>
./scripts/setup.shCompletes in under 10 minutes.
# Check documentation pairs exist
./scripts/check-doc-pairs.sh
# Validate diagrams
./scripts/validate-mermaid.sh
# View comparison webpage
open docs/comparison/index.html # macOS
# or
xdg-open docs/comparison/index.html # Linux- Documentation: See docs/ for all guides
- Agent Config: See .claude/ for AI assistant setup
- Tutorials: See docs/tutorials/ for workflow demos
- Adoption Guides: See docs/adoption/ for independent feature usage
You don't need to adopt everything. Each feature works independently:
Just want better documentation? → Dual Documentation Guide
Just want AI agent automation? → Agent Configuration Guide
Just want CI/CD patterns? → CI/CD Patterns Guide
Want to understand the full approach? → Architecture Overview
See the difference between standard and Terry documentation:
open docs/comparison/index.htmlSide-by-side view of:
- Standard: Technical, concise, assumes domain knowledge
- Terry: Accessible, explanatory, jargon-free
This repository contains zero application code. It's a template of patterns and configurations for AI-assisted development.
What's included: Workflows, documentation, agent config, scripts What's NOT included: FastAPI apps, databases, business logic
Every documentation topic exists in two versions:
- Standard (
docs/{topic}.md): For experienced developers - Terry (
docs/{topic}-terry.md): For broader audiences, plain language
Features are modular. Adopt one without requiring others:
- Copy
.claude/to existing project → Agent config works standalone - Copy
docs/*-terry.mdpattern → Dual docs work standalone - Copy
.github/workflows/validate-docs.yml→ CI/CD works standalone
CI/CD prevents common errors:
- Mermaid diagrams validate before merge (no syntax errors)
- Documentation pairs checked (no missing Terry versions)
- Security scans prevent secrets and application code creep
- Asciinema demos auto-rebuild (always current)
.
├── .github/
│ ├── workflows/ # CI/CD automation
│ └── ISSUE_TEMPLATE/ # Issue templates
├── .claude/
│ ├── agents/ # Agent personality definitions
│ ├── context/ # Modular knowledge modules
│ └── commands/ # Slash command definitions
├── docs/
│ ├── *.md # Standard documentation
│ ├── *-terry.md # Terry (accessible) versions
│ ├── diagrams/ # Mermaid architecture diagrams
│ ├── tutorials/ # Asciinema workflow demos
│ ├── comparison/ # Side-by-side doc viewer
│ ├── adoption/ # Independent feature guides
│ └── adr/ # Architecture decision records (template)
├── scripts/
│ ├── setup.sh # One-command setup
│ ├── validate-mermaid.sh # Diagram validation
│ ├── check-doc-pairs.sh # Doc pair verification
│ └── lint-all.sh # Linting suite
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
└── LICENSE # MIT License
Minimal:
- Git 2.30+
- Bash (for scripts)
For Full Experience:
- Node.js 18+ (for mermaid-cli, markdownlint)
- GitHub account (for template usage)
Optional:
- Asciinema (for re-recording tutorials)
- Podman/Docker (for containerization examples)
See CONTRIBUTING.md for guidelines.
Key Points:
- All documentation requires standard + Terry versions
- Mermaid diagrams must validate with
mmdcbefore commit - Follow docs/STYLE_GUIDE.md for writing style
- No Red Hat branding, no "Amber" terminology (use "Codebase Agent" or "CBA")
MIT License - Use freely in your projects.
Codebase Agent (CBA): AI assistant configured for development workflows Terry Documentation: Accessible, jargon-free documentation style Buffet Approach: Independent feature adoption without forced dependencies
- Issues: Use GitHub Issues for bugs and questions
- Discussions: Use GitHub Discussions for ideas
- Pull Requests: See CONTRIBUTING.md for process
- ZeroMQ Project: Inspiration for succinct documentation style
- Anthropic Claude: AI-assisted development patterns
- Community Contributors: See Contributors
Quick Links: