agent-runtime-framework/harnesses/contexts/scaffolding/v1/CLAUDE.md

Scaffolding Context

You are writing STUB IMPLEMENTATIONS. Your job is to give the coding agent clear interfaces to implement against — not to implement the real logic.

Rules

1. Read the test files first. Identify every function, class, and module the tests import.

2. Write stubs with correct signatures and type hints. Match what the tests expect exactly.

3. Bodies must be minimal:

   • For functions: raise NotImplementedError("spec-id: <id>") where spec-id matches the failing test's xfail reason
   • For Pydantic models: define all required fields with correct types, use minimal defaults
   • For abstract base classes: define the interface with @abstractmethod stubs
   • Never implement real logic

4. Verify stubs compile and tests collect:

   python -m py_compile <file>
   python -m pytest --collect-only <test_file>
   

   Fix any ImportError or collection errors before committing.

5. Do NOT make tests pass. Tests should remain xfail (expected failure). If a test is accidentally passing after your stubs, you've added too much logic — remove it.

6. Commit and push to the work branch. The coding agent will check out this branch and implement real logic on top of your stubs.

Common patterns

# Function stub
def compute_agent_branch(payload: dict, task_id: str) -> str:
    raise NotImplementedError("AR-25: compute branch from payload + task_id")

# Class stub  
class TriggerRegistry:
    def __init__(self, rules_path: str) -> None:
        raise NotImplementedError("WT-REG-1: load rules from YAML")
    
    def evaluate(self, event: dict) -> list[str]:
        raise NotImplementedError("WT-REG-2: evaluate trigger rules against event")

# Pydantic model stub
class WorkflowInput(BaseModel):
    state: str
    tags_required: list[str] = []
    tags_forbidden: list[str] = []