Architecture Overview
Relevant source files
The following files were used as context for generating this wiki page:The AI Dev Atelier is a production-grade skill pack designed for AI-assisted software development. Its architecture is modular, extensible, and enforces specific development workflows through a combination of self-contained skills, external capability providers, and runtime hooks. The system is structured to ensure consistency, maintainability, and adherence to best practices, particularly in documentation and research-driven development.
The core architectural philosophy centers on the "skill" as the primary unit of functionality. Each skill is an independent module with its own instructions, scripts, and reference materials. This is complemented by a system of Multi-Capability Providers (MCPs) for extensible functionality like web search and academic research, and PreToolUse hooks that act as guardrails to guide agent behavior and enforce repository-specific rules.
Sources: AGENTS.md:5-6, AGENTS.md:10-16, skills/docs-write/references/documentation-guide.md:200-207
Core Components
The repository is organized around several key components that work together to provide a comprehensive AI development environment.
This diagram shows the high-level structure of the ai-dev-atelier repository, highlighting the main components and their relationships.
Sources: AGENTS.md:10-21
Skills
Skills are the fundamental building blocks of the system. Each skill is a self-contained directory that provides a specific capability, such as code quality checks, documentation writing, or academic research. The project contains 9 primary skills.
Sources: AGENTS.md:10, AGENTS.md:26-36
| Skill | Purpose | Entry Point |
|---|---|---|
code-quality | Typecheck, lint, format, and check Markdown. | scripts/finalize.sh |
docs-check | Detect documentation that needs updates based on git diff. | scripts/check-docs.sh |
docs-write | Write or update documentation following project standards. | Workflow (no script) |
git-commit | Write clear commit messages using Conventional Commits. | Workflow (no script) |
code-review | Perform CodeRabbit-style reviews. | scripts/review-run.sh |
resolve-pr-comments | Facilitate multi-agent resolution of PR comments. | scripts/pr-resolver*.sh |
search | Provides web, library docs, and GitHub code search via MCPs. | MCP-based |
research | Conducts academic research with evidence cards via MCPs. | scripts/research-*.sh |
ui-animation | Guides the creation of UI animations with a focus on accessibility. | Workflow (no script) |
Sources: AGENTS.md:26-36
Skill Structure
Each skill follows the Anthropic Agent Skills standard. A typical skill directory contains:
SKILL.md: A file with YAML frontmatter defining the skill's name and description, followed by Markdown instructions, workflows, and examples.scripts/: A directory containing executable bash scripts that implement the skill's logic.references/: A directory for supporting materials like guides, templates, and examples.
This diagram illustrates the standard internal structure of a skill directory.
Sources: AGENTS.md:12-14, AGENTS.md:118-123
Multi-Capability Providers (MCPs)
MCPs are external services that extend the capabilities of the AI agents. They are defined in mcp.json and provide functionalities like web search, academic paper retrieval, and PDF reading. Skills like search and research are heavily reliant on these providers.
Sources: AGENTS.md:6, AGENTS.md:20, AGENTS.md:80-95
| Server | Purpose | Required Key |
|---|---|---|
tavily-remote-mcp | Web search | TAVILY_API_KEY |
context7 | Library documentation search | Optional |
grep | GitHub code search | None |
openalex-research | Academic paper search | OPENALEX_EMAIL |
pdf-reader | PDF content extraction | None |
paper-search | Multi-platform paper search | Optional |
zai-zread | GitHub repo semantic search (issues, PRs, docs) | Z_AI_API_KEY |
zai-vision | Image/video analysis and UI code generation | Z_AI_API_KEY |
Sources: AGENTS.md:80-95
The following diagram shows how a skill, such as research, interacts with an MCP to fulfill a request.
Workflow Guardrails (Hooks)
The system uses PreToolUse hooks, defined in hooks.json, to intercept tool calls and enforce repository-specific workflows. These hooks act as guardrails to prevent common mistakes, such as using git push in a Graphite-managed repository or making redundant API calls.
Sources: AGENTS.md:18, AGENTS.md:72-79
| Hook ID | Matcher | Purpose |
|---|---|---|
graphite-block | Bash | Blocks git push, git checkout -b, and gh pr create in Graphite-enabled repos. |
pr-comments-block | Bash | Blocks gh api calls that fetch PR comments on open PRs in the current repo. |
Sources: AGENTS.md:74-77
This sequence diagram shows how the graphite-block hook intercepts a forbidden git command.
Sources: AGENTS.md:72-79
Data and Runtime Outputs
All runtime data generated by skills is stored in the .ada/ directory, which is ignored by git. This keeps the main repository clean while preserving outputs from processes like code reviews, PR comment resolution, and research.
.ada/data/reviews/: Stores code review results..ada/data/pr-resolver/: Contains data for PR comment resolution..ada/data/research/{topic}/: Holds evidence cards and reports from the research skill..ada/temp/: Used for temporary files, such as downloaded PDFs for research.
Sources: AGENTS.md:108-114, skills/research/SKILL.md:88-94
Subsystems
The architecture supports several key subsystems, each with its own workflow and components.
Documentation Subsystem
The project follows a "docs-as-code" approach, where documentation is stored in version control and updated alongside code. A documentation-guide.md file provides comprehensive standards for style, structure, and content.
The recommended structure places all documentation within a .docs/ directory at the repository root, organized into subdirectories like guides/, db/, api/, and architecture/.
Sources: skills/docs-write/references/documentation-guide.md:46-81, skills/docs-write/references/documentation-guide.md:200-207
The docs-check skill provides tooling to enforce this system. Its check-docs.sh script analyzes git diff to identify code changes that likely require corresponding documentation updates, suggesting relevant documentation files to review.
This flowchart shows the workflow of the check-docs.sh script.
Sources: skills/docs-check/scripts/check-docs.sh, skills/docs-write/SKILL.md:58
Research Subsystem
The research skill implements a rigorous, multi-step workflow for conducting academic and web-based research. It is designed to produce comprehensive, evidence-based reports. The workflow mandates a "write-first" pattern to avoid context loss, where findings are immediately written to "evidence cards" after reading only 1-2 sources.
The key stages are:
- Gather Codebase Context: Research is grounded in the project's existing architecture and needs.
- Formulate Research Question: A clear question is defined based on the context.
- Comprehensive Discovery: Use MCPs to find 25+ academic and non-academic sources.
- Incremental Evidence Card Creation: Create 5+ evidence cards, synthesizing findings from sources.
- Generate Report: Synthesize all evidence cards into a final comparative report.
All research artifacts, including the question, evidence cards, and final report, are stored in the .ada/data/research/{topic}/ directory.
Sources: skills/research/SKILL.md:14-36, skills/research/references/guides/guide-workflow.md:19-30, skills/research/references/guides/guide-workflow.md:70-120
Summary
The architecture of AI Dev Atelier is deliberately structured to support robust, scalable, and maintainable AI-assisted development. Its modular design, centered on skills, allows for clear separation of concerns and easy extension. The integration of MCPs provides powerful, extensible capabilities, while workflow guardrails via hooks ensure that development practices remain consistent and aligned with project standards. This combination creates a powerful and opinionated framework for building software with AI agents.
Sources: AGENTS.md