<AI-ROOT>/ Repository Structure

How our bot workflow is organized on the owner's computer, in the repo, in your AI tool and in the cloud

📁 <AI-ROOT>/
Root on the owner's computer
📁 _shared/
Tools for all apps
📁 qa-kit/
Optional QA tools (UI flows, image diff, proxy, mocks)
📁 report-template/
QA report HTML template
📁 contracts/ NEW
Output format per stage (brief, gap, plan, review, quality, qa)
📁 domains/ NEW
fintech/DOMAIN.md (generic fintech best practices)
telecom/DOMAIN.md (generic telecom best practices)
📁 <App-Name>/
One folder per app
📄 PROJECT_CONTEXT.md
App overview, stack, architecture
📄 rules.md
Team rules (gates, safety, token saving)
📁 project/
quality-rules, quality-must-haves, devices, app-internals, test-accounts (local only)
📁 tasks/<TASK-KEY>/
brief, gap, plan, review, quality, qa, loops, approvals (.md)
📁 reviews/
PR review history
📁 qa/
Screenshots, recordings, reports
📁 project-overrides/ NEW
Project rules that win, except safety rules
📁 <Next-App>/
Same layout for future apps
📁 <REPO>/.cursor/
Project-level AI tool config (Cursor shown)
📄 rules/team.mdc
Synced team rules
📁 skills/
flutter-captain and Flutter skills
📁 ~/.cursor/
User-level AI tool config (Cursor shown)
📄 agents/*.md
AI tool subagents (Gap Finder, Dev Planner on a strong model; rest auto)
📁 skills/
flutter-captain, clean-feature, feature-review, legacy-edit, responsive-ui, reusable-widget
🤖 Bot team (cloud, optional)
Bots that run the pipeline
🤖 Captain, Captain B (optional)
Orchestrate the pipeline
🤖 Intake
BRS, Tracker, Design, Code Analysts
🤖 Plan
Gap Finder, Dev Planner, Tracker Drafter
🤖 Build
Flutter Dev 1 and 2, QA Test Writer
🤖 Review
PR Reviewer, Code Quality Checker, Security, Localization (optional)
🤖 QA
QA Lead, QA Reporter, Tracker Updater
🤖 Support
Cache Keeper, Git Advisor, Crash/Analytics Analysts (optional, idle)
Pipeline: Intake > Gap > Plan > Dev + Tests > Analyze > Review > QA > Report > TrackerApproval gate after every stage. The owner approves commits, tracker posts and status changes.