FlashFusion Source-of-Truth Monorepo

Status: MVP → Beta Transition | Score: 78/100 | Version: 1.0.0

Unified consolidation of 54 repositories across the FlashFusion ecosystem into a production-ready monorepo with comprehensive tooling, documentation, and CI/CD.

Overview

This monorepo serves as the Source-of-Truth (SoT) for all FlashFusion projects, tools, and agents. It uses a SoT canonical ownership model where all changes are made here and pushed to downstream mirrors.

Key Highlights

✅ Production Infrastructure: Complete CI/CD with automated security scanning
✅ Excellent Documentation: 95/100 score with comprehensive guides
✅ Strong Security: No critical vulnerabilities, automated dependency updates
✅ Modern Stack: pnpm workspaces, Turborepo, TypeScript 5.4+, React 19
✅ Consolidation Complete: 51/54 repos imported (94%), 3 unavailable
✅ Agent Framework: Unified AI agent architecture - All 4 agents implemented (Claude, Gemini, GitHub, Codex)

Repository Count

• Local repos: 4 (flashfusion-consolidated, HarvestFlow, INT-Smart-Triage-AI-2.0, MCP-Cloud-Demo)
• Krosebrook: 34 repos (all imported)
• flashfusionv1: 5 repos (3 unavailable/deleted)
• ChaosClubCo: 8 repos (all imported)
• Total: 54 repositories (51 imported, 3 unavailable)

Structure

source-of-truth-monorepo/
├── projects/                    # All project code
│   ├── local/                   # Local-only repos
│   ├── krosebrook/              # Krosebrook org repos
│   │   ├── core/                # Core FlashFusion projects
│   │   ├── apps/                # Applications
│   │   └── tools/               # Development tools
│   ├── flashfusionv1/           # FlashFusionv1 org repos
│   └── chaosclubco/             # ChaosClubCo org repos
├── agents/                      # AI agent implementations
│   ├── claude-agent/
│   ├── codex-agent/
│   ├── gemini-agent/
│   └── github-agent/
├── shared/                      # Shared utilities
│   ├── auth/                    # Authentication & authorization
│   ├── contracts/               # Agent output schemas
│   ├── logging/                 # Structured logging
│   ├── otel/                    # Observability (OTEL)
│   └── workflows/               # CI/CD utilities
└── .github/                     # GitHub workflows

Tech Stack

• Package Manager: pnpm 9.x
• Build Tool: Turbo
• Versioning: Changesets (independent package versions)
• CI/CD: GitHub Actions
• Security: gitleaks, Renovate, pnpm audit
• Observability: Structured JSON logs, OTEL-ready

Quick Start

Prerequisites

• Node.js 20+
• pnpm 9+

Installation

# Clone the repository
git clone git@github.com:Krosebrook/source-of-truth-monorepo.git
cd source-of-truth-monorepo

# Install dependencies (includes security patches)
pnpm install

# Run all quality checks
pnpm format:check
pnpm lint
pnpm type-check

# Build all projects
pnpm build

# Run tests with coverage
pnpm test:coverage

Development

# Start dev mode for all projects
pnpm dev

# Build only changed projects
pnpm build --filter=...[HEAD^]

# Lint specific project
pnpm --filter @flashfusion/project-name lint

Consolidating Additional Repositories

This monorepo includes an automated consolidation script to import additional repositories from GitHub.

Quick Start

cd scripts

# Install dependencies
pip install -r requirements.txt

# Set GitHub token
export GITHUB_TOKEN=your_github_token

# Test with dry-run
python consolidate.py --phase 1 --dry-run

# Execute consolidation
python consolidate.py --phase 1

Features

• ✅ Fetches all repos from GitHub user (currently configured for Krosebrook)
• ✅ Filters by language (JS/TS, Python, Java, C#, PHP, HTML/CSS)
• ✅ Auto-categorizes into apps/services/libraries/tools/etc.
• ✅ Progress tracking with real-time progress bars
• ✅ Error handling and resume capability
• ✅ Dry-run mode for testing
• ✅ Generates inventory and summary reports
• ✅ Optional: Archive old repos after verification (Phase 2)

Full Documentation: scripts/CONSOLIDATION_README.md
Quick Start Guide: scripts/QUICK_START.md

Ownership Model

SoT Canonical (default for all projects):

• All development happens in this monorepo
• Changes are pushed to downstream mirrors via git subtree split
• Never commit directly to mirror repos

CI/CD

Workflows

• CI (ci.yml): Runs lint, build, test on every push/PR
• Security (security.yml): gitleaks scan + dependency audit
• Subtree Push (subtree-push.yml): Pushes changes to 50 mirrors (requires deploy keys)
  • Status: ✅ Infrastructure Complete - Ready for Activation
  • Activation Guide: Quick Start
  • Setup Guide: Configure Deploy Keys
  • Validation: Run ./scripts/validate-setup.sh

Turbo Caching

Turbo caches build outputs to speed up CI. Only changed projects + dependencies are rebuilt.

GitHub Copilot Custom Agents 🎯

NEW: 17 specialized AI agents with intelligent auto-selection!

The repository includes production-ready GitHub Copilot Custom Agents implementing the Symphony of Roles architecture:

Agent Auto-Selection

Simply describe what you need and GitHub Copilot recommends the right agent:

"Fix SQL injection vulnerability" → @security-agent
"Write user stories for payments" → @product-agent
"Debug authentication error" → @debug-agent

Learn more: Agent Auto-Selection Guide

All 17 Agents

• Discovery: Visionary, Analyst, Product
• Design: UX, UI
• Build: Mobile, Database, API
• Release: Test, Deploy, Security
• Growth: Growth
• Cross-Phase: Docs, Review, Refactor, Debug, Automation

Full Documentation: .github/agents/README.md

---

Agent Parity

All agents (Claude, Codex, Gemini, GitHub Agent) follow unified contracts:

CLI Flags

agent-cli --prompt <path> --context <path> --output-schema <path> --out <dir>

Output Schema

All agents output JSON conforming to shared/contracts/agent-output.schema.json.

See: shared/contracts/README.md

GitHub Copilot Agent Auto-Select 🤖

NEW: Automatic agent suggestions based on your file changes!

When you create a pull request, our AI system automatically analyzes your changed files and suggests the most relevant GitHub Copilot agents to help you:

• 🔍 Automatic Detection: Workflow analyzes PR file changes
• 💬 Smart Suggestions: Top 5 agents ranked by relevance
• 🛠️ Local Tool: CLI utility for pre-PR suggestions
• ⚙️ Configurable: Pattern-based matching system

Quick Start:

# Get agent suggestions for your current changes
node .github/scripts/suggest-agents.cjs

# Or let the PR workflow do it automatically!

See: .github/AGENT_AUTOSELECT_README.md for full documentation

Documentation

📚 Core Documentation

Getting Started:

• README.md - Project overview and quick start (you are here)
• GETTING_STARTED.md - Detailed onboarding guide
• CONTRIBUTING.md - Contribution guidelines
• CODE_OF_CONDUCT.md - Community standards

Architecture & Design:

• CLAUDE.md - ⭐ AI Assistant comprehensive guide (32KB, for Claude/GPT/Gemini)
• GEMINI.md - Gemini-specific AI assistant guidance
• AGENTS.md - ⭐ UPDATED: Complete AI agents architecture with best practices (30KB)
• REPO_MAP.md - Complete index of all 54 repositories

Planning & Roadmap:

• ROADMAP.md - NEW: Comprehensive product roadmap (MVP → V2.0+)
• AUDIT_SUMMARY.md - Current status and health metrics
• AUDIT_REPORT_2025-12-21.md - Full audit report (84KB)
• AUDIT_WORKFLOW_FINDINGS.md - NEW: GitHub Actions workflow audit (19KB)
• AUDIT_INDEX.md - Audit documentation index
• IMPLEMENTATION_SUMMARY.md - Implementation history

Development:

• REFACTORING.md - NEW: Code quality and architecture improvements
• DEBUGGING.md - NEW: Debugging guide and known issues
• TEST_GUIDELINES.md - Testing standards and best practices
• TROUBLESHOOTING.md - Common issues and solutions

Security & Operations:

• SECURITY.md - Security policy and practices
• SECURITY_FIXES.md - Recent security patches
• CHANGELOG.md - Version history and changes
• APPS_IMPORT_LOG.md - Import log and status tracking

📖 Additional Resources

AI & Agents:

• Agent Auto-Selection Guide - Intelligent agent selection
• Agent Auto-Selection Examples - Common scenarios
• Visionary Agent Guide - Complete strategic visionary agent guide
• Visionary Agent Example - Sample market research output
• shared/contracts/README.md - Agent contracts
• .github/agents/README.md - GitHub Copilot agents

Shared Utilities:

• shared/auth/README.md - Authentication & authorization
• shared/logging/README.md - Structured logging guide
• shared/otel/README.md - Observability setup
• shared/test-utils/README.md - Testing utilities

Deployment & Infrastructure:

• [docs/how-to