PRIMITIVE-001: Define contract primitive type and create example contracts #206

New issue

Closed

opened 2026-04-13 02:43:54 +00:00 by Mark · 0 comments

Mark commented

2026-04-13 02:43:54 +00:00

Owner

Problem

The contract primitive type exists in base templates but has no actual implementations. Contracts are supposed to be the intent-binding interface between incoming intents and skill families, but this is not defined anywhere.

Current State

primitives/_shared/base_templates/base_contract.yaml exists with placeholder schema
No actual contract primitives exist (no type: contract in any template.yaml)
Workers currently advertise "capabilities" (contracts) but the terminology is confused
The contract_factory exists but has nothing to create

What Contracts Should Be

Per AGENTS.md and architecture discussions:

Contracts are derived primitives that:

Bind intent types to skill families
Define input/output schemas for validation
Specify bond requirements and execution constraints
Are advertised by workers (workers have contracts, not skills)

Example contract structure:

primitive:
  type: contract
  tier: muscle
  id: writing_contract

contract_interface:
  intent_type: writing_task
  skill_family: writer  # Maps to skills: write_article, write, etc.

input_schema:
  type: object
  required: [topic, format]
  properties:
    topic: {type: string}
    format: {type: string, enum: [news, analysis, opinion]}
    word_count: {type: integer, minimum: 500}

output_schema:
  type: object
  required: [article, citations]
  properties:
    article: {type: string}
    citations: {type: array, items: {type: string}}

execution:
  bond_required: 10
  timeout_seconds: 300
  max_retries: 2

Scope (MINIMAL)

Define contract schema in documentation
Create 2-3 example contracts in primitives/_muscle/:
- writing_contract/ - binds writing_task → writer skills
- research_contract/ - binds research_task → researcher skills
Update PrimitiveLoader to handle contract type
Document how workers advertise contracts

Files

docs/reference/CONTRACT_PRIMITIVES.md (new)
primitives/_muscle/writing_contract/template.yaml (new)
primitives/_muscle/research_contract/template.yaml (new)
runtime/primitive_loader.py - Add contract handling
AGENTS.md - Add contract section

Acceptance Criteria

Contract schema documented
2+ example contracts created
PrimitiveLoader handles contract type
Workers can advertise contracts
Tests pass with contracts loaded

Follows terminology refactoring (commit a10e79f)
Related to issue #117 (closed - terminology resolved)
Blocks contract_factory from having real work

## Problem The `contract` primitive type exists in base templates but has no actual implementations. Contracts are supposed to be the **intent-binding interface** between incoming intents and skill families, but this is not defined anywhere. ## Current State - `primitives/_shared/base_templates/base_contract.yaml` exists with placeholder schema - No actual contract primitives exist (no `type: contract` in any template.yaml) - Workers currently advertise "capabilities" (contracts) but the terminology is confused - The contract_factory exists but has nothing to create ## What Contracts Should Be Per AGENTS.md and architecture discussions: **Contracts are derived primitives that:** 1. Bind intent types to skill families 2. Define input/output schemas for validation 3. Specify bond requirements and execution constraints 4. Are advertised by workers (workers have contracts, not skills) **Example contract structure:** ```yaml primitive: type: contract tier: muscle id: writing_contract contract_interface: intent_type: writing_task skill_family: writer # Maps to skills: write_article, write, etc. input_schema: type: object required: [topic, format] properties: topic: {type: string} format: {type: string, enum: [news, analysis, opinion]} word_count: {type: integer, minimum: 500} output_schema: type: object required: [article, citations] properties: article: {type: string} citations: {type: array, items: {type: string}} execution: bond_required: 10 timeout_seconds: 300 max_retries: 2 ``` ## Scope (MINIMAL) 1. **Define contract schema** in documentation 2. **Create 2-3 example contracts** in `primitives/_muscle/`: - `writing_contract/` - binds writing_task → writer skills - `research_contract/` - binds research_task → researcher skills 3. **Update PrimitiveLoader** to handle contract type 4. **Document** how workers advertise contracts ## Files - `docs/reference/CONTRACT_PRIMITIVES.md` (new) - `primitives/_muscle/writing_contract/template.yaml` (new) - `primitives/_muscle/research_contract/template.yaml` (new) - `runtime/primitive_loader.py` - Add contract handling - `AGENTS.md` - Add contract section ## Acceptance Criteria - [ ] Contract schema documented - [ ] 2+ example contracts created - [ ] PrimitiveLoader handles contract type - [ ] Workers can advertise contracts - [ ] Tests pass with contracts loaded ## Related - Follows terminology refactoring (commit a10e79f) - Related to issue #117 (closed - terminology resolved) - Blocks contract_factory from having real work