Skip to content
This repository was archived by the owner on Apr 11, 2026. It is now read-only.

CODEBASE_MAP.md

Latest commit

 

History

History
343 lines (294 loc) · 14.5 KB

CODEBASE_MAP.md

File metadata and controls

343 lines (294 loc) · 14.5 KB
last_mapped 2026-04-03 00:00:00 UTC
total_files 120
total_tokens 219407

Codebase Map

Auto-generated by /flow-code:map. Last mapped: 2026-04-03T00:00:00Z

System Overview

graph TB
    subgraph Commands["Commands (13)"]
        CMD["/flow-code:*"]
    end

    subgraph Skills["Skills (18)"]
        PLAN[plan]
        WORK[work]
        INTERVIEW[interview]
        PRIME[prime]
        IMPL_REV[impl-review]
        PLAN_REV[plan-review]
        EPIC_REV[epic-review]
        RALPH_INIT[ralph-init]
        AUTO_IMPROVE[auto-improve]
        MAP[map]
        SETUP[setup]
        SYNC[sync]
        DEPS[deps]
        EXPORT[export-context]
        RP_EXPLORER[rp-explorer]
        WORKTREE[worktree-kit]
        BROWSER[browser]
        FC[flow-code]
    end

    subgraph Agents["Agents (20)"]
        WORKER[worker]
        SCOUTS["9 Research Scouts"]
        PRIME_SCOUTS["8 Prime Scouts"]
        PLAN_SYNC[plan-sync]
        GAP[flow-gap-analyst]
        QA[quality-auditor]
    end

    subgraph Core["Core Engine"]
        FLOWCTL["flowctl/ package"]
        FLOW_DIR[".flow/ state"]
    end

    subgraph Autonomous["Autonomous Harnesses"]
        RALPH["ralph.sh"]
        AI_LOOP["auto-improve.sh"]
    end

    CMD --> Skills
    PLAN --> SCOUTS
    PLAN --> GAP
    PRIME --> PRIME_SCOUTS
    MAP --> SONNET["Sonnet subagents"]
    WORK --> WORKER
    WORKER --> IMPL_REV
    WORK --> PLAN_SYNC
    WORK --> EPIC_REV

    RALPH --> PLAN_REV
    RALPH --> WORK
    RALPH --> EPIC_REV

    Skills --> FLOWCTL
    Agents --> FLOWCTL
    FLOWCTL --> FLOW_DIR
Loading

Directory Structure

flow-code/
├── .claude-plugin/
│   ├── marketplace.json          # Marketplace listing (source: "./")
│   └── plugin.json               # Plugin metadata (v0.1.0)
├── agents/                       # 20 subagent definitions
│   ├── worker.md                 # Task implementer (inherit model)
│   ├── repo-scout.md             # Grep/glob pattern finder (opus)
│   ├── context-scout.md          # RepoPrompt deep explorer (opus)
│   ├── practice-scout.md         # Best practices researcher (opus)
│   ├── docs-scout.md             # External docs fetcher (opus)
│   ├── github-scout.md           # Cross-repo pattern searcher (opus)
│   ├── quality-auditor.md        # Code review auditor (opus)
│   ├── flow-gap-analyst.md       # Edge case/gap finder (opus)
│   ├── plan-sync.md              # Drift detection + spec updater (opus)
│   ├── build-scout.md            # Build system assessor (sonnet)
│   ├── env-scout.md              # Environment setup checker (sonnet)
│   ├── testing-scout.md          # Test infra assessor (sonnet)
│   ├── tooling-scout.md          # Lint/format checker (sonnet)
│   ├── claude-md-scout.md        # CLAUDE.md quality scorer (sonnet)
│   ├── docs-gap-scout.md         # Doc update need finder (sonnet)
│   ├── epic-scout.md             # Inter-epic dependency finder (sonnet)
│   ├── memory-scout.md           # Past learnings retriever (sonnet)
│   ├── observability-scout.md    # Logging/tracing checker (sonnet)
│   ├── security-scout.md         # GitHub security checker (sonnet)
│   └── workflow-scout.md         # CI/CD assessor (sonnet)
├── commands/flow-code/           # 13 command facades (thin stubs → skills)
│   ├── plan.md, work.md, interview.md, prime.md
│   ├── impl-review.md, plan-review.md, epic-review.md
│   ├── ralph-init.md, auto-improve.md, map.md
│   ├── setup.md, sync.md, uninstall.md
├── skills/                       # 18 skill implementations
│   ├── flow-code/                # Task CRUD via flowctl
│   ├── flow-code-run/            # Unified pipeline entry point (phase loop)
│   ├── flow-code-interview/      # SKILL.md + questions.md
│   ├── flow-code-prime/          # SKILL.md + workflow.md + pillars.md + remediation.md
│   ├── flow-code-ralph-init/     # SKILL.md + templates/ (ralph.sh, config.env, prompts)
│   ├── flow-code-auto-improve/   # SKILL.md + templates/ (auto-improve.sh, programs/)
│   ├── flow-code-map/            # SKILL.md + scripts/scan-codebase.py
│   ├── flow-code-setup/          # SKILL.md + workflow.md + templates/
│   ├── flow-code-sync/           # SKILL.md
│   ├── flow-code-deps/           # SKILL.md
│   ├── flow-code-export-context/ # SKILL.md
│   ├── flow-code-rp-explorer/    # SKILL.md + cli-reference.md
│   ├── flow-code-worktree-kit/   # SKILL.md + scripts/worktree.sh
│   └── browser/                  # SKILL.md + references/
├── scripts/
│   ├── flowctl                   # Shell wrapper → flowctl.py
│   ├── flowctl.py                # Thin shim (~20 lines) → flowctl package
│   ├── flowctl/                 # Core engine package
│   │   ├── __init__.py           # __version__ only
│   │   ├── __main__.py           # python -m flowctl support
│   │   ├── compat.py             # fcntl/Windows platform abstraction
│   │   ├── cli.py                # argparse setup + command dispatch
│   │   ├── core/                 # Shared utilities
│   │   │   ├── constants.py, io.py, ids.py, config.py
│   │   │   ├── paths.py, state.py, git.py
│   │   └── commands/             # Command handlers
│   │       ├── admin.py, epic.py, task.py, workflow.py
│   │       ├── query.py, memory.py, rp.py, findings.py
│   │       ├── stack.py, gap.py
│   │       └── review/           # Review subpackage
│   │           ├── __init__.py, commands.py, prompts.py
│   │           ├── adversarial.py, checkpoint.py, codex_utils.py
│   ├── hooks/
│   │   ├── flowctl hook auto-memory  # Stop hook: transcript → .flow/memory/
│   │   └── flowctl hook ralph-guard  # Ralph workflow enforcer (Rust)
│   ├── smoke_test.sh             # Quick flowctl sanity test
│   ├── ci_test.sh                # Comprehensive CI test suite
│   └── ralph_*.sh                # Ralph smoke/e2e test scripts
├── hooks/
│   └── hooks.json                # Plugin hook registrations
├── docs/
│   ├── CODEBASE_MAP.md           # This file
│   ├── flowctl.md                # CLI reference
│   ├── ralph.md                  # Ralph architecture guide
│   └── ci-workflow-example.yml   # GitHub Actions template
├── README.md                     # English documentation
└── README_CN.md                  # Chinese documentation

Module Guide

flowctl/ — Core Engine Package

Purpose: Single authoritative package for all .flow/ state mutations. Entry point: scripts/flowctl.py (thin shim) via scripts/flowctl (shell wrapper) Structure: flowctl/cli.py dispatches to flowctl/commands/* modules using flowctl/core/* utilities

Key responsibilities:

  • Epic/task CRUD and state machine (todo → in_progress → done/blocked)
  • Dependency resolution and task scheduling (flowctl next)
  • Review status tracking (plan_review_status, completion_review_status)
  • Memory system (memory add/list/init/search)
  • RepoPrompt and Codex CLI wrappers (rp chat-send, codex impl-review)
  • Worker prompt generation and phase-gate execution (worker-prompt, worker-phase)
  • Ralph control signals (pause/resume/stop via sentinel files)
  • Checkpoint save/restore for long operations
  • CI validation (validate --all)

Used by: Every agent, every skill, ralph.sh, auto-improve.sh, all hooks.

agents/ — 20 Subagents

Tier Model Count Agents Invoked By
Research opus 6 worker, repo-scout, context-scout, practice-scout, docs-scout, github-scout plan, work
Analysis opus 3 quality-auditor, flow-gap-analyst, plan-sync plan, work, review
Prime sonnet 8 build/env/testing/tooling/claude-md/observability/security/workflow scouts prime
Context sonnet 3 docs-gap-scout, epic-scout, memory-scout plan

Parallelism patterns:

  • Plan fan-out: 7 scouts fire simultaneously in one Task call
  • Prime fan-out: 8 scouts fire simultaneously
  • Map fan-out: N Sonnet subagents based on token budget
  • Worker isolation: One worker per task, fresh context, disallowedTools: Task

skills/ — 18 Skills

Category Skills Purpose
Core lifecycle plan, work, interview Spec → tasks → implementation
Review gates impl-review, plan-review, epic-review Carmack-level review with fix loops
Autonomous ralph-init, auto-improve Overnight loops (task execution / code optimization)
Assessment prime 8-pillar agent readiness (48 criteria)
Utilities setup, sync, map, deps, export-context, rp-explorer, worktree-kit, browser, flow-code Supporting tools

hooks/ — Event Lifecycle

PreToolUse (Bash|Execute, Edit|Write)
    └── flowctl hook ralph-guard — blocks invalid commands during Ralph runs

PostToolUse (Bash|Execute)
    └── flowctl hook ralph-guard — tracks state (verdicts, receipts, done calls)

Stop
    ├── flowctl hook ralph-guard — blocks stop if receipt missing
    └── flowctl hook auto-memory — extracts learnings via Gemini → .flow/memory/

SubagentStop
    └── flowctl hook ralph-guard — same as Stop

All hooks are conditional — no-op if guard/memory files don't exist.

Data Flow

Core Lifecycle

sequenceDiagram
    participant User
    participant Interview
    participant Plan
    participant Scouts
    participant Work
    participant Worker
    participant Review
    participant flowctl

    User->>Interview: /flow-code:interview
    Interview->>flowctl: epic set-plan (refined spec)

    Note over User,flowctl: Preferred: /flow-code:go fn-N (unified pipeline)
    User->>Run: /flow-code:go "description"
    loop flowctl phase next/done
        Run->>flowctl: phase next --epic fn-N --json
        flowctl-->>Run: {phase, prompt, all_done}
        alt phase = plan
            Run->>Scouts: research scouts in parallel
            Scouts-->>Run: patterns, docs, gaps
            Run->>flowctl: epic plan + task create
        else phase = work
            Run->>Worker: spawn workers (Teams + worktree)
            Worker->>flowctl: worker-phase next/done loop
            Worker->>flowctl: done (summary + evidence)
        end
        Run->>flowctl: phase done --epic fn-N --phase X
    end
Loading

Ralph Autonomous Loop

sequenceDiagram
    participant ralph.sh
    participant Claude
    participant flowctl

    ralph.sh->>flowctl: next --json
    flowctl-->>ralph.sh: {status: plan/work/completion_review}

    alt status = plan
        ralph.sh->>Claude: prompt_plan.md (new process)
        Claude->>Claude: /flow-code:go (plan phase)
    else status = work
        ralph.sh->>Claude: prompt_work.md (new process)
        Claude->>Claude: /flow-code:go (work phase)
    else status = completion_review
        ralph.sh->>Claude: prompt_completion.md (new process)
        Claude->>Claude: /flow-code:go (close phase)
    end

    Claude-->>ralph.sh: exit (verdict in log)
    ralph.sh->>ralph.sh: parse verdict, verify receipt, log
Loading

Auto-Improve Experiment Loop

sequenceDiagram
    participant auto-improve.sh
    participant Claude
    participant Git

    auto-improve.sh->>Git: save checkpoint (HEAD)
    auto-improve.sh->>Claude: prompt_experiment.md (new process)
    Claude->>Claude: read program.md + history
    Claude->>Claude: discover + implement + guard
    Claude-->>auto-improve.sh: <result>keep/discard</result>

    alt keep
        auto-improve.sh->>auto-improve.sh: verify guard passes
        auto-improve.sh->>Git: add -A && commit
    else discard / crash
        auto-improve.sh->>Git: reset --hard checkpoint
    end
    auto-improve.sh->>auto-improve.sh: log to experiments.jsonl
Loading

Conventions

  • flowctl-only writes: All .flow/ mutations through flowctl, never direct file edits
  • Bundled CLI: $FLOWCTL always from ${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl, never which flowctl
  • Command → Skill routing: Every command is a thin stub that delegates to a matching skill
  • Parallel scout dispatch: All scouts must launch in ONE Task call, never sequential
  • Worker isolation: One worker per task, fresh context, disallowedTools: Task
  • Re-anchor before every fix: Re-read flowctl show/cat before each review fix iteration
  • Promise tag protocol: <promise>RETRY|FAIL|COMPLETE</promise> for Ralph control
  • Template scaffold + preserve: Init copies templates; update preserves user-edited config
  • Backend priority chain: --review flag > FLOW_REVIEW_BACKEND env > .flow/config.json > error

Gotchas

  • flowctl.py uses datetime.utcnow() (deprecated in Python 3.12+) — expect DeprecationWarning
  • which flowctl will always fail — it's bundled, not installed globally
  • Ralph hooks only activate when FLOW_RALPH=1 AND bin/flowctl exists
  • Auto-memory hook timeout is 45s (Gemini call) — can slow session exit
  • scan-codebase.py requires tiktoken — use uv run for auto-install or pip install tiktoken
  • Worker has disallowedTools: Task — cannot spawn sub-agents (prevents infinite nesting)
  • Review receipts require exact JSON schema: {"type","id","mode","timestamp","iteration"}
  • ref/ directory contains reference repos (not part of the plugin) — exclude from scans

Navigation Guide

To add a new command: Create commands/flow-code/<name>.md (thin stub) + skills/flow-code-<name>/SKILL.md To add a new agent: Create agents/<name>.md with frontmatter (name, description, model, disallowedTools) To add a new scout to planning: Add to the scout dispatch in skills/flow-code-run/SKILL.md plan phase To add a new prime pillar: Add criteria to skills/flow-code-prime/pillars.md, remediation to remediation.md To modify Ralph loop: Edit skills/flow-code-ralph-init/templates/ralph.sh (canonical source) To modify auto-improve loop: Edit skills/flow-code-auto-improve/templates/auto-improve.sh To add a review backend: Add to flowctl review-backend and the review phase in skills/flow-code-run/SKILL.md To change task state machine: Modify flowctl/crates/flowctl-core/src/state_machine.rs