Contributing Guidelines
Relevant source files
The following files were used as context for generating this wiki page:
The ATMOS Project Wiki system is a research-grade documentation framework designed to transform source code analysis into structured, navigable Markdown-based wikis. Contributors to this system must adhere to strict quality standards involving deep codebase exploration, metadata collection, and automated validation.
This guide outlines the architectural requirements and workflows for three primary contribution paths: initial wiki generation, incremental updates, and topic-specific deep dives. Each path requires the use of specialized skills that enforce minimum word counts, Mermaid diagram inclusion, and source file traceability.
Sources: skills/project-wiki/README.md, skills/project-wiki/SKILL.md:10-25
Core Philosophy and Standards
Contributors are expected to act as technical researchers rather than simple document summarizers. The system prioritizes prose and visual diagrams over extensive code blocks, aiming to explain the "why" and "how" behind architectural decisions.
Quality Metrics for Articles
Every article generated must meet specific depth thresholds to pass automated validation.
| Metric | Getting Started | Deep Dive / Specify |
|---|---|---|
| Minimum Word Count | 800+ words | 1500+ words |
| Source Files Referenced | 3+ files | 5+ files |
| Mermaid Diagrams | 2+ diagrams | 3+ diagrams |
| H2 Sections | 4+ sections | 6+ sections |
| Cross-references | 2+ links | 4+ links |
Sources: skills/project-wiki/SKILL.md:300-315, skills/project-wiki/README.md:95-105
Workflow Architecture
The contribution process is governed by a multi-step workflow that ensures metadata integrity and schema compliance. The following diagram illustrates the standard generation sequence.
The workflow includes mandatory validation gates using scripts like validate_catalog.py and validate_content.py to ensure the wiki is rendering-ready.
Sources: skills/project-wiki/SKILL.md:40-250
Contribution Skills
Initial Wiki Generation (project-wiki)
This is the primary entry point for documenting a new codebase. It involves building a hierarchical _catalog.json and a two-part structure: "Getting Started" for newcomers and "Deep Dive" for maintainers.
- Key Scripts:
collect_metadata.sh,init_wiki_todo.sh. - Mandatory Artifacts:
_concepts.json,_metadata/commit_details.txt.
Sources: skills/project-wiki/SKILL.md:50-150
Incremental Updates (project-wiki-update)
When the codebase evolves, contributors use the update skill to synchronize the wiki. It uses a three-phase strategy to detect changes.
This strategy ensures that only pages referencing modified source files are regenerated, preserving unchanged content.
Sources: skills/project-wiki-update/SKILL.md:20-60
Topic Specification (project-wiki-specify)
For contributors adding focused research on a specific theme (e.g., "Why was Rust chosen?"), the specify skill creates a dedicated section in the wiki. These articles must adhere to the higher "Deep Dive" thresholds for word count and diagrams.
Sources: skills/project-wiki-specify/SKILL.md:40-70
Documentation Structure and Metadata
All contributions must follow a strict directory layout and YAML frontmatter format. The frontend integration relies on these standards for navigation and rendering.
Frontmatter Requirement
Every Markdown file MUST start with a YAML block. Blockquotes or inline metadata are forbidden as they break the parser.
---
title: Article Title
section: deep-dive
level: intermediate
reading_time: 12
path: section/article-name
sources:
- path/to/source_file.rs
updated_at: 2026-02-10T12:00:00Z
---
Sources: skills/project-wiki/references/output_structure.md:120-145
Directory Layout
The wiki is organized within the .atmos/wiki/ directory to remain local and version-controllable.
| Path | Purpose |
|---|---|
_catalog.json | Navigation metadata and hierarchy |
_metadata/ | Collected Git logs and contributor stats |
_briefings/ | Research questions for sub-agents |
getting-started/ | Beginner-level introductory articles |
deep-dive/ | Advanced implementation details |
Sources: skills/project-wiki/references/output_structure.md:10-40
Technical Integration
The wiki is designed to be rendered in a 3-column viewer (Navigation | Content | TOC). Contributors should ensure headings are stable for the Table of Contents (TOC) and that Mermaid diagrams support both light and dark modes.
Sources: specs/tech/project-wiki.md:100-130
The ATMOS contributing framework ensures that documentation is not a static byproduct but a research-driven asset. By adhering to the mandatory validation scripts and content depth standards, contributors maintain a high-quality, navigable knowledge base that evolves alongside the codebase.