Home

Relevant source files

The following files were used as context for generating this wiki page:

• skills/resolve-pr-comments/references/documentation-guide.md
• skills/docs-write/references/documentation-guide.md
• skills/docs-check/references/documentation-guide.md
• skills/code-review/references/documentation-guide.md
• skills/code-quality/references/documentation-guide.md
• skills/docs-write/SKILL.md
• skills/docs-check/scripts/check-docs.sh
• skills/research/references/guides/guide-workflow.md
• skills/research/SKILL.md
• skills/docs-check/SKILL.md
• skills/git-commit/SKILL.md
• skills/git-commit/references/examples.md
• skills/research/references/templates/template-research-question.md
• skills/research/references/evidence-card-guide.md
• skills/research/references/guides/guide-evidence-cards.md

The ai-dev-atelier repository is a collection of "skills" designed for an AI agent, establishing a structured environment for software development tasks. The project is governed by a set of core principles and workflows that emphasize documentation, research, and code quality. The central philosophy is a "Docs-as-Code" approach, where documentation is version-controlled and maintained alongside the codebase, and a rigorous, evidence-based research methodology.

This project defines standardized workflows for common development activities, including writing documentation, checking for documentation updates, conducting research, and making git commits. These workflows are encapsulated in different "skills," each with its own set of guidelines, tools, and reference materials. The goal is to ensure consistency, quality, and maintainability across all development activities.

Core Workflows and Principles

The repository's operation is centered around a few key skills that interact to maintain code and documentation quality. The primary workflows involve committing code, checking and writing documentation, and conducting research.

This diagram illustrates the high-level interaction between the core skills.

Documentation System (Docs-as-Code)

The project mandates a "Docs-as-Code" approach, where documentation is stored in version control, updated in the same PR as code changes, and reviewed as part of the code review process.

Sources: skills/resolve-pr-comments/references/documentation-guide.md:200-207

Core Principles

Documentation must adhere to four core principles:

Principle	Description
Focused	Document what's necessary, not everything. Avoid documenting minor bug fixes or internal refactoring.
Visual	Use diagrams for complex concepts like schemas, workflows, and architecture.
Updated	Keep documentation in sync with code changes.
Consistent	Follow project conventions and style guides.

Sources: skills/resolve-pr-comments/references/documentation-guide.md:6-11

Directory Structure

All documentation must reside in the .docs/ directory at the repository root. The recommended structure organizes documents by topic.

This diagram shows the standard documentation directory structure.

Document Types

The documentation system is based on the Divio framework, which categorizes documents into four types based on their purpose.

Type	Purpose	Audience
Tutorial	End-to-end learning by doing.	Beginner
How-to	Goal-oriented steps for a specific task.	Intermediate
Reference	Exact, complete facts (e.g., API, config).	All
Explanation	Concepts, trade-offs, and the "why" behind decisions.	All

Sources: skills/docs-write/references/documentation-guide.md:36-41

Visuals and Diagrams

Visuals are a key component of the documentation strategy. The guidelines specify which tools to use for different scenarios.

• Mermaid: Used for inline diagrams embedded directly in Markdown files. It is suitable for overviews, workflows, and visual summaries that enhance understanding.
• PlantUML: Used for diagrams stored as separate .puml files. This is preferred when a diagram is referenced from multiple documents or needs to be version-controlled separately.

Sources: skills/code-review/references/documentation-guide.md:86-121

Automated Documentation Check (docs-check)

The docs-check skill provides a script to analyze git diff output and identify code changes that may require documentation updates. This helps maintain synchronization between code and docs.

The workflow for the check-docs.sh script is as follows:

Research Methodology

The repository defines a rigorous, comprehensive research workflow designed to produce evidence-based reports. It is mandatory for all research tasks.

The "Write-First" Pattern

A critical rule of the research process is the "Write-First Pattern". This pattern is mandatory to prevent context overload and information loss, as AI agent context windows are limited. It dictates that after reading a maximum of 1-2 sources, the researcher must immediately write or update an evidence card and save all files before proceeding.

This flowchart illustrates the mandatory "Write-First" loop.

Comprehensive Research Workflow

The full research process is a multi-step workflow that begins with understanding the existing codebase and ends with a detailed report.

Key components of this workflow include:

• Codebase Context: Research must be relevant and actionable, informed by the current state of the project.
• Comprehensive Discovery: Aims to find 25+ sources, including highly-cited academic papers, recent research, and non-academic sources like blogs and documentation. It explicitly requires seeking out conflicting viewpoints.
• Evidence Cards: At least 5 evidence cards must be created. Each card synthesizes information from multiple sources that support a single approach, and must include claims, evidence, benefits, and limitations.
• Critical Evaluation: After creating cards, each approach is evaluated against the codebase context and project constraints.

Sources: skills/research/references/guides/guide-workflow.md:42-124, skills/research/references/evidence-card-guide.md:17-29

Development Workflow

Git Commits

The git-commit skill enforces clear, atomic commits using the Conventional Commits specification as a baseline. The primary goal is to create a granular, clean, and revertible git history.

Commit Granularity

An atomic commit is defined as the smallest complete change that has a single purpose, is self-contained, and leaves the code in a working state.

Commit Together (Same Commit)	Commit Separately (Different Commits)
Feature + its unit tests	Feature + unrelated formatting
Bug fix + regression test	Bug fix + dependency update
API change + docs update	Refactor + new feature
Refactor + affected tests	Multiple unrelated fixes

Sources: skills/git-commit/SKILL.md:100-105

Commit Message Format

Commits must follow a specific format, which can be adapted based on project-specific conventions detected from git log or configuration files.

<type>(<scope>)!: <subject>

<body>

<footer>

• type: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert.
• scope: (Optional) The part of the codebase affected.
• !: (Optional) Indicates a breaking change.
• subject: A concise description in imperative mood.
• body: (Optional) Explains the "why" and "what" of the change.
• footer: (Optional) For issue references (Closes #123) or BREAKING CHANGE descriptions.

Sources: skills/git-commit/SKILL.md:49-55, skills/git-commit/references/examples.md