Super AI Agency Framework

🚀 A persona-driven AI development framework that merges 13 expert AI agents with GitHub Spec-Kit v0.4.4 and spec-kit-learn v1.1.0 to deliver a structured, gated, spec-driven development workflow from strategy to production with a full post-ship learning loop.

---

Table of Contents

• What is This?
• 🆕 What’s New in v2.0
• The 9-Phase Workflow
• 🗺️ Workflow Diagram
• Get Started
• Simulation Guide
• Complete Step-by-Step Workflow
• AI Agent Roster
• Slash Commands
• Project Structure
• Constitution & Governance
• Spec-Kit Extensions
• Extension Integration Guide
• Bridge Script
• Emergency Recovery
• Extending the Framework
• Compatibility
• Contributing
• License

---

🤔 What is This?

The Super AI Agency Framework is a complete AI-powered software development team that follows a strict, gated, 9-phase workflow. Instead of vibe-coding, every feature goes through mandatory phases — from strategy to production and post-ship learning — with specialized AI personas responsible for each phase.

Why Not Just Use Spec-Kit or Copilot Alone?

---

🆕 What’s New in v2.0

Addressing all gaps identified in the Agency + Spec-Kit integration analysis.

🔴 Critical Gaps Fixed

⚠️ Partial Alignments Resolved

🆕 New Features

---

🌟 The 9-Phase Workflow

Phase 0: Init        → /speckit.init        → Scaffold workspace + install spec-kit-learn
Phase 1: Specify     → /speckit.specify     → PM strategy + BA BRD + Enhanced Clarify
Phase 2: Plan        → /speckit.plan        → SAD + DB + API + Diagrams + Consistency Check
Phase 3: Tasks       → /speckit.tasks       → Git branch + backlog + tasks.md + pre-impl analyze
Phase 4: Implement   → /speckit.implement   → TDD: QA tests first → FE/BE → learn.md → verify
Phase 5: Review      → /speckit-commit      → staff-review (5-pass) + 7-Lens audit + QA exec
Phase 6: Deploy      → /speckit-deploy      → Docker + CI/CD + Trivy + staging + manual verify
Phase 7: Ship        → /speckit-ship        → Regression + handover + production + PR auto-created
Phase 8: Post-Ship   → /speckit.reconcile   → Reconcile + Retro + Retrospective + Constitution update

Every phase requires your explicit approval before proceeding. No phase can be skipped.
Bridge sync runs AUTOMATICALLY after every approval — not a manual step.

---

🗺️ Workflow Diagram

flowchart TD
    classDef agency fill:#1e3a5f,stroke:#4a90d9,color:#e8f4ff,font-weight:bold
    classDef speckit fill:#1a3d2b,stroke:#4caf50,color:#e8f5e9,font-weight:bold
    classDef bridge fill:#3d2a00,stroke:#ff9800,color:#fff3e0,font-weight:bold
    classDef gate fill:#4a1942,stroke:#e040fb,color:#fce4ec,font-weight:bold
    classDef human fill:#1a1a2e,stroke:#e91e63,color:#fce4ec,font-weight:bold
    classDef learn fill:#1a2a3d,stroke:#00bcd4,color:#e0f7fa,font-weight:bold

    START([🚀 Project Start]) --> PH0

    subgraph PH0["⚙️ PHASE 0 — Init"]
        P0_AG["🏛️ ORCHESTRATOR\n/speckit.init\nScaffold Artifacts/\nInstall spec-kit-learn"]:::agency
        P0_SK["🔧 speckit-init +\nspeckit-checklist gate"]:::speckit
        P0_AG --> P0_SK
    end
    PH0 --> PH1

    subgraph PH1["📋 PHASE 1 — Specify & Clarify"]
        P1a["🏛️ @product-manager\nSTRATEGY.md"]:::agency
        P1b["🏛️ @business-analyst\nBRD.md (Gherkin, BPMN, NFRs)"]:::agency
        P1br["🔁 BRIDGE AUTO-SYNC\nArtifacts/ → .specify/"]:::bridge
        P1c["🔧 /speckit.learn.clarify\nEnhanced Q&A + context"]:::learn
        P1d["🔧 speckit-checklist gate"]:::speckit
        P1a --> P1b --> P1br --> P1c --> P1d
    end
    P1d --> G1{{"✋ GATE: Specs Approved?"}}:::gate
    G1 -- REVISION --> P1b
    G1 -- PASS --> PH2

    subgraph PH2["🏗️ PHASE 2 — Plan & Design"]
        P2a["🏛️ @principal-architect\nSAD.md + research.md"]:::agency
        P2b["🏛️ @senior-dba\nSCHEMA.sql + SEED_DATA"]:::agency
        P2c["🏛️ @backend-dev\nPHASE_X_API.yaml"]:::agency
        P2br["🔁 BRIDGE AUTO-SYNC"]:::bridge
        P2learn["🔧 /speckit.learn.diagrams\nComponent + System + Architecture"]:::learn
        P2e["🔧 speckit-analyze\nDual-track: 5 artifacts"]:::speckit
        P2a --> P2b --> P2c --> P2br --> P2learn --> P2e
    end
    P2e --> G2{{"✋ GATE: Consistency OK?"}}:::gate
    G2 -- CRITICAL --> P2a
    G2 -- PASS --> PH3

    subgraph PH3["📅 PHASE 3 — Sprint Planning"]
        P3git["🏛️ GIT BRANCH\nsprint-X-name created"]:::agency
        P3a["🏛️ @agile-lead\nMASTER_PLAN.md"]:::agency
        P3b["🔧 speckit-tasks\ntasks.md with TDD order"]:::speckit
        P3br["🔁 BRIDGE AUTO-SYNC"]:::bridge
        P3d["🔧 speckit-analyze\npre-impl consistency"]:::speckit
        P3git --> P3a --> P3b --> P3br --> P3d
    end
    P3d --> G3{{"✋ GATE: Sprint Approved?"}}:::gate
    G3 -- PASS --> PH4

    subgraph PH4["💻 PHASE 4 — Implement (TDD Loop)"]
        P4a["🏛️ @qa-engineer FIRST\nTEST_CASES written"]:::agency
        P4b["🏛️ DESIGN GATE\nScratch OR Upload design"]:::agency
        P4c["🔧 speckit-implement\n@frontend tasks.md"]:::speckit
        P4d["🔧 speckit-implement\n@backend tasks.md + MermaidJS"]:::speckit
        P4learn["🔧 /speckit.learn.review\nlearn.md auto-generated"]:::learn
        P4e["🔧 speckit-verify-run\nMANDATORY — Constitution §2"]:::speckit
        P4a --> P4b --> P4c & P4d --> P4learn --> P4e
    end
    P4e --> G4{{"✋ GATE: Verify CRITICAL?"}}:::gate
    G4 -- CRITICAL --> P4c
    G4 -- PASS --> PH5

    subgraph PH5["🔍 PHASE 5 — Review & Commit"]
        P5a["🔧 speckit-staff-review-run\nMANDATORY 5-pass"]:::speckit
        P5b["🏛️ @tech-lead\n7-Lens Audit"]:::agency
        P5c["🏛️ @qa-engineer\nTest Execution >85%"]:::agency
        P5a --> P5b --> P5c
    end
    P5c --> G5{{"✋ GATE: APPROVED?"}}:::gate
    G5 -- REQUEST_CHANGES --> P4c
    G5 -- APPROVED --> COMMIT["📦 git commit + push sprint branch"]
    COMMIT --> LOOP{{"More tickets?"}}
    LOOP -- YES --> P4a
    LOOP -- NO --> PH6

    subgraph PH6["🚀 PHASE 6 — Deploy to Staging"]
        P6a["🏛️ @devops + speckit-deploy\nDockerfile + CI/CD + Trivy"]:::agency
        P6b["✋ YOU: Manual Verify\nRun app + check browser"]:::human
        P6a --> P6b
    end
    P6b --> G6{{"✋ GATE: Staging OK?"}}:::gate
    G6 -- FAIL --> P6a
    G6 -- PASS --> PH7

    subgraph PH7["🏁 PHASE 7 — Ship"]
        P7a["🏛️ Full Regression ALL sprints\nBLOCKER if any fails"]:::agency
        P7b["🏛️ @tech-lead\nHANDOVER + WALKTHROUGH"]:::agency
        P7c["✋ YOU: Approve Production"]:::human
        P7d["🏛️ @devops Blue/Green"]:::agency
        P7e["🔧 speckit-ship-run\nPR → main (auto)"]:::speckit
        P7f["✋ YOU: Verify Production"]:::human
        P7a --> P7b --> P7c --> P7d --> P7e --> P7f
    end
    P7f --> PH8

    subgraph PH8["🔄 PHASE 8 — Post-Ship MANDATORY"]
        P8a["🔧 speckit-reconcile-run\nDrift detection + fix"]:::speckit
        P8br["🔁 BRIDGE AUTO-SYNC"]:::bridge
        P8b["🔧 speckit-retro-run\nMetrics dashboard"]:::speckit
        P8c["🔧 speckit-retrospective-analyze\nSpec adherence score"]:::speckit
        P8d["🔧 speckit-constitution\nOffer update — YOUR approval"]:::speckit
        P8a --> P8br --> P8b --> P8c --> P8d
    end

    P8d --> MORE{{"More Sprints?"}}
    MORE -- YES --> PH3
    MORE -- NO --> DONE(["✅ Project Complete"])

Legend: 🏛️ Agency Persona | 🔧 Spec-Kit Tool | 🔁 Bridge Auto-Sync | ✋ Human Gate | 🔧🔵 spec-kit-learn

---

⚡ Get Started

Prerequisites

• Python 3.11+
• uv — Python package manager
• Git
• An AI coding agent (supported list)

Installation

Option 1: Clone and Initialize (Recommended)

# Clone the repository
git clone https://github.com/ahmedemad3/super-ai-agency-framework.git
cd super-ai-agency-framework

# Install Spec-Kit CLI (if not already installed)
uv tool install specify-cli --from git+https://github.com/github/[email protected]

# Initialize Spec-Kit in the project (already done, but verify)
specify check

Option 2: Start from Scratch

# Create a new project directory
mkdir my-project && cd my-project

# Install Spec-Kit CLI
uv tool install specify-cli --from git+https://github.com/github/[email protected]

# Initialize with Spec-Kit + Agency skills
specify init . --ai agy --ai-skills --force

# Download the Agency skills (from this repo)
# Copy the .agent/ folder from this repo into your project

Option 3: Add to Existing Project

cd your-existing-project

# Initialize Spec-Kit (merge mode)
specify init . --ai agy --ai-skills --force

# Copy the Agency skills from this repo
cp -r /path/to/super-ai-agency-framework/.agent/skills/BA-skill .agent/skills/
cp -r /path/to/super-ai-agency-framework/.agent/skills/DBA-skill .agent/skills/
cp -r /path/to/super-ai-agency-framework/.agent/skills/Orchestrator-skill .agent/skills/
# ... (copy all 13 Agency skills)

# Copy governance files
cp -r /path/to/super-ai-agency-framework/Artifacts/00_Governance ./Artifacts/00_Governance/

# Copy workflows
cp -r /path/to/super-ai-agency-framework/.agent/workflows .agent/workflows/

First Run

1. Open your AI coding agent in the project directory
2. Say: “Start project” or /speckit-init
3. The Orchestrator detects no artifacts → begins Phase 0
4. Follow the prompts through each phase
5. The bridge sync runs automatically — you do not need to trigger it manually

---

📘 Simulation Guide

The complete step-by-step playbook for running any project through the 9-phase framework.

📄 SIMULATION_GUIDE.md — Read this before starting any project. It covers:

• Every phase with your exact review checklist
• What each step produces and how to validate it
• Pass/Fail gates and when to block
• Emergency recovery commands
• Complete artifact checklist by phase
• Quick reference for all commands

---

📋 Complete Step-by-Step Workflow

Treat this framework as a managed engineering organization — you are the CEO, the AI is the Agency.

Phase 0: Initialize

Phase 1: Specify (Strategy + Requirements)

Before approving: Does every story have Given/When/Then? Are NFRs specific numbers?

Phase 1b: Clarify

Always run this — even if the BRD looks complete. It catches hidden assumptions.

🔗 Bridge Sync: .\.agent\scripts\spec-kit-bridge.ps1 -FeatureName "001-my-feature"

Phase 2: Plan (Architecture + Database + API)

⚠️ Step 2.3 is often missed — The API design is a separate step from architecture. The developer persona designs the OpenAPI contract — no implementation code yet.

🔁 Bridge Sync: Runs automatically after each approval in Phase 2.

NEW in v2.0: After architecture approval, /speckit.learn.diagrams --all auto-generates visual architecture docs (component, system, software architecture diagrams).

Phase 2b: Analyze (Cross-Artifact Consistency)

Checks: BRD ↔ API mapping, Schema ↔ DTOs, SAD feasibility, naming consistency.

Phase 3: Tasks (Sprint Planning)

NEW in v2.0: speckit-tasks is now invoked to generate tasks.md — speckit-implement reads it for TDD order enforcement. Git branch auto-created at sprint start.

Phase 4: Implement (TDD Loop — Per Ticket)

Repeat for EACH ticket in Sprint Backlog:

NEW in v2.0: speckit-implement is now mandatory — agents execute through it, not free-form. speckit-verify-run is now mandatory (not optional). learn.md is auto-generated after every ticket.

Phase 5: Review (Code Quality Gate — Per Ticket)

Review: 5-pass staff review FIRST, then 7-Lens: Architecture · Security · Resilience · Observability · Performance · Test Quality · Maintainability

NEW in v2.0: speckit-staff-review-run is now mandatory (was optional). Must run before Tech Lead 7-Lens.

Phase 6: Deploy (Staging)

NEW in v2.0: You are explicitly asked to verify staging manually before proceeding to Phase 7.

Phase 7: Ship (Production)

NEW in v2.0: speckit-ship-run is now mandatory (was optional) — auto-creates PR with full artifact traceability.

Phase 8: Post-Ship (NEW — MANDATORY)

NEW in v2.0: Phase 8 is now mandatory — it’s the learning loop that improves every future sprint.

Multi-Sprint Loop

After Ship, if MASTER_PLAN.md has more sprints:

→ Go back to Phase 3: "Plan Sprint [X+1]"
→ Repeat Phase 4 → 5 → 6 → 7
→ Continue until all sprints shipped

🔄 Multi-Sprint Edge Cases

• API evolution: If a later sprint introduces new endpoints, update PHASE_[X]_API.yaml during that sprint’s Phase 4.
• Architectural changes: If a later sprint adds a major component (e.g., Elasticsearch), re-run /speckit.plan and /speckit-analyze before Phase 4.
• Test Suite Growth: By Sprint 10, regression tests may exceed context limits. Use “critical path regression” for later sprints.
• Bridge Sync Scheduled: Always run spec-kit-bridge.ps1 after Phase 1b, Phase 2, Phase 3, AND at the end of Phase 7 to sync test cases and deliverables.

---

🤖 AI Agent Roster

13 Specialized Persona Skills

12 Spec-Kit Skills (Auto-installed + spec-kit-learn)

---

🔧 Slash Commands

Core Workflow Commands

spec-kit-learn Commands (Auto-triggered)

| Command | Trigger | Purpose | |---------|---------|---------|----------| | /speckit.learn.diagrams | After /speckit.plan | Visual architecture diagrams (Component, System, Software) | | /speckit.learn.review | After /speckit.implement | Educational learn.md — Key Decisions, Concepts, Glossary | | /speckit.learn.clarify | During /speckit-clarify | Enhanced Q&A with Why + Pros/Cons + Recommended option |

Enhancement Commands

---

📁 Project Structure

super-ai-agency-framework/
├── .agent/
│   ├── skills/                        ← 22 Skills (13 Agency + 9 Spec-Kit)
│   │   ├── Orchestrator-skill/        ← 🎯 CEO: 8-phase decision engine
│   │   ├── Product-manager-skill/     ← 📊 Strategy & MVP
│   │   ├── BA-skill/                  ← 📋 Requirements (Gherkin)
│   │   ├── Solution-architect-skill/  ← 🏗️ System Design (C4)
│   │   ├── DBA-skill/                 ← 🗄️ Database Design
│   │   ├── Sr.Java-skill/             ← ☕ Java 21+ Backend
│   │   ├── Sr.Node-skill/             ← 🟢 Node.js Backend
│   │   ├── Sr.Front-skill/            ← 🎨 Frontend (React/Vue/Angular)
│   │   ├── Sr.QA-skill/               ← 🧪 Testing (TDD + Regression)
│   │   ├── TL-skill/                  ← 🔍 7-Lens Code Review
│   │   ├── PM-skill/                  ← 📅 Sprint Planning (DAG)
│   │   ├── Sr.Devops-skill/           ← 🚀 Docker + CI/CD
│   │   ├── tech_proposal-skill/       ← 📄 Technical Proposals
│   │   └── speckit-*/                 ← 🧩 9 Spec-Kit skills
│   ├── scripts/
│   │   └── spec-kit-bridge.ps1        ← 🔗 Artifact sync script
│   └── workflows/                     ← ⚡ 6 workflow definitions
│       ├── speckit-init.md
│       ├── speckit-clarify.md
│       ├── speckit-analyze.md
│       ├── speckit-commit.md
│       ├── speckit-deploy.md
│       └── speckit-ship.md
├── .specify/                          ← 🧩 Spec-Kit scaffold
│   ├── memory/constitution.md
│   ├── extensions/                    ← Installed extensions
│   ├── presets/agency-enterprise/     ← Custom Agency preset
│   ├── scripts/
│   └── templates/
├── Artifacts/                         ← 📂 Source of Truth
│   ├── 00_Governance/                 ← Constitution & Artifact Map
│   ├── 01_Strategy/                   ← PM output
│   ├── 02_Specs/                      ← BA output
│   ├── 03_Architecture/               ← Architect output
│   ├── 04_Database/                   ← DBA output
│   ├── 05_Planning/                   ← Sprint backlogs
│   ├── 06_Quality_Reports/            ← Tests, reviews, regression
│   ├── 07_API_Specs/                  ← OpenAPI contracts
│   └── 08_Releases/                   ← Handover docs, deploy logs
├── README.md
├── LICENSE
├── CONTRIBUTING.md
├── CHANGELOG.md
└── .gitignore

---

🛡️ Constitution & Governance

Every AI agent is bound by the Constitution (Artifacts/00_Governance/CONSTITUTION.md). It defines:

The Orchestrator injects a `` into every XML protocol to enforce compliance.

---

🧩 Spec-Kit Extensions

7 extensions — all mandatory (no longer optional):

v2.0 Change: All extensions changed from optional: true → optional: false in extensions.yml. They are now enforced by the Orchestrator XML protocol.

Install additional extensions:

# Browse the catalog
specify extension search

# Install from GitHub
specify extension add  --from 

# List installed
specify extension list

---

📡 Extension Integration Guide

v2.0 Change: Extensions are now auto-triggered by the Orchestrator at specific phase gates — not manual.

---

🔗 Bridge Script

The spec-kit-bridge.ps1 script syncs Artifacts/ (Agency source of truth) → .specify/specs/ (Spec-Kit CLI compatibility).

v2.0 Change: The bridge now runs AUTOMATICALLY after every approval via the `` XML tag in the Orchestrator SOP. You do NOT need to run it manually.

Automatic sync points (all now automatic):

• After STRATEGY.md approved → spec.md (overwrite)
• After BRD.md approved → spec.md (append)
• After Clarifications recorded → spec.md (append)
• After SAD.md approved → plan.md
• After SCHEMA.sql approved → schema.sql + data-model.md
• After API.yaml approved → contracts/
• After SPRINT_BACKLOG approved → tasks.md
• After Phase 8 reconcile → Artifacts/ (reverse sync)

Manual use (if needed for debugging):

# Dry run (preview what would be synced)
.agent\scripts\spec-kit-bridge.ps1 -FeatureName "001-my-feature" -DryRun

# Live sync
.agent\scripts\spec-kit-bridge.ps1 -FeatureName "001-my-feature"

If bridge_sync_status shows STALE in the status block, say: “Run bridge sync for feature [name]”.

---

🚨 Emergency Recovery

When the AI drifts off-workflow, use these rescue commands:

---

🔌 Extending the Framework

The framework is designed for easy growth. Two extension paths are available:

Option 1: Add a New Agency Skill (AI Persona)

Best for: Adding a new expert role (e.g., Security Auditor, Data Engineer, Mobile Developer) Effort: ~15 minutes — just 1 file

Create a new folder in .agent/skills/ with a SKILL.md:

.agent/skills/My-New-skill/SKILL.md

SKILL.md Template:

---
name: persona-my-new-role
description: Act as a [Role] (X+ years exp) specializing in [Specialty].
---

# Role: [Title]

## Context & Experience
You have **X years of experience**. You specialize in...

## Technical Skills & Competencies
- Skill 1
- Skill 2

## 🧠 Context Loading Protocol
1. **Load Artifacts**: Read `[relevant artifacts]`

## Workflow Interaction Protocol
1. **Incoming**: You receive [trigger]
2. **Action**: [What you do]
3. **Outgoing**: Save to `Artifacts/[folder]/[FILE].md`
   - End with: *"@team-orchestrator, [deliverable] is ready."*

## Deliverables
- **`FILE_NAME.md`**: Description

Then add one XML protocol block to the Orchestrator (Orchestrator-skill/SKILL.md) to wire it into a phase — done.

Option 2: Add a Spec-Kit Extension

Best for: Adding workflow commands, integrations (Jira, Linear), or quality gates Effort: 2 minutes (install) or ~30 minutes (build your own)

Install from Community

# Search available extensions
specify extension search

# Install from GitHub
specify extension add  --from 

This auto-registers a new skill in .agent/skills/ and adds a slash command. Zero code needed.

Build Your Own Extension

Create this structure:

.specify/extensions/my-extension/
├── extension.yml              ← Extension metadata
├── commands/
│   └── speckit.my-ext.run.md  ← The command prompt (AI instructions)
└── templates/                 ← Optional template overrides

extension.yml:

name: my-extension
version: 1.0.0
description: What this extension does
author: Your Name
commands:
  - name: speckit.my-ext.run
    description: What the command does
    type: agent-skill

commands/speckit.my-ext.run.md:

You are a [role]. When invoked:
1. Read [artifacts]
2. Perform [task]
3. Output results to [path]

Then install it:

specify extension add my-extension --from ./path/to/extension.zip

Quick Comparison

---

🤖 Compatibility

This framework works with any AI coding agent that supports Spec-Kit:

---

Contributing

See CONTRIBUTING.md for guidelines.

Changelog

See CHANGELOG.md for version history.

v2.0 (2026-04-10): Automatic bridge sync, mandatory spec-kit-learn, mandatory Phase 8 post-ship, mandatory speckit-implement and speckit-verify-run, git sprint branching, Constitution v2.0, 9-phase workflow, SIMULATION_GUIDE.md.

License

This project is licensed under the MIT License — see LICENSE for details.

Acknowledgements

• GitHub Spec-Kit — The spec-driven development toolkit this framework extends
• John Lam — Research behind Spec-Driven Development
• imviancagrace/spec-kit-learn — Educational guides extension integrated in v2.0