docops 0.1.2

Normative Documentation for AI-Assisted Development

DocOps

Stop losing context. Start coding with confidence.

The Problem: Vibe Coding Without a Map

You're using AI to write code. It's fast. It's magical. It's also slowly eroding your understanding of your own codebase.

Every time you prompt "add a payment feature" or "fix the authentication", the AI generates code. You accept it. It works. But:

• You don't fully understand what it did
• You forget how components connect
• The codebase grows, but your mental model doesn't
• Context window limits mean the AI forgets too

After a few weeks:

• You need to change the order flow but can't remember which services are involved
• The AI suggests changes that break hidden dependencies
• You're debugging code you don't recognize
• Documentation? Outdated five commits ago

The paradox: The more AI helps you code, the less you understand your code.

---

The Solution: Contracts as Source of Truth

DocOps creates contracts — structured documentation files that describe every source file in terms of:

Section	Purpose
DEPENDS ON	What this file uses
USED BY	What uses this file
EXPECTS	Requirements for inputs
GUARANTEES	What it promises to deliver
FORBIDDEN	What it must NEVER do

These contracts are:

• AI-generated from your source code
• Human-readable for understanding
• Machine-parseable for AI agents to follow
• Automatically aggregated into system-level documentation

The Philosophy: Shared Responsibility

DocOps is not about AI doing all the work or humans writing all the docs.

It's a collaboration:

Actor	Role
AI	Generates initial contract structure, suggests updates, fills in technical details
Human	Reviews, corrects, adds context, defines constraints and FORBIDDEN rules

The maintenance of documentation is a shared responsibility:

• AI can create the initial structure and suggest details based on code analysis
• Human can do the same, but also direct the AI's behavior by editing contracts

When you edit a contract:

• You're teaching the AI what matters
• You're constraining future changes to respect your design
• You're documenting intent that code alone can't express
• You're directing future AI actions by defining boundaries and rules

The human shapes the boundaries. The AI fills in the details. Both can initiate, both can refine.

---

How It Works

# Initialize in your project
docops init

# Generate contracts for all files
docops sync

This creates:

docs/
├── contracts/              # One .contract.md per source file
│   └── src/
│       └── services/
│           └── order_service.contract.md
├── spec/
│   ├── domains.md          # Bounded contexts (auto-generated)
│   └── principles.md       # System laws from FORBIDDEN sections
└── dependencies.md         # Mermaid graph of relationships

---

Installation

pip install docops

Or from source:

git clone https://github.com/ferdinandobons/DocOps.git
cd DocOps
pip install -e .

---

Configuration

DocOps supports 100+ LLM providers via LiteLLM. Configure in .env:

Anthropic (Default)

DOCOPS_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_API_KEY=sk-ant-...

OpenAI

DOCOPS_MODEL=gpt-4o
OPENAI_API_KEY=sk-...

Google Gemini

DOCOPS_MODEL=gemini/gemini-pro
GEMINI_API_KEY=...

Ollama (Free, Local)

DOCOPS_MODEL=ollama/llama3
# No API key needed - runs locally

Azure OpenAI

DOCOPS_MODEL=azure/gpt-4
AZURE_API_KEY=...
AZURE_API_BASE=https://your-resource.openai.azure.com

Other Providers

Provider	Model Format	API Key Env Var
Mistral	mistral/mistral-large	MISTRAL_API_KEY
Groq	groq/llama-70b	GROQ_API_KEY
AWS Bedrock	bedrock/anthropic.claude-v2	AWS credentials
Together AI	together_ai/meta-llama/Llama-3-70b	TOGETHER_API_KEY

See LiteLLM docs for all supported providers.

---

Commands

docops init          # Initialize DocOps structure
docops sync          # Sync contracts for the entire project
docops ai            # Show AI agent guidance
docops version       # Show version

Targeted Sync

docops sync accepts files and/or directories to sync only specific targets:

docops sync main.py                        # single file
docops sync src/services/                  # entire directory
docops sync main.py src/utils/ lib.py      # mix files and dirs

Options

Flag	Effect
--force	Regenerate contracts even if they already exist
--dry-run	Preview what would be generated, without writing files

docops sync --force                  # regenerate everything
docops sync main.py --force          # regenerate one file
docops sync --dry-run                # preview only

---

For AI Agents

DocOps is designed to work with AI coding assistants. Include this in your AI agent configuration:

Supported Tools

Tool	Config File
Cursor	.cursorrules
Windsurf	.windsurfrules
Cline	.clinerules
Claude Code	CLAUDE.md
Continue.dev	.continue/config.json
Aider	.aider.conf.yml

Add this to your config file:

## DocOps Integration

This project uses DocOps for normative documentation.

### Before Making Changes
1. Read `docs/dependencies.md` to understand file relationships
2. Read the contract for any file you plan to modify: `docs/contracts/{path}/{filename}.contract.md`
3. Check FORBIDDEN section to avoid violations
4. Check DEPENDS ON and USED BY to understand impact

### After Making Changes
1. If you modified a file's behavior, update its contract
2. If you added new files, create contracts for them
3. Run `docops sync` to regenerate aggregated docs
4. Verify your changes don't violate any FORBIDDEN rules

### Contract Structure
Each contract contains:
- PURPOSE: Why this file exists
- ROLE: Architectural responsibility
- DEPENDS ON: Upstream dependencies (what this uses)
- EXPECTS: Input requirements
- WORKFLOW: High-level steps
- USED BY: Downstream dependents (what uses this)
- GUARANTEES: Post-execution promises
- BOUNDARIES: Scope limits
- FORBIDDEN: Critical constraints (NEVER violate these)

### Key Principle
**Contracts are the Source of Truth.** When code and contract disagree, fix the code.

---

Why This Works

1. Contracts survive refactoring — Even when code changes, the contracts document intent
2. AI stays aligned — Agents can read contracts before modifying files
3. Context is preserved — DEPENDS ON/USED BY create an explicit dependency graph
4. Constraints are enforced — FORBIDDEN sections prevent common mistakes
5. Understanding scales — System-level docs aggregate from file-level contracts

---

The DocOps Philosophy

Code changes. Context fades. Contracts persist.

• Don't trust memory — Document everything
• Don't trust AI alone — Contracts constrain it
• Don't trust outdated docs — Regenerate from source
• Don't trust implicit knowledge — Make dependencies explicit

---

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a PR.

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run linting
ruff check docops tests

# Run type checking
mypy docops

---

License

MIT