CooperativeCoding

Seven Principles

The foundation of human-AI collaborative design.

The Cooperation Loop

A continuous cycle where human intent and agent capability meet.

Design

Human or agent creates or updates the canvas — classes, methods, fields, relationships, and documentation contracts. Both can edit the canvas and the code at any time. The canvas is where the human exercises architectural authority.

Implement

The agent generates or updates source code based on canvas elements. Documentation blocks become docstrings, edges become inheritance declarations and imports, node kinds become class skeletons. The agent can loop autonomously: implement, test, fix, repeat.

Sync

Every change on either side produces a sync request for the other. Canvas changes produce code requests; code changes produce design requests. The agent processes each request and decides what changes are needed. The loop continues until both sides match.

Visual Example

A UserService with its methods and dependencies, as it appears on a CooperativeCoding canvas.

Each node carries its own documentation contract: responsibilities, pseudo code, and constraints. The agent implements code from these contracts, and sync keeps both sides aligned.

Generated Python Code

The sync engine generates this code from the canvas above. Signatures and docstrings come from the nodes; method bodies are left as stubs for the agent to implement.

class UserService:
    """Manages user accounts: creation, lookup, updates, and deletion.

    Responsibility:
        All user lifecycle operations including registration,
        lookup, updates, and soft deletion.
    """

    def get_user(self, user_id: str) -> User:
        """Look up a user by ID."""
        raise NotImplementedError

    def delete_user(self, user_id: str) -> None:
        """Soft delete a user."""
        raise NotImplementedError

    def register(self, name: str, email: str, password: str) -> User:
        """Create a new user account with validated input, hashed creds, and a welcome email.

        Pseudo Code:
            1. Validate name and email format
            2. Check for duplicates in db
            3. Hash password using hasher
            4. Create user record in db
            5. Send welcome email
            6. Return new user
        """
        raise NotImplementedError

Data Model

The building blocks of architectural description — a semantic layer on top of JSON Canvas v1.0.

Bidirectional Sync

Canvas and code are two views of the same system. The sync engine keeps them honest.

Getting Started

Four steps to begin working with CooperativeCoding.

Specification Documents

The complete CooperativeCoding specification, organized in five core documents plus a language binding reference.