@caoscompanybr/merlin 3.5.0

package/.merlin-core/docs/GUIDE.md

@@ -0,0 +1,413 @@
+# Merlin — Your AI Development Team
+
+> A plain-language guide for everyone who works with Merlin, no coding experience required.
+
+---
+
+## What is Merlin?
+
+Imagine hiring a team of 15 specialists — a developer, an architect, a QA tester, a project manager, a designer, and more — who all work inside your computer, follow strict rules, remember what happened yesterday, and always ask permission before doing anything risky.
+
+That's Merlin.
+
+It's a framework that turns a single AI assistant (Claude) into a **managed software development operation**. Instead of one AI that does everything (and forgets everything), you get specialized agents that know their role, collaborate with each other, and maintain institutional memory across work sessions.
+
+### The Key Difference
+
+| Without Merlin                                   | With Merlin                                  |
+| ------------------------------------------------ | -------------------------------------------- |
+| One AI that forgets everything between chats     | 15 specialists that remember context         |
+| No rules — AI might delete files or break things | Constitutional principles + safety gates     |
+| You manage the AI manually                       | Structured workflows guide the process       |
+| Quality depends on luck                          | 3 layers of quality enforcement              |
+| No documentation trail                           | Automatic handoffs, learnings, and decisions |
+
+---
+
+## Meet Your Team
+
+Merlin has **15 agents**, each with a name and a specific job. You don't need to call them by name — Merlin automatically assigns the right agent based on what you're asking for.
+
+### The Core Team
+
+| Name      | Role                | What They Do                                                              |
+| --------- | ------------------- | ------------------------------------------------------------------------- |
+| **Orion** | Master Orchestrator | The team lead. Decides who handles what and coordinates multi-agent work. |
+| **Dex**   | Developer           | Writes code, fixes bugs, builds features. Your primary builder.           |
+| **Aria**  | Architect           | Designs the technical solution before anyone starts coding.               |
+| **Quinn** | QA Specialist       | Tests everything. Tries to break what Dex built. Finds edge cases.        |
+| **Gage**  | DevOps Engineer     | Handles deployments, CI/CD pipelines, git operations, and infrastructure. |
+
+### The Product Team
+
+| Name       | Role             | What They Do                                                        |
+| ---------- | ---------------- | ------------------------------------------------------------------- |
+| **Atlas**  | Business Analyst | Analyzes requirements, finds gaps, maps stakeholder needs.          |
+| **Pax**    | Product Owner    | Manages the backlog, prioritizes features, writes user stories.     |
+| **Morgan** | Project Manager  | Tracks timelines, sprints, risks, and milestones.                   |
+| **River**  | Scrum Master     | Runs standups, retrospectives, and removes impediments.             |
+| **Uma**    | UX Designer      | Designs user interfaces, ensures accessibility, creates wireframes. |
+
+### The Specialists
+
+| Name      | Role             | What They Do                                                            |
+| --------- | ---------------- | ----------------------------------------------------------------------- |
+| **Sage**  | Deep Researcher  | Reads the entire codebase before anyone starts. The team's memory.      |
+| **Scout** | Fast Locator     | Quickly finds files, patterns, and code references.                     |
+| **Iris**  | Web Researcher   | Searches the internet for solutions, documentation, and best practices. |
+| **Dara**  | Data Engineer    | Handles databases, schemas, migrations, and data pipelines.             |
+| **Mira**  | System Optimizer | Analyzes Merlin itself — finds bottlenecks and suggests improvements.   |
+
+---
+
+## How Work Gets Done
+
+### The Folloni Funnel
+
+Every significant feature follows three clear phases. Think of it like building a house: you don't start pouring concrete before you have blueprints.
+
+```
+ ┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
+ │   1. RESEARCH    │────▶│    2. PLAN       │────▶│    3. BUILD      │
+ │                  │     │                  │     │                  │
+ │  Sage + Scout    │     │  Aria            │     │  Dex → Quinn     │
+ │  read everything │     │  designs the     │     │  → Gage          │
+ │  and produce a   │     │  technical spec  │     │  write, test,    │
+ │  requirements    │     │  based on the    │     │  and ship the    │
+ │  document        │     │  requirements    │     │  code            │
+ └─────────────────┘     └─────────────────┘     └─────────────────┘
+        ▲                        ▲
+        │                        │
+   CONTEXT RESET            CONTEXT RESET
+   (fresh start)            (fresh start)
+```
+
+**Why context resets?** Each phase starts with a clean slate, carrying only the
+document from the previous phase. This prevents the AI from getting confused
+by old conversations — like starting a new meeting with just the minutes from
+the last one.
+
+### For Quick Tasks
+
+Not everything needs the full funnel. For small fixes or simple additions:
+
+- **`/oneshot`** — Research + plan + implement in one go
+- **`/commit`** — Stage and commit with a well-formatted message
+- **`/debug`** — Investigate a bug without changing code
+
+---
+
+## The Commands You'll Use Most
+
+Think of commands as **buttons you press** to tell Merlin what you want to do.
+You type them in the Claude Code terminal.
+
+### "I want to start a new feature"
+
+```
+/plan "Add user authentication with Google login"
+```
+
+Merlin will research the codebase, design a plan, and present it for your approval before writing any code.
+
+### "I want to build what we planned"
+
+```
+/implement
+```
+
+Merlin finds the latest plan and starts building it, following the spec exactly.
+
+### "I want a quick fix"
+
+```
+/oneshot "Fix the login button not working on mobile"
+```
+
+For small tasks that don't need a full plan.
+
+### "I want to ship what we built"
+
+```
+/commit
+/describe-pr
+```
+
+Creates a clean commit and a pull request description.
+
+### "I want to check quality"
+
+```
+/adversarial-review
+```
+
+Quinn attacks the code from 6 different angles trying to find problems.
+
+### "I want to continue where we left off"
+
+```
+/fast-start
+```
+
+Merlin checks all pending reminders, objectives, and handoffs for your project
+and gives you a briefing — like a morning standup with your AI team.
+
+### "I want to discuss something"
+
+```
+/doubts "How does the payment system work?"
+```
+
+Start a collaborative discussion. Merlin searches its accumulated knowledge
+before answering.
+
+### "I want to remember something for next time"
+
+```
+/capture-learning "The Stripe webhook needs a 5-second timeout"
+/create-reminder "Deploy the staging fix before Friday"
+/create-objective "Reach 90% test coverage by end of sprint"
+```
+
+---
+
+## Safety & Approvals
+
+Merlin has a built-in safety system with three levels. Think of it like traffic lights:
+
+### 🟢 Green — Automatic (LOW risk)
+
+These happen without asking:
+
+- Reading files
+- Writing code
+- Running tests
+- Creating commits
+- Searching the codebase
+
+### 🟡 Yellow — Asks First (MEDIUM risk)
+
+Merlin pauses and asks for your OK:
+
+- Pushing code to GitHub
+- Creating pull requests
+- Installing new packages
+- Running build commands
+
+> **YOLO Mode:** You can turn this on (`merlin-tools yolo on`) to auto-approve
+> yellow actions. Useful when you're in flow and trust the process.
+
+### 🔴 Red — Always Asks (HIGH risk)
+
+Merlin **always** stops and waits for explicit permission. Even in YOLO mode:
+
+- Deploying to production
+- Force-pushing to git
+- Deleting large amounts of code (50+ lines)
+- Financial operations (Stripe charges, subscriptions)
+- Actions that affect external services
+
+**The rule is simple:** the harder something is to undo, the more Merlin will
+insist on your approval.
+
+---
+
+## Memory & Context
+
+One of Merlin's most powerful features is **persistent memory**. Unlike a normal
+AI chat that forgets everything when you close the window, Merlin maintains
+several types of memory:
+
+### Types of Memory
+
+| Type           | What It Is                                                       | Real-World Analogy                              |
+| -------------- | ---------------------------------------------------------------- | ----------------------------------------------- |
+| **Handoffs**   | Session summaries — what was done, what's pending, key decisions | Shift change notes at a hospital                |
+| **Learnings**  | Domain knowledge — gotchas, patterns, conventions                | A team wiki of "things we learned the hard way" |
+| **Reminders**  | Persistent alerts that surface in future sessions                | Sticky notes on your monitor                    |
+| **Objectives** | Goals with measurable success criteria                           | OKRs or sprint goals                            |
+| **Plans**      | Technical implementation specs                                   | Architecture documents                          |
+| **Decisions**  | Architecture Decision Records (ADRs)                             | Meeting minutes for important choices           |
+| **Research**   | Deep analysis documents                                          | Investigation reports                           |
+
+### How Memory Works
+
+1. **During work** — Merlin automatically captures important context
+2. **Between sessions** — Everything is saved as markdown files in `thoughts/shared/`
+3. **Next session** — `/fast-start` retrieves the most relevant memories using a smart scoring system that considers:
+   - How recently the memory was created
+   - How relevant it is to your current task
+   - What type of memory is most useful right now
+
+### The Smart Part
+
+As your conversation gets longer and the AI's "working memory" fills up,
+Merlin actually injects **more** supporting context — summaries, reminders,
+and handoff notes — to keep the agent grounded. Think of it like a pilot's
+checklist that becomes more detailed during the critical phases of a flight.
+
+---
+
+## Skills — What Merlin Knows How To Do
+
+Skills are specialized knowledge modules that activate automatically based on
+what you're working on. You don't need to enable them — Merlin detects when
+a skill is relevant and loads it.
+
+### Code & Development
+
+| Skill      | What It Does                                       |
+| ---------- | -------------------------------------------------- |
+| JavaScript | ES6+ patterns, async/await, Node.js best practices |
+| TypeScript | Type system, generics, utility types               |
+| Python     | Type hints, async, dataclasses, Python 3.10+       |
+| Code Style | Naming conventions, readability rules              |
+| API Design | REST, GraphQL, OpenAPI standards                   |
+| Database   | SQL/NoSQL patterns, migrations, indexing           |
+
+### Design & Frontend
+
+| Skill              | What It Does                                         |
+| ------------------ | ---------------------------------------------------- |
+| Design System      | Semantic color tokens, typography, spacing grid      |
+| Color Palette      | Industry-specific palettes with WCAG contrast checks |
+| Typography         | Font pairing (20 combinations), size scales          |
+| UX Patterns        | Landing pages, dashboards, charts, accessibility     |
+| Design Inspiration | Generates design briefs before visual work           |
+| Frontend Design    | Design philosophy, anti-patterns, aesthetic vision   |
+
+### Documents
+
+| Skill | What It Does                        |
+| ----- | ----------------------------------- |
+| PDF   | Generate PDF documents from content |
+| DOCX  | Create Word documents               |
+| PPTX  | Create PowerPoint presentations     |
+| XLSX  | Create Excel spreadsheets           |
+
+### Presentations
+
+| Skill   | What It Does                                                                                                                          |
+| ------- | ------------------------------------------------------------------------------------------------------------------------------------- |
+| BLKSKRN | Create stunning local HTML presentations with cinematic animations, ambient backgrounds, and zero dependencies. Opens in any browser. |
+
+### Testing & Quality
+
+| Skill              | What It Does                                      |
+| ------------------ | ------------------------------------------------- |
+| Testing            | Unit, integration, and end-to-end test strategies |
+| Property Testing   | Math-based testing with random inputs             |
+| Webapp Testing     | Browser-based testing with Playwright             |
+| Adversarial Review | 7-axis attack surface analysis                    |
+| Engineering Audit  | 6-axis holistic engineering code audit            |
+| Static Analysis    | Security scanning with Semgrep, ESLint            |
+
+### Infrastructure
+
+| Skill           | What It Does                               |
+| --------------- | ------------------------------------------ |
+| Deploy          | One-click deployment (Netlify, Vercel)     |
+| MCP Builder     | Guide for creating MCP server integrations |
+| Cloud Discovery | Cloud computing and serverless patterns    |
+
+### Meta & Collaboration
+
+| Skill              | What It Does                                |
+| ------------------ | ------------------------------------------- |
+| Skill Creator      | Create, test, and optimize new skills       |
+| Claude API         | Build apps with the Claude API and SDKs     |
+| Team Execution     | Multi-agent coordination modes              |
+| Party Mode         | Roundtable discussions with multiple agents |
+| Elicitation        | 20+ techniques for extracting requirements  |
+| Context Management | Session lifecycle and handoff creation      |
+
+---
+
+## The Constitution
+
+Merlin operates under **13 constitutional principles** — non-negotiable rules
+that every agent must follow. The most important ones for you to know:
+
+1. **Spec-Driven Development** — We always research before planning, and plan
+   before coding. No one writes code without a spec.
+
+2. **No Invention** — Merlin only builds what you asked for. It never adds
+   features from its imagination.
+
+3. **Quality First** — Every change goes through quality checks. No shortcuts.
+
+4. **Human Gates** — For risky actions, a human (you) must approve. Always.
+
+5. **Professional Objectivity** — Merlin tells you the truth, even if it's not
+   what you want to hear. Technical accuracy over validation.
+
+---
+
+## Your Projects
+
+Merlin can manage multiple projects simultaneously from a central hub (the
+Gestao Merlin repository). Each project gets its own copy of the framework
+with project-specific configuration.
+
+### Currently Managed Projects
+
+| Project            | What It Is                                        |
+| ------------------ | ------------------------------------------------- |
+| **acme-web**       | E-commerce storefront (Next.js)                   |
+| **acme-extension** | Chrome extension for event tracking (React + WXT) |
+| **media-manager**  | Video backlog manager (Electron + React)          |
+| **example-saas**   | SaaS platform                                     |
+| **community-site** | Community project                                 |
+| **client-site**    | Marketing site (static)                           |
+| **sample-project** | Internal tool                                     |
+| + more projects    | Across the fleet                                  |
+
+### How Fleet Deployment Works
+
+When the framework is updated (like this v2.2 release), a single command
+deploys the changes to all projects:
+
+```bash
+bash .merlin-core/tools/convert-to-merlin.sh --yes
+```
+
+Each project keeps its own configuration, memories, and domain skills while
+receiving the latest framework core, agents, and general skills.
+
+---
+
+## Glossary
+
+| Term                 | Definition                                                                         |
+| -------------------- | ---------------------------------------------------------------------------------- |
+| **Agent**            | A specialized AI persona with a specific role (developer, architect, etc.)         |
+| **Alkimia**          | The 8-layer context engine that decides what information each agent receives       |
+| **BLKSKRN**          | Merlin's local presentation engine — creates HTML slides with cinematic animations |
+| **Constitution**     | The 13 rules that govern how all agents behave                                     |
+| **Folloni Funnel**   | The 3-phase development workflow: Research → Plan → Build                          |
+| **Handoff**          | A document that captures session state for continuity                              |
+| **Learning**         | A captured piece of domain knowledge (a gotcha, pattern, or convention)            |
+| **MCP**              | Model Context Protocol — a standard for connecting AI to external tools            |
+| **Quality Gate**     | An automated checkpoint that must pass before code can proceed                     |
+| **Skill**            | A knowledge module that auto-activates based on context                            |
+| **Slash Command**    | A `/command` you type to trigger a specific workflow                               |
+| **ThoughtsProvider** | The memory system that stores and retrieves learnings, handoffs, etc.              |
+| **Token Bracket**    | How Merlin tracks conversation length and adjusts detail level                     |
+| **YOLO Mode**        | Autonomous mode that auto-approves medium-risk actions                             |
+
+---
+
+## Getting Help
+
+- Type `/help` in Claude Code for command reference
+- Type `/fast-start` at the beginning of each session for a briefing
+- Type `/doubts "your question"` to discuss anything about the codebase
+- Type `/founder-mode` for a strategic project overview
+
+---
+
+<div align="center">
+  <sub>Merlin v3.5.0 — Modules &amp; Licensing</sub>
+  <br />
+  <sub>Built with the Folloni Funnel methodology.</sub>
+</div>

package/.merlin-core/docs/merlin-commands-guide-pt.md

@@ -0,0 +1,183 @@
+# Merlin Core — Guia de Comandos
+
+> Framework v3.5.0 | 39 comandos organizados por fase de trabalho
+
+---
+
+## Fluxo Principal
+
+```
+Sessao → Pesquisar → Planejar → Implementar → Revisar → Commitar → Entregar
+```
+
+---
+
+## 1. Sessao
+
+Comandos para inicio e fim do trabalho, gestao de contexto entre sessoes.
+
+| Comando             | O que faz                                                              |
+| ------------------- | ---------------------------------------------------------------------- |
+| `/fast-start`       | Comecar sessao — mostra pendencias, handoffs, lembretes e objetivos    |
+| `/doubts`           | Tirar duvidas sobre o codigo com base nos learnings do projeto         |
+| `/create-reminder`  | Criar lembrete persistente (aparece em sessoes futuras)                |
+| `/create-objective` | Definir meta com criterios de sucesso                                  |
+| `/check-objectives` | Ver progresso das metas ativas                                         |
+| `/capture-learning` | Salvar aprendizado (gotcha, padrao, convencao)                         |
+| `/recall-learnings` | Buscar learnings salvos sobre um tema                                  |
+| `/handoff`          | Salvar contexto para continuar em outra sessao                         |
+| `/resume-handoff`   | Retomar de onde parou (le o ultimo handoff)                            |
+| `/conclude`         | Fechar um thought (plano, handoff, lembrete, objetivo) que ja terminou |
+
+---
+
+## 2. Pesquisa
+
+Antes de planejar — entender o que existe no codigo.
+
+| Comando          | O que faz                                                 |
+| ---------------- | --------------------------------------------------------- |
+| `/research`      | Pesquisa profunda no codigo — entender como algo funciona |
+| `/analyze-issue` | Analisar um problema ou bug especifico                    |
+
+---
+
+## 3. Planejamento
+
+Antes de codar — criar o roteiro de implementacao.
+
+| Comando          | O que faz                                  |
+| ---------------- | ------------------------------------------ |
+| `/plan`          | Criar plano de implementacao detalhado     |
+| `/iterate-plan`  | Ajustar um plano existente                 |
+| `/validate-plan` | Validar se o plano esta completo e correto |
+
+---
+
+## 4. Implementacao
+
+Hora de codar — seguir o plano ou resolver rapido.
+
+| Comando      | O que faz                                                |
+| ------------ | -------------------------------------------------------- |
+| `/implement` | Executar o plano passo a passo                           |
+| `/oneshot`   | Tarefa rapida — pesquisa + plano + implementa de uma vez |
+| `/tdd`       | Implementar com Test-Driven Development (teste primeiro) |
+
+---
+
+## 5. Revisao
+
+Antes de commitar — garantir qualidade.
+
+| Comando               | O que faz                                           |
+| --------------------- | --------------------------------------------------- |
+| `/review`             | Revisar as mudancas (qualidade, seguranca, padroes) |
+| `/debug`              | Investigar um bug sem editar codigo                 |
+| `/check`              | Verificacao rapida de saude do codigo               |
+| `/adversarial-review` | Revisao agressiva — tenta quebrar o codigo          |
+| `/verify-goals`       | Verificar se o que foi feito atende os objetivos    |
+
+---
+
+## 6. Git
+
+Commitar e documentar as mudancas.
+
+| Comando        | O que faz                                  |
+| -------------- | ------------------------------------------ |
+| `/commit`      | Criar commit com mensagem bem formatada    |
+| `/describe-pr` | Gerar descricao completa para Pull Request |
+
+---
+
+## 7. Especiais
+
+Ferramentas avancadas para situacoes especificas.
+
+| Comando          | O que faz                                            |
+| ---------------- | ---------------------------------------------------- |
+| `/elicit`        | Extrair requisitos do usuario com perguntas guiadas  |
+| `/party`         | Multiplos agentes trabalhando juntos na mesma tarefa |
+| `/founder-mode`  | Modo fundador — visao estrategica do projeto         |
+| `/common-ground` | Alinhar entendimento entre voce e o agente           |
+| `/skill-audit`   | Auditar quais skills estao ativas e seu estado       |
+
+---
+
+## Cenarios Praticos
+
+### Bug simples
+
+```
+/oneshot → /review → /commit
+```
+
+### Feature nova
+
+```
+/research → /plan → /implement → /review → /commit
+```
+
+### Inicio de sessao
+
+```
+/fast-start → (trabalhar) → /handoff
+```
+
+### Nao sei por onde comecar
+
+```
+/doubts → /research → /plan
+```
+
+### Tarefa grande (varias sessoes)
+
+```
+Sessao 1: /research → /plan → /handoff
+Sessao 2: /fast-start → /implement → /handoff
+Sessao 3: /fast-start → /review → /commit → /conclude
+```
+
+### Investigar problema sem mexer no codigo
+
+```
+/debug → /analyze-issue → /capture-learning
+```
+
+### Revisao rigorosa antes de deploy
+
+```
+/review → /adversarial-review → /verify-goals → /commit → /describe-pr
+```
+
+---
+
+## Onde Ficam os Documentos
+
+| Diretorio                     | Conteudo                                    |
+| ----------------------------- | ------------------------------------------- |
+| `thoughts/shared/plans/`      | Planos de implementacao                     |
+| `thoughts/shared/handoffs/`   | Contexto entre sessoes                      |
+| `thoughts/shared/research/`   | Pesquisas realizadas                        |
+| `thoughts/shared/decisions/`  | Decisoes de arquitetura                     |
+| `thoughts/shared/reminders/`  | Lembretes persistentes                      |
+| `thoughts/shared/objectives/` | Metas com criterios de sucesso              |
+| `thoughts/shared/learnings/`  | Aprendizados (gotchas, padroes, convencoes) |
+
+---
+
+## Ciclo de Vida dos Thoughts
+
+Cada thought tem um status que controla se ele aparece nas sessoes:
+
+| Tipo     | Status Ativo                  | Status Final             |
+| -------- | ----------------------------- | ------------------------ |
+| Plano    | `draft` → `active`            | `concluded`              |
+| Handoff  | `active`                      | `concluded`              |
+| Lembrete | `pending` → `acknowledged`    | `completed` / `expired`  |
+| Objetivo | `draft` → `active` → `paused` | `achieved` / `abandoned` |
+| Pesquisa | `active`                      | `concluded`              |
+| Decisao  | `active`                      | `concluded`              |
+
+Use `/conclude` para fechar thoughts que ja terminaram. Thoughts com status final nao aparecem mais no `/fast-start`.