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/   │   │
           │  └────────────┘      └────────────┘   │
           └──────────────────────────────────────────┘

1. 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

2. Hub: Manages context and dependencies

   • Scans service metadata (service.meta.yaml)
   • Generates dependency graphs
   • Creates optimized reading lists for AI
   • Validates consistency

3. 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

1. Read the getting started guide: docs/getting-started.md
2. Try the minimal example: examples/minimal/
3. Use the template: template/minimal/

• Run pre-commit install after cloning to enable the shared linting suite (Black, Ruff, mypy, markdownlint, codespell, prettier, etc.).
• Execute scripts/audit_codex.sh to run the full codex audit locally. Results are written to reports/codex/audit.json and reports/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 graphs
  • validate_context.py - Validate context consistency
  • gen_reading_list.py - Generate AI reading lists
• Hub Metadata (hub/meta/) - Generated graphs and reading lists
  • graph.json - Machine-readable dependency graph
  • graph.mmd - Mermaid visualization
  • reading_lists/ - Generated reading orders for AI

• Sample Service (services/sample_service/) - Example service structure
  • Service metadata (service.meta.yaml)
  • Task definitions
  • Implementation example

• 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

1. Phase 0: Pre-start - AI joins before coding begins
2. Documentation First - Create shared context before implementation
3. Iterative Collaboration - AI and humans iterate together
4. 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 validation

Context 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.sh

Pre-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.