aios-core 2.1.6 → 2.2.0

package/.aios-core/docs/standards/AIOS-FRAMEWORK-MASTER.md

@@ -1,1963 +1,1963 @@
-# AIOS Framework - Complete Documentation
-
-> **⚠️ DEPRECATION NOTICE**
->
-> This document describes **v2.0.0** of the AIOS Framework.
->
-> **For the current version (v2.1), see:**
-> - [AIOS-LIVRO-DE-OURO-V2.1-COMPLETE.md](./AIOS-LIVRO-DE-OURO-V2.1-COMPLETE.md) - Complete v2.1 framework guide
-> - [STANDARDS-INDEX.md](./STANDARDS-INDEX.md) - Navigation for all standards
->
-> **Key changes in v2.1:**
-> - 4-module architecture (core, development, product, infrastructure)
-> - Squad System (replaces "Expansion Packs")
-> - Multi-repo strategy (3 public + 2 private repos)
-> - Quality Gates 3-layer system
-> - Story Template v2.0
->
-> This document is retained for historical reference only.
-
-**Version:** 2.0.0 (DEPRECATED - See v2.1)
-**Status:** ⚠️ Deprecated - Reference Only
-**Last Updated:** 2025-01-18
-**Maintained By:** AIOS Framework Team
-
----
-
-## 📋 Table of Contents
-
-### Part I: Framework Overview
-1. [What is AIOS?](#what-is-aios)
-2. [Core Philosophy](#core-philosophy)
-3. [Framework Architecture](#framework-architecture)
-4. [Getting Started](#getting-started)
-
-### Part II: Framework Structure
-5. [Directory Structure](#directory-structure)
-6. [File Organization](#file-organization)
-7. [Naming Conventions](#naming-conventions)
-
-### Part III: Agent System
-8. [Agent Architecture](#agent-architecture)
-9. [Agent Personalization](#agent-personalization)
-10. [Agent Roles & Specializations](#agent-roles--specializations)
-11. [Greeting System](#greeting-system)
-
-### Part IV: Task & Workflow System
-12. [Task Format Specification](#task-format-specification)
-13. [Execution Modes](#execution-modes)
-14. [Workflow Orchestration](#workflow-orchestration)
-15. [Fork/Join & Organizer-Worker Patterns](#forkjoin--organizer-worker-patterns)
-
-### Part V: Executor Types
-16. [The Four Executor Types](#the-four-executor-types)
-17. [Executor Decision Tree](#executor-decision-tree)
-
-### Part VI: Standards & Best Practices
-18. [Coding Standards](#coding-standards)
-19. [Technology Stack](#technology-stack)
-20. [Quality Gates & CodeRabbit Integration](#quality-gates--coderabbit-integration)
-
-### Part VII: Migration & Roadmap
-21. [Current Migration Status](#current-migration-status)
-22. [Future Architecture (Q2 2026)](#future-architecture-q2-2026)
-23. [Subdirectory Migration Plan](#subdirectory-migration-plan)
-
-### Part VIII: Appendices
-24. [Glossary](#glossary)
-25. [Decision History](#decision-history)
-26. [References](#references)
-
----
-
-# Part I: Framework Overview
-
-## What is AIOS?
-
-**AIOS (AI Operating System)** is a sophisticated framework for orchestrating AI agents, workers, and humans in complex software development workflows. It provides a structured, scalable approach to building AI-assisted development teams with personality, coordination, and quality gates.
-
-### Key Capabilities
-
-- 🤖 **16 Specialized Agents** - Dev, QA, Architect, PM, PO, Analyst, Data Engineer, DevOps, etc.
-- 📋 **60+ Executable Tasks** - Story creation, code generation, testing, deployment, documentation
-- 📝 **20+ Templates** - PRDs, stories, architecture docs, test plans, database schemas
-- 🔄 **Multi-Agent Workflows** - Greenfield, brownfield, fork/join, organizer-worker patterns
-- 🎭 **Personalized Agent System** - Named personalities with archetypes, vocabularies, and signatures
-- 🎯 **Three Execution Modes** - YOLO (autonomous), Interactive (balanced), Pre-Flight (comprehensive)
-- ✅ **Quality Gates** - CodeRabbit integration, automated reviews, acceptance criteria validation
-
----
-
-## Core Philosophy
-
-### Structure is Sacred. Tone is Flexible.
-
-AIOS follows a fundamental principle:
-
-> "Quando as informações estão sempre nas mesmas posições, nosso cérebro sabe onde buscar rápido."
-
-**FIXED:**
-- Template positions
-- Section order
-- Metric formats
-- File structure
-- Task workflows
-
-**FLEXIBLE:**
-- Status messages
-- Vocabulary choices
-- Emoji usage
-- Agent personality
-- Communication tone
-
-### Design Principles
-
-1. **Familiaridade + Personalização = Produtividade**
-   - Users learn structure once
-   - Personality makes it memorable
-   - Consistency enables speed
-
-2. **Separation of Concerns**
-   - Framework vs. Project
-   - Structure vs. Tone
-   - Automation vs. Human Judgment
-
-3. **Progressive Complexity**
-   - Simple by default
-   - Complex when needed
-   - Scalable architecture
-
-4. **Multi-Agent Coordination**
-   - Agents work together
-   - Clear handoffs
-   - Shared context
-
----
-
-## Framework Architecture
-
-### Dual-Layer Architecture
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│  FRAMEWORK LAYER (.aios-core/)                              │
-│  ├── Agents (16 specialists)                                │
-│  ├── Tasks (60+ executable workflows)                       │
-│  ├── Templates (20+ document generators)                    │
-│  ├── Workflows (6+ multi-agent orchestrations)              │
-│  ├── Checklists (6+ validation processes)                   │
-│  ├── Data (Knowledge base)                                  │
-│  ├── Scripts (54+ utilities)                                │
-│  └── Tools (MCP integrations)                               │
-└─────────────────────────────────────────────────────────────┘
-                         ↕
-┌─────────────────────────────────────────────────────────────┐
-│  PROJECT LAYER (root workspace)                             │
-│  ├── frontend/ (Next.js, React)                             │
-│  ├── backend/ (NestJS, Supabase)                            │
-│  ├── docs/ (Project documentation)                          │
-│  ├── tests/ (Unit, integration, E2E)                        │
-│  └── .aios/ (Session state, logs)                           │
-└─────────────────────────────────────────────────────────────┘
-```
-
-**Framework Layer:** Portable across all AIOS projects  
-**Project Layer:** Specific to each implementation
-
----
-
-### Three-Layer Personality System
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│   LAYER 1: Agent Persona Config (.aios-core/agents/*.md)   │
-│   - Name, archetype, zodiac                                 │
-│   - Vocabulary, emoji palette                               │
-│   - Greeting levels, signature                              │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│   LAYER 2: Output Formatter (.aios-core/scripts/)          │
-│   - greeting-builder.js                                     │
-│   - session-context-loader.js                               │
-│   - project-status-loader.js                                │
-└─────────────────────────────────────────────────────────────┘
-                         ↓
-┌─────────────────────────────────────────────────────────────┐
-│   LAYER 3: Standardized Output                              │
-│   - Fixed structure + personalized tone                     │
-│   - Contextual greetings                                    │
-│   - Agent signatures                                        │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
-
-## Getting Started
-
-### Prerequisites
-
-- **Node.js** 18+ (LTS)
-- **Git** (version control)
-- **IDE:** Cursor or VS Code with Claude extension
-- **MCP Servers:** ClickUp, Context7, Exa (optional)
-
-### Quick Start
-
-```bash
-# 1. Clone the repository
-git clone <your-aios-project>
-cd <project-directory>
-
-# 2. Install dependencies
-npm install
-
-# 3. Configure AIOS
-# Edit .aios-core/core-config.yaml
-
-# 4. Activate first agent
-# In IDE: type /AIOS/agents/pm
-
-# 5. Create your first story
-*create-next-story
-```
-
-### First Commands to Try
-
-```bash
-# Product Owner (Story Management)
-/AIOS/agents/po
-*create-next-story
-*validate-story-draft docs/stories/your-story.md
-
-# Developer (Implementation)
-/AIOS/agents/dev
-*develop-story docs/stories/your-story.md
-
-# QA (Quality Assurance)
-/AIOS/agents/qa
-*review docs/stories/your-story.md
-*code-review
-```
-
----
-
-# Part II: Framework Structure
-
-## Directory Structure
-
-### Complete Framework Structure
-
-```
-.aios-core/                              # Framework Core (Portable)
-├── agents/                              # 16 agent definitions
-│   ├── dev.md                           # 💻 Dex (Builder)
-│   ├── qa.md                            # 🛡️ Quinn (Guardian)
-│   ├── architect.md                     # 🏛️ Aria (Visionary)
-│   ├── pm.md                            # 📊 Morgan (Balancer)
-│   ├── po.md                            # 📋 Pax (Balancer)
-│   ├── sm.md                            # 🌊 Sage (Flow Master)
-│   ├── analyst.md                       # 🔍 Scout (Explorer)
-│   ├── data-engineer.md                 # 🔧 Dara (Engineer)
-│   ├── devops.md                        # ⚙️ Gage (Operator)
-│   ├── db-sage.md                       # 🗄️ [Database Architect]
-│   ├── ux-design-expert.md              # 🎨 Uma (Empathizer)
-│   ├── aios-master.md                   # ⭐ Orion (Orchestrator)
-│   ├── aios-developer.md                # 🛠️ [Framework Developer]
-│   ├── aios-orchestrator.md             # 🎭 [Workflow Orchestrator]
-│   ├── github-devops.md                 # 🐙 [Git Operations]
-│   └── test-agent.md                    # 🧪 [Test Agent]
-│
-├── tasks/                               # 60+ executable workflows
-│   ├── create-doc.md                    # Document generation
-│   ├── create-next-story.md             # Story creation
-│   ├── develop-story.md                 # Story implementation
-│   ├── review-story.md                  # Story review
-│   ├── validate-next-story.md           # Story validation
-│   ├── manage-story-backlog.md          # Backlog management
-│   ├── execute-checklist.md             # Checklist execution
-│   ├── document-project.md              # Project documentation
-│   ├── generate-tests.md                # Test generation
-│   ├── nfr-assess.md                    # Non-functional requirements
-│   ├── qa-gate.md                       # Quality gate decision
-│   ├── code-review.md                   # Automated code review
-│   ├── apply-qa-fixes.md                # QA fix application
-│   ├── improve-code-quality.md          # Code quality improvements
-│   ├── setup-database.md                # Database setup
-│   ├── domain-modeling.md               # Domain modeling
-│   ├── version-management.md            # Version management
-│   ├── pre-push-quality-gate.md         # Pre-push validation
-│   ├── github-pr-automation.md          # PR automation
-│   ├── create-agent.md                  # Agent creation
-│   ├── create-task.md                   # Task creation
-│   ├── create-workflow.md               # Workflow creation
-│   └── ... (40+ more)
-│
-├── templates/                           # 20+ document templates
-│   ├── story-tmpl.yaml                  # Story template v2.0
-│   ├── design-story-tmpl.yaml           # Design story template
-│   ├── prd-tmpl.yaml                    # PRD template
-│   ├── epic-tmpl.md                     # Epic template
-│   ├── architecture-tmpl.yaml           # Architecture template
-│   ├── fullstack-architecture-tmpl.yaml # Full-stack architecture
-│   ├── brownfield-architecture-tmpl.yaml # Brownfield architecture
-│   ├── schema-design-tmpl.yaml          # Database schema template
-│   ├── project-brief-tmpl.yaml          # Project brief
-│   ├── market-research-tmpl.yaml        # Market research
-│   ├── competitor-analysis-tmpl.yaml    # Competitor analysis
-│   ├── github-pr-template.md            # PR template
-│   ├── github-actions-ci.yml            # CI/CD template
-│   ├── personalized-task-template-v2.md # Task template
-│   └── ... (6+ more)
-│
-├── workflows/                           # 6 multi-step workflows
-│   ├── greenfield-fullstack.yaml        # Greenfield full-stack
-│   ├── greenfield-service.yaml          # Greenfield service
-│   ├── greenfield-ui.yaml               # Greenfield UI
-│   ├── brownfield-fullstack.yaml        # Brownfield full-stack
-│   ├── brownfield-service.yaml          # Brownfield service
-│   └── brownfield-ui.yaml               # Brownfield UI
-│
-├── checklists/                          # 6+ validation checklists
-│   ├── po-master-checklist.md           # PO validation
-│   ├── story-draft-checklist.md         # Story draft validation
-│   ├── story-dod-checklist.md           # Story Definition of Done
-│   ├── architect-checklist.md           # Architecture review
-│   ├── qa-checklist.md                  # QA validation
-│   ├── pm-checklist.md                  # PM validation
-│   └── change-checklist.md              # Change management
-│
-├── data/                                # Knowledge base
-│   ├── aios-kb.md                       # AIOS knowledge base
-│   ├── technical-preferences.md         # Tech stack preferences
-│   ├── elicitation-methods.md           # Elicitation techniques
-│   ├── brainstorming-techniques.md      # Brainstorming methods
-│   ├── mode-selection-best-practices.md # Execution mode guidance
-│   ├── test-levels-framework.md         # Testing strategy
-│   ├── test-priorities-matrix.md        # Test prioritization
-│   └── agent-config-requirements.yaml   # Agent requirements
-│
-├── scripts/                             # 54+ utility scripts
-│   ├── agent-config-loader.js           # Agent configuration
-│   ├── greeting-builder.js              # Greeting generation
-│   ├── generate-greeting.js             # Greeting orchestrator
-│   ├── session-context-loader.js        # Session management
-│   ├── project-status-loader.js         # Project status
-│   ├── config-cache.js                  # Configuration cache
-│   ├── performance-tracker.js           # Performance tracking
-│   ├── component-generator.js           # Component scaffolding
-│   ├── elicitation-engine.js            # Interactive elicitation
-│   ├── story-manager.js                 # Story lifecycle
-│   ├── yaml-validator.js                # YAML validation
-│   ├── usage-analytics.js               # Usage tracking
-│   ├── migrate-task-to-v2.js            # Task migration
-│   ├── validate-task-v2.js              # Task validation
-│   └── ... (40+ more)
-│
-├── tools/                               # Tool integrations
-│   ├── mcp/                             # MCP server configs
-│   │   ├── clickup-direct.yaml
-│   │   ├── context7.yaml
-│   │   └── exa-direct.yaml
-│   ├── cli/                             # CLI tool wrappers
-│   │   ├── github-cli.yaml
-│   │   └── railway-cli.yaml
-│   └── local/                           # Local tools
-│
-├── elicitation/                         # Elicitation engines
-│   ├── agent-elicitation.js
-│   ├── task-elicitation.js
-│   └── workflow-elicitation.js
-│
-├── core-config.yaml                     # Framework configuration
-├── install-manifest.yaml                # Installation manifest
-├── user-guide.md                        # User guide
-└── working-in-the-brownfield.md         # Brownfield guide
-```
-
----
-
-## File Organization
-
-### File Types & Purposes
-
-| Type | Location | Purpose | Format |
-|------|----------|---------|--------|
-| **Agents** | `.aios-core/agents/*.md` | Agent definitions with persona | Markdown + YAML |
-| **Tasks** | `.aios-core/tasks/*.md` | Executable workflows | Markdown + YAML |
-| **Templates** | `.aios-core/templates/*.yaml` | Document generators | YAML |
-| **Workflows** | `.aios-core/workflows/*.yaml` | Multi-agent orchestration | YAML |
-| **Checklists** | `.aios-core/checklists/*.md` | Validation processes | Markdown + Checklist |
-| **Data/KB** | `.aios-core/data/*.md` | Knowledge base, references | Markdown/YAML |
-| **Scripts** | `.aios-core/scripts/*.js` | Utilities, automation | JavaScript |
-| **Tools** | `.aios-core/tools/*/*.yaml` | Tool integrations | YAML |
-
-### Framework vs. Project Files
-
-**Framework Files (.aios-core/):**
-- ✅ Portable across projects
-- ✅ Version controlled in framework repo
-- ✅ Shared by all AIOS projects
-- ✅ Changes require framework approval
-
-**Project Files (root/):**
-- ✅ Project-specific implementation
-- ✅ Version controlled in project repo
-- ✅ Unique to each project
-- ✅ Changes by project team
-
----
-
-## Naming Conventions
-
-### File Names
-
-**Rule:** `kebab-case` for all files
-
-```bash
-✅ CORRECT:
-- create-next-story.md
-- fullstack-architecture-tmpl.yaml
-- agent-config-loader.js
-
-❌ WRONG:
-- createNextStory.md
-- fullstackArchitectureTmpl.yaml
-- agent_config_loader.js
-```
-
-### Variable Names
-
-**JavaScript/JSON:** `camelCase`
-```javascript
-✅ CORRECT:
-const agentConfig = { ... }
-const taskDefinition = { ... }
-
-❌ WRONG:
-const agent_config = { ... }
-const task-definition = { ... }
-```
-
-**CSS:** `kebab-case`
-```css
-✅ CORRECT:
-.content-area { }
---spacing-md: 200px;
-
-❌ WRONG:
-.contentArea { }
---spacing_md: 200px;
-```
-
-**Database:** `snake_case`
-```sql
-✅ CORRECT:
-tasks.responsavel_type
-workflow_executions.started_at
-
-❌ WRONG:
-tasks.responsavelType
-workflow_executions.startedAt
-```
-
----
-
-# Part III: Agent System
-
-## Agent Architecture
-
-### Agent Definition Structure
-
-Every agent follows this YAML structure:
-
-```yaml
-# Agent Core Identity
-agent:
-  name: {PersonalizedName}        # Human name (Dex, Quinn, Pax)
-  id: {agent-id}                  # System identifier
-  title: {Role}                   # Professional role
-  icon: {emoji}                   # Visual identifier
-  whenToUse: "{description}"      # When to activate this agent
-
-# Personality Profile
-persona_profile:
-  archetype: {Archetype}          # Builder, Guardian, Balancer, etc.
-  zodiac: {Sign}                  # ♒ Aquarius, ♍ Virgo, ♎ Libra, etc.
-
-  communication:
-    tone: {tone}                  # pragmatic | empathetic | analytical
-    emoji_frequency: {level}      # high | medium | low | minimal
-
-    vocabulary:                   # Agent-specific words (5-10)
-      - {word1}
-      - {word2}
-      - {word3}
-
-    greeting_levels:              # 3 personification levels
-      minimal: "{icon} {id} Agent ready"
-      named: "{icon} {name} ({archetype}) ready. {tagline}!"
-      archetypal: "{icon} {name} the {archetype} ready to {verb}!"
-
-    signature_closing: "{personalized_sign_off}"
-
-# Behavioral Configuration
-persona:
-  role: {DetailedRole}
-  style: {CommunicationStyle}
-  identity: {CoreIdentity}
-  focus: {PrimaryFocus}
-  core_principles:
-    - {principle1}
-    - {principle2}
-    - {principle3}
-
-# Commands
-commands:
-  - name: {command-name}
-    description: {description}
-
-# Dependencies
-dependencies:
-  tasks:
-    - {task-file}.md
-  templates:
-    - {template-file}.yaml
-  checklists:
-    - {checklist-file}.md
-  data:
-    - {data-file}.md
-  tools:
-    - {tool-name}
-```
-
----
-
-## Agent Personalization
-
-### The 11 Archetypes
-
-| Archetype | Name | Icon | Zodiac | Tone | Examples |
-|-----------|------|------|--------|------|----------|
-| **Builder** | Dex | 💻 | ♒ Aquarius | Pragmatic | Dev |
-| **Guardian** | Quinn | 🛡️ | ♍ Virgo | Protective | QA |
-| **Balancer** | Pax, Morgan | 📋 📊 | ♎ Libra | Diplomatic | PO, PM |
-| **Visionary** | Aria | 🏛️ | ♐ Sagittarius | Conceptual | Architect |
-| **Flow Master** | Sage | 🌊 | ♓ Pisces | Adaptive | SM |
-| **Explorer** | Scout | 🔍 | ♊ Gemini | Curious | Analyst |
-| **Engineer** | Dara | 🔧 | ♉ Taurus | Methodical | Data Engineer |
-| **Operator** | Gage | ⚙️ | ♑ Capricorn | Efficient | DevOps |
-| **Empathizer** | Uma | 🎨 | ♋ Cancer | Empathetic | UX Expert |
-| **Orchestrator** | Orion | ⭐ | ♌ Leo | Commanding | AIOS Master |
-| **Architect** | (Various) | 🏗️ | (Various) | Systematic | DB Sage |
-
-### Vocabulary System
-
-Each archetype has specific vocabulary:
-
-**Builder (Dex):**
-- construir, implementar, refatorar, resolver, otimizar
-- debuggar, testar, deployar, commitar, mergear
-
-**Guardian (Quinn):**
-- validar, verificar, proteger, garantir, auditar
-- revisar, inspecionar, certificar, assegurar
-
-**Balancer (Pax, Morgan):**
-- equilibrar, harmonizar, priorizar, alinhar, integrar
-- negociar, mediar, sincronizar, coordenar
-
-### Emoji Palette System
-
-**High Frequency:**
-- ✅ ❌ ⚠️ 🎯 🚀 ⭐ 💡 🔥
-
-**Medium Frequency:**
-- 📊 📋 📝 🔍 💻 🛡️ 🏛️ 🌊
-
-**Low Frequency:**
-- Agent-specific emojis only
-
-**Minimal:**
-- Status indicators only (✅ ❌ ⚠️)
-
----
-
-## Agent Roles & Specializations
-
-### Development Team
-
-**💻 Dex (Builder) - Developer**
-- **Role:** Full-stack implementation
-- **Commands:** `*develop-story`, `*apply-qa-fixes`, `*improve-code-quality`
-- **When to Use:** Code implementation, debugging, refactoring
-
-**🛡️ Quinn (Guardian) - QA Engineer**
-- **Role:** Quality assurance and testing
-- **Commands:** `*review`, `*code-review`, `*gate`, `*nfr-assess`
-- **When to Use:** Testing, quality validation, acceptance criteria
-
-**🏛️ Aria (Visionary) - Architect**
-- **Role:** System architecture and design
-- **Commands:** `*create-full-stack-architecture`, `*document-project`
-- **When to Use:** Architecture decisions, system design, tech stack
-
----
-
-### Product & Agile Team
-
-**📋 Pax (Balancer) - Product Owner**
-- **Role:** Story management and backlog
-- **Commands:** `*create-next-story`, `*validate-story-draft`, `*sync-story`
-- **When to Use:** Story creation, backlog prioritization, acceptance
-
-**📊 Morgan (Balancer) - Product Manager**
-- **Role:** Product strategy and roadmap
-- **Commands:** `*create-doc`, `*brownfield-create-epic`
-- **When to Use:** PRDs, product strategy, stakeholder management
-
-**🌊 Sage (Flow Master) - Scrum Master**
-- **Role:** Process facilitation and flow
-- **Commands:** `*execute-checklist`, `*correct-course`
-- **When to Use:** Sprint planning, retrospectives, flow optimization
-
----
-
-### Specialized Agents
-
-**🔍 Scout (Explorer) - Business Analyst**
-- **Role:** Requirements analysis and research
-- **Commands:** `*facilitate-brainstorming-session`, `*create-deep-research-prompt`
-- **When to Use:** Requirements elicitation, market research, analysis
-
-**🔧 Dara (Engineer) - Data Engineer**
-- **Role:** Data modeling and pipelines
-- **Commands:** `*setup-database`, `*domain-modeling`
-- **When to Use:** Database design, ETL pipelines, data architecture
-
-**⚙️ Gage (Operator) - DevOps Engineer**
-- **Role:** Deployment and operations
-- **Commands:** `*version-management`, `*github-pr-automation`, `*ci-cd-configuration`
-- **When to Use:** CI/CD, deployment, infrastructure, monitoring
-
-**🎨 Uma (Empathizer) - UX Design Expert**
-- **Role:** User experience and design systems
-- **Commands:** `*ux-user-research`, `*ux-create-wireframe`, `*audit-codebase`
-- **When to Use:** UX research, design systems, accessibility
-
----
-
-### Framework Agents
-
-**⭐ Orion (Orchestrator) - AIOS Master**
-- **Role:** Framework orchestration and agent coordination
-- **Commands:** `*create-agent`, `*create-task`, `*create-workflow`
-- **When to Use:** Framework development, agent creation, workflow design
-
-**🗄️ DB Sage - Database Architect**
-- **Role:** Database schema design and optimization
-- **When to Use:** Complex database design, query optimization
-
-**🐙 GitHub DevOps - Git Operations**
-- **Role:** Git push operations and PR management
-- **When to Use:** Git push, PR creation (not available for local operations)
-
----
-
-## Greeting System
-
-### Three Greeting Levels
-
-**1. Minimal** (Quick activation)
-```
-💻 dev Agent ready
-```
-
-**2. Named** (Standard, personalized)
-```
-💻 Dex (Builder) pronto. Vamos construir isso!
-```
-
-**3. Archetypal** (Full personality)
-```
-💻 Dex the Builder (♒ Aquarius) ready to implement!
-```
-
-### Contextual Greeting Components
-
-**Complete Greeting Structure:**
-
-```
-{Archetypal Greeting}
-
-📊 **Project Status:**
-  - 🌿 **Branch:** main
-  - 📝 **Modified:** file1.md, file2.js ...and 10 more
-  - 📖 **Recent:** feat: complete story implementation
-  - 📌 **Story:** STORY-6.1.4
-
-💡 **Context:** {Intelligent narrative based on previous work}
-   **Recommended:** Use *{command} to continue
-
-**Quick Commands:**
-   - *help: Show all available commands
-   - *command1: Description
-   - *command2: Description
-
-Type *guide for comprehensive usage instructions.
-
-— {Agent Signature}
-```
-
-### Context Intelligence
-
-The greeting system analyzes:
-- **Previous Agent:** Who was active before
-- **Modified Files:** What files were changed
-- **Current Story:** What story is being worked on
-- **Last Commands:** What commands were recently used
-- **Session Type:** New, existing, or workflow session
-
-**Example Context:**
-```
-💡 **Context:** Vejo que @Dex finalizou a implementação do 
-   **`greeting-builder.js`** no **`story-6.1.4.md`**. 
-   Agora podemos revisar a qualidade dessa implementação
-   
-   **Recommended:** Use `*review story-6.1.4.md` para continuar
-```
-
----
-
-# Part IV: Task & Workflow System
-
-## Task Format Specification
-
-### Universal Task Structure (AIOS v1.0)
-
-Every task follows this specification:
-
-```yaml
-task: {taskIdentifier()}
-responsável: {AgentName}           # Agent executing (Dex, Quinn, etc.)
-responsavel_type: Agente           # Agente | Worker | Humano | Clone
-atomic_layer: {Layer}              # Optional for open-source
-
-**Entrada:**
-- campo: {fieldName}
-  tipo: {type}                     # string | number | boolean | array | object
-  origem: {source}                 # Step X | User Input | config | agent output
-  obrigatório: {true|false}
-  padrão: {defaultValue}           # Optional
-  validação: {validationRule}      # Optional
-
-**Saída:**
-- campo: {fieldName}
-  tipo: {type}
-  destino: {destination}           # Step Y | state | output | multiple steps
-  persistido: {true|false}         # Saved to file/DB or memory-only
-  cache_key: {key}                 # Optional: if cacheable
-
-**Checklist:**
-  pre-conditions:
-    - [ ] {condition}
-      tipo: pre-condition
-      blocker: {true|false}
-      validação: {validation_logic}
-  
-  post-conditions:
-    - [ ] {condition}
-      tipo: post-condition
-      blocker: {true|false}
-      validação: {validation_logic}
-  
-  acceptance-criteria:
-    - [ ] {criterion}
-      tipo: acceptance
-      blocker: false
-      story: {STORY-XXX}
-
-**Performance:**
-- duration_expected: {X}ms
-- cost_estimated: ${Y}
-- cacheable: {true|false}
-- parallelizable: {true|false}
-
-**Error Handling:**
-- strategy: {retry|fallback|abort}
-- retry:
-    max_attempts: {N}
-    backoff: {linear|exponential}
-```
-
-### Task Components Explained
-
-**Entrada (Input):**
-- Defines all required and optional inputs
-- Specifies data types and validation rules
-- Documents default values
-- Tracks data origin (previous step, user, config)
-
-**Saída (Output):**
-- Defines all outputs produced
-- Specifies destination (next step, state, file)
-- Indicates persistence (temporary or permanent)
-- Enables caching when appropriate
-
-**Checklist:**
-- **Pre-conditions:** Validated BEFORE execution (blocking)
-- **Post-conditions:** Validated AFTER execution (quality gates)
-- **Acceptance Criteria:** Manual verification steps
-
-**Performance:**
-- Expected duration for tracking
-- Cost estimation (for AI executors)
-- Cacheability for optimization
-- Parallelizability for concurrency
-
-**Error Handling:**
-- Strategy: retry, fallback, or abort
-- Retry configuration with backoff
-- Fallback values or alternative flows
-- Notification mechanisms
-
----
-
-## Execution Modes
-
-### The Three Execution Modes
-
-Every task supports three execution modes to balance automation, education, and control:
-
-#### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
-
-**Characteristics:**
-- ✅ Autonomous decision making
-- ✅ All decisions logged to `.ai/decision-log-{task-id}.md`
-- ✅ Minimal user interaction
-- ✅ Fast execution
-
-**Best For:**
-- Experienced developers
-- Simple, well-defined tasks
-- Time-sensitive work
-- Repetitive operations
-
-**Example:**
-```yaml
-mode: yolo
-```
-
-**Decision Logging:**
-```markdown
-## Decision: Use TypeScript for API layer
-**Context:** Need to define type-safe API contracts
-**Options:** [TypeScript, JavaScript with JSDoc]
-**Selected:** TypeScript
-**Rationale:** Better IDE support and compile-time checks
-**Timestamp:** 2025-01-18T14:30:00Z
-```
-
----
-
-#### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
-
-**Characteristics:**
-- ✅ Explicit decision checkpoints
-- ✅ Educational explanations
-- ✅ Collaborative decision making
-- ✅ Context preservation
-
-**Best For:**
-- Learning new patterns
-- Complex decisions
-- Collaborative work
-- Code reviews
-
-**Example:**
-```yaml
-mode: interactive
-```
-
-**Checkpoint Example:**
-```markdown
-🤔 **Decision Point:** Database Technology Selection
-
-**Options:**
-1. PostgreSQL (Relational, ACID, complex queries)
-2. MongoDB (Document, flexible schema, horizontal scaling)
-3. Supabase (PostgreSQL + Auth + Storage + Realtime)
-
-**Recommendation:** Supabase (Option 3)
-**Rationale:** Provides PostgreSQL + auth + storage out-of-box
-
-**Your choice?** (1-3 or 'explain')
-```
-
----
-
-#### 3. Pre-Flight Planning - Comprehensive Upfront (1 questionnaire)
-
-**Characteristics:**
-- ✅ Task analysis phase (identify ambiguities)
-- ✅ Comprehensive questionnaire
-- ✅ Zero ambiguity execution
-- ✅ Plan approval before work
-
-**Best For:**
-- Ambiguous requirements
-- Critical work (production, security)
-- Team consensus needed
-- Large-scale changes
-
-**Example:**
-```yaml
-mode: preflight
-```
-
-**Pre-Flight Questionnaire:**
-```markdown
-📋 **Pre-Flight Planning: Implement User Authentication**
-
-**Identified Ambiguities:**
-1. Authentication Method: Social login or email/password?
-2. Session Management: JWT or session cookies?
-3. Password Requirements: Complexity rules?
-4. MFA Support: Required or optional?
-5. User Roles: RBAC or simple user types?
-
-**Please Answer:**
-[... comprehensive questionnaire ...]
-
-**Execution Plan:**
-[... generated after questionnaire ...]
-
-**Approve plan?** (yes/no/modify)
-```
-
----
-
-### Mode Selection Guidelines
-
-| Scenario | YOLO | Interactive | Pre-Flight |
-|----------|------|-------------|------------|
-| **Simple CRUD** | ✅ Perfect | ⚠️ Overkill | ❌ Too much |
-| **Learning new tech** | ❌ Miss details | ✅ Perfect | ⚠️ Good |
-| **Security feature** | ❌ Risky | ⚠️ Good | ✅ Perfect |
-| **Time pressure** | ✅ Perfect | ⚠️ Slower | ❌ Slow |
-| **Team project** | ❌ Solo | ⚠️ Good | ✅ Perfect |
-| **Experimental** | ✅ Perfect | ✅ Good | ❌ Overhead |
-
----
-
-## Workflow Orchestration
-
-### Workflow Types
-
-AIOS supports multiple workflow patterns:
-
-1. **Sequential** - Tasks execute one after another
-2. **Fork/Join** - Parallel execution with synchronization
-3. **Organizer-Worker** - Dynamic work distribution
-4. **Conditional** - Branch based on conditions
-5. **Loop** - Repeat until condition met
-
-### Workflow Definition Format
-
-```yaml
-workflow:
-  id: {workflow-id}
-  name: {WorkflowName}
-  version: {X.Y.Z}
-  type: {sequential|fork-join|organizer-worker|conditional|loop}
-  
-  steps:
-    - id: step-1
-      task: {task-name}
-      agent: {agent-id}
-      dependencies: []
-      condition: {optional}
-      
-    - id: step-2
-      task: {task-name}
-      agent: {agent-id}
-      dependencies: [step-1]
-      
-    - id: step-3
-      type: fork
-      branches:
-        - id: branch-a
-          steps: [...]
-        - id: branch-b
-          steps: [...]
-      join: step-4
-      
-    - id: step-4
-      type: join
-      merge_strategy: {combine|first|last|custom}
-```
-
-### Built-in Workflows
-
-**Greenfield Workflows:**
-- `greenfield-fullstack.yaml` - Complete full-stack project
-- `greenfield-service.yaml` - Backend service only
-- `greenfield-ui.yaml` - Frontend UI only
-
-**Brownfield Workflows:**
-- `brownfield-fullstack.yaml` - Add features to existing full-stack
-- `brownfield-service.yaml` - Extend existing backend
-- `brownfield-ui.yaml` - Enhance existing frontend
-
----
-
-## Fork/Join & Organizer-Worker Patterns
-
-### Fork/Join Pattern (Story 6.1.12)
-
-**Purpose:** Execute tasks in parallel and synchronize results
-
-**Use Cases:**
-- Parallel test execution
-- Multi-agent analysis
-- Concurrent API calls
-- Independent component building
-
-**Example:**
-
-```yaml
-- id: analyze-architecture
-  type: fork
-  branches:
-    - id: frontend-analysis
-      agent: architect
-      task: analyze-frontend-architecture
-      
-    - id: backend-analysis
-      agent: architect
-      task: analyze-backend-architecture
-      
-    - id: database-analysis
-      agent: db-sage
-      task: analyze-database-schema
-      
-  join: merge-analysis
-  merge_strategy: combine_reports
-
-- id: merge-analysis
-  type: join
-  task: consolidate-architecture-report
-  agent: architect
-```
-
-**Merge Strategies:**
-- `combine` - Combine all results
-- `first` - Use first completed result
-- `last` - Use last completed result
-- `custom` - Custom merge function
-
----
-
-### Organizer-Worker Pattern (Story 6.1.13)
-
-**Purpose:** Intelligent work distribution across agents
-
-**Use Cases:**
-- Dynamic task distribution
-- Load balancing
-- Skill-based assignment
-- Scalable multi-agent coordination
-
-**Pattern Structure:**
-
-```
-┌─────────────────────────────────────┐
-│   Organizer Agent                   │
-│   (aios-master)                     │
-│   - Receives work                   │
-│   - Distributes to workers          │
-│   - Collects results                │
-│   - Merges outputs                  │
-└─────────────────────────────────────┘
-         ↓          ↓          ↓
-┌──────────┐  ┌──────────┐  ┌──────────┐
-│ Worker 1 │  │ Worker 2 │  │ Worker 3 │
-│ (dev)    │  │ (dev)    │  │ (qa)     │
-└──────────┘  └──────────┘  └──────────┘
-```
-
-**Agent Role Extension:**
-
-```yaml
-# Organizer Agent
-agent:
-  id: aios-master
-  role: organizer              # NEW: organizer role
-  can_distribute_work: true
-
-# Worker Agents
-agent:
-  id: dev
-  role: worker                 # NEW: worker role (default)
-  skills: [coding, testing]
-```
-
-**Distribution Strategies:**
-
-1. **Round Robin** - Distribute evenly
-```yaml
-distribution_strategy: round_robin
-```
-
-2. **Load Balanced** - Consider current workload
-```yaml
-distribution_strategy: load_balanced
-max_concurrent_tasks: 3
-```
-
-3. **Skill Based** - Match skills to requirements
-```yaml
-distribution_strategy: skill_based
-required_skills: [coding, frontend]
-```
-
-**Example Workflow:**
-
-```yaml
-- id: implement-features
-  type: organizer-worker
-  organizer: aios-master
-  workers: [dev-1, dev-2, dev-3]
-  distribution_strategy: skill_based
-  
-  work_items:
-    - feature: user-authentication
-      required_skills: [backend, security]
-    - feature: dashboard-ui
-      required_skills: [frontend, react]
-    - feature: data-pipeline
-      required_skills: [data, etl]
-  
-  merge_strategy: combine
-  failure_strategy: reassign
-```
-
----
-
-# Part V: Executor Types
-
-## The Four Executor Types
-
-### 1. Agente (AI-Powered Execution)
-
-**Definition:** AI agent using Large Language Models for creative/analytical tasks
-
-**When to Use:**
-- ✅ Requires creativity or subjective judgment
-- ✅ Natural language understanding/generation
-- ✅ Contextual analysis
-- ✅ No deterministic algorithm
-
-**Examples:**
-- Analyze requirements and extract insights
-- Generate code from specifications
-- Design system architecture
-- Review code for quality
-- Create documentation
-
-**Characteristics:**
-- **Cost:** $$$$ High ($0.001 - $0.01 per execution)
-- **Speed:** Slow (3-10 seconds)
-- **Deterministic:** ❌ No (stochastic outputs)
-
----
-
-### 2. Worker (Script-Based Execution)
-
-**Definition:** Deterministic script/function with predefined logic
-
-**When to Use:**
-- ✅ Deterministic (same input → same output)
-- ✅ Data transformation or validation
-- ✅ File/database operations
-- ✅ External API calls (no AI)
-
-**Examples:**
-- Load configuration from JSON
-- Validate HTML structure
-- Export PNG from HTML
-- Calculate metrics
-- Run migrations
-
-**Characteristics:**
-- **Cost:** $ Low ($0 - $0.001 per execution)
-- **Speed:** Fast (< 1 second)
-- **Deterministic:** ✅ Yes (repeatable)
-
----
-
-### 3. Humano (Manual Human Execution)
-
-**Definition:** Human operator for subjective judgment or approval
-
-**When to Use:**
-- ✅ Requires human subjective judgment
-- ✅ Quality gate or approval step
-- ✅ Sensitive decisions
-- ✅ Cannot be automated (yet)
-
-**Examples:**
-- Review and approve/reject work
-- Make strategic decisions
-- Handle edge cases
-- Provide creative direction
-- Security review
-
-**Characteristics:**
-- **Cost:** $$$ Medium ($5 - $50 per execution)
-- **Speed:** Very Slow (minutes to hours)
-- **Deterministic:** ❌ No (subjective)
-
----
-
-### 4. Clone (Mind Emulation with Heuristics)
-
-**Definition:** AI agent with personality heuristics and domain axioms
-
-**When to Use:**
-- ✅ Requires specific domain expertise
-- ✅ Must follow specific methodology
-- ✅ Needs validation against established principles
-- ✅ Benefits from "personality-driven" execution
-
-**Examples:**
-- Validate components (Atomic Design - Brad Frost)
-- Review copy (Alex Hormozi methodology)
-- Evaluate design consistency
-- Apply mental models
-
-**Characteristics:**
-- **Cost:** $$$$ High ($0.002 - $0.015 per execution)
-- **Speed:** Slow (5-15 seconds)
-- **Deterministic:** ⚠️ Partial (heuristics guide AI)
-
----
-
-## Executor Decision Tree
-
-### Decision Flow
-
-```
-Task to Execute
-    ↓
-Requires Creativity/Subjectivity?
-    ├─ NO → Deterministic Algorithm Exists?
-    │           ├─ YES → Worker (script)
-    │           └─ NO → Requires Human Judgment?
-    │                       ├─ YES → Critical Decision?
-    │                       │           ├─ YES → Humano
-    │                       │           └─ NO → Specific Methodology?
-    │                       │                       ├─ YES → Clone
-    │                       │                       └─ NO → Agente
-    │                       └─ NO → Agente
-    └─ YES → Requires Human Judgment?
-                ├─ YES → Critical Decision?
-                │           ├─ YES → Humano
-                │           └─ NO → Specific Methodology?
-                │                       ├─ YES → Clone
-                │                       └─ NO → Agente
-                └─ NO → Specific Methodology?
-                            ├─ YES → Clone
-                            └─ NO → Agente
-```
-
-### Decision Criteria
-
-| Criterion | Worker | Agente | Humano | Clone |
-|-----------|--------|--------|--------|-------|
-| **Creativity Required** | ❌ | ✅ | ✅ | ✅ |
-| **Deterministic** | ✅ | ❌ | ❌ | ⚠️ |
-| **Cost** | $ | $$$$ | $$$ | $$$$ |
-| **Speed** | Fast | Slow | Very Slow | Slow |
-| **Human Judgment** | ❌ | ❌ | ✅ | ❌ |
-| **Methodology** | ❌ | ❌ | ⚠️ | ✅ |
-
----
-
-# Part VI: Standards & Best Practices
-
-## Coding Standards
-
-### JavaScript/TypeScript Standards
-
-**Naming Conventions:**
-- `camelCase` for variables, functions, methods
-- `PascalCase` for classes, components, interfaces
-- `UPPER_CASE` for constants
-- `kebab-case` for file names
-
-**Code Structure:**
-```javascript
-// ✅ GOOD
-const userProfile = {
-  firstName: 'John',
-  lastName: 'Doe',
-  isActive: true
-};
-
-// ❌ BAD
-const user_profile = {
-  first_name: 'John',
-  last_name: 'Doe',
-  is_active: true
-};
-```
-
-**Function Design:**
-- Keep functions small (<50 lines)
-- Single responsibility
-- Pure functions when possible
-- Document with JSDoc
-
-**Error Handling:**
-```javascript
-// ✅ GOOD
-try {
-  const result = await operation();
-  return { success: true, data: result };
-} catch (error) {
-  logger.error('Operation failed:', error);
-  return { success: false, error: error.message };
-}
-
-// ❌ BAD
-const result = await operation(); // No error handling
-```
-
----
-
-### CSS Standards
-
-**Naming Convention:** `kebab-case`
-
-```css
-/* ✅ GOOD */
-.content-area {
-  padding: var(--spacing-md);
-}
-
---spacing-md: 200px;
---color-primary: #007bff;
-
-/* ❌ BAD */
-.contentArea {
-  padding: var(--spacing_md);
-}
-```
-
-**CSS Organization:**
-1. Layout properties
-2. Box model properties
-3. Visual properties
-4. Typography
-5. Misc
-
----
-
-### Database Standards
-
-**Naming Convention:** `snake_case`
-
-```sql
--- ✅ GOOD
-CREATE TABLE workflow_executions (
-  execution_id UUID PRIMARY KEY,
-  workflow_id UUID NOT NULL,
-  started_at TIMESTAMP,
-  completed_at TIMESTAMP,
-  status VARCHAR(20)
-);
-
--- ❌ BAD
-CREATE TABLE workflowExecutions (
-  executionId UUID PRIMARY KEY,
-  workflowId UUID NOT NULL,
-  startedAt TIMESTAMP
-);
-```
-
----
-
-## Technology Stack
-
-### Frontend Stack
-
-**Core:**
-- **Framework:** Next.js 14 (App Router)
-- **UI Library:** React 18
-- **Language:** TypeScript 5
-- **Styling:** Tailwind CSS 3
-
-**State Management:**
-- **Global:** Zustand or React Context
-- **Server:** React Server Components
-- **Forms:** React Hook Form + Zod
-
-**UI Components:**
-- **Library:** shadcn/ui (Radix UI)
-- **Icons:** Lucide React
-- **Animations:** Framer Motion
-
----
-
-### Backend Stack
-
-**Core:**
-- **Framework:** NestJS
-- **Language:** TypeScript 5
-- **Runtime:** Node.js 18+ (LTS)
-
-**Database:**
-- **Primary:** Supabase (PostgreSQL)
-- **ORM:** Prisma or TypeORM
-- **Migrations:** Prisma Migrate
-
-**Authentication:**
-- **Provider:** Supabase Auth
-- **Strategy:** JWT + Row Level Security (RLS)
-
-**API:**
-- **Type:** REST + tRPC (type-safe)
-- **Validation:** Zod
-- **Documentation:** OpenAPI/Swagger
-
----
-
-### DevOps & Infrastructure
-
-**Version Control:**
-- **Platform:** GitHub
-- **Workflow:** Feature branches + PRs
-- **CI/CD:** GitHub Actions
-
-**Deployment:**
-- **Platform:** Railway (recommended) or Vercel
-- **Strategy:** Zero-downtime deployment
-- **Environments:** dev, staging, production
-
-**Monitoring:**
-- **Logs:** Structured logging (Winston/Pino)
-- **Metrics:** Custom dashboards
-- **Errors:** Error tracking service
-
----
-
-## Quality Gates & CodeRabbit Integration
-
-### CodeRabbit Quality Gates
-
-AIOS uses **CodeRabbit** for automated code review at three key checkpoints:
-
-#### 1. Pre-Commit Gate (@dev)
-
-**When:** Before committing code  
-**Command:** `*code-review uncommitted`
-
-**Focus:**
-- Syntax errors
-- Basic code quality
-- Linting violations
-- Obvious bugs
-
-**Action:** Fix CRITICAL issues before committing
-
----
-
-#### 2. Mid-Point Review (@dev + @qa)
-
-**When:** During story implementation  
-**Command:** `*code-review --base main`
-
-**Focus:**
-- Architecture patterns
-- Error handling
-- Performance issues
-- Integration points
-
-**Action:** Address HIGH and CRITICAL issues
-
----
-
-#### 3. Pre-PR Gate (@dev + @qa)
-
-**When:** Before creating PR  
-**Command:** `*code-review --base main --full`
-
-**Focus:**
-- Complete code quality
-- Test coverage
-- Documentation
-- Backward compatibility
-- Security vulnerabilities
-
-**Action:** Resolve ALL CRITICAL, address HIGH issues
-
----
-
-### Severity Levels
-
-| Severity | Action | Examples |
-|----------|--------|----------|
-| **CRITICAL** | ❌ Block | Security vulnerabilities, data loss risks |
-| **HIGH** | ⚠️ Fix before PR | Performance issues, error handling gaps |
-| **MEDIUM** | 📋 Document as debt | Code maintainability, design patterns |
-| **LOW** | ℹ️ Optional | Style inconsistencies, minor optimizations |
-
----
-
-### Story-Specific Integration
-
-Each story includes CodeRabbit integration:
-
-```yaml
-# CodeRabbit Integration
-story_type: [Feature|Bug|Refactor|Architecture]
-specialized_agents: [@dev, @qa, @architect]
-
-quality_gates:
-  pre_commit: Focus on syntax and basic quality
-  mid_point: Focus on architecture and integration
-  pre_pr: Comprehensive review before merge
-
-focus_areas:
-  - Error Handling: Check all error paths
-  - Performance: Validate response times
-  - Security: Check for vulnerabilities
-  - Integration: Validate API contracts
-```
-
----
-
-# Part VII: Migration & Roadmap
-
-## Current Migration Status
-
-### Epic 6.1: Agent Identity System (In Progress)
-
-**Objective:** Modernize agent system with personality, unified greeting, and improved structure
-
-**Waves:**
-
-**Wave 1 - Foundation (In Progress):**
-- ✅ Story 6.1.1: Agent Personalization Implementation
-- ✅ Story 6.1.2: Persona Profile Integration
-- ✅ Story 6.1.3: Greeting Levels Implementation
-- ✅ Story 6.1.4: Unified Greeting System Integration
-- ⏸️ Story 6.1.4.1: Fix Remaining Agent YAML Issues (Approved)
-- ✅ Story 6.1.5: Output Formatter Implementation
-- ✅ Story 6.1.6: Output Formatter Testing
-- ✅ Story 6.1.7: Core Tasks Migration
-- ✅ Story 6.1.8: Templates Migration
-- ✅ Story 6.1.9: Checklists Migration
-- 📋 Story 6.1.10: Dependencies & Data Files Migration (Ready)
-- 📋 Story 6.1.11: AIOS-Master Tasks Creation (Ready)
-- 📋 Story 6.1.12: Fork/Join Workflow Operations (Ready)
-- 📋 Story 6.1.13: Organizer-Worker Pattern (Ready)
-
-**Wave 2 - Enhancement (Pending):**
-- ❌ Story 6.1.14: Expansion Pack Framework (REJECTED - Architecture conflict)
-- ❌ Story 6.1.14.1-3: Expansion Pack Extraction (REJECTED - Architecture conflict)
-- 📋 Story 6.1.15: Subdirectory Architecture Validation (PROPOSED)
-- 📋 Story 6.1.16-21: Subdirectory Migration (PROPOSED - if 6.1.15 succeeds)
-
----
-
-## Future Architecture (Q2 2026)
-
-### Repository Restructuring (Decision 005)
-
-**Current State:**
-```
-aios-fullstack/
-├── .aios-core/              # Framework embedded in project
-├── frontend/
-├── backend/
-└── docs/
-```
-
-**Future State (Q2 2026):**
-```
-aios/
-├── aios-core/               # Framework repository (standalone)
-│   ├── agents/
-│   ├── tasks/
-│   ├── templates/
-│   └── ...
-│
-└── aios-fullstack/          # Project repository
-    ├── frontend/
-    ├── backend/
-    └── .aios/               # Framework reference (git submodule)
-```
-
-**Benefits:**
-- ✅ Framework versioning independent of project
-- ✅ Easier framework updates
-- ✅ Cleaner project structure
-- ✅ Multiple projects share same framework
-
-**Migration Timeline:**
-- **Q1 2026:** Prepare for separation
-- **Q2 2026:** Execute repository split
-- **Q3 2026:** Complete migration
-
----
-
-## Subdirectory Migration Plan
-
-### The Challenge (Story 6.1.15+)
-
-**Current Structure:** Flat files in `.aios-core/{type}/`
-```
-.aios-core/
-├── tasks/
-│   ├── create-doc.md
-│   ├── develop-story.md
-│   ├── generate-tests.md
-│   └── ... (60+ files)
-```
-
-**Proposed Structure:** Organized subdirectories
-```
-.aios-core/
-├── tasks/
-│   ├── documentation/
-│   │   ├── create-doc.md
-│   │   └── document-project.md
-│   ├── development/
-│   │   ├── develop-story.md
-│   │   └── apply-qa-fixes.md
-│   └── testing/
-│       ├── generate-tests.md
-│       └── nfr-assess.md
-```
-
----
-
-### Migration Phases
-
-**Phase 0: Validation (Story 6.1.15)**
-- Duration: 2-3 days
-- Investment: $100-150
-- Goal: Test subdirectory architecture works
-- Deliverable: GO/NO-GO decision
-
-**Phase 1: Core Infrastructure (Story 6.1.16)**
-- Duration: 1.5 days
-- Investment: $75
-- Goal: Update file resolution logic
-- Deliverable: Scripts support subdirectories
-
-**Phase 2: File Migration (Stories 6.1.17-19)**
-- Duration: 10-15 days
-- Investment: $500-750
-- Goal: Move files to subdirectories
-- Deliverable: Organized framework structure
-
-**Phase 3: Reference Updates (Story 6.1.20)**
-- Duration: 1 day
-- Investment: $50
-- Goal: Update all agent references
-- Deliverable: All references correct
-
-**Phase 4: Cleanup (Story 6.1.21)**
-- Duration: 0.5 day
-- Investment: $25
-- Goal: Remove backward compatibility
-- Deliverable: Optimized system
-
-**Total Effort:** 15-21 days, $750-1,050
-
----
-
-### Proposed Subdirectory Organization
-
-**data/ subdirectories:**
-```
-data/
-├── agile/                   # Agile/Scrum knowledge
-├── architecture/            # Architecture patterns
-├── design-systems/          # UX/Design frameworks
-├── database/                # Database knowledge
-├── infrastructure/          # DevOps/Infrastructure
-├── quality/                 # Testing/QA knowledge
-└── technical/               # Technical standards
-```
-
-**tasks/ subdirectories:**
-```
-tasks/
-├── agile/                   # Story management
-├── architecture/            # Architecture tasks
-├── database/                # Database tasks
-├── data-engineering/        # Data engineering
-├── development/             # Development tasks
-├── devops/                  # DevOps tasks
-├── documentation/           # Documentation tasks
-├── quality/                 # QA tasks
-├── research/                # Research/Analysis
-├── ux-design/               # UX/Design tasks
-└── framework/               # Framework management
-```
-
-**templates/ subdirectories:**
-```
-templates/
-├── agile/                   # Story, epic templates
-├── architecture/            # Architecture templates
-├── database/                # Database templates
-├── infrastructure/          # Infrastructure templates
-├── product/                 # PRD, brief templates
-└── ux-design/               # Design templates
-```
-
----
-
-### Risk Mitigation
-
-**Risks:**
-1. ❌ Breaking agent loading
-2. ❌ Performance degradation
-3. ❌ Incomplete migration
-4. ❌ Script path resolution failures
-
-**Mitigations:**
-1. ✅ Test in isolated environment first (Phase 0)
-2. ✅ Benchmark performance during validation
-3. ✅ Automated migration scripts + validation
-4. ✅ Comprehensive script audit (Phase 1)
-5. ✅ Backward compatibility during migration
-6. ✅ Git-based rollback strategy
-
----
-
-# Part VIII: Appendices
-
-## Glossary
-
-### Core Concepts
-
-**AIOS:** AI Operating System - Framework for orchestrating AI agents and workflows
-
-**Agent:** AI-powered executor with personality, specialized role, and commands
-
-**Task:** Executable workflow with inputs, outputs, validation, and error handling
-
-**Workflow:** Multi-step orchestration coordinating multiple agents/tasks
-
-**Executor:** Entity that executes tasks (Agente, Worker, Humano, Clone)
-
-**Archetype:** Personality template (Builder, Guardian, Balancer, etc.)
-
-**Persona Profile:** Agent personality configuration (communication, vocabulary, greetings)
-
-**Greeting System:** Contextual agent activation with status, context, and commands
-
-**Quality Gate:** Validation checkpoint using CodeRabbit or manual review
-
-**Fork/Join:** Parallel execution pattern with synchronization
-
-**Organizer-Worker:** Dynamic work distribution pattern
-
-**Execution Mode:** YOLO (autonomous), Interactive (balanced), Pre-Flight (comprehensive)
-
----
-
-### File Types
-
-**Agent Definition (.md):** Agent personality, role, commands, dependencies
-
-**Task Definition (.md):** Executable workflow with YAML specification
-
-**Template (.yaml/.md):** Document generator with variables and structure
-
-**Workflow (.yaml):** Multi-agent orchestration definition
-
-**Checklist (.md):** Validation process with checkboxes
-
-**Data/KB (.md/.yaml):** Knowledge base, reference material
-
-**Script (.js):** Utility, automation, or tool
-
-**Config (.yaml):** Configuration file
-
----
-
-### Patterns
-
-**MCP (Model Context Protocol):** Integration protocol for external tools
-
-**RLS (Row Level Security):** Database security at row level
-
-**RBAC (Role-Based Access Control):** Permission system
-
-**JWT (JSON Web Token):** Authentication token standard
-
-**ETL (Extract, Transform, Load):** Data pipeline pattern
-
-**CRUD (Create, Read, Update, Delete):** Basic operations
-
-**CI/CD (Continuous Integration/Deployment):** Automation pipeline
-
-**PRD (Product Requirements Document):** Product specification
-
-**NFR (Non-Functional Requirements):** Quality attributes
-
----
-
-## Decision History
-
-### Major Architectural Decisions
-
-**Decision 001:** Agent Personalization Standard (2025-01-14)
-- **Status:** Implemented
-- **Decision:** Three-layer personality system (persona → formatter → output)
-- **Rationale:** Familiaridade + Personalização = Produtividade
-
-**Decision 002:** Unified Greeting System (2025-01-16)
-- **Status:** Implemented
-- **Decision:** Single greeting generator for all agents
-- **Rationale:** Consistency, performance, maintainability
-
-**Decision 003:** Task Format v2.0 (2025-11-13)
-- **Status:** Implemented
-- **Decision:** Universal task specification with execution modes
-- **Rationale:** Scalability, reusability, clarity
-
-**Decision 004:** Open Source vs Service (2025-01-14)
-- **Status:** Defined
-- **Decision:** Open-source = Agente-only, Service = All executors
-- **Rationale:** Community vs commercial differentiation
-
-**Decision 005:** Repository Restructuring (2025-01-15)
-- **Status:** Planned (Q2 2026)
-- **Decision:** Split framework and project repositories
-- **Rationale:** Independent versioning, cleaner structure
-
-**Decision 006:** Subdirectory Migration (2025-01-18)
-- **Status:** Approved (Pending validation)
-- **Decision:** Organize framework files in domain subdirectories
-- **Rationale:** Scalability, better organization, expansion packs support
-
-**Decision 007:** Expansion Pack Architecture (2025-01-18)
-- **Status:** REJECTED (Conflict with AIOS principles)
-- **Decision:** NO new directory types (methodologies/, patterns/)
-- **Rationale:** Violates 7-type framework structure
-- **Alternative:** Use subdirectories in existing types (data/, tasks/, templates/)
-
----
-
-## References
-
-### Internal Documentation
-
-- **Framework Structure:** `docs/architecture/source-tree.md`
-- **Coding Standards:** `docs/framework/coding-standards.md`
-- **Technology Stack:** `docs/framework/tech-stack.md`
-- **Agent Standard:** `.aios-core/docs/standards/AGENT-PERSONALIZATION-STANDARD-V1.md`
-- **Task Format:** `.aios-core/docs/standards/TASK-FORMAT-SPECIFICATION-V1.md`
-- **Executor Tree:** `.aios-core/docs/standards/EXECUTOR-DECISION-TREE.md`
-- **Architectural Decisions:** `.aios-core/docs/standards/V3-ARCHITECTURAL-DECISIONS.md`
-- **Repository Restructuring:** `docs/decisions/decision-005-repository-restructuring-FINAL.md`
-
-### Implementation Stories
-
-- **Story 6.1.4:** Unified Greeting System Integration
-- **Story 6.1.10:** Dependencies & Data Files Migration
-- **Story 6.1.11:** AIOS-Master Tasks Creation
-- **Story 6.1.12:** Fork/Join Workflow Operations
-- **Story 6.1.13:** Organizer-Worker Pattern Implementation
-
-### External Resources
-
-- **Atomic Design:** Brad Frost's methodology
-- **Twelve-Factor App:** Methodology for SaaS applications
-- **MCP Protocol:** Model Context Protocol specification
-- **Supabase Docs:** https://supabase.com/docs
-- **Next.js Docs:** https://nextjs.org/docs
-- **NestJS Docs:** https://docs.nestjs.com
-
----
-
-## Contributing
-
-### How to Contribute
-
-1. **Read this document** - Understand AIOS principles
-2. **Choose an area** - Framework, agents, tasks, workflows
-3. **Follow standards** - Coding standards, naming conventions
-4. **Test thoroughly** - Unit tests, integration tests
-5. **Document changes** - Update relevant docs
-6. **Submit PR** - Follow PR template
-
-### PR Template
-
-```markdown
-## Story Reference
-[Story 6.1.X] {Story Title}
-
-## Changes
-- [ ] Agent definitions updated
-- [ ] Task files created/modified
-- [ ] Templates added/changed
-- [ ] Tests added
-- [ ] Documentation updated
-
-## Testing
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing complete
-
-## CodeRabbit Review
-- [ ] Pre-commit review passed
-- [ ] All CRITICAL issues resolved
-- [ ] HIGH issues addressed or documented
-
-## Checklist
-- [ ] Follows coding standards
-- [ ] Naming conventions correct
-- [ ] No breaking changes (or documented)
-- [ ] Backward compatible
-```
-
----
-
-## Support & Contact
-
-### Getting Help
-
-1. **Documentation First:** Check this master document
-2. **Framework Docs:** Review specific docs in `docs/framework/`
-3. **Decision History:** Check `docs/decisions/`
-4. **Story Context:** Review implementation stories
-
-### Framework Team
-
-- **Architect:** Aria (@architect)
-- **Lead Developer:** Dex (@dev)
-- **Quality Lead:** Quinn (@qa)
-- **Product Owner:** Pax (@po)
-
----
-
-**Document Version:** 2.0.0  
-**Last Updated:** 2025-01-18  
-**Maintained By:** AIOS Framework Team  
-**Status:** Living Document
-
----
-
-*This document consolidates all AIOS framework documentation into a single, comprehensive reference. It is a living document and will be updated as the framework evolves.*
-
-— Aria, arquitetando o futuro 🏗️
-
+# AIOS Framework - Complete Documentation
+
+> **⚠️ DEPRECATION NOTICE**
+>
+> This document describes **v2.0.0** of the AIOS Framework.
+>
+> **For the current version (v2.1), see:**
+> - [AIOS-LIVRO-DE-OURO-V2.1-COMPLETE.md](./AIOS-LIVRO-DE-OURO-V2.1-COMPLETE.md) - Complete v2.1 framework guide
+> - [STANDARDS-INDEX.md](./STANDARDS-INDEX.md) - Navigation for all standards
+>
+> **Key changes in v2.1:**
+> - 4-module architecture (core, development, product, infrastructure)
+> - Squad System (replaces "Expansion Packs")
+> - Multi-repo strategy (3 public + 2 private repos)
+> - Quality Gates 3-layer system
+> - Story Template v2.0
+>
+> This document is retained for historical reference only.
+
+**Version:** 2.0.0 (DEPRECATED - See v2.1)
+**Status:** ⚠️ Deprecated - Reference Only
+**Last Updated:** 2025-01-18
+**Maintained By:** AIOS Framework Team
+
+---
+
+## 📋 Table of Contents
+
+### Part I: Framework Overview
+1. [What is AIOS?](#what-is-aios)
+2. [Core Philosophy](#core-philosophy)
+3. [Framework Architecture](#framework-architecture)
+4. [Getting Started](#getting-started)
+
+### Part II: Framework Structure
+5. [Directory Structure](#directory-structure)
+6. [File Organization](#file-organization)
+7. [Naming Conventions](#naming-conventions)
+
+### Part III: Agent System
+8. [Agent Architecture](#agent-architecture)
+9. [Agent Personalization](#agent-personalization)
+10. [Agent Roles & Specializations](#agent-roles--specializations)
+11. [Greeting System](#greeting-system)
+
+### Part IV: Task & Workflow System
+12. [Task Format Specification](#task-format-specification)
+13. [Execution Modes](#execution-modes)
+14. [Workflow Orchestration](#workflow-orchestration)
+15. [Fork/Join & Organizer-Worker Patterns](#forkjoin--organizer-worker-patterns)
+
+### Part V: Executor Types
+16. [The Four Executor Types](#the-four-executor-types)
+17. [Executor Decision Tree](#executor-decision-tree)
+
+### Part VI: Standards & Best Practices
+18. [Coding Standards](#coding-standards)
+19. [Technology Stack](#technology-stack)
+20. [Quality Gates & CodeRabbit Integration](#quality-gates--coderabbit-integration)
+
+### Part VII: Migration & Roadmap
+21. [Current Migration Status](#current-migration-status)
+22. [Future Architecture (Q2 2026)](#future-architecture-q2-2026)
+23. [Subdirectory Migration Plan](#subdirectory-migration-plan)
+
+### Part VIII: Appendices
+24. [Glossary](#glossary)
+25. [Decision History](#decision-history)
+26. [References](#references)
+
+---
+
+# Part I: Framework Overview
+
+## What is AIOS?
+
+**AIOS (AI Operating System)** is a sophisticated framework for orchestrating AI agents, workers, and humans in complex software development workflows. It provides a structured, scalable approach to building AI-assisted development teams with personality, coordination, and quality gates.
+
+### Key Capabilities
+
+- 🤖 **16 Specialized Agents** - Dev, QA, Architect, PM, PO, Analyst, Data Engineer, DevOps, etc.
+- 📋 **60+ Executable Tasks** - Story creation, code generation, testing, deployment, documentation
+- 📝 **20+ Templates** - PRDs, stories, architecture docs, test plans, database schemas
+- 🔄 **Multi-Agent Workflows** - Greenfield, brownfield, fork/join, organizer-worker patterns
+- 🎭 **Personalized Agent System** - Named personalities with archetypes, vocabularies, and signatures
+- 🎯 **Three Execution Modes** - YOLO (autonomous), Interactive (balanced), Pre-Flight (comprehensive)
+- ✅ **Quality Gates** - CodeRabbit integration, automated reviews, acceptance criteria validation
+
+---
+
+## Core Philosophy
+
+### Structure is Sacred. Tone is Flexible.
+
+AIOS follows a fundamental principle:
+
+> "Quando as informações estão sempre nas mesmas posições, nosso cérebro sabe onde buscar rápido."
+
+**FIXED:**
+- Template positions
+- Section order
+- Metric formats
+- File structure
+- Task workflows
+
+**FLEXIBLE:**
+- Status messages
+- Vocabulary choices
+- Emoji usage
+- Agent personality
+- Communication tone
+
+### Design Principles
+
+1. **Familiaridade + Personalização = Produtividade**
+   - Users learn structure once
+   - Personality makes it memorable
+   - Consistency enables speed
+
+2. **Separation of Concerns**
+   - Framework vs. Project
+   - Structure vs. Tone
+   - Automation vs. Human Judgment
+
+3. **Progressive Complexity**
+   - Simple by default
+   - Complex when needed
+   - Scalable architecture
+
+4. **Multi-Agent Coordination**
+   - Agents work together
+   - Clear handoffs
+   - Shared context
+
+---
+
+## Framework Architecture
+
+### Dual-Layer Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  FRAMEWORK LAYER (.aios-core/)                              │
+│  ├── Agents (16 specialists)                                │
+│  ├── Tasks (60+ executable workflows)                       │
+│  ├── Templates (20+ document generators)                    │
+│  ├── Workflows (6+ multi-agent orchestrations)              │
+│  ├── Checklists (6+ validation processes)                   │
+│  ├── Data (Knowledge base)                                  │
+│  ├── Scripts (54+ utilities)                                │
+│  └── Tools (MCP integrations)                               │
+└─────────────────────────────────────────────────────────────┘
+                         ↕
+┌─────────────────────────────────────────────────────────────┐
+│  PROJECT LAYER (root workspace)                             │
+│  ├── frontend/ (Next.js, React)                             │
+│  ├── backend/ (NestJS, Supabase)                            │
+│  ├── docs/ (Project documentation)                          │
+│  ├── tests/ (Unit, integration, E2E)                        │
+│  └── .aios/ (Session state, logs)                           │
+└─────────────────────────────────────────────────────────────┘
+```
+
+**Framework Layer:** Portable across all AIOS projects  
+**Project Layer:** Specific to each implementation
+
+---
+
+### Three-Layer Personality System
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│   LAYER 1: Agent Persona Config (.aios-core/agents/*.md)   │
+│   - Name, archetype, zodiac                                 │
+│   - Vocabulary, emoji palette                               │
+│   - Greeting levels, signature                              │
+└─────────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────┐
+│   LAYER 2: Output Formatter (.aios-core/scripts/)          │
+│   - greeting-builder.js                                     │
+│   - session-context-loader.js                               │
+│   - project-status-loader.js                                │
+└─────────────────────────────────────────────────────────────┘
+                         ↓
+┌─────────────────────────────────────────────────────────────┐
+│   LAYER 3: Standardized Output                              │
+│   - Fixed structure + personalized tone                     │
+│   - Contextual greetings                                    │
+│   - Agent signatures                                        │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Getting Started
+
+### Prerequisites
+
+- **Node.js** 18+ (LTS)
+- **Git** (version control)
+- **IDE:** Cursor or VS Code with Claude extension
+- **MCP Servers:** ClickUp, Context7, Exa (optional)
+
+### Quick Start
+
+```bash
+# 1. Clone the repository
+git clone <your-aios-project>
+cd <project-directory>
+
+# 2. Install dependencies
+npm install
+
+# 3. Configure AIOS
+# Edit .aios-core/core-config.yaml
+
+# 4. Activate first agent
+# In IDE: type /AIOS/agents/pm
+
+# 5. Create your first story
+*create-next-story
+```
+
+### First Commands to Try
+
+```bash
+# Product Owner (Story Management)
+/AIOS/agents/po
+*create-next-story
+*validate-story-draft docs/stories/your-story.md
+
+# Developer (Implementation)
+/AIOS/agents/dev
+*develop-story docs/stories/your-story.md
+
+# QA (Quality Assurance)
+/AIOS/agents/qa
+*review docs/stories/your-story.md
+*code-review
+```
+
+---
+
+# Part II: Framework Structure
+
+## Directory Structure
+
+### Complete Framework Structure
+
+```
+.aios-core/                              # Framework Core (Portable)
+├── agents/                              # 16 agent definitions
+│   ├── dev.md                           # 💻 Dex (Builder)
+│   ├── qa.md                            # 🛡️ Quinn (Guardian)
+│   ├── architect.md                     # 🏛️ Aria (Visionary)
+│   ├── pm.md                            # 📊 Morgan (Balancer)
+│   ├── po.md                            # 📋 Pax (Balancer)
+│   ├── sm.md                            # 🌊 Sage (Flow Master)
+│   ├── analyst.md                       # 🔍 Scout (Explorer)
+│   ├── data-engineer.md                 # 🔧 Dara (Engineer)
+│   ├── devops.md                        # ⚙️ Gage (Operator)
+│   ├── db-sage.md                       # 🗄️ [Database Architect]
+│   ├── ux-design-expert.md              # 🎨 Uma (Empathizer)
+│   ├── aios-master.md                   # ⭐ Orion (Orchestrator)
+│   ├── aios-developer.md                # 🛠️ [Framework Developer]
+│   ├── aios-orchestrator.md             # 🎭 [Workflow Orchestrator]
+│   ├── github-devops.md                 # 🐙 [Git Operations]
+│   └── test-agent.md                    # 🧪 [Test Agent]
+│
+├── tasks/                               # 60+ executable workflows
+│   ├── create-doc.md                    # Document generation
+│   ├── create-next-story.md             # Story creation
+│   ├── develop-story.md                 # Story implementation
+│   ├── review-story.md                  # Story review
+│   ├── validate-next-story.md           # Story validation
+│   ├── manage-story-backlog.md          # Backlog management
+│   ├── execute-checklist.md             # Checklist execution
+│   ├── document-project.md              # Project documentation
+│   ├── generate-tests.md                # Test generation
+│   ├── nfr-assess.md                    # Non-functional requirements
+│   ├── qa-gate.md                       # Quality gate decision
+│   ├── code-review.md                   # Automated code review
+│   ├── apply-qa-fixes.md                # QA fix application
+│   ├── improve-code-quality.md          # Code quality improvements
+│   ├── setup-database.md                # Database setup
+│   ├── domain-modeling.md               # Domain modeling
+│   ├── version-management.md            # Version management
+│   ├── pre-push-quality-gate.md         # Pre-push validation
+│   ├── github-pr-automation.md          # PR automation
+│   ├── create-agent.md                  # Agent creation
+│   ├── create-task.md                   # Task creation
+│   ├── create-workflow.md               # Workflow creation
+│   └── ... (40+ more)
+│
+├── templates/                           # 20+ document templates
+│   ├── story-tmpl.yaml                  # Story template v2.0
+│   ├── design-story-tmpl.yaml           # Design story template
+│   ├── prd-tmpl.yaml                    # PRD template
+│   ├── epic-tmpl.md                     # Epic template
+│   ├── architecture-tmpl.yaml           # Architecture template
+│   ├── fullstack-architecture-tmpl.yaml # Full-stack architecture
+│   ├── brownfield-architecture-tmpl.yaml # Brownfield architecture
+│   ├── schema-design-tmpl.yaml          # Database schema template
+│   ├── project-brief-tmpl.yaml          # Project brief
+│   ├── market-research-tmpl.yaml        # Market research
+│   ├── competitor-analysis-tmpl.yaml    # Competitor analysis
+│   ├── github-pr-template.md            # PR template
+│   ├── github-actions-ci.yml            # CI/CD template
+│   ├── personalized-task-template-v2.md # Task template
+│   └── ... (6+ more)
+│
+├── workflows/                           # 6 multi-step workflows
+│   ├── greenfield-fullstack.yaml        # Greenfield full-stack
+│   ├── greenfield-service.yaml          # Greenfield service
+│   ├── greenfield-ui.yaml               # Greenfield UI
+│   ├── brownfield-fullstack.yaml        # Brownfield full-stack
+│   ├── brownfield-service.yaml          # Brownfield service
+│   └── brownfield-ui.yaml               # Brownfield UI
+│
+├── checklists/                          # 6+ validation checklists
+│   ├── po-master-checklist.md           # PO validation
+│   ├── story-draft-checklist.md         # Story draft validation
+│   ├── story-dod-checklist.md           # Story Definition of Done
+│   ├── architect-checklist.md           # Architecture review
+│   ├── qa-checklist.md                  # QA validation
+│   ├── pm-checklist.md                  # PM validation
+│   └── change-checklist.md              # Change management
+│
+├── data/                                # Knowledge base
+│   ├── aios-kb.md                       # AIOS knowledge base
+│   ├── technical-preferences.md         # Tech stack preferences
+│   ├── elicitation-methods.md           # Elicitation techniques
+│   ├── brainstorming-techniques.md      # Brainstorming methods
+│   ├── mode-selection-best-practices.md # Execution mode guidance
+│   ├── test-levels-framework.md         # Testing strategy
+│   ├── test-priorities-matrix.md        # Test prioritization
+│   └── agent-config-requirements.yaml   # Agent requirements
+│
+├── scripts/                             # 54+ utility scripts
+│   ├── agent-config-loader.js           # Agent configuration
+│   ├── greeting-builder.js              # Greeting generation
+│   ├── generate-greeting.js             # Greeting orchestrator
+│   ├── session-context-loader.js        # Session management
+│   ├── project-status-loader.js         # Project status
+│   ├── config-cache.js                  # Configuration cache
+│   ├── performance-tracker.js           # Performance tracking
+│   ├── component-generator.js           # Component scaffolding
+│   ├── elicitation-engine.js            # Interactive elicitation
+│   ├── story-manager.js                 # Story lifecycle
+│   ├── yaml-validator.js                # YAML validation
+│   ├── usage-analytics.js               # Usage tracking
+│   ├── migrate-task-to-v2.js            # Task migration
+│   ├── validate-task-v2.js              # Task validation
+│   └── ... (40+ more)
+│
+├── tools/                               # Tool integrations
+│   ├── mcp/                             # MCP server configs
+│   │   ├── clickup-direct.yaml
+│   │   ├── context7.yaml
+│   │   └── exa-direct.yaml
+│   ├── cli/                             # CLI tool wrappers
+│   │   ├── github-cli.yaml
+│   │   └── railway-cli.yaml
+│   └── local/                           # Local tools
+│
+├── elicitation/                         # Elicitation engines
+│   ├── agent-elicitation.js
+│   ├── task-elicitation.js
+│   └── workflow-elicitation.js
+│
+├── core-config.yaml                     # Framework configuration
+├── install-manifest.yaml                # Installation manifest
+├── user-guide.md                        # User guide
+└── working-in-the-brownfield.md         # Brownfield guide
+```
+
+---
+
+## File Organization
+
+### File Types & Purposes
+
+| Type | Location | Purpose | Format |
+|------|----------|---------|--------|
+| **Agents** | `.aios-core/agents/*.md` | Agent definitions with persona | Markdown + YAML |
+| **Tasks** | `.aios-core/tasks/*.md` | Executable workflows | Markdown + YAML |
+| **Templates** | `.aios-core/templates/*.yaml` | Document generators | YAML |
+| **Workflows** | `.aios-core/workflows/*.yaml` | Multi-agent orchestration | YAML |
+| **Checklists** | `.aios-core/checklists/*.md` | Validation processes | Markdown + Checklist |
+| **Data/KB** | `.aios-core/data/*.md` | Knowledge base, references | Markdown/YAML |
+| **Scripts** | `.aios-core/scripts/*.js` | Utilities, automation | JavaScript |
+| **Tools** | `.aios-core/tools/*/*.yaml` | Tool integrations | YAML |
+
+### Framework vs. Project Files
+
+**Framework Files (.aios-core/):**
+- ✅ Portable across projects
+- ✅ Version controlled in framework repo
+- ✅ Shared by all AIOS projects
+- ✅ Changes require framework approval
+
+**Project Files (root/):**
+- ✅ Project-specific implementation
+- ✅ Version controlled in project repo
+- ✅ Unique to each project
+- ✅ Changes by project team
+
+---
+
+## Naming Conventions
+
+### File Names
+
+**Rule:** `kebab-case` for all files
+
+```bash
+✅ CORRECT:
+- create-next-story.md
+- fullstack-architecture-tmpl.yaml
+- agent-config-loader.js
+
+❌ WRONG:
+- createNextStory.md
+- fullstackArchitectureTmpl.yaml
+- agent_config_loader.js
+```
+
+### Variable Names
+
+**JavaScript/JSON:** `camelCase`
+```javascript
+✅ CORRECT:
+const agentConfig = { ... }
+const taskDefinition = { ... }
+
+❌ WRONG:
+const agent_config = { ... }
+const task-definition = { ... }
+```
+
+**CSS:** `kebab-case`
+```css
+✅ CORRECT:
+.content-area { }
+--spacing-md: 200px;
+
+❌ WRONG:
+.contentArea { }
+--spacing_md: 200px;
+```
+
+**Database:** `snake_case`
+```sql
+✅ CORRECT:
+tasks.responsavel_type
+workflow_executions.started_at
+
+❌ WRONG:
+tasks.responsavelType
+workflow_executions.startedAt
+```
+
+---
+
+# Part III: Agent System
+
+## Agent Architecture
+
+### Agent Definition Structure
+
+Every agent follows this YAML structure:
+
+```yaml
+# Agent Core Identity
+agent:
+  name: {PersonalizedName}        # Human name (Dex, Quinn, Pax)
+  id: {agent-id}                  # System identifier
+  title: {Role}                   # Professional role
+  icon: {emoji}                   # Visual identifier
+  whenToUse: "{description}"      # When to activate this agent
+
+# Personality Profile
+persona_profile:
+  archetype: {Archetype}          # Builder, Guardian, Balancer, etc.
+  zodiac: {Sign}                  # ♒ Aquarius, ♍ Virgo, ♎ Libra, etc.
+
+  communication:
+    tone: {tone}                  # pragmatic | empathetic | analytical
+    emoji_frequency: {level}      # high | medium | low | minimal
+
+    vocabulary:                   # Agent-specific words (5-10)
+      - {word1}
+      - {word2}
+      - {word3}
+
+    greeting_levels:              # 3 personification levels
+      minimal: "{icon} {id} Agent ready"
+      named: "{icon} {name} ({archetype}) ready. {tagline}!"
+      archetypal: "{icon} {name} the {archetype} ready to {verb}!"
+
+    signature_closing: "{personalized_sign_off}"
+
+# Behavioral Configuration
+persona:
+  role: {DetailedRole}
+  style: {CommunicationStyle}
+  identity: {CoreIdentity}
+  focus: {PrimaryFocus}
+  core_principles:
+    - {principle1}
+    - {principle2}
+    - {principle3}
+
+# Commands
+commands:
+  - name: {command-name}
+    description: {description}
+
+# Dependencies
+dependencies:
+  tasks:
+    - {task-file}.md
+  templates:
+    - {template-file}.yaml
+  checklists:
+    - {checklist-file}.md
+  data:
+    - {data-file}.md
+  tools:
+    - {tool-name}
+```
+
+---
+
+## Agent Personalization
+
+### The 11 Archetypes
+
+| Archetype | Name | Icon | Zodiac | Tone | Examples |
+|-----------|------|------|--------|------|----------|
+| **Builder** | Dex | 💻 | ♒ Aquarius | Pragmatic | Dev |
+| **Guardian** | Quinn | 🛡️ | ♍ Virgo | Protective | QA |
+| **Balancer** | Pax, Morgan | 📋 📊 | ♎ Libra | Diplomatic | PO, PM |
+| **Visionary** | Aria | 🏛️ | ♐ Sagittarius | Conceptual | Architect |
+| **Flow Master** | Sage | 🌊 | ♓ Pisces | Adaptive | SM |
+| **Explorer** | Scout | 🔍 | ♊ Gemini | Curious | Analyst |
+| **Engineer** | Dara | 🔧 | ♉ Taurus | Methodical | Data Engineer |
+| **Operator** | Gage | ⚙️ | ♑ Capricorn | Efficient | DevOps |
+| **Empathizer** | Uma | 🎨 | ♋ Cancer | Empathetic | UX Expert |
+| **Orchestrator** | Orion | ⭐ | ♌ Leo | Commanding | AIOS Master |
+| **Architect** | (Various) | 🏗️ | (Various) | Systematic | DB Sage |
+
+### Vocabulary System
+
+Each archetype has specific vocabulary:
+
+**Builder (Dex):**
+- construir, implementar, refatorar, resolver, otimizar
+- debuggar, testar, deployar, commitar, mergear
+
+**Guardian (Quinn):**
+- validar, verificar, proteger, garantir, auditar
+- revisar, inspecionar, certificar, assegurar
+
+**Balancer (Pax, Morgan):**
+- equilibrar, harmonizar, priorizar, alinhar, integrar
+- negociar, mediar, sincronizar, coordenar
+
+### Emoji Palette System
+
+**High Frequency:**
+- ✅ ❌ ⚠️ 🎯 🚀 ⭐ 💡 🔥
+
+**Medium Frequency:**
+- 📊 📋 📝 🔍 💻 🛡️ 🏛️ 🌊
+
+**Low Frequency:**
+- Agent-specific emojis only
+
+**Minimal:**
+- Status indicators only (✅ ❌ ⚠️)
+
+---
+
+## Agent Roles & Specializations
+
+### Development Team
+
+**💻 Dex (Builder) - Developer**
+- **Role:** Full-stack implementation
+- **Commands:** `*develop-story`, `*apply-qa-fixes`, `*improve-code-quality`
+- **When to Use:** Code implementation, debugging, refactoring
+
+**🛡️ Quinn (Guardian) - QA Engineer**
+- **Role:** Quality assurance and testing
+- **Commands:** `*review`, `*code-review`, `*gate`, `*nfr-assess`
+- **When to Use:** Testing, quality validation, acceptance criteria
+
+**🏛️ Aria (Visionary) - Architect**
+- **Role:** System architecture and design
+- **Commands:** `*create-full-stack-architecture`, `*document-project`
+- **When to Use:** Architecture decisions, system design, tech stack
+
+---
+
+### Product & Agile Team
+
+**📋 Pax (Balancer) - Product Owner**
+- **Role:** Story management and backlog
+- **Commands:** `*create-next-story`, `*validate-story-draft`, `*sync-story`
+- **When to Use:** Story creation, backlog prioritization, acceptance
+
+**📊 Morgan (Balancer) - Product Manager**
+- **Role:** Product strategy and roadmap
+- **Commands:** `*create-doc`, `*brownfield-create-epic`
+- **When to Use:** PRDs, product strategy, stakeholder management
+
+**🌊 Sage (Flow Master) - Scrum Master**
+- **Role:** Process facilitation and flow
+- **Commands:** `*execute-checklist`, `*correct-course`
+- **When to Use:** Sprint planning, retrospectives, flow optimization
+
+---
+
+### Specialized Agents
+
+**🔍 Scout (Explorer) - Business Analyst**
+- **Role:** Requirements analysis and research
+- **Commands:** `*facilitate-brainstorming-session`, `*create-deep-research-prompt`
+- **When to Use:** Requirements elicitation, market research, analysis
+
+**🔧 Dara (Engineer) - Data Engineer**
+- **Role:** Data modeling and pipelines
+- **Commands:** `*setup-database`, `*domain-modeling`
+- **When to Use:** Database design, ETL pipelines, data architecture
+
+**⚙️ Gage (Operator) - DevOps Engineer**
+- **Role:** Deployment and operations
+- **Commands:** `*version-management`, `*github-pr-automation`, `*ci-cd-configuration`
+- **When to Use:** CI/CD, deployment, infrastructure, monitoring
+
+**🎨 Uma (Empathizer) - UX Design Expert**
+- **Role:** User experience and design systems
+- **Commands:** `*ux-user-research`, `*ux-create-wireframe`, `*audit-codebase`
+- **When to Use:** UX research, design systems, accessibility
+
+---
+
+### Framework Agents
+
+**⭐ Orion (Orchestrator) - AIOS Master**
+- **Role:** Framework orchestration and agent coordination
+- **Commands:** `*create-agent`, `*create-task`, `*create-workflow`
+- **When to Use:** Framework development, agent creation, workflow design
+
+**🗄️ DB Sage - Database Architect**
+- **Role:** Database schema design and optimization
+- **When to Use:** Complex database design, query optimization
+
+**🐙 GitHub DevOps - Git Operations**
+- **Role:** Git push operations and PR management
+- **When to Use:** Git push, PR creation (not available for local operations)
+
+---
+
+## Greeting System
+
+### Three Greeting Levels
+
+**1. Minimal** (Quick activation)
+```
+💻 dev Agent ready
+```
+
+**2. Named** (Standard, personalized)
+```
+💻 Dex (Builder) pronto. Vamos construir isso!
+```
+
+**3. Archetypal** (Full personality)
+```
+💻 Dex the Builder (♒ Aquarius) ready to implement!
+```
+
+### Contextual Greeting Components
+
+**Complete Greeting Structure:**
+
+```
+{Archetypal Greeting}
+
+📊 **Project Status:**
+  - 🌿 **Branch:** main
+  - 📝 **Modified:** file1.md, file2.js ...and 10 more
+  - 📖 **Recent:** feat: complete story implementation
+  - 📌 **Story:** STORY-6.1.4
+
+💡 **Context:** {Intelligent narrative based on previous work}
+   **Recommended:** Use *{command} to continue
+
+**Quick Commands:**
+   - *help: Show all available commands
+   - *command1: Description
+   - *command2: Description
+
+Type *guide for comprehensive usage instructions.
+
+— {Agent Signature}
+```
+
+### Context Intelligence
+
+The greeting system analyzes:
+- **Previous Agent:** Who was active before
+- **Modified Files:** What files were changed
+- **Current Story:** What story is being worked on
+- **Last Commands:** What commands were recently used
+- **Session Type:** New, existing, or workflow session
+
+**Example Context:**
+```
+💡 **Context:** Vejo que @Dex finalizou a implementação do 
+   **`greeting-builder.js`** no **`story-6.1.4.md`**. 
+   Agora podemos revisar a qualidade dessa implementação
+   
+   **Recommended:** Use `*review story-6.1.4.md` para continuar
+```
+
+---
+
+# Part IV: Task & Workflow System
+
+## Task Format Specification
+
+### Universal Task Structure (AIOS v1.0)
+
+Every task follows this specification:
+
+```yaml
+task: {taskIdentifier()}
+responsável: {AgentName}           # Agent executing (Dex, Quinn, etc.)
+responsavel_type: Agente           # Agente | Worker | Humano | Clone
+atomic_layer: {Layer}              # Optional for open-source
+
+**Entrada:**
+- campo: {fieldName}
+  tipo: {type}                     # string | number | boolean | array | object
+  origem: {source}                 # Step X | User Input | config | agent output
+  obrigatório: {true|false}
+  padrão: {defaultValue}           # Optional
+  validação: {validationRule}      # Optional
+
+**Saída:**
+- campo: {fieldName}
+  tipo: {type}
+  destino: {destination}           # Step Y | state | output | multiple steps
+  persistido: {true|false}         # Saved to file/DB or memory-only
+  cache_key: {key}                 # Optional: if cacheable
+
+**Checklist:**
+  pre-conditions:
+    - [ ] {condition}
+      tipo: pre-condition
+      blocker: {true|false}
+      validação: {validation_logic}
+  
+  post-conditions:
+    - [ ] {condition}
+      tipo: post-condition
+      blocker: {true|false}
+      validação: {validation_logic}
+  
+  acceptance-criteria:
+    - [ ] {criterion}
+      tipo: acceptance
+      blocker: false
+      story: {STORY-XXX}
+
+**Performance:**
+- duration_expected: {X}ms
+- cost_estimated: ${Y}
+- cacheable: {true|false}
+- parallelizable: {true|false}
+
+**Error Handling:**
+- strategy: {retry|fallback|abort}
+- retry:
+    max_attempts: {N}
+    backoff: {linear|exponential}
+```
+
+### Task Components Explained
+
+**Entrada (Input):**
+- Defines all required and optional inputs
+- Specifies data types and validation rules
+- Documents default values
+- Tracks data origin (previous step, user, config)
+
+**Saída (Output):**
+- Defines all outputs produced
+- Specifies destination (next step, state, file)
+- Indicates persistence (temporary or permanent)
+- Enables caching when appropriate
+
+**Checklist:**
+- **Pre-conditions:** Validated BEFORE execution (blocking)
+- **Post-conditions:** Validated AFTER execution (quality gates)
+- **Acceptance Criteria:** Manual verification steps
+
+**Performance:**
+- Expected duration for tracking
+- Cost estimation (for AI executors)
+- Cacheability for optimization
+- Parallelizability for concurrency
+
+**Error Handling:**
+- Strategy: retry, fallback, or abort
+- Retry configuration with backoff
+- Fallback values or alternative flows
+- Notification mechanisms
+
+---
+
+## Execution Modes
+
+### The Three Execution Modes
+
+Every task supports three execution modes to balance automation, education, and control:
+
+#### 1. YOLO Mode - Fast, Autonomous (0-1 prompts)
+
+**Characteristics:**
+- ✅ Autonomous decision making
+- ✅ All decisions logged to `.ai/decision-log-{task-id}.md`
+- ✅ Minimal user interaction
+- ✅ Fast execution
+
+**Best For:**
+- Experienced developers
+- Simple, well-defined tasks
+- Time-sensitive work
+- Repetitive operations
+
+**Example:**
+```yaml
+mode: yolo
+```
+
+**Decision Logging:**
+```markdown
+## Decision: Use TypeScript for API layer
+**Context:** Need to define type-safe API contracts
+**Options:** [TypeScript, JavaScript with JSDoc]
+**Selected:** TypeScript
+**Rationale:** Better IDE support and compile-time checks
+**Timestamp:** 2025-01-18T14:30:00Z
+```
+
+---
+
+#### 2. Interactive Mode - Balanced, Educational (5-10 prompts) **[DEFAULT]**
+
+**Characteristics:**
+- ✅ Explicit decision checkpoints
+- ✅ Educational explanations
+- ✅ Collaborative decision making
+- ✅ Context preservation
+
+**Best For:**
+- Learning new patterns
+- Complex decisions
+- Collaborative work
+- Code reviews
+
+**Example:**
+```yaml
+mode: interactive
+```
+
+**Checkpoint Example:**
+```markdown
+🤔 **Decision Point:** Database Technology Selection
+
+**Options:**
+1. PostgreSQL (Relational, ACID, complex queries)
+2. MongoDB (Document, flexible schema, horizontal scaling)
+3. Supabase (PostgreSQL + Auth + Storage + Realtime)
+
+**Recommendation:** Supabase (Option 3)
+**Rationale:** Provides PostgreSQL + auth + storage out-of-box
+
+**Your choice?** (1-3 or 'explain')
+```
+
+---
+
+#### 3. Pre-Flight Planning - Comprehensive Upfront (1 questionnaire)
+
+**Characteristics:**
+- ✅ Task analysis phase (identify ambiguities)
+- ✅ Comprehensive questionnaire
+- ✅ Zero ambiguity execution
+- ✅ Plan approval before work
+
+**Best For:**
+- Ambiguous requirements
+- Critical work (production, security)
+- Team consensus needed
+- Large-scale changes
+
+**Example:**
+```yaml
+mode: preflight
+```
+
+**Pre-Flight Questionnaire:**
+```markdown
+📋 **Pre-Flight Planning: Implement User Authentication**
+
+**Identified Ambiguities:**
+1. Authentication Method: Social login or email/password?
+2. Session Management: JWT or session cookies?
+3. Password Requirements: Complexity rules?
+4. MFA Support: Required or optional?
+5. User Roles: RBAC or simple user types?
+
+**Please Answer:**
+[... comprehensive questionnaire ...]
+
+**Execution Plan:**
+[... generated after questionnaire ...]
+
+**Approve plan?** (yes/no/modify)
+```
+
+---
+
+### Mode Selection Guidelines
+
+| Scenario | YOLO | Interactive | Pre-Flight |
+|----------|------|-------------|------------|
+| **Simple CRUD** | ✅ Perfect | ⚠️ Overkill | ❌ Too much |
+| **Learning new tech** | ❌ Miss details | ✅ Perfect | ⚠️ Good |
+| **Security feature** | ❌ Risky | ⚠️ Good | ✅ Perfect |
+| **Time pressure** | ✅ Perfect | ⚠️ Slower | ❌ Slow |
+| **Team project** | ❌ Solo | ⚠️ Good | ✅ Perfect |
+| **Experimental** | ✅ Perfect | ✅ Good | ❌ Overhead |
+
+---
+
+## Workflow Orchestration
+
+### Workflow Types
+
+AIOS supports multiple workflow patterns:
+
+1. **Sequential** - Tasks execute one after another
+2. **Fork/Join** - Parallel execution with synchronization
+3. **Organizer-Worker** - Dynamic work distribution
+4. **Conditional** - Branch based on conditions
+5. **Loop** - Repeat until condition met
+
+### Workflow Definition Format
+
+```yaml
+workflow:
+  id: {workflow-id}
+  name: {WorkflowName}
+  version: {X.Y.Z}
+  type: {sequential|fork-join|organizer-worker|conditional|loop}
+  
+  steps:
+    - id: step-1
+      task: {task-name}
+      agent: {agent-id}
+      dependencies: []
+      condition: {optional}
+      
+    - id: step-2
+      task: {task-name}
+      agent: {agent-id}
+      dependencies: [step-1]
+      
+    - id: step-3
+      type: fork
+      branches:
+        - id: branch-a
+          steps: [...]
+        - id: branch-b
+          steps: [...]
+      join: step-4
+      
+    - id: step-4
+      type: join
+      merge_strategy: {combine|first|last|custom}
+```
+
+### Built-in Workflows
+
+**Greenfield Workflows:**
+- `greenfield-fullstack.yaml` - Complete full-stack project
+- `greenfield-service.yaml` - Backend service only
+- `greenfield-ui.yaml` - Frontend UI only
+
+**Brownfield Workflows:**
+- `brownfield-fullstack.yaml` - Add features to existing full-stack
+- `brownfield-service.yaml` - Extend existing backend
+- `brownfield-ui.yaml` - Enhance existing frontend
+
+---
+
+## Fork/Join & Organizer-Worker Patterns
+
+### Fork/Join Pattern (Story 6.1.12)
+
+**Purpose:** Execute tasks in parallel and synchronize results
+
+**Use Cases:**
+- Parallel test execution
+- Multi-agent analysis
+- Concurrent API calls
+- Independent component building
+
+**Example:**
+
+```yaml
+- id: analyze-architecture
+  type: fork
+  branches:
+    - id: frontend-analysis
+      agent: architect
+      task: analyze-frontend-architecture
+      
+    - id: backend-analysis
+      agent: architect
+      task: analyze-backend-architecture
+      
+    - id: database-analysis
+      agent: db-sage
+      task: analyze-database-schema
+      
+  join: merge-analysis
+  merge_strategy: combine_reports
+
+- id: merge-analysis
+  type: join
+  task: consolidate-architecture-report
+  agent: architect
+```
+
+**Merge Strategies:**
+- `combine` - Combine all results
+- `first` - Use first completed result
+- `last` - Use last completed result
+- `custom` - Custom merge function
+
+---
+
+### Organizer-Worker Pattern (Story 6.1.13)
+
+**Purpose:** Intelligent work distribution across agents
+
+**Use Cases:**
+- Dynamic task distribution
+- Load balancing
+- Skill-based assignment
+- Scalable multi-agent coordination
+
+**Pattern Structure:**
+
+```
+┌─────────────────────────────────────┐
+│   Organizer Agent                   │
+│   (aios-master)                     │
+│   - Receives work                   │
+│   - Distributes to workers          │
+│   - Collects results                │
+│   - Merges outputs                  │
+└─────────────────────────────────────┘
+         ↓          ↓          ↓
+┌──────────┐  ┌──────────┐  ┌──────────┐
+│ Worker 1 │  │ Worker 2 │  │ Worker 3 │
+│ (dev)    │  │ (dev)    │  │ (qa)     │
+└──────────┘  └──────────┘  └──────────┘
+```
+
+**Agent Role Extension:**
+
+```yaml
+# Organizer Agent
+agent:
+  id: aios-master
+  role: organizer              # NEW: organizer role
+  can_distribute_work: true
+
+# Worker Agents
+agent:
+  id: dev
+  role: worker                 # NEW: worker role (default)
+  skills: [coding, testing]
+```
+
+**Distribution Strategies:**
+
+1. **Round Robin** - Distribute evenly
+```yaml
+distribution_strategy: round_robin
+```
+
+2. **Load Balanced** - Consider current workload
+```yaml
+distribution_strategy: load_balanced
+max_concurrent_tasks: 3
+```
+
+3. **Skill Based** - Match skills to requirements
+```yaml
+distribution_strategy: skill_based
+required_skills: [coding, frontend]
+```
+
+**Example Workflow:**
+
+```yaml
+- id: implement-features
+  type: organizer-worker
+  organizer: aios-master
+  workers: [dev-1, dev-2, dev-3]
+  distribution_strategy: skill_based
+  
+  work_items:
+    - feature: user-authentication
+      required_skills: [backend, security]
+    - feature: dashboard-ui
+      required_skills: [frontend, react]
+    - feature: data-pipeline
+      required_skills: [data, etl]
+  
+  merge_strategy: combine
+  failure_strategy: reassign
+```
+
+---
+
+# Part V: Executor Types
+
+## The Four Executor Types
+
+### 1. Agente (AI-Powered Execution)
+
+**Definition:** AI agent using Large Language Models for creative/analytical tasks
+
+**When to Use:**
+- ✅ Requires creativity or subjective judgment
+- ✅ Natural language understanding/generation
+- ✅ Contextual analysis
+- ✅ No deterministic algorithm
+
+**Examples:**
+- Analyze requirements and extract insights
+- Generate code from specifications
+- Design system architecture
+- Review code for quality
+- Create documentation
+
+**Characteristics:**
+- **Cost:** $$$$ High ($0.001 - $0.01 per execution)
+- **Speed:** Slow (3-10 seconds)
+- **Deterministic:** ❌ No (stochastic outputs)
+
+---
+
+### 2. Worker (Script-Based Execution)
+
+**Definition:** Deterministic script/function with predefined logic
+
+**When to Use:**
+- ✅ Deterministic (same input → same output)
+- ✅ Data transformation or validation
+- ✅ File/database operations
+- ✅ External API calls (no AI)
+
+**Examples:**
+- Load configuration from JSON
+- Validate HTML structure
+- Export PNG from HTML
+- Calculate metrics
+- Run migrations
+
+**Characteristics:**
+- **Cost:** $ Low ($0 - $0.001 per execution)
+- **Speed:** Fast (< 1 second)
+- **Deterministic:** ✅ Yes (repeatable)
+
+---
+
+### 3. Humano (Manual Human Execution)
+
+**Definition:** Human operator for subjective judgment or approval
+
+**When to Use:**
+- ✅ Requires human subjective judgment
+- ✅ Quality gate or approval step
+- ✅ Sensitive decisions
+- ✅ Cannot be automated (yet)
+
+**Examples:**
+- Review and approve/reject work
+- Make strategic decisions
+- Handle edge cases
+- Provide creative direction
+- Security review
+
+**Characteristics:**
+- **Cost:** $$$ Medium ($5 - $50 per execution)
+- **Speed:** Very Slow (minutes to hours)
+- **Deterministic:** ❌ No (subjective)
+
+---
+
+### 4. Clone (Mind Emulation with Heuristics)
+
+**Definition:** AI agent with personality heuristics and domain axioms
+
+**When to Use:**
+- ✅ Requires specific domain expertise
+- ✅ Must follow specific methodology
+- ✅ Needs validation against established principles
+- ✅ Benefits from "personality-driven" execution
+
+**Examples:**
+- Validate components (Atomic Design - Brad Frost)
+- Review copy (Alex Hormozi methodology)
+- Evaluate design consistency
+- Apply mental models
+
+**Characteristics:**
+- **Cost:** $$$$ High ($0.002 - $0.015 per execution)
+- **Speed:** Slow (5-15 seconds)
+- **Deterministic:** ⚠️ Partial (heuristics guide AI)
+
+---
+
+## Executor Decision Tree
+
+### Decision Flow
+
+```
+Task to Execute
+    ↓
+Requires Creativity/Subjectivity?
+    ├─ NO → Deterministic Algorithm Exists?
+    │           ├─ YES → Worker (script)
+    │           └─ NO → Requires Human Judgment?
+    │                       ├─ YES → Critical Decision?
+    │                       │           ├─ YES → Humano
+    │                       │           └─ NO → Specific Methodology?
+    │                       │                       ├─ YES → Clone
+    │                       │                       └─ NO → Agente
+    │                       └─ NO → Agente
+    └─ YES → Requires Human Judgment?
+                ├─ YES → Critical Decision?
+                │           ├─ YES → Humano
+                │           └─ NO → Specific Methodology?
+                │                       ├─ YES → Clone
+                │                       └─ NO → Agente
+                └─ NO → Specific Methodology?
+                            ├─ YES → Clone
+                            └─ NO → Agente
+```
+
+### Decision Criteria
+
+| Criterion | Worker | Agente | Humano | Clone |
+|-----------|--------|--------|--------|-------|
+| **Creativity Required** | ❌ | ✅ | ✅ | ✅ |
+| **Deterministic** | ✅ | ❌ | ❌ | ⚠️ |
+| **Cost** | $ | $$$$ | $$$ | $$$$ |
+| **Speed** | Fast | Slow | Very Slow | Slow |
+| **Human Judgment** | ❌ | ❌ | ✅ | ❌ |
+| **Methodology** | ❌ | ❌ | ⚠️ | ✅ |
+
+---
+
+# Part VI: Standards & Best Practices
+
+## Coding Standards
+
+### JavaScript/TypeScript Standards
+
+**Naming Conventions:**
+- `camelCase` for variables, functions, methods
+- `PascalCase` for classes, components, interfaces
+- `UPPER_CASE` for constants
+- `kebab-case` for file names
+
+**Code Structure:**
+```javascript
+// ✅ GOOD
+const userProfile = {
+  firstName: 'John',
+  lastName: 'Doe',
+  isActive: true
+};
+
+// ❌ BAD
+const user_profile = {
+  first_name: 'John',
+  last_name: 'Doe',
+  is_active: true
+};
+```
+
+**Function Design:**
+- Keep functions small (<50 lines)
+- Single responsibility
+- Pure functions when possible
+- Document with JSDoc
+
+**Error Handling:**
+```javascript
+// ✅ GOOD
+try {
+  const result = await operation();
+  return { success: true, data: result };
+} catch (error) {
+  logger.error('Operation failed:', error);
+  return { success: false, error: error.message };
+}
+
+// ❌ BAD
+const result = await operation(); // No error handling
+```
+
+---
+
+### CSS Standards
+
+**Naming Convention:** `kebab-case`
+
+```css
+/* ✅ GOOD */
+.content-area {
+  padding: var(--spacing-md);
+}
+
+--spacing-md: 200px;
+--color-primary: #007bff;
+
+/* ❌ BAD */
+.contentArea {
+  padding: var(--spacing_md);
+}
+```
+
+**CSS Organization:**
+1. Layout properties
+2. Box model properties
+3. Visual properties
+4. Typography
+5. Misc
+
+---
+
+### Database Standards
+
+**Naming Convention:** `snake_case`
+
+```sql
+-- ✅ GOOD
+CREATE TABLE workflow_executions (
+  execution_id UUID PRIMARY KEY,
+  workflow_id UUID NOT NULL,
+  started_at TIMESTAMP,
+  completed_at TIMESTAMP,
+  status VARCHAR(20)
+);
+
+-- ❌ BAD
+CREATE TABLE workflowExecutions (
+  executionId UUID PRIMARY KEY,
+  workflowId UUID NOT NULL,
+  startedAt TIMESTAMP
+);
+```
+
+---
+
+## Technology Stack
+
+### Frontend Stack
+
+**Core:**
+- **Framework:** Next.js 14 (App Router)
+- **UI Library:** React 18
+- **Language:** TypeScript 5
+- **Styling:** Tailwind CSS 3
+
+**State Management:**
+- **Global:** Zustand or React Context
+- **Server:** React Server Components
+- **Forms:** React Hook Form + Zod
+
+**UI Components:**
+- **Library:** shadcn/ui (Radix UI)
+- **Icons:** Lucide React
+- **Animations:** Framer Motion
+
+---
+
+### Backend Stack
+
+**Core:**
+- **Framework:** NestJS
+- **Language:** TypeScript 5
+- **Runtime:** Node.js 18+ (LTS)
+
+**Database:**
+- **Primary:** Supabase (PostgreSQL)
+- **ORM:** Prisma or TypeORM
+- **Migrations:** Prisma Migrate
+
+**Authentication:**
+- **Provider:** Supabase Auth
+- **Strategy:** JWT + Row Level Security (RLS)
+
+**API:**
+- **Type:** REST + tRPC (type-safe)
+- **Validation:** Zod
+- **Documentation:** OpenAPI/Swagger
+
+---
+
+### DevOps & Infrastructure
+
+**Version Control:**
+- **Platform:** GitHub
+- **Workflow:** Feature branches + PRs
+- **CI/CD:** GitHub Actions
+
+**Deployment:**
+- **Platform:** Railway (recommended) or Vercel
+- **Strategy:** Zero-downtime deployment
+- **Environments:** dev, staging, production
+
+**Monitoring:**
+- **Logs:** Structured logging (Winston/Pino)
+- **Metrics:** Custom dashboards
+- **Errors:** Error tracking service
+
+---
+
+## Quality Gates & CodeRabbit Integration
+
+### CodeRabbit Quality Gates
+
+AIOS uses **CodeRabbit** for automated code review at three key checkpoints:
+
+#### 1. Pre-Commit Gate (@dev)
+
+**When:** Before committing code  
+**Command:** `*code-review uncommitted`
+
+**Focus:**
+- Syntax errors
+- Basic code quality
+- Linting violations
+- Obvious bugs
+
+**Action:** Fix CRITICAL issues before committing
+
+---
+
+#### 2. Mid-Point Review (@dev + @qa)
+
+**When:** During story implementation  
+**Command:** `*code-review --base main`
+
+**Focus:**
+- Architecture patterns
+- Error handling
+- Performance issues
+- Integration points
+
+**Action:** Address HIGH and CRITICAL issues
+
+---
+
+#### 3. Pre-PR Gate (@dev + @qa)
+
+**When:** Before creating PR  
+**Command:** `*code-review --base main --full`
+
+**Focus:**
+- Complete code quality
+- Test coverage
+- Documentation
+- Backward compatibility
+- Security vulnerabilities
+
+**Action:** Resolve ALL CRITICAL, address HIGH issues
+
+---
+
+### Severity Levels
+
+| Severity | Action | Examples |
+|----------|--------|----------|
+| **CRITICAL** | ❌ Block | Security vulnerabilities, data loss risks |
+| **HIGH** | ⚠️ Fix before PR | Performance issues, error handling gaps |
+| **MEDIUM** | 📋 Document as debt | Code maintainability, design patterns |
+| **LOW** | ℹ️ Optional | Style inconsistencies, minor optimizations |
+
+---
+
+### Story-Specific Integration
+
+Each story includes CodeRabbit integration:
+
+```yaml
+# CodeRabbit Integration
+story_type: [Feature|Bug|Refactor|Architecture]
+specialized_agents: [@dev, @qa, @architect]
+
+quality_gates:
+  pre_commit: Focus on syntax and basic quality
+  mid_point: Focus on architecture and integration
+  pre_pr: Comprehensive review before merge
+
+focus_areas:
+  - Error Handling: Check all error paths
+  - Performance: Validate response times
+  - Security: Check for vulnerabilities
+  - Integration: Validate API contracts
+```
+
+---
+
+# Part VII: Migration & Roadmap
+
+## Current Migration Status
+
+### Epic 6.1: Agent Identity System (In Progress)
+
+**Objective:** Modernize agent system with personality, unified greeting, and improved structure
+
+**Waves:**
+
+**Wave 1 - Foundation (In Progress):**
+- ✅ Story 6.1.1: Agent Personalization Implementation
+- ✅ Story 6.1.2: Persona Profile Integration
+- ✅ Story 6.1.3: Greeting Levels Implementation
+- ✅ Story 6.1.4: Unified Greeting System Integration
+- ⏸️ Story 6.1.4.1: Fix Remaining Agent YAML Issues (Approved)
+- ✅ Story 6.1.5: Output Formatter Implementation
+- ✅ Story 6.1.6: Output Formatter Testing
+- ✅ Story 6.1.7: Core Tasks Migration
+- ✅ Story 6.1.8: Templates Migration
+- ✅ Story 6.1.9: Checklists Migration
+- 📋 Story 6.1.10: Dependencies & Data Files Migration (Ready)
+- 📋 Story 6.1.11: AIOS-Master Tasks Creation (Ready)
+- 📋 Story 6.1.12: Fork/Join Workflow Operations (Ready)
+- 📋 Story 6.1.13: Organizer-Worker Pattern (Ready)
+
+**Wave 2 - Enhancement (Pending):**
+- ❌ Story 6.1.14: Expansion Pack Framework (REJECTED - Architecture conflict)
+- ❌ Story 6.1.14.1-3: Expansion Pack Extraction (REJECTED - Architecture conflict)
+- 📋 Story 6.1.15: Subdirectory Architecture Validation (PROPOSED)
+- 📋 Story 6.1.16-21: Subdirectory Migration (PROPOSED - if 6.1.15 succeeds)
+
+---
+
+## Future Architecture (Q2 2026)
+
+### Repository Restructuring (Decision 005)
+
+**Current State:**
+```
+@synkra/aios-core/
+├── .aios-core/              # Framework embedded in project
+├── frontend/
+├── backend/
+└── docs/
+```
+
+**Future State (Q2 2026):**
+```
+aios/
+├── aios-core/               # Framework repository (standalone)
+│   ├── agents/
+│   ├── tasks/
+│   ├── templates/
+│   └── ...
+│
+└── @synkra/aios-core/          # Project repository
+    ├── frontend/
+    ├── backend/
+    └── .aios/               # Framework reference (git submodule)
+```
+
+**Benefits:**
+- ✅ Framework versioning independent of project
+- ✅ Easier framework updates
+- ✅ Cleaner project structure
+- ✅ Multiple projects share same framework
+
+**Migration Timeline:**
+- **Q1 2026:** Prepare for separation
+- **Q2 2026:** Execute repository split
+- **Q3 2026:** Complete migration
+
+---
+
+## Subdirectory Migration Plan
+
+### The Challenge (Story 6.1.15+)
+
+**Current Structure:** Flat files in `.aios-core/{type}/`
+```
+.aios-core/
+├── tasks/
+│   ├── create-doc.md
+│   ├── develop-story.md
+│   ├── generate-tests.md
+│   └── ... (60+ files)
+```
+
+**Proposed Structure:** Organized subdirectories
+```
+.aios-core/
+├── tasks/
+│   ├── documentation/
+│   │   ├── create-doc.md
+│   │   └── document-project.md
+│   ├── development/
+│   │   ├── develop-story.md
+│   │   └── apply-qa-fixes.md
+│   └── testing/
+│       ├── generate-tests.md
+│       └── nfr-assess.md
+```
+
+---
+
+### Migration Phases
+
+**Phase 0: Validation (Story 6.1.15)**
+- Duration: 2-3 days
+- Investment: $100-150
+- Goal: Test subdirectory architecture works
+- Deliverable: GO/NO-GO decision
+
+**Phase 1: Core Infrastructure (Story 6.1.16)**
+- Duration: 1.5 days
+- Investment: $75
+- Goal: Update file resolution logic
+- Deliverable: Scripts support subdirectories
+
+**Phase 2: File Migration (Stories 6.1.17-19)**
+- Duration: 10-15 days
+- Investment: $500-750
+- Goal: Move files to subdirectories
+- Deliverable: Organized framework structure
+
+**Phase 3: Reference Updates (Story 6.1.20)**
+- Duration: 1 day
+- Investment: $50
+- Goal: Update all agent references
+- Deliverable: All references correct
+
+**Phase 4: Cleanup (Story 6.1.21)**
+- Duration: 0.5 day
+- Investment: $25
+- Goal: Remove backward compatibility
+- Deliverable: Optimized system
+
+**Total Effort:** 15-21 days, $750-1,050
+
+---
+
+### Proposed Subdirectory Organization
+
+**data/ subdirectories:**
+```
+data/
+├── agile/                   # Agile/Scrum knowledge
+├── architecture/            # Architecture patterns
+├── design-systems/          # UX/Design frameworks
+├── database/                # Database knowledge
+├── infrastructure/          # DevOps/Infrastructure
+├── quality/                 # Testing/QA knowledge
+└── technical/               # Technical standards
+```
+
+**tasks/ subdirectories:**
+```
+tasks/
+├── agile/                   # Story management
+├── architecture/            # Architecture tasks
+├── database/                # Database tasks
+├── data-engineering/        # Data engineering
+├── development/             # Development tasks
+├── devops/                  # DevOps tasks
+├── documentation/           # Documentation tasks
+├── quality/                 # QA tasks
+├── research/                # Research/Analysis
+├── ux-design/               # UX/Design tasks
+└── framework/               # Framework management
+```
+
+**templates/ subdirectories:**
+```
+templates/
+├── agile/                   # Story, epic templates
+├── architecture/            # Architecture templates
+├── database/                # Database templates
+├── infrastructure/          # Infrastructure templates
+├── product/                 # PRD, brief templates
+└── ux-design/               # Design templates
+```
+
+---
+
+### Risk Mitigation
+
+**Risks:**
+1. ❌ Breaking agent loading
+2. ❌ Performance degradation
+3. ❌ Incomplete migration
+4. ❌ Script path resolution failures
+
+**Mitigations:**
+1. ✅ Test in isolated environment first (Phase 0)
+2. ✅ Benchmark performance during validation
+3. ✅ Automated migration scripts + validation
+4. ✅ Comprehensive script audit (Phase 1)
+5. ✅ Backward compatibility during migration
+6. ✅ Git-based rollback strategy
+
+---
+
+# Part VIII: Appendices
+
+## Glossary
+
+### Core Concepts
+
+**AIOS:** AI Operating System - Framework for orchestrating AI agents and workflows
+
+**Agent:** AI-powered executor with personality, specialized role, and commands
+
+**Task:** Executable workflow with inputs, outputs, validation, and error handling
+
+**Workflow:** Multi-step orchestration coordinating multiple agents/tasks
+
+**Executor:** Entity that executes tasks (Agente, Worker, Humano, Clone)
+
+**Archetype:** Personality template (Builder, Guardian, Balancer, etc.)
+
+**Persona Profile:** Agent personality configuration (communication, vocabulary, greetings)
+
+**Greeting System:** Contextual agent activation with status, context, and commands
+
+**Quality Gate:** Validation checkpoint using CodeRabbit or manual review
+
+**Fork/Join:** Parallel execution pattern with synchronization
+
+**Organizer-Worker:** Dynamic work distribution pattern
+
+**Execution Mode:** YOLO (autonomous), Interactive (balanced), Pre-Flight (comprehensive)
+
+---
+
+### File Types
+
+**Agent Definition (.md):** Agent personality, role, commands, dependencies
+
+**Task Definition (.md):** Executable workflow with YAML specification
+
+**Template (.yaml/.md):** Document generator with variables and structure
+
+**Workflow (.yaml):** Multi-agent orchestration definition
+
+**Checklist (.md):** Validation process with checkboxes
+
+**Data/KB (.md/.yaml):** Knowledge base, reference material
+
+**Script (.js):** Utility, automation, or tool
+
+**Config (.yaml):** Configuration file
+
+---
+
+### Patterns
+
+**MCP (Model Context Protocol):** Integration protocol for external tools
+
+**RLS (Row Level Security):** Database security at row level
+
+**RBAC (Role-Based Access Control):** Permission system
+
+**JWT (JSON Web Token):** Authentication token standard
+
+**ETL (Extract, Transform, Load):** Data pipeline pattern
+
+**CRUD (Create, Read, Update, Delete):** Basic operations
+
+**CI/CD (Continuous Integration/Deployment):** Automation pipeline
+
+**PRD (Product Requirements Document):** Product specification
+
+**NFR (Non-Functional Requirements):** Quality attributes
+
+---
+
+## Decision History
+
+### Major Architectural Decisions
+
+**Decision 001:** Agent Personalization Standard (2025-01-14)
+- **Status:** Implemented
+- **Decision:** Three-layer personality system (persona → formatter → output)
+- **Rationale:** Familiaridade + Personalização = Produtividade
+
+**Decision 002:** Unified Greeting System (2025-01-16)
+- **Status:** Implemented
+- **Decision:** Single greeting generator for all agents
+- **Rationale:** Consistency, performance, maintainability
+
+**Decision 003:** Task Format v2.0 (2025-11-13)
+- **Status:** Implemented
+- **Decision:** Universal task specification with execution modes
+- **Rationale:** Scalability, reusability, clarity
+
+**Decision 004:** Open Source vs Service (2025-01-14)
+- **Status:** Defined
+- **Decision:** Open-source = Agente-only, Service = All executors
+- **Rationale:** Community vs commercial differentiation
+
+**Decision 005:** Repository Restructuring (2025-01-15)
+- **Status:** Planned (Q2 2026)
+- **Decision:** Split framework and project repositories
+- **Rationale:** Independent versioning, cleaner structure
+
+**Decision 006:** Subdirectory Migration (2025-01-18)
+- **Status:** Approved (Pending validation)
+- **Decision:** Organize framework files in domain subdirectories
+- **Rationale:** Scalability, better organization, expansion packs support
+
+**Decision 007:** Expansion Pack Architecture (2025-01-18)
+- **Status:** REJECTED (Conflict with AIOS principles)
+- **Decision:** NO new directory types (methodologies/, patterns/)
+- **Rationale:** Violates 7-type framework structure
+- **Alternative:** Use subdirectories in existing types (data/, tasks/, templates/)
+
+---
+
+## References
+
+### Internal Documentation
+
+- **Framework Structure:** `docs/architecture/source-tree.md`
+- **Coding Standards:** `docs/framework/coding-standards.md`
+- **Technology Stack:** `docs/framework/tech-stack.md`
+- **Agent Standard:** `.aios-core/docs/standards/AGENT-PERSONALIZATION-STANDARD-V1.md`
+- **Task Format:** `.aios-core/docs/standards/TASK-FORMAT-SPECIFICATION-V1.md`
+- **Executor Tree:** `.aios-core/docs/standards/EXECUTOR-DECISION-TREE.md`
+- **Architectural Decisions:** `.aios-core/docs/standards/V3-ARCHITECTURAL-DECISIONS.md`
+- **Repository Restructuring:** `docs/decisions/decision-005-repository-restructuring-FINAL.md`
+
+### Implementation Stories
+
+- **Story 6.1.4:** Unified Greeting System Integration
+- **Story 6.1.10:** Dependencies & Data Files Migration
+- **Story 6.1.11:** AIOS-Master Tasks Creation
+- **Story 6.1.12:** Fork/Join Workflow Operations
+- **Story 6.1.13:** Organizer-Worker Pattern Implementation
+
+### External Resources
+
+- **Atomic Design:** Brad Frost's methodology
+- **Twelve-Factor App:** Methodology for SaaS applications
+- **MCP Protocol:** Model Context Protocol specification
+- **Supabase Docs:** https://supabase.com/docs
+- **Next.js Docs:** https://nextjs.org/docs
+- **NestJS Docs:** https://docs.nestjs.com
+
+---
+
+## Contributing
+
+### How to Contribute
+
+1. **Read this document** - Understand AIOS principles
+2. **Choose an area** - Framework, agents, tasks, workflows
+3. **Follow standards** - Coding standards, naming conventions
+4. **Test thoroughly** - Unit tests, integration tests
+5. **Document changes** - Update relevant docs
+6. **Submit PR** - Follow PR template
+
+### PR Template
+
+```markdown
+## Story Reference
+[Story 6.1.X] {Story Title}
+
+## Changes
+- [ ] Agent definitions updated
+- [ ] Task files created/modified
+- [ ] Templates added/changed
+- [ ] Tests added
+- [ ] Documentation updated
+
+## Testing
+- [ ] Unit tests pass
+- [ ] Integration tests pass
+- [ ] Manual testing complete
+
+## CodeRabbit Review
+- [ ] Pre-commit review passed
+- [ ] All CRITICAL issues resolved
+- [ ] HIGH issues addressed or documented
+
+## Checklist
+- [ ] Follows coding standards
+- [ ] Naming conventions correct
+- [ ] No breaking changes (or documented)
+- [ ] Backward compatible
+```
+
+---
+
+## Support & Contact
+
+### Getting Help
+
+1. **Documentation First:** Check this master document
+2. **Framework Docs:** Review specific docs in `docs/framework/`
+3. **Decision History:** Check `docs/decisions/`
+4. **Story Context:** Review implementation stories
+
+### Framework Team
+
+- **Architect:** Aria (@architect)
+- **Lead Developer:** Dex (@dev)
+- **Quality Lead:** Quinn (@qa)
+- **Product Owner:** Pax (@po)
+
+---
+
+**Document Version:** 2.0.0  
+**Last Updated:** 2025-01-18  
+**Maintained By:** AIOS Framework Team  
+**Status:** Living Document
+
+---
+
+*This document consolidates all AIOS framework documentation into a single, comprehensive reference. It is a living document and will be updated as the framework evolves.*
+
+— Aria, arquitetando o futuro 🏗️
+