sinapse-ai 1.26.0 → 1.27.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (10) hide show
  1. package/.sinapse-ai/install-manifest.yaml +1 -1
  2. package/CHANGELOG.md +5 -5
  3. package/README.en.md +98 -411
  4. package/README.md +99 -458
  5. package/bin/commands/install.js +29 -9
  6. package/bin/commands/update.js +6 -4
  7. package/bin/lib/detection.js +1 -1
  8. package/bin/lib/prompts.js +9 -9
  9. package/docs/getting-started.md +2 -2
  10. package/package.json +1 -1
package/.sinapse-ai/install-manifest.yaml CHANGED
@@ -7,7 +7,7 @@
7
7
  # - SHA256 hashes for change detection
8
8
  # - File types for categorization
9
9
  #
10
- version: 1.26.0
10
+ version: 1.27.0
11
11
  generator: scripts/generate-install-manifest.js
12
12
  file_count: 1156
13
13
  files:
package/CHANGELOG.md CHANGED
@@ -1,17 +1,17 @@
1
- ## [1.26.0](https://github.com/caioimori/sinapse-ai/compare/1.25.3...1.26.0) (2026-07-15)
1
+ ## [1.27.0](https://github.com/caioimori/sinapse-ai/compare/1.26.0...1.27.0) (2026-07-16)
2
2
 
3
3
  ### Features
4
4
 
5
- * deliver React Bits across providers [Story react-bits-distribution-parity] ([aa191f1](https://github.com/caioimori/sinapse-ai/commit/aa191f102dc417e3a0182c02661907e474226abb))
5
+ * default install to both providers [Story canonical-install-readme] ([6ba3df1](https://github.com/caioimori/sinapse-ai/commit/6ba3df13dd43c8103bd601758a1f2e96a87738c3))
6
6
 
7
7
  ### Bug Fixes
8
8
 
9
- * **docs:** align provider skill metrics [Story react-bits-distribution-parity] ([729d120](https://github.com/caioimori/sinapse-ai/commit/729d120ee1735473d01971efdb746be59d2d19d8))
10
- * **react-bits:** harden corpus delivery and orchestration [Story react-bits-distribution-parity] ([6456062](https://github.com/caioimori/sinapse-ai/commit/6456062cd756826e6bc14c698ebde07298d8a5eb))
9
+ * address canonical install review [Story canonical-install-readme] ([191fdc4](https://github.com/caioimori/sinapse-ai/commit/191fdc43aee9e6525dfd636118087eaa311d4709))
11
10
 
12
11
  ### Documentation
13
12
 
14
- * close installer parity release evidence [Story hotfix-installer-provider-adapter-parity-1.25.3] ([#386](https://github.com/caioimori/sinapse-ai/issues/386)) ([ceafcb8](https://github.com/caioimori/sinapse-ai/commit/ceafcb8ac522835c264115e9ee16cba6e49e173c))
13
+ * recommend supported Node LTS [Story canonical-install-readme] ([693e9d0](https://github.com/caioimori/sinapse-ai/commit/693e9d0f9819cd700eae45734da41b055063fa5b))
14
+ * record React Bits release evidence [Story react-bits-distribution-parity] ([6dff59a](https://github.com/caioimori/sinapse-ai/commit/6dff59ab779d79437e8e09a07c5cf3a9ae8e024c))
15
15
 
16
16
  # Changelog
17
17
 
package/README.en.md CHANGED
@@ -1,464 +1,151 @@
1
- [![npm version](https://img.shields.io/npm/v/sinapse-ai.svg)](https://www.npmjs.com/package/sinapse-ai)
2
- [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
3
- [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org/)
4
- [![CI](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml/badge.svg)](https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml)
1
+ <p align="center">
2
+ <a href="https://www.npmjs.com/package/sinapse-ai"><img src="https://img.shields.io/npm/v/sinapse-ai?color=00B894&label=npm" alt="npm version"></a>
3
+ <a href="https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml"><img src="https://github.com/caioimori/sinapse-ai/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
4
+ <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-0EA5E9.svg" alt="MIT license"></a>
5
+ <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D18-22C55E.svg" alt="Node 18 or newer"></a>
6
+ </p>
5
7
 
6
- ```
7
- ____ ___ _ _ _ ____ ____ _____
8
- / ___|/ _ \ \ | | / \ | _ \/ ___|| ____|
9
- \___ \ | | | \| | / _ \ | |_) \___ \| _|
10
- ___) | |_| | |\ |/ ___ \| __/ ___) | |___
11
- |____/ \___/|_| \_/_/ \_\_| |____/|_____|
12
- ```
13
-
14
- > **AI squads that build with you, not for you.**
8
+ <h1 align="center">SINAPSE AI</h1>
15
9
 
16
- [English] | [**Portugues**](README.md)
17
-
18
- ---
10
+ <p align="center"><strong>A governed AI team for Claude Code and Codex.</strong></p>
19
11
 
20
- ## What is SINAPSE?
12
+ <p align="center">
13
+ 17 squads · 172 agents · 1,412 task files · 1,348 resolvable pointers
14
+ </p>
21
15
 
22
- SINAPSE is an open-source meta-framework that organizes **172 AI agents into 17 specialized squads**, operating directly in the terminal via Claude Code or Codex CLI. Each agent has a defined role, each squad masters a discipline, and the entire system is governed by a **Constitution with real enforcement** -- 20 registered Claude Code hooks and 9 Codex lifecycle events through the compatibility bridge.
23
-
24
- The core concept is simple: instead of a single AI assistant trying to do everything, SINAPSE structures work into specialized teams. A branding squad handles visual identity. A cybersecurity squad handles compliance and pentesting. A copywriting squad handles persuasion and conversion. The runtime measures **1,412 task files**: **1,201 squad tasks** and **211 development tasks**. Of those files, **1,348 pointers are resolvable** by real agents.
25
-
26
- Unlike tools that just chat with AI, SINAPSE enforces discipline. The **Documentation-First** pipeline requires a story to be created and validated before any code is written. Quality gates run automatically before merge. Unauthorized agents are blocked from pushing. All via hooks that intercept operations in real time -- not after the fact.
16
+ <p align="center"><a href="README.md">Portugues</a> · <a href="docs/getting-started.md">Documentation</a> · <a href="https://www.npmjs.com/package/sinapse-ai">npm</a> · <a href="https://github.com/caioimori/sinapse-ai/issues">Issues</a></p>
27
17
 
28
18
  ---
29
19
 
30
- ## Why does SINAPSE exist?
31
-
32
- Generative AI has a known problem: the more you ask of it, the worse it gets. A single assistant trying to do everything -- code, copy, branding, testing, deployment -- loses context, invents features, and suffers from context amnesia after just a few long iterations.
33
-
34
- SINAPSE solves this the way human teams solve it: **coordinated specialization**. Instead of one tired generalist, you have 172 agents in 17 squads, each with a defined role, its own knowledge base, and executable tasks. An orchestrator routes your request to whoever actually knows how to solve it -- automatically, without you needing to memorize agent names or commands.
35
-
36
- The differential isn't just the quantity of agents. It's **real governance**: 20 Claude Code hook registrations and 9 Codex lifecycle events intercept operations at runtime, a Constitution with 11 articles governs the framework, and 7 of those articles are NON-NEGOTIABLE -- violations are blocked before execution, not detected afterwards. **Speed with rigor, without choosing between the two.**
37
-
38
- ---
39
-
40
- ## Quick Start
41
-
42
- ### 1. Install
43
-
44
- ```bash
45
- npx sinapse-ai install
46
- ```
47
-
48
- The wizard detects your environment, configures your IDE, and installs squads automatically.
49
-
50
- ### 2. Verify
51
-
52
- ```bash
53
- npx sinapse-ai doctor
54
- ```
55
-
56
- ### 3. Activate your first agent
57
-
58
- Claude Code:
59
-
60
20
  ```text
61
- @developer
62
- *help
21
+ S I N A P S E
22
+ specialized work, one governed system
63
23
  ```
64
24
 
65
- Codex:
66
-
67
- ```text
68
- $snps
69
- $sinapse-agent developer
70
- ```
71
-
72
- Done. You have 17 squads operating in your terminal.
73
-
74
- ---
75
-
76
- ## Why install in every project?
77
-
78
- Every first installation raises objections. All of them legitimate. Answered here, in the spirit of SINAPSE culture -- direct, no defensiveness.
25
+ SINAPSE organizes product, engineering, design, growth, security, and operations
26
+ work through coordinated specialists. It does not replace your LLM: it installs
27
+ the agent, skill, rule, and quality-gate layer that makes Claude Code and Codex
28
+ consistent inside a project.
79
29
 
80
- ### "I'll have multiple copies on my computer. Isn't that wasteful?"
30
+ ## Start with one command
81
31
 
82
- No. Each project has its own `.sinapse-ai/` -- just like it has its own `package.json` or `node_modules/`. And this **isn't waste, it's isolation**.
83
-
84
- Real footprint: `.sinapse-ai/` weighs ~500KB. Twenty projects = 10MB. Smaller than a single `node_modules/` of a typical Next.js project (300MB+). The disk cost is marginal. The isolation gain is essential.
85
-
86
- ### "Why not install once globally and be done with it?"
87
-
88
- Because open source projects need to be **self-contained**. When you share a project (or someone clones yours), the framework needs to travel with it.
89
-
90
- **With local installation:** `git clone` and you're done. Framework, rules, agents, Constitution, context -- everything comes with the project. Any person, any machine, any time: it works the same.
91
-
92
- **With global installation:** whoever clones the project has to install SINAPSE separately, ensure the same version, copy rules manually, and pray there's no drift between machines. Open source dies like that.
93
-
94
- ### "What's the actual difference between global and local?"
95
-
96
- | Aspect | Global | Local (recommended) |
97
- |--------|:------:|:-------------------:|
98
- | Disk space | Smaller (1 copy) | Larger (~500KB/project) |
99
- | Per-project versioning | No | Yes |
100
- | Clone = working | No | Yes |
101
- | Project-specific custom rules | No | Yes |
102
- | Team collaboration | Broken | Perfect |
103
- | Update without breaking other projects | No | Yes |
104
- | Open source compatible | No | Yes |
105
-
106
- ### "Does it work on Windows?"
107
-
108
- Yes. Tested on Windows 11, macOS, and Linux. The installer detects the OS automatically. WSL is not required (but recommended for advanced features like automated CodeRabbit review).
109
-
110
- ### "How do I update without losing my customizations?"
32
+ From your project directory, run:
111
33
 
112
34
  ```bash
113
- npx sinapse-ai update
35
+ npx sinapse-ai@latest install
114
36
  ```
115
37
 
116
- The update is **idempotent by design**. L1 (framework core) and L2 (templates) get updated. L3 (configuration) and L4 (your stories, packages, customizations) **are never touched**. You can run `update` as many times as you want, including after customizing rules locally. Nothing is lost.
117
-
118
- ### TL;DR
119
-
120
- Local installation = a bit more disk, much more robustness.
121
-
122
- If you work alone and never share projects, global will technically work -- but the moment you join a team, publish open source, or need multiple versions in parallel, local becomes essential.
123
-
124
- SINAPSE optimizes for the generic case: **your project should work for anyone who clones it, on any machine, at any time**.
125
-
126
- ---
127
-
128
- ## Architecture
38
+ This is the canonical path for fresh or unconfigured projects. With no flags,
39
+ it configures **Claude Code and Codex**. Re-runs preserve the saved provider
40
+ and project-owned content. To intentionally install one provider only, use
41
+ `--llm=claude-code` or `--llm=codex`; use `--reconfigure` to change an existing selection.
129
42
 
130
- ### CLI First
131
-
132
- ```
133
- CLI First > Observability Second > UI Third
134
- ```
135
-
136
- All intelligence lives in the terminal. Dashboards observe. The UI is never required to operate the system. This is Article I of the Constitution -- non-negotiable.
137
-
138
- ### 4-Layer Model
139
-
140
- SINAPSE separates framework and project artifacts into 4 layers with automatic protection:
141
-
142
- ```mermaid
143
- graph TB
144
- subgraph L4["L4 - PROJECT (always mutable)"]
145
- L4A[Stories]
146
- L4B[Packages]
147
- L4C[Squads]
148
- L4D[Tests]
149
- end
150
- subgraph L3["L3 - CONFIGURATION (restricted)"]
151
- L3A[Entity Registry]
152
- L3B[Agent Memory]
153
- L3C[Config files]
154
- end
155
- subgraph L2["L2 - TEMPLATES (immutable)"]
156
- L2A[Tasks]
157
- L2B[Templates]
158
- L2C[Checklists]
159
- L2D[Workflows]
160
- end
161
- subgraph L1["L1 - FRAMEWORK CORE (immutable)"]
162
- L1A[.sinapse-ai/core]
163
- L1B[bin/]
164
- L1C[Constitution]
165
- end
166
-
167
- L1 --> L2 --> L3 --> L4
168
-
169
- style L1 fill:#0f172a,stroke:#ef4444,color:#fff
170
- style L2 fill:#1e293b,stroke:#f59e0b,color:#fff
171
- style L3 fill:#1e293b,stroke:#8b5cf6,color:#fff
172
- style L4 fill:#1e293b,stroke:#10b981,color:#fff
43
+ ```text
44
+ install -> native agents and skills -> rules and hooks -> ready project
173
45
  ```
174
46
 
175
- | Layer | Mutability | Content |
176
- |-------|-----------|---------|
177
- | **L1** Framework Core | Never | `.sinapse-ai/core/`, `bin/`, Constitution |
178
- | **L2** Templates | Never | Tasks, templates, checklists, workflows |
179
- | **L3** Configuration | Restricted | Entity registry, agent memory, config |
180
- | **L4** Project | Always | Stories, packages, squads, tests |
181
-
182
- Deny rules in `.claude/settings.json` enforce this deterministically. **Framework updates touch L1+L2, never L3+L4** — your customizations are preserved.
183
-
184
- ### Constitution
185
-
186
- SINAPSE is governed by a formal Constitution with 11 articles and provider-specific enforcement surfaces: 20 Claude Code hook registrations and 9 Codex lifecycle events.
187
-
188
- | Article | Principle | Severity |
189
- |---------|-----------|----------|
190
- | I | CLI First | NON-NEGOTIABLE |
191
- | II | Agent Authority | NON-NEGOTIABLE |
192
- | III | Documentation-First Development | NON-NEGOTIABLE |
193
- | IV | No Invention | MUST |
194
- | V | Quality First | MUST |
195
- | VI | Absolute Imports | SHOULD |
196
- | VII | Ecosystem Metrics Accuracy | NON-NEGOTIABLE |
197
- | VIII | Mandatory Delegation | NON-NEGOTIABLE |
198
- | IX | Safe Collaboration | NON-NEGOTIABLE |
199
- | X | Security & Data Protection | NON-NEGOTIABLE |
200
- | XI | Conservative Default | MUST |
201
-
202
- 7 articles are NON-NEGOTIABLE -- violations are automatically blocked before execution.
203
-
204
- ---
205
-
206
- ## Agent System
47
+ | After installation | Claude Code | Codex |
48
+ |---|---|---|
49
+ | Orchestrator | `@sinapse-orqx` | `$snps` |
50
+ | Specialist | `@developer` | `$sinapse-agent developer` |
51
+ | Reconfigure providers | `npx sinapse-ai@latest install --reconfigure` | same command |
207
52
 
208
- SINAPSE includes 12 core agents covering the complete development cycle:
53
+ ## What ships with the project
209
54
 
210
- | Agent | Persona | Role |
211
- |-------|---------|------|
212
- | `sinapse-orqx` | **Imperator** | Master orchestrator -- routing and cross-squad coordination |
213
- | `developer` | **Pixel** | Code implementation and story development |
214
- | `quality-gate` | **Litmus** | Testing, QA, and quality gates |
215
- | `architect` | **Stratum** | Architecture and technology decisions |
216
- | `project-lead` | **Beacon** | Product management and epics |
217
- | `product-lead` | **Axis** | Story validation and prioritization |
218
- | `sprint-lead` | **Sync** | Story creation and sprints |
219
- | `analyst` | **Scope** | Business research and analysis |
220
- | `data-engineer` | **Tensor** | Database design, migrations, and RLS |
221
- | `ux-design-expert` | **Mosaic** | UX/UI design |
222
- | `devops` | **Pipeline** | CI/CD, git push (exclusive), releases |
223
- | `squad-creator` | **Loom** | New squad creation |
55
+ | Surface | Claude Code | Codex |
56
+ |---|:---:|:---:|
57
+ | Canonical agents | 172 | 172 |
58
+ | Installed skills | 37 | 37 |
59
+ | Registered hooks | 20 native registrations | 9 lifecycle events |
60
+ | React Bits | Skill plus 9-file corpus | Skill plus 9-file corpus |
224
61
 
225
- In Claude Code, activate an agent with `@agent-name` and use `*help` to see its commands. In Codex, start with `$snps` for routing or use `$sinapse-agent agent-id` for direct activation.
62
+ The catalog contains 17 squads and 172 specialized agents. The runtime measures
63
+ 1,201 squad tasks, 211 development tasks, 1,412 task files, and 1,348 pointers resolvable
64
+ at runtime. React Bits is included as a frontend capability with a searchable
65
+ snapshot of 139 components and performance, accessibility, and reduced-motion
66
+ guidance.
226
67
 
227
- ### Development Workflow
68
+ ## How work flows
228
69
 
229
70
  ```mermaid
230
71
  flowchart LR
231
- A([User briefing]) --> B[sprint-lead<br/>creates story]
232
- B --> C{product-lead<br/>validates}
233
- C -->|GO| D[developer<br/>implements]
234
- C -->|NO-GO| B
235
- D --> E{quality-gate<br/>tests}
236
- E -->|PASS| F[devops<br/>push + PR]
237
- E -->|FAIL| D
238
- F --> G([Merged to main])
239
-
240
- style B fill:#1e293b,stroke:#3b82f6,color:#fff
241
- style C fill:#1e293b,stroke:#8b5cf6,color:#fff
242
- style D fill:#1e293b,stroke:#10b981,color:#fff
243
- style E fill:#1e293b,stroke:#f59e0b,color:#fff
244
- style F fill:#1e293b,stroke:#ef4444,color:#fff
245
- ```
246
-
247
- The framework ensures no step is skipped. Each gate blocks automatically if the previous one wasn't fulfilled.
248
-
249
- ---
250
-
251
- ## 17 Specialized Squads
252
-
253
- Each squad is an autonomous team with its own orchestrator, specialist agents, knowledge base, tasks, and workflows.
254
-
255
- | Squad | Domain | Agents |
256
- |-------|--------|--------|
257
- | **squad-brand** | Brand strategy, archetypes, visual audit | 15 |
258
- | **squad-design** | Design systems, components, tokens, UI, art direction, premium LP | 14 |
259
- | **squad-copy** | Persuasive copywriting, headlines, conversion | 13 |
260
- | **squad-council** | Strategic advisors (Munger, Dalio, Thiel, ...) | 11 |
261
- | **squad-storytelling** | Narrative, scripts, story frameworks | 10 |
262
- | **squad-commercial** | Sales, funnel, revenue, commercial pipeline | 10 |
263
- | **squad-paidmedia** | Meta Ads, Google Ads, campaigns, optimization | 9 |
264
- | **squad-animations** | Motion design, CSS, particles, 3D | 9 |
265
- | **squad-cloning** | Cognitive cloning, mind synthesis, digital twins | 9 |
266
- | **squad-cybersecurity** | Threat intel, pentest, compliance, LGPD | 8 |
267
- | **squad-courses** | Courses, curricula, assessments, educational launch | 8 |
268
- | **squad-research** | Market analysis, competitive intelligence | 7 |
269
- | **claude-code-mastery** | Advanced Claude Code, MCP, deep integration | 8 |
270
- | **squad-content** | Editorial governance, content strategy | 7 |
271
- | **squad-product** | Product discovery, strategy, operations | 7 |
272
- | **squad-growth** | Analytics, CRO, SEO, growth hacking | 7 |
273
- | **squad-finance** | Budget, pricing, profitability analysis | 8 |
274
-
275
- **Total: 17 squads, 172 specialized agents, and 1,412 task files** (**1,201 squad tasks + 211 development tasks; 1,348 resolvable pointers**)
276
-
277
- Activate any squad via its orchestrator using the provider-native syntax:
278
-
279
- ```text
280
- # Claude Code
281
- @brand-orqx # Brand squad
282
- @copy-orqx # Copy squad
283
-
284
- # Codex
285
- $sinapse-agent brand-orqx
286
- $sinapse-agent copy-orqx
287
- $snps # Route through the primary orchestrator
72
+ A[Brief] --> B[Orchestrator]
73
+ B --> C[Specialist]
74
+ C --> D[Ready story]
75
+ D --> E[Implementation]
76
+ E --> F[QA and gates]
77
+ F --> G[Delivery]
288
78
  ```
289
79
 
290
- The orchestrator receives your request and automatically delegates to the right specialist within the squad.
80
+ The framework applies an 11-article Constitution: documentation before code,
81
+ clear authority per agent, security, quality, and safe collaboration. The
82
+ orchestrator routes, specialists execute, and the process leaves evidence.
291
83
 
292
- ---
293
-
294
- ## IDE Support
295
-
296
- SINAPSE supports two IDEs with deep integrations:
297
-
298
- | IDE | Activation | Highlights |
299
- |-----|------------|------------|
300
- | **Claude Code** | `@agent-name` | Hooks, contextual rules, deny/allow, Chrome Brain |
301
- | **Codex CLI** | `$snps` or `$sinapse-agent agent-id` | Native skills, multi-model, `codex exec` for CI/CD |
302
-
303
- Both IDEs have access to all 17 squads, 172 agents, workflows, and knowledge bases. The installer detects and configures automatically.
304
-
305
- ### Parity Table
306
-
307
- | Measured surface | Claude Code | Codex CLI |
308
- |------------------|:-----------:|:---------:|
309
- | Native agents | 172 | 172 |
310
- | Direct activation | `@agent-name` | `$sinapse-agent agent-id` |
311
- | Primary routing | `@sinapse-orqx` | `$snps` |
312
- | Installed skills | 37 | 37 |
313
- | Registered hooks | 20 native registrations | 9 lifecycle events through the bridge |
314
- | Validation source | `npm run validate:providers` | `npm run validate:codex-native` |
84
+ ## Essential commands
315
85
 
316
- Both providers resolve the same agents, tasks, workflows, and knowledge bases. Their activation and hook surfaces are different native adapters validated independently by the parity gate.
317
-
318
- ---
319
-
320
- ## Who is SINAPSE for?
321
-
322
- SINAPSE isn't for everyone. It's opinionated, rigorous, and demands discipline. But for those who need speed **with rigor**, it transforms generative AI from a toy into real infrastructure.
323
-
324
- ### Ideal for
325
-
326
- - **Technical founders** building SaaS solo or in small teams who need to operate like a large team
327
- - **Consultants and agencies** delivering complete projects (brand + copy + dev + deploy) who need consistent quality across clients
328
- - **Product teams** who want to eliminate inconsistency between requirements, design, implementation, and QA
329
- - **Educators** teaching applied AI who need a real framework to demonstrate in class
330
- - **Independent builders** who treat AI as infrastructure, not as a toy
331
-
332
- ### Not for
333
-
334
- - One-shot projects without continuity or process discipline
335
- - Teams that prefer total flexibility over governance
336
- - Users who expect "magic AI" without methodology
337
-
338
- If you identify with the first group, you're in the right place.
339
-
340
- ---
341
-
342
- ## Quality and Security
343
-
344
- ### Constitutional Enforcement
86
+ ```bash
87
+ # Install or synchronize both providers in the current project
88
+ npx sinapse-ai@latest install
345
89
 
346
- SINAPSE doesn't just document rules -- Claude Code uses **20 registered hooks**, while Codex exposes **9 lifecycle events** through the compatibility bridge:
90
+ # Update an installation without losing project customizations
91
+ npx sinapse-ai@latest update
347
92
 
348
- - `enforce-git-push-authority.sh` -- blocks push by unauthorized agents
349
- - `enforce-story-gate.cjs` -- blocks code without a validated story
350
- - `sql-governance.py` -- blocks dangerous SQL (injection patterns)
351
- - `enforce-delegation.cjs` -- blocks orchestrators from executing domain work
352
- - `enforce-architecture-first.cjs` -- blocks code in protected paths without documentation
93
+ # Diagnose and fix the environment
94
+ npx sinapse-ai@latest doctor --fix
353
95
 
354
- ### 25 Deployment Blockers (3 Tiers)
96
+ # Show the installed surface
97
+ npx sinapse-ai@latest status
98
+ ```
355
99
 
356
- No project goes to production without passing all of them:
100
+ `install --force` reinstalls managed surfaces. `install --reconfigure` opens
101
+ provider selection only in interactive terminals; non-interactive runs use both.
102
+ `install --global-only` configures only global adapters and does not change the
103
+ current project.
357
104
 
358
- - **Tier 1** -- 10 absolute blockers: RLS, zero hardcoded keys, protected service_role, MFA, authenticated APIs, parameterized SQL
359
- - **Tier 2** -- 7 compliance blockers: DPO, consent, data subject rights, breach notification (LGPD)
360
- - **Tier 3** -- 8 operational blockers: logging, backup, vulnerability scanning, incident response
105
+ ## Architecture that respects the project
361
106
 
362
- ### Quality Gates
107
+ | Layer | Responsibility | Policy |
108
+ |---|---|---|
109
+ | L1 | Framework core | Immutable |
110
+ | L2 | Templates and workflows | Extend-only |
111
+ | L3 | Configuration | Mutable with guardrails |
112
+ | L4 | Stories, packages, squads, and tests | Always project-owned |
363
113
 
364
- ```bash
365
- npm run lint # ESLint
366
- npm run typecheck # TypeScript
367
- npm test # Tests
368
- npm run test:coverage # Coverage
369
- ```
114
+ Updates refresh managed content and preserve local work. Gates also prevent
115
+ unauthorized pushes, code writes without a validated story, unsafe SQL, and
116
+ Claude/Codex drift.
370
117
 
371
- Pre-commit and pre-push hooks validate automatically before each operation.
118
+ ## Who it is for
372
119
 
373
- ---
120
+ - Teams that want specialized AI without losing traceability.
121
+ - Projects that need the same contract in Claude Code and Codex.
122
+ - Product work that values story-first development, QA, security, and gradual delivery.
123
+ - Builders who prefer clear commands over a pile of improvised prompts.
374
124
 
375
125
  ## Documentation
376
126
 
377
- | Resource | Link |
378
- |----------|------|
379
- | Getting Started | [docs/guides/getting-started.md](docs/guides/getting-started.md) |
380
- | Architecture | [docs/framework/core-architecture.md](docs/framework/core-architecture.md) |
381
- | Squads Guide | [docs/guides/squads-guide.md](docs/guides/squads-guide.md) |
382
- | Agent Reference | [docs/guides/agent-reference.md](docs/guides/agent-reference.md) |
383
- | Workflows | [docs/guides/workflows-guide.md](docs/guides/workflows-guide.md) |
127
+ | Topic | Link |
128
+ |---|---|
129
+ | Getting started | [docs/getting-started.md](docs/getting-started.md) |
130
+ | Claude Code and Codex integration | [docs/guides/ide-integration.md](docs/guides/ide-integration.md) |
131
+ | Engineering workflows | [docs/framework/software-engineering-applicability.md](docs/framework/software-engineering-applicability.md) |
132
+ | Agent reference | [docs/agent-reference-guide.md](docs/agent-reference-guide.md) |
133
+ | React Bits | [docs/framework/react-bits/index.md](docs/framework/react-bits/index.md) |
384
134
  | Security | [SECURITY.md](SECURITY.md) |
385
135
  | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
386
136
 
387
- ---
388
-
389
- ## CLI Reference
390
-
391
- The public surface is intentional -- four canonical lifecycle commands, two diagnostics, one advanced sub-command.
392
-
393
- ```bash
394
- # Lifecycle
395
- npx sinapse-ai install # Install (idempotent -- re-runs are upserts)
396
- npx sinapse-ai install --force # Reinstall from scratch, ignoring existing state
397
- npx sinapse-ai update # Update to the latest version
398
- npx sinapse-ai uninstall # Remove the framework from the project
399
-
400
- # Diagnostics
401
- npx sinapse-ai status # Installation state + list of squads
402
- npx sinapse-ai doctor # 16 health checks against the environment
403
- npx sinapse-ai doctor --fix # Auto-fix detected issues
404
- npx sinapse-ai doctor --json # Machine-readable output for CI
405
- npx sinapse-ai doctor --dry-run # Show what `--fix` would do without applying
406
-
407
- # Advanced
408
- npx sinapse-ai chrome-brain install # Install browser automation
409
- ```
410
-
411
- All commands are safe to re-run. After installing, use `@agent-name` in Claude Code or `$snps` / `$sinapse-agent agent-id` in Codex.
412
-
413
- ---
414
-
415
137
  ## Contributing
416
138
 
417
139
  ```bash
418
140
  git clone https://github.com/caioimori/sinapse-ai.git
419
- cd sinapse-ai && npm install
141
+ cd sinapse-ai
142
+ npm install
143
+ npm test
420
144
  ```
421
145
 
422
- 1. Fork the repository
423
- 2. Create your branch (`git checkout -b feat/my-feature`)
424
- 3. Commit (`git commit -m 'feat: description'`)
425
- 4. Push (`git push origin feat/my-feature`)
426
- 5. Open a Pull Request
427
-
428
- See [CONTRIBUTING.md](CONTRIBUTING.md) for full details.
429
-
430
- ---
431
-
432
- ## Legal
433
-
434
- | Document | Link |
435
- |----------|------|
436
- | License | [MIT](LICENSE) |
437
- | Security | [SECURITY.md](SECURITY.md) |
438
- | Code of Conduct | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) |
439
- | Contributing | [CONTRIBUTING.md](CONTRIBUTING.md) |
440
-
441
- ---
442
-
443
- ## Maintainers
444
-
445
- - [@caioimori](https://github.com/caioimori) -- Lead Maintainer
446
- - [@Matheus-soier](https://github.com/Matheus-soier) -- Co-Maintainer
447
-
448
- ---
449
-
450
- ## Ready to start?
451
-
452
- ```bash
453
- npx sinapse-ai install
454
- ```
455
-
456
- One command. 17 squads. 172 agents. Constitutional governance. All operating directly in the terminal.
457
-
458
- **[Full documentation](docs/guides/getting-started.md)** • **[Report issue](https://github.com/caioimori/sinapse-ai/issues)** • **[Discussions](https://github.com/caioimori/sinapse-ai/discussions)**
459
-
460
- ---
146
+ Open a branch, keep the story and gates current, then submit a pull request.
147
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for the complete process.
461
148
 
462
- **Built for builders. Governed by a Constitution. Operating 100% in the terminal.**
149
+ ## License
463
150
 
464
- **[Back to top](#sinapse-ai)**
151
+ MIT. See [LICENSE](LICENSE).