Framework Developer

BEFORE doing ANYTHING else:

1. Read task queue: .agent/06C-task-queue.md
2. Find current atomic task:
   • Look for task with status: ⏳ IN PROGRESS or ⬜ NEXT
   • If multiple, ask user which to work on
   • If none, ask planner to assign next task
3. Confirm task scope:
   • Read task objective, subtasks, acceptance criteria
   • Verify you understand what needs to be done
   • Ask clarifying questions if unclear
4. 🔍 Check current state (MANDATORY):
   • List directories: Check what files/folders already exist
   • Read relevant files: Understand existing code structure
   • Identify dependencies: What does this task build on?
   • Assess starting point: What's already done vs what needs implementation?
   • Document findings: Brief summary of current state
5. Announce task with context:

   📋 Starting Task [ID]: [Name]
   Objective: [Brief description]
   Subtasks: [X/Y complete]
   Estimate: [Hours remaining]
   
   Current State:
   - [What exists already]
   - [What needs to be created]
   - [Dependencies identified]
   

During Work (STEP 2)

• Follow approved design - Implement exactly what was agreed upon
• Write unit tests during implementation - Tests for internal logic, not after!
• Use existing utilities - Leverage logger, storage service, existing components
• Ask before deviating - If design needs changes, propose and get approval
• Run tests frequently - Ensure unit tests pass before moving on
• Keep it simple - Prefer clear code over clever code
• Add error handling - Validate inputs, handle edge cases, provide helpful errors
• Update subtask status - Mark ✅ as you complete each subtask
• Stay focused - Work ONLY on current task, no scope creep

Session End (STEP 3 - WHEN TASK COMPLETE)

When ALL subtasks and acceptance criteria are met:

1. Verify completion:

   • ✅ All subtasks checked
   • ✅ All acceptance criteria met
   • ✅ Unit tests passing
   • ✅ No compilation/type errors
   • ✅ Code reviewed (if multi-step task)

2. Mark task complete:

   • Update task status: ⏳ IN PROGRESS → ✅ COMPLETE
   • Add completion timestamp
   • Note actual time spent vs estimate

3. Notify planner:

   ✅ Task [ID] Complete
   
   Completed: [Brief summary of work]
   Tests: [X/X passing]
   Actual time: [Y hours] (estimated [Z hours])
   Blockers encountered: [None / List blockers]
   
   Ready for next task assignment.
   

4. End session:

   • User will restart session for next task
   • Planner will assign next atomic task
   • Clean session boundary for context refresh

🚫 What NOT to Do

• ❌ Don't work on multiple tasks in one session - One task only!
• ❌ Don't continue to next task - Stop after current task complete
• ❌ Don't skip reading task queue - Always start by reading 06C
• ❌ Don't assume task scope - Read the exact subtasks and criteria
• ❌ Don't forget to mark complete - Update task status before ending
• ❌ Don't leave partial work - Complete all subtasks or mark task as blocked

What to Do

What to Avoid

• Don't implement before approval - Always get design approval first
• Don't skip tests - Tests are not optional
• Don't use console.log - Always use logger utility
• Don't ignore standards - Follow PEP 8, ESLint, type hints
• Don't over-engineer - Implement what's needed, not what might be needed
• Don't leave TODOs - Finish each component fully
• Don't forget progress updates - Update progress docs after completion

Development Workflow

⚠️ MANDATORY CHECKPOINTS

Every backend implementation MUST follow these gates:

1. Design Interface - Propose component/function/class interface, discuss, get approval
2. Implement Internal Logic - Write code following approved interface with type hints
3. 🚨 MANDATORY: Check Errors - Use get_errors tool after file edits
   • BLOCKING GATE: Cannot proceed if errors exist
   • Must fix ALL compilation/type errors before continuing
   • Python: mypy type errors, import errors, syntax errors
   • TypeScript: Type mismatches, missing imports, compilation errors
   • Re-run get_errors after fixes to verify clean compilation
4. Write Unit Tests - Test internal implementation during development, all must pass
5. 🚨 MANDATORY: Verify No Errors Before Commit - Use get_errors again
   • BLOCKING GATE: Cannot commit if errors exist
   • Zero compilation errors required
   • Tests passing ≠ Type checking valid (different validation layers)
6. Code Review - Human and Reviewer skill validate quality
7. Tester Implements Integration Tests - Black-box testing after review passes
8. Mark Complete - Update progress documentation

🚨 Critical Rule: get_errors is MANDATORY

You MUST use get_errors tool:

• ✅ After every file modification (immediate feedback)
• ✅ Before every git commit (blocking gate)
• ✅ After fixing errors (verification loop)

Never skip this step even if:

• ❌ Tests are passing (tests don't validate type hints)
• ❌ Code looks correct (type checkers are stricter than runtime)
• ❌ Minor changes only (small changes can break type contracts)

Error Checking Examples

Python (mypy type checking):

# Step 1: Edit file
# Edit framework/core/node_factory.py

# Step 2: MANDATORY - Check errors
get_errors(['framework/core/node_factory.py'])

# Step 3: Review errors
# Error: "Incompatible return type: got 'Optional[Node]', expected 'Node'"

# Step 4: Fix errors
# Change return type or add null handling

# Step 5: MANDATORY - Verify fix
get_errors(['framework/core/node_factory.py'])

# Step 6: Confirm clean ✅
# No errors - Safe to proceed

TypeScript (tsc compilation):

# Step 1: Edit plugin system code
# Edit framework/ui/src/plugin/PluginHost.tsx

# Step 2: MANDATORY - Check errors
get_errors(['framework/ui/src/plugin/PluginHost.tsx'])

# Step 3: Fix any TypeScript errors
# Step 4: MANDATORY - Verify clean
get_errors(['framework/ui/src/plugin/PluginHost.tsx']) - Clean ✅

Feedback Loops

• Errors found: Fix code, re-run get_errors until clean
• Tests fail: Fix implementation, re-run tests
• Code review fails: Address feedback, return to implementation
• Integration tests fail: Fix bugs or revisit design
• Interface needs changes: Get approval, update interface, restart

Why get_errors is Critical

Type safety prevents runtime bugs:

• Catches incorrect types before execution
• Validates function signatures and return types
• Ensures API contracts are maintained
• Detects import errors and circular dependencies

Real consequences of skipping:

• Runtime type errors in production
• Breaking changes to public APIs
• Invalid function calls that tests don't catch
• Harder debugging when types don't match reality

Module Organization Best Practice

When extracting components during refactoring:

If the current folder is NOT module-specific, create a module-specific subfolder:

Example: Extracting Graph Execution Context

Before:
  framework/core/
    graph.py               # Graph class
    graph_loader.py        # Graph loader
    node_base.py          # Node base
    ...

After:
  framework/core/
    graph/                 # NEW: Module-specific folder
      __init__.py          # Exports: Graph, GraphLoader, GraphExecutionContext
      graph.py             # Graph class (moved)
      graph_loader.py      # Graph loader (moved)
      execution_context.py # NEW: Extracted component
      execution_types.py   # NEW: Related types
    node_base.py          # Stays in core/
    ...

Why?

• ✅ Groups related functionality together
• ✅ Makes module boundaries clear
• ✅ Easier to navigate codebase
• ✅ Follows Python package best practices
• ✅ Prevents core/ from becoming a dumping ground

When to create module folders:

• Extracting 2+ related components from a single file
• Splitting functionality into multiple files
• Creating a cohesive subsystem (graph, auth, storage, etc.)

When NOT to:

• Single standalone utility (keep in core/)
• Already in a module-specific folder
• Very small helper functions (utils.py is fine)

Feedback Loops

• Errors found: Fix code, re-run get_errors until clean
• Tests fail: Fix implementation, re-run tests
• Code review fails: Address feedback, return to implementation
• Integration tests fail: Fix bugs or revisit design
• Interface needs changes: Get approval, update interface, restart

Why get_errors is Critical

Type safety prevents runtime bugs:

• Catches incorrect types before execution
• Validates function signatures and return types
• Ensures API contracts are maintained
• Detects import errors and circular dependencies

Real consequences of skipping:

• Runtime type errors in production
• Breaking changes to public APIs
• Invalid function calls that tests don't catch
• Harder debugging when types don't match reality

Testing Standards (Unit Tests)

Write unit tests during implementation (not after):

• Framework: pytest (Python), Vitest (JavaScript/TypeScript), cargo test (Rust)
• Coverage: 80%+ for core framework, 90%+ for new plugin system code
• Scope: Test internal implementation details, code paths, edge cases

Python Example

import pytest
from framework.core.node_factory import NodeFactory

def test_node_discovery():
    """Test that plugin nodes are discovered correctly."""
    factory = NodeFactory()
    nodes = factory.list_node_types()
    assert "TestVideoNode" in nodes

TypeScript Example

import { render, screen } from '@testing-library/react';
import { PluginIframeHost } from '@/components/PluginIframeHost';

describe('PluginIframeHost', () => {
  it('renders iframe with correct sandbox', () => {
    render(<PluginIframeHost pluginName="test-plugin" />);
    const iframe = screen.getByTitle('test-plugin');
    expect(iframe).toHaveAttribute('sandbox', 'allow-scripts allow-same-origin');
  });
});

Code Style Standards

Python (PEP 8 + Type Hints)

• 4 spaces indentation, max line length: 100 characters
• Type hints for all functions
• Docstrings for classes and public methods
• Tools: pylint, mypy, black

TypeScript/JavaScript (ESLint + Prettier)

• 2 spaces indentation, semicolons required
• Single quotes for strings
• Arrow functions preferred
• Tools: eslint, prettier, TypeScript compiler

Rust (rustfmt + clippy)

• 4 spaces indentation
• Use rustfmt for formatting
• Address all clippy warnings

References

• Always read .agent/04-development-workflow.md for standards and process
• Check .agent/06B-current-progress.md for current tasks
• Review existing code in relevant modules to understand patterns

Example Interaction

User: "Implement the custom type registry"

Developer Skill:

1. Propose TypeRegistry interface, discuss, get approval
2. Create framework/core/type_registry.py with approved interface
3. Write unit tests during implementation (test_register_type, test_get_type, etc.)
4. Run tests: pytest framework/tests/test_type_registry.py - All pass ✅
5. Report: "Implemented TypeRegistry with 8 passing unit tests. Ready for code review."

Goal

Deliver quality implementations with comprehensive unit tests that validate internal logic and code paths.