AI as Team Member from Day 0 - A practical approach to AI-driven development
Context Hive is a development methodology and template collection that treats AI as a full team member from the very beginning of a project (Day 0 / Phase 0). Instead of using AI as a tool, we collaborate with AI through comprehensive documentation that serves as shared context.
- AI joins from Day 0: AI participates in the project from the pre-start phase, not as an afterthought
- Documentation as shared context: Vision, requirements, design, and rules serve as the foundation for AI collaboration
- Practical, not perfect: We share real experiences, including failures and limitations
- Scale limits unknown: We're honest about what we don't know yet
Context Hive is built around three key components working together:
┌─────────────────────────────────────────────────────────────┐
│ Phase 0: Pre-Start │
│ │
│ ┌───────────┐ ┌──────────────┐ ┌────────┐ ┌─────────┐│
│ │ Vision.md │──│Requirements │──│Design │──│Rules.md ││
│ │ │ │ .md │ │ .md │ │ ││
│ └───────────┘ └──────────────┘ └────────┘ └─────────┘│
│ │ │ │ │ │
│ └────────────────┼───────────────┼────────────┘ │
│ ▼ ▼ │
└─────────────────────────┼───────────────┼──────────────────┘
│ │
▼ ▼
┌───────────────────────────────────┐
│ Hub System │
│ ┌─────────────────────────────┐ │
│ │ build_graph.py │ │
│ │ validate_context.py │ │
│ │ gen_reading_list.py │ │
│ └─────────────────────────────┘ │
│ │
│ Generates: │
│ - Dependency graph (graph.json) │
│ - Visualizations (graph.mmd) │
│ - Reading lists per task │
└───────────────┬───────────────────┘
│
▼
┌──────────────────────────────────────────┐
│ Service Layer │
│ │
│ ┌────────────┐ ┌────────────┐ │
│ │ Service A │ │ Service B │ │
│ │ │ │ │ │
│ │ ├─app/ │ │ ├─app/ │ │
│ │ ├─tests/ │ │ ├─tests/ │ │
│ │ └─tasks/ │ │ └─tasks/ │ │
│ └────────────┘ └────────────┘ │
└──────────────────────────────────────────┘
-
Phase 0 (Pre-Start): Write four pillar documents
- Vision: Project goals and purpose
- Requirements: What needs to be built
- Design: How it will be built
- Rules: Development standards
-
Hub: Manages context and dependencies
- Scans service metadata (
service.meta.yaml) - Generates dependency graphs
- Creates optimized reading lists for AI
- Validates consistency
- Scans service metadata (
-
Services: Implement features with AI
- Each service declares its dependencies
- Tasks reference specific documents
- AI reads in optimal order (via reading lists)
- Humans review and iterate
Traditional approach: AI gets code snippets → makes mistakes → constant corrections
Context Hive: AI gets complete context → autonomous implementation → minimal corrections
- Read the getting started guide: docs/getting-started.md
- Try the minimal example: examples/minimal/
- Use the template: template/minimal/
- Run
pre-commit installafter cloning to enable the shared linting suite (Black, Ruff, mypy, markdownlint, codespell, prettier, etc.). - Execute
scripts/audit_codex.shto run the full codex audit locally. Results are written toreports/codex/audit.jsonandreports/codex/audit.html. - See docs/CODEX_AUDIT_GUIDE.md for audit criteria, pass/fail gates, and triage workflow.
- Getting Started - Complete beginner's guide
- Theory - Core concepts and methodology
- Applicability - When to use Context Hive
- Core Concepts - AI as team member, Hub architecture, COPA methodology
- Philosophy - Design decisions and rationale
- 5-Phase Process - Detailed development workflow
- Best Practices - Practical guidelines
- Context Hive vs. Other Approaches - How we compare to alternatives
- Contributing - How to contribute
- Hub Tools (hub/tools/) - Python scripts for managing context
build_graph.py- Generate dependency graphsvalidate_context.py- Validate context consistencygen_reading_list.py- Generate AI reading lists
- Hub Metadata (hub/meta/) - Generated graphs and reading lists
graph.json- Machine-readable dependency graphgraph.mmd- Mermaid visualizationreading_lists/- Generated reading orders for AI
- Sample Service (services/sample_service/) - Example service structure
- Service metadata (
service.meta.yaml) - Task definitions
- Implementation example
- Service metadata (
- Minimal Template (template/minimal/) - The essential 4-document starter kit
- Vision document
- Requirements document
- Design document
- Rules document
- Minimal Example (examples/minimal/) - A working FastAPI Hello World built with Context Hive
- Complete documentation set
- Implementation code
- Tests
- Init Script (scripts/init-project.sh) - Initialize a new Context Hive project
context-hive/
├── README.md # This file
├── THEORY.md # Core methodology
├── APPLICABILITY.md # When to use this approach
├── CONTRIBUTING.md # Contribution guidelines
├── LICENSE # License information
├── requirements.txt # Python dependencies
│
├── docs/ # Documentation
│ ├── getting-started.md # 30-minute tutorial
│ ├── concepts.md # Core concepts and Hub architecture
│ ├── philosophy.md # Design decisions and rationale
│ ├── process.md # 5-phase development process
│ ├── comparison.md # vs. other approaches
│ └── best-practices.md # Practical guidelines
│
├── hub/ # Hub: Context Management System
│ ├── README.md # Hub documentation
│ ├── meta/ # Generated metadata
│ │ ├── graph.json # Dependency graph (machine-readable)
│ │ ├── graph.mmd # Dependency graph (Mermaid)
│ │ └── reading_lists/ # Generated AI reading lists
│ └── tools/ # Hub management tools
│ ├── build_graph.py # Generate dependency graph
│ ├── validate_context.py # Validate context consistency
│ └── gen_reading_list.py # Generate reading lists
│
├── services/ # Service implementations
│ └── sample_service/ # Example service
│ ├── README.md # Service documentation
│ ├── service.meta.yaml # Service metadata
│ ├── app/ # Implementation
│ └── tasks/ # Task definitions
│
├── scripts/ # Utility scripts
│ └── init-project.sh # Project initialization script
│
├── template/
│ └── minimal/ # Minimal template (4 documents)
│ ├── README.md
│ └── docs/
│ └── templates.md
│
└── examples/
└── minimal/ # Working example
├── README.md
├── docs/ # 4 core documents
└── src/ # Implementation
- Phase 0: Pre-start - AI joins before coding begins
- Documentation First - Create shared context before implementation
- Iterative Collaboration - AI and humans iterate together
- Learning from Failures - We welcome and share failure stories
Context Hive works well for:
- Greenfield projects starting from scratch
- Projects with clear business goals
- Teams open to AI collaboration
- Iterative development processes
See APPLICABILITY.md for detailed guidance.
If you want to contribute to Context Hive itself, follow these steps:
# Clone the repository
git clone https://github.com/Petsuro85/context-hive.git
cd context-hive
# Switch to develop branch
git checkout develop
# Run the bootstrap script to set up your environment
bash scripts/bootstrap_dev.sh
# This will:
# - Create a Python virtual environment
# - Install all dependencies
# - Set up pre-commit hooks
# - Run initial validationContext Hive uses a develop → master workflow:
- develop: Active development branch where all work happens
- master: Protected production branch for public releases
Before submitting changes:
# Run full validation suite
bash scripts/validate_all.sh
# This runs:
# - Schema validation (strict mode)
# - Dependency graph generation
# - Reading list generation# Generate reading list for a service/task
bash scripts/make_readinglist.sh sample_service implement_api
# Generate release notes from commits
bash scripts/release_notes.sh
# Bootstrap development environment
bash scripts/bootstrap_dev.shPre-commit hooks automatically run on every commit to ensure code quality:
- Python: black (formatting), ruff (linting), mypy (type checking)
- Markdown: mdformat (formatting)
- General: trailing whitespace, YAML/JSON validation
If hooks fail, fix the issues and commit again.
We welcome contributions! This includes:
- Success stories and case studies
- Failure stories and lessons learned
- Template improvements
- Documentation enhancements
- Translation
See CONTRIBUTING.md for details.
MIT License - See LICENSE file for details.
- Issues: GitHub Issues
- Discussions: GitHub Discussions
Remember: AI as team member, not as tool. Documentation as shared context, not as burden.