Metadata-Version: 2.4
Name: codd-dev
Version: 0.2.0a1
Summary: CoDD: Coherence-Driven Development — cross-artifact change impact analysis
Project-URL: Homepage, https://github.com/yohey-w/shogun-codd
Project-URL: Repository, https://github.com/yohey-w/shogun-codd
Project-URL: Issues, https://github.com/yohey-w/shogun-codd/issues
Author-email: Yohei Watanabe <yohey-w@users.noreply.github.com>
License-Expression: MIT
License-File: LICENSE
Keywords: change-impact,claude-code,dependency-graph,plugin,software-engineering
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: mcp
Provides-Extra: scan
Requires-Dist: tree-sitter-java>=0.22; extra == 'scan'
Requires-Dist: tree-sitter-python>=0.22; extra == 'scan'
Requires-Dist: tree-sitter-typescript>=0.22; extra == 'scan'
Requires-Dist: tree-sitter>=0.22; extra == 'scan'
Description-Content-Type: text/markdown

# CoDD — Coherence-Driven Development

**CoDD keeps AI-built systems coherent as requirements change.**

Give CoDD your requirements and constraints. AI generates the design top-down, derives implementation and test strategy from those artifacts, and traces change impact across a dependency graph — so nothing falls out of sync.

> *Harnesses tell agents how to work. CoDD keeps artifacts coherent.*

```
Harness (CLAUDE.md, AGENTS.md, Hooks, Skills)  ← Rules, guardrails, flow
  └─ CoDD (methodology)                        ← Operates on the harness flow
       └─ Design docs (docs/*.md)              ← Artifacts CoDD generates and maintains
```

**Public Alpha** — `pip install codd-dev` — init / scan / impact / validate are stable today.

## The Problem

AI can generate code from specs. But what happens when requirements change mid-project?

- Which design docs are affected?
- Which tests need updating?
- Which API contracts broke?
- Did anyone forget to update the database migration?

Spec-driven tools help you write specs first. They don't track what happens when those specs change. That's where CoDD comes in.

### Why not just AGENTS.md or hooks?

AGENTS.md, CLAUDE.md, and hooks are **harness infrastructure** — they tell agents how to behave. CoDD is a **coherence layer** that sits on top of any harness and keeps design artifacts, implementation, and tests in sync when requirements change. CoDD is harness-agnostic: it works with Claude Code, GitHub Copilot, Cursor, or any agent framework.

## Core Principle: Derive, Don't Configure

**Upstream artifacts + best practices = downstream is self-evident.**

- `system_design.md` says "Next.js + Supabase" → test strategy is vitest + Playwright. No config needed.
- `api_design.md` says "FastAPI" → pytest + httpx. No config needed.
- Requirements change → `codd impact` shows exactly what's affected.

You define requirements and constraints. AI derives everything else.

## How It Works

```
Phase 1: Requirements (human)        ─┐
Phase 2: Design generation (AI)       │ V-Model left side
Phase 3: Scan (auto)                  │
Phase 4: Implementation (AI)         ─┘
Phase 5: Verification (AI + human)   ─── V-Model right side
Phase 6: Change impact analysis      ─┐
Phase 7: Change propagation           │ Continuous coherence
Phase 8: Customer review             ─┘
```

Design docs are generated in **Wave order** — each wave depends on the previous:

```
Wave 1: Acceptance criteria + ADR        (← requirements only)
Wave 2: System design                    (← req + Wave 1)
Wave 3: Database design + API design     (← req + Wave 1-2)
Wave 4: UI/UX design                     (← req + Wave 1-3)
Wave 5: Implementation plan              (← all above)
```

Verification runs bottom-up (IPA Common Frame):
```
Unit tests      ← verifies detailed design
Integration     ← verifies system design
E2E / System    ← verifies requirements + acceptance criteria
```

## Three Layers (Don't Confuse Them)

```
Harness (CLAUDE.md, Hooks, Skills)   ← Rules, guardrails, flow
  └─ CoDD (methodology)              ← Operates on the harness flow
       └─ Design docs (docs/*.md)    ← Artifacts CoDD generates and maintains
```

- **Harness** = how agents work (any harness: Claude Code, Copilot, Cursor, etc.)
- **CoDD** = how artifacts stay coherent across changes
- **Docs** = what CoDD produces and maintains

CoDD is **harness-agnostic**. It runs on top of whatever agent framework you use.

## Quick Start

```bash
# Install
pip install codd-dev

# Initialize
codd init --project-name "my-project" --language "typescript"

# Scan — build dependency graph from frontmatter
codd scan

# Impact — what breaks if I change this?
codd impact --diff HEAD~1
```

## Real Project: Osato LMS

CoDD was dogfooded on a production LMS (Learning Management System). All design documents, implementation code, and tests were generated by AI following CoDD's workflow. No manual review by the client.

```
docs/
├── requirements/       # What to build (client agreement, SSoT)
├── design/             # How to build it (system design, API, DB, UI)
├── detailed_design/    # Module-level specs
├── plan/               # WBS, schedule, RACI
├── governance/         # ADR, meeting minutes, change requests
├── test/               # Acceptance criteria, test plans
├── operations/         # Runbooks, monitoring design
└── infra/              # Infrastructure specs
```

Every doc has CoDD frontmatter declaring its dependencies:

```yaml
---
codd:
  node_id: "design:api-design"
  depends_on:
    - id: "design:system-design"
      relation: derives_from
    - id: "req:lms-requirements-v2.0"
      relation: implements
---
```

When the requirements changed mid-project, `codd impact` identified exactly which design docs, API endpoints, and test cases needed updating — and AI fixed them automatically.

## How CoDD Differs from Spec Kit / OpenSpec

|  | Spec Kit | OpenSpec | **CoDD** |
|--|----------|---------|----------|
| Write specs first | Yes | Yes | Yes |
| AI generates code from specs | Yes | Yes | Yes |
| **Change propagation** | No | No | **Dependency graph + impact analysis** |
| **Derive test strategy from architecture** | No | No | **Automatic (derive, don't configure)** |
| **V-Model verification** | No | No | **Unit → Integration → E2E** |
| **Impact analysis on change** | No | No | **codd impact --diff HEAD~1** |
| Harness-agnostic | GitHub Copilot focused | Multi-agent | **Any harness** |

**Spec Kit and OpenSpec answer "how do I start?" CoDD answers "how do I keep going when things change?"**

## What's Available Now (v0.2.0-alpha.1)

| Command | Status | What it does |
|---------|--------|-------------|
| `codd init` | **Stable** | Initialize CoDD in any project |
| `codd scan` | **Stable** | Build dependency graph from frontmatter |
| `codd impact` | **Stable** | Analyze change impact (Green/Amber/Gray bands) |
| `codd validate` | **Alpha** | Check frontmatter integrity and graph consistency |
| `codd generate` | Experimental | Generate design docs in Wave order |
| `codd plan` | Experimental | Wave execution status and auto-initialization |
| `codd verify` | Experimental | V-Model verification (typecheck + tests → design tracing) |
| `codd implement` | Experimental | Design-to-code generation |

### Alpha Scope: What We Promise / What We Don't

| We promise | We don't promise (yet) |
|------------|----------------------|
| Frontmatter-based dependency graph works | Full semantic dependency types beyond Wave order |
| `codd impact` correctly identifies affected nodes | Automatic fix of affected nodes |
| `codd validate` catches broken references and cycles | Exhaustive validation of all edge cases |
| Harness-agnostic (no vendor lock-in) | Turnkey integrations for every harness |
| Derivation principle: architecture → test strategy | Fully automated end-to-end generation pipeline |
| MIT license, stable CLI interface for core commands | API stability for experimental commands |

## Frontmatter is the Single Source of Truth

CoDD uses YAML frontmatter in Markdown files to declare dependencies. `graph.db` is a derived cache — regenerated on every `codd scan`. No separate config files to maintain.

```yaml
---
codd:
  node_id: "design:system-design"
  type: design
  depends_on:
    - id: "req:lms-requirements-v2.0"
      relation: implements
  conventions:
    - targets: ["db:rls_policies"]
      reason: "Tenant isolation is non-negotiable"
---
```

## Real-World Example: Derive, Don't Configure

```
system_design.md says "Next.js + Supabase"
→ Test strategy: vitest (unit) + Playwright (E2E). No config needed.

system_design.md says "FastAPI + Python"
→ Test strategy: pytest (unit/integration) + httpx (API). No config needed.

system_design.md says "CLI tool in Go"
→ Test strategy: go test (unit/integration). No config needed.
```

The architecture determines the test strategy. CoDD derives it — you don't configure it.

## Roadmap

- [ ] Semantic dependency types (requires, affects, verifies, implements)
- [ ] `codd verify` — full docs ↔ code ↔ tests coherence check
- [ ] Multi-agent integration examples (Claude Code, Copilot, Cursor)
- [ ] VS Code extension for impact visualization

## License

MIT
