sinapse-ai 1.21.0 → 1.22.0

package/.claude/rules/project-intelligence-reference.md

@@ -0,0 +1,159 @@
+---
+paths:
+  - "package.json"
+  - "core-config.yaml"
+  - "docs/prd.md"
+  - "docs/project-brief.md"
+  - "docs/epics/**"
+  - "docs/stories/**"
+  - ".sinapse-ai/**"
+---
+
+# Project Intelligence — Operational Reference
+
+> Companion to `project-intelligence.md` (the always-on core law). This file carries
+> the per-dimension signals, behaviors and examples and loads when you work on
+> project-setup files.
+
+## Initial State Audit — signals per dimension
+
+The audit collects existence + summary for each dimension. Each is a YES/NO/PARTIAL signal:
+
+| # | Dimension | Signals checked |
+|---|---|---|
+| 1 | **Docs** | `docs/project-brief.md`, `docs/prd.md`, `docs/architecture*.md`, `docs/front-end-spec.md`, `docs/epics/`, `docs/stories/` |
+| 2 | **Brand** | `brand/`, `brandbook*`, `assets/brand/`, `public/brand/`, `*logo*`, `BRAND.md`, `BRANDBOOK.md` |
+| 3 | **Design system** | `tokens.json`, `design-tokens.json`, `tailwind.config.*` with custom theme, `components/ui/`, `DESIGN.md`, `DS.md` |
+| 4 | **Components** | `components/`, `src/components/`, `app/`, `pages/` with `.tsx` / `.jsx` / `.vue` files |
+| 5 | **Code** | `package.json`, `tsconfig.json`, `src/`, language-specific markers (`go.mod`, `pyproject.toml`, `Cargo.toml`) |
+| 6 | **Tests** | `jest.config.*`, `vitest.config.*`, `__tests__/`, `tests/`, `*.test.*`, `*.spec.*` |
+| 7 | **Infra** | `.github/workflows/`, `Dockerfile`, `docker-compose.*`, `vercel.json`, `.env.example`, CI configs |
+| 8 | **Git history** | `.git/` exists, `git log` has commits, recent activity (last 30 days), branch count |
+
+### Maturity classification — criteria
+
+| Level | Criteria | Recommended workflow |
+|---|---|---|
+| `EMPTY` | 0/8 signals; directory has only `.git/` or nothing | Full greenfield workflow (greenfield-handler.js) |
+| `BOOTSTRAPPED` | Only Infra (7) present (CI, Dockerfile, .env.example) — no code yet | Skip Phase 0 Bootstrap, jump to Phase 1 Discovery |
+| `PARTIAL` | Some Docs/Brand/DS but no Code, OR Code without Docs | **Continue from where it stopped** — never overwrite, merge with existing |
+| `MATURE` | Code + Tests + (Docs OR Infra) — real working project | Brownfield Discovery (10-phase technical debt) before any change |
+| `SINAPSE_MANAGED` | `.sinapse-ai/` exists with `core-config.yaml` | Resume SDC: read `docs/stories/`, find active story, continue |
+
+### Audit output (always presented to user before proceeding)
+
+```
+Estado detectado: {maturity_level}
+Já existe: {list of YES dimensions, e.g., "Brand (logo + brandbook), 1 PRD parcial em docs/, 5 componentes UI"}
+Faltando: {list of NO dimensions critical to the user's request}
+Recomendação: {workflow + concrete first step}
+```
+
+### Anti-shortcuts (FORBIDDEN)
+
+- Skipping the audit because "it looks empty" — always run, always check all 8 dimensions
+- Calling a directory "greenfield" because `package.json` is missing (could have brand assets, half-written PRD, design tokens — all without `package.json`)
+- Calling a directory "brownfield" only because `package.json` exists (could be just bootstrapped infra with zero feature work — different workflow)
+- Overwriting existing partial work without listing it to the user first
+- Ignoring `docs/epics/` and `docs/stories/` from a previous session
+
+## Quick Tech Scan (BROWNFIELD, < 5 seconds)
+
+When brownfield detected, silently check:
+
+| Check | How | Sets Context |
+|-------|-----|-------------|
+| Framework | package.json dependencies | next/react/vue/angular/express |
+| Language | tsconfig.json exists? | typescript/javascript |
+| Database | supabase/, prisma/, .env | supabase/prisma/drizzle/none |
+| Tests | jest.config, vitest.config | jest/vitest/none |
+| CI | .github/workflows/ | github-actions/none |
+
+Report to user in ONE line: "Projeto Next.js + TypeScript + Supabase detectado."
+
+## Behavior Adaptation by State
+
+### Greenfield Behavior
+
+A bare `setup → story → implement` loop is **not enough** for greenfield. Large projects need upstream artifacts (project-brief, PRD, architecture, design spec) BEFORE stories. The greenfield branch sub-classifies the request and invokes the right workflow.
+
+#### Step 1 — Sub-classify project_type
+
+Detect intent and target from the user's first message (PT-BR or EN keywords):
+
+| project_type | Triggers |
+|---|---|
+| `site` | site, website, institucional, página, web page |
+| `lp` | landing page, LP, captura, sales page, squeeze page |
+| `app` | app mobile, ios, android, react native, flutter |
+| `platform` | plataforma, dashboard, admin panel, portal interno |
+| `saas` | SaaS, software as a service, app web com login, multi-tenant |
+| `api` | API, backend, REST, GraphQL, microservice |
+| `service` | worker, cron job, ETL, integration, automation |
+
+If detection is ambiguous, ask ONE clarifying question with these options as choices.
+
+#### Step 2 — Map to required workflow
+
+| project_type | Workflow file | Phase 1 agents |
+|---|---|---|
+| `site` / `lp` / `app` | `.sinapse-ai/development/workflows/greenfield-ui.yaml` | analyst → project-lead → ux-design-expert → architect → product-lead |
+| `platform` / `saas` | `.sinapse-ai/development/workflows/greenfield-fullstack.yaml` | analyst → project-lead → ux-design-expert → architect → product-lead |
+| `api` / `service` | `.sinapse-ai/development/workflows/greenfield-service.yaml` | analyst → project-lead → architect → product-lead |
+
+Execution mechanism: `.sinapse-ai/core/orchestration/greenfield-handler.js` orchestrates Phase 0 (Bootstrap) → Phase 1 (Discovery 5-agent) → Phase 2 (Sharding) → Phase 3 (Dev Cycle).
+
+#### Step 3 — Apply DS grounding (UI projects)
+
+For `site` / `lp` / `app` / `platform` / `saas`, the DS Resolver runs before any visual output (see `~/.claude/rules/design-system-grounding.md`). Internal projects use the SINAPSE Brandbook; external clients use the client's brand or the high-quality fallback.
+
+#### Step 4 — Forbidden shortcut
+
+The greenfield branch NEVER skips to "implement" without:
+- `docs/project-brief.md` validated
+- `docs/prd.md` validated
+- `docs/{front-end-spec | service-architecture}.md` validated
+- `docs/architecture.md` (or `fullstack-architecture.md`) validated
+- Stories in `docs/stories/` with status ≥ Ready
+
+#### Auto-apply infra templates
+
+Independent of project_type: PR template, CI, `.env.example`, CODEOWNERS, gitignore. These run during Phase 0 (Bootstrap) of the greenfield workflow.
+
+### Continuation Behavior (PARTIAL maturity)
+
+When the audit detects partial work — e.g., a brandbook without a site, a PRD without code, components without architecture, an abandoned epic — the framework MUST treat it as a continuation, not a bootstrap.
+
+- **Inventory first:** list every existing artifact and tell the user what's there
+- **Identify gaps:** what's missing to ship the user's stated goal?
+- **Propose continuation plan:** which greenfield phase resumes from here? which brownfield steps apply?
+- **Merge, never replace:** existing brand/DS/components are inputs to the workflow, not throwaway scaffolding
+- **Preserve epic + story state:** if `docs/epics/` or `docs/stories/` exist, resume their lifecycle (Draft → Ready → InProgress → Done)
+
+Example: user says "criar um site" but the audit finds a `brand/` folder with logo + brandbook. The framework reports:
+> Estado: `PARTIAL`. Já existe: brand assets (logo + brandbook). Faltando: PRD, design spec, código. Recomendação: greenfield-ui.yaml começando da Phase 1, usando seu brandbook como input.
+
+### Brownfield Behavior (MATURE maturity)
+- Prioritize: understanding existing code before changing anything
+- First action: read README, package.json, folder structure
+- Workflow: quick scan → understand → then proceed with user request
+- NEVER rewrite or refactor without understanding existing patterns
+- Respect existing conventions (naming, folder structure, testing framework)
+- For non-trivial changes: invoke Brownfield Discovery (10-phase technical debt assessment)
+
+### SINAPSE-Managed Behavior
+- Check for active story in docs/stories/
+- Resume where last session left off
+- Follow SDC workflow (story → implement → QA → push)
+
+## Anti-Patterns (FORBIDDEN) — full list
+
+- Asking user "is this a new or existing project?"
+- Asking user to set `projectType` in config
+- Starting implementation in brownfield without reading existing code first
+- Applying greenfield templates to a brownfield project (overwriting existing CI/configs)
+- Ignoring existing patterns and imposing SINAPSE conventions forcefully
+- Treating greenfield as "setup → story → implement" without sub-classifying project_type
+- Skipping `greenfield-handler.js` (or its workflow file) on a `site` / `lp` / `platform` / `saas` / `api` request
+- Letting a domain orchestrator (design, brand) generate visual output before greenfield Phase 1 produces project-brief.md + prd.md + design spec
+- Generating UI without DS grounding (see `~/.claude/rules/design-system-grounding.md`)

package/.claude/rules/project-intelligence.md

@@ -1,168 +1,50 @@
 # Project Intelligence — Auto-Detection (NON-NEGOTIABLE)
 
 > Applies to ALL agents, ALL sessions. Users NEVER configure project type manually.
+> This is the always-on CORE (the law). The per-dimension signals, per-state
+> behaviors (greenfield / continuation / brownfield / SINAPSE-managed) and examples
+> live in `project-intelligence-reference.md` and load when you work on
+> project-setup files.
 
-## Initial State Audit (ALWAYS FIRST — runs before classification)
+## Initial State Audit (ALWAYS FIRST — NON-NEGOTIABLE preflight)
 
-> **This is a NON-NEGOTIABLE preflight step.** Without it, the framework treats every fresh-looking directory as "greenfield" and ignores partial work that's already there (existing brand, components, half-written PRD, abandoned epics, an in-progress design system, brownfield code with no `package.json`, etc.). The audit costs ~2 seconds and prevents the framework from overwriting or duplicating work.
+Before classifying anything, silently audit **8 dimensions** (existence + summary):
+**Docs · Brand · Design system · Components · Code · Tests · Infra · Git history.**
+Never skip it "because it looks empty" — partial work (brand without code, a
+half-written PRD, abandoned epics) is exactly what the audit protects.
 
-### Eight dimensions to check (silent, parallel)
+## Maturity Classification (from the 8 signals)
 
-The audit collects existence + summary for each dimension. Each is a YES/NO/PARTIAL signal:
-
-| # | Dimension | Signals checked |
-|---|---|---|
-| 1 | **Docs** | `docs/project-brief.md`, `docs/prd.md`, `docs/architecture*.md`, `docs/front-end-spec.md`, `docs/epics/`, `docs/stories/` |
-| 2 | **Brand** | `brand/`, `brandbook*`, `assets/brand/`, `public/brand/`, `*logo*`, `BRAND.md`, `BRANDBOOK.md` |
-| 3 | **Design system** | `tokens.json`, `design-tokens.json`, `tailwind.config.*` with custom theme, `components/ui/`, `DESIGN.md`, `DS.md` |
-| 4 | **Components** | `components/`, `src/components/`, `app/`, `pages/` with `.tsx` / `.jsx` / `.vue` files |
-| 5 | **Code** | `package.json`, `tsconfig.json`, `src/`, language-specific markers (`go.mod`, `pyproject.toml`, `Cargo.toml`) |
-| 6 | **Tests** | `jest.config.*`, `vitest.config.*`, `__tests__/`, `tests/`, `*.test.*`, `*.spec.*` |
-| 7 | **Infra** | `.github/workflows/`, `Dockerfile`, `docker-compose.*`, `vercel.json`, `.env.example`, CI configs |
-| 8 | **Git history** | `.git/` exists, `git log` has commits, recent activity (last 30 days), branch count |
-
-### Maturity classification
-
-Combining the 8 signals produces 1 of 5 maturity levels:
-
-| Level | Criteria | Recommended workflow |
+| Level | Meaning | Path |
 |---|---|---|
-| `EMPTY` | 0/8 signals; directory has only `.git/` or nothing | Full greenfield workflow (greenfield-handler.js) |
-| `BOOTSTRAPPED` | Only Infra (7) present (CI, Dockerfile, .env.example) — no code yet | Skip Phase 0 Bootstrap, jump to Phase 1 Discovery |
-| `PARTIAL` | Some Docs/Brand/DS but no Code, OR Code without Docs | **Continue from where it stopped** — never overwrite, merge with existing |
-| `MATURE` | Code + Tests + (Docs OR Infra) — real working project | Brownfield Discovery (10-phase technical debt) before any change |
-| `SINAPSE_MANAGED` | `.sinapse-ai/` exists with `core-config.yaml` | Resume SDC: read `docs/stories/`, find active story, continue |
-
-### Audit output (always presented to user before proceeding)
+| `EMPTY` | 0/8 signals | Full greenfield workflow |
+| `BOOTSTRAPPED` | only Infra present | Greenfield from Phase 1 (skip Bootstrap) |
+| `PARTIAL` | some Docs/Brand/DS without Code, or Code without Docs | **Continue** — never overwrite, merge with existing |
+| `MATURE` | Code + Tests + (Docs OR Infra) | Brownfield Discovery before any change |
+| `SINAPSE_MANAGED` | `.sinapse-ai/` + `core-config.yaml` | Resume SDC from active story |
+
+**Audit output is always presented to the user before proceeding** (one structured
+PT-BR paragraph: estado detectado · já existe · faltando · recomendação). Only
+after this report does the framework classify + invoke workflows.
+
+## The Law
+
+- **Auto-detect, never ask** "is this a new or existing project?" or make the user
+  set `projectType`.
+- **Brownfield:** understand existing code BEFORE changing anything; respect
+  existing conventions; never impose SINAPSE conventions forcefully.
+- **Partial work is sacred:** inventory first, merge — never replace; preserve
+  epic/story state from previous sessions.
+- **Greenfield is NOT "setup → story → implement":** sub-classify the project type
+  and run the required greenfield workflow with its upstream artifacts.
 
-After running the audit, the framework reports in ONE structured paragraph (PT-BR):
-
-```
-Estado detectado: {maturity_level}
-Já existe: {list of YES dimensions, e.g., "Brand (logo + brandbook), 1 PRD parcial em docs/, 5 componentes UI"}
-Faltando: {list of NO dimensions critical to the user's request}
-Recomendação: {workflow + concrete first step}
-```
-
-Only AFTER this report (and any user adjustment) does the framework proceed to classification + workflow invocation.
-
-### Anti-shortcuts (FORBIDDEN)
+## Anti-Patterns (FORBIDDEN)
 
-- Skipping the audit because "it looks empty" — always run, always check all 8 dimensions
-- Calling a directory "greenfield" because `package.json` is missing (could have brand assets, half-written PRD, design tokens — all without `package.json`)
-- Calling a directory "brownfield" only because `package.json` exists (could be just bootstrapped infra with zero feature work — different workflow)
+- Skipping the audit; calling a directory greenfield/brownfield from one signal
 - Overwriting existing partial work without listing it to the user first
 - Ignoring `docs/epics/` and `docs/stories/` from a previous session
+- Applying greenfield templates over an existing project's CI/configs
 
-## Classification (after audit)
-
-Use the maturity level from the audit to pick the path:
-
-```
-maturity == EMPTY              → Full greenfield (see Greenfield Behavior below)
-maturity == BOOTSTRAPPED       → Greenfield Phase 1 onward (skip Bootstrap)
-maturity == PARTIAL            → Continuation Behavior (below)
-maturity == MATURE             → Brownfield Behavior (below)
-maturity == SINAPSE_MANAGED    → SINAPSE-Managed Behavior (below)
-```
-
-## Quick Tech Scan (BROWNFIELD, < 5 seconds)
-
-When brownfield detected, silently check:
-
-| Check | How | Sets Context |
-|-------|-----|-------------|
-| Framework | package.json dependencies | next/react/vue/angular/express |
-| Language | tsconfig.json exists? | typescript/javascript |
-| Database | supabase/, prisma/, .env | supabase/prisma/drizzle/none |
-| Tests | jest.config, vitest.config | jest/vitest/none |
-| CI | .github/workflows/ | github-actions/none |
-
-Report to user in ONE line: "Projeto Next.js + TypeScript + Supabase detectado."
-
-## Behavior Adaptation by State
-
-### Greenfield Behavior
-
-A bare `setup → story → implement` loop is **not enough** for greenfield. Large projects need upstream artifacts (project-brief, PRD, architecture, design spec) BEFORE stories. The greenfield branch sub-classifies the request and invokes the right workflow.
-
-#### Step 1 — Sub-classify project_type
-
-Detect intent and target from the user's first message (PT-BR or EN keywords):
-
-| project_type | Triggers |
-|---|---|
-| `site` | site, website, institucional, página, web page |
-| `lp` | landing page, LP, captura, sales page, squeeze page |
-| `app` | app mobile, ios, android, react native, flutter |
-| `platform` | plataforma, dashboard, admin panel, portal interno |
-| `saas` | SaaS, software as a service, app web com login, multi-tenant |
-| `api` | API, backend, REST, GraphQL, microservice |
-| `service` | worker, cron job, ETL, integration, automation |
-
-If detection is ambiguous, ask ONE clarifying question with these options as choices.
-
-#### Step 2 — Map to required workflow
-
-| project_type | Workflow file | Phase 1 agents |
-|---|---|---|
-| `site` / `lp` / `app` | `.sinapse-ai/development/workflows/greenfield-ui.yaml` | analyst → project-lead → ux-design-expert → architect → product-lead |
-| `platform` / `saas` | `.sinapse-ai/development/workflows/greenfield-fullstack.yaml` | analyst → project-lead → ux-design-expert → architect → product-lead |
-| `api` / `service` | `.sinapse-ai/development/workflows/greenfield-service.yaml` | analyst → project-lead → architect → product-lead |
-
-Execution mechanism: `.sinapse-ai/core/orchestration/greenfield-handler.js` orchestrates Phase 0 (Bootstrap) → Phase 1 (Discovery 5-agent) → Phase 2 (Sharding) → Phase 3 (Dev Cycle).
-
-#### Step 3 — Apply DS grounding (UI projects)
-
-For `site` / `lp` / `app` / `platform` / `saas`, the DS Resolver runs before any visual output (see `~/.claude/rules/design-system-grounding.md`). Internal projects use the SINAPSE Brandbook; external clients use the client's brand or the high-quality fallback.
-
-#### Step 4 — Forbidden shortcut
-
-The greenfield branch NEVER skips to "implement" without:
-- `docs/project-brief.md` validated
-- `docs/prd.md` validated
-- `docs/{front-end-spec | service-architecture}.md` validated
-- `docs/architecture.md` (or `fullstack-architecture.md`) validated
-- Stories in `docs/stories/` with status ≥ Ready
-
-#### Auto-apply infra templates
-
-Independent of project_type: PR template, CI, `.env.example`, CODEOWNERS, gitignore. These run during Phase 0 (Bootstrap) of the greenfield workflow.
-
-### Continuation Behavior (PARTIAL maturity)
-
-When the audit detects partial work — e.g., a brandbook without a site, a PRD without code, components without architecture, an abandoned epic — the framework MUST treat it as a continuation, not a bootstrap.
-
-- **Inventory first:** list every existing artifact and tell the user what's there
-- **Identify gaps:** what's missing to ship the user's stated goal?
-- **Propose continuation plan:** which greenfield phase resumes from here? which brownfield steps apply?
-- **Merge, never replace:** existing brand/DS/components are inputs to the workflow, not throwaway scaffolding
-- **Preserve epic + story state:** if `docs/epics/` or `docs/stories/` exist, resume their lifecycle (Draft → Ready → InProgress → Done)
-
-Example: user says "criar um site" but the audit finds a `brand/` folder with logo + brandbook. The framework reports:
-> Estado: `PARTIAL`. Já existe: brand assets (logo + brandbook). Faltando: PRD, design spec, código. Recomendação: greenfield-ui.yaml começando da Phase 1, usando seu brandbook como input.
-
-### Brownfield Behavior (MATURE maturity)
-- Prioritize: understanding existing code before changing anything
-- First action: read README, package.json, folder structure
-- Workflow: quick scan → understand → then proceed with user request
-- NEVER rewrite or refactor without understanding existing patterns
-- Respect existing conventions (naming, folder structure, testing framework)
-- For non-trivial changes: invoke Brownfield Discovery (10-phase technical debt assessment)
-
-### SINAPSE-Managed Behavior
-- Check for active story in docs/stories/
-- Resume where last session left off
-- Follow SDC workflow (story → implement → QA → push)
-
-## Anti-Patterns (FORBIDDEN)
-
-- Asking user "is this a new or existing project?"
-- Asking user to set `projectType` in config
-- Starting implementation in brownfield without reading existing code first
-- Applying greenfield templates to a brownfield project (overwriting existing CI/configs)
-- Ignoring existing patterns and imposing SINAPSE conventions forcefully
-- Treating greenfield as "setup → story → implement" without sub-classifying project_type
-- Skipping `greenfield-handler.js` (or its workflow file) on a `site` / `lp` / `platform` / `saas` / `api` request
-- Letting a domain orchestrator (design, brand) generate visual output before greenfield Phase 1 produces project-brief.md + prd.md + design spec
-- Generating UI without DS grounding (see `~/.claude/rules/design-system-grounding.md`)
+> **Detail (loads on setup work):** signals checked per dimension, quick tech scan
+> table, per-state behaviors (greenfield steps 1-4, continuation, brownfield,
+> SINAPSE-managed), examples — see `project-intelligence-reference.md`.

package/.claude/rules/safe-collaboration-reference.md

@@ -0,0 +1,163 @@
+---
+paths:
+  - "**/*"
+---
+
+# Safe Collaboration — Operational Reference
+
+> Companion to `safe-collaboration.md` (the always-on core law). This file carries the
+> operational detail and loads when you work on files — i.e., when a commit/push is coming.
+
+## Automatic Safety Protocol (every session)
+
+### 1. Session Start — Auto-Sync (MANDATORY)
+
+Before ANY work begins in a session, the agent MUST:
+
+```
+1. git fetch origin
+2. Check if local main is behind origin/main
+3. If behind → git pull origin main (fast-forward only)
+4. If diverged → STOP, inform user, resolve safely
+5. Create work branch if not already on one
+6. Verify branch protection is active on main
+```
+
+### 2. Branch Naming — Automatic
+
+The agent creates the branch. The user never needs to name it.
+
+| Who | Branch Pattern | Example |
+|-----|---------------|---------|
+| Caio's session | `caio/{type}/{short-desc}` | `caio/feat/installer-ux` |
+| Matheus's session | `soier/{type}/{short-desc}` | `soier/fix/agent-config` |
+| AI agent | `agent/{squad}/{agent-id}/{type}-{desc}` | `agent/core/pixel/feat-dark-mode` |
+| Unknown | `dev/{type}/{short-desc}` | `dev/feat/new-feature` |
+
+Types: `feat`, `fix`, `refactor`, `docs`, `chore`, `test`
+
+**User Detection (priority order):**
+1. `git config user.name` -> lookup in mapping table (case-insensitive)
+2. `$USERNAME` (Windows) or `$USER` (Unix) -> lookup in mapping table
+3. Fallback: `dev/`
+
+**Mapping Table:**
+
+| git config / env var contains | Branch prefix |
+|-------------------------------|---------------|
+| caio (case-insensitive)       | `caio/`       |
+| matheus OR soier              | `soier/`      |
+| (anything else)               | `dev/`        |
+
+### 3. Before Every Commit — Safety Checks (MANDATORY)
+
+```
+1. git status — verify only expected files changed
+2. git diff --stat — show summary to user
+3. SECRET SCAN — reject if ANY of these are staged:
+   - .env files (except .env.example with placeholders)
+   - Files containing API keys, tokens, passwords in plaintext
+   - Private keys (RSA, SSH, PGP)
+   - Database connection strings with credentials
+   - Webhook URLs with embedded tokens
+4. Commit with conventional message + story reference
+```
+
+**If secrets detected → BLOCK commit, warn user, remove file from staging.**
+
+### 4. Before Push — Conflict Prevention (MANDATORY)
+
+```
+1. git fetch origin main
+2. git merge origin/main --no-edit (into feature branch)
+3. If conflicts → AGENT resolves them (not the user)
+   - For simple conflicts (whitespace, imports): auto-resolve
+   - For complex conflicts: show both versions, ask user which to keep
+4. Run tests after merge
+5. Only then: git push origin {branch}
+```
+
+### 5. PR Creation — Automatic
+
+After push, the agent MUST:
+```
+1. gh pr create with clear title and description (uses PR template)
+2. Auto-assign reviewer based on who is pushing:
+   - Maintainer's PR → can merge directly (admin bypass)
+   - Collaborator's PR → assign maintainer as reviewer (required approval)
+3. Inform the user: "PR criado"
+```
+
+### 6. After PR Merge — Cleanup
+
+```
+1. git checkout main
+2. git pull origin main
+3. Delete local feature branch
+4. Inform user: "Branch limpa, pronto para proximo trabalho"
+```
+
+## Conflict Resolution Rules
+
+| Scenario | Agent Action |
+|----------|-------------|
+| Same file, different sections | Auto-merge (git handles) |
+| Same file, same lines | Show diff, ask user which version to keep |
+| Package.json version conflict | Always take higher version |
+| Generated files (lock, build) | Regenerate after merge |
+| Story/doc files | Merge both contents (additive) |
+
+**NEVER use `--force` push. Use `--force-with-lease` ONLY as last resort with user confirmation.**
+
+## Communication Protocol
+
+When working in parallel, agents MUST inform users about:
+
+| Event | Message |
+|-------|---------|
+| Session start | "Atualizando seu projeto... X mudancas novas do {outro}." |
+| Branch created | "Criada area segura para trabalhar: `caio/feat/xxx`" |
+| Pre-push conflict found | "{outro} mudou {file}. Resolvendo automaticamente..." |
+| Secret detected | "BLOQUEADO: encontrei {tipo} em {file}. Removendo antes de salvar." |
+| PR created | "Enviei para revisao. {outro} precisa aprovar no GitHub." |
+| PR merged by other | "{outro} aprovou suas mudancas. Atualizando seu projeto..." |
+
+## Destructive Operations — BLOCKED BY DEFAULT
+
+These operations require EXPLICIT user confirmation before execution:
+
+| Operation | Risk | Confirmation Required |
+|-----------|------|----------------------|
+| `git push --force` / `--force-with-lease` | Overwrite remote history | YES + explain risk |
+| `git reset --hard` | Destroy local uncommitted work | YES + explain risk |
+| `git branch -D` | Delete branch with unmerged commits | YES + explain risk |
+| `git clean -f` | Delete untracked files permanently | YES + explain risk |
+| Delete remote branch | Affects other collaborators | YES |
+
+## For Projects Using SINAPSE (not just sinapse-ai repo)
+
+These same rules apply to ANY project where SINAPSE agents operate:
+1. Auto-branch before work
+2. Auto-sync before starting
+3. Secret scan before every commit
+4. Auto-resolve simple conflicts
+5. Auto-PR with reviewer assignment
+6. User never touches git directly
+
+## User Cheat Sheet (the ONLY things users do manually)
+
+```
+! git push origin main          ← when agent can't push (hook block)
+! npm publish                   ← when publishing to NPM
+```
+
+Everything else: **ask the agent to do it.**
+
+## PR Quality Standards
+
+| Metric | Target | Warning |
+|--------|--------|---------|
+| PR size | < 200 lines | > 400 lines |
+| PR cycle time | < 1 day | > 3 days |
+
+**DORA Targets (Elite):** Deploy multiple/day, lead time < 1 day, failure rate < 4%, recovery < 1 hour.