Multi Agent Git Workflow

Multi-Agent Git Workflow

Coordinated parallel development with dynamic micro-task breakdown and on-demand agent spawning. The workflow reads the repo, decomposes the feature into atomic micro-tasks, spawns as many coding agents as needed (backend-1, backend-2, frontend-1, data-1, etc.), coordinates their work, and runs a continuous validation loop. This workflow stops only when the feature is fully done.

When to Use

• A feature requires work across multiple surfaces, files, or domains
• You want dynamic task decomposition instead of pre-assigned waves
• You need multiple coding agents working in parallel on independent micro-tasks
• You want continuous test/eval/quality loops that run until everything is green
• Feature specs live in docs/features/ (no Git issues required)
• Quality gates: tests pass, evals green, lint/format/type-check clean — then stop

Core Concepts

Full Workflow Diagram

[Input Source]
  Git Issue #N
  OR
  docs/features//*.md
            ↓
  [Repo Scanner] → Read entire repo, map surfaces, identify all affected areas
            ↓
  [Web Research Pipeline] → Search docs, blogs, RFCs, GitHub issues, Stack Overflow, Reddit
    ├─ [Web Researcher Agent]       → Search official docs, API refs, release notes
    ├─ [Community Researcher]       → Search Stack Overflow, GitHub issues, Reddit, blogs
    ├─ [Reddit Researcher Agent]    → Deep Reddit analysis: user experiences, war stories, sentiment, consensus
    ├─ [Competitive Analyst]        → Compare alternatives, benchmarks, trade-offs
    └─ [Security Scanner]           → Search CVE databases, advisories, dependency audits
            ↓
  [Micro-Task Decomposer] → Break feature into atomic micro-tasks
    Each micro-task:
      - Single responsibility (one file or one function)
      - Independent or has explicit dependency on another micro-task
      - Has acceptance criteria
      - Has estimated complexity (trivial/small/medium/large)
            ↓
  [Task Queue] → Prioritized list of all micro-tasks with dependencies
    micro-task-001: Create src/cache/schema.py — DEPS: none — TRIVIAL
    micro-task-002: Write tests for schema.py — DEPS: 001 — TRIVIAL
    micro-task-003: Implement Redis cache store — DEPS: 001 — SMALL
    micro-task-004: Implement FAISS similarity lookup — DEPS: 001 — MEDIUM
    micro-task-005: Write tests for cache store — DEPS: 003 — SMALL
    micro-task-006: Write tests for FAISS lookup — DEPS: 004 — SMALL
    micro-task-007: Integrate cache into /v1/chat endpoint — DEPS: 003,004 — MEDIUM
    micro-task-008: Add cache hit indicator to UI — DEPS: 007 — SMALL
    micro-task-009: Add E2E test for cache flow — DEPS: 007,008 — MEDIUM
    micro-task-010: Add cache metrics to observability — DEPS: 007 — SMALL
            ↓
  [Agent Spawner] → Spawn coding agents based on micro-task count and type
    backend-1, backend-2, backend-3  (Python/FastAPI work)
    frontend-1                       (React/UI work)
    data-1                           (Schema/migration work)
    test-1, test-2                   (Test writing work)
    Each agent gets 1-N micro-tasks based on dependency graph
            ↓
  [Parallel Execution] → Agents work on their micro-tasks simultaneously
    Each agent:
      1. Reads its assigned micro-task(s)
      2. Creates/modifies files per task spec
      3. Writes tests for the changes
      4. Runs lint, format, type-check locally
      5. Marks micro-task as DONE or BLOCKED
            ↓
  [Dependency Resolver] → When a micro-task completes, unlock dependents
    micro-task-001 DONE → unlock 002, 003, 004
    micro-task-003 DONE → unlock 005, 007 (if 004 also done)
    micro-task-004 DONE → unlock 006, 007 (if 003 also done)
    Newly unlocked tasks → assign to available agents
            ↓
  [Continuous Validation Loop] → NEVER STOPS until ALL gates pass
    ┌─────────────────────────────────────────────────┐
    │  1. [TDD Guide]     → Ensure every change has  ││
    │                          tests, RED→GREEN cycle ││
    │         ↓                                       │
    │  2. [Lint Check]    → ruff, black, eslint      │
    │         ↓                                       │
    │  3. [Format Check]  → Code formatted correctly  │
    │         ↓                                       │
    │  4. [Type Check]    → mypy, tsc --noEmit        │
    │         ↓                                       │
    │  5. [Test Suite]    → All unit + integration    │
    │                          tests pass             │
    │         ↓                                       │
    │  6. [E2E Tests]     → Playwright flows pass     │
    │         ↓                                       │
    │  7. [Eval Harness]  → Pass@k >= target          │
    │         ↓                                       │
    │  8. [Code Review]   → Quality review complete   │
    │         ↓                                       │
    │  9. [Security Scan] → No vulnerabilities        │
    │         ↓                                       │
    │  ┌───────────────────────────────────────┐      │
    │  │  ALL PASS? ──YES──→ Exit loop, merge  │      │
    │  │       │                               │      │
    │  │       NO                              │      │
    │  │       ↓                               │      │
    │  │  Identify failures                    │      │
    │  │  Route to responsible agent           │      │
    │  │  Agent applies fix                    │      │
    │  │  Return to step 1                     │      │
    │  └───────────────────────────────────────┘      │
    └─────────────────────────────────────────────────┘
            ↓
  [Git Agent] → Create branch, commit, PR, merge when loop exits

---

Input Sources

Option A: Git Issues

Read GitHub issue, extract requirements, acceptance criteria, affected surfaces.

Option B: Feature Specs (docs/features//*.md)

When Git issues are not available, use feature specs:

docs/features//
├── spec.md              # Feature description, requirements, acceptance criteria
├── requirements.md      # Detailed requirements with user stories (optional)
└── constraints.md       # Technical constraints (optional)

The coordinator reads from whichever source is available.

---

Step 1: Repo Scanner

Read the entire repository to build a complete surface map:

repo_scan_result = {
    "directories": {
        "agents/": ["planner.md", "architect.md", "code-reviewer.md", ...],
        "skills/": ["tdd-workflow/", "code-review/", "security-review/", ...],
        "commands/": ["build-fix.md", "code-review.md", ...],
        "src/": ["api/", "models/", "services/", "cache/", ...],
        "tests/": ["unit/", "integration/", "e2e/"],
        # ... all directories and files
    },
    "dependencies": {
        "python": ["fastapi==0.109.0", "pydantic==2.5.0", "sqlalchemy==2.0.25", ...],
        "node": ["react@18.2.0", "typescript@5.3.0", "zod@3.22.0", ...],
    },
    "existing_surfaces": {
        "api_endpoints": ["/v1/chat", "/v1/users", "/v1/markets", ...],
        "models": ["User", "Market", "Chat", ...],
        "components": ["ChatMessage", "UserCard", "MarketList", ...],
        "tests": {"unit_count": 142, "integration_count": 23, "e2e_count": 8},
        "coverage": {"line": 0.78, "branch": 0.65},
    },
    "affected_by_feature": [
        "src/api/v1/chat.py",          # needs cache middleware
        "src/cache/",                  # new directory
        "tests/unit/test_semantic_cache.py",  # new test
        "tests/integration/test_cache_endpoint.py",  # new test
    ],
}

---

Step 1b: Web Research Pipeline

After the repo scan, the web research pipeline runs in parallel to gather external knowledge. This runs BEFORE micro-task decomposition so that findings inform the task breakdown.

Parallel Research Agents

[Web Research Pipeline] — 5 agents running in parallel:

  1. [Web Researcher Agent]
     Sources: Official docs, API references, release notes, changelogs
     Tools: web_search, web_fetch
     Outputs: .workflow//research/web-research.md

  2. [Community Researcher Agent]
     Sources: Stack Overflow, GitHub issues, dev blogs, Hacker News
     Tools: web_search, web_fetch
     Outputs: .workflow//research/community-research.md

  3. [Reddit Researcher Agent]
     Sources: Reddit (r/programming, r/Python, r/typescript, r/webdev, framework-specific subs)
     Tools: web_search, web_fetch
     Outputs: .workflow//research/reddit-research.md
     Focus: Real user experiences, production war stories, sentiment, consensus

  4. [Competitive Analyst Agent]
     Sources: Alternative implementations, benchmarks, trade-off analyses
     Tools: web_search, web_fetch
     Outputs: .workflow//research/competitive-analysis.md

  5. [Security Scanner Agent]
     Sources: CVE databases, npm audit, pip-audit, GitHub advisories
     Tools: web_search, Bash (npm audit, pip-audit, trivy)
     Outputs: .workflow//research/security-audit.md

Web Research Agent

The Web Researcher Agent searches for official documentation, API references, and release notes:

web_researcher_config:
  search_queries:
    - "   official documentation"
    - "  API reference"
    - "  changelog release notes"
    - " best practice "
  sources_trusted:
    - Official documentation sites (docs.djangoproject.com, fastapi.tiangolo.com, react.dev)
    - GitHub repositories (official org repos)
    - RFCs and standards documents
    - Official blogs and release announcements
  sources_distrusted:
    - Random blogs without authorship
    - AI-generated content without citations
    - Outdated content (>2 versions old)
  output_format:
    - Finding: What was found
    - Source: URL
    - Confidence: high/medium/low
    - Relevance: How it applies to our feature
    - Code Example: If applicable

Community Researcher Agent

The Community Researcher Agent searches for real-world experience outside Reddit (which has its own dedicated agent):

community_researcher_config:
  search_queries:
    - "  Stack Overflow"
    - "github.com / issues  bug"
    - " gotcha pitfall workaround"
    - " production experience lessons learned"
  focus_areas:
    - Common bugs and their fixes
    - Performance gotchas
    - Migration experiences
    - Production war stories
    - Alternative approaches the team didn't consider
  exclude_sources:
    - reddit.com  # handled by dedicated Reddit Researcher Agent
  output_format:
    - Problem: What issue people encountered
    - Solution: How they fixed it
    - Source: URL (Stack Overflow, GitHub issue, blog)
    - Consensus: Do multiple sources agree?

Reddit Researcher Agent

The Reddit Researcher Agent does deep analysis of Reddit threads for ground-level practitioner knowledge:

reddit_researcher_config:
  search_queries:
    - "site:reddit.com   experience production"
    - "site:reddit.com  real world review"
    - "site:reddit.com  vs  comparison"
    - "site:reddit.com  gotcha pitfall regret"
    - "site:reddit.com  worth it "
  target_subreddits:
    - r/programming
    - r/Python
    - r/typescript
    - r/webdev
    - r/devops
    - r/machinelearning
    - Framework-specific subs (r/FastAPI, r/reactjs, r/node, r/PostgreSQL)
  analysis_dimensions:
    - Sentiment: positive / neutral / negative
    - Consensus: strong agreement / mixed / strong disagreement
    - Production evidence: yes/no (did commenter deploy this at scale?)
    - Recency: within 12 months / older (flag if outdated)
    - Severity: data loss / security / performance / inconvenience
  output_format:
    - Summary: 2-3 sentence overview of community sentiment
    - Key findings with direct quotes from top comments
    - Gotchas table with severity ratings
    - Community consensus table (Do it / Don't / Depends)
    - Notable dissenting opinions
    - Production war stories

Competitive Analyst Agent

The Competitive Analyst Agent compares alternative approaches:

competitive_analyst_config:
  search_queries:
    - " approach A vs approach B"
    - " vs  comparison benchmark"
    - " performance comparison"
  analysis_dimensions:
    - Performance (benchmarks, latency, throughput)
    - Developer experience (API ergonomics, learning curve)
    - Maturity (release history, adoption, community)
    - Maintenance (active development, issue resolution time)
    - Licensing (MIT, Apache, GPL, commercial)
  output_format:
    - Comparison table with scored dimensions
    - Recommendation with rationale
    - Trade-offs clearly stated

Security Scanner Agent

The Security Scanner Agent checks for vulnerabilities in any new dependencies:

security_scanner_config:
  methods:
    - web_search: " CVE vulnerability "
    - Bash: "npm audit" (Node.js projects)
    - Bash: "pip-audit" (Python projects)
    - Bash: "trivy fs ." (filesystem scan)
    - web_fetch: GitHub Security Advisories for the package
  check_scope:
    - Direct dependencies
    - Transitive dependencies (2 levels deep)
    - Known CVEs in the past 12 months
    - Unmaintained packages (no release in 12+ months)
  output_format:
    - Package: name + version
    - Vulnerability: CVE ID, severity, description
    - Fix: Upgrade path or workaround
    - Risk: high/medium/low

Research Synthesis

After all 4 agents complete, their findings are synthesized:

# Research Synthesis: 

## Official Documentation (Web Researcher)
- 

## Community Knowledge (Community Researcher)
- 

## Reddit Sentiment (Reddit Researcher)
- 
- 
- 

## Competitive Landscape (Competitive Analyst)
- 

## Security Assessment (Security Scanner)
- 

## Synthesized Recommendation
Based on all research, the recommended approach is:
   because .

## Risks to Address in Implementation
-  — mitigation: 
-  — mitigation: 

## References
- [Official docs](URL)
- [Stack Overflow](URL)
- [Reddit thread](URL)
- [Benchmark comparison](URL)
- [CVE advisory](URL)

This synthesis feeds directly into the Micro-Task Decomposer, ensuring tasks are informed by real-world data, security findings, and the best available approach.

---

Step 2: Micro-Task Decomposer

Break the feature into atomic micro-tasks — each with a single responsibility:

# .workflow//micro-tasks.yaml
feature: semantic-caching
micro_tasks:
  # Phase 0: Foundation (no dependencies)
  - id: MT-001
    description: "Create src/cache/__init__.py with public exports"
    type: create
    files: ["src/cache/__init__.py"]
    deps: []
    complexity: trivial
    surface: python

  - id: MT-002
    description: "Create CacheEntry dataclass with serialization"
    type: create
    files: ["src/cache/schema.py"]
    deps: []
    complexity: small
    surface: python

  - id: MT-003
    description: "Implement Redis-backed cache store with TTL and LRU"
    type: create
    files: ["src/cache/store.py"]
    deps: [MT-002]
    complexity: medium
    surface: python

  # Phase 1: Core logic (depends on foundation)
  - id: MT-004
    description: "Implement SemanticCache class with FAISS similarity"
    type: create
    files: ["src/cache/semantic_cache.py"]
    deps: [MT-002]
    complexity: medium
    surface: python

  - id: MT-005
    description: "Write unit tests for CacheEntry"
    type: test
    files: ["tests/unit/test_cache_schema.py"]
    deps: [MT-002]
    complexity: trivial
    surface: python-test

  - id: MT-006
    description: "Write unit tests for cache store"
    type: test
    files: ["tests/unit/test_cache_store.py"]
    deps: [MT-003]
    complexity: small
    surface: python-test

  - id: MT-007
    description: "Write unit tests for SemanticCache"
    type: test
    files: ["tests/unit/test_semantic_cache.py"]
    deps: [MT-004]
    complexity: small
    surface: python-test

  # Phase 2: Integration (depends on core)
  - id: MT-008
    descript

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [noah-sheldon](https://github.com/noah-sheldon)
- **Source:** [noah-sheldon/ai-dev-kit](https://github.com/noah-sheldon/ai-dev-kit)
- **License:** MIT
- **Homepage:** https://noahsheldon.dev

Install and usage instructions live in the source repository linked above.