sinapse-ai 9.3.0 → 9.5.0

package/.sinapse-ai/development/skills/debug.md

@@ -0,0 +1,57 @@
+---
+name: debug
+description: Structured debugging assistance when agent is stuck
+trigger: On repeated failure or explicit invocation
+agents: [developer, quality-gate]
+---
+
+# Debug Skill
+
+## Usage
+
+Invoke with `*debug` or `/debug` when stuck on an error after 2+ failed attempts.
+
+## Protocol
+
+### 1. Capture Context
+- Current error message (full stack trace)
+- What was attempted (last 2-3 actions)
+- Expected vs actual behavior
+- Relevant file paths and line numbers
+
+### 2. Classify Error
+| Category | Examples | First Action |
+|----------|----------|-------------|
+| Syntax | SyntaxError, unexpected token | Check recent edits for typos |
+| Type | TypeError, undefined is not | Trace variable origin, check types |
+| Runtime | ENOENT, ECONNREFUSED | Verify paths, ports, services |
+| Logic | Wrong output, infinite loop | Add logging, isolate with minimal repro |
+| Config | Module not found, env missing | Check package.json, .env, tsconfig |
+| Test | Assertion failed, timeout | Compare expected vs actual values |
+
+### 3. Investigate (max 5 minutes)
+1. Read the error source file at the failing line
+2. Check recent git diff for unintended changes
+3. Search codebase for similar patterns that work
+4. Check if dependency versions match (package.json vs lock)
+5. Verify environment (Node version, env vars)
+
+### 4. Fix or Escalate
+- If root cause found — apply fix, verify, continue
+- If unclear after 5 min — document findings, escalate to user
+- Never loop on the same approach more than twice
+
+## Anti-Patterns
+- Guessing without reading the actual error
+- Changing multiple things at once (isolate changes)
+- Ignoring stack traces (read bottom-up for root cause)
+- Retrying the exact same command expecting different results
+
+## Output
+```
+## Debug Report
+- Error: {error_type}: {message}
+- Root Cause: {explanation}
+- Fix Applied: {description of change}
+- Verified: {how it was confirmed working}
+```

package/.sinapse-ai/development/skills/deploy-readiness.md

@@ -0,0 +1,93 @@
+---
+name: deploy-readiness
+description: Automated deployment readiness check against 25 blockers
+trigger: Before any production deployment
+agents: [devops, quality-gate, developer]
+---
+
+# Deploy Readiness Skill
+
+## Usage
+
+Invoke with `*deploy-readiness` or `/deploy-readiness` before any production deploy.
+
+## Protocol
+
+Run all 25 deployment blockers from Constitution Article X. For each item, execute the automated check where possible or mark as MANUAL.
+
+### Tier 1: Absolute Blockers (10 items — deploy = impossible)
+
+| # | Blocker | Automated Check |
+|---|---------|-----------------|
+| 1 | Tables without RLS | `SELECT tablename FROM pg_tables WHERE schemaname='public' AND NOT rowsecurity` |
+| 2 | Hardcoded API keys | `grep -rn "sk-\|sk_live\|AKIA\|password\s*=" src/ app/ --include="*.{ts,js,tsx}"` |
+| 3 | service_role in frontend | `grep -rn "service_role" src/ app/ pages/ --include="*.{ts,js,tsx}"` |
+| 4 | No MFA on admin accounts | MANUAL — verify in cloud dashboard |
+| 5 | APIs without auth | MANUAL — review endpoint middleware |
+| 6 | SQL string concatenation | `grep -rn "query(\`.*\${" src/ --include="*.{ts,js}"` |
+| 7 | Critical/high vulns in deps | `npm audit --audit-level=high` |
+| 8 | Secrets in codebase | `git log --all -p -- "*.env" \| head -5` + grep patterns |
+| 9 | Default credentials | MANUAL — check for admin/admin, test/test |
+| 10 | No TLS | MANUAL — verify HTTPS enforcement |
+
+### Tier 2: Compliance Blockers (7 items — deploy = illegal in Brazil)
+
+| # | Blocker | Check |
+|---|---------|-------|
+| 11 | No DPO designated | MANUAL — organizational check |
+| 12 | No breach notification capability | MANUAL — process check |
+| 13 | No consent mechanism | Search for consent UI: `grep -rn "consent\|consentimento" src/` |
+| 14 | No data subject rights portal | Search for deletion endpoint: `grep -rn "delete.*account\|excluir" src/` |
+| 15 | International transfer without SCCs | MANUAL — review data flows |
+| 16 | Children's data without parental consent | MANUAL — if applicable |
+| 17 | No published privacy policy | Check for privacy route: `grep -rn "privacidade\|privacy" src/` |
+
+### Tier 3: Operational Blockers (8 items — deploy = irresponsible)
+
+| # | Blocker | Check |
+|---|---------|-------|
+| 18 | No asset inventory | MANUAL — documentation check |
+| 19 | No centralized logging | Search for logger: `grep -rn "winston\|pino\|logger" src/` |
+| 20 | No incident response plan | MANUAL — documentation check |
+| 21 | No backup verification (90 days) | MANUAL — ops check |
+| 22 | No vulnerability scanning | Check CI for scan step: `grep -rn "audit\|snyk\|trivy" .github/` |
+| 23 | No network segmentation | MANUAL — infra review |
+| 24 | No vendor security assessment | MANUAL — procurement check |
+| 25 | No SSL on database | MANUAL — verify DB connection string |
+
+## Execution
+
+1. Run all automated checks in parallel where possible
+2. Collect results into score card
+3. For MANUAL items: mark as UNCHECKED (requires human verification)
+
+## Output
+
+```
+## Deploy Readiness Report — {project} — {date}
+
+### Score: {passed}/{total_auto} automated | {manual_count} manual checks pending
+
+### Tier 1 — Absolute Blockers
+| # | Check | Status | Details |
+|---|-------|--------|---------|
+| 1 | RLS | PASS | All 12 tables have RLS |
+| 2 | API Keys | FAIL | Found sk- in config.ts:42 |
+
+### Tier 2 — Compliance (LGPD)
+...
+
+### Tier 3 — Operational
+...
+
+### Verdict: READY | BLOCKED | NEEDS_MANUAL_REVIEW
+- Blocking items: {list}
+- Manual items pending: {list}
+```
+
+## Rules
+- Any Tier 1 FAIL = BLOCKED, no override
+- Tier 2 FAIL = BLOCKED (legal requirement)
+- Tier 3 FAIL = WARN, deploy with documented risk acceptance
+- MANUAL items do NOT block but must be reviewed before launch
+- Reference: `.claude/rules/security-data-protection.md`

package/.sinapse-ai/development/skills/fast-review.md

@@ -0,0 +1,69 @@
+---
+name: fast-review
+description: Quick code review focused on common issues
+trigger: Before commit or on demand
+agents: [developer, quality-gate]
+---
+
+# Fast Review Skill
+
+## Usage
+
+Invoke with `*fast-review` or `/fast-review` before committing changes.
+
+## What It Checks
+
+### 1. Code Quality (auto)
+- Unused imports or variables
+- Console.log / debugger statements left in code
+- TODO/FIXME/HACK comments without ticket reference
+- Functions exceeding 50 lines
+- Files exceeding 300 lines
+
+### 2. TypeScript (auto)
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+### 3. Lint (auto)
+```bash
+npx eslint --quiet {changed_files} 2>&1 | head -30
+```
+
+### 4. Pattern Checks (read-only)
+- Relative imports (should be absolute per Constitution Art. VI)
+- `any` type usage (should use proper types)
+- Missing error handling in async functions
+- API calls without try/catch
+
+### 5. Test Coverage (if tests exist)
+- New functions should have corresponding tests
+- Modified functions — existing tests still pass
+
+## Execution
+
+1. Get changed files: `git diff --name-only --cached` (staged) or `git diff --name-only` (unstaged)
+2. Run checks 1-4 on changed files only
+3. Summarize findings
+
+## Output Format
+
+```
+## Fast Review — {n} files checked
+
+| Category | Issues | Severity |
+|----------|--------|----------|
+| Quality | 2 console.logs | LOW |
+| TypeScript | 0 errors | - |
+| Lint | 1 warning | LOW |
+| Patterns | 1 relative import | MEDIUM |
+
+Verdict: CLEAN | MINOR_ISSUES | NEEDS_FIX
+```
+
+## Rules
+- CLEAN = no issues found, safe to commit
+- MINOR_ISSUES = proceed but consider fixing (LOW severity only)
+- NEEDS_FIX = MEDIUM+ issues must be resolved before commit
+- This is lighter than full CodeRabbit — use for quick iterations
+- For PR-level review, use CodeRabbit instead

package/.sinapse-ai/development/skills/model-router.md

@@ -0,0 +1,92 @@
+---
+name: model-router
+description: Decide which model to use for sub-agent tasks
+trigger: When spawning sub-agents or deciding task complexity
+agents: [developer, quality-gate, architect, analyst]
+---
+
+# Model Router Skill
+
+## Usage
+
+Invoke with `*model-router` or `/model-router` to determine the optimal model for a sub-agent task. Can also be used as internal guidance when orchestrating multi-agent workflows.
+
+## Decision Tree
+
+```
+Task received
+├── Can be done WITHOUT sub-agent? (file read, grep, simple command)
+│   └── YES → Do it directly. No sub-agent needed.
+│       Cost: $0 additional. Fastest path.
+│
+└── Needs sub-agent?
+    ├── Routine / mechanical work?
+    │   └── YES → model: "haiku"
+    │
+    ├── Standard implementation / analysis?
+    │   └── YES → model: "sonnet"
+    │
+    └── Complex reasoning / architecture?
+        └── YES → model: "opus" (default)
+```
+
+## Model Selection Matrix
+
+### No Sub-Agent (direct execution)
+| Task | Why |
+|------|-----|
+| Read a file | Native tool, instant |
+| Grep for pattern | Native tool, instant |
+| Run a test | Single bash command |
+| Check git status | Single bash command |
+| Simple file edit | Native tool, instant |
+
+### Haiku (fast, cheap — routine work)
+| Task | Why |
+|------|-----|
+| Lint check on file list | Mechanical, no judgment |
+| Format code | Pattern-based, deterministic |
+| Generate boilerplate | Template-driven |
+| Parse and extract data | Structural, low ambiguity |
+| Rename variables | Find-and-replace logic |
+| Validate JSON/YAML syntax | Structural validation |
+| Run checklist items | Binary pass/fail |
+
+### Sonnet (balanced — standard work)
+| Task | Why |
+|------|-----|
+| Implement a function from spec | Needs understanding but well-scoped |
+| Write unit tests | Requires code comprehension |
+| Code review (non-architectural) | Pattern recognition + judgment |
+| Bug fix with known root cause | Targeted reasoning |
+| Documentation from code | Comprehension + writing |
+| Refactor within a file | Understanding + transformation |
+| Story creation from brief | Structured writing |
+
+### Opus (full power — complex reasoning)
+| Task | Why |
+|------|-----|
+| Architecture decisions | Multi-dimensional tradeoffs |
+| Complex debugging (unknown cause) | Deep reasoning required |
+| Cross-system integration | Multiple context domains |
+| Security audit | Nuanced threat modeling |
+| Spec critique / validation | Judgment under uncertainty |
+| Multi-file refactoring | System-wide understanding |
+| Novel problem solving | No established pattern to follow |
+
+## Rules
+- Default to direct execution when possible (cost: $0, speed: instant)
+- When in doubt between tiers, pick the LOWER one first — escalate if poor results
+- Never use Opus for tasks Haiku can handle
+- Log model selection rationale for cost tracking
+- Sub-agent model is set via `model:` parameter in Task tool
+
+## Output
+
+```
+## Model Router Decision
+- Task: {description}
+- Classification: {routine|standard|complex|direct}
+- Model: {haiku|sonnet|opus|none}
+- Rationale: {one-line reason}
+```

package/.sinapse-ai/development/skills/research-synthesis.md

@@ -0,0 +1,77 @@
+---
+name: research-synthesis
+description: Synthesize findings from multiple sources into actionable summary
+trigger: After research phase or on demand
+agents: [analyst, architect, project-lead]
+---
+
+# Research Synthesis Skill
+
+## Usage
+
+Invoke with `*research-synthesis` or `/research-synthesis` after gathering research data.
+
+## Input
+
+Accepts any combination of:
+- Web search results (from EXA or manual search)
+- Documentation excerpts
+- Code analysis findings
+- Competitor analysis data
+- File paths containing raw research
+
+## Protocol
+
+### 1. Collect
+- Gather all source materials (files, search results, notes)
+- Tag each source with origin and confidence level
+
+### 2. Deduplicate
+- Remove redundant findings across sources
+- Keep the most authoritative version of each fact
+
+### 3. Categorize
+| Category | Description |
+|----------|-------------|
+| Facts | Verified, multiple sources agree |
+| Insights | Patterns or conclusions derived from facts |
+| Risks | Potential problems or concerns identified |
+| Opportunities | Actionable improvements or options |
+| Unknowns | Questions that remain unanswered |
+
+### 4. Synthesize
+- Cross-reference findings for consistency
+- Identify contradictions between sources
+- Rank by relevance to the current objective
+
+### 5. Output
+
+```
+## Research Synthesis — {topic}
+
+### Key Findings
+1. {finding with source reference}
+2. {finding with source reference}
+
+### Recommendations
+- {actionable recommendation}
+
+### Risks
+- {risk with mitigation suggestion}
+
+### Open Questions
+- {question needing further investigation}
+
+### Sources
+| # | Source | Confidence |
+|---|--------|------------|
+| 1 | {url or file} | HIGH |
+| 2 | {url or file} | MEDIUM |
+```
+
+## Rules
+- Every finding must reference its source
+- Confidence levels: HIGH (multiple sources), MEDIUM (single reliable), LOW (unverified)
+- Contradictions must be explicitly called out, not silently resolved
+- Keep synthesis under 500 words — link to raw data for details
+- Save output to `docs/research/` if part of a formal research task

package/.sinapse-ai/development/skills/security-scan.md

@@ -0,0 +1,73 @@
+---
+name: security-scan
+description: Run security checks from the 25 deployment blockers
+trigger: Before deploy, on demand, or during QA gate
+agents: [developer, quality-gate, devops]
+---
+
+# Security Scan Skill
+
+## Usage
+
+Invoke with `*security-scan` or `/security-scan` before any deployment.
+
+## Automated Checks (Tier 1 — Absolute Blockers)
+
+Run these checks in order. Any failure = BLOCKED.
+
+### 1. Secrets in Code
+```bash
+# Check for hardcoded keys, tokens, passwords
+grep -rn "sk-\|sk_live\|password\s*=\s*['\"]" src/ app/ pages/ --include="*.ts" --include="*.js" --include="*.tsx"
+# Check for service_role in frontend
+grep -rn "service_role" src/ app/ pages/ --include="*.ts" --include="*.js"
+```
+
+### 2. Dependencies
+```bash
+npm audit --audit-level=high
+```
+
+### 3. Environment Files
+```bash
+# Verify .env is gitignored
+git check-ignore .env
+# Verify .env.example exists (if .env exists)
+test -f .env.example
+```
+
+### 4. SQL Safety
+- Scan for string concatenation in SQL queries
+- Verify parameterized queries or ORM usage
+
+### 5. RLS Check (if Supabase project)
+- Verify all user-data tables have RLS enabled
+- Check for policies on each RLS-enabled table
+
+## Quick Scan vs Full Scan
+
+| Mode | Checks | When |
+|------|--------|------|
+| Quick (`*security-scan quick`) | 1-3 only | Before every commit |
+| Full (`*security-scan full`) | All 1-5 + CORS + headers | Before deploy |
+
+## Output Format
+
+```
+## Security Scan — {timestamp}
+
+| Check | Status | Details |
+|-------|--------|---------|
+| Secrets | PASS | No hardcoded secrets found |
+| Deps | WARN | 2 moderate vulnerabilities |
+| Env | PASS | .env gitignored, .env.example present |
+| SQL | PASS | All queries parameterized |
+| RLS | N/A | No Supabase detected |
+
+Verdict: PASS | WARN | BLOCKED
+```
+
+## Rules
+- BLOCKED verdict prevents deploy — no override without user confirmation
+- WARN allows deploy but must be documented as tech debt
+- Reference: Constitution Article X, `.claude/rules/security-data-protection.md`

package/.sinapse-ai/development/skills/sinapse-methodology.md

@@ -0,0 +1,175 @@
+---
+name: sinapse-methodology
+description: Complete SINAPSE AI development methodology in one self-contained skill
+trigger: When teaching SINAPSE methodology to any AI tool or new team member
+agents: [analyst, architect, developer, sprint-lead, product-lead]
+---
+
+# SINAPSE Methodology
+
+A complete AI-orchestrated development methodology. Self-contained — works in any project, any AI tool.
+
+## 1. Core Philosophy
+
+**CLI First. Observability Second. UI Third.**
+
+All intelligence lives in the CLI. Dashboards observe, never control. UI is optional. Every feature must work 100% via CLI before any UI exists.
+
+## 2. Constitution (10 Articles)
+
+Non-negotiable principles that govern all work:
+
+| # | Article | Severity | Summary |
+|---|---------|----------|---------|
+| I | CLI First | NON-NEGOTIABLE | CLI is the source of truth |
+| II | Agent Authority | NON-NEGOTIABLE | Each agent has exclusive operations |
+| III | Documentation-First | NON-NEGOTIABLE | Story before code, always |
+| IV | No Invention | MUST | Every spec traces to a requirement |
+| V | Quality First | MUST | Quality gates cannot be bypassed |
+| VI | Absolute Imports | SHOULD | No relative imports in codebase |
+| VII | Ecosystem Metrics | NON-NEGOTIABLE | Metrics must reflect reality |
+| VIII | Mandatory Delegation | NON-NEGOTIABLE | Orchestrators never do domain work |
+| IX | Safe Collaboration | NON-NEGOTIABLE | Git safety net for non-git-experts |
+| X | Security & Data | NON-NEGOTIABLE | 25 deployment blockers enforced |
+
+## 3. Agent System
+
+Specialized agents with exclusive authority domains:
+
+### Development Agents
+
+| Agent | Role | Exclusive Operations |
+|-------|------|---------------------|
+| Sprint Lead | Scrum Master | Story creation |
+| Product Lead | Product Owner | Story validation |
+| Developer | Implementation | Code, local git |
+| Quality Gate | QA | Quality checks, verdicts |
+| Architect | Design authority | Architecture decisions |
+| Data Engineer | Database | Schema, RLS, migrations |
+| DevOps | Deployment | git push, PR, CI/CD (EXCLUSIVE) |
+| Analyst | Research | Research, analysis |
+| Project Lead | PM | Epic orchestration |
+
+### Key Rule: Mandatory Delegation
+Orchestrators NEVER execute domain work. They absorb, diagnose, delegate, coordinate. Even if explicitly asked to "just do it," they delegate to the specialist.
+
+## 4. Story Development Cycle (SDC)
+
+The primary workflow for all development:
+
+```
+Phase 1: CREATE (Sprint Lead)
+  Input: Epic/PRD
+  Output: Story file with AC, scope, dependencies
+  Status: Draft
+
+Phase 2: VALIDATE (Product Lead)
+  10-point checklist (title, AC, scope, deps, complexity, value, risks, DoD, alignment)
+  Decision: GO (>=7/10) or NO-GO
+  Status: Draft -> Ready
+
+Phase 3: IMPLEMENT (Developer)
+  Modes: YOLO (autonomous) | Interactive | Pre-Flight (plan-first)
+  Self-healing code review (max 2 iterations)
+  Status: Ready -> InProgress
+
+Phase 4: QA GATE (Quality Gate)
+  7 checks: code review, tests, AC met, no regressions, perf, security, docs
+  Verdict: PASS | CONCERNS | FAIL | WAIVED
+  Status: InProgress -> InReview -> Done
+```
+
+**Golden Rule:** No code without a validated story. No exceptions.
+
+## 5. Quality Gates
+
+### Pre-Commit
+- Secrets scan (API keys, tokens, passwords)
+- Lint + typecheck
+- Fast review (unused imports, console.logs, patterns)
+
+### Pre-Merge (QA Loop)
+- Automated review with self-healing (max 5 iterations)
+- Verdicts: APPROVE, REJECT (fix + re-review), BLOCKED (escalate)
+
+### Pre-Deploy (25 Blockers)
+- Tier 1: 10 absolute blockers (RLS, secrets, auth, SQL injection, deps)
+- Tier 2: 7 compliance blockers (LGPD/Brazil)
+- Tier 3: 8 operational blockers (logging, backups, incident response)
+
+## 6. Safe Collaboration Protocol
+
+For teams where members are product builders, not git experts:
+
+1. **Auto-branch** — Never work on main. Create feature branch automatically.
+2. **Auto-sync** — git fetch + pull at session start. Always.
+3. **Auto-resolve** — Simple conflicts resolved by agent, complex ones shown to user.
+4. **Auto-PR** — PR created with reviewer assignment after push.
+5. **Secret scan** — Every commit checked for secrets. Blocked if found.
+
+Users never touch git. They focus on WHAT to build. Agents handle HOW to save it.
+
+## 7. Incremental Development (IDS)
+
+Decision hierarchy for every new artifact:
+
+```
+REUSE (>=90% match) > ADAPT (60-89% match, <30% changes) > CREATE (justify)
+```
+
+Creating something new requires: evaluated patterns, rejection reasons, unique capability justification, and registry entry within 24 hours.
+
+## 8. Security by Default
+
+Security is not a feature — it is the foundation. From day one:
+
+- RLS on every table with user data
+- Parameterized queries only (no SQL concatenation)
+- service_role never in frontend
+- Rate limiting on all public APIs
+- Input validation with schema (Zod)
+- CORS restricted to known origins
+- MFA on all admin accounts
+
+## 9. Framework Boundary Model
+
+4 layers with clear mutability rules:
+
+| Layer | Mutability | Example |
+|-------|-----------|---------|
+| L1 Core | NEVER | Constitution, orchestration engine |
+| L2 Templates | NEVER (extend only) | Tasks, templates, checklists |
+| L3 Config | Mutable (guarded) | Knowledge base, agent memory |
+| L4 Runtime | ALWAYS | Stories, packages, tests |
+
+## 10. Workflow Selection
+
+| Situation | Workflow |
+|-----------|---------|
+| New feature from epic | Story Development Cycle |
+| QA found issues | QA Loop (max 5 iterations) |
+| Complex feature needs spec | Spec Pipeline then SDC |
+| Joining existing project | Brownfield Discovery (10-phase) |
+| Trivial bug fix | SDC with fast-track |
+
+## 11. Communication Principles
+
+- Explain simply. "Saved your work" not "committed to HEAD."
+- Never assume git knowledge from users.
+- Always confirm before destructive operations.
+- Document every decision for future context.
+- Every finding references its source.
+
+## 12. Applying to Any Project
+
+To use SINAPSE methodology in a new project:
+
+1. Define agents and their exclusive authorities
+2. Enforce documentation-first (story before code)
+3. Set up quality gates (pre-commit, pre-merge, pre-deploy)
+4. Use the SDC workflow for all development
+5. Apply REUSE > ADAPT > CREATE for every artifact
+6. Implement safe collaboration for non-git-expert teams
+7. Security from commit one, not "later"
+
+This methodology scales from solo developers to multi-agent AI orchestration systems. The principles remain the same regardless of team size or tooling.