feat: Refine and expand claude-flow agentic platform components, documentation, and tooling across v2 and v3, including new research analysis.

Author: deepakdgupta1

.gitignore

@@ -126,3 +126,16 @@ tests/artifacts/
 
 # Stray bv/CLI artifacts (malformed flag creates files like --graph-format.svg)
 --graph-format*
+
+# ----- ACFS specific -----
+# Ignore any local overrides or sensitive data
+*.local
+*.override
+*.secret
+
+# Ignore any local test data
+test_data/
+test_output/
+
+# Ignore any local research data
+docs/research/preprocessed

docs/acfs-workflow.md

@@ -0,0 +1,234 @@
+# ACFS Workflow: Building a New Project
+
+A prescribed sequence of steps and commands for using the Agentic Coding Flywheel Setup (ACFS) to build a new application.
+
+---
+
+## Overview: The Flywheel Loop
+
+ACFS structures development around a compounding loop rather than a linear flow:
+
+```
+Plan (Beads) --> Coordinate (Agent Mail) --> Execute (NTM + Agents)
+      ^                                              |
+      |                                              v
+      +---- Remember (CASS Memory) <---- Scan (UBS) +
+```
+
+Each tool in the chain handles one ring of this loop:
+- **`br`/`bd`** — Plan and track work
+- **`ntm`** — Orchestrate agents
+- **`ubs`** — Guard code quality
+- **`cass`/`cm`** — Preserve memory across sessions
+
+---
+
+## Phase 1 — Initialize the Project
+
+```bash
+acfs newproj event-management --interactive
+cd /data/projects/event-management
+```
+
+This scaffolds: `.git/`, `.beads/`, `.claude/`, and a project-specific `AGENTS.md`.
+
+> **Do not skip flags** like `--no-br` or `--no-claude` — they omit essential agent infrastructure.
+
+Alternative forms:
+
+```bash
+acfs newproj my-project            # Non-interactive
+acfs newproj my-project ~/code     # Custom directory
+```
+
+---
+
+## Phase 2 — Set Up Issue Tracking (Beads)
+
+```bash
+bd init
+git branch beads-sync main
+git push -u origin beads-sync
+bd config set sync.branch beads-sync
+```
+
+The dedicated `beads-sync` branch prevents worktree conflicts when agents later push Beads state.
+
+---
+
+## Phase 3 — Create Your Initial Tasks
+
+```bash
+br create "Feature: Event creation and management" --priority=1
+br create "Feature: Attendee registration" --priority=2
+br create "Feature: Calendar and scheduling" --priority=3
+```
+
+Check what is unblocked at any time:
+
+```bash
+br ready           # List tasks with no blockers
+bv --robot-triage  # Dependency graph + priority analysis
+```
+
+---
+
+## Phase 4 — Spawn Agents
+
+```bash
+ntm spawn event-management --cc=2 --cod=1 --gmi=1
+ntm attach event-management
+```
+
+### Agent flags
+
+| Flag | Agent |
+|------|-------|
+| `--cc=N` | Claude Code (N instances) |
+| `--cod=N` | Codex CLI |
+| `--gmi=N` | Gemini CLI |
+| `--amp=N` | Amp (reasoning-heavy tasks) |
+
+---
+
+## Phase 5 — The Flywheel Loop (During Development)
+
+### 5a. Get context and send to agents
+
+```bash
+cm context "Build event registration system" --json
+ntm send event-management "Let's build the event registration feature. [paste context]"
+```
+
+### 5b. Track progress
+
+```bash
+br list --status=open
+br update <id> --status=in_progress
+br show <id>
+```
+
+### 5c. Multi-agent file coordination (via MCP Agent Mail)
+
+Prevents conflicts between agents working on the same files:
+
+```
+ensure_project(project_key=...)
+register_agent(...)
+file_reservation_paths(..., ["src/**"], exclusive=true)
+send_message(..., thread_id="br-123", subject="[br-123] Starting work", ack_required=true)
+```
+
+### 5d. Scan staged files before every commit
+
+```bash
+ubs $(git diff --name-only --cached)
+```
+
+---
+
+## Phase 6 — Land the Plane (Session Completion)
+
+This sequence is **mandatory** at the end of every session, in order:
+
+```bash
+# 1. File any remaining work
+br create "Follow-up: Add iCal export"
+
+# 2. Run quality gates (TypeScript/Bun example)
+bun run type-check && bun run lint && bun test
+
+# 3. Close completed issues
+br close <id> --reason "Completed"
+br close <id1> <id2> <id3>   # Close multiple at once
+
+# 4. Export Beads state (no git operations)
+br sync --flush-only
+
+# 5. Push everything — work is NOT done until this succeeds
+git pull --rebase
+git add .beads/ src/
+git commit -m "feat: event registration system"
+git push
+git status   # Must show "up to date with origin"
+```
+
+> **Critical:** Work is **not complete** until `git push` succeeds. Agents that stop before pushing leave work stranded locally.
+
+---
+
+## Full Command Chain (Quick Reference)
+
+```bash
+# 1. Initialize project
+acfs newproj event-management --interactive
+cd /data/projects/event-management
+
+# 2. Set up Beads
+bd init
+git branch beads-sync main
+git push -u origin beads-sync
+bd config set sync.branch beads-sync
+
+# 3. Create initial tasks
+br create "Feature: Event management" --priority=1
+
+# 4. Spawn agents
+ntm spawn event-management --cc=2 --cod=1
+ntm attach event-management
+
+# 5. Flywheel loop...
+ubs $(git diff --name-only --cached)
+
+# 6. Land the plane
+br close 1 --reason "Completed"
+br sync --flush-only
+git pull --rebase
+git add .beads/ src/
+git commit -m "feat: event management system"
+git push
+git status
+```
+
+---
+
+## Tool Reference
+
+| Purpose | Command | Notes |
+|---------|---------|-------|
+| Project creation | `acfs newproj` | Creates full agent-ready scaffold |
+| Agent orchestration | `ntm spawn`, `ntm attach`, `ntm send` | Start and coordinate agent sessions |
+| Task planning | `br ready`, `br create`, `br close` | Unblocked task list and lifecycle |
+| Beads sync | `br sync --flush-only` | Export state without git operations |
+| Graph analysis | `bv --robot-triage`, `bv --robot-plan` | Dependency and priority analysis |
+| Code quality | `ubs <files>` | Scan for bugs before committing |
+| Session search | `cass search` | Find previous solutions |
+| Agent memory | `cm context "<task>"` | Get relevant context from past work |
+| Account switching | `caam activate` | Switch between agent credentials |
+| Safety guard | `dcg test "<cmd>"` | Test if a command would be blocked |
+
+---
+
+## Critical Constraints
+
+1. Never use `acfs newproj --no-br`, `--no-claude`, or `--no-agents` — these skip essential setup.
+2. Always use interactive mode on first run: `acfs newproj -i`.
+3. Work is incomplete until `git push` succeeds.
+4. Never delete files without explicit permission.
+5. Always run quality checks (tests, linter, type checks) before committing.
+
+---
+
+## Project Directory Structure
+
+After `acfs newproj`, your project looks like:
+
+```
+/data/projects/my-project/
+├── .git/        # Git repository
+├── .beads/      # Beads issue tracking database
+├── .claude/     # Claude Code project settings
+├── AGENTS.md    # Instructions for AI agents
+├── .gitignore   # Standard ignores for project type
+└── [your code files]
+```

docs/research/claude-flow

@@ -0,0 +1 @@
+Subproject commit 8a89fc1ac4bb9c74438e0724ef7081431908ec09