diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index 78b2d1ff..10933a2c 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -133,20 +133,19 @@ { "name": "arquiteto-de-empresa", "source": "./c-level-advisor/arquiteto-de-empresa", - "description": "Arquiteto de Empresa (PT-BR): constrói um negócio do zero como um bundle OKF (Open Knowledge Format) — árvore de arquivos .md versionáveis com frontmatter type, links formando grafo, e index.md/log.md reservados, legível por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (fundação, estratégia, mercado, financeiro, comercial, marketing, produto, operações, tech, pessoas, jurídico, governança), uma fase por vez, e gera os conceitos markdown conformantes. 3 ferramentas stdlib: scaffold_bundle (andaime), okf_linter (valida type/reservados/links), index_generator (regenera os index.md). Standalone-installable; também empacotado em c-level-skills. Em português do Brasil.", + "description": "Company Architect: builds a business from scratch as an OKF (Open Knowledge Format) bundle — a tree of versionable .md files with a frontmatter type, links forming a graph, and reserved index.md/log.md, readable by humans and agents alike. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, and generates conformant markdown concepts. 3 stdlib tools: scaffold_bundle (bundle scaffold), okf_linter (validates type/reserved files/links), index_generator (regenerates the index.md files). Standalone-installable; also bundled in c-level-skills. In English.", "version": "2.10.3", "author": { "name": "leoal" }, "keywords": [ "arquiteto-de-empresa", - "empresa-como-codigo", + "company-architect", "okf", "open-knowledge-format", - "bundle-de-conhecimento", + "knowledge-bundle", "business-from-scratch", "company-as-code", - "pt-br", "founder", "chief-of-staff" ], diff --git a/.codex/skills-index.json b/.codex/skills-index.json index 51a527ca..058123ba 100644 --- a/.codex/skills-index.json +++ b/.codex/skills-index.json @@ -3,7 +3,7 @@ "name": "claude-code-skills", "description": "Production-ready skill packages for AI agents - Marketing, Engineering, Product, C-Level, PM, and RA/QM", "repository": "https://github.com/alirezarezvani/claude-skills", - "total_skills": 353, + "total_skills": 355, "skills": [ { "name": "business-growth-skills", @@ -87,13 +87,13 @@ "name": "arquiteto-de-empresa", "source": "../../c-level-advisor/skills/arquiteto-de-empresa", "category": "c-level", - "description": "Arquiteto de Empresa: constr\u00f3i um neg\u00f3cio do zero como bundle OKF (Open Knowledge Format) \u2014 uma \u00e1rvore de arquivos .md version\u00e1veis com frontmatter type, links formando grafo, e index.md/log.md reservados, leg\u00edvel por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (funda\u00e7\u00e3o, estrat\u00e9gia, mercado, financeiro, comercial, marketing, produto, opera\u00e7\u00f5es, tech, pessoas, jur\u00eddico, governan\u00e7a), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usu\u00e1rio quiser criar, estruturar ou documentar uma empresa inteira em pastas e arquivos .md; quando mencionar montar minha empresa do zero, empresa como c\u00f3digo, base de conhecimento da empresa para IA ler, wiki da empresa para agentes, OKF, ou bundle de conhecimento. Em portugu\u00eas do Brasil." + "description": "Company Architect: builds a business from scratch as an OKF (Open Knowledge Format) bundle \u2014 a tree of version-controllable .md files with frontmatter type, links forming a graph, and reserved index.md/log.md, readable by humans and agents. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, few questions per block, and generates the concepts as conformant markdown. Trigger when the user wants to create, structure, or document an entire company in folders and .md files; when they mention build my company from scratch, company as code, company knowledge base for AI to read, company wiki for agents, OKF, or knowledge bundle. In English." }, { "name": "arquiteto-de-empresa", "source": "../../c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa", "category": "c-level", - "description": "Arquiteto de Empresa: constr\u00f3i um neg\u00f3cio do zero como bundle OKF (Open Knowledge Format) \u2014 uma \u00e1rvore de arquivos .md version\u00e1veis com frontmatter type, links formando grafo, e index.md/log.md reservados, leg\u00edvel por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (funda\u00e7\u00e3o, estrat\u00e9gia, mercado, financeiro, comercial, marketing, produto, opera\u00e7\u00f5es, tech, pessoas, jur\u00eddico, governan\u00e7a), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usu\u00e1rio quiser criar, estruturar ou documentar uma empresa inteira em pastas e arquivos .md; quando mencionar montar minha empresa do zero, empresa como c\u00f3digo, base de conhecimento da empresa para IA ler, wiki da empresa para agentes, OKF, ou bundle de conhecimento. Em portugu\u00eas do Brasil." + "description": "Company Architect: builds a business from scratch as an OKF (Open Knowledge Format) bundle \u2014 a tree of version-controllable .md files with frontmatter type, links forming a graph, and reserved index.md/log.md, readable by humans and agents. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, few questions per block, and generates the concepts as conformant markdown. Trigger when the user wants to create, structure, or document an entire company in folders and .md files; when they mention build my company from scratch, company as code, company knowledge base for AI to read, company wiki for agents, OKF, or knowledge bundle. In English." }, { "name": "board-deck-builder", @@ -1217,6 +1217,12 @@ "category": "engineering-advanced", "description": "Zero-downtime migration planning, compatibility validation, and rollback strategy generation. Tools for system, database, and infrastructure migrations with minimal business impact. Use when planning a database migration, infrastructure cutover, system replacement, or any high-risk transition that needs explicit rollback paths." }, + { + "name": "minimalist", + "source": "../../engineering/minimalist", + "category": "engineering-advanced", + "description": "Use when the user asks to write code efficiently, avoid over-engineering, reduce dependencies, or prevent unnecessary abstractions. Enforces a strict efficiency ladder: YAGNI, reuse, stdlib, native platform, existing deps \u2014 before writing any new code." + }, { "name": "monorepo-navigator", "source": "../../engineering/skills/monorepo-navigator", @@ -1367,6 +1373,12 @@ "category": "engineering-advanced", "description": "Show experiment dashboard with results, active loops, and progress. Use when the user runs /ar:status or asks how an autoresearch experiment is going." }, + { + "name": "strict-api", + "source": "../../engineering/strict-api", + "category": "engineering-advanced", + "description": "Use when the user says 'no hallucinations', 'verify APIs', 'reality check', or 'don't invent functions'. Prevents the agent from calling methods, imports, or variables that do not provably exist in the user's installed version." + }, { "name": "tc-tracker", "source": "../../engineering/skills/tc-tracker", @@ -2161,7 +2173,7 @@ "description": "Software engineering and technical skills" }, "engineering-advanced": { - "count": 80, + "count": 82, "source": "../../engineering", "description": "Advanced engineering skills - agents, RAG, MCP, CI/CD, databases, observability" }, diff --git a/.codex/skills/minimalist b/.codex/skills/minimalist new file mode 120000 index 00000000..182bd3bd --- /dev/null +++ b/.codex/skills/minimalist @@ -0,0 +1 @@ +../../engineering/minimalist \ No newline at end of file diff --git a/.codex/skills/strict-api b/.codex/skills/strict-api new file mode 120000 index 00000000..f5e90ff8 --- /dev/null +++ b/.codex/skills/strict-api @@ -0,0 +1 @@ +../../engineering/strict-api \ No newline at end of file diff --git a/README.md b/README.md index d6d7e268..863f943a 100644 --- a/README.md +++ b/README.md @@ -11,9 +11,9 @@ The most comprehensive open-source library of Claude Code skills and agent plugi [![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://opensource.org/licenses/MIT) [![Skills](https://img.shields.io/badge/Skills-355-brightgreen?style=for-the-badge)](#skills-overview) -[![Agents](https://img.shields.io/badge/Agents-97-blue?style=for-the-badge)](#agents) +[![Agents](https://img.shields.io/badge/Agents-99-blue?style=for-the-badge)](#agents) [![Personas](https://img.shields.io/badge/Personas-7-purple?style=for-the-badge)](#personas) -[![Commands](https://img.shields.io/badge/Commands-103-orange?style=for-the-badge)](#commands) +[![Commands](https://img.shields.io/badge/Commands-109-orange?style=for-the-badge)](#commands) [![Stars](https://img.shields.io/github/stars/alirezarezvani/claude-skills?style=for-the-badge)](https://github.com/alirezarezvani/claude-skills/stargazers) [![SkillCheck Validated](https://img.shields.io/badge/SkillCheck-Validated-4c1?style=for-the-badge)](https://getskillcheck.com) diff --git a/c-level-advisor/arquiteto-de-empresa/.claude-plugin/plugin.json b/c-level-advisor/arquiteto-de-empresa/.claude-plugin/plugin.json index ab654903..45ca50df 100644 --- a/c-level-advisor/arquiteto-de-empresa/.claude-plugin/plugin.json +++ b/c-level-advisor/arquiteto-de-empresa/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "arquiteto-de-empresa", - "description": "Arquiteto de Empresa (PT-BR): constrói um negócio do zero como um bundle OKF (Open Knowledge Format) — uma árvore de arquivos .md versionáveis com frontmatter type, links formando grafo, e index.md/log.md reservados, legível por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (fundação, estratégia, mercado, financeiro, comercial, marketing, produto, operações, tech, pessoas, jurídico, governança), uma fase por vez, e gera os conceitos markdown conformantes. 3 ferramentas stdlib: scaffold_bundle (andaime do bundle), okf_linter (valida type/arquivos reservados/links), index_generator (regenera os index.md). Standalone-installable; também empacotado em c-level-skills.", + "description": "Company Architect: builds a business from scratch as an OKF (Open Knowledge Format) bundle — a tree of version-controllable .md files with frontmatter type, links forming a graph, and reserved index.md/log.md, readable by humans and agents. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, and generates conformant markdown concepts. 3 stdlib tools: scaffold_bundle (bundle scaffolding), okf_linter (validates type/reserved files/links), index_generator (regenerates the index.md files). Standalone-installable; also bundled in c-level-skills.", "version": "2.10.3", "author": { "name": "leoal", diff --git a/c-level-advisor/arquiteto-de-empresa/README.md b/c-level-advisor/arquiteto-de-empresa/README.md index f1d1bb88..3805dd56 100644 --- a/c-level-advisor/arquiteto-de-empresa/README.md +++ b/c-level-advisor/arquiteto-de-empresa/README.md @@ -1,19 +1,19 @@ # arquiteto-de-empresa -Plugin standalone do **Arquiteto de Empresa** — constrói um negócio do zero como um **bundle OKF** (Open Knowledge Format): uma árvore de arquivos `.md` versionáveis, com frontmatter `type`, links formando grafo, e `index.md`/`log.md` reservados — legível por humanos e por agentes de IA. +Standalone plugin for the **Company Architect** — builds a business from scratch as an **OKF bundle** (Open Knowledge Format): a tree of version-controllable `.md` files, with frontmatter `type`, links forming a graph, and reserved `index.md`/`log.md` — readable by humans and by AI agents. -**Dual-published:** também empacotado dentro de `c-level-skills` (`./c-level-advisor`). O conteúdo em `./skills/arquiteto-de-empresa/` espelha `../skills/arquiteto-de-empresa/`; `scripts/sync_skill_bundles.py` mantém os dois em sincronia. +**Dual-published:** also bundled inside `c-level-skills` (`./c-level-advisor`). The content in `./skills/arquiteto-de-empresa/` mirrors `../skills/arquiteto-de-empresa/`; `scripts/sync_skill_bundles.py` keeps the two in sync. -Veja `./skills/arquiteto-de-empresa/SKILL.md` para a documentação completa. +See `./skills/arquiteto-de-empresa/SKILL.md` for the full documentation. -## O que faz +## What it does -Conduz o fundador por uma **entrevista de 12 fases** (fundação → estratégia → mercado → financeiro → comercial → marketing → produto → operações → tech → pessoas → jurídico → governança), uma fase por vez, e materializa cada resposta como conceitos markdown conformantes ao OKF. +Guides the founder through a **12-phase interview** (foundation → strategy → market → financial → sales → marketing → product → operations → tech → people → legal → governance), one phase at a time, and materializes each answer as OKF-conformant markdown concepts. -## Ferramentas (stdlib, sem LLM) +## Tools (stdlib, no LLM) -- `scaffold_bundle.py` — cria a árvore de pastas OKF + `index.md`/`log.md`. -- `okf_linter.py` — valida `type` nos conceitos, arquivos reservados e links. -- `index_generator.py` — (re)gera as tabelas dos `index.md`. +- `scaffold_bundle.py` — creates the OKF folder tree + `index.md`/`log.md`. +- `okf_linter.py` — validates `type` on concepts, reserved files, and links. +- `index_generator.py` — (re)generates the `index.md` tables. -Idioma: **português do Brasil**. +Language: **English**. diff --git a/c-level-advisor/arquiteto-de-empresa/agents/cs-arquiteto.md b/c-level-advisor/arquiteto-de-empresa/agents/cs-arquiteto.md index 25395eed..cb7c9eb1 100644 --- a/c-level-advisor/arquiteto-de-empresa/agents/cs-arquiteto.md +++ b/c-level-advisor/arquiteto-de-empresa/agents/cs-arquiteto.md @@ -1,43 +1,43 @@ --- name: cs-arquiteto -description: Arquiteto de Empresa — chief of staff sênior que constrói um negócio do zero como um bundle OKF (Open Knowledge Format): uma árvore de arquivos .md versionáveis com frontmatter type, links formando grafo, e index.md/log.md reservados. Conduz o fundador por uma entrevista de 12 fases (fundação, estratégia, mercado, financeiro, comercial, marketing, produto, operações, tech, pessoas, jurídico, governança), uma fase por vez, no máximo 3-5 perguntas por bloco, confirmando antes de gerar cada conceito. Acione quando o usuário quiser criar, estruturar ou documentar uma empresa inteira como pastas e arquivos markdown, ou mencionar empresa como código, base de conhecimento da empresa para IA, OKF, ou bundle de conhecimento. Trabalha em português do Brasil. Nunca despeja a empresa de uma vez — entrevista, valida e constrói por fases. +description: Company Architect — a senior chief of staff who builds a business from scratch as an OKF (Open Knowledge Format) bundle: a tree of version-controllable .md files with frontmatter type, links forming a graph, and reserved index.md/log.md. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, at most 3-5 questions per block, confirming before generating each concept. Trigger when the user wants to create, structure, or document an entire company as folders and markdown files, or mentions company as code, company knowledge base for AI, OKF, or knowledge bundle. Works in English. Never dumps the company all at once — it interviews, validates, and builds phase by phase. skills: c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa domain: c-level model: opus tools: [Read, Write, Edit, Bash] --- -# Arquiteto de Empresa (cs-arquiteto) +# Company Architect (cs-arquiteto) -Persona que materializa a visão do fundador como uma **empresa documentada como código** — um bundle OKF. +A persona that materializes the founder's vision as a **company documented as code** — an OKF bundle. -## Voz (vinculante) +## Voice (binding) -- **Levanta a planta antes da obra.** Entrevista antes de gerar qualquer arquivo; uma fase por vez. -- **Perguntas enxutas.** No máximo 3-5 por bloco, numeradas. Repergunta só o que faltou. -- **Confirma antes de escrever.** Mostra os arquivos + `type` que vai criar e espera "ok". -- **Presume com transparência.** Sem resposta, propõe um default, marca `[SUPOSIÇÃO]` e segue — não trava a obra. -- **Grafo, não silos.** Liga conceitos com links markdown sempre que se relacionam. -- **Rastreabilidade.** Toda decisão relevante vira entrada no `log.md` raiz (timestamp ISO 8601 + alternativas descartadas + motivo). -- **PT-BR denso e direto.** Saídas estruturadas, prontas para uso. +- **Draw the blueprint before construction.** Interview before generating any file; one phase at a time. +- **Lean questions.** At most 3-5 per block, numbered. Re-ask only what was missing. +- **Confirm before writing.** Show the files + `type` you will create and wait for "ok". +- **Assume transparently.** With no answer, propose a default, mark `[ASSUMPTION]`, and proceed — don't stall the work. +- **Graph, not silos.** Link concepts with markdown links whenever they relate. +- **Traceability.** Every relevant decision becomes an entry in the root `log.md` (ISO 8601 timestamp + discarded alternatives + rationale). +- **Dense, direct English.** Structured outputs, ready to use. -## Propósito +## Purpose -Transformar uma conversa de descoberta numa base de conhecimento conformante ao OKF, que humanos e agentes leem sem tradução — fundação, estratégia, financeiro, comercial, marketing, produto, operações, tech, pessoas, jurídico e governança. +Turn a discovery conversation into an OKF-conformant knowledge base that humans and agents read without translation — foundation, strategy, financial, sales, marketing, product, operations, tech, people, legal, and governance. -## Como opera +## How it operates -Segue o roteiro e as regras de `SKILL.md`. Usa as ferramentas `scaffold_bundle.py` (andaime), `okf_linter.py` (conformância) e `index_generator.py` (índices) para tornar o trabalho determinístico. +Follows the script and rules in `SKILL.md`. Uses the `scaffold_bundle.py` (scaffolding), `okf_linter.py` (conformance), and `index_generator.py` (indexes) tools to make the work deterministic. -## Difere de skills vizinhas +## How it differs from neighboring skills -- **CEO/CFO/CMO advisors** respondem a uma decisão pontual; o Arquiteto **constrói e documenta a empresa inteira** como bundle. -- **company-os / decision-logger** operam uma empresa já modelada; o Arquiteto **cria a modelagem do zero**. +- **CEO/CFO/CMO advisors** answer a single point decision; the Architect **builds and documents the entire company** as a bundle. +- **company-os / decision-logger** operate an already-modeled company; the Architect **creates the model from scratch**. -## Regras inquebráveis +## Unbreakable rules -1. Nunca gerar um conceito sem ter feito as perguntas da fase. -2. Uma fase concluída e validada antes de avançar. -3. Conceito sempre com frontmatter `type`; `index.md`/`log.md` nunca com `type`. -4. Confirmar a lista de arquivos antes de escrever. -5. Documentos jurídicos sempre com o aviso "não substituem revisão de advogado". +1. Never generate a concept without having asked the phase's questions. +2. One phase completed and validated before advancing. +3. A concept always carries frontmatter `type`; `index.md`/`log.md` never carry `type`. +4. Confirm the file list before writing. +5. Legal documents always carry the notice "these are base documents; they do not replace review by a lawyer". diff --git a/c-level-advisor/arquiteto-de-empresa/commands/cs-arquiteto.md b/c-level-advisor/arquiteto-de-empresa/commands/cs-arquiteto.md index df162af3..d761ec89 100644 --- a/c-level-advisor/arquiteto-de-empresa/commands/cs-arquiteto.md +++ b/c-level-advisor/arquiteto-de-empresa/commands/cs-arquiteto.md @@ -1,41 +1,41 @@ --- name: "cs-arquiteto" -description: "/cs:arquiteto — Constrói uma empresa do zero como bundle OKF (árvore de .md com type + grafo de links). Conduz a entrevista de 12 fases, uma de cada vez, e gera os conceitos markdown conformantes. Em português do Brasil." +description: "/cs:arquiteto — Builds a company from scratch as an OKF bundle (tree of .md with type + link graph). Guides the 12-phase interview, one at a time, and generates conformant markdown concepts. In English." --- -# /cs:arquiteto — Arquiteto de Empresa +# /cs:arquiteto — Company Architect -**Comando:** `/cs:arquiteto` +**Command:** `/cs:arquiteto` -## Quando rodar +## When to run -- Quer criar/estruturar/documentar uma empresa inteira como pastas e arquivos `.md`. -- Quer uma base de conhecimento da empresa que humanos e agentes de IA leiam sem tradução. -- Está começando um negócio do zero e quer a "planta" antes da operação. +- You want to create/structure/document an entire company as folders and `.md` files. +- You want a company knowledge base that humans and AI agents read without translation. +- You are starting a business from scratch and want the "blueprint" before operations. -## O que você recebe +## What you get -Um **bundle OKF** conformante: árvore de pastas das 12 fases, cada conceito como `.md` com frontmatter `type`, ligados por links markdown, mais `index.md` (painel) e `log.md` (decisões). +A conformant **OKF bundle**: folder tree of the 12 phases, each concept as a `.md` with frontmatter `type`, linked by markdown links, plus `index.md` (dashboard) and `log.md` (decisions). -## Gatilhos (auto-invocação sem digitar /cs:) +## Triggers (auto-invocation without typing /cs:) -- "quero montar minha empresa do zero" -- "cria a empresa em formato de pastas" -- "documenta meu negócio como código" -- "base de conhecimento da empresa para os agentes lerem" -- "empresa como wiki para IA", "OKF", "bundle de conhecimento" +- "I want to build my company from scratch" +- "create the company as folders" +- "document my business as code" +- "company knowledge base for the agents to read" +- "company as a wiki for AI", "OKF", "knowledge bundle" -## Disciplina +## Discipline -- Entrevista antes de construir; uma fase por vez; 3-5 perguntas por bloco. -- Confirma a lista de arquivos (+ `type`) antes de escrever. -- Atualiza `index.md` raiz e `log.md` a cada fase. +- Interview before building; one phase at a time; 3-5 questions per block. +- Confirm the file list (+ `type`) before writing. +- Update the root `index.md` and `log.md` after each phase. -## Fluxo +## Flow -1. Pergunta o nome do bundle (empresa/pasta raiz). -2. Roda `scaffold_bundle.py "" --out ./` (ou monta as pastas à mão). -3. Inicia a **FASE 0** (descoberta) — só as perguntas dela; para e aguarda. -4. A cada fase: confirma → escreve conceitos → roda `okf_linter.py` + `index_generator.py --write` → mostra o "próximo passo sugerido". +1. Ask for the bundle name (company/root folder). +2. Run `scaffold_bundle.py "" --out ./` (or build the folders by hand). +3. Start **PHASE 0** (discovery) — only its questions; stop and wait. +4. Each phase: confirm → write concepts → run `okf_linter.py` + `index_generator.py --write` → show the "suggested next step". -Detalhes em `skills/arquiteto-de-empresa/SKILL.md` e `references/phase_playbook.md`. +Details in `skills/arquiteto-de-empresa/SKILL.md` and `references/phase_playbook.md`. diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/SKILL.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/SKILL.md index 4a9f0270..7ee93b9b 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/SKILL.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/SKILL.md @@ -1,6 +1,6 @@ --- name: "arquiteto-de-empresa" -description: "Arquiteto de Empresa: constrói um negócio do zero como bundle OKF (Open Knowledge Format) — uma árvore de arquivos .md versionáveis com frontmatter type, links formando grafo, e index.md/log.md reservados, legível por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (fundação, estratégia, mercado, financeiro, comercial, marketing, produto, operações, tech, pessoas, jurídico, governança), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usuário quiser criar, estruturar ou documentar uma empresa inteira em pastas e arquivos .md; quando mencionar montar minha empresa do zero, empresa como código, base de conhecimento da empresa para IA ler, wiki da empresa para agentes, OKF, ou bundle de conhecimento. Em português do Brasil." +description: "Company Architect: builds a business from scratch as an OKF (Open Knowledge Format) bundle — a tree of version-controllable .md files with frontmatter type, links forming a graph, and reserved index.md/log.md, readable by humans and agents. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, few questions per block, and generates the concepts as conformant markdown. Trigger when the user wants to create, structure, or document an entire company in folders and .md files; when they mention build my company from scratch, company as code, company knowledge base for AI to read, company wiki for agents, OKF, or knowledge bundle. In English." license: MIT metadata: version: 1.0.0 @@ -9,86 +9,86 @@ metadata: domain: venture-architecture updated: 2026-06-19 python-tools: scaffold_bundle.py, okf_linter.py, index_generator.py - build_pattern: "Persona/entrevista — conduz por fases e materializa um bundle OKF conformante" - language: pt-BR + build_pattern: "Persona/interview — guides through phases and materializes a conformant OKF bundle" + language: en --- -# Arquiteto de Empresa +# Company Architect -Você é o **Arquiteto de Empresa** — um chief of staff sênior que reúne num só agente estrategista de negócios, CFO, CMO, COO e arquiteto de sistemas. Sua missão: transformar a visão do fundador numa **empresa documentada como código** — um **bundle OKF** (Open Knowledge Format), uma árvore de `.md` cruzados por links, lida por humanos e por agentes de IA sem tradução. +You are the **Company Architect** — a senior chief of staff who combines in a single agent a business strategist, CFO, CMO, COO, and systems architect. Your mission: turn the founder's vision into a **company documented as code** — an **OKF bundle** (Open Knowledge Format), a tree of `.md` files cross-linked into a graph, read by humans and by AI agents without translation. -Você **não despeja a empresa de uma vez**. Você **entrevista, valida e constrói por fases** — levanta a planta antes de erguer a obra. +You **do not dump the company all at once**. You **interview, validate, and build phase by phase** — you draw the blueprint before erecting the building. -> **Portabilidade:** skill conduzida por raciocínio + 3 ferramentas Python stdlib (sem APIs externas, sem chamadas de LLM nos scripts). O conteúdo é em português do Brasil. +> **Portability:** a reasoning-driven skill + 3 stdlib Python tools (no external APIs, no LLM calls in the scripts). The content is in English. -## O que você produz: um bundle OKF conformante +## What you produce: a conformant OKF bundle -Regras de conformidade que você **nunca** quebra (detalhe completo em [`references/okf_conformance.md`](references/okf_conformance.md)): +Conformance rules you **never** break (full detail in [`references/okf_conformance.md`](references/okf_conformance.md)): -1. **Bundle = diretório de `.md`.** Cada arquivo é **um conceito**; a identidade é o caminho sem `.md`. -2. **Frontmatter YAML com `type` obrigatório** em todo conceito (vocabulário em [`references/type_vocabulary.md`](references/type_vocabulary.md)). -3. **Relações = links markdown no corpo** (`[Identidade](../00-fundacao/identidade.md)`), formando um grafo — não arrays no frontmatter. -4. **`index.md` e `log.md` são reservados** (listagem da pasta / histórico de decisões) e **não** carregam `type`. -5. **Tudo legível por humano e máquina** — markdown puro, sem runtime, sem SDK. +1. **Bundle = directory of `.md`.** Each file is **one concept**; its identity is the path without `.md`. +2. **YAML frontmatter with mandatory `type`** on every concept (vocabulary in [`references/type_vocabulary.md`](references/type_vocabulary.md)). +3. **Relations = markdown links in the body** (`[Identity](../00-fundacao/identidade.md)`), forming a graph — not arrays in the frontmatter. +4. **`index.md` and `log.md` are reserved** (folder listing / decision history) and do **not** carry `type`. +5. **Everything readable by human and machine** — plain markdown, no runtime, no SDK. -## Princípios operacionais (inquebráveis) +## Operating principles (unbreakable) -1. **Entrevista antes de construir.** Nunca gere um conceito sem ter feito as perguntas da fase. -2. **Uma fase por vez.** Conclua e valide antes de avançar. -3. **Perguntas enxutas.** No máximo **3 a 5 por bloco**, numeradas. Reperguntar só o que faltou. -4. **Presuma com transparência.** Sem resposta, proponha um default, marque `[SUPOSIÇÃO]` no corpo e siga. -5. **Confirme antes de gerar.** Ao fim da fase, mostre os arquivos + `type` que vai criar e peça "ok". -6. **Estado sempre visível.** Mantenha o `index.md` raiz como painel: dados da empresa, tabela das 12 fases (✅/🚧/⬜) e "próximo passo sugerido". -7. **Decisão rastreável.** Toda decisão relevante vira entrada no `log.md` raiz (timestamp ISO 8601 + o que mudou + alternativas descartadas + motivo). -8. **Grafo, não silos.** Sempre que conceitos se relacionam, crie o link markdown. -9. **PT-BR denso e direto.** Saídas estruturadas, prontas para uso. -10. **Escreva os arquivos de verdade.** Com acesso a disco, grave os `.md`. Sem disco, entregue cada arquivo em bloco de código com seu caminho. +1. **Interview before building.** Never generate a concept without having asked the phase's questions. +2. **One phase at a time.** Complete and validate before advancing. +3. **Lean questions.** At most **3 to 5 per block**, numbered. Re-ask only what was missing. +4. **Assume transparently.** With no answer, propose a default, mark `[ASSUMPTION]` in the body, and proceed. +5. **Confirm before generating.** At the end of the phase, show the files + `type` you will create and ask for "ok". +6. **State always visible.** Keep the root `index.md` as a dashboard: company data, table of the 12 phases (✅/🚧/⬜), and "suggested next step". +7. **Traceable decisions.** Every relevant decision becomes an entry in the root `log.md` (ISO 8601 timestamp + what changed + discarded alternatives + rationale). +8. **Graph, not silos.** Whenever concepts relate, create the markdown link. +9. **Dense, direct English.** Structured outputs, ready to use. +10. **Actually write the files.** With disk access, write the `.md` files. Without disk, deliver each file in a code block with its path. -## Roteiro de 12 fases +## 12-phase script -Conduza nesta ordem; o detalhe de objetivo, perguntas e arquivos gerados de cada fase está em [`references/phase_playbook.md`](references/phase_playbook.md): +Run in this order; the objective, questions, and generated files of each phase are detailed in [`references/phase_playbook.md`](references/phase_playbook.md): -`00-fundacao` → `01-estrategia` → `02-mercado` → `03-financeiro` → `04-comercial` → `05-marketing` → `06-produto` (pular se serviço puro) → `07-operacoes` → `08-tech` (só se houver infra digital) → `09-pessoas` → `10-juridico` → `11-governanca`. +`00-fundacao` → `01-estrategia` → `02-mercado` → `03-financeiro` → `04-comercial` → `05-marketing` → `06-produto` (skip if pure service) → `07-operacoes` → `08-tech` (only if there is digital infrastructure) → `09-pessoas` → `10-juridico` → `11-governanca`. -Em cada fase: (a) diga o objetivo em 1 linha, (b) faça as perguntas, (c) monte os conceitos, (d) confirme e escreva, (e) atualize `index.md` raiz e `log.md`. +In each phase: (a) state the objective in 1 line, (b) ask the questions, (c) assemble the concepts, (d) confirm and write, (e) update the root `index.md` and `log.md`. -## Ferramentas (tornam o trabalho determinístico) +## Tools (they make the work deterministic) -Os scripts espelham o que você faria à mão — andaime, validação e índice. Todos stdlib, com `--help` e dados de exemplo embutidos. +The scripts mirror what you would do by hand — scaffold, validation, and index. All stdlib, with `--help` and embedded sample data. ```bash -# 1. Andaime: cria a árvore de pastas OKF + index.md/log.md + index por pasta -python scripts/scaffold_bundle.py "Minha Empresa" --out ./minha-empresa --has-product --has-tech +# 1. Scaffold: creates the OKF folder tree + index.md/log.md + per-folder index +python scripts/scaffold_bundle.py "My Company" --out ./my-company --has-product --has-tech -# 2. Linter OKF: valida type nos conceitos, arquivos reservados sem type, links resolvem -python scripts/okf_linter.py ./minha-empresa +# 2. OKF linter: validates type on concepts, reserved files without type, links resolve +python scripts/okf_linter.py ./my-company -# 3. Gerador de index: (re)gera as tabelas dos index.md + painel de progresso na raiz -python scripts/index_generator.py ./minha-empresa +# 3. Index generator: (re)generates the index.md tables + progress dashboard at the root +python scripts/index_generator.py ./my-company ``` -Fluxo recomendado: **scaffold → entrevista por fase → escreve conceitos → `okf_linter` → `index_generator`**. +Recommended flow: **scaffold → interview per phase → write concepts → `okf_linter` → `index_generator`**. -## Como começar (faça isto ao ser acionado) +## How to start (do this when invoked) -1. Cumprimente em 1 linha e confirme que vai conduzir a construção por fases, gerando um bundle OKF. -2. Pergunte o **nome do bundle** (nome da empresa/pasta raiz). -3. Rode `scaffold_bundle.py` para criar o esqueleto (ou monte as pastas manualmente). -4. **Inicie a FASE 0** (descoberta) — só as perguntas dela. **Pare e aguarde** as respostas. -5. A cada fase: confirme → escreva → rode `okf_linter` + `index_generator` → mostre o "próximo passo sugerido". +1. Greet in 1 line and confirm that you will guide the construction phase by phase, generating an OKF bundle. +2. Ask for the **bundle name** (company name / root folder). +3. Run `scaffold_bundle.py` to create the skeleton (or build the folders manually). +4. **Start PHASE 0** (discovery) — only its questions. **Stop and wait** for the answers. +5. Each phase: confirm → write → run `okf_linter` + `index_generator` → show the "suggested next step". -## Referências +## References -- [`references/okf_conformance.md`](references/okf_conformance.md) — spec OKF v0.1, regras de bundle, frontmatter, arquivos reservados (com fontes) -- [`references/type_vocabulary.md`](references/type_vocabulary.md) — vocabulário de `type` por pasta e conceito + nomenclatura -- [`references/phase_playbook.md`](references/phase_playbook.md) — as 12 fases: objetivo, perguntas (3-5/bloco) e arquivos gerados +- [`references/okf_conformance.md`](references/okf_conformance.md) — OKF v0.1 spec, bundle rules, frontmatter, reserved files (with sources) +- [`references/type_vocabulary.md`](references/type_vocabulary.md) — `type` vocabulary by folder and concept + naming +- [`references/phase_playbook.md`](references/phase_playbook.md) — the 12 phases: objective, questions (3-5/block), and generated files ## Assets -- [`assets/frontmatter_template.md`](assets/frontmatter_template.md) — template de frontmatter de conceito -- [`assets/index_template.md`](assets/index_template.md) / [`assets/log_template.md`](assets/log_template.md) — modelos dos arquivos reservados -- [`assets/exemplo-bundle/`](assets/exemplo-bundle/) — mini bundle de exemplo (`00-fundacao` + `index.md` + `log.md`) +- [`assets/frontmatter_template.md`](assets/frontmatter_template.md) — concept frontmatter template +- [`assets/index_template.md`](assets/index_template.md) / [`assets/log_template.md`](assets/log_template.md) — models for the reserved files +- [`assets/exemplo-bundle/`](assets/exemplo-bundle/) — mini example bundle (`00-fundacao` + `index.md` + `log.md`) --- -**Versão:** 1.0.0 · **Idioma:** pt-BR · **Padrão de saída:** bundle OKF (Open Knowledge Format v0.1) +**Version:** 1.0.0 · **Language:** English · **Output format:** OKF bundle (Open Knowledge Format v0.1) diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md index e713f837..99adc180 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md @@ -1,27 +1,27 @@ --- -type: Fundação -title: Identidade — Cafeteria Aurora -description: Propósito, missão e valores inegociáveis da Cafeteria Aurora -tags: [fundacao, identidade, cultura] +type: Foundation +title: Identity — Aurora Café +description: Purpose, mission, and non-negotiable values of Aurora Café +tags: [foundation, identity, culture] timestamp: 2026-06-19T10:00:00Z -status: rascunho -versao: 0.1 +status: draft +version: 0.1 --- -# Identidade — Cafeteria Aurora +# Identity — Aurora Café -## Propósito +## Purpose -Transformar a primeira hora do dia do bairro num ritual que vale acordar para viver. +Turn the neighborhood's first hour of the day into a ritual worth waking up for. -## Missão +## Mission -Servir café de origem rastreável, num espaço onde as pessoas querem ficar — não só passar. +Serve coffee of traceable origin, in a space where people want to stay — not just pass through. -## Valores inegociáveis +## Non-negotiable values -1. **Grão sempre rastreável.** Sabemos o produtor de cada lote. -2. **Atendimento que lembra o nome.** Relação, não transação. -3. **Desperdício mínimo.** Borra, copos e sobras têm destino. +1. **Always-traceable bean.** We know the producer of every lot. +2. **Service that remembers your name.** Relationship, not transaction. +3. **Minimal waste.** Grounds, cups, and leftovers all have a destination. -> O problema concreto que isso resolve está em [problema-solucao](problema-solucao.md) `[SUPOSIÇÃO: arquivo a criar na FASE 1]`. +> The concrete problem this solves is in [problema-solucao](problema-solucao.md). diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md index 7a811724..411f2fa6 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md @@ -1,9 +1,10 @@ -# 00 — Fundação +# 00 — Foundation -Ancoragem da identidade da Cafeteria Aurora e do problema que ela resolve. +Anchoring Aurora Café's identity and the problem it solves. -## Conceitos +## Concepts -| Conceito | O que é | type | status | +| Concept | What it is | type | status | |---|---|---|---| -| [identidade](identidade.md) | Propósito, missão e valores | Fundação | rascunho | +| [identidade](identidade.md) | Purpose, mission, and values | Foundation | draft | +| [problema-solucao](problema-solucao.md) | The pain solved + how | Problem-Solution | draft | diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/problema-solucao.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/problema-solucao.md new file mode 100644 index 00000000..d8e26ea0 --- /dev/null +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/problema-solucao.md @@ -0,0 +1,21 @@ +--- +type: Problem-Solution +title: Problem & Solution — Aurora Café +description: The concrete pain Aurora Café solves and how it solves it +tags: [foundation, problem-solution] +timestamp: 2026-06-19T10:00:00Z +status: draft +version: 0.1 +--- + +# Problem & Solution — Aurora Café + +## Problem + +The neighborhood has no café worth lingering in — only grab-and-go counters where the coffee is an afterthought and no one learns your name. `[ASSUMPTION: to be confirmed with the founder in PHASE 1]` + +## Solution + +A neighborhood café built around traceable single-origin coffee and a space people *want* to stay in, anchoring the first hour of the day as a ritual. + +> Anchored by the [Identity](identidade.md) — same purpose, mission, and values. diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md index 8f50c9e2..c84e2fae 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md @@ -1,27 +1,27 @@ -# Cafeteria Aurora — Bundle OKF (exemplo) +# Aurora Café — OKF Bundle (example) -Mini bundle de demonstração do formato. Empresa fictícia (cafeteria de bairro) com a FASE 1 (Fundação) preenchida. Mostra os arquivos reservados (`index.md`, `log.md`) e um conceito real com frontmatter `type`. +A mini demonstration bundle of the format. Fictional company (a neighborhood café) with PHASE 1 (Foundation) filled in. Shows the reserved files (`index.md`, `log.md`) and a real concept with frontmatter `type`. -## Dados da empresa +## Company data -- **Nome:** Cafeteria Aurora -- **Estágio:** ideia -- **Modelo:** serviço (cafeteria física) -- **Jurisdição:** Brasil (MEI a definir) +- **Name:** Aurora Café +- **Stage:** idea +- **Model:** service (physical café) +- **Jurisdiction:** Brazil (MEI — *Microempreendedor Individual*, sole-proprietor entity — to be defined) -## Progresso das fases +## Phase progress -| Fase | Área | Status | +| Phase | Area | Status | |---|---|---| -| 0 | Descoberta | ✅ | -| 1 | Fundação | 🚧 | -| 2 | Estratégia | ⬜ | -| 3 | Mercado | ⬜ | +| 0 | Discovery | ✅ | +| 1 | Foundation | 🚧 | +| 2 | Strategy | ⬜ | +| 3 | Market | ⬜ | -**Próximo passo sugerido:** concluir `00-fundacao/problema-solucao.md` e iniciar a FASE 2 (Estratégia). +**Suggested next step:** add `00-fundacao/manifesto.md` to complete PHASE 1, then start PHASE 2 (Strategy). -## Pastas +## Folders -| Pasta | O que é | +| Folder | What it is | |---|---| -| [00-fundacao](00-fundacao/index.md) | Identidade, problema-solução, manifesto | +| [00-fundacao](00-fundacao/index.md) | Identity, problem-solution, manifesto | diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md index a88f509a..90c720a1 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md @@ -1,8 +1,8 @@ -# Log de decisões — Cafeteria Aurora +# Decision log — Aurora Café -## 2026-06-19T10:00:00Z — Bundle criado +## 2026-06-19T10:00:00Z — Bundle created -- **O que mudou:** esqueleto OKF gerado; FASE 0 (descoberta) concluída. -- **Decisão:** posicionar como cafeteria de bairro com foco em grãos especiais. -- **Alternativas descartadas:** modelo de franquia (capital alto), só delivery (sem o ritual presencial que é o diferencial). -- **Motivo:** o valor central é a experiência presencial; franquia diluiria a marca cedo demais. +- **What changed:** OKF skeleton generated; PHASE 0 (discovery) completed. +- **Decision:** position as a neighborhood café focused on specialty beans. +- **Discarded alternatives:** franchise model (high capital), delivery-only (loses the in-person ritual that is the differentiator). +- **Rationale:** the core value is the in-person experience; a franchise would dilute the brand too early. diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/frontmatter_template.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/frontmatter_template.md index ea2ac248..3c8eb174 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/frontmatter_template.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/frontmatter_template.md @@ -1,17 +1,17 @@ --- -type: -title: -description: +type: +title: +description: <1-line summary> tags: [, ] timestamp: 2026-06-19T10:00:00Z -resource: -status: rascunho -versao: 0.1 +resource: +status: draft +version: 0.1 --- -# +# - -Deriva da [Proposta de Valor](../01-estrategia/proposta-de-valor.md). + +Derives from the [Value Proposition](../01-estrategia/proposta-de-valor.md). - + diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/index_template.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/index_template.md index 97fb9371..302d4c8b 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/index_template.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/index_template.md @@ -1,13 +1,13 @@ -# +# -<1 parágrafo: propósito desta pasta/área.> +<1 paragraph: purpose of this folder/area.> -## Conceitos +## Concepts -| Conceito | O que é | type | status | +| Concept | What it is | type | status | |---|---|---|---| -| [identidade](identidade.md) | Propósito, missão, valores | Fundação | rascunho | -| [problema-solucao](problema-solucao.md) | Dor + solução | Problema-Solução | rascunho | +| [identidade](identidade.md) | Purpose, mission, values | Foundation | draft | +| [problema-solucao](problema-solucao.md) | Pain + solution | Problem-Solution | draft | - + diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/log_template.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/log_template.md index 360772f4..4a7fc65d 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/log_template.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/assets/log_template.md @@ -1,10 +1,10 @@ -# Log de decisões +# Decision log -Histórico append-only. Entrada mais recente no topo. Use timestamp ISO 8601. +Append-only history. Most recent entry at the top. Use an ISO 8601 timestamp. -## 2026-06-19T10:00:00Z — Bundle criado +## 2026-06-19T10:00:00Z — Bundle created -- **O que mudou:** esqueleto OKF gerado; FASE 0 (descoberta) concluída. -- **Decisão:** . -- **Alternativas descartadas:** . -- **Motivo:** . +- **What changed:** OKF skeleton generated; PHASE 0 (discovery) completed. +- **Decision:** . +- **Discarded alternatives:** . +- **Rationale:** . diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/okf_conformance.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/okf_conformance.md index f3db191f..512ba59d 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/okf_conformance.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/okf_conformance.md @@ -1,91 +1,91 @@ -# Conformância OKF (Open Knowledge Format v0.1) +# OKF Conformance (Open Knowledge Format v0.1) -Referência das regras que tornam a saída do Arquiteto de Empresa um **bundle OKF conformante** — uma base de conhecimento legível por humanos e por agentes, sem camada de tradução. +Reference for the rules that make the Company Architect's output a **conformant OKF bundle** — a knowledge base readable by humans and by agents, with no translation layer. -## O que é um bundle OKF +## What an OKF bundle is -Um **bundle** é um diretório de arquivos Markdown (`.md`). Cada arquivo representa **um conceito**. A identidade canônica do conceito é o seu **caminho relativo sem a extensão**: +A **bundle** is a directory of Markdown files (`.md`). Each file represents **one concept**. The concept's canonical identity is its **relative path without the extension**: ``` -03-financeiro/unit-economics.md → conceito "03-financeiro/unit-economics" +03-financeiro/unit-economics.md → concept "03-financeiro/unit-economics" ``` -A hierarquia de pastas é só organização física. A estrutura **semântica** real emerge dos **links** entre conceitos (o grafo), que costuma ser mais rica que a árvore de pastas. +The folder hierarchy is just physical organization. The real **semantic** structure emerges from the **links** between concepts (the graph), which is usually richer than the folder tree. -## Regra 1 — Cada arquivo é um conceito +## Rule 1 — Each file is a concept -Um arquivo, um conceito. Não junte "estratégia + financeiro" num só `.md`. Se um conceito fica grande demais, quebre em conceitos menores e ligue-os por links. Isso mantém o grafo navegável e os diffs legíveis em versionamento (git). +One file, one concept. Do not merge "strategy + financial" into a single `.md`. If a concept grows too large, break it into smaller concepts and link them. This keeps the graph navigable and the diffs readable under version control (git). -## Regra 2 — Frontmatter YAML com `type` obrigatório +## Rule 2 — YAML frontmatter with mandatory `type` -Todo arquivo **de conceito** abre com um bloco `---` de frontmatter YAML contendo, no mínimo, o campo `type`. Os demais campos são opcionais e chaves extras são toleradas. +Every **concept** file opens with a `---` YAML frontmatter block containing, at minimum, the `type` field. The other fields are optional and extra keys are tolerated. ```yaml --- -type: Modelo Financeiro # OBRIGATÓRIO — ver type_vocabulary.md +type: Financial Model # REQUIRED — see type_vocabulary.md title: Unit Economics -description: CAC, LTV, payback e margem de contribuição -tags: [financeiro, metricas] -timestamp: 2026-06-19T10:00:00Z # ISO 8601, último update significativo -resource: https://docs.google.com/spreadsheets/d/... # URI canônica, se houver -status: rascunho # extra tolerado: rascunho | em-revisao | aprovado -versao: 0.1 # extra tolerado +description: CAC, LTV, payback, and contribution margin +tags: [financial, metrics] +timestamp: 2026-06-19T10:00:00Z # ISO 8601, last significant update +resource: https://docs.google.com/spreadsheets/d/... # canonical URI, if any +status: draft # tolerated extra: draft | in-review | approved +version: 0.1 # tolerated extra --- ``` -O valor de `type` vem de um vocabulário controlado e consistente — ver [`type_vocabulary.md`](type_vocabulary.md). É o `type` que permite a um agente filtrar "todos os conceitos do tipo `Persona`" sem ler o corpo. +The `type` value comes from a controlled and consistent vocabulary — see [`type_vocabulary.md`](type_vocabulary.md). It is `type` that lets an agent filter "all concepts of type `Persona`" without reading the body. -## Regra 3 — Relações são links markdown no corpo +## Rule 3 — Relations are markdown links in the body -Conceitos se ligam com **links markdown normais** dentro do texto: +Concepts link to each other with **normal markdown links** inside the text: ```markdown -A precificação deriva da [Proposta de Valor](../01-estrategia/proposta-de-valor.md) -e alimenta as [Projeções](projecoes.md). +Pricing derives from the [Value Proposition](../01-estrategia/proposta-de-valor.md) +and feeds the [Projections](projecoes.md). ``` -Esses links formam o **grafo de conhecimento**. **Não** declare dependências como arrays no frontmatter — o grafo vive no corpo, onde o link tem contexto. Prefira caminhos relativos (resilientes a mover o bundle). +These links form the **knowledge graph**. Do **not** declare dependencies as arrays in the frontmatter — the graph lives in the body, where the link has context. Prefer relative paths (resilient to moving the bundle). -## Regra 4 — `index.md` e `log.md` são reservados +## Rule 4 — `index.md` and `log.md` are reserved -Dois nomes têm semântica especial e **não** carregam `type`: +Two names have special semantics and do **not** carry `type`: -- **`index.md`** — listagem/sumário do conteúdo da pasta (progressive disclosure). Cada pasta tem o seu; o `index.md` raiz é o painel do bundle inteiro. -- **`log.md`** — histórico append-only de mudanças e decisões. Normalmente só na raiz. +- **`index.md`** — listing/summary of the folder's content (progressive disclosure). Every folder has its own; the root `index.md` is the dashboard for the whole bundle. +- **`log.md`** — append-only history of changes and decisions. Usually only at the root. -Um linter conformante trata como erro um `index.md`/`log.md` que tenha `type`, e como erro um conceito que **não** tenha. +A conformant linter treats an `index.md`/`log.md` that has a `type` as an error, and a concept that does **not** have one as an error. -## Regra 5 — Legível por humano e máquina +## Rule 5 — Readable by human and machine -Markdown puro. Sem runtime, sem SDK, sem banco. Um humano lê no editor; um agente lê o mesmo arquivo e o frontmatter dá a ele a estrutura. Essa é a tese do formato: **a documentação é a interface**, igual para os dois. +Plain markdown. No runtime, no SDK, no database. A human reads it in an editor; an agent reads the same file and the frontmatter gives it the structure. That is the format's thesis: **the documentation is the interface**, the same for both. -## Convenções de nomenclatura +## Naming conventions -- Minúsculas, sem acento, hífen no lugar de espaço: `unit-economics.md`, `proposta-de-valor.md`. -- SOPs no formato `SOP-01-nome-do-processo.md`. -- Pastas numeradas por fase: `00-fundacao`, `01-estrategia`, … `11-governanca`. -- Toda pasta tem um `index.md`. +- Lowercase, no accents, hyphen instead of space: `unit-economics.md`, `proposta-de-valor.md`. +- SOPs in the format `SOP-01-process-name.md`. +- Folders numbered by phase: `00-fundacao`, `01-estrategia`, … `11-governanca`. +- Every folder has an `index.md`. -## Conteúdo dos arquivos reservados +## Content of the reserved files -- **`index.md` de pasta:** 1 parágrafo de propósito da área + tabela `| Conceito | O que é | type | status |` com link para cada arquivo. -- **`log.md` raiz:** entradas cronológicas `## 2026-06-19T10:00:00Z — ` com: o que mudou, decisão tomada, alternativas descartadas, motivo. +- **Folder `index.md`:** 1 paragraph of the area's purpose + a `| Concept | What it is | type | status |` table with a link to each file. +- **Root `log.md`:** chronological entries `## 2026-06-19T10:00:00Z — ` with: what changed, decision made, discarded alternatives, rationale. -## Checklist de conformância (o que o linter verifica) +## Conformance checklist (what the linter checks) -- [ ] Todo conceito (`.md` que não seja `index.md`/`log.md`) tem frontmatter com `type` não vazio. -- [ ] `type` pertence ao vocabulário de [`type_vocabulary.md`](type_vocabulary.md). -- [ ] `index.md` e `log.md` **não** têm `type`. -- [ ] Links markdown relativos resolvem para arquivos existentes. -- [ ] Nomes em kebab-case, sem acento/espaço. -- [ ] Toda pasta tem `index.md`. +- [ ] Every concept (`.md` that is not `index.md`/`log.md`) has frontmatter with a non-empty `type`. +- [ ] `type` belongs to the vocabulary in [`type_vocabulary.md`](type_vocabulary.md). +- [ ] `index.md` and `log.md` do **not** have `type`. +- [ ] Relative markdown links resolve to existing files. +- [ ] Names in kebab-case, no accents/spaces. +- [ ] Every folder has an `index.md`. -## Fontes +## Sources -1. **Open Knowledge Format (OKF) v0.1** — especificação aberta para empacotar conhecimento como Markdown + YAML frontmatter, originada no contexto Google Cloud / agentes de IA. -2. **agentskills.io — SKILL.md standard** — convenção de `SKILL.md` com frontmatter YAML adotada por Claude Code, Codex, Gemini CLI e Hermes Agent (mesmo contrato deste repositório). -3. **CommonMark Spec** (https://spec.commonmark.org/) — base de Markdown portável usada nos corpos dos conceitos. -4. **YAML 1.2 Spec** (https://yaml.org/spec/1.2.2/) — sintaxe do frontmatter. -5. **ISO 8601** — formato de `timestamp` (`2026-06-19T10:00:00Z`). -6. **Zettelkasten / Niklas Luhmann** — princípio de "uma nota = um conceito" e conhecimento como grafo de links, fundamento conceitual do bundle. -7. **Docs-as-Code** (Anne Gentle, *Docs Like Code*) — documentação versionada, revisada e construída como software; justifica o bundle em git. +1. **Open Knowledge Format (OKF) v0.1** — open specification for packaging knowledge as Markdown + YAML frontmatter, originating in the Google Cloud / AI agents context. +2. **agentskills.io — SKILL.md standard** — the `SKILL.md` convention with YAML frontmatter adopted by Claude Code, Codex, Gemini CLI, and Hermes Agent (the same contract as this repository). +3. **CommonMark Spec** (https://spec.commonmark.org/) — portable Markdown base used in the concept bodies. +4. **YAML 1.2 Spec** (https://yaml.org/spec/1.2.2/) — frontmatter syntax. +5. **ISO 8601** — `timestamp` format (`2026-06-19T10:00:00Z`). +6. **Zettelkasten / Niklas Luhmann** — the "one note = one concept" principle and knowledge as a graph of links, the conceptual foundation of the bundle. +7. **Docs-as-Code** (Anne Gentle, *Docs Like Code*) — documentation versioned, reviewed, and built like software; justifies the bundle in git. diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/phase_playbook.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/phase_playbook.md index 8a883b90..c8a75db2 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/phase_playbook.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/phase_playbook.md @@ -1,99 +1,99 @@ -# Playbook das 12 fases +# 12-phase playbook -Roteiro da entrevista. Conduza **na ordem**. Em cada fase: (a) diga o objetivo em 1 linha, (b) faça as perguntas (3-5 por bloco, numeradas), (c) monte os conceitos, (d) confirme e escreva, (e) atualize `index.md` raiz e `log.md`. Os `type` de cada arquivo estão em [`type_vocabulary.md`](type_vocabulary.md). +The interview script. Run **in order**. In each phase: (a) state the objective in 1 line, (b) ask the questions (3-5 per block, numbered), (c) assemble the concepts, (d) confirm and write, (e) update the root `index.md` and `log.md`. The `type` of each file is in [`type_vocabulary.md`](type_vocabulary.md). --- -## FASE 0 — Descoberta (briefing inicial) -**Objetivo:** entender que empresa é essa antes de criar qualquer arquivo. -**Perguntas:** -1. O que a empresa faz (ou vai fazer)? -2. Em que estágio está (ideia / MVP / operando / escalando)? -3. Modelo (serviço, produto, SaaS, marketplace, infoproduto, híbrido)? -4. Setor e jurisdição (país/estado, tipo de PJ se já houver)? -5. Já tem nome e marca? -**Gera:** o esqueleto de pastas (`scaffold_bundle.py`), o `index.md` raiz preenchido e a 1ª entrada no `log.md`. +## PHASE 0 — Discovery (initial briefing) +**Objective:** understand what company this is before creating any file. +**Questions:** +1. What does the company do (or plan to do)? +2. What stage is it at (idea / MVP / operating / scaling)? +3. Model (service, product, SaaS, marketplace, info-product, hybrid)? +4. Sector and jurisdiction (country/state, entity type if one already exists)? +5. Does it already have a name and brand? +**Generates:** the folder skeleton (`scaffold_bundle.py`), the filled-in root `index.md`, and the 1st entry in `log.md`. -## FASE 1 — Fundação (`00-fundacao`) -**Objetivo:** ancorar identidade e o problema. -**Perguntas:** Por que a empresa existe (propósito além do lucro)? Que dor específica resolve e para quem? Como é o "mundo melhor" que ela cria? Quais 3–5 valores inegociáveis? -**Gera:** `identidade.md`, `problema-solucao.md`, `manifesto.md`. +## PHASE 1 — Foundation (`00-fundacao`) +**Objective:** anchor identity and the problem. +**Questions:** Why does the company exist (purpose beyond profit)? What specific pain does it solve and for whom? What is the "better world" it creates? What are the 3–5 non-negotiable values? +**Generates:** `identidade.md`, `problema-solucao.md`, `manifesto.md`. -## FASE 2 — Estratégia & Modelo de Negócio (`01-estrategia`) -**Objetivo:** desenhar como a empresa cria, entrega e captura valor. -**Perguntas:** Proposta de valor central (o "antes vs depois" do cliente)? Como entra receita (única, recorrência, comissão, ticket)? Estrutura de custos principal? Vantagem que dificulta cópia (dados, marca, rede, processo, custo)? -**Gera:** `business-model-canvas.md`, `proposta-de-valor.md`, `posicionamento.md`, `vantagem-competitiva.md`. +## PHASE 2 — Strategy & Business Model (`01-estrategia`) +**Objective:** design how the company creates, delivers, and captures value. +**Questions:** Core value proposition (the customer's "before vs. after")? How does revenue come in (one-off, recurring, commission, ticket)? Main cost structure? Advantage that makes copying hard (data, brand, network, process, cost)? +**Generates:** `business-model-canvas.md`, `proposta-de-valor.md`, `posicionamento.md`, `vantagem-competitiva.md`. -## FASE 3 — Mercado & Inteligência (`02-mercado`) -**Objetivo:** dimensionar oportunidade e mapear o terreno. -**Perguntas:** 3–5 concorrentes/alternativas reais (inclui "não fazer nada")? Tamanho aproximado do mercado e fatia atingível? Cliente ideal (ICP) em uma frase? Tendências a favor/contra? -**Gera:** `analise-mercado.md` (TAM/SAM/SOM), `concorrentes.md`, `icp-personas.md`, `swot.md`. -> Se autorizado e houver busca, valide tamanho de mercado, concorrentes e tendências; cite fontes no corpo e registre URLs em `resource`. +## PHASE 3 — Market & Intelligence (`02-mercado`) +**Objective:** size the opportunity and map the terrain. +**Questions:** 3–5 real competitors/alternatives (including "do nothing")? Approximate market size and reachable share? Ideal customer (ICP) in one sentence? Trends for/against? +**Generates:** `analise-mercado.md` (TAM/SAM/SOM), `concorrentes.md`, `icp-personas.md`, `swot.md`. +> If authorized and search is available, validate market size, competitors, and trends; cite sources in the body and record URLs in `resource`. -## FASE 4 — Financeiro (`03-financeiro`) -**Objetivo:** transformar o modelo em números. -**Perguntas:** Preço (ou faixa) por produto/serviço e margem estimada? Custos fixos e variáveis mensais? Meta de faturamento nos 12 primeiros meses? Precisa de capital inicial — quanto e de onde? -**Gera:** `modelo-receita.md`, `estrutura-custos.md`, `precificacao.md`, `unit-economics.md` (CAC, LTV, payback, margem), `projecoes.md` (conservador / base / agressivo + break-even). +## PHASE 4 — Financial (`03-financeiro`) +**Objective:** turn the model into numbers. +**Questions:** Price (or range) per product/service and estimated margin? Fixed and variable monthly costs? Revenue target for the first 12 months? Do you need initial capital — how much and from where? +**Generates:** `modelo-receita.md`, `estrutura-custos.md`, `precificacao.md`, `unit-economics.md` (CAC, LTV, payback, margin), `projecoes.md` (conservative / base / aggressive + break-even). -## FASE 5 — Go-to-Market & Comercial (`04-comercial`) -**Objetivo:** definir como a empresa adquire e fecha clientes. -**Perguntas:** Como o cliente descobre você? Caminho do primeiro contato até o pagamento? Quem vende (você, time, autoatendimento)? Meta de novos clientes/mês? -**Gera:** `funil-vendas.md`, `processo-comercial.md`, `playbook-vendas.md`, `metas-comerciais.md`. +## PHASE 5 — Go-to-Market & Sales (`04-comercial`) +**Objective:** define how the company acquires and closes customers. +**Questions:** How does the customer discover you? Path from first contact to payment? Who sells (you, a team, self-service)? Target of new customers/month? +**Generates:** `funil-vendas.md`, `processo-comercial.md`, `playbook-vendas.md`, `metas-comerciais.md`. -## FASE 6 — Marketing & Marca (`05-marketing`) -**Objetivo:** dar voz, narrativa e canais à empresa. -**Perguntas:** Como a marca deve "soar" (técnico, próximo, premium, irreverente)? 3 pilares de conteúdo? Em que canais o cliente já está? Oferta de entrada (isca/lead magnet)? -**Gera:** `branding.md`, `estrategia-conteudo.md`, `canais.md`, `calendario-editorial.md`. +## PHASE 6 — Marketing & Brand (`05-marketing`) +**Objective:** give the company voice, narrative, and channels. +**Questions:** How should the brand "sound" (technical, approachable, premium, irreverent)? 3 content pillars? Which channels is the customer already on? Entry offer (hook/lead magnet)? +**Generates:** `branding.md`, `estrategia-conteudo.md`, `canais.md`, `calendario-editorial.md`. -## FASE 7 — Produto (`06-produto`) — _pular se serviço puro_ -**Objetivo:** especificar o que se entrega como produto. -**Perguntas:** Produto/feature núcleo do MVP? O que fica fora da v1? Como o cliente usa no dia a dia? Como medir que está funcionando? -**Gera:** `prd.md`, `roadmap.md`, `features.md`. +## PHASE 7 — Product (`06-produto`) — _skip if pure service_ +**Objective:** specify what is delivered as a product. +**Questions:** Core product/feature of the MVP? What is out of scope for v1? How does the customer use it day to day? How do you measure that it is working? +**Generates:** `prd.md`, `roadmap.md`, `features.md`. -## FASE 8 — Operações & Processos (`07-operacoes`) -**Objetivo:** garantir que a empresa funcione sem depender só do fundador. -**Perguntas:** 3–5 processos que não podem falhar (entrega, atendimento, cobrança…)? Ferramentas que sustentam a operação? Quem faz o quê? Gargalos atuais? -**Gera:** `processos.md`, `stack-ferramentas.md`, `fornecedores.md` e `sops/SOP-XX-*.md` dos processos críticos. +## PHASE 8 — Operations & Processes (`07-operacoes`) +**Objective:** ensure the company runs without depending only on the founder. +**Questions:** 3–5 processes that cannot fail (delivery, support, billing…)? Tools that sustain the operation? Who does what? Current bottlenecks? +**Generates:** `processos.md`, `stack-ferramentas.md`, `fornecedores.md`, and `sops/SOP-XX-*.md` for the critical processes. -## FASE 9 — Tech & Infra (`08-tech`) — _só se houver infra digital_ -**Objetivo:** desenhar a base técnica. -**Perguntas:** Stack atual ou desejada? Construir vs contratar? Onde roda (cloud/VPS) e qual escala esperada? Integrações obrigatórias? -**Gera:** `arquitetura.md`, `stack.md`, `infraestrutura.md`. +## PHASE 9 — Tech & Infra (`08-tech`) — _only if there is digital infrastructure_ +**Objective:** design the technical base. +**Questions:** Current or desired stack? Build vs. buy? Where it runs (cloud/VPS) and what scale is expected? Mandatory integrations? +**Generates:** `arquitetura.md`, `stack.md`, `infraestrutura.md`. -## FASE 10 — Pessoas & Cultura (`09-pessoas`) -**Objetivo:** estruturar quem toca a empresa. -**Perguntas:** Quem está hoje e qual papel ocupa? 3 próximas contratações por prioridade? Como vocês trabalham (modelo, cadência)? Comportamentos que definem a cultura? -**Gera:** `organograma.md`, `funcoes-responsabilidades.md` (RACI), `cultura.md`, `plano-contratacao.md`. +## PHASE 10 — People & Culture (`09-pessoas`) +**Objective:** structure who runs the company. +**Questions:** Who is here today and what role do they hold? 3 next hires by priority? How do you work (model, cadence)? Behaviors that define the culture? +**Generates:** `organograma.md`, `funcoes-responsabilidades.md` (RACI), `cultura.md`, `plano-contratacao.md`. -## FASE 11 — Jurídico & Compliance (`10-juridico`) -**Objetivo:** dar lastro legal à operação. -**Perguntas:** Tipo de PJ e divisão societária (sócios e %)? Sócios/parceiros com contrato a formalizar? Que dados de clientes você trata (LGPD)? Precisa de licença/regulação do setor? -**Gera:** `estrutura-societaria.md`, `compliance.md`, modelos em `contratos/`. -> Inclua sempre no corpo: *"documentos-base, não substituem revisão de advogado".* +## PHASE 11 — Legal & Compliance (`10-juridico`) +**Objective:** give the operation legal grounding. +**Questions:** Entity type and ownership split (partners and %)? Partners/collaborators with a contract to formalize? What customer data do you handle (data-protection law — e.g. GDPR / LGPD / CCPA, per jurisdiction)? Do you need a sector license/regulation? +**Generates:** `estrutura-societaria.md`, `compliance.md`, templates in `contratos/`. +> Always include in the body: *"these are base documents; they do not replace review by a lawyer".* -## FASE 12 — Governança & OKRs (`11-governanca`) -**Objetivo:** instalar o sistema de pilotagem. -**Perguntas:** Métrica-norte (a única que melhor mede valor entregue)? 3 objetivos do próximo trimestre? Rituais de acompanhamento? Dashboards essenciais? -**Gera:** `okrs.md`, `rituais.md`, `metricas.md` (north star + por área) e fecha o ciclo no `log.md`. +## PHASE 12 — Governance & OKRs (`11-governanca`) +**Objective:** install the steering system. +**Questions:** North-star metric (the single one that best measures value delivered)? 3 objectives for the next quarter? Follow-up rituals? Essential dashboards? +**Generates:** `okrs.md`, `rituais.md`, `metricas.md` (north star + per area) and closes the cycle in `log.md`. --- -## Painel de progresso (manter no `index.md` raiz) +## Progress dashboard (keep in the root `index.md`) -| Fase | Área | Status | +| Phase | Area | Status | |---|---|---| -| 0 | Descoberta | ⬜ | -| 1 | Fundação | ⬜ | -| 2 | Estratégia | ⬜ | -| 3 | Mercado | ⬜ | -| 4 | Financeiro | ⬜ | -| 5 | Comercial | ⬜ | +| 0 | Discovery | ⬜ | +| 1 | Foundation | ⬜ | +| 2 | Strategy | ⬜ | +| 3 | Market | ⬜ | +| 4 | Financial | ⬜ | +| 5 | Sales | ⬜ | | 6 | Marketing | ⬜ | -| 7 | Produto | ⬜ | -| 8 | Operações | ⬜ | +| 7 | Product | ⬜ | +| 8 | Operations | ⬜ | | 9 | Tech | ⬜ | -| 10 | Pessoas | ⬜ | -| 11 | Jurídico | ⬜ | -| 12 | Governança | ⬜ | +| 10 | People | ⬜ | +| 11 | Legal | ⬜ | +| 12 | Governance | ⬜ | -Legenda: ✅ feito · 🚧 em andamento · ⬜ pendente. O `index_generator.py` regenera esta tabela a partir do que existe em disco. +Legend: ✅ done · 🚧 in progress · ⬜ pending. The `index_generator.py` regenerates this table from what exists on disk. diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/type_vocabulary.md b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/type_vocabulary.md index e13e47b4..80c5ef01 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/type_vocabulary.md +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/references/type_vocabulary.md @@ -1,73 +1,73 @@ -# Vocabulário de `type` e estrutura do bundle +# `type` vocabulary and bundle structure -Vocabulário **controlado** do campo `type` do frontmatter. Use exatamente estes valores para que agentes possam filtrar conceitos por tipo de forma consistente. As regras de frontmatter estão em [`okf_conformance.md`](okf_conformance.md). +**Controlled** vocabulary for the frontmatter `type` field. Use exactly these values so agents can filter concepts by type consistently. The frontmatter rules are in [`okf_conformance.md`](okf_conformance.md). -## Tabela pasta → conceito → `type` +## Folder → concept → `type` table -| Pasta | Conceitos (arquivos) | `type` | +| Folder | Concepts (files) | `type` | |---|---|---| -| `00-fundacao` | `identidade`, `manifesto` | `Fundação` | -| `00-fundacao` | `problema-solucao` | `Problema-Solução` | -| `01-estrategia` | `business-model-canvas`, `proposta-de-valor`, `posicionamento`, `vantagem-competitiva` | `Estratégia` | -| `02-mercado` | `analise-mercado`, `concorrentes`, `swot` | `Análise de Mercado` | +| `00-fundacao` | `identidade`, `manifesto` | `Foundation` | +| `00-fundacao` | `problema-solucao` | `Problem-Solution` | +| `01-estrategia` | `business-model-canvas`, `proposta-de-valor`, `posicionamento`, `vantagem-competitiva` | `Strategy` | +| `02-mercado` | `analise-mercado`, `concorrentes`, `swot` | `Market Analysis` | | `02-mercado` | `icp-personas` | `Persona` | -| `03-financeiro` | `modelo-receita`, `estrutura-custos`, `precificacao`, `unit-economics`, `projecoes` | `Modelo Financeiro` | -| `04-comercial` | `funil-vendas`, `processo-comercial`, `metas-comerciais` | `Processo Comercial` | +| `03-financeiro` | `modelo-receita`, `estrutura-custos`, `precificacao`, `unit-economics`, `projecoes` | `Financial Model` | +| `04-comercial` | `funil-vendas`, `processo-comercial`, `metas-comerciais` | `Sales Process` | | `04-comercial` | `playbook-vendas` | `Playbook` | -| `05-marketing` | `branding` | `Marca` | -| `05-marketing` | `estrategia-conteudo`, `canais`, `calendario-editorial` | `Estratégia de Conteúdo` | -| `06-produto` | `prd`, `roadmap`, `features` | `Documento de Produto` | -| `07-operacoes` | `processos` | `Processo` | +| `05-marketing` | `branding` | `Brand` | +| `05-marketing` | `estrategia-conteudo`, `canais`, `calendario-editorial` | `Content Strategy` | +| `06-produto` | `prd`, `roadmap`, `features` | `Product Document` | +| `07-operacoes` | `processos` | `Process` | | `07-operacoes` | `sops/SOP-XX-*` | `Runbook` | -| `07-operacoes` | `stack-ferramentas`, `fornecedores` | `Recurso Operacional` | -| `08-tech` | `arquitetura`, `stack`, `infraestrutura` | `Arquitetura` | -| `09-pessoas` | `organograma`, `funcoes-responsabilidades`, `cultura`, `plano-contratacao` | `Organização` | -| `10-juridico` | `estrutura-societaria`, `compliance`, `contratos/*` | `Documento Jurídico` | +| `07-operacoes` | `stack-ferramentas`, `fornecedores` | `Operational Resource` | +| `08-tech` | `arquitetura`, `stack`, `infraestrutura` | `Architecture` | +| `09-pessoas` | `organograma`, `funcoes-responsabilidades`, `cultura`, `plano-contratacao` | `Organization` | +| `10-juridico` | `estrutura-societaria`, `compliance`, `contratos/*` | `Legal Document` | | `11-governanca` | `okrs` | `OKR` | -| `11-governanca` | `metricas` | `Métrica` | +| `11-governanca` | `metricas` | `Metric` | | `11-governanca` | `rituais` | `Ritual` | -> Os scripts `okf_linter.py` e `scaffold_bundle.py` carregam exatamente este mapa pasta→type. Ao adicionar um conceito novo, ou ele cai num `type` existente, ou você estende o vocabulário aqui **e** nos scripts. +> The `okf_linter.py` and `scaffold_bundle.py` scripts load exactly this folder→type map. When adding a new concept, either it falls into an existing `type`, or you extend the vocabulary here **and** in the scripts. -## Template de frontmatter (todo conceito) +## Frontmatter template (every concept) ```yaml --- -type: <um valor da tabela acima> # OBRIGATÓRIO -title: <Nome de exibição> -description: <Resumo em 1 linha> +type: <one value from the table above> # REQUIRED +title: <Display name> +description: <1-line summary> tags: [<tag>, <tag>] timestamp: 2026-06-19T10:00:00Z # ISO 8601 -resource: <URI canônica, se houver — planilha, doc, repo, dashboard> -status: rascunho # rascunho | em-revisao | aprovado -versao: 0.1 +resource: <canonical URI, if any — spreadsheet, doc, repo, dashboard> +status: draft # draft | in-review | approved +version: 0.1 --- ``` -## Árvore de referência do bundle +## Bundle reference tree ``` -{nome-empresa}/ -├── index.md # painel + listagem raiz (reservado, sem type) -├── log.md # histórico de decisões (reservado, sem type) +{company-name}/ +├── index.md # dashboard + root listing (reserved, no type) +├── log.md # decision history (reserved, no type) ├── 00-fundacao/ # identidade, problema-solucao, manifesto ├── 01-estrategia/ # business-model-canvas, proposta-de-valor, posicionamento, vantagem-competitiva ├── 02-mercado/ # analise-mercado, concorrentes, icp-personas, swot ├── 03-financeiro/ # modelo-receita, estrutura-custos, precificacao, unit-economics, projecoes ├── 04-comercial/ # funil-vendas, processo-comercial, playbook-vendas, metas-comerciais ├── 05-marketing/ # branding, estrategia-conteudo, canais, calendario-editorial -├── 06-produto/ # prd, roadmap, features (pular se serviço puro) +├── 06-produto/ # prd, roadmap, features (skip if pure service) ├── 07-operacoes/ # processos, stack-ferramentas, fornecedores, sops/SOP-XX-* -├── 08-tech/ # arquitetura, stack, infraestrutura (só se houver infra digital) +├── 08-tech/ # arquitetura, stack, infraestrutura (only if there is digital infrastructure) ├── 09-pessoas/ # organograma, funcoes-responsabilidades, cultura, plano-contratacao ├── 10-juridico/ # estrutura-societaria, compliance, contratos/* └── 11-governanca/ # okrs, rituais, metricas ``` -Cada pasta tem o seu `index.md`. As pastas `06-produto` e `08-tech` são condicionais (produto/infra digital). +Every folder has its own `index.md`. The `06-produto` and `08-tech` folders are conditional (digital product/infrastructure). -## Nomenclatura (resumo) +## Naming (summary) -- Minúsculas, sem acento, hífen no lugar de espaço (`unit-economics.md`). -- SOPs: `SOP-01-nome-do-processo.md` (`type: Runbook`). -- Contratos: arquivos sob `10-juridico/contratos/` (`type: Documento Jurídico`); incluir sempre no corpo: *"documentos-base, não substituem revisão de advogado".* +- Lowercase, no accents, hyphen instead of space (`unit-economics.md`). +- SOPs: `SOP-01-process-name.md` (`type: Runbook`). +- Contracts: files under `10-juridico/contratos/` (`type: Legal Document`); always include in the body: *"these are base documents; they do not replace review by a lawyer".* diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/index_generator.py b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/index_generator.py index 545d903d..d2e1eef2 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/index_generator.py +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/index_generator.py @@ -1,19 +1,19 @@ #!/usr/bin/env python3 -"""index_generator.py — (Re)gera as tabelas de conceitos dos index.md de um bundle OKF. +"""index_generator.py — (Re)generates the concept tables of the index.md files of an OKF bundle. -Para cada pasta que tenha um `index.md` com os marcadores -`<!-- okf:index:start -->` ... `<!-- okf:index:end -->`, lê os conceitos irmãos -(.md que não sejam index.md/log.md), extrai title/description/type/status do -frontmatter e regenera a tabela entre os marcadores. +For each folder that has an `index.md` with the markers +`<!-- okf:index:start -->` ... `<!-- okf:index:end -->`, it reads the sibling concepts +(.md that are not index.md/log.md), extracts title/description/type/status from the +frontmatter, and regenerates the table between the markers. -Por padrão é dry-run (mostra o que mudaria). Use --write para gravar. -Determinístico, apenas stdlib. +By default it is a dry-run (shows what would change). Use --write to save. +Deterministic, standard library only. -Uso: - python index_generator.py # demo em bundle de exemplo embutido - python index_generator.py ./minha-empresa # dry-run: mostra tabelas propostas - python index_generator.py ./minha-empresa --write - python index_generator.py ./minha-empresa --output json +Usage: + python index_generator.py # demo on an embedded example bundle + python index_generator.py ./my-company # dry-run: shows proposed tables + python index_generator.py ./my-company --write + python index_generator.py ./my-company --output json python index_generator.py --sample """ @@ -62,7 +62,7 @@ def concept_rows(folder): status = fm.get("status", "") rows.append(f"| [{slug}]({name}) | {what} | {tp} | {status} |") if not rows: - rows = ["<!-- (sem conceitos ainda) -->"] + rows = ["<!-- (no concepts yet) -->"] return rows @@ -70,7 +70,7 @@ def replace_between(text, body): si = text.find(START) ei = text.find(END) if si == -1 or ei == -1 or ei < si: - return None # sem marcadores + return None # no markers new_block = START + "\n" + "\n".join(body) + "\n" + END return text[:si] + new_block + text[ei + len(END):] @@ -115,25 +115,25 @@ def build_sample_bundle(base): root = os.path.join(base, "exemplo") os.makedirs(os.path.join(root, "00-fundacao"), exist_ok=True) with open(os.path.join(root, "00-fundacao", "index.md"), "w", encoding="utf-8") as f: - f.write("# Fundação\n\n## Conceitos\n\n| Conceito | O que é | type | status |\n|---|---|---|---|\n" + f.write("# Foundation\n\n## Concepts\n\n| Concept | What it is | type | status |\n|---|---|---|---|\n" + START + "\n" + END + "\n") with open(os.path.join(root, "00-fundacao", "identidade.md"), "w", encoding="utf-8") as f: - f.write("---\ntype: Fundação\ntitle: Identidade\ndescription: Propósito, missão e valores\n" - "status: rascunho\n---\n\n# Identidade\n") + f.write("---\ntype: Foundation\ntitle: Identity\ndescription: Purpose, mission, and values\n" + "status: draft\n---\n\n# Identity\n") return root def render_text(r): out = ["=" * 64, "INDEX GENERATOR (OKF)", f"Bundle: {r['bundle']}", - f"Modo: {r['mode']} index.md processados: {r['indexes_processed']} " - f"alterados: {r['indexes_changed']}", "=" * 64] + f"Mode: {r['mode']} index.md processed: {r['indexes_processed']} " + f"changed: {r['indexes_changed']}", "=" * 64] for item in r["results"]: - flag = "ALTERA" if item["changed"] else "ok" - out.append(f"\n[{flag}] {item['index']} ({item['concepts']} conceito(s))") + flag = "CHANGE" if item["changed"] else "ok" + out.append(f"\n[{flag}] {item['index']} ({item['concepts']} concept(s))") for row in item["rows"]: out.append(f" {row}") if r["mode"] == "dry-run": - out.append("\n(dry-run: nada gravado. Use --write para aplicar.)") + out.append("\n(dry-run: nothing saved. Use --write to apply.)") return "\n".join(out) @@ -144,25 +144,25 @@ def main(): pass p = argparse.ArgumentParser( - description="(Re)gera as tabelas de conceitos dos index.md de um bundle OKF.", + description="(Re)generates the concept tables of the index.md files of an OKF bundle.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - p.add_argument("path", nargs="?", help="Pasta do bundle (omitido = exemplo embutido)") - p.add_argument("--sample", action="store_true", help="Usa o bundle de exemplo embutido") - p.add_argument("--write", action="store_true", help="Grava as mudanças (default: dry-run)") + p.add_argument("path", nargs="?", help="Bundle folder (omitted = embedded example)") + p.add_argument("--sample", action="store_true", help="Uses the embedded example bundle") + p.add_argument("--write", action="store_true", help="Saves the changes (default: dry-run)") p.add_argument("--output", choices=("text", "json"), default="text") args = p.parse_args() if args.path and not args.sample: if not os.path.isdir(args.path): - print(f"erro: não é uma pasta: {args.path}", file=sys.stderr) + print(f"error: not a folder: {args.path}", file=sys.stderr) return 2 result = process(args.path, args.write) else: with tempfile.TemporaryDirectory() as tmp: result = process(build_sample_bundle(tmp), args.write) - result["bundle"] = "<bundle de exemplo embutido>" + result["bundle"] = "<embedded example bundle>" if args.output == "json": print(json.dumps(result, indent=2, ensure_ascii=False)) diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/okf_linter.py b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/okf_linter.py index 9c406aab..89732c43 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/okf_linter.py +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/okf_linter.py @@ -1,20 +1,20 @@ #!/usr/bin/env python3 -"""okf_linter.py — Valida a conformância OKF (Open Knowledge Format) de um bundle de empresa. +"""okf_linter.py — Validates the OKF (Open Knowledge Format) conformance of a company bundle. -Regras verificadas (ver references/okf_conformance.md): - 1. Todo conceito (.md que não seja index.md/log.md) tem frontmatter com `type` não vazio. [ERRO] - 2. O `type` pertence ao vocabulário controlado. [AVISO] - 3. index.md / log.md NÃO têm `type`. [ERRO] - 4. Links markdown relativos (.md) resolvem para arquivos existentes. [ERRO] - 5. Toda pasta com conceitos tem um index.md. [AVISO] +Rules checked (see references/okf_conformance.md): + 1. Every concept (.md that is not index.md/log.md) has frontmatter with a non-empty `type`. [ERROR] + 2. The `type` belongs to the controlled vocabulary. [WARNING] + 3. index.md / log.md do NOT have a `type`. [ERROR] + 4. Relative markdown links (.md) resolve to existing files. [ERROR] + 5. Every folder with concepts has an index.md. [WARNING] -Sai com código 0 se não houver ERROS (avisos não falham). Determinístico, apenas stdlib. +Exits with code 0 if there are no ERRORS (warnings do not fail). Deterministic, standard library only. -Uso: - python okf_linter.py # lint de um bundle de exemplo embutido (PASS) - python okf_linter.py ./minha-empresa - python okf_linter.py ./minha-empresa --output json - python okf_linter.py --sample # idem ao primeiro +Usage: + python okf_linter.py # lint an embedded example bundle (PASS) + python okf_linter.py ./my-company + python okf_linter.py ./my-company --output json + python okf_linter.py --sample # same as the first """ import argparse @@ -25,11 +25,11 @@ import sys import tempfile VALID_TYPES = { - "Fundação", "Problema-Solução", "Estratégia", "Análise de Mercado", "Persona", - "Modelo Financeiro", "Processo Comercial", "Playbook", "Marca", - "Estratégia de Conteúdo", "Documento de Produto", "Processo", "Runbook", - "Recurso Operacional", "Arquitetura", "Organização", "Documento Jurídico", - "OKR", "Métrica", "Ritual", + "Foundation", "Problem-Solution", "Strategy", "Market Analysis", "Persona", + "Financial Model", "Sales Process", "Playbook", "Brand", + "Content Strategy", "Product Document", "Process", "Runbook", + "Operational Resource", "Architecture", "Organization", "Legal Document", + "OKR", "Metric", "Ritual", } RESERVED = {"index.md", "log.md"} @@ -37,7 +37,7 @@ LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+\.md)(?:#[^)]*)?\)") def parse_frontmatter(text): - """Retorna (tem_frontmatter, dict_simples). Parser mínimo: pares chave: valor de 1º nível.""" + """Returns (has_frontmatter, simple_dict). Minimal parser: top-level key: value pairs.""" if not text.startswith("---"): return False, {} end = text.find("\n---", 3) @@ -53,7 +53,7 @@ def parse_frontmatter(text): def lint(bundle_dir): - findings = [] # cada item: {severity, rule, path, detail} + findings = [] # each item: {severity, rule, path, detail} bundle_dir = os.path.abspath(bundle_dir) md_files = [] @@ -73,7 +73,7 @@ def lint(bundle_dir): with open(full, "r", encoding="utf-8") as f: text = f.read() except (IOError, OSError) as e: - findings.append({"severity": "error", "rule": "leitura", "path": rel, "detail": str(e)}) + findings.append({"severity": "error", "rule": "read", "path": rel, "detail": str(e)}) continue has_fm, fm = parse_frontmatter(text) @@ -81,33 +81,33 @@ def lint(bundle_dir): if is_reserved: if has_fm and fm.get("type"): - findings.append({"severity": "error", "rule": "reservado_sem_type", "path": rel, - "detail": f"{name} é reservado e não pode ter `type`"}) + findings.append({"severity": "error", "rule": "reserved_without_type", "path": rel, + "detail": f"{name} is reserved and cannot have a `type`"}) else: tp = fm.get("type", "").strip() if has_fm else "" if not tp: - findings.append({"severity": "error", "rule": "type_obrigatorio", "path": rel, - "detail": "conceito sem `type` no frontmatter"}) + findings.append({"severity": "error", "rule": "type_required", "path": rel, + "detail": "concept without `type` in frontmatter"}) elif tp not in VALID_TYPES: - findings.append({"severity": "warning", "rule": "type_desconhecido", "path": rel, - "detail": f"`type: {tp}` fora do vocabulário"}) + findings.append({"severity": "warning", "rule": "type_unknown", "path": rel, + "detail": f"`type: {tp}` outside the vocabulary"}) - # links relativos .md resolvem + # relative .md links resolve for m in LINK_RE.finditer(text): target = m.group(1) if target.startswith("http"): continue resolved = os.path.normpath(os.path.join(os.path.dirname(full), target)) if not os.path.exists(resolved): - findings.append({"severity": "error", "rule": "link_quebrado", "path": rel, - "detail": f"link para inexistente: {target}"}) + findings.append({"severity": "error", "rule": "broken_link", "path": rel, + "detail": f"link to nonexistent file: {target}"}) - # pastas com conceitos têm index.md + # folders with concepts have an index.md for d in sorted(dirs_with_concepts): if not os.path.exists(os.path.join(d, "index.md")): rel = os.path.relpath(d, bundle_dir) or "." - findings.append({"severity": "warning", "rule": "index_ausente", "path": rel, - "detail": "pasta com conceitos sem index.md"}) + findings.append({"severity": "warning", "rule": "index_missing", "path": rel, + "detail": "folder with concepts without an index.md"}) errors = [f for f in findings if f["severity"] == "error"] warnings = [f for f in findings if f["severity"] == "warning"] @@ -122,17 +122,17 @@ def lint(bundle_dir): def build_sample_bundle(base): - """Cria um bundle mínimo e CONFORME para demonstração; retorna o caminho.""" + """Creates a minimal and CONFORMANT bundle for demonstration; returns the path.""" root = os.path.join(base, "exemplo") os.makedirs(os.path.join(root, "00-fundacao"), exist_ok=True) with open(os.path.join(root, "index.md"), "w", encoding="utf-8") as f: - f.write("# Exemplo\n\n[Fundação](00-fundacao/index.md)\n") + f.write("# Example\n\n[Foundation](00-fundacao/index.md)\n") with open(os.path.join(root, "log.md"), "w", encoding="utf-8") as f: - f.write("# Log\n\n## 2026-01-01T00:00:00Z — criado\n") + f.write("# Log\n\n## 2026-01-01T00:00:00Z — created\n") with open(os.path.join(root, "00-fundacao", "index.md"), "w", encoding="utf-8") as f: - f.write("# Fundação\n\n[identidade](identidade.md)\n") + f.write("# Foundation\n\n[identidade](identidade.md)\n") with open(os.path.join(root, "00-fundacao", "identidade.md"), "w", encoding="utf-8") as f: - f.write("---\ntype: Fundação\ntitle: Identidade\n---\n\n# Identidade\n\nVolta ao [index](index.md).\n") + f.write("---\ntype: Foundation\ntitle: Identity\n---\n\n# Identity\n\nBack to [index](index.md).\n") return root @@ -141,15 +141,15 @@ def render_text(r): out.append("=" * 64) out.append("OKF LINTER") out.append(f"Bundle: {r['bundle']}") - out.append(f"Arquivos .md: {r['md_files']} Erros: {r['errors']} Avisos: {r['warnings']}") + out.append(f".md files: {r['md_files']} Errors: {r['errors']} Warnings: {r['warnings']}") out.append("=" * 64) if not r["findings"]: - out.append(" Nenhum problema encontrado.") + out.append(" No problems found.") for f in r["findings"]: - tag = "ERRO " if f["severity"] == "error" else "AVISO" + tag = "ERROR" if f["severity"] == "error" else "WARN " out.append(f" [{tag}] {f['rule']:22s} {f['path']}: {f['detail']}") out.append("-" * 64) - out.append(f"Veredito: {r['verdict']}") + out.append(f"Verdict: {r['verdict']}") return "\n".join(out) @@ -160,24 +160,24 @@ def main(): pass p = argparse.ArgumentParser( - description="Valida a conformância OKF de um bundle de empresa.", + description="Validates the OKF conformance of a company bundle.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - p.add_argument("path", nargs="?", help="Pasta do bundle (omitido = bundle de exemplo embutido)") - p.add_argument("--sample", action="store_true", help="Usa o bundle de exemplo embutido") + p.add_argument("path", nargs="?", help="Bundle folder (omitted = embedded example bundle)") + p.add_argument("--sample", action="store_true", help="Uses the embedded example bundle") p.add_argument("--output", choices=("text", "json"), default="text") args = p.parse_args() if args.path and not args.sample: if not os.path.isdir(args.path): - print(f"erro: não é uma pasta: {args.path}", file=sys.stderr) + print(f"error: not a folder: {args.path}", file=sys.stderr) return 2 result = lint(args.path) else: with tempfile.TemporaryDirectory() as tmp: result = lint(build_sample_bundle(tmp)) - result["bundle"] = "<bundle de exemplo embutido>" + result["bundle"] = "<embedded example bundle>" if args.output == "json": print(json.dumps(result, indent=2, ensure_ascii=False)) diff --git a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py index 3fc6256e..c2d34a95 100644 --- a/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py +++ b/c-level-advisor/arquiteto-de-empresa/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py @@ -1,20 +1,20 @@ #!/usr/bin/env python3 -"""scaffold_bundle.py — Cria o esqueleto de um bundle OKF (Open Knowledge Format) para uma empresa. +"""scaffold_bundle.py — Creates the skeleton of an OKF (Open Knowledge Format) bundle for a company. -Gera a árvore de pastas das 12 fases, com `index.md` em cada pasta, mais o -`index.md` raiz (painel das fases) e o `log.md` raiz. Arquivos reservados -(index.md / log.md) NÃO recebem `type`, conforme a spec OKF. +Generates the folder tree of the 12 phases, with an `index.md` in each folder, plus the +root `index.md` (phase dashboard) and the root `log.md`. Reserved files +(index.md / log.md) do NOT receive a `type`, per the OKF spec. -As pastas `06-produto` e `08-tech` só são criadas com --has-product / --has-tech. +The `06-produto` and `08-tech` folders are only created with --has-product / --has-tech. -Determinístico. Sem chamadas de LLM. Apenas stdlib. +Deterministic. No LLM calls. Standard library only. -Uso: - python scaffold_bundle.py # preview (dry-run) de "Empresa Exemplo" - python scaffold_bundle.py "Minha Empresa" --out ./minha-empresa +Usage: + python scaffold_bundle.py # preview (dry-run) of "Example Company" + python scaffold_bundle.py "My Company" --out ./my-company python scaffold_bundle.py "Acme" --out ./acme --has-product --has-tech python scaffold_bundle.py "Acme" --out ./acme --dry-run --output json - python scaffold_bundle.py --sample # idem ao primeiro (preview, não escreve) + python scaffold_bundle.py --sample # same as the first (preview, does not write) """ import argparse @@ -24,38 +24,38 @@ import re import sys import unicodedata -# Pastas das fases. (slug, rótulo, condicional?) +# Phase folders. (slug, label, conditional?) FOLDERS = [ - ("00-fundacao", "Fundação", None), - ("01-estrategia", "Estratégia", None), - ("02-mercado", "Mercado", None), - ("03-financeiro", "Financeiro", None), - ("04-comercial", "Comercial", None), + ("00-fundacao", "Foundation", None), + ("01-estrategia", "Strategy", None), + ("02-mercado", "Market", None), + ("03-financeiro", "Financial", None), + ("04-comercial", "Sales", None), ("05-marketing", "Marketing", None), - ("06-produto", "Produto", "has_product"), - ("07-operacoes", "Operações", None), + ("06-produto", "Product", "has_product"), + ("07-operacoes", "Operations", None), ("08-tech", "Tech", "has_tech"), - ("09-pessoas", "Pessoas", None), - ("10-juridico", "Jurídico", None), - ("11-governanca", "Governança", None), + ("09-pessoas", "People", None), + ("10-juridico", "Legal", None), + ("11-governanca", "Governance", None), ] -# Painel: (nº da fase, área) — fase 0 = descoberta, sem pasta própria. +# Dashboard: (phase number, area) — phase 0 = discovery, no folder of its own. DASHBOARD = [ - (0, "Descoberta"), (1, "Fundação"), (2, "Estratégia"), (3, "Mercado"), - (4, "Financeiro"), (5, "Comercial"), (6, "Marketing"), (7, "Produto"), - (8, "Operações"), (9, "Tech"), (10, "Pessoas"), (11, "Jurídico"), - (12, "Governança"), + (0, "Discovery"), (1, "Foundation"), (2, "Strategy"), (3, "Market"), + (4, "Financial"), (5, "Sales"), (6, "Marketing"), (7, "Product"), + (8, "Operations"), (9, "Tech"), (10, "People"), (11, "Legal"), + (12, "Governance"), ] def slugify(name): - """minúsculas, sem acento, hífen no lugar de espaço.""" + """lowercase, no accents, hyphen instead of space.""" nfkd = unicodedata.normalize("NFKD", name) ascii_only = "".join(c for c in nfkd if not unicodedata.combining(c)) ascii_only = ascii_only.lower() ascii_only = re.sub(r"[^a-z0-9]+", "-", ascii_only).strip("-") - return ascii_only or "empresa" + return ascii_only or "company" def planned_folders(has_product, has_tech): @@ -71,49 +71,49 @@ def root_index(name, folders): rows = "\n".join(f"| {n} | {area} | ⬜ |" for n, area in DASHBOARD) folder_rows = "\n".join(f"| [{slug}]({slug}/index.md) | {label} |" for slug, label in folders) return ( - f"# {name} — Bundle OKF\n\n" - "Empresa documentada como código (Open Knowledge Format v0.1). " - "Cada arquivo é um conceito; relações são links markdown; `index.md`/`log.md` são reservados.\n\n" - "## Dados da empresa\n\n" - f"- **Nome:** {name}\n- **Estágio:** _(a preencher na FASE 0)_\n" - "- **Modelo:** _(serviço / produto / SaaS / marketplace / híbrido)_\n\n" - "## Progresso das 12 fases\n\n" - "| Fase | Área | Status |\n|---|---|---|\n" + f"# {name} — OKF Bundle\n\n" + "Company documented as code (Open Knowledge Format v0.1). " + "Each file is a concept; relations are markdown links; `index.md`/`log.md` are reserved.\n\n" + "## Company data\n\n" + f"- **Name:** {name}\n- **Stage:** _(to be filled in PHASE 0)_\n" + "- **Model:** _(service / product / SaaS / marketplace / hybrid)_\n\n" + "## Progress of the 12 phases\n\n" + "| Phase | Area | Status |\n|---|---|---|\n" f"{rows}\n\n" - "Legenda: ✅ feito · 🚧 em andamento · ⬜ pendente.\n\n" - "**Próximo passo sugerido:** iniciar a FASE 0 (descoberta).\n\n" - "## Pastas\n\n" - "| Pasta | Área |\n|---|---|\n" + "Legend: ✅ done · 🚧 in progress · ⬜ pending.\n\n" + "**Suggested next step:** start PHASE 0 (discovery).\n\n" + "## Folders\n\n" + "| Folder | Area |\n|---|---|\n" f"{folder_rows}\n" ) def root_log(name): return ( - f"# Log de decisões — {name}\n\n" - "Histórico append-only. Entrada mais recente no topo. Timestamp ISO 8601.\n\n" - "## 2026-01-01T00:00:00Z — Bundle criado\n\n" - "- **O que mudou:** esqueleto OKF gerado por scaffold_bundle.py.\n" - "- **Decisão:** _(a registrar)_.\n" - "- **Alternativas descartadas:** _(a registrar)_.\n" - "- **Motivo:** _(a registrar)_.\n" + f"# Decision log — {name}\n\n" + "Append-only history. Most recent entry at the top. ISO 8601 timestamp.\n\n" + "## 2026-01-01T00:00:00Z — Bundle created\n\n" + "- **What changed:** OKF skeleton generated by scaffold_bundle.py.\n" + "- **Decision:** _(to be recorded)_.\n" + "- **Discarded alternatives:** _(to be recorded)_.\n" + "- **Rationale:** _(to be recorded)_.\n" ) def folder_index(label): return ( f"# {label}\n\n" - "_(1 parágrafo: propósito desta área.)_\n\n" - "## Conceitos\n\n" - "| Conceito | O que é | type | status |\n|---|---|---|---|\n" + "_(1 paragraph: purpose of this area.)_\n\n" + "## Concepts\n\n" + "| Concept | What it is | type | status |\n|---|---|---|---|\n" "<!-- okf:index:start -->\n" - "<!-- (sem conceitos ainda — gerado por index_generator.py) -->\n" + "<!-- (no concepts yet — generated by index_generator.py) -->\n" "<!-- okf:index:end -->\n" ) def build_plan(name, out_dir, has_product, has_tech): - """Retorna lista de (caminho_relativo, conteúdo) que seriam escritos.""" + """Returns a list of (relative_path, content) that would be written.""" folders = planned_folders(has_product, has_tech) files = [ ("index.md", root_index(name, folders)), @@ -145,22 +145,22 @@ def main(): pass p = argparse.ArgumentParser( - description="Cria o esqueleto de um bundle OKF para uma empresa.", + description="Creates the skeleton of an OKF bundle for a company.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - p.add_argument("name", nargs="?", help="Nome da empresa (omitido = preview de exemplo)") - p.add_argument("--out", help="Pasta de destino (default: ./<slug-do-nome>)") - p.add_argument("--has-product", action="store_true", help="Inclui a pasta 06-produto") - p.add_argument("--has-tech", action="store_true", help="Inclui a pasta 08-tech") - p.add_argument("--force", action="store_true", help="Sobrescreve arquivos existentes") - p.add_argument("--dry-run", action="store_true", help="Não escreve; só mostra o plano") - p.add_argument("--sample", action="store_true", help="Preview de 'Empresa Exemplo' (não escreve)") + p.add_argument("name", nargs="?", help="Company name (omitted = example preview)") + p.add_argument("--out", help="Destination folder (default: ./<name-slug>)") + p.add_argument("--has-product", action="store_true", help="Includes the 06-produto folder") + p.add_argument("--has-tech", action="store_true", help="Includes the 08-tech folder") + p.add_argument("--force", action="store_true", help="Overwrites existing files") + p.add_argument("--dry-run", action="store_true", help="Does not write; only shows the plan") + p.add_argument("--sample", action="store_true", help="Preview of 'Example Company' (does not write)") p.add_argument("--output", choices=("text", "json"), default="text") args = p.parse_args() sample_mode = args.sample or not args.name - name = args.name or "Empresa Exemplo" + name = args.name or "Example Company" dry = args.dry_run or sample_mode out_dir = args.out or os.path.join(".", slugify(name)) @@ -168,10 +168,10 @@ def main(): if dry: written, skipped = [], [] - action = "PREVIEW (nada escrito)" + action = "PREVIEW (nothing written)" else: written, skipped = write_plan(out_dir, files, args.force) - action = "ESCRITO" + action = "WRITTEN" result = { "name": name, @@ -188,17 +188,17 @@ def main(): print(json.dumps(result, indent=2, ensure_ascii=False)) else: print("=" * 64) - print("SCAFFOLD BUNDLE OKF") - print(f"Empresa: {name}") - print(f"Destino: {out_dir} [{action}]") + print("SCAFFOLD OKF BUNDLE") + print(f"Company: {name}") + print(f"Destination: {out_dir} [{action}]") print("=" * 64) for rel, _ in files: mark = "+" if (dry or rel in written) else ("=" if rel in skipped else " ") print(f" [{mark}] {rel}") if skipped: - print(f"\n{len(skipped)} arquivo(s) preservado(s) (use --force para sobrescrever).") + print(f"\n{len(skipped)} file(s) preserved (use --force to overwrite).") if dry: - print("\n(dry-run/sample: nada foi escrito. Rode com um nome + --out para gerar.)") + print("\n(dry-run/sample: nothing was written. Run with a name + --out to generate.)") return 0 diff --git a/c-level-advisor/skills/arquiteto-de-empresa/SKILL.md b/c-level-advisor/skills/arquiteto-de-empresa/SKILL.md index 4a9f0270..7ee93b9b 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/SKILL.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/SKILL.md @@ -1,6 +1,6 @@ --- name: "arquiteto-de-empresa" -description: "Arquiteto de Empresa: constrói um negócio do zero como bundle OKF (Open Knowledge Format) — uma árvore de arquivos .md versionáveis com frontmatter type, links formando grafo, e index.md/log.md reservados, legível por humanos e por agentes. Conduz o fundador por uma entrevista de 12 fases (fundação, estratégia, mercado, financeiro, comercial, marketing, produto, operações, tech, pessoas, jurídico, governança), uma fase por vez, poucas perguntas por bloco, e gera os conceitos como markdown conformante. Acione quando o usuário quiser criar, estruturar ou documentar uma empresa inteira em pastas e arquivos .md; quando mencionar montar minha empresa do zero, empresa como código, base de conhecimento da empresa para IA ler, wiki da empresa para agentes, OKF, ou bundle de conhecimento. Em português do Brasil." +description: "Company Architect: builds a business from scratch as an OKF (Open Knowledge Format) bundle — a tree of version-controllable .md files with frontmatter type, links forming a graph, and reserved index.md/log.md, readable by humans and agents. Guides the founder through a 12-phase interview (foundation, strategy, market, financial, sales, marketing, product, operations, tech, people, legal, governance), one phase at a time, few questions per block, and generates the concepts as conformant markdown. Trigger when the user wants to create, structure, or document an entire company in folders and .md files; when they mention build my company from scratch, company as code, company knowledge base for AI to read, company wiki for agents, OKF, or knowledge bundle. In English." license: MIT metadata: version: 1.0.0 @@ -9,86 +9,86 @@ metadata: domain: venture-architecture updated: 2026-06-19 python-tools: scaffold_bundle.py, okf_linter.py, index_generator.py - build_pattern: "Persona/entrevista — conduz por fases e materializa um bundle OKF conformante" - language: pt-BR + build_pattern: "Persona/interview — guides through phases and materializes a conformant OKF bundle" + language: en --- -# Arquiteto de Empresa +# Company Architect -Você é o **Arquiteto de Empresa** — um chief of staff sênior que reúne num só agente estrategista de negócios, CFO, CMO, COO e arquiteto de sistemas. Sua missão: transformar a visão do fundador numa **empresa documentada como código** — um **bundle OKF** (Open Knowledge Format), uma árvore de `.md` cruzados por links, lida por humanos e por agentes de IA sem tradução. +You are the **Company Architect** — a senior chief of staff who combines in a single agent a business strategist, CFO, CMO, COO, and systems architect. Your mission: turn the founder's vision into a **company documented as code** — an **OKF bundle** (Open Knowledge Format), a tree of `.md` files cross-linked into a graph, read by humans and by AI agents without translation. -Você **não despeja a empresa de uma vez**. Você **entrevista, valida e constrói por fases** — levanta a planta antes de erguer a obra. +You **do not dump the company all at once**. You **interview, validate, and build phase by phase** — you draw the blueprint before erecting the building. -> **Portabilidade:** skill conduzida por raciocínio + 3 ferramentas Python stdlib (sem APIs externas, sem chamadas de LLM nos scripts). O conteúdo é em português do Brasil. +> **Portability:** a reasoning-driven skill + 3 stdlib Python tools (no external APIs, no LLM calls in the scripts). The content is in English. -## O que você produz: um bundle OKF conformante +## What you produce: a conformant OKF bundle -Regras de conformidade que você **nunca** quebra (detalhe completo em [`references/okf_conformance.md`](references/okf_conformance.md)): +Conformance rules you **never** break (full detail in [`references/okf_conformance.md`](references/okf_conformance.md)): -1. **Bundle = diretório de `.md`.** Cada arquivo é **um conceito**; a identidade é o caminho sem `.md`. -2. **Frontmatter YAML com `type` obrigatório** em todo conceito (vocabulário em [`references/type_vocabulary.md`](references/type_vocabulary.md)). -3. **Relações = links markdown no corpo** (`[Identidade](../00-fundacao/identidade.md)`), formando um grafo — não arrays no frontmatter. -4. **`index.md` e `log.md` são reservados** (listagem da pasta / histórico de decisões) e **não** carregam `type`. -5. **Tudo legível por humano e máquina** — markdown puro, sem runtime, sem SDK. +1. **Bundle = directory of `.md`.** Each file is **one concept**; its identity is the path without `.md`. +2. **YAML frontmatter with mandatory `type`** on every concept (vocabulary in [`references/type_vocabulary.md`](references/type_vocabulary.md)). +3. **Relations = markdown links in the body** (`[Identity](../00-fundacao/identidade.md)`), forming a graph — not arrays in the frontmatter. +4. **`index.md` and `log.md` are reserved** (folder listing / decision history) and do **not** carry `type`. +5. **Everything readable by human and machine** — plain markdown, no runtime, no SDK. -## Princípios operacionais (inquebráveis) +## Operating principles (unbreakable) -1. **Entrevista antes de construir.** Nunca gere um conceito sem ter feito as perguntas da fase. -2. **Uma fase por vez.** Conclua e valide antes de avançar. -3. **Perguntas enxutas.** No máximo **3 a 5 por bloco**, numeradas. Reperguntar só o que faltou. -4. **Presuma com transparência.** Sem resposta, proponha um default, marque `[SUPOSIÇÃO]` no corpo e siga. -5. **Confirme antes de gerar.** Ao fim da fase, mostre os arquivos + `type` que vai criar e peça "ok". -6. **Estado sempre visível.** Mantenha o `index.md` raiz como painel: dados da empresa, tabela das 12 fases (✅/🚧/⬜) e "próximo passo sugerido". -7. **Decisão rastreável.** Toda decisão relevante vira entrada no `log.md` raiz (timestamp ISO 8601 + o que mudou + alternativas descartadas + motivo). -8. **Grafo, não silos.** Sempre que conceitos se relacionam, crie o link markdown. -9. **PT-BR denso e direto.** Saídas estruturadas, prontas para uso. -10. **Escreva os arquivos de verdade.** Com acesso a disco, grave os `.md`. Sem disco, entregue cada arquivo em bloco de código com seu caminho. +1. **Interview before building.** Never generate a concept without having asked the phase's questions. +2. **One phase at a time.** Complete and validate before advancing. +3. **Lean questions.** At most **3 to 5 per block**, numbered. Re-ask only what was missing. +4. **Assume transparently.** With no answer, propose a default, mark `[ASSUMPTION]` in the body, and proceed. +5. **Confirm before generating.** At the end of the phase, show the files + `type` you will create and ask for "ok". +6. **State always visible.** Keep the root `index.md` as a dashboard: company data, table of the 12 phases (✅/🚧/⬜), and "suggested next step". +7. **Traceable decisions.** Every relevant decision becomes an entry in the root `log.md` (ISO 8601 timestamp + what changed + discarded alternatives + rationale). +8. **Graph, not silos.** Whenever concepts relate, create the markdown link. +9. **Dense, direct English.** Structured outputs, ready to use. +10. **Actually write the files.** With disk access, write the `.md` files. Without disk, deliver each file in a code block with its path. -## Roteiro de 12 fases +## 12-phase script -Conduza nesta ordem; o detalhe de objetivo, perguntas e arquivos gerados de cada fase está em [`references/phase_playbook.md`](references/phase_playbook.md): +Run in this order; the objective, questions, and generated files of each phase are detailed in [`references/phase_playbook.md`](references/phase_playbook.md): -`00-fundacao` → `01-estrategia` → `02-mercado` → `03-financeiro` → `04-comercial` → `05-marketing` → `06-produto` (pular se serviço puro) → `07-operacoes` → `08-tech` (só se houver infra digital) → `09-pessoas` → `10-juridico` → `11-governanca`. +`00-fundacao` → `01-estrategia` → `02-mercado` → `03-financeiro` → `04-comercial` → `05-marketing` → `06-produto` (skip if pure service) → `07-operacoes` → `08-tech` (only if there is digital infrastructure) → `09-pessoas` → `10-juridico` → `11-governanca`. -Em cada fase: (a) diga o objetivo em 1 linha, (b) faça as perguntas, (c) monte os conceitos, (d) confirme e escreva, (e) atualize `index.md` raiz e `log.md`. +In each phase: (a) state the objective in 1 line, (b) ask the questions, (c) assemble the concepts, (d) confirm and write, (e) update the root `index.md` and `log.md`. -## Ferramentas (tornam o trabalho determinístico) +## Tools (they make the work deterministic) -Os scripts espelham o que você faria à mão — andaime, validação e índice. Todos stdlib, com `--help` e dados de exemplo embutidos. +The scripts mirror what you would do by hand — scaffold, validation, and index. All stdlib, with `--help` and embedded sample data. ```bash -# 1. Andaime: cria a árvore de pastas OKF + index.md/log.md + index por pasta -python scripts/scaffold_bundle.py "Minha Empresa" --out ./minha-empresa --has-product --has-tech +# 1. Scaffold: creates the OKF folder tree + index.md/log.md + per-folder index +python scripts/scaffold_bundle.py "My Company" --out ./my-company --has-product --has-tech -# 2. Linter OKF: valida type nos conceitos, arquivos reservados sem type, links resolvem -python scripts/okf_linter.py ./minha-empresa +# 2. OKF linter: validates type on concepts, reserved files without type, links resolve +python scripts/okf_linter.py ./my-company -# 3. Gerador de index: (re)gera as tabelas dos index.md + painel de progresso na raiz -python scripts/index_generator.py ./minha-empresa +# 3. Index generator: (re)generates the index.md tables + progress dashboard at the root +python scripts/index_generator.py ./my-company ``` -Fluxo recomendado: **scaffold → entrevista por fase → escreve conceitos → `okf_linter` → `index_generator`**. +Recommended flow: **scaffold → interview per phase → write concepts → `okf_linter` → `index_generator`**. -## Como começar (faça isto ao ser acionado) +## How to start (do this when invoked) -1. Cumprimente em 1 linha e confirme que vai conduzir a construção por fases, gerando um bundle OKF. -2. Pergunte o **nome do bundle** (nome da empresa/pasta raiz). -3. Rode `scaffold_bundle.py` para criar o esqueleto (ou monte as pastas manualmente). -4. **Inicie a FASE 0** (descoberta) — só as perguntas dela. **Pare e aguarde** as respostas. -5. A cada fase: confirme → escreva → rode `okf_linter` + `index_generator` → mostre o "próximo passo sugerido". +1. Greet in 1 line and confirm that you will guide the construction phase by phase, generating an OKF bundle. +2. Ask for the **bundle name** (company name / root folder). +3. Run `scaffold_bundle.py` to create the skeleton (or build the folders manually). +4. **Start PHASE 0** (discovery) — only its questions. **Stop and wait** for the answers. +5. Each phase: confirm → write → run `okf_linter` + `index_generator` → show the "suggested next step". -## Referências +## References -- [`references/okf_conformance.md`](references/okf_conformance.md) — spec OKF v0.1, regras de bundle, frontmatter, arquivos reservados (com fontes) -- [`references/type_vocabulary.md`](references/type_vocabulary.md) — vocabulário de `type` por pasta e conceito + nomenclatura -- [`references/phase_playbook.md`](references/phase_playbook.md) — as 12 fases: objetivo, perguntas (3-5/bloco) e arquivos gerados +- [`references/okf_conformance.md`](references/okf_conformance.md) — OKF v0.1 spec, bundle rules, frontmatter, reserved files (with sources) +- [`references/type_vocabulary.md`](references/type_vocabulary.md) — `type` vocabulary by folder and concept + naming +- [`references/phase_playbook.md`](references/phase_playbook.md) — the 12 phases: objective, questions (3-5/block), and generated files ## Assets -- [`assets/frontmatter_template.md`](assets/frontmatter_template.md) — template de frontmatter de conceito -- [`assets/index_template.md`](assets/index_template.md) / [`assets/log_template.md`](assets/log_template.md) — modelos dos arquivos reservados -- [`assets/exemplo-bundle/`](assets/exemplo-bundle/) — mini bundle de exemplo (`00-fundacao` + `index.md` + `log.md`) +- [`assets/frontmatter_template.md`](assets/frontmatter_template.md) — concept frontmatter template +- [`assets/index_template.md`](assets/index_template.md) / [`assets/log_template.md`](assets/log_template.md) — models for the reserved files +- [`assets/exemplo-bundle/`](assets/exemplo-bundle/) — mini example bundle (`00-fundacao` + `index.md` + `log.md`) --- -**Versão:** 1.0.0 · **Idioma:** pt-BR · **Padrão de saída:** bundle OKF (Open Knowledge Format v0.1) +**Version:** 1.0.0 · **Language:** English · **Output format:** OKF bundle (Open Knowledge Format v0.1) diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md index e713f837..99adc180 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/identidade.md @@ -1,27 +1,27 @@ --- -type: Fundação -title: Identidade — Cafeteria Aurora -description: Propósito, missão e valores inegociáveis da Cafeteria Aurora -tags: [fundacao, identidade, cultura] +type: Foundation +title: Identity — Aurora Café +description: Purpose, mission, and non-negotiable values of Aurora Café +tags: [foundation, identity, culture] timestamp: 2026-06-19T10:00:00Z -status: rascunho -versao: 0.1 +status: draft +version: 0.1 --- -# Identidade — Cafeteria Aurora +# Identity — Aurora Café -## Propósito +## Purpose -Transformar a primeira hora do dia do bairro num ritual que vale acordar para viver. +Turn the neighborhood's first hour of the day into a ritual worth waking up for. -## Missão +## Mission -Servir café de origem rastreável, num espaço onde as pessoas querem ficar — não só passar. +Serve coffee of traceable origin, in a space where people want to stay — not just pass through. -## Valores inegociáveis +## Non-negotiable values -1. **Grão sempre rastreável.** Sabemos o produtor de cada lote. -2. **Atendimento que lembra o nome.** Relação, não transação. -3. **Desperdício mínimo.** Borra, copos e sobras têm destino. +1. **Always-traceable bean.** We know the producer of every lot. +2. **Service that remembers your name.** Relationship, not transaction. +3. **Minimal waste.** Grounds, cups, and leftovers all have a destination. -> O problema concreto que isso resolve está em [problema-solucao](problema-solucao.md) `[SUPOSIÇÃO: arquivo a criar na FASE 1]`. +> The concrete problem this solves is in [problema-solucao](problema-solucao.md). diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md index 7a811724..411f2fa6 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/index.md @@ -1,9 +1,10 @@ -# 00 — Fundação +# 00 — Foundation -Ancoragem da identidade da Cafeteria Aurora e do problema que ela resolve. +Anchoring Aurora Café's identity and the problem it solves. -## Conceitos +## Concepts -| Conceito | O que é | type | status | +| Concept | What it is | type | status | |---|---|---|---| -| [identidade](identidade.md) | Propósito, missão e valores | Fundação | rascunho | +| [identidade](identidade.md) | Purpose, mission, and values | Foundation | draft | +| [problema-solucao](problema-solucao.md) | The pain solved + how | Problem-Solution | draft | diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/problema-solucao.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/problema-solucao.md new file mode 100644 index 00000000..d8e26ea0 --- /dev/null +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/00-fundacao/problema-solucao.md @@ -0,0 +1,21 @@ +--- +type: Problem-Solution +title: Problem & Solution — Aurora Café +description: The concrete pain Aurora Café solves and how it solves it +tags: [foundation, problem-solution] +timestamp: 2026-06-19T10:00:00Z +status: draft +version: 0.1 +--- + +# Problem & Solution — Aurora Café + +## Problem + +The neighborhood has no café worth lingering in — only grab-and-go counters where the coffee is an afterthought and no one learns your name. `[ASSUMPTION: to be confirmed with the founder in PHASE 1]` + +## Solution + +A neighborhood café built around traceable single-origin coffee and a space people *want* to stay in, anchoring the first hour of the day as a ritual. + +> Anchored by the [Identity](identidade.md) — same purpose, mission, and values. diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md index 8f50c9e2..c84e2fae 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/index.md @@ -1,27 +1,27 @@ -# Cafeteria Aurora — Bundle OKF (exemplo) +# Aurora Café — OKF Bundle (example) -Mini bundle de demonstração do formato. Empresa fictícia (cafeteria de bairro) com a FASE 1 (Fundação) preenchida. Mostra os arquivos reservados (`index.md`, `log.md`) e um conceito real com frontmatter `type`. +A mini demonstration bundle of the format. Fictional company (a neighborhood café) with PHASE 1 (Foundation) filled in. Shows the reserved files (`index.md`, `log.md`) and a real concept with frontmatter `type`. -## Dados da empresa +## Company data -- **Nome:** Cafeteria Aurora -- **Estágio:** ideia -- **Modelo:** serviço (cafeteria física) -- **Jurisdição:** Brasil (MEI a definir) +- **Name:** Aurora Café +- **Stage:** idea +- **Model:** service (physical café) +- **Jurisdiction:** Brazil (MEI — *Microempreendedor Individual*, sole-proprietor entity — to be defined) -## Progresso das fases +## Phase progress -| Fase | Área | Status | +| Phase | Area | Status | |---|---|---| -| 0 | Descoberta | ✅ | -| 1 | Fundação | 🚧 | -| 2 | Estratégia | ⬜ | -| 3 | Mercado | ⬜ | +| 0 | Discovery | ✅ | +| 1 | Foundation | 🚧 | +| 2 | Strategy | ⬜ | +| 3 | Market | ⬜ | -**Próximo passo sugerido:** concluir `00-fundacao/problema-solucao.md` e iniciar a FASE 2 (Estratégia). +**Suggested next step:** add `00-fundacao/manifesto.md` to complete PHASE 1, then start PHASE 2 (Strategy). -## Pastas +## Folders -| Pasta | O que é | +| Folder | What it is | |---|---| -| [00-fundacao](00-fundacao/index.md) | Identidade, problema-solução, manifesto | +| [00-fundacao](00-fundacao/index.md) | Identity, problem-solution, manifesto | diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md index a88f509a..90c720a1 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/exemplo-bundle/log.md @@ -1,8 +1,8 @@ -# Log de decisões — Cafeteria Aurora +# Decision log — Aurora Café -## 2026-06-19T10:00:00Z — Bundle criado +## 2026-06-19T10:00:00Z — Bundle created -- **O que mudou:** esqueleto OKF gerado; FASE 0 (descoberta) concluída. -- **Decisão:** posicionar como cafeteria de bairro com foco em grãos especiais. -- **Alternativas descartadas:** modelo de franquia (capital alto), só delivery (sem o ritual presencial que é o diferencial). -- **Motivo:** o valor central é a experiência presencial; franquia diluiria a marca cedo demais. +- **What changed:** OKF skeleton generated; PHASE 0 (discovery) completed. +- **Decision:** position as a neighborhood café focused on specialty beans. +- **Discarded alternatives:** franchise model (high capital), delivery-only (loses the in-person ritual that is the differentiator). +- **Rationale:** the core value is the in-person experience; a franchise would dilute the brand too early. diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/frontmatter_template.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/frontmatter_template.md index ea2ac248..3c8eb174 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/frontmatter_template.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/frontmatter_template.md @@ -1,17 +1,17 @@ --- -type: <um valor do vocabulário — ver references/type_vocabulary.md> -title: <Nome de exibição do conceito> -description: <Resumo em 1 linha> +type: <one value from the vocabulary — see references/type_vocabulary.md> +title: <Concept display name> +description: <1-line summary> tags: [<tag>, <tag>] timestamp: 2026-06-19T10:00:00Z -resource: <URI canônica, se houver — planilha, doc, repo, dashboard> -status: rascunho -versao: 0.1 +resource: <canonical URI, if any — spreadsheet, doc, repo, dashboard> +status: draft +version: 0.1 --- -# <Título do conceito> +# <Concept title> -<Corpo em markdown. Ligue a outros conceitos com links relativos, ex.:> -Deriva da [Proposta de Valor](../01-estrategia/proposta-de-valor.md). +<Body in markdown. Link to other concepts with relative links, e.g.:> +Derives from the [Value Proposition](../01-estrategia/proposta-de-valor.md). -<Marque suposições com [SUPOSIÇÃO] quando o fundador não tiver respondido.> +<Mark assumptions with [ASSUMPTION] when the founder has not answered.> diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/index_template.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/index_template.md index 97fb9371..302d4c8b 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/index_template.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/index_template.md @@ -1,13 +1,13 @@ -# <Nome da Área ou da Empresa> +# <Area or Company Name> -<1 parágrafo: propósito desta pasta/área.> +<1 paragraph: purpose of this folder/area.> -## Conceitos +## Concepts -| Conceito | O que é | type | status | +| Concept | What it is | type | status | |---|---|---|---| -| [identidade](identidade.md) | Propósito, missão, valores | Fundação | rascunho | -| [problema-solucao](problema-solucao.md) | Dor + solução | Problema-Solução | rascunho | +| [identidade](identidade.md) | Purpose, mission, values | Foundation | draft | +| [problema-solucao](problema-solucao.md) | Pain + solution | Problem-Solution | draft | -<No index.md RAIZ, inclua também o painel das 12 fases (ver references/phase_playbook.md) -e a linha "Próximo passo sugerido: ...".> +<In the ROOT index.md, also include the 12-phase dashboard (see references/phase_playbook.md) +and the line "Suggested next step: ...".> diff --git a/c-level-advisor/skills/arquiteto-de-empresa/assets/log_template.md b/c-level-advisor/skills/arquiteto-de-empresa/assets/log_template.md index 360772f4..4a7fc65d 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/assets/log_template.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/assets/log_template.md @@ -1,10 +1,10 @@ -# Log de decisões +# Decision log -Histórico append-only. Entrada mais recente no topo. Use timestamp ISO 8601. +Append-only history. Most recent entry at the top. Use an ISO 8601 timestamp. -## 2026-06-19T10:00:00Z — Bundle criado +## 2026-06-19T10:00:00Z — Bundle created -- **O que mudou:** esqueleto OKF gerado; FASE 0 (descoberta) concluída. -- **Decisão:** <a decisão tomada>. -- **Alternativas descartadas:** <opções consideradas e por que caíram>. -- **Motivo:** <justificativa>. +- **What changed:** OKF skeleton generated; PHASE 0 (discovery) completed. +- **Decision:** <the decision made>. +- **Discarded alternatives:** <options considered and why they were dropped>. +- **Rationale:** <justification>. diff --git a/c-level-advisor/skills/arquiteto-de-empresa/references/okf_conformance.md b/c-level-advisor/skills/arquiteto-de-empresa/references/okf_conformance.md index f3db191f..512ba59d 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/references/okf_conformance.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/references/okf_conformance.md @@ -1,91 +1,91 @@ -# Conformância OKF (Open Knowledge Format v0.1) +# OKF Conformance (Open Knowledge Format v0.1) -Referência das regras que tornam a saída do Arquiteto de Empresa um **bundle OKF conformante** — uma base de conhecimento legível por humanos e por agentes, sem camada de tradução. +Reference for the rules that make the Company Architect's output a **conformant OKF bundle** — a knowledge base readable by humans and by agents, with no translation layer. -## O que é um bundle OKF +## What an OKF bundle is -Um **bundle** é um diretório de arquivos Markdown (`.md`). Cada arquivo representa **um conceito**. A identidade canônica do conceito é o seu **caminho relativo sem a extensão**: +A **bundle** is a directory of Markdown files (`.md`). Each file represents **one concept**. The concept's canonical identity is its **relative path without the extension**: ``` -03-financeiro/unit-economics.md → conceito "03-financeiro/unit-economics" +03-financeiro/unit-economics.md → concept "03-financeiro/unit-economics" ``` -A hierarquia de pastas é só organização física. A estrutura **semântica** real emerge dos **links** entre conceitos (o grafo), que costuma ser mais rica que a árvore de pastas. +The folder hierarchy is just physical organization. The real **semantic** structure emerges from the **links** between concepts (the graph), which is usually richer than the folder tree. -## Regra 1 — Cada arquivo é um conceito +## Rule 1 — Each file is a concept -Um arquivo, um conceito. Não junte "estratégia + financeiro" num só `.md`. Se um conceito fica grande demais, quebre em conceitos menores e ligue-os por links. Isso mantém o grafo navegável e os diffs legíveis em versionamento (git). +One file, one concept. Do not merge "strategy + financial" into a single `.md`. If a concept grows too large, break it into smaller concepts and link them. This keeps the graph navigable and the diffs readable under version control (git). -## Regra 2 — Frontmatter YAML com `type` obrigatório +## Rule 2 — YAML frontmatter with mandatory `type` -Todo arquivo **de conceito** abre com um bloco `---` de frontmatter YAML contendo, no mínimo, o campo `type`. Os demais campos são opcionais e chaves extras são toleradas. +Every **concept** file opens with a `---` YAML frontmatter block containing, at minimum, the `type` field. The other fields are optional and extra keys are tolerated. ```yaml --- -type: Modelo Financeiro # OBRIGATÓRIO — ver type_vocabulary.md +type: Financial Model # REQUIRED — see type_vocabulary.md title: Unit Economics -description: CAC, LTV, payback e margem de contribuição -tags: [financeiro, metricas] -timestamp: 2026-06-19T10:00:00Z # ISO 8601, último update significativo -resource: https://docs.google.com/spreadsheets/d/... # URI canônica, se houver -status: rascunho # extra tolerado: rascunho | em-revisao | aprovado -versao: 0.1 # extra tolerado +description: CAC, LTV, payback, and contribution margin +tags: [financial, metrics] +timestamp: 2026-06-19T10:00:00Z # ISO 8601, last significant update +resource: https://docs.google.com/spreadsheets/d/... # canonical URI, if any +status: draft # tolerated extra: draft | in-review | approved +version: 0.1 # tolerated extra --- ``` -O valor de `type` vem de um vocabulário controlado e consistente — ver [`type_vocabulary.md`](type_vocabulary.md). É o `type` que permite a um agente filtrar "todos os conceitos do tipo `Persona`" sem ler o corpo. +The `type` value comes from a controlled and consistent vocabulary — see [`type_vocabulary.md`](type_vocabulary.md). It is `type` that lets an agent filter "all concepts of type `Persona`" without reading the body. -## Regra 3 — Relações são links markdown no corpo +## Rule 3 — Relations are markdown links in the body -Conceitos se ligam com **links markdown normais** dentro do texto: +Concepts link to each other with **normal markdown links** inside the text: ```markdown -A precificação deriva da [Proposta de Valor](../01-estrategia/proposta-de-valor.md) -e alimenta as [Projeções](projecoes.md). +Pricing derives from the [Value Proposition](../01-estrategia/proposta-de-valor.md) +and feeds the [Projections](projecoes.md). ``` -Esses links formam o **grafo de conhecimento**. **Não** declare dependências como arrays no frontmatter — o grafo vive no corpo, onde o link tem contexto. Prefira caminhos relativos (resilientes a mover o bundle). +These links form the **knowledge graph**. Do **not** declare dependencies as arrays in the frontmatter — the graph lives in the body, where the link has context. Prefer relative paths (resilient to moving the bundle). -## Regra 4 — `index.md` e `log.md` são reservados +## Rule 4 — `index.md` and `log.md` are reserved -Dois nomes têm semântica especial e **não** carregam `type`: +Two names have special semantics and do **not** carry `type`: -- **`index.md`** — listagem/sumário do conteúdo da pasta (progressive disclosure). Cada pasta tem o seu; o `index.md` raiz é o painel do bundle inteiro. -- **`log.md`** — histórico append-only de mudanças e decisões. Normalmente só na raiz. +- **`index.md`** — listing/summary of the folder's content (progressive disclosure). Every folder has its own; the root `index.md` is the dashboard for the whole bundle. +- **`log.md`** — append-only history of changes and decisions. Usually only at the root. -Um linter conformante trata como erro um `index.md`/`log.md` que tenha `type`, e como erro um conceito que **não** tenha. +A conformant linter treats an `index.md`/`log.md` that has a `type` as an error, and a concept that does **not** have one as an error. -## Regra 5 — Legível por humano e máquina +## Rule 5 — Readable by human and machine -Markdown puro. Sem runtime, sem SDK, sem banco. Um humano lê no editor; um agente lê o mesmo arquivo e o frontmatter dá a ele a estrutura. Essa é a tese do formato: **a documentação é a interface**, igual para os dois. +Plain markdown. No runtime, no SDK, no database. A human reads it in an editor; an agent reads the same file and the frontmatter gives it the structure. That is the format's thesis: **the documentation is the interface**, the same for both. -## Convenções de nomenclatura +## Naming conventions -- Minúsculas, sem acento, hífen no lugar de espaço: `unit-economics.md`, `proposta-de-valor.md`. -- SOPs no formato `SOP-01-nome-do-processo.md`. -- Pastas numeradas por fase: `00-fundacao`, `01-estrategia`, … `11-governanca`. -- Toda pasta tem um `index.md`. +- Lowercase, no accents, hyphen instead of space: `unit-economics.md`, `proposta-de-valor.md`. +- SOPs in the format `SOP-01-process-name.md`. +- Folders numbered by phase: `00-fundacao`, `01-estrategia`, … `11-governanca`. +- Every folder has an `index.md`. -## Conteúdo dos arquivos reservados +## Content of the reserved files -- **`index.md` de pasta:** 1 parágrafo de propósito da área + tabela `| Conceito | O que é | type | status |` com link para cada arquivo. -- **`log.md` raiz:** entradas cronológicas `## 2026-06-19T10:00:00Z — <título>` com: o que mudou, decisão tomada, alternativas descartadas, motivo. +- **Folder `index.md`:** 1 paragraph of the area's purpose + a `| Concept | What it is | type | status |` table with a link to each file. +- **Root `log.md`:** chronological entries `## 2026-06-19T10:00:00Z — <title>` with: what changed, decision made, discarded alternatives, rationale. -## Checklist de conformância (o que o linter verifica) +## Conformance checklist (what the linter checks) -- [ ] Todo conceito (`.md` que não seja `index.md`/`log.md`) tem frontmatter com `type` não vazio. -- [ ] `type` pertence ao vocabulário de [`type_vocabulary.md`](type_vocabulary.md). -- [ ] `index.md` e `log.md` **não** têm `type`. -- [ ] Links markdown relativos resolvem para arquivos existentes. -- [ ] Nomes em kebab-case, sem acento/espaço. -- [ ] Toda pasta tem `index.md`. +- [ ] Every concept (`.md` that is not `index.md`/`log.md`) has frontmatter with a non-empty `type`. +- [ ] `type` belongs to the vocabulary in [`type_vocabulary.md`](type_vocabulary.md). +- [ ] `index.md` and `log.md` do **not** have `type`. +- [ ] Relative markdown links resolve to existing files. +- [ ] Names in kebab-case, no accents/spaces. +- [ ] Every folder has an `index.md`. -## Fontes +## Sources -1. **Open Knowledge Format (OKF) v0.1** — especificação aberta para empacotar conhecimento como Markdown + YAML frontmatter, originada no contexto Google Cloud / agentes de IA. -2. **agentskills.io — SKILL.md standard** — convenção de `SKILL.md` com frontmatter YAML adotada por Claude Code, Codex, Gemini CLI e Hermes Agent (mesmo contrato deste repositório). -3. **CommonMark Spec** (https://spec.commonmark.org/) — base de Markdown portável usada nos corpos dos conceitos. -4. **YAML 1.2 Spec** (https://yaml.org/spec/1.2.2/) — sintaxe do frontmatter. -5. **ISO 8601** — formato de `timestamp` (`2026-06-19T10:00:00Z`). -6. **Zettelkasten / Niklas Luhmann** — princípio de "uma nota = um conceito" e conhecimento como grafo de links, fundamento conceitual do bundle. -7. **Docs-as-Code** (Anne Gentle, *Docs Like Code*) — documentação versionada, revisada e construída como software; justifica o bundle em git. +1. **Open Knowledge Format (OKF) v0.1** — open specification for packaging knowledge as Markdown + YAML frontmatter, originating in the Google Cloud / AI agents context. +2. **agentskills.io — SKILL.md standard** — the `SKILL.md` convention with YAML frontmatter adopted by Claude Code, Codex, Gemini CLI, and Hermes Agent (the same contract as this repository). +3. **CommonMark Spec** (https://spec.commonmark.org/) — portable Markdown base used in the concept bodies. +4. **YAML 1.2 Spec** (https://yaml.org/spec/1.2.2/) — frontmatter syntax. +5. **ISO 8601** — `timestamp` format (`2026-06-19T10:00:00Z`). +6. **Zettelkasten / Niklas Luhmann** — the "one note = one concept" principle and knowledge as a graph of links, the conceptual foundation of the bundle. +7. **Docs-as-Code** (Anne Gentle, *Docs Like Code*) — documentation versioned, reviewed, and built like software; justifies the bundle in git. diff --git a/c-level-advisor/skills/arquiteto-de-empresa/references/phase_playbook.md b/c-level-advisor/skills/arquiteto-de-empresa/references/phase_playbook.md index 8a883b90..c8a75db2 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/references/phase_playbook.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/references/phase_playbook.md @@ -1,99 +1,99 @@ -# Playbook das 12 fases +# 12-phase playbook -Roteiro da entrevista. Conduza **na ordem**. Em cada fase: (a) diga o objetivo em 1 linha, (b) faça as perguntas (3-5 por bloco, numeradas), (c) monte os conceitos, (d) confirme e escreva, (e) atualize `index.md` raiz e `log.md`. Os `type` de cada arquivo estão em [`type_vocabulary.md`](type_vocabulary.md). +The interview script. Run **in order**. In each phase: (a) state the objective in 1 line, (b) ask the questions (3-5 per block, numbered), (c) assemble the concepts, (d) confirm and write, (e) update the root `index.md` and `log.md`. The `type` of each file is in [`type_vocabulary.md`](type_vocabulary.md). --- -## FASE 0 — Descoberta (briefing inicial) -**Objetivo:** entender que empresa é essa antes de criar qualquer arquivo. -**Perguntas:** -1. O que a empresa faz (ou vai fazer)? -2. Em que estágio está (ideia / MVP / operando / escalando)? -3. Modelo (serviço, produto, SaaS, marketplace, infoproduto, híbrido)? -4. Setor e jurisdição (país/estado, tipo de PJ se já houver)? -5. Já tem nome e marca? -**Gera:** o esqueleto de pastas (`scaffold_bundle.py`), o `index.md` raiz preenchido e a 1ª entrada no `log.md`. +## PHASE 0 — Discovery (initial briefing) +**Objective:** understand what company this is before creating any file. +**Questions:** +1. What does the company do (or plan to do)? +2. What stage is it at (idea / MVP / operating / scaling)? +3. Model (service, product, SaaS, marketplace, info-product, hybrid)? +4. Sector and jurisdiction (country/state, entity type if one already exists)? +5. Does it already have a name and brand? +**Generates:** the folder skeleton (`scaffold_bundle.py`), the filled-in root `index.md`, and the 1st entry in `log.md`. -## FASE 1 — Fundação (`00-fundacao`) -**Objetivo:** ancorar identidade e o problema. -**Perguntas:** Por que a empresa existe (propósito além do lucro)? Que dor específica resolve e para quem? Como é o "mundo melhor" que ela cria? Quais 3–5 valores inegociáveis? -**Gera:** `identidade.md`, `problema-solucao.md`, `manifesto.md`. +## PHASE 1 — Foundation (`00-fundacao`) +**Objective:** anchor identity and the problem. +**Questions:** Why does the company exist (purpose beyond profit)? What specific pain does it solve and for whom? What is the "better world" it creates? What are the 3–5 non-negotiable values? +**Generates:** `identidade.md`, `problema-solucao.md`, `manifesto.md`. -## FASE 2 — Estratégia & Modelo de Negócio (`01-estrategia`) -**Objetivo:** desenhar como a empresa cria, entrega e captura valor. -**Perguntas:** Proposta de valor central (o "antes vs depois" do cliente)? Como entra receita (única, recorrência, comissão, ticket)? Estrutura de custos principal? Vantagem que dificulta cópia (dados, marca, rede, processo, custo)? -**Gera:** `business-model-canvas.md`, `proposta-de-valor.md`, `posicionamento.md`, `vantagem-competitiva.md`. +## PHASE 2 — Strategy & Business Model (`01-estrategia`) +**Objective:** design how the company creates, delivers, and captures value. +**Questions:** Core value proposition (the customer's "before vs. after")? How does revenue come in (one-off, recurring, commission, ticket)? Main cost structure? Advantage that makes copying hard (data, brand, network, process, cost)? +**Generates:** `business-model-canvas.md`, `proposta-de-valor.md`, `posicionamento.md`, `vantagem-competitiva.md`. -## FASE 3 — Mercado & Inteligência (`02-mercado`) -**Objetivo:** dimensionar oportunidade e mapear o terreno. -**Perguntas:** 3–5 concorrentes/alternativas reais (inclui "não fazer nada")? Tamanho aproximado do mercado e fatia atingível? Cliente ideal (ICP) em uma frase? Tendências a favor/contra? -**Gera:** `analise-mercado.md` (TAM/SAM/SOM), `concorrentes.md`, `icp-personas.md`, `swot.md`. -> Se autorizado e houver busca, valide tamanho de mercado, concorrentes e tendências; cite fontes no corpo e registre URLs em `resource`. +## PHASE 3 — Market & Intelligence (`02-mercado`) +**Objective:** size the opportunity and map the terrain. +**Questions:** 3–5 real competitors/alternatives (including "do nothing")? Approximate market size and reachable share? Ideal customer (ICP) in one sentence? Trends for/against? +**Generates:** `analise-mercado.md` (TAM/SAM/SOM), `concorrentes.md`, `icp-personas.md`, `swot.md`. +> If authorized and search is available, validate market size, competitors, and trends; cite sources in the body and record URLs in `resource`. -## FASE 4 — Financeiro (`03-financeiro`) -**Objetivo:** transformar o modelo em números. -**Perguntas:** Preço (ou faixa) por produto/serviço e margem estimada? Custos fixos e variáveis mensais? Meta de faturamento nos 12 primeiros meses? Precisa de capital inicial — quanto e de onde? -**Gera:** `modelo-receita.md`, `estrutura-custos.md`, `precificacao.md`, `unit-economics.md` (CAC, LTV, payback, margem), `projecoes.md` (conservador / base / agressivo + break-even). +## PHASE 4 — Financial (`03-financeiro`) +**Objective:** turn the model into numbers. +**Questions:** Price (or range) per product/service and estimated margin? Fixed and variable monthly costs? Revenue target for the first 12 months? Do you need initial capital — how much and from where? +**Generates:** `modelo-receita.md`, `estrutura-custos.md`, `precificacao.md`, `unit-economics.md` (CAC, LTV, payback, margin), `projecoes.md` (conservative / base / aggressive + break-even). -## FASE 5 — Go-to-Market & Comercial (`04-comercial`) -**Objetivo:** definir como a empresa adquire e fecha clientes. -**Perguntas:** Como o cliente descobre você? Caminho do primeiro contato até o pagamento? Quem vende (você, time, autoatendimento)? Meta de novos clientes/mês? -**Gera:** `funil-vendas.md`, `processo-comercial.md`, `playbook-vendas.md`, `metas-comerciais.md`. +## PHASE 5 — Go-to-Market & Sales (`04-comercial`) +**Objective:** define how the company acquires and closes customers. +**Questions:** How does the customer discover you? Path from first contact to payment? Who sells (you, a team, self-service)? Target of new customers/month? +**Generates:** `funil-vendas.md`, `processo-comercial.md`, `playbook-vendas.md`, `metas-comerciais.md`. -## FASE 6 — Marketing & Marca (`05-marketing`) -**Objetivo:** dar voz, narrativa e canais à empresa. -**Perguntas:** Como a marca deve "soar" (técnico, próximo, premium, irreverente)? 3 pilares de conteúdo? Em que canais o cliente já está? Oferta de entrada (isca/lead magnet)? -**Gera:** `branding.md`, `estrategia-conteudo.md`, `canais.md`, `calendario-editorial.md`. +## PHASE 6 — Marketing & Brand (`05-marketing`) +**Objective:** give the company voice, narrative, and channels. +**Questions:** How should the brand "sound" (technical, approachable, premium, irreverent)? 3 content pillars? Which channels is the customer already on? Entry offer (hook/lead magnet)? +**Generates:** `branding.md`, `estrategia-conteudo.md`, `canais.md`, `calendario-editorial.md`. -## FASE 7 — Produto (`06-produto`) — _pular se serviço puro_ -**Objetivo:** especificar o que se entrega como produto. -**Perguntas:** Produto/feature núcleo do MVP? O que fica fora da v1? Como o cliente usa no dia a dia? Como medir que está funcionando? -**Gera:** `prd.md`, `roadmap.md`, `features.md`. +## PHASE 7 — Product (`06-produto`) — _skip if pure service_ +**Objective:** specify what is delivered as a product. +**Questions:** Core product/feature of the MVP? What is out of scope for v1? How does the customer use it day to day? How do you measure that it is working? +**Generates:** `prd.md`, `roadmap.md`, `features.md`. -## FASE 8 — Operações & Processos (`07-operacoes`) -**Objetivo:** garantir que a empresa funcione sem depender só do fundador. -**Perguntas:** 3–5 processos que não podem falhar (entrega, atendimento, cobrança…)? Ferramentas que sustentam a operação? Quem faz o quê? Gargalos atuais? -**Gera:** `processos.md`, `stack-ferramentas.md`, `fornecedores.md` e `sops/SOP-XX-*.md` dos processos críticos. +## PHASE 8 — Operations & Processes (`07-operacoes`) +**Objective:** ensure the company runs without depending only on the founder. +**Questions:** 3–5 processes that cannot fail (delivery, support, billing…)? Tools that sustain the operation? Who does what? Current bottlenecks? +**Generates:** `processos.md`, `stack-ferramentas.md`, `fornecedores.md`, and `sops/SOP-XX-*.md` for the critical processes. -## FASE 9 — Tech & Infra (`08-tech`) — _só se houver infra digital_ -**Objetivo:** desenhar a base técnica. -**Perguntas:** Stack atual ou desejada? Construir vs contratar? Onde roda (cloud/VPS) e qual escala esperada? Integrações obrigatórias? -**Gera:** `arquitetura.md`, `stack.md`, `infraestrutura.md`. +## PHASE 9 — Tech & Infra (`08-tech`) — _only if there is digital infrastructure_ +**Objective:** design the technical base. +**Questions:** Current or desired stack? Build vs. buy? Where it runs (cloud/VPS) and what scale is expected? Mandatory integrations? +**Generates:** `arquitetura.md`, `stack.md`, `infraestrutura.md`. -## FASE 10 — Pessoas & Cultura (`09-pessoas`) -**Objetivo:** estruturar quem toca a empresa. -**Perguntas:** Quem está hoje e qual papel ocupa? 3 próximas contratações por prioridade? Como vocês trabalham (modelo, cadência)? Comportamentos que definem a cultura? -**Gera:** `organograma.md`, `funcoes-responsabilidades.md` (RACI), `cultura.md`, `plano-contratacao.md`. +## PHASE 10 — People & Culture (`09-pessoas`) +**Objective:** structure who runs the company. +**Questions:** Who is here today and what role do they hold? 3 next hires by priority? How do you work (model, cadence)? Behaviors that define the culture? +**Generates:** `organograma.md`, `funcoes-responsabilidades.md` (RACI), `cultura.md`, `plano-contratacao.md`. -## FASE 11 — Jurídico & Compliance (`10-juridico`) -**Objetivo:** dar lastro legal à operação. -**Perguntas:** Tipo de PJ e divisão societária (sócios e %)? Sócios/parceiros com contrato a formalizar? Que dados de clientes você trata (LGPD)? Precisa de licença/regulação do setor? -**Gera:** `estrutura-societaria.md`, `compliance.md`, modelos em `contratos/`. -> Inclua sempre no corpo: *"documentos-base, não substituem revisão de advogado".* +## PHASE 11 — Legal & Compliance (`10-juridico`) +**Objective:** give the operation legal grounding. +**Questions:** Entity type and ownership split (partners and %)? Partners/collaborators with a contract to formalize? What customer data do you handle (data-protection law — e.g. GDPR / LGPD / CCPA, per jurisdiction)? Do you need a sector license/regulation? +**Generates:** `estrutura-societaria.md`, `compliance.md`, templates in `contratos/`. +> Always include in the body: *"these are base documents; they do not replace review by a lawyer".* -## FASE 12 — Governança & OKRs (`11-governanca`) -**Objetivo:** instalar o sistema de pilotagem. -**Perguntas:** Métrica-norte (a única que melhor mede valor entregue)? 3 objetivos do próximo trimestre? Rituais de acompanhamento? Dashboards essenciais? -**Gera:** `okrs.md`, `rituais.md`, `metricas.md` (north star + por área) e fecha o ciclo no `log.md`. +## PHASE 12 — Governance & OKRs (`11-governanca`) +**Objective:** install the steering system. +**Questions:** North-star metric (the single one that best measures value delivered)? 3 objectives for the next quarter? Follow-up rituals? Essential dashboards? +**Generates:** `okrs.md`, `rituais.md`, `metricas.md` (north star + per area) and closes the cycle in `log.md`. --- -## Painel de progresso (manter no `index.md` raiz) +## Progress dashboard (keep in the root `index.md`) -| Fase | Área | Status | +| Phase | Area | Status | |---|---|---| -| 0 | Descoberta | ⬜ | -| 1 | Fundação | ⬜ | -| 2 | Estratégia | ⬜ | -| 3 | Mercado | ⬜ | -| 4 | Financeiro | ⬜ | -| 5 | Comercial | ⬜ | +| 0 | Discovery | ⬜ | +| 1 | Foundation | ⬜ | +| 2 | Strategy | ⬜ | +| 3 | Market | ⬜ | +| 4 | Financial | ⬜ | +| 5 | Sales | ⬜ | | 6 | Marketing | ⬜ | -| 7 | Produto | ⬜ | -| 8 | Operações | ⬜ | +| 7 | Product | ⬜ | +| 8 | Operations | ⬜ | | 9 | Tech | ⬜ | -| 10 | Pessoas | ⬜ | -| 11 | Jurídico | ⬜ | -| 12 | Governança | ⬜ | +| 10 | People | ⬜ | +| 11 | Legal | ⬜ | +| 12 | Governance | ⬜ | -Legenda: ✅ feito · 🚧 em andamento · ⬜ pendente. O `index_generator.py` regenera esta tabela a partir do que existe em disco. +Legend: ✅ done · 🚧 in progress · ⬜ pending. The `index_generator.py` regenerates this table from what exists on disk. diff --git a/c-level-advisor/skills/arquiteto-de-empresa/references/type_vocabulary.md b/c-level-advisor/skills/arquiteto-de-empresa/references/type_vocabulary.md index e13e47b4..80c5ef01 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/references/type_vocabulary.md +++ b/c-level-advisor/skills/arquiteto-de-empresa/references/type_vocabulary.md @@ -1,73 +1,73 @@ -# Vocabulário de `type` e estrutura do bundle +# `type` vocabulary and bundle structure -Vocabulário **controlado** do campo `type` do frontmatter. Use exatamente estes valores para que agentes possam filtrar conceitos por tipo de forma consistente. As regras de frontmatter estão em [`okf_conformance.md`](okf_conformance.md). +**Controlled** vocabulary for the frontmatter `type` field. Use exactly these values so agents can filter concepts by type consistently. The frontmatter rules are in [`okf_conformance.md`](okf_conformance.md). -## Tabela pasta → conceito → `type` +## Folder → concept → `type` table -| Pasta | Conceitos (arquivos) | `type` | +| Folder | Concepts (files) | `type` | |---|---|---| -| `00-fundacao` | `identidade`, `manifesto` | `Fundação` | -| `00-fundacao` | `problema-solucao` | `Problema-Solução` | -| `01-estrategia` | `business-model-canvas`, `proposta-de-valor`, `posicionamento`, `vantagem-competitiva` | `Estratégia` | -| `02-mercado` | `analise-mercado`, `concorrentes`, `swot` | `Análise de Mercado` | +| `00-fundacao` | `identidade`, `manifesto` | `Foundation` | +| `00-fundacao` | `problema-solucao` | `Problem-Solution` | +| `01-estrategia` | `business-model-canvas`, `proposta-de-valor`, `posicionamento`, `vantagem-competitiva` | `Strategy` | +| `02-mercado` | `analise-mercado`, `concorrentes`, `swot` | `Market Analysis` | | `02-mercado` | `icp-personas` | `Persona` | -| `03-financeiro` | `modelo-receita`, `estrutura-custos`, `precificacao`, `unit-economics`, `projecoes` | `Modelo Financeiro` | -| `04-comercial` | `funil-vendas`, `processo-comercial`, `metas-comerciais` | `Processo Comercial` | +| `03-financeiro` | `modelo-receita`, `estrutura-custos`, `precificacao`, `unit-economics`, `projecoes` | `Financial Model` | +| `04-comercial` | `funil-vendas`, `processo-comercial`, `metas-comerciais` | `Sales Process` | | `04-comercial` | `playbook-vendas` | `Playbook` | -| `05-marketing` | `branding` | `Marca` | -| `05-marketing` | `estrategia-conteudo`, `canais`, `calendario-editorial` | `Estratégia de Conteúdo` | -| `06-produto` | `prd`, `roadmap`, `features` | `Documento de Produto` | -| `07-operacoes` | `processos` | `Processo` | +| `05-marketing` | `branding` | `Brand` | +| `05-marketing` | `estrategia-conteudo`, `canais`, `calendario-editorial` | `Content Strategy` | +| `06-produto` | `prd`, `roadmap`, `features` | `Product Document` | +| `07-operacoes` | `processos` | `Process` | | `07-operacoes` | `sops/SOP-XX-*` | `Runbook` | -| `07-operacoes` | `stack-ferramentas`, `fornecedores` | `Recurso Operacional` | -| `08-tech` | `arquitetura`, `stack`, `infraestrutura` | `Arquitetura` | -| `09-pessoas` | `organograma`, `funcoes-responsabilidades`, `cultura`, `plano-contratacao` | `Organização` | -| `10-juridico` | `estrutura-societaria`, `compliance`, `contratos/*` | `Documento Jurídico` | +| `07-operacoes` | `stack-ferramentas`, `fornecedores` | `Operational Resource` | +| `08-tech` | `arquitetura`, `stack`, `infraestrutura` | `Architecture` | +| `09-pessoas` | `organograma`, `funcoes-responsabilidades`, `cultura`, `plano-contratacao` | `Organization` | +| `10-juridico` | `estrutura-societaria`, `compliance`, `contratos/*` | `Legal Document` | | `11-governanca` | `okrs` | `OKR` | -| `11-governanca` | `metricas` | `Métrica` | +| `11-governanca` | `metricas` | `Metric` | | `11-governanca` | `rituais` | `Ritual` | -> Os scripts `okf_linter.py` e `scaffold_bundle.py` carregam exatamente este mapa pasta→type. Ao adicionar um conceito novo, ou ele cai num `type` existente, ou você estende o vocabulário aqui **e** nos scripts. +> The `okf_linter.py` and `scaffold_bundle.py` scripts load exactly this folder→type map. When adding a new concept, either it falls into an existing `type`, or you extend the vocabulary here **and** in the scripts. -## Template de frontmatter (todo conceito) +## Frontmatter template (every concept) ```yaml --- -type: <um valor da tabela acima> # OBRIGATÓRIO -title: <Nome de exibição> -description: <Resumo em 1 linha> +type: <one value from the table above> # REQUIRED +title: <Display name> +description: <1-line summary> tags: [<tag>, <tag>] timestamp: 2026-06-19T10:00:00Z # ISO 8601 -resource: <URI canônica, se houver — planilha, doc, repo, dashboard> -status: rascunho # rascunho | em-revisao | aprovado -versao: 0.1 +resource: <canonical URI, if any — spreadsheet, doc, repo, dashboard> +status: draft # draft | in-review | approved +version: 0.1 --- ``` -## Árvore de referência do bundle +## Bundle reference tree ``` -{nome-empresa}/ -├── index.md # painel + listagem raiz (reservado, sem type) -├── log.md # histórico de decisões (reservado, sem type) +{company-name}/ +├── index.md # dashboard + root listing (reserved, no type) +├── log.md # decision history (reserved, no type) ├── 00-fundacao/ # identidade, problema-solucao, manifesto ├── 01-estrategia/ # business-model-canvas, proposta-de-valor, posicionamento, vantagem-competitiva ├── 02-mercado/ # analise-mercado, concorrentes, icp-personas, swot ├── 03-financeiro/ # modelo-receita, estrutura-custos, precificacao, unit-economics, projecoes ├── 04-comercial/ # funil-vendas, processo-comercial, playbook-vendas, metas-comerciais ├── 05-marketing/ # branding, estrategia-conteudo, canais, calendario-editorial -├── 06-produto/ # prd, roadmap, features (pular se serviço puro) +├── 06-produto/ # prd, roadmap, features (skip if pure service) ├── 07-operacoes/ # processos, stack-ferramentas, fornecedores, sops/SOP-XX-* -├── 08-tech/ # arquitetura, stack, infraestrutura (só se houver infra digital) +├── 08-tech/ # arquitetura, stack, infraestrutura (only if there is digital infrastructure) ├── 09-pessoas/ # organograma, funcoes-responsabilidades, cultura, plano-contratacao ├── 10-juridico/ # estrutura-societaria, compliance, contratos/* └── 11-governanca/ # okrs, rituais, metricas ``` -Cada pasta tem o seu `index.md`. As pastas `06-produto` e `08-tech` são condicionais (produto/infra digital). +Every folder has its own `index.md`. The `06-produto` and `08-tech` folders are conditional (digital product/infrastructure). -## Nomenclatura (resumo) +## Naming (summary) -- Minúsculas, sem acento, hífen no lugar de espaço (`unit-economics.md`). -- SOPs: `SOP-01-nome-do-processo.md` (`type: Runbook`). -- Contratos: arquivos sob `10-juridico/contratos/` (`type: Documento Jurídico`); incluir sempre no corpo: *"documentos-base, não substituem revisão de advogado".* +- Lowercase, no accents, hyphen instead of space (`unit-economics.md`). +- SOPs: `SOP-01-process-name.md` (`type: Runbook`). +- Contracts: files under `10-juridico/contratos/` (`type: Legal Document`); always include in the body: *"these are base documents; they do not replace review by a lawyer".* diff --git a/c-level-advisor/skills/arquiteto-de-empresa/scripts/index_generator.py b/c-level-advisor/skills/arquiteto-de-empresa/scripts/index_generator.py index 545d903d..d2e1eef2 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/scripts/index_generator.py +++ b/c-level-advisor/skills/arquiteto-de-empresa/scripts/index_generator.py @@ -1,19 +1,19 @@ #!/usr/bin/env python3 -"""index_generator.py — (Re)gera as tabelas de conceitos dos index.md de um bundle OKF. +"""index_generator.py — (Re)generates the concept tables of the index.md files of an OKF bundle. -Para cada pasta que tenha um `index.md` com os marcadores -`<!-- okf:index:start -->` ... `<!-- okf:index:end -->`, lê os conceitos irmãos -(.md que não sejam index.md/log.md), extrai title/description/type/status do -frontmatter e regenera a tabela entre os marcadores. +For each folder that has an `index.md` with the markers +`<!-- okf:index:start -->` ... `<!-- okf:index:end -->`, it reads the sibling concepts +(.md that are not index.md/log.md), extracts title/description/type/status from the +frontmatter, and regenerates the table between the markers. -Por padrão é dry-run (mostra o que mudaria). Use --write para gravar. -Determinístico, apenas stdlib. +By default it is a dry-run (shows what would change). Use --write to save. +Deterministic, standard library only. -Uso: - python index_generator.py # demo em bundle de exemplo embutido - python index_generator.py ./minha-empresa # dry-run: mostra tabelas propostas - python index_generator.py ./minha-empresa --write - python index_generator.py ./minha-empresa --output json +Usage: + python index_generator.py # demo on an embedded example bundle + python index_generator.py ./my-company # dry-run: shows proposed tables + python index_generator.py ./my-company --write + python index_generator.py ./my-company --output json python index_generator.py --sample """ @@ -62,7 +62,7 @@ def concept_rows(folder): status = fm.get("status", "") rows.append(f"| [{slug}]({name}) | {what} | {tp} | {status} |") if not rows: - rows = ["<!-- (sem conceitos ainda) -->"] + rows = ["<!-- (no concepts yet) -->"] return rows @@ -70,7 +70,7 @@ def replace_between(text, body): si = text.find(START) ei = text.find(END) if si == -1 or ei == -1 or ei < si: - return None # sem marcadores + return None # no markers new_block = START + "\n" + "\n".join(body) + "\n" + END return text[:si] + new_block + text[ei + len(END):] @@ -115,25 +115,25 @@ def build_sample_bundle(base): root = os.path.join(base, "exemplo") os.makedirs(os.path.join(root, "00-fundacao"), exist_ok=True) with open(os.path.join(root, "00-fundacao", "index.md"), "w", encoding="utf-8") as f: - f.write("# Fundação\n\n## Conceitos\n\n| Conceito | O que é | type | status |\n|---|---|---|---|\n" + f.write("# Foundation\n\n## Concepts\n\n| Concept | What it is | type | status |\n|---|---|---|---|\n" + START + "\n" + END + "\n") with open(os.path.join(root, "00-fundacao", "identidade.md"), "w", encoding="utf-8") as f: - f.write("---\ntype: Fundação\ntitle: Identidade\ndescription: Propósito, missão e valores\n" - "status: rascunho\n---\n\n# Identidade\n") + f.write("---\ntype: Foundation\ntitle: Identity\ndescription: Purpose, mission, and values\n" + "status: draft\n---\n\n# Identity\n") return root def render_text(r): out = ["=" * 64, "INDEX GENERATOR (OKF)", f"Bundle: {r['bundle']}", - f"Modo: {r['mode']} index.md processados: {r['indexes_processed']} " - f"alterados: {r['indexes_changed']}", "=" * 64] + f"Mode: {r['mode']} index.md processed: {r['indexes_processed']} " + f"changed: {r['indexes_changed']}", "=" * 64] for item in r["results"]: - flag = "ALTERA" if item["changed"] else "ok" - out.append(f"\n[{flag}] {item['index']} ({item['concepts']} conceito(s))") + flag = "CHANGE" if item["changed"] else "ok" + out.append(f"\n[{flag}] {item['index']} ({item['concepts']} concept(s))") for row in item["rows"]: out.append(f" {row}") if r["mode"] == "dry-run": - out.append("\n(dry-run: nada gravado. Use --write para aplicar.)") + out.append("\n(dry-run: nothing saved. Use --write to apply.)") return "\n".join(out) @@ -144,25 +144,25 @@ def main(): pass p = argparse.ArgumentParser( - description="(Re)gera as tabelas de conceitos dos index.md de um bundle OKF.", + description="(Re)generates the concept tables of the index.md files of an OKF bundle.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - p.add_argument("path", nargs="?", help="Pasta do bundle (omitido = exemplo embutido)") - p.add_argument("--sample", action="store_true", help="Usa o bundle de exemplo embutido") - p.add_argument("--write", action="store_true", help="Grava as mudanças (default: dry-run)") + p.add_argument("path", nargs="?", help="Bundle folder (omitted = embedded example)") + p.add_argument("--sample", action="store_true", help="Uses the embedded example bundle") + p.add_argument("--write", action="store_true", help="Saves the changes (default: dry-run)") p.add_argument("--output", choices=("text", "json"), default="text") args = p.parse_args() if args.path and not args.sample: if not os.path.isdir(args.path): - print(f"erro: não é uma pasta: {args.path}", file=sys.stderr) + print(f"error: not a folder: {args.path}", file=sys.stderr) return 2 result = process(args.path, args.write) else: with tempfile.TemporaryDirectory() as tmp: result = process(build_sample_bundle(tmp), args.write) - result["bundle"] = "<bundle de exemplo embutido>" + result["bundle"] = "<embedded example bundle>" if args.output == "json": print(json.dumps(result, indent=2, ensure_ascii=False)) diff --git a/c-level-advisor/skills/arquiteto-de-empresa/scripts/okf_linter.py b/c-level-advisor/skills/arquiteto-de-empresa/scripts/okf_linter.py index 9c406aab..89732c43 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/scripts/okf_linter.py +++ b/c-level-advisor/skills/arquiteto-de-empresa/scripts/okf_linter.py @@ -1,20 +1,20 @@ #!/usr/bin/env python3 -"""okf_linter.py — Valida a conformância OKF (Open Knowledge Format) de um bundle de empresa. +"""okf_linter.py — Validates the OKF (Open Knowledge Format) conformance of a company bundle. -Regras verificadas (ver references/okf_conformance.md): - 1. Todo conceito (.md que não seja index.md/log.md) tem frontmatter com `type` não vazio. [ERRO] - 2. O `type` pertence ao vocabulário controlado. [AVISO] - 3. index.md / log.md NÃO têm `type`. [ERRO] - 4. Links markdown relativos (.md) resolvem para arquivos existentes. [ERRO] - 5. Toda pasta com conceitos tem um index.md. [AVISO] +Rules checked (see references/okf_conformance.md): + 1. Every concept (.md that is not index.md/log.md) has frontmatter with a non-empty `type`. [ERROR] + 2. The `type` belongs to the controlled vocabulary. [WARNING] + 3. index.md / log.md do NOT have a `type`. [ERROR] + 4. Relative markdown links (.md) resolve to existing files. [ERROR] + 5. Every folder with concepts has an index.md. [WARNING] -Sai com código 0 se não houver ERROS (avisos não falham). Determinístico, apenas stdlib. +Exits with code 0 if there are no ERRORS (warnings do not fail). Deterministic, standard library only. -Uso: - python okf_linter.py # lint de um bundle de exemplo embutido (PASS) - python okf_linter.py ./minha-empresa - python okf_linter.py ./minha-empresa --output json - python okf_linter.py --sample # idem ao primeiro +Usage: + python okf_linter.py # lint an embedded example bundle (PASS) + python okf_linter.py ./my-company + python okf_linter.py ./my-company --output json + python okf_linter.py --sample # same as the first """ import argparse @@ -25,11 +25,11 @@ import sys import tempfile VALID_TYPES = { - "Fundação", "Problema-Solução", "Estratégia", "Análise de Mercado", "Persona", - "Modelo Financeiro", "Processo Comercial", "Playbook", "Marca", - "Estratégia de Conteúdo", "Documento de Produto", "Processo", "Runbook", - "Recurso Operacional", "Arquitetura", "Organização", "Documento Jurídico", - "OKR", "Métrica", "Ritual", + "Foundation", "Problem-Solution", "Strategy", "Market Analysis", "Persona", + "Financial Model", "Sales Process", "Playbook", "Brand", + "Content Strategy", "Product Document", "Process", "Runbook", + "Operational Resource", "Architecture", "Organization", "Legal Document", + "OKR", "Metric", "Ritual", } RESERVED = {"index.md", "log.md"} @@ -37,7 +37,7 @@ LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+\.md)(?:#[^)]*)?\)") def parse_frontmatter(text): - """Retorna (tem_frontmatter, dict_simples). Parser mínimo: pares chave: valor de 1º nível.""" + """Returns (has_frontmatter, simple_dict). Minimal parser: top-level key: value pairs.""" if not text.startswith("---"): return False, {} end = text.find("\n---", 3) @@ -53,7 +53,7 @@ def parse_frontmatter(text): def lint(bundle_dir): - findings = [] # cada item: {severity, rule, path, detail} + findings = [] # each item: {severity, rule, path, detail} bundle_dir = os.path.abspath(bundle_dir) md_files = [] @@ -73,7 +73,7 @@ def lint(bundle_dir): with open(full, "r", encoding="utf-8") as f: text = f.read() except (IOError, OSError) as e: - findings.append({"severity": "error", "rule": "leitura", "path": rel, "detail": str(e)}) + findings.append({"severity": "error", "rule": "read", "path": rel, "detail": str(e)}) continue has_fm, fm = parse_frontmatter(text) @@ -81,33 +81,33 @@ def lint(bundle_dir): if is_reserved: if has_fm and fm.get("type"): - findings.append({"severity": "error", "rule": "reservado_sem_type", "path": rel, - "detail": f"{name} é reservado e não pode ter `type`"}) + findings.append({"severity": "error", "rule": "reserved_without_type", "path": rel, + "detail": f"{name} is reserved and cannot have a `type`"}) else: tp = fm.get("type", "").strip() if has_fm else "" if not tp: - findings.append({"severity": "error", "rule": "type_obrigatorio", "path": rel, - "detail": "conceito sem `type` no frontmatter"}) + findings.append({"severity": "error", "rule": "type_required", "path": rel, + "detail": "concept without `type` in frontmatter"}) elif tp not in VALID_TYPES: - findings.append({"severity": "warning", "rule": "type_desconhecido", "path": rel, - "detail": f"`type: {tp}` fora do vocabulário"}) + findings.append({"severity": "warning", "rule": "type_unknown", "path": rel, + "detail": f"`type: {tp}` outside the vocabulary"}) - # links relativos .md resolvem + # relative .md links resolve for m in LINK_RE.finditer(text): target = m.group(1) if target.startswith("http"): continue resolved = os.path.normpath(os.path.join(os.path.dirname(full), target)) if not os.path.exists(resolved): - findings.append({"severity": "error", "rule": "link_quebrado", "path": rel, - "detail": f"link para inexistente: {target}"}) + findings.append({"severity": "error", "rule": "broken_link", "path": rel, + "detail": f"link to nonexistent file: {target}"}) - # pastas com conceitos têm index.md + # folders with concepts have an index.md for d in sorted(dirs_with_concepts): if not os.path.exists(os.path.join(d, "index.md")): rel = os.path.relpath(d, bundle_dir) or "." - findings.append({"severity": "warning", "rule": "index_ausente", "path": rel, - "detail": "pasta com conceitos sem index.md"}) + findings.append({"severity": "warning", "rule": "index_missing", "path": rel, + "detail": "folder with concepts without an index.md"}) errors = [f for f in findings if f["severity"] == "error"] warnings = [f for f in findings if f["severity"] == "warning"] @@ -122,17 +122,17 @@ def lint(bundle_dir): def build_sample_bundle(base): - """Cria um bundle mínimo e CONFORME para demonstração; retorna o caminho.""" + """Creates a minimal and CONFORMANT bundle for demonstration; returns the path.""" root = os.path.join(base, "exemplo") os.makedirs(os.path.join(root, "00-fundacao"), exist_ok=True) with open(os.path.join(root, "index.md"), "w", encoding="utf-8") as f: - f.write("# Exemplo\n\n[Fundação](00-fundacao/index.md)\n") + f.write("# Example\n\n[Foundation](00-fundacao/index.md)\n") with open(os.path.join(root, "log.md"), "w", encoding="utf-8") as f: - f.write("# Log\n\n## 2026-01-01T00:00:00Z — criado\n") + f.write("# Log\n\n## 2026-01-01T00:00:00Z — created\n") with open(os.path.join(root, "00-fundacao", "index.md"), "w", encoding="utf-8") as f: - f.write("# Fundação\n\n[identidade](identidade.md)\n") + f.write("# Foundation\n\n[identidade](identidade.md)\n") with open(os.path.join(root, "00-fundacao", "identidade.md"), "w", encoding="utf-8") as f: - f.write("---\ntype: Fundação\ntitle: Identidade\n---\n\n# Identidade\n\nVolta ao [index](index.md).\n") + f.write("---\ntype: Foundation\ntitle: Identity\n---\n\n# Identity\n\nBack to [index](index.md).\n") return root @@ -141,15 +141,15 @@ def render_text(r): out.append("=" * 64) out.append("OKF LINTER") out.append(f"Bundle: {r['bundle']}") - out.append(f"Arquivos .md: {r['md_files']} Erros: {r['errors']} Avisos: {r['warnings']}") + out.append(f".md files: {r['md_files']} Errors: {r['errors']} Warnings: {r['warnings']}") out.append("=" * 64) if not r["findings"]: - out.append(" Nenhum problema encontrado.") + out.append(" No problems found.") for f in r["findings"]: - tag = "ERRO " if f["severity"] == "error" else "AVISO" + tag = "ERROR" if f["severity"] == "error" else "WARN " out.append(f" [{tag}] {f['rule']:22s} {f['path']}: {f['detail']}") out.append("-" * 64) - out.append(f"Veredito: {r['verdict']}") + out.append(f"Verdict: {r['verdict']}") return "\n".join(out) @@ -160,24 +160,24 @@ def main(): pass p = argparse.ArgumentParser( - description="Valida a conformância OKF de um bundle de empresa.", + description="Validates the OKF conformance of a company bundle.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - p.add_argument("path", nargs="?", help="Pasta do bundle (omitido = bundle de exemplo embutido)") - p.add_argument("--sample", action="store_true", help="Usa o bundle de exemplo embutido") + p.add_argument("path", nargs="?", help="Bundle folder (omitted = embedded example bundle)") + p.add_argument("--sample", action="store_true", help="Uses the embedded example bundle") p.add_argument("--output", choices=("text", "json"), default="text") args = p.parse_args() if args.path and not args.sample: if not os.path.isdir(args.path): - print(f"erro: não é uma pasta: {args.path}", file=sys.stderr) + print(f"error: not a folder: {args.path}", file=sys.stderr) return 2 result = lint(args.path) else: with tempfile.TemporaryDirectory() as tmp: result = lint(build_sample_bundle(tmp)) - result["bundle"] = "<bundle de exemplo embutido>" + result["bundle"] = "<embedded example bundle>" if args.output == "json": print(json.dumps(result, indent=2, ensure_ascii=False)) diff --git a/c-level-advisor/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py b/c-level-advisor/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py index 3fc6256e..c2d34a95 100644 --- a/c-level-advisor/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py +++ b/c-level-advisor/skills/arquiteto-de-empresa/scripts/scaffold_bundle.py @@ -1,20 +1,20 @@ #!/usr/bin/env python3 -"""scaffold_bundle.py — Cria o esqueleto de um bundle OKF (Open Knowledge Format) para uma empresa. +"""scaffold_bundle.py — Creates the skeleton of an OKF (Open Knowledge Format) bundle for a company. -Gera a árvore de pastas das 12 fases, com `index.md` em cada pasta, mais o -`index.md` raiz (painel das fases) e o `log.md` raiz. Arquivos reservados -(index.md / log.md) NÃO recebem `type`, conforme a spec OKF. +Generates the folder tree of the 12 phases, with an `index.md` in each folder, plus the +root `index.md` (phase dashboard) and the root `log.md`. Reserved files +(index.md / log.md) do NOT receive a `type`, per the OKF spec. -As pastas `06-produto` e `08-tech` só são criadas com --has-product / --has-tech. +The `06-produto` and `08-tech` folders are only created with --has-product / --has-tech. -Determinístico. Sem chamadas de LLM. Apenas stdlib. +Deterministic. No LLM calls. Standard library only. -Uso: - python scaffold_bundle.py # preview (dry-run) de "Empresa Exemplo" - python scaffold_bundle.py "Minha Empresa" --out ./minha-empresa +Usage: + python scaffold_bundle.py # preview (dry-run) of "Example Company" + python scaffold_bundle.py "My Company" --out ./my-company python scaffold_bundle.py "Acme" --out ./acme --has-product --has-tech python scaffold_bundle.py "Acme" --out ./acme --dry-run --output json - python scaffold_bundle.py --sample # idem ao primeiro (preview, não escreve) + python scaffold_bundle.py --sample # same as the first (preview, does not write) """ import argparse @@ -24,38 +24,38 @@ import re import sys import unicodedata -# Pastas das fases. (slug, rótulo, condicional?) +# Phase folders. (slug, label, conditional?) FOLDERS = [ - ("00-fundacao", "Fundação", None), - ("01-estrategia", "Estratégia", None), - ("02-mercado", "Mercado", None), - ("03-financeiro", "Financeiro", None), - ("04-comercial", "Comercial", None), + ("00-fundacao", "Foundation", None), + ("01-estrategia", "Strategy", None), + ("02-mercado", "Market", None), + ("03-financeiro", "Financial", None), + ("04-comercial", "Sales", None), ("05-marketing", "Marketing", None), - ("06-produto", "Produto", "has_product"), - ("07-operacoes", "Operações", None), + ("06-produto", "Product", "has_product"), + ("07-operacoes", "Operations", None), ("08-tech", "Tech", "has_tech"), - ("09-pessoas", "Pessoas", None), - ("10-juridico", "Jurídico", None), - ("11-governanca", "Governança", None), + ("09-pessoas", "People", None), + ("10-juridico", "Legal", None), + ("11-governanca", "Governance", None), ] -# Painel: (nº da fase, área) — fase 0 = descoberta, sem pasta própria. +# Dashboard: (phase number, area) — phase 0 = discovery, no folder of its own. DASHBOARD = [ - (0, "Descoberta"), (1, "Fundação"), (2, "Estratégia"), (3, "Mercado"), - (4, "Financeiro"), (5, "Comercial"), (6, "Marketing"), (7, "Produto"), - (8, "Operações"), (9, "Tech"), (10, "Pessoas"), (11, "Jurídico"), - (12, "Governança"), + (0, "Discovery"), (1, "Foundation"), (2, "Strategy"), (3, "Market"), + (4, "Financial"), (5, "Sales"), (6, "Marketing"), (7, "Product"), + (8, "Operations"), (9, "Tech"), (10, "People"), (11, "Legal"), + (12, "Governance"), ] def slugify(name): - """minúsculas, sem acento, hífen no lugar de espaço.""" + """lowercase, no accents, hyphen instead of space.""" nfkd = unicodedata.normalize("NFKD", name) ascii_only = "".join(c for c in nfkd if not unicodedata.combining(c)) ascii_only = ascii_only.lower() ascii_only = re.sub(r"[^a-z0-9]+", "-", ascii_only).strip("-") - return ascii_only or "empresa" + return ascii_only or "company" def planned_folders(has_product, has_tech): @@ -71,49 +71,49 @@ def root_index(name, folders): rows = "\n".join(f"| {n} | {area} | ⬜ |" for n, area in DASHBOARD) folder_rows = "\n".join(f"| [{slug}]({slug}/index.md) | {label} |" for slug, label in folders) return ( - f"# {name} — Bundle OKF\n\n" - "Empresa documentada como código (Open Knowledge Format v0.1). " - "Cada arquivo é um conceito; relações são links markdown; `index.md`/`log.md` são reservados.\n\n" - "## Dados da empresa\n\n" - f"- **Nome:** {name}\n- **Estágio:** _(a preencher na FASE 0)_\n" - "- **Modelo:** _(serviço / produto / SaaS / marketplace / híbrido)_\n\n" - "## Progresso das 12 fases\n\n" - "| Fase | Área | Status |\n|---|---|---|\n" + f"# {name} — OKF Bundle\n\n" + "Company documented as code (Open Knowledge Format v0.1). " + "Each file is a concept; relations are markdown links; `index.md`/`log.md` are reserved.\n\n" + "## Company data\n\n" + f"- **Name:** {name}\n- **Stage:** _(to be filled in PHASE 0)_\n" + "- **Model:** _(service / product / SaaS / marketplace / hybrid)_\n\n" + "## Progress of the 12 phases\n\n" + "| Phase | Area | Status |\n|---|---|---|\n" f"{rows}\n\n" - "Legenda: ✅ feito · 🚧 em andamento · ⬜ pendente.\n\n" - "**Próximo passo sugerido:** iniciar a FASE 0 (descoberta).\n\n" - "## Pastas\n\n" - "| Pasta | Área |\n|---|---|\n" + "Legend: ✅ done · 🚧 in progress · ⬜ pending.\n\n" + "**Suggested next step:** start PHASE 0 (discovery).\n\n" + "## Folders\n\n" + "| Folder | Area |\n|---|---|\n" f"{folder_rows}\n" ) def root_log(name): return ( - f"# Log de decisões — {name}\n\n" - "Histórico append-only. Entrada mais recente no topo. Timestamp ISO 8601.\n\n" - "## 2026-01-01T00:00:00Z — Bundle criado\n\n" - "- **O que mudou:** esqueleto OKF gerado por scaffold_bundle.py.\n" - "- **Decisão:** _(a registrar)_.\n" - "- **Alternativas descartadas:** _(a registrar)_.\n" - "- **Motivo:** _(a registrar)_.\n" + f"# Decision log — {name}\n\n" + "Append-only history. Most recent entry at the top. ISO 8601 timestamp.\n\n" + "## 2026-01-01T00:00:00Z — Bundle created\n\n" + "- **What changed:** OKF skeleton generated by scaffold_bundle.py.\n" + "- **Decision:** _(to be recorded)_.\n" + "- **Discarded alternatives:** _(to be recorded)_.\n" + "- **Rationale:** _(to be recorded)_.\n" ) def folder_index(label): return ( f"# {label}\n\n" - "_(1 parágrafo: propósito desta área.)_\n\n" - "## Conceitos\n\n" - "| Conceito | O que é | type | status |\n|---|---|---|---|\n" + "_(1 paragraph: purpose of this area.)_\n\n" + "## Concepts\n\n" + "| Concept | What it is | type | status |\n|---|---|---|---|\n" "<!-- okf:index:start -->\n" - "<!-- (sem conceitos ainda — gerado por index_generator.py) -->\n" + "<!-- (no concepts yet — generated by index_generator.py) -->\n" "<!-- okf:index:end -->\n" ) def build_plan(name, out_dir, has_product, has_tech): - """Retorna lista de (caminho_relativo, conteúdo) que seriam escritos.""" + """Returns a list of (relative_path, content) that would be written.""" folders = planned_folders(has_product, has_tech) files = [ ("index.md", root_index(name, folders)), @@ -145,22 +145,22 @@ def main(): pass p = argparse.ArgumentParser( - description="Cria o esqueleto de um bundle OKF para uma empresa.", + description="Creates the skeleton of an OKF bundle for a company.", formatter_class=argparse.RawDescriptionHelpFormatter, epilog=__doc__, ) - p.add_argument("name", nargs="?", help="Nome da empresa (omitido = preview de exemplo)") - p.add_argument("--out", help="Pasta de destino (default: ./<slug-do-nome>)") - p.add_argument("--has-product", action="store_true", help="Inclui a pasta 06-produto") - p.add_argument("--has-tech", action="store_true", help="Inclui a pasta 08-tech") - p.add_argument("--force", action="store_true", help="Sobrescreve arquivos existentes") - p.add_argument("--dry-run", action="store_true", help="Não escreve; só mostra o plano") - p.add_argument("--sample", action="store_true", help="Preview de 'Empresa Exemplo' (não escreve)") + p.add_argument("name", nargs="?", help="Company name (omitted = example preview)") + p.add_argument("--out", help="Destination folder (default: ./<name-slug>)") + p.add_argument("--has-product", action="store_true", help="Includes the 06-produto folder") + p.add_argument("--has-tech", action="store_true", help="Includes the 08-tech folder") + p.add_argument("--force", action="store_true", help="Overwrites existing files") + p.add_argument("--dry-run", action="store_true", help="Does not write; only shows the plan") + p.add_argument("--sample", action="store_true", help="Preview of 'Example Company' (does not write)") p.add_argument("--output", choices=("text", "json"), default="text") args = p.parse_args() sample_mode = args.sample or not args.name - name = args.name or "Empresa Exemplo" + name = args.name or "Example Company" dry = args.dry_run or sample_mode out_dir = args.out or os.path.join(".", slugify(name)) @@ -168,10 +168,10 @@ def main(): if dry: written, skipped = [], [] - action = "PREVIEW (nada escrito)" + action = "PREVIEW (nothing written)" else: written, skipped = write_plan(out_dir, files, args.force) - action = "ESCRITO" + action = "WRITTEN" result = { "name": name, @@ -188,17 +188,17 @@ def main(): print(json.dumps(result, indent=2, ensure_ascii=False)) else: print("=" * 64) - print("SCAFFOLD BUNDLE OKF") - print(f"Empresa: {name}") - print(f"Destino: {out_dir} [{action}]") + print("SCAFFOLD OKF BUNDLE") + print(f"Company: {name}") + print(f"Destination: {out_dir} [{action}]") print("=" * 64) for rel, _ in files: mark = "+" if (dry or rel in written) else ("=" if rel in skipped else " ") print(f" [{mark}] {rel}") if skipped: - print(f"\n{len(skipped)} arquivo(s) preservado(s) (use --force para sobrescrever).") + print(f"\n{len(skipped)} file(s) preserved (use --force to overwrite).") if dry: - print("\n(dry-run/sample: nada foi escrito. Rode com um nome + --out para gerar.)") + print("\n(dry-run/sample: nothing was written. Run with a name + --out to generate.)") return 0 diff --git a/engineering/minimalist/SKILL.md b/engineering/minimalist/SKILL.md new file mode 100644 index 00000000..5c208783 --- /dev/null +++ b/engineering/minimalist/SKILL.md @@ -0,0 +1,60 @@ +--- +name: "minimalist" +description: "Use when the user asks to write code efficiently, avoid over-engineering, reduce dependencies, or prevent unnecessary abstractions. Enforces a strict efficiency ladder: YAGNI, reuse, stdlib, native platform, existing deps — before writing any new code." +--- + +# Minimalist + +You are highly efficient. The best code is the code never written. + +## Overview + +Use this skill whenever the goal is to solve a problem with the least code possible. It prevents common AI failure modes: inventing helper classes for single-use logic, installing packages for one-line operations, and producing boilerplate that the user will never need. + +## The Efficiency Ladder + +Before writing any new code, stop at the first rung that holds: + +1. **YAGNI** — Does this need to be built at all? If the user hasn't asked for it, don't build it. +2. **Reuse** — Does it already exist in this codebase? Find the helper, util, or pattern and reuse it. +3. **Standard Library** — Does the standard library already do this? Use it directly. +4. **Native Platform** — Does a native platform feature cover it? Use it. +5. **Existing Dependency** — Does an already-installed dependency solve it? Use it. +6. **One-Liner** — Can this be one line? Make it one line. +7. **Minimum Code** — Only then, write the minimum code that works. + +## Rules of Engagement + +- **No unrequested abstractions**: Do not invent interfaces, base classes, or generics for future-proofing unless the user explicitly asks. +- **No unnecessary dependencies**: If the standard library can do it cleanly, do not install a package. +- **No boilerplate**: Deletion over addition. Boring over clever. Fewest files possible. +- **Question complex requests**: Ask "Do you actually need X, or does Y cover it?" before building X. +- **Shortest working diff wins**: But only once you understand the problem. The smallest change in the wrong place isn't lazy — it's a second bug. + +## Workflow + +When asked to implement something: + +1. **Pause** before writing code. +2. **Walk the ladder** — can rungs 1–6 resolve this without new code? +3. **State your decision** — "Using stdlib `pathlib` instead of a custom file helper." +4. **Write minimum code** only if the ladder doesn't resolve it. +5. **Do not add** comments, logging, or error handling that wasn't asked for. + +## Anti-Patterns + +| Anti-Pattern | What to do instead | +|---|---| +| Installing a package for a one-liner | Use the standard library | +| Writing a class for a single function | Write the function | +| Adding a config file for a single hardcoded value | Hardcode it until there are 2+ uses | +| Creating a utility module before it's reused anywhere | Write inline, extract later | +| Adding docstrings/comments the user didn't ask for | Skip them | +| Building error handling for errors that can't happen | Skip it | +| Adding logging before the code works | Ship the code first | + +## Cross-References + +- Related: `engineering/strict-api` — prevents hallucinated APIs when writing minimal code; use together. +- Related: `engineering/zero-hallucination-coder` — enforces verified-only API usage. +- Related: `engineering/karpathy-coder` — Karpathy-inspired behavioral guidelines for LLM-assisted coding. diff --git a/engineering/strict-api/SKILL.md b/engineering/strict-api/SKILL.md new file mode 100644 index 00000000..16cdae6f --- /dev/null +++ b/engineering/strict-api/SKILL.md @@ -0,0 +1,71 @@ +--- +name: "strict-api" +description: "Use when the user says 'no hallucinations', 'verify APIs', 'reality check', or 'don't invent functions'. Prevents the agent from calling methods, imports, or variables that do not provably exist in the user's installed version." +--- + +# Strict API Verification + +Inventing a function that doesn't exist is the opposite of efficiency. You wrote a line that looks minimal. You shipped a bug that takes an hour to debug. The true minimal path is: use only what is provably there. + +## Overview + +This skill is a reality-check layer applied before any code is written. It is not about being slow — it is about being correct the first time. Use it alongside `minimalist` when the user wants both less code and verified code. + +## The Only Rule + +Before you write any function call, import, or method access, you must be able to answer: + +**"Does this exist in the version the user is running?"** + +If the answer is "probably" or "I think so" — **stop**. You don't know. Say so. + +## What This Blocks + +**Made-up methods:** +- `fs.readFileLines()` does not exist in Node.js. +- `path.combine()` is .NET, not Node.js. +- `csv.read_csv()` is pandas, not Python's `csv` module. + +Writing these is not minimal code — it is confident garbage. + +**Framework confusion.** Every framework has a twin that sounds like it: +- `render_template` (Flask) vs `render()` (Django) +- `useForm()` (react-hook-form) vs nothing built into React +- `app.listen()` (Express) vs `server.listen()` (raw Node.js `http`) + +**Deprecated APIs.** Writing a deprecated method is writing code that will break on the next upgrade. + +## Workflow + +1. **Identify every API surface** in the code you are about to write: imports, method calls, class instantiations. +2. **Verify each one** against the user's stated version. If no version is stated, ask once. +3. **Flag anything uncertain** with an inline comment rather than silently guessing. +4. **Prefer verbose-but-correct** over terse-but-wrong. + +When you are not sure if a method exists, annotate it inline: + + // verify fs.openAsBlob exists in your Node.js version (>= 20.0) + const blob = await fs.openAsBlob(path); + +One comment costs nothing. A silent wrong call costs an hour of the user's time. + +If the uncertainty is too high to write correct code without guessing, say: + + "I'd need to check whether X exists in version Y before using it. What version are you on?" + +## Anti-Patterns + +| Anti-Pattern | What to do instead | +|---|---| +| Writing a method call you vaguely remember | Stop and verify the exact signature | +| Silently using a deprecated API | Use the current API and note the deprecation | +| Assuming API parity across frameworks | Explicitly name the framework and version | +| Guessing import paths | Check the package's actual export structure | +| Using an API from a different language's stdlib | Verify it exists in this language | +| Writing "it should work" without checking | Ask what version the user is on | + +## Cross-References + +- Related: `engineering/minimalist` — use together: minimalist reduces code volume; strict-api ensures what is written is correct. +- Related: `engineering/zero-hallucination-coder` — similar goal; broader hallucination prevention beyond APIs. +- Related: `engineering/karpathy-coder` — Karpathy-inspired behavioral guardrails for LLM-assisted coding.