docops 0.1.3
Normative Documentation for AI-Assisted Development
Requires Python: >=3.10
Keywords: documentation, ai, contracts, vibe-coding, llm, openai, anthropic, ollama

# 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

```bash
# 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

```bash
pip install docops
```

Or from source:

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

---

## Configuration

DocOps supports **100+ LLM providers** via [LiteLLM](https://docs.litellm.ai/docs/providers). Configure in `.env`:

### Anthropic (Default)
```bash
DOCOPS_MODEL=claude-sonnet-4-5-20250929
ANTHROPIC_API_KEY=sk-ant-...
```

### OpenAI
```bash
DOCOPS_MODEL=gpt-4o
OPENAI_API_KEY=sk-...
```

### Google Gemini
```bash
DOCOPS_MODEL=gemini/gemini-pro
GEMINI_API_KEY=...
```

### Ollama (Free, Local)
```bash
DOCOPS_MODEL=ollama/llama3
# No API key needed - runs locally
```

### Azure OpenAI
```bash
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](https://docs.litellm.ai/docs/providers) for all supported providers.

---

## Commands

```bash
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:

```bash
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 |

```bash
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:

```markdown
## DocOps Integration

This project uses DocOps for normative documentation.

- Run `docops --help` and `docops sync --help` to see available commands and options.
- Run `docops ai` to see the full contract structure, workflow, and constraints.

### 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

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

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

# Run tests
pytest

# Run linting
ruff check docops tests

# Run type checking
mypy docops
```

---

## License

MIT