sinapse-ai 1.21.0 → 1.23.0

package/.claude/hooks/doc-first-gate.cjs

@@ -30,17 +30,30 @@
 const fs = require('fs');
 const path = require('path');
 
-/** Paths that require doc-first before code changes (mirror enforce-story-gate). */
+/** Code directories (fast path) — mirror enforce-story-gate. Expanded beyond the
+ *  original 8 to cover common back-end/full-stack layouts; combined with CODE_EXT
+ *  below so code in ANY non-exempt, non-config location is gated. */
 const CODE_PATHS = [
-  'packages/', 'src/', 'app/', 'lib/', 'bin/',
+  'packages/', 'src/', 'app/', 'apps/', 'lib/', 'bin/',
   'components/', 'pages/', 'api/', 'services/',
+  'server/', 'client/', 'backend/', 'frontend/', 'functions/',
+  'worker/', 'workers/', 'routes/', 'controllers/', 'models/',
+  'handlers/', 'middleware/', 'hooks/', 'stores/', 'store/',
+  'features/', 'modules/', 'domain/', 'views/', 'screens/',
+  'contexts/', 'providers/', 'utils/', 'helpers/', 'cmd/',
+  'internal/', 'pkg/',
 ];
 
+/** Code file extensions — catches code in ANY non-exempt, non-config location. */
+const CODE_EXT = /\.(m?[jt]sx?|cjs|vue|svelte|astro|py|go|rs|java|rb|php|swift|kt|kts|c|cc|cpp|h|hpp|cs|scala|ex|exs|clj|dart)$/i;
+
 /** Paths always exempt. */
 const EXEMPT_PATHS = [
   '.claude/', '.sinapse-ai/', '.sinapse/', '.sinapse-custom/',
   'docs/', 'tests/', '__tests__/', 'test/',
   'node_modules/', '.git/', 'squads/', 'outputs/',
+  // Build outputs / generated — never gated.
+  '.next/', 'dist/', 'build/', 'out/', 'coverage/', '.vercel/', '.turbo/', '.cache/',
 ];
 
 /** Config files always exempt (scaffolding a project is allowed pre-docs). */
@@ -73,8 +86,24 @@ function isExempt(rel) {
   return EXEMPT_PATHS.some((ep) => rel.startsWith(ep));
 }
 
+/**
+ * Config-like files exempt by PATTERN in ANY folder (so extension-based detection
+ * never over-blocks tooling config): `*.config.{js,ts,mjs,cjs}`, `*.d.ts`, and
+ * dotfile rc configs (`.eslintrc.json`, `.prettierrc.cjs`).
+ */
+function isConfigLike(rel) {
+  const base = path.basename(rel);
+  return (
+    /\.config\.[cm]?[jt]s$/i.test(base) ||
+    /\.d\.ts$/i.test(base) ||
+    /^\.[a-z0-9_-]+rc(\.[a-z]+)?$/i.test(base)
+  );
+}
+
 function isCodePath(rel) {
-  return CODE_PATHS.some((cp) => rel.startsWith(cp));
+  if (isConfigLike(rel)) return false;
+  if (CODE_PATHS.some((cp) => rel.startsWith(cp))) return true;
+  return CODE_EXT.test(rel);
 }
 
 function main() {

package/.claude/hooks/enforce-story-gate.cjs

@@ -24,17 +24,33 @@ const path = require('path');
 // Configuration
 // ---------------------------------------------------------------------------
 
-/** Paths that require an active story before code changes. */
+/**
+ * Code directories (fast path). Expanded beyond the original 8 to cover common
+ * back-end / full-stack layouts. NOTE: this is no longer the ONLY signal — any
+ * code file (by extension) in a non-exempt, non-config location is also gated
+ * (see isCodePath), so this list is a fast-path, not a hole-prone allowlist.
+ */
 const CODE_PATHS = [
-  'packages/', 'src/', 'app/', 'lib/', 'bin/',
+  'packages/', 'src/', 'app/', 'apps/', 'lib/', 'bin/',
   'components/', 'pages/', 'api/', 'services/',
+  'server/', 'client/', 'backend/', 'frontend/', 'functions/',
+  'worker/', 'workers/', 'routes/', 'controllers/', 'models/',
+  'handlers/', 'middleware/', 'hooks/', 'stores/', 'store/',
+  'features/', 'modules/', 'domain/', 'views/', 'screens/',
+  'contexts/', 'providers/', 'utils/', 'helpers/', 'cmd/',
+  'internal/', 'pkg/',
 ];
 
+/** Code file extensions — catches code in ANY non-exempt, non-config location. */
+const CODE_EXT = /\.(m?[jt]sx?|cjs|vue|svelte|astro|py|go|rs|java|rb|php|swift|kt|kts|c|cc|cpp|h|hpp|cs|scala|ex|exs|clj|dart)$/i;
+
 /** Paths always exempt from story requirement. */
 const EXEMPT_PATHS = [
   '.claude/', '.sinapse-ai/', '.sinapse/', '.sinapse-custom/',
   'docs/', 'tests/', '__tests__/', 'test/',
   'node_modules/', '.git/', 'squads/', 'outputs/',
+  // Build outputs / generated — never gated.
+  '.next/', 'dist/', 'build/', 'out/', 'coverage/', '.vercel/', '.turbo/', '.cache/',
 ];
 
 /** Config files always exempt. */
@@ -49,6 +65,29 @@ const EXEMPT_FILES = [
   'postcss.config.js', 'postcss.config.cjs',
 ];
 
+/**
+ * Config-like files exempt by PATTERN in ANY folder (so the extension-based
+ * detection never over-blocks tooling config): `*.config.{js,ts,mjs,cjs}`,
+ * `*.d.ts` type decls, and dotfile rc configs (`.eslintrc.json`, `.prettierrc.cjs`).
+ */
+function isConfigLike(rel) {
+  const base = path.basename(rel);
+  return (
+    /\.config\.[cm]?[jt]s$/i.test(base) ||
+    /\.d\.ts$/i.test(base) ||
+    /^\.[a-z0-9_-]+rc(\.[a-z]+)?$/i.test(base)
+  );
+}
+
+/** True if this project IS the SINAPSE framework's own repo (Art. III exception). */
+function isFrameworkRepo(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8')).name === 'sinapse-ai';
+  } catch {
+    return false;
+  }
+}
+
 /** Story statuses that allow implementation. */
 const VALID_STATUSES = ['ready', 'inprogress', 'in progress', 'in_progress', 'inreview', 'in review', 'in_review', 'done'];
 
@@ -76,7 +115,13 @@ function isExempt(rel) {
 }
 
 function isCodePath(rel) {
-  return CODE_PATHS.some((cp) => rel.startsWith(cp));
+  // Config-like files are never gated, even inside code dirs.
+  if (isConfigLike(rel)) return false;
+  // Fast path: known code directory.
+  if (CODE_PATHS.some((cp) => rel.startsWith(cp))) return true;
+  // Catch-all: a code file (by extension) anywhere non-exempt, non-config —
+  // this is what closes the "code in server/ or root escapes the gate" hole.
+  return CODE_EXT.test(rel);
 }
 
 /**
@@ -180,6 +225,11 @@ function main() {
   // Only enforce on code paths
   if (!isCodePath(rel)) process.exit(0);
 
+  // Framework's own repo operates above the story layer (Art. III exception) —
+  // mirror doc-first-gate. The expanded detection now reaches scripts/ etc., so
+  // without this the framework's own development would be over-blocked.
+  if (isFrameworkRepo(root)) process.exit(0);
+
   // Check for active story
   if (hasActiveStory(root)) process.exit(0);
 

package/.claude/rules/coderabbit-integration.md

@@ -9,6 +9,12 @@ paths:
 
 # CodeRabbit Integration — Detailed Rules
 
+> **Single source of truth.** This rule (auto-loaded) plus the machine config in
+> `.sinapse-ai/core-config.yaml` (`coderabbit_integration`) are the ONE canonical
+> definition of the CodeRabbit integration — WSL execution mechanics, self-healing
+> thresholds, review commands, severity handling and report location. Agents
+> **reference** this; they must not copy the mechanics into their own definitions.
+
 ## Self-Healing Configuration
 
 ### Dev Phase (@developer — Story Development Cycle Phase 3)

package/.claude/rules/documentation-first-reference.md

@@ -0,0 +1,146 @@
+---
+paths:
+  - "packages/**"
+  - "squads/**"
+  - "bin/**"
+  - "scripts/**"
+  - "tests/**"
+  - ".sinapse-ai/**"
+  - "docs/epics/**"
+  - "docs/stories/**"
+  - "docs/prd.md"
+  - "docs/project-brief.md"
+  - "src/**"
+  - "app/**"
+  - "pages/**"
+  - "components/**"
+---
+
+# Documentation-First — Operational Reference
+
+> Companion to `documentation-first.md` (the always-on core law + gates). This file
+> carries the operational detail and loads when you work on code or product docs.
+
+## Required Pipeline (detail)
+
+1. **Epic** — The initiative MUST have an epic defined (or an existing one identified)
+2. **Story** — Each work unit MUST have a story file in `docs/stories/` with:
+   - Clear acceptance criteria (Given/When/Then preferred)
+   - Defined scope (IN/OUT)
+   - Dependencies mapped
+   - Complexity estimate
+3. **Validation** — Story MUST be validated (@product-lead) before implementation starts
+4. **Status** — Story status MUST be >= `Ready` before any code is written
+
+## Automatic Behavior
+
+| User Says | Agent Does |
+|-----------|-----------|
+| "Implementa feature X" | Creates story FIRST, then implements |
+| "Corrige esse bug" | Creates bug-fix story FIRST, then fixes |
+| "Faz isso rapidinho" | Creates story anyway — no shortcuts |
+| "Pula a documentacao" | REFUSES. Explains this is NON-NEGOTIABLE |
+| "So quero o codigo" | Routes to @sprint-lead for story, then @developer |
+
+## Enforcement model — floor-reactive by design (honest)
+
+Doc-first is enforced by a **deterministic reactive floor**, not by proactive prose: on a build request, `sinapse route` classifies the project type and **blocks** when the required artifacts are missing (story `Ready`; epic/PRD/architecture for large projects). This floor holds even if the agent forgets the rule, and it is covered by passing tests.
+
+Audit AF-20260629 **refuted** the earlier "prose without enforcement" hypothesis — the floor genuinely classifies and blocks. What is *not* wired into the prompt is the proactive **layer-2 conduction** (auto-walking the user through PRD → epic → story turn by turn). That layer is intentional **roadmap**, not a missing guardrail: no new always-on hook is added here by design (a reactive floor is lower-risk than a proactive prompt injector).
+
+## Project Type Gate — detail
+
+> **Why this exists:** A bare `epic + story` pipeline is necessary but not sufficient for **large projects**. A site, landing page, SaaS platform, mobile app, or backend service needs *upstream* artifacts (project brief, PRD, architecture, design spec) **before** stories can be written meaningfully. Without this gate, the framework writes stories from a vague verbal description and produces generic / off-brand output.
+
+### Classification matrix
+
+The first thing every agent does on a briefing is **classify the project type** by intent + keywords:
+
+| Project type | Trigger keywords (PT/EN) | Required workflow |
+|---|---|---|
+| `site` | site, website, institutional, página | `greenfield-ui.yaml` |
+| `lp` | landing page, LP, captura, sales page | `greenfield-ui.yaml` |
+| `app` | app, mobile, ios, android, react native | `greenfield-ui.yaml` |
+| `platform` | plataforma, dashboard, admin, portal | `greenfield-fullstack.yaml` |
+| `saas` | SaaS, software as a service, app web | `greenfield-fullstack.yaml` |
+| `api` | API, backend, microservice, serviço | `greenfield-service.yaml` |
+| `service` | worker, integration, automation, ETL | `greenfield-service.yaml` |
+| `feature` | feature, funcionalidade (existing project) | SDC (Story Development Cycle) |
+| `fix` | bug, conserta, corrige, ajusta, tweak | SDC YOLO mode |
+| `refactor` | refatora, limpa, renomeia | SDC interactive mode |
+
+### The gate
+
+```
+project_type ∈ [site, lp, app, platform, saas, api, service]
+  AND no epic exists in docs/epics/
+  → BLOCK execution
+  → INVOKE the required greenfield workflow
+  → No "implement first, document later" — ever
+```
+
+### Required upstream artifacts per project type
+
+| Project type | Required artifacts BEFORE first story |
+|---|---|
+| `site` / `lp` / `app` | project-brief.md → prd.md → front-end-spec.md → front-end-architecture.md |
+| `platform` / `saas` | project-brief.md → prd.md → front-end-spec.md → fullstack-architecture.md |
+| `api` / `service` | project-brief.md → prd.md → service-architecture.md |
+| `feature` (in existing project) | epic.md → story.md (no upstream re-doc needed) |
+| `fix` / `refactor` | story.md only (SDC) |
+
+### Complexity gate (Spec Pipeline trigger)
+
+When the user briefing is ambiguous or the scope is large, the gate ALSO triggers the Spec Pipeline (see `workflow-execution.md` § 3):
+
+```
+complexity_score ≥ 16 (COMPLEX class) → run Spec Pipeline FIRST
+  → @project-lead gathers requirements
+  → @architect assesses + plans
+  → @analyst researches
+  → @project-lead writes spec.md
+  → @quality-gate critiques
+  → only then: epic + stories
+```
+
+### Examples
+
+| User says | Classification | What the framework does |
+|---|---|---|
+| "criar um site pra meu cliente Acme" | `site` | Invokes `greenfield-ui.yaml` (5-agent Phase 1) |
+| "monta uma plataforma SaaS de gestão" | `saas` (COMPLEX) | Spec Pipeline → then `greenfield-fullstack.yaml` |
+| "API de cobrança Asaas" | `api` | Invokes `greenfield-service.yaml` |
+| "corrige o botão verde da home" | `fix` | SDC YOLO direct |
+| "implementa dark mode na plataforma" | `feature` | SDC interactive |
+| "landing page do lançamento de outubro" | `lp` | Invokes `greenfield-ui.yaml` |
+
+## Workflow Enforcement
+
+### CORRECT Flow (always)
+```
+User briefing
+  → @sprint-lead *draft (create story)
+  → @product-lead *validate (validate story)
+  → @developer *develop (implement)
+  → @quality-gate *qa-gate (quality check)
+  → @devops *push (deploy)
+```
+
+### FORBIDDEN Flow (never)
+```
+User briefing → @developer *develop (BLOCKED — no story)
+User briefing → Direct code writing (BLOCKED — no story)
+```
+
+## Anti-Patterns (FORBIDDEN) — full list
+
+- Writing ANY code without a story
+- "Quick fix" without documentation
+- Implementing features based only on verbal description
+- Skipping story validation
+- Starting implementation with a Draft story (must be Ready)
+- Treating documentation as "optional" or "we'll do it later"
+- Any agent accepting implementation work without verifying story exists
+- Routing a `site` / `lp` / `app` / `platform` / `saas` / `api` request directly to a domain orchestrator (e.g., `@design-orqx`, `@brand-orqx`) **before** the greenfield workflow runs and produces project-brief.md + prd.md
+- Skipping the Spec Pipeline on COMPLEX briefings (score ≥ 16)
+- Generating UI without DS grounding (see `~/.claude/rules/design-system-grounding.md`)

package/.claude/rules/documentation-first.md

@@ -2,37 +2,21 @@
 
 > **Constitution Article III — Elevated to NON-NEGOTIABLE**
 > Applies to ALL agents, ALL projects, ALL requests. No exceptions.
+> This is the always-on CORE (the law + the gates). Operational detail
+> (classification matrix, upstream-artifact tables, workflow files, examples)
+> lives in `documentation-first-reference.md` and loads when you work on code.
 
 ## Rule
 
-Before ANY code implementation begins, the full documentation pipeline MUST be completed. This is AUTOMATIC behavior — no user needs to request it.
-
-### Required Pipeline
+Before ANY code implementation begins, the documentation pipeline MUST be completed —
+AUTOMATIC behavior, never something the user requests:
 
 ```
 User briefing → Epic (if new initiative) → Story → Validation → Implementation
 ```
 
-1. **Epic** — The initiative MUST have an epic defined (or an existing one identified)
-2. **Story** — Each work unit MUST have a story file in `docs/stories/` with:
-   - Clear acceptance criteria (Given/When/Then preferred)
-   - Defined scope (IN/OUT)
-   - Dependencies mapped
-   - Complexity estimate
-3. **Validation** — Story MUST be validated (@product-lead) before implementation starts
-4. **Status** — Story status MUST be >= `Ready` before any code is written
-
-## Automatic Behavior (NON-NEGOTIABLE)
-
-This is NOT something the user needs to request. It happens AUTOMATICALLY on every briefing:
-
-| User Says | Agent Does |
-|-----------|-----------|
-| "Implementa feature X" | Creates story FIRST, then implements |
-| "Corrige esse bug" | Creates bug-fix story FIRST, then fixes |
-| "Faz isso rapidinho" | Creates story anyway — no shortcuts |
-| "Pula a documentacao" | REFUSES. Explains this is NON-NEGOTIABLE |
-| "So quero o codigo" | Routes to @sprint-lead for story, then @developer |
+If the user says "faz rapidinho", "pula a documentação", or "só quero o código":
+create the story anyway — the agent REFUSES shortcuts. This is NON-NEGOTIABLE.
 
 ## Gate: BLOCK
 
@@ -44,109 +28,33 @@ No implementation proceeds without ALL of these:
 
 **Attempting to write code without a valid story → BLOCKED.**
 
-## Enforcement model — floor-reactive by design (honest)
-
-Doc-first is enforced by a **deterministic reactive floor**, not by proactive prose: on a build request, `sinapse route` classifies the project type and **blocks** when the required artifacts are missing (story `Ready`; epic/PRD/architecture for large projects). This floor holds even if the agent forgets the rule, and it is covered by passing tests.
-
-Audit AF-20260629 **refuted** the earlier "prose without enforcement" hypothesis — the floor genuinely classifies and blocks. What is *not* wired into the prompt is the proactive **layer-2 conduction** (auto-walking the user through PRD → epic → story turn by turn). That layer is intentional **roadmap**, not a missing guardrail: no new always-on hook is added here by design (a reactive floor is lower-risk than a proactive prompt injector).
-
 ## Project Type Gate (NON-NEGOTIABLE)
 
-> **Why this exists:** A bare `epic + story` pipeline is necessary but not sufficient for **large projects**. A site, landing page, SaaS platform, mobile app, or backend service needs *upstream* artifacts (project brief, PRD, architecture, design spec) **before** stories can be written meaningfully. Without this gate, the framework writes stories from a vague verbal description and produces generic / off-brand output.
-
-### Classification matrix
-
-The first thing every agent does on a briefing is **classify the project type** by intent + keywords:
-
-| Project type | Trigger keywords (PT/EN) | Required workflow |
-|---|---|---|
-| `site` | site, website, institutional, página | `greenfield-ui.yaml` |
-| `lp` | landing page, LP, captura, sales page | `greenfield-ui.yaml` |
-| `app` | app, mobile, ios, android, react native | `greenfield-ui.yaml` |
-| `platform` | plataforma, dashboard, admin, portal | `greenfield-fullstack.yaml` |
-| `saas` | SaaS, software as a service, app web | `greenfield-fullstack.yaml` |
-| `api` | API, backend, microservice, serviço | `greenfield-service.yaml` |
-| `service` | worker, integration, automation, ETL | `greenfield-service.yaml` |
-| `feature` | feature, funcionalidade (existing project) | SDC (Story Development Cycle) |
-| `fix` | bug, conserta, corrige, ajusta, tweak | SDC YOLO mode |
-| `refactor` | refatora, limpa, renomeia | SDC interactive mode |
-
-### The gate
-
-```
-project_type ∈ [site, lp, app, platform, saas, api, service]
-  AND no epic exists in docs/epics/
-  → BLOCK execution
-  → INVOKE the required greenfield workflow
-  → No "implement first, document later" — ever
-```
-
-### Required upstream artifacts per project type
-
-| Project type | Required artifacts BEFORE first story |
-|---|---|
-| `site` / `lp` / `app` | project-brief.md → prd.md → front-end-spec.md → front-end-architecture.md |
-| `platform` / `saas` | project-brief.md → prd.md → front-end-spec.md → fullstack-architecture.md |
-| `api` / `service` | project-brief.md → prd.md → service-architecture.md |
-| `feature` (in existing project) | epic.md → story.md (no upstream re-doc needed) |
-| `fix` / `refactor` | story.md only (SDC) |
+A bare `epic + story` is NOT sufficient for large projects. On every briefing the
+agent FIRST classifies the project type; for `site / lp / app / platform / saas /
+api / service` with no epic in `docs/epics/` → **BLOCK execution and invoke the
+required greenfield workflow** (project-brief → PRD → spec/architecture → stories).
+No "implement first, document later" — ever. Ambiguous or large briefings
+(complexity ≥ 16 COMPLEX) ALSO trigger the Spec Pipeline first.
 
-### Complexity gate (Spec Pipeline trigger)
-
-When the user briefing is ambiguous or the scope is large, the gate ALSO triggers the Spec Pipeline (see `workflow-execution.md` § 3):
-
-```
-complexity_score ≥ 16 (COMPLEX class) → run Spec Pipeline FIRST
-  → @project-lead gathers requirements
-  → @architect assesses + plans
-  → @analyst researches
-  → @project-lead writes spec.md
-  → @quality-gate critiques
-  → only then: epic + stories
-```
-
-### Examples
-
-| User says | Classification | What the framework does |
-|---|---|---|
-| "criar um site pra meu cliente Acme" | `site` | Invokes `greenfield-ui.yaml` (5-agent Phase 1) |
-| "monta uma plataforma SaaS de gestão" | `saas` (COMPLEX) | Spec Pipeline → then `greenfield-fullstack.yaml` |
-| "API de cobrança Asaas" | `api` | Invokes `greenfield-service.yaml` |
-| "corrige o botão verde da home" | `fix` | SDC YOLO direct |
-| "implementa dark mode na plataforma" | `feature` | SDC interactive |
-| "landing page do lançamento de outubro" | `lp` | Invokes `greenfield-ui.yaml` |
-
-## Workflow Enforcement
-
-### CORRECT Flow (always)
-```
-User briefing
-  → @sprint-lead *draft (create story)
-  → @product-lead *validate (validate story)
-  → @developer *develop (implement)
-  → @quality-gate *qa-gate (quality check)
-  → @devops *push (deploy)
-```
-
-### FORBIDDEN Flow (never)
-```
-User briefing → @developer *develop (BLOCKED — no story)
-User briefing → Direct code writing (BLOCKED — no story)
-```
+Enforcement is a deterministic reactive floor: `sinapse route` classifies and
+blocks when required artifacts are missing — it holds even if the agent forgets.
 
 ## Exception
 
-The ONLY exception is framework governance work by @sinapse-orqx (constitutional amendments, ecosystem health), which operates above the story layer. Even then, changes SHOULD be documented.
+ONLY framework governance work by @sinapse-orqx (constitutional amendments,
+ecosystem health) operates above the story layer. Even then, changes SHOULD be documented.
 
 ## Anti-Patterns (FORBIDDEN)
 
-- Writing ANY code without a story
-- "Quick fix" without documentation
-- Implementing features based only on verbal description
-- Skipping story validation
-- Starting implementation with a Draft story (must be Ready)
-- Treating documentation as "optional" or "we'll do it later"
-- Any agent accepting implementation work without verifying story exists
-- Routing a `site` / `lp` / `app` / `platform` / `saas` / `api` request directly to a domain orchestrator (e.g., `@design-orqx`, `@brand-orqx`) **before** the greenfield workflow runs and produces project-brief.md + prd.md
+- Writing ANY code without a story; "quick fix" without documentation
+- Starting implementation with a Draft story (must be Ready); skipping validation
+- Routing a large-project request to a domain orchestrator before the greenfield
+  workflow produces project-brief.md + prd.md
 - Skipping the Spec Pipeline on COMPLEX briefings (score ≥ 16)
-- Generating UI without DS grounding (see `~/.claude/rules/design-system-grounding.md`)
+- Treating documentation as "optional" or "we'll do it later"
+
+> **Detail (loads on code work):** classification matrix (triggers per project
+> type), required upstream artifacts per type, complexity dimensions, correct /
+> forbidden flows, examples, enforcement-model notes — see
+> `documentation-first-reference.md`.

package/.claude/rules/mandatory-delegation-reference.md

@@ -0,0 +1,93 @@
+---
+paths:
+  - "squads/**"
+  - ".sinapse-ai/development/**"
+  - ".claude/commands/**"
+  - ".claude/agents/**"
+---
+
+# Mandatory Delegation — Operational Reference
+
+> Companion to `mandatory-delegation.md` (the always-on core law). This file carries
+> the full matrices and handoff detail and loads when you work on agent/squad files.
+
+## Delegation Matrix
+
+### Framework Agents (Development Workflow)
+
+| Request Type | Delegate To |
+|-------------|-------------|
+| Code implementation | @developer (Pixel) |
+| Story creation | @sprint-lead (Sync) |
+| Story validation | @product-lead (Axis) |
+| Architecture decisions | @architect (Stratum) |
+| Quality/testing | @quality-gate (Litmus) |
+| Database work | @data-engineer (Tensor) |
+| UX/UI design | @ux-design-expert (Mosaic) |
+| Git push/PR/release | @devops (Pipeline) |
+| Epic orchestration | @project-lead (Beacon) |
+| Research/analysis | @analyst (Scope) |
+
+### Squad Orchestrators (Domain Expertise)
+
+| Request Domain | Delegate To |
+|---------------|-------------|
+| Branding, identidade visual | @brand-orqx (Meridian) |
+| Vendas, CRM, pipeline | @commercial-orqx (Pipeline) |
+| Conteudo, editorial | @content-orqx |
+| Copywriting, persuasao | @copy-orqx (Quill) |
+| Animacoes web, motion | @animations-orqx (Kinetic) |
+| UX/UI, design system | @design-orqx (Nexus) |
+| Financeiro, pricing | @finance-orqx (Ledger) |
+| Growth, SEO, analytics | @growth-orqx (Catalyst) |
+| Midia paga, ads | @paidmedia-orqx (Apex) |
+| Produto, roadmap | @product-orqx (Vector) |
+| Pesquisa, inteligencia | @research-orqx (Prism) |
+| Claude Code mastery | @swarm-orqx (Relay) |
+| Conselho estrategico | @council-orqx (Zenith) |
+| Storytelling, pitch | @storytelling-orqx (Arc) |
+| Cybersecurity | @cyber-orqx (Fortress) |
+| Clonagem cognitiva | @cloning-orqx (Helix) |
+| Cursos, workshops | @courses-orqx (Syllabus) |
+
+## What Orchestrators CAN Do (their actual domain)
+
+Orchestrators have their OWN domain of expertise:
+
+| Orchestrator | Own Domain (can execute directly) |
+|-------------|----------------------------------|
+| Imperator (sinapse-orqx) | Routing, diagnostico, plano de orquestracao, coordenacao cross-squad, framework governance |
+| Squad *-orqx | Routing intra-squad, coordenacao de agentes do squad, handoff management |
+
+Everything OUTSIDE their orchestration domain MUST be delegated.
+
+## Universal Auto-Routing — detail
+
+**On EVERY user message (not just orchestrator):**
+1. Detect the domain of the request
+2. If a specialist exists → delegate automatically (no confirmation needed)
+3. Brief acknowledgment: "Delegando para @specialist..."
+4. Return the result to the user
+
+**Auto-detect project state on first interaction:**
+- Check for `.sinapse-ai/` → SINAPSE-managed (continue SDC)
+- Check for `package.json` or `.git` → Brownfield (run quick tech scan first)
+- Empty directory → Greenfield (ask project type, scaffold)
+
+**Cross-agent handoff (automatic, never ask user):**
+- Agent needs git push → auto-delegate to @devops
+- Agent needs tests → auto-delegate to @quality-gate
+- Agent needs schema → auto-delegate to @data-engineer
+- Agent needs story → auto-create via fast-track or @sprint-lead
+- Agent needs architecture decision → auto-delegate to @architect
+
+## Anti-Patterns (FORBIDDEN) — full list
+
+- Orchestrator writing application code
+- Orchestrator making architectural decisions without @architect
+- Orchestrator creating stories without @sprint-lead
+- Orchestrator running quality checks without @quality-gate
+- Orchestrator doing database work without @data-engineer
+- Orchestrator doing ANY specialist work outside of orchestration
+- Saying "vou fazer isso eu mesmo" instead of delegating
+- Absorbing a request and executing it instead of routing