parallel development strategy

revolutionary ai development system that deploys multiple specialized agents
in parallel to achieve what would take months traditionally in hours.

core principle: 26 agents working in parallel = 4000x speedup over traditional development

when to spawn parallel agents:

  [ok] large refactoring tasks (1000+ line files, multi-module changes)
  [ok] complex multi-feature implementations (10+ independent components)
  [ok] parallel testing/debugging (fix 20+ lint errors simultaneously)
  [ok] architectural refactoring (breaking monoliths into modules)
  [ok] independent tasks that can run concurrently

when NOT to spawn parallel agents:

  [x] simple single-file changes
  [x] exploratory research tasks (use investigation instead)
  [x] planning without implementation
  [x] tasks with serial dependencies (must complete in order)

parallel execution patterns:

pattern 1: phased development (sequential phases, parallel within each)

  phase a - foundation (parallel):

    <agent><phase-a-types>
    <agent-type>coder</agent-type>
    <task>
    objective: extract type definitions from existing code

    context:
    - working with large codebase that needs type definitions
    - current types are scattered throughout files

    todo:
    [ ] identify all type definitions in codebase
    [ ] extract to shared types module
    [ ] update imports across affected files

    success: types compile and tests pass
    </task>
    </phase-a-types></agent>

    <agent><phase-a-models>
    <agent-type>coder</agent-type>
    <task>
    objective: create base data models

    context:
    - need consistent data models across application
    - current models are incomplete

    todo:
    [ ] analyze existing data structures
    [ ] create base model classes
    [ ] document model relationships

    success: models defined and documented
    </task>
    </phase-a-models></agent>

    <agent><phase-a-config>
    <agent-type>coder</agent-type>
    <task>
    objective: setup configuration structure

    context:
    - application needs centralized configuration
    - config is currently scattered

    todo:
    [ ] identify all config variables
    [ ] create config module structure
    [ ] migrate existing config

    success: config centralized and working
    </task>
    </phase-a-config></agent>

  phase b - implementation (parallel):

    <agent><phase-b-auth>
    <agent-type>coder</agent-type>
    <task>
    objective: implement authentication system

    todo:
    [ ] create auth module
    [ ] implement user login
    [ ] add session management

    success: authentication working
    </task>
    </phase-b-auth></agent>

pattern 2: feature breakdown (independent features in parallel)

  <agent><user-profile>
  <agent-type>coder</agent-type>
  <task>
  objective: implement user profile feature

  todo:
  [ ] create profile data model
    [ ] build profile ui
    [ ] add profile editing

    success: user profile feature complete
    </task>
    </user-profile></agent>

  <agent><search-function>
  <agent-type>coder</agent-type>
  <task>
  objective: build search functionality

  todo:
  [ ] implement search algorithm
    [ ] create search ui
    [ ] add filters

    success: search working
    </task>
  </search-function></agent>

pattern 3: testing in parallel (each agent tests different module)

  <agent><test-auth>
  <agent-type>coder</agent-type>
  <skill>testing</skill>
  <task>
  objective: write and run authentication tests

  todo:
    [ ] write unit tests for auth
    [ ] run tests and verify they pass
    [ ] document test coverage

    success: auth tests passing
    </task>
  </test-auth></agent>

  <agent><test-db>
  <agent-type>coder</agent-type>
  <skill>testing</skill>
  <task>
  objective: test database layer thoroughly

  todo:
    [ ] write database integration tests
    [ ] test migrations
    [ ] verify data integrity

    success: database tests passing
    </task>
  </test-db></agent>

pattern 4: lint fixing (each agent fixes one file)

  <agent><fix-file1>
  <agent-type>coder</agent-type>
  <files>
    <file>src/file1.py</file>
  </files>
  <task>
  objective: fix lint errors in src/file1.py

  todo:
    [ ] run linter on file1.py
    [ ] fix each lint error
    [ ] verify fixes don't break functionality

  success: no lint errors in file1.py
  </task>
  </fix-file1></agent>

  <agent><fix-file2>
  <agent-type>coder</agent-type>
  <files>
    <file>src/file2.py</file>
  </files>
  <task>
  objective: fix lint errors in src/file2.py

  todo:
    [ ] run linter on file2.py
    [ ] fix each lint error
    [ ] verify fixes don't break functionality

  success: no lint errors in file2.py
  </task>
  </fix-file2></agent>

pattern 5: kollabor konsensus (orchestrated team intelligence)

  the kollabor konsensus pattern coordinates multiple specialist agents
  through a central orchestrator that decomposes complex tasks into
  parallelizable subtasks, similar to how expert teams tackle large projects.

  key concept: one orchestrator + n specialists + integration phase

  example: building complete feature with cross-cutting concerns

  step 1 - orchestrator analysis (you do this):

    <read><file>feature_spec.md</file></read>
    <terminal>find . -name "*.py" | head -20</terminal>
    <grep>pattern="class\|def" glob="kollabor/**/*.py"</grep>

    analyze requirements and identify parallel workstreams:
    - data layer (models, migrations)
    - business logic (services, controllers)
    - ui components (widgets, views)
    - testing (unit, integration)
    - documentation (api docs, user guides)

  step 2 - deploy specialist team (parallel):

    <agent><konsensus-data-layer>
    <agent-type>coder</agent-type>
    <skill>database</skill>
    <task>
    objective: implement complete data layer for feature

    context:
    - feature requires user preferences storage
    - need schema with versioning support
    - must migrate existing data

    todo:
    [ ] design database schema
    [ ] create migration scripts
    [ ] implement repository pattern
    [ ] add data validation layer
    [ ] write database tests

    success: data layer tested and migrations working
    </task>
    </konsensus-data-layer></agent>

    <agent><konsensus-business-logic>
    <agent-type>coder</agent-type>
    <task>
    objective: implement business logic services

    context:
    - feature processes user preferences
    - needs caching layer for performance
    - must handle edge cases

    todo:
    [ ] create service layer
    [ ] implement caching strategy
    [ ] add error handling
    [ ] write business logic tests
    [ ] document service interfaces

    success: services tested and documented
    </task>
    </konsensus-business-logic></agent>

    <agent><konsensus-ui-components>
    <agent-type>coder</agent-type>
    <skill>ui-design</skill>
    <task>
    objective: build user interface components

    context:
    - feature needs settings panel
    - must use existing design system
    - requires keyboard navigation

    todo:
    [ ] design ui layout
    [ ] implement widgets using design system
    [ ] add keyboard handlers
    [ ] ensure accessibility
    [ ] write ui tests

    success: ui functional and accessible
    </task>
    </konsensus-ui-components></agent>

    <agent><konsensus-integration-tests>
    <agent-type>coder</agent-type>
    <skill>testing</skill>
    <task>
    objective: create comprehensive integration tests

    context:
    - feature touches multiple layers
    - need end-to-end test coverage
    - must test error scenarios

    todo:
    [ ] design integration test suite
    [ ] implement end-to-end tests
    [ ] add edge case tests
    [ ] test rollback scenarios
    [ ] document test coverage

    success: all integration tests passing
    </task>
    </konsensus-integration-tests></agent>

    <agent><konsensus-documentation>
    <agent-type>coder</agent-type>
    <skill>documentation</skill>
    <task>
    objective: write complete documentation

    context:
    - feature is user-facing
    - needs api documentation
    - requires migration guide

    todo:
    [ ] write user documentation
    [ ] document api interfaces
    [ ] create migration guide
    [ ] add code examples
    [ ] review docs for clarity

    success: documentation complete and clear
    </task>
    </konsensus-documentation></agent>

  step 3 - consensus integration (sequential):

    <agent><konsensus-integrator>
    <agent-type>coder</agent-type>
    <task>
    objective: integrate all specialist outputs into working feature

    context:
    - data, business, ui, test, and doc specialists completed work
    - need to verify integration points
    - must ensure feature works end-to-end

    todo:
    [ ] review all specialist outputs
    [ ] verify integration points work
    [ ] run full test suite
    [ ] fix integration issues
    [ ] validate documentation
    [ ] create feature summary

    success: feature fully integrated and tested
    </task>
    </konsensus-integrator></agent>

  result: 6 specialists + 1 integrator = complete feature in parallel
          each specialist owns their domain completely
          integrator ensures consensus across all components

  when to use kollabor konsensus:

    [ok] features requiring multiple layers (data + logic + ui)
    [ok] complex refactorings touching multiple subsystems
    [ok] features needing comprehensive testing and documentation
    [ok] tasks where different expertise domains are clear
    [ok] projects requiring coordinated parallel workstreams

  konsensus best practices:

    [1] clear domain boundaries
        ensure each specialist has distinct responsibility
        avoid overlapping work between specialists

    [2] well-defined interfaces
        specify how components integrate upfront
        document api contracts between specialists

    [3] independent verification
        each specialist validates their own work
        integration agent catches cross-cutting issues

    [4] sequential integration phase
        never parallelize the integration step
        one agent must verify consensus

agent creation best practices:

  [1] investigate first, then spawn
      use read/terminal tools to understand current state
      identify concrete tasks that can run in parallel

  [2] write comprehensive task descriptions
      objective: clear statement of what to accomplish
      context: relevant constraints and background
      todo: step-by-step checklist
      success: how to verify completion

  [3] use descriptive agent names
      prefix with phase: phaseA, phaseB, featureX, etc.
      include purpose: extractor, validator, builder
      example: "phaseB-type-extractor" not "agent1"

  [4] include verification in task
      each agent should validate its work
      run tests after changes
      check for regressions

  [5] attach relevant files
      use <files><file>path/to/file.py</file></files>
      agents get these files in their context

  [6] use agent-type and skill tags appropriately
      <agent-type>coder</agent-type> for development
      <agent-type>research</agent-type> for investigation
      <skill>debugging</skill> for bug fixes
      <skill>testing</skill> for test writing

real-world example: refactoring 2757-line monolithic file

  investigation (you do this first):
    <read><file>monolith.py</file></read>
    <terminal>wc -l monolith.py</terminal>
    <terminal>grep -r "class\|def" monolith.py</terminal>

  phase a - extract foundations (parallel):

    <agent><models-extractor>
    <agent-type>coder</agent-type>
    <files>
      <file>monolith.py</file>
    </files>
    <task>
    objective: extract all data model classes from monolith.py

    context:
    - monolith.py is 2757 lines with mixed concerns
    - data models need to be separated

    todo:
    [ ] identify all data model classes
    [ ] extract to models/base.py
    [ ] update imports in monolith.py

    success: models in separate file, imports resolve
    </task>
    </models-extractor></agent>

    <agent><validators-extractor>
    <agent-type>coder</agent-type>
    <files>
      <file>monolith.py</file>
    </files>
    <task>
    objective: extract validation logic into validators.py

    context:
    - validation logic scattered throughout monolith
    - need centralized validation module

    todo:
    [ ] identify all validation functions
    [ ] extract to validators.py
    [ ] update references

    success: validators module created, working
    </task>
    </validators-extractor></agent>

    <agent><database-layer>
    <agent-type>coder</agent-type>
    <files>
      <file>monolith.py</file>
    </files>
    <task>
    objective: extract database queries into database.py

    context:
    - database queries mixed with business logic
    - need repository pattern

    todo:
    [ ] identify all database queries
    [ ] create database.py with repository pattern
    [ ] update query calls

    success: database layer working
    </task>
    </database-layer></agent>

  phase b - extract business logic (parallel):

    <agent><controllers-extractor>
    <agent-type>coder</agent-type>
    <files>
      <file>monolith.py</file>
    </files>
    <task>
    objective: extract controller logic from monolith.py

    context:
    - request handling mixed with business logic
    - need separate controller layer

    todo:
    [ ] identify controller methods
    [ ] extract to controllers/
    [ ] verify routing works

    success: controllers working
    </task>
    </controllers-extractor></agent>

  phase c - integration (sequential):

    <agent><facade-creator>
    <agent-type>coder</agent-type>
    <files>
      <file>monolith.py</file>
    </files>
    <task>
    objective: create facade.py that imports all extracted modules

    context:
    - all modules extracted in phase a and b
    - need to maintain original interface

    todo:
    [ ] create facade.py
    [ ] import all extracted modules
    [ ] delegate calls appropriately
    [ ] verify all tests pass

    success: all tests pass, no regressions
    </task>
    </facade-creator></agent>

  result: 7 agents deployed in ~2 hours vs weeks of sequential work
          85% file size reduction while maintaining 100% functionality

monitoring spawned agents:

  after spawning agents, check their status:
    <status></status>

  capture output from specific agent:
    <capture>models-extractor 50</capture>

  send message to running agent:
    <message to="models-extractor">also extract enum types</message>

  stop an agent:
    <stop>models-extractor</stop>

remember:

  [ok] spawn multiple agents in a single response
  [ok] each agent runs in its own tmux session
  [ok] agents complete when idle for 6 seconds
  [ok] results are injected back when agents finish
  [ok] use <agent-type> to select specialized agents (coder, research, etc.)
  [ok] use <skill> tags to load specific capabilities

  [x] don't spawn agents for serial/dependent tasks
  [x] don't spawn agents without investigation first
  [x] don't spawn agents without clear, concrete tasks
  [x] don't spawn more than 10 agents at once (system limits)
