A reusable framework that enables AI agents (like Claude) to autonomously build, test, and maintain software projects with minimal human intervention.
This framework provides the scaffolding for agentic development - a development approach where AI agents handle the full software development lifecycle through:
- Multi-agent orchestration for complex, multi-domain tasks
- Task complexity commands that right-size automation for the work
- Closed-loop validation with automatic error correction
- Architectural decision records for consistency across sessions
- Git workflow automation with branch protection
- Exemplar-first patterns for codebase consistency
Specialized AI agents collaborate on complex tasks:
- Orchestrator Agent - Coordinates multi-domain workflows
- Frontend/UI Agent - Handles user-facing components
- State/Data Agent - Manages data layers and business logic
- Testing Agent - Creates comprehensive test suites (unit + E2E, mandatory for all features)
- Review Agent - Validates quality, security, and best practices
- Documentation Agent - Maintains docs and ADRs
Right-sized automation with built-in testing workflows:
/small-task- Direct implementation (1-3 files, no tests)/medium-task- Multi-agent delegation (3-8 files, unit + E2E tests required)/heavy-task- Full orchestration (10+ files, comprehensive test suite required)/bugfix- Investigation-first fixing/refactor- Quality improvements/explore- Codebase understanding/research- External information gathering
Testing is mandatory: Medium and heavy tasks automatically include unit tests, integration tests, and E2E tests for UI features. All tests must pass before completion.
Automatic validation hooks ensure code quality:
- Type checking runs after every edit (customizable)
- Linting runs after every edit (customizable)
- Errors automatically feed back to agents
- Agents self-correct without human intervention
ADRs maintain consistency:
- Document architectural decisions
- Reference across sessions
- Enforce patterns before PRs
- Immutable record of trade-offs
Branch management and PR workflows:
- Branch relevance checking
- Conventional commit messages
- Automated PR creation and review
- ADR enforcement before merge
Out of the box, this framework works for TypeScript projects with:
- TypeScript for type safety
- ESLint for linting
- Prettier for formatting
- Jest for unit/integration testing
- Playwright for E2E testing
But it's fully customizable for any tech stack. The orchestration patterns, validation loops, and ADR workflows are language-agnostic. Swap the tools, keep the workflows.
git clone https://github.com/yourusername/agentic-layer-framework.git my-project
cd my-project
rm -rf .git # Start fresh
git initEdit /path/to/your/project/CLAUDE.md:
- Replace default tech stack with yours
- Define your coding standards
- Set project-specific success criteria
Edit validation commands for your tools:
- Locate hook configuration (depends on your AI tool)
- Replace
npm run typecheckwith your type checker - Replace
npm run lintwith your linter - Add language-specific checks
Examples:
# Python
mypy . && flake8
# Go
go vet ./... && golangci-lint run
# Rust
cargo check && cargo clippy
# Java
mvn compile && mvn checkstyle:checkEdit .claude/agents/ files:
- Adapt agent focuses to your tech stack
- Create domain-specific agents (Backend, Database, DevOps, etc.)
- Update orchestrator to coordinate your custom agents
If using the default TypeScript setup:
npm installOr replace with your language's package manager and dependencies.
MCPs significantly enhance the framework's capabilities. Highly recommended:
- GitHub MCP - 40% faster PR workflows, better error handling
npm install -g @modelcontextprotocol/server-github
- Memory MCP - Cross-session context and pattern memory
npm install -g @modelcontextprotocol/server-memory
- Sequential Thinking MCP - Enhanced planning and reasoning
npm install -g @modelcontextprotocol/server-sequential-thinking
- Brave Search MCP - Developer-focused research
npm install -g @modelcontextprotocol/server-brave-search
Configuration: See MCP Integration Guide for setup instructions and API keys.
Note: MCPs are optional - the framework works without them, but they provide significant enhancements.
If you're adding the framework to an existing codebase with established patterns, use the /bootstrap command to automatically generate documentation:
/bootstrapWhat bootstrap does:
-
Analyzes your codebase comprehensively:
- Detects tech stack, frameworks, and libraries
- Identifies architectural patterns and file organization
- Discovers code conventions and naming patterns
- Reviews existing documentation
-
Generates project-specific documentation:
- Enhances/creates README.md with project details
- Customizes CLAUDE.md for your project (replaces generic placeholders)
- Creates ADRs documenting existing architectural patterns
- Updates ADR index
-
Asks minimal clarifying questions (0-5, only if patterns are ambiguous)
-
Commits all generated documentation in a single commit
Result: The framework now has full context about your project's patterns, conventions, and architecture. All task commands will work with project-specific knowledge immediately.
When to use:
- ✅ Adding framework to existing project (50+ files)
- ✅ Project has established patterns and conventions
- ✅ You want framework to understand your codebase automatically
When to skip:
- ❌ Brand new project (no code yet)
- ❌ You prefer manual documentation
- ❌ Project is still in experimental phase
Time: 5-10 minutes (vs 4-8 hours of manual documentation)
See Bootstrap Skill Documentation and ADR-003 for details.
Use task complexity commands for development:
# Understanding existing code
/explore How does the authentication system work?
# Simple changes
/small-task Add logging to the error handler
# Multi-domain features
/medium-task Build user profile page with data fetching and tests
# Complex systems
/heavy-task Implement complete notification system with email, SMS, and in-appADRs document important decisions for future reference:
- When to create: First implementation of a pattern, technology choices, architectural decisions
- Required before PRs: New patterns must have ADRs before merging
- Immutable: Once accepted, create new ADR to change direction
- Cross-session memory: Agents reference ADRs to maintain consistency
Create with: /adr "Your decision title"
The FIRST implementation of any pattern becomes the exemplar:
- Build first instance with extra care
- Add comprehensive documentation
- Mark as exemplar:
// EXEMPLAR: Pattern Name - Future implementations follow the exemplar
This ensures consistency without copy-pasting code in documentation.
Validation errors automatically feed back to agents:
- Agent writes code
- Hooks run validation automatically
- If errors: Agent sees errors and fixes them
- If passes: Agent continues to next task
- Repeat until validation passes
No human intervention needed for fixing type errors, lint issues, etc.
Commands explicitly signal task complexity:
- Predictable: Same complexity → same orchestration pattern
- Efficient: Right-sized tooling for the work
- Clear: Upfront communication of scope
See CLAUDE.md for decision tree on which command to use.
agentic-framework/
├── .claude/ # Framework configuration
│ ├── agents/ # Specialized agent configs
│ │ ├── orchestrator.md # Coordinates multi-agent workflows
│ │ ├── frontend.md # UI/component development
│ │ ├── state-management.md # Data layer
│ │ ├── testing.md # Test creation
│ │ ├── review.md # Code review
│ │ └── documentation.md # Docs and ADRs
│ └── skills/ # Task command implementations
│ ├── small-task.md # Direct implementation
│ ├── medium-task.md # Multi-agent delegation
│ ├── heavy-task.md # Full orchestration
│ ├── bugfix.md # Investigation + fix
│ ├── refactor.md # Quality improvements
│ ├── explore.md # Codebase understanding
│ └── research.md # External research
├── .github/ # GitHub automation
│ ├── workflows/ # CI/CD pipelines (examples)
│ ├── pull_request_template.md # PR creation template
│ └── pr_review_template.md # PR review checklist template
├── docs/
│ └── adr/ # Architecture Decision Records
│ ├── README.md # ADR index
│ └── 001-agentic-development-framework-architecture.md # Framework foundation
├── CLAUDE.md # Main AI instructions (CUSTOMIZE THIS)
├── README.md # This file
├── package.json # Framework tooling (TypeScript defaults)
├── tsconfig.json # TypeScript config (example)
├── eslint.config.js # ESLint config (example)
├── .prettierrc # Prettier config (example)
├── jest.config.ts # Jest config (example)
└── playwright.config.ts # Playwright config (example)
If using the default TypeScript configuration:
| Command | Description |
|---|---|
npm run typecheck |
Check TypeScript types |
npm run lint |
Lint code |
npm run lint:fix |
Auto-fix linting issues |
npm test |
Run unit/integration tests |
npm run test:watch |
Run tests in watch mode |
npm run test:e2e |
Run E2E tests (headless) |
npm run test:e2e:ui |
Run E2E tests with UI |
npm run build |
Build for production |
For other stacks: Replace these with your language's equivalents.
- CLAUDE.md - Main AI instructions (customize for your project)
- docs/adr/ - Framework architectural decisions
- .claude/agents/ - Agent configurations
- .claude/skills/ - Task command implementations
A: No. The default configuration uses TypeScript, but the framework works with any language. Update CLAUDE.md and validation hooks for your stack.
A: Yes! Use the /bootstrap command after adding framework files to your project. Bootstrap automatically analyzes your codebase and generates project-specific documentation (README, CLAUDE.md, ADRs for existing patterns). This takes 5-10 minutes vs 4-8 hours of manual documentation. See section 3.6 above for details.
A: The patterns are designed for Claude (via Claude Code), but the concepts work with any agentic AI system. You may need to adapt configurations.
A: Create new files in .claude/agents/ following existing templates. Update the orchestrator to be aware of new agents.
A: You can use the framework without agents - the ADR system, task commands, and validation hooks work independently.
This framework is open for contributions:
- Bug fixes: Open an issue or PR
- New agent templates: Share domain-specific agents
- Language-specific guides: Document setup for new tech stacks
- Improvements: Suggest enhancements to orchestration patterns
The goal of this framework is to enable autonomous software development - where AI agents can:
- Understand requirements and existing code
- Plan implementations across multiple domains
- Execute with proper patterns and quality
- Validate their own work automatically
- Document decisions for future consistency
The framework doesn't replace developers - it makes them more effective by handling repetitive tasks, maintaining consistency, and catching errors automatically.
MIT License - See LICENSE for details.
The real goal: Build systems that build systems.