Manifest System

What is the Manifest System?

The Manifest System provides structured project configuration that enables CCO to understand your project's architecture at scale. When working with large projects containing multiple components, the manifest file helps the orchestrator:

• Understand component boundaries and dependencies
• Route tasks to the most appropriate agent based on component ownership
• Prioritize context retrieval from relevant component paths
• Detect structural issues before they cause problems

Manifest File

The codified-manifest.yaml file lives at your workspace root and defines the complete structure of your project:

workspace/
├── codified-manifest.yaml    # Project manifest
├── src/
├── tests/
└── docs/

Manifest Schema

The manifest uses a structured YAML format with components, dependencies, and agent assignments:

name: "project-name"
version: "1.0"
components:
  - name: "component-name"
    path: "src/component"
    dependencies: ["other-component"]
    agents: ["planner", "implementer"]

This schema enables:

• Project-wide naming for tooling integration
• Version tracking for migration and compatibility
• Component-level isolation for safe refactoring
• Agent-based routing for specialized handling

Component Definition

Each component in the manifest consists of four key fields:

components:
  - name: "user-service"   # Unique name
    path: "services/user"

components:
  - name: "auth"
    path: "src/auth"        # All auth-related code

components:
  - name: "api"
    path: "src/api"
    dependencies:          # These components must exist
      - "database"
      - "auth"

components:
  - name: "payments"
    path: "src/payments"
    agents:                # Route payment tasks to specialist
      - "payment-analyst"
      - "compliance-reviewer"

Validation Features

CCO performs rigorous validation on manifest files to catch errors early:

# This will fail validation:
# Error: Circular dependency detected: api -> database -> api
components:
  - name: "api"
    dependencies: ["database"]
  - name: "database"
    dependencies: ["api"]

# Valid: ui can depend on api even if api is defined later
components:
  - name: "ui"
    dependencies: ["api"]    # Forward reference - OK
  - name: "api"
    path: "src/api"

# This will fail validation:
# Error: Duplicate component name 'auth'
components:
  - name: "auth"
    path: "src/auth"
  - name: "auth"           # Duplicate - validation fails
    path: "lib/auth"

Integration with Retrieval

When a manifest is present, CCO boosts the relevance scores of documents based on task scope and component matching:

# Manifest component path matching
components:
  - name: "payments"
    path: "src/payments"
    agents: ["payment-analyst"]

Context Boosting Rules

CCO applies scoring bonuses when retrieving context:

Example: Task Routing with Manifest

When you run a task that modifies payment logic:

cco task --repo /path/to/project --task "Add retry logic to payment processor"

CCO's retrieval system:

1. Matches task scope to the payments component based on path patterns
2. Boosts documents in src/payments by +15
3. Boosts documents mentioning payment-analyst by +8
4. Routes the task to agents specialized in payments

Python API

CCO provides a Python API for programmatic manifest operations:

from codified_orchestrator.manifest import load_manifest, validate_manifest

manifest = load_manifest(Path("/path/to/workspace"))
is_valid, errors = validate_manifest(manifest)

Loading a Manifest

The load_manifest function reads and parses a manifest file:

from pathlib import Path
from codified_orchestrator.manifest import load_manifest

# Load manifest from workspace root
workspace = Path("/path/to/your/project")
manifest = load_manifest(workspace)

print(f"Project: {manifest.name}")
print(f"Components: {len(manifest.components)}")

Validating a Manifest

The validate_manifest function checks for structural issues:

from pathlib import Path
from codified_orchestrator.manifest import load_manifest, validate_manifest

workspace = Path("/path/to/your/project")
manifest = load_manifest(workspace)

is_valid, errors = validate_manifest(manifest)

if not is_valid:
    print("Manifest validation failed:")
    for error in errors:
        print(f"  - {error}")
else:
    print("Manifest is valid!")

Working with Components

Access component data programmatically:

from pathlib import Path
from codified_orchestrator.manifest import load_manifest

manifest = load_manifest(Path("/path/to/workspace"))

# Iterate over all components
for component in manifest.components:
    print(f"{component.name}: {component.path}")
    print(f"  Dependencies: {component.dependencies}")
    print(f"  Agents: {component.agents}")

# Find specific component
payment_component = next(
    (c for c in manifest.components if c.name == "payments"),
    None
)
if payment_component:
    print(f"Payments path: {payment_component.path}")

Dependency Resolution

Resolve component dependencies in topological order:

from pathlib import Path
from codified_orchestrator.manifest import load_manifest, get_build_order

manifest = load_manifest(Path("/path/to/workspace"))

# Get components in dependency order
build_order = get_build_order(manifest.components)

for component in build_order:
    print(f"Build: {component.name}")