conectese 0.1.14

package/README.md

@@ -0,0 +1,265 @@
+# conectese
+
+Crie equipes (squads) de agentes de IA focadas no ambiente jurídico — direto da sua IDE.
+
+O conectese é um framework de orquestração multi-agente voltado inteiramente para **Advogados Especializados e Escritórios de Advocacia**. Descreva a necessidade do seu caso em linguagem natural, e o conectese cria uma equipe de agentes e analistas jurídicos de IA que trabalham juntos para melhorar a análise processual, garantir a privacidade (LGPD) e dar suporte na sua tomada de decisão.
+
+## Conheça mais
+
+[conecte.se](https://conecte.se) - **Contato:** carlos@conecte.se
+
+## O que é um Squad Jurídico?
+
+Um squad jurídico é uma equipe de agentes de IA que colaboram para destrinchar e solucionar um caso ou analisar um conjunto probatório. Cada agente tem um papel específico (como extração, anonimização e formação de tese). Eles executam em pipeline com *checkpoints* onde o agente pausa e pede sua aprovação antes de tomar qualquer decisão sensível.
+
+Exemplo do nosso **Pipeline OpenLaw**:
+
+- **Extrator de Dados** lê peças e provas processuais brutas
+- **Especialista LGPD (Anonimizador)** higieniza os dados e mascara informações pessoais e sensíveis
+- **Analista Jurídico Geral** monta o panorama probatório e interroga o advogado humano
+- **Orquestrador de Pareceres** convoca os Especialistas (Direito Penal, Civil, Tributário, etc)
+- **Compositor de Minutas** redige a fundamentação coesa e unificada
+- **Restaurador LGPD** reverte a anonimização e insere os dados reais no documento final
+
+## Para quem?
+
+Para profissionais do Direito e equipes que desejam alavancar produtividade com máxima segurança e privacidade usando IA.
+
+- **Advogados Autônomos** — ganhe suporte de especialistas virtuais em todas as áreas do direito
+- **Escritórios de Advocacia (Boutiques e Massificados)** — crie pipelines reutilizáveis para triar centenas de peças por dia
+- **Departamentos Jurídicos In-House** — automatize análise de contratos, due diligence corporativa e adequação à LGPD
+- **Pesquisadores Jurídicos** — encontre teses, jurisprudências e sumulas relacionadas aos autos rapidamente
+
+## O que dá pra fazer?
+
+- **Análise de Iniciais e Defesas** — ler autos densos, extrair fatias de prazo, pedidos e fatos principais
+- **Anonimização Automática LGPD** — preparar documentos protegidos para análise de modelos de LLM na nuvem
+- **Elaboração de Minutas e Pareceres** — cruzar argumentos de especialistas para redigir peças processuais
+- **Triagem Massificada** — ler publicações nos diários oficiais e encaminhar para a frente de trabalho correta
+- **Auditoria de Contratos** — revisar cláusulas buscando riscos para a empresa ou para o cliente
+
+## Instalação
+
+**Pré-requisito:** Node.js 20+
+
+```bash
+npx conectese init
+```
+
+Para atualizar uma instalação existente:
+
+```bash
+npx conectese update
+```
+
+## IDEs Suportadas
+
+| IDE | Status |
+|-----|--------|
+| Claude Code | Disponível |
+| Cursor | Disponível |
+| VS Code + Copilot | Disponível |
+| Codex (OpenAI) | Disponível |
+| Open Code | Disponível |
+| Antigravity | Disponível |
+
+## Escritório Virtual (Conectese Dashboard)
+
+O Escritório Virtual é uma interface visual 2D que mostra seus agentes trabalhando no seu caso em tempo real.
+
+**Passo 1 — Gere o dashboard** (na sua IDE):
+
+```
+/conectese dashboard
+```
+
+**Passo 2 — Sirva localmente** (no terminal):
+
+```bash
+npx serve squads/<nome-do-squad>/dashboard
+```
+
+**Passo 3 —** Abra `http://localhost:3000` no seu navegador.
+
+## Criando seu Squad
+
+Abra o menu:
+
+```
+/conectese
+```
+
+O **Conectese** vai te mostrar as opções disponíveis. 
+
+Para criar um novo squad personalizado, o **Arquiteto** fará algumas perguntas sobre qual a área do seu escritório e o tipo de casos, e projetará o squad ideal configurando tudo. Você sempre aprova o design (a "tese") antes de qualquer execução.
+
+## Executando um Squad
+
+Você pode executar a triagem de um caso pedindo diretamente:
+
+```
+/conectese rode o squad <nome-do-squad>
+```
+
+A equipe de IA inicia, pausando nos checkpoints onde os analistas jurídicos pedirão o input estratégico do Advogado (Human-in-the-Loop).
+
+## Exemplos
+
+```
+/conectese
+/conectese crie um Squad que receba sentenças de primeiro grau e levante possibilidades de embargo ou apelação
+/conectese quero um Squad focado em Direito Tributário que analise autos de infração e sugira defesas
+/conectese crie um Squad que higieniza dados LGPD de processos de Direito de Família e gera resumos seguros
+/conectese roda o squad analise-tributaria
+```
+
+## Comandos
+
+| Comando | O que faz |
+|---------|-----------|
+| `/conectese` | Abre o menu principal |
+| `/conectese help` | Mostra todos os comandos |
+| `/conectese create` | Cria um novo squad / equipe de IA |
+| `/conectese run <nome>` | Analisa um caso no squad |
+| `/conectese list` | Lista seus squads de IA |
+| `/conectese edit <nome>` | Modifica as diretrizes de uma equipe |
+| `/conectese skills` | Navega pelas habilidades jurídicas instaladas |
+| `/conectese install <nome>` | Instala uma habilidade do catálogo |
+| `/conectese uninstall <nome>` | Remove uma habilidade instalada |
+
+## Custo de Tokens
+
+O conectese é open source e pode ser usado gratuitamente como software de orquestração. O uso de LLMs locais mantém os dados sigilosos na sua máquina (usando Ollama, LM Studio, etc).
+
+No uso de inteligência de fronteira (Claude Pro/Max, OpenAI API, Gemini Advanced):
+- O repasse das peças anonimizadas aos LLMs tem custo de tokens de acordo com o tamanho do processo escaneado.
+- Recomenda-se estritamente o uso dos agentes **LGPD-Anonymizers** primeiro, para que apenas os dados anonimizados trafeguem nas APIs.
+
+## Sessões de Navegador e Privacidade
+
+Caso um agente precise buscar atualizações de jurisprudência ativas, ele usa um navegador automatizado.
+- **Isolamento de Sessão:** Cookies de jusbrasil/STJ são salvos apenas em `_conectese/_browser_profile/` que nunca sai da sua máquina ou vai para o Git.
+
+## Sobre
+
+O conectese é mantido como base de um projeto open source. Esta implementação específica foi transformada em um motor de inteligência e segurança jurídica projetado para advogados e escritórios de advocacia que precisam escalar o raciocínio forense humano com confiança.
+
+Saiba mais em [conecte.se](https://conecte.se) ou entre em contato via carlos@conecte.se.
+
+## Licença
+
+MIT — use como quiser.
+
+---
+
+# conectese (English)
+
+Create AI squads specialized in the Legal environment — right from your IDE.
+
+conectese is a multi-agent orchestration framework geared entirely towards **Lawyers, Law Firms, and Corporate Legal Departments**. Describe your case needs in plain language, and conectese creates a team of AI legal analysts and agents who work together to enhance procedural analysis, guarantee privacy (GDPR/LGPD), and support your decision-making.
+
+## Learn more
+
+[conecte.se](https://conecte.se) - **Contact:** carlos@conecte.se
+
+## What is a Legal Squad?
+
+A legal squad is a team of AI agents that collaborate to dissect a lawsuit, draft legal documents, or anonymize evidence. They run in a pipeline with checkpoints where the agent pauses and asks for the Head Human Lawyer's approval before proceeding with sensitive decisions.
+
+Example:
+
+- **Data Extractor** parses raw PDF filings
+- **LGPD Anonymizer** redacts PII and sanitizes the facts
+- **Legal Analyst** maps out the procedural landscape
+- **Specialists Routing** channels tasks to domain-specific AIs (Tax, Civil, Criminal)
+- **Legal Draftsperson** sews arguments into a final brief
+- **Data Restorer** reinjects real names maintaining confidentiality
+
+## Installation
+
+**Prerequisite:** Node.js 20+
+
+```bash
+npx conectese init
+```
+
+To update an existing installation:
+
+```bash
+npx conectese update
+```
+
+## Supported IDEs
+
+| IDE | Status |
+|-----|--------|
+| Claude Code | Available |
+| Cursor | Available |
+| VS Code + Copilot | Available |
+| Codex (OpenAI) | Available |
+| Open Code | Available |
+| Antigravity | Available |
+
+## Virtual Office
+
+The Virtual Office is a 2D interface showing your AI legal team working in real time.
+
+**Step 1 — Generate the dashboard** (in your IDE):
+```
+/conectese dashboard
+```
+
+**Step 2 — Serve it locally** (in terminal):
+```bash
+npx serve squads/<squad-name>/dashboard
+```
+
+**Step 3 —** Open `http://localhost:3000` in your browser.
+
+## Creating your Squad
+
+Describe what you need:
+
+```
+/conectese create "A squad that reviews M&A contracts and flags liabilities"
+```
+
+The **Architect** asks a few questions, designs the legal squad, and sets everything up safely. You approve the design before execution.
+
+## Running a Squad
+
+```
+/conectese run <squad-name>
+```
+
+The squad runs automatically, pausing at critical junctures if legal interpretation is ambiguous to ask for your strategic guidance.
+
+## Examples
+
+```
+/conectese create "Squad that reads 1st degree sentences and draft grounds for appeal"
+/conectese create "Squad that sanitizes GDPR/LGPD data on family court proceedings"
+/conectese create "Squad that audits labor contracts against current regulations"
+```
+
+## Token Cost
+
+conectese itself is completely free and open source. For utmost confidentiality, you can use OpenCode with local offline LLMs. 
+When leveraging frontier models (Claude, OpenAI):
+- Passing massive case dossiers will incur higher token costs per run.
+- Using the **Anonymizer** agent beforehand ensures you are not passing sensitive PII into external APIs inadvertently.
+
+## Browser Sessions & Privacy
+
+When fetching active jurisprudence, conectese can perform browser actions locally.
+- **Persistent cookies:** stored completely locally in `_conectese/_browser_profile/`.
+
+## About
+
+This implementation of conectese has been heavily customized to serve as a legal intelligence engine, designed for law firms needing to scale their forensic rationale confidently and safely.
+
+Learn more at [conecte.se](https://conecte.se) or reach out at carlos@conecte.se.
+
+## License
+
+MIT — use it however you want.

package/_conectese/.conectese-version

@@ -0,0 +1 @@
+0.1.0

package/_conectese/config/playwright.config.json

@@ -0,0 +1,11 @@
+{
+  "browser": {
+    "browserName": "chromium",
+    "isolated": false,
+    "userDataDir": "_conectese/_browser_profile",
+    "launchOptions": {
+      "headless": true,
+      "channel": "chrome"
+    }
+  }
+}

package/_conectese/core/architect.agent.yaml

@@ -0,0 +1,110 @@
+# SHARED — applies to ALL IDEs. Do not add IDE-specific logic here.
+# For IDE-specific behavior: templates/ide-templates/{ide}/ only.
+agent:
+  webskip: false
+  metadata:
+    id: "_conectese/core/architect"
+    name: Arquiteto
+    title: Squad Architect
+    icon: 🧠
+    squad: core
+    hasSidecar: false
+
+  persona:
+    role: >
+      Squad Architecture Specialist who designs multi-agent teams and
+      automated pipelines. Translates business needs into optimized
+      squad configurations with the right agents, workflows, and skills.
+    identity: >
+      Strategic systems thinker who sees organizations as interconnected
+      workflows. Has an instinct for breaking complex processes into
+      clear agent responsibilities. Patient with non-technical users,
+      always explains decisions in plain language. Believes the best
+      squad is the simplest one that gets the job done.
+    communication_style: >
+      Clear and structured. Uses numbered lists and visual separators
+      to organize information. Asks one question at a time. Confirms
+      understanding before proceeding. Speaks naturally — never instructs
+      the user like a form ("reply with a number", "type yes to confirm").
+      Just presents options and lets the user respond however they want.
+    principles:
+      - YAGNI — never create agents that aren't strictly necessary
+      - Each agent must have exactly one clear responsibility
+      - Pipelines must have checkpoints at every user decision point
+      - Default to the simplest pipeline that achieves the goal
+      - "Path safety: Never use Bash mkdir to create directories. Always use the Write tool to create files — it creates parent directories automatically and avoids Windows/Bash path separator conflicts (backslash vs forward slash)."
+
+  discussion: true
+
+  menu:
+    - trigger: CS or fuzzy match on create-squad or create
+      description: "[CS] Create a new squad from natural language description"
+      action: create-squad
+
+    - trigger: ES or fuzzy match on edit-squad or edit or modify
+      description: "[ES] Edit an existing squad"
+      action: edit-squad
+
+    - trigger: LS or fuzzy match on list-squads or list or my squads
+      description: "[LS] List all squads"
+      action: list-squads
+
+    - trigger: DS or fuzzy match on delete-squad or delete or remove
+      description: "[DS] Delete a squad"
+      action: delete-squad
+
+  workflows:
+    create-squad: |
+      ## Create Squad
+
+      The create flow is now handled by the phased orchestration system.
+      See the SKILL.md entry point for the full phased flow:
+      Discovery → Investigation → Design → Template Selection (optional) → Build
+
+      Each phase is a separate prompt in `_conectese/core/prompts/`:
+      - `discovery.prompt.md` — Phase 1: Intelligent wizard
+      - `sherlock-*.md` — Phase 2: Investigation (optional)
+      - `design.prompt.md` — Phase 3: Squad architecture (includes optional Phase G.5: Template Selection)
+      - `build.prompt.md` — Phase 4: File generation + validation
+
+      The SKILL.md orchestrator dispatches each phase as a subagent.
+
+    edit-squad: |
+      ## Edit Squad Workflow
+
+      1. Ask which squad to edit (list available squads if not specified).
+         If only 1 squad exists, add "Cancel" as a second option. If 0 squads, inform user directly.
+      2. Read the squad's squad.yaml to understand current structure
+      3. Ask what changes the user wants
+      4. **If the user asks to edit/define/change the visual template or identity of a design agent:**
+         - Read and follow `skills/template-designer/SKILL.md`
+         - If `template-reference.html` and `visual-identity.md` already exist in the squad's `pipeline/data/`, load them as the starting point
+      5. Modify the relevant files (agent .md files, pipeline steps, squad.yaml)
+      6. Present summary of changes
+      7. Confirm with user
+
+    list-squads: |
+      ## List Squads Workflow
+
+      1. Read all directories in squads/
+      2. For each, read squad.yaml to get name, description, icon, agent count
+      3. Present as a formatted list:
+         ```
+         Your Squads:
+         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+         📋 my-squad
+            My Squad Description
+            3 agents | Last run: never
+         ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+         ```
+      4. If no squads exist, suggest creating one
+
+    delete-squad: |
+      ## Delete Squad Workflow
+
+      1. Ask which squad to delete (list available if not specified).
+         If only 1 squad exists, add "Cancel" as a second option. If 0 squads, inform user directly.
+      2. Show squad details (name, agents, output count)
+      3. Confirm deletion with explicit "Are you sure?" presented as a numbered list (1. Yes, delete / 2. No, cancel)
+      4. If confirmed, delete the entire squads/{code}/ directory
+      5. Confirm deletion

package/_conectese/core/best-practices/_catalog.yaml

@@ -0,0 +1,116 @@
+# Best Practices Catalog
+# The Architect reads this file to discover which best-practices are available.
+# Read the full file only for best-practices relevant to the squad being created.
+
+catalog:
+  # === Discipline Best Practices ===
+  - id: copywriting
+    name: "Copywriting & Persuasive Writing"
+    whenToUse: "Creating agents that write persuasive copy, hooks, CTAs, social media captions, sales content, or viral angles."
+    file: copywriting.md
+
+  - id: researching
+    name: "Research & Data Collection"
+    whenToUse: "Creating agents that research topics, collect data from the web, verify facts, or produce structured research briefs."
+    file: researching.md
+
+  - id: review
+    name: "Content Review & Quality Control"
+    whenToUse: "Creating agents that evaluate content quality, score against criteria, or produce structured APPROVE/REJECT verdicts."
+    file: review.md
+
+  - id: image-design
+    name: "Visual Design & Image Creation"
+    whenToUse: "Creating agents that design graphics, carousel slides, social media visuals, or HTML/CSS templates for rendering."
+    file: image-design.md
+
+  - id: social-networks-publishing
+    name: "Social Networks Publishing"
+    whenToUse: "Creating agents that publish content to Instagram, LinkedIn, X/Twitter, YouTube, or other social platforms."
+    file: social-networks-publishing.md
+
+  - id: strategist
+    name: "Strategy & Editorial Planning"
+    whenToUse: "Creating agents that plan content strategy, editorial calendars, competitive positioning, or audience segmentation."
+    file: strategist.md
+
+  - id: technical-writing
+    name: "Technical & Long-Form Writing"
+    whenToUse: "Creating agents that write articles, blog posts, documentation, tutorials, white papers, or educational content."
+    file: technical-writing.md
+
+  - id: data-analysis
+    name: "Data Analysis & Interpretation"
+    whenToUse: "Creating agents that interpret metrics, extract insights, benchmark performance, or produce analytical reports."
+    file: data-analysis.md
+
+  # === Platform Best Practices ===
+  - id: instagram-feed
+    name: "Instagram Feed & Carousels"
+    whenToUse: "Creating agents that produce Instagram feed posts, carousels, or static image content for Instagram."
+    file: instagram-feed.md
+
+  - id: instagram-reels
+    name: "Instagram Reels"
+    whenToUse: "Creating agents that produce Instagram Reels or short-form vertical video for Instagram."
+    file: instagram-reels.md
+
+  - id: instagram-stories
+    name: "Instagram Stories"
+    whenToUse: "Creating agents that produce Instagram Stories or ephemeral 24-hour content."
+    file: instagram-stories.md
+
+  - id: linkedin-post
+    name: "LinkedIn Post"
+    whenToUse: "Creating agents that produce LinkedIn posts, text updates, or document carousels for LinkedIn."
+    file: linkedin-post.md
+
+  - id: linkedin-article
+    name: "LinkedIn Article"
+    whenToUse: "Creating agents that produce LinkedIn articles or long-form professional content."
+    file: linkedin-article.md
+
+  - id: twitter-post
+    name: "Twitter/X Post"
+    whenToUse: "Creating agents that produce tweets, quote tweets, or single posts for X/Twitter."
+    file: twitter-post.md
+
+  - id: twitter-thread
+    name: "Twitter/X Thread"
+    whenToUse: "Creating agents that produce Twitter/X threads or multi-tweet narratives."
+    file: twitter-thread.md
+
+  - id: youtube-script
+    name: "YouTube Video Script"
+    whenToUse: "Creating agents that produce YouTube video scripts or long-form video content."
+    file: youtube-script.md
+
+  - id: youtube-shorts
+    name: "YouTube Shorts"
+    whenToUse: "Creating agents that produce YouTube Shorts or short-form vertical video for YouTube."
+    file: youtube-shorts.md
+
+  - id: email-newsletter
+    name: "Email Newsletter"
+    whenToUse: "Creating agents that produce email newsletters or recurring subscriber content."
+    file: email-newsletter.md
+
+  - id: email-sales
+    name: "Sales Email"
+    whenToUse: "Creating agents that produce sales emails, cold outreach, or direct response email campaigns."
+    file: email-sales.md
+
+  - id: blog-post
+    name: "Blog Post"
+    whenToUse: "Creating agents that produce blog posts, articles, or long-form content marketing."
+    file: blog-post.md
+
+  - id: blog-seo
+    name: "Blog Post (SEO)"
+    whenToUse: "Creating agents that produce SEO-optimized blog posts or search-targeted content."
+    file: blog-seo.md
+
+  - id: whatsapp-broadcast
+    name: "WhatsApp Broadcast"
+    whenToUse: "Creating agents that produce WhatsApp broadcast messages or conversational marketing content."
+    file: whatsapp-broadcast.md

package/_conectese/core/best-practices/blog-post.md

@@ -0,0 +1,132 @@
+---
+name: "Blog Post"
+platform: "blog"
+content_type: "post"
+description: "Long-form blog posts optimized for readability, engagement, and clear value delivery with structured subheadings"
+whenToUse: |
+  Creating agents that produce blog posts, articles, or long-form content marketing.
+constraints:
+  optimal_word_count: "1500-2500"
+  title_max_chars: 70
+  meta_description_chars: 160
+  subheading_frequency: "every 200-300 words"
+version: "1.0.0"
+---
+
+## Platform Rules
+
+- Average time on page is the strongest engagement signal. Blog posts that keep readers scrolling for 3-5 minutes outperform those that get abandoned in the first 30 seconds. Structure and readability directly determine this metric.
+- Posts between 1,500-2,500 words hit the optimal balance of depth and retention. Below 800 words, content is perceived as thin and struggles to rank. Above 3,000 words, completion rates drop unless the topic demands exhaustive coverage.
+- Mobile readability is non-negotiable. Over 60% of blog traffic comes from mobile devices. Long paragraphs, wide images, and dense formatting that work on desktop become unreadable walls on small screens.
+- Subheadings serve as a scannable table of contents. Studies show 73% of readers scan blog posts rather than reading word by word. If the subheadings alone do not convey the article's value, the structure needs reworking.
+- Internal linking keeps readers on site and distributes page authority. Posts with 3+ internal links to related content have higher average session duration and lower bounce rates.
+- External links to authoritative sources (research, industry leaders, official documentation) increase credibility and can positively impact search ranking when linking to genuinely relevant resources.
+- Publishing consistency builds audience expectation and return visits. A regular cadence (1-2 posts per week) outperforms sporadic publishing bursts followed by silence.
+- Visual breaks every 300 words prevent fatigue: images, callout boxes, bullet lists, or blockquotes. Unbroken text spanning more than 300 words causes readers to disengage.
+
+## Content Structure
+
+### Blog Post Architecture
+
+1. **Title** — Under 70 characters. Clearly communicates what the reader will learn or gain. Front-load the key topic. Avoid vague or overly clever titles that sacrifice clarity for creativity.
+2. **Meta description** — 150-160 characters. Summarizes the post's value proposition in one sentence. This appears in search results and social shares — it is a second headline.
+3. **Intro hook (2-3 sentences)** — Open with a surprising stat, bold claim, relatable problem, or a story that places the reader in a scenario. Then state exactly what the post will deliver.
+4. **Body sections (3-6 H2 sections)** — Each section covers one major point with its own H2 subheading. Sections are 200-300 words each with H3 sub-sections for deeper breakdowns.
+5. **Conclusion (3-5 sentences)** — Summarize the key takeaways in 1-2 sentences, then deliver a clear CTA: read a related post, download a resource, leave a comment, or try a specific action.
+
+### Section-Level Structure
+
+- **H2 subheading** — Descriptive, scannable, and self-contained. A reader should understand the section's value from the heading alone.
+- **Opening sentence** — State the section's key point immediately. Do not build up to the insight.
+- **Supporting content** — Evidence, examples, data, or step-by-step instructions. Use bullet points for lists of 3+ items.
+- **Transition** — Final sentence bridges to the next section or reinforces the section's takeaway.
+
+### Effective Post Formats
+
+- **How-to guide**: "How to [achieve X]: A Step-by-Step Guide"
+- **Listicle**: "7 [Things] That [Outcome] (and How to Use Them)"
+- **Problem/Solution**: "Why [Problem Exists] and What to Do About It"
+- **Lessons learned**: "What I Learned From [Experience]: [N] Key Takeaways"
+- **Comparison**: "[Option A] vs. [Option B]: Which Is Right for [Audience]?"
+
+## Writing Guidelines
+
+- **Hook the reader in the first 2-3 sentences or lose them.** Open with a stat, question, bold claim, or relatable scenario. Never start with a dictionary definition or generic background. "Content marketing is important" loses readers. "87% of blog posts get zero organic traffic" keeps them.
+- Write in short paragraphs: 3-4 lines maximum on desktop, which translates to 2-3 lines on mobile. Single-sentence paragraphs are powerful for emphasis.
+- Bold key phrases and takeaways within paragraphs so scanners can extract value without reading every word.
+- Use bullet points and numbered lists for any sequence of 3+ items. Lists are easier to scan than inline comma-separated items.
+- Subheadings every 200-300 words. Each H2 should read like a mini-headline that a scanner would click on if presented independently.
+- Write in second person ("you") to create direct connection with the reader. First person ("I/we") works for personal stories and experience-based authority.
+- Include at least one visual break (image, callout box, blockquote, or list) every 300 words. Continuous text blocks cause reader fatigue and increase bounce rate.
+- End with a specific, actionable CTA. "What do you think?" is weak. "Try implementing [technique] this week and comment below with your results" is strong.
+- Include 3+ internal links to related content on your site and 2+ external links to authoritative sources. Link naturally within context, not in a dumped list at the end.
+- Write the title last, after you know what the post delivers. Front-load the most important keyword or concept in the first 40 characters.
+
+## Output Format
+
+```
+=== TITLE ===
+[Under 70 characters — clear, specific, keyword front-loaded]
+
+=== META DESCRIPTION ===
+[150-160 characters — summarizes the post's value proposition in one sentence]
+
+=== INTRO ===
+[Hook — surprising stat, bold claim, relatable problem, or opening story. 1-2 sentences.]
+
+[Promise — exactly what the reader will learn or gain from this post. 1 sentence.]
+
+=== BODY ===
+## [H2 Section 1 Title]
+[200-300 words — one major point with evidence, examples, or steps. Include bullet points or visuals where appropriate.]
+
+## [H2 Section 2 Title]
+[200-300 words — one major point with evidence, examples, or steps.]
+
+### [H3 Subsection if needed]
+[Deeper breakdown of a specific aspect — 100-150 words.]
+
+## [H2 Section 3 Title]
+[200-300 words — one major point with evidence, examples, or steps.]
+
+## [H2 Section 4 Title]
+[200-300 words — one major point with evidence, examples, or steps.]
+
+[Continue for 3-6 H2 sections total]
+
+=== CONCLUSION ===
+[Key takeaway summary — 1-2 sentences.]
+
+[CTA — specific, actionable ask. 1-2 sentences.]
+
+=== POST NOTES ===
+Target word count: [1500-2500]
+Internal links needed: [3+ with suggested anchor text]
+External links needed: [2+ to authoritative sources]
+Visual breaks: [List of suggested image/callout placements]
+```
+
+## Quality Criteria
+
+- [ ] Title is under 70 characters and clearly communicates the post's value
+- [ ] Meta description is 150-160 characters and serves as a compelling second headline
+- [ ] Intro hooks the reader in the first 2-3 sentences with a stat, bold claim, or relatable scenario
+- [ ] Post contains 3-6 H2 sections, each covering one major point
+- [ ] Subheadings appear every 200-300 words and are scannable as a standalone outline
+- [ ] Paragraphs are 3-4 lines maximum with key phrases bolded
+- [ ] At least one visual break (image, callout, list, or blockquote) every 300 words
+- [ ] 3+ internal links and 2+ external links are included with natural anchor text
+- [ ] Total word count is between 1,500-2,500 words
+- [ ] Conclusion ends with a specific, actionable CTA (not generic "What do you think?")
+
+## Anti-Patterns
+
+- **Walls of text** — Paragraphs exceeding 5-6 lines on desktop become impenetrable on mobile. Readers bounce rather than parse dense blocks. Short paragraphs and visual breaks are not optional — they are structural requirements for retention.
+- **No subheadings** — A 2,000-word post without H2/H3 subheadings is functionally a wall of text. Scanners (73% of readers) cannot extract value and leave. Subheadings serve as both navigation and content promises.
+- **Clickbait titles that do not deliver** — "This One Trick Changed Everything" followed by generic advice destroys trust. The reader feels deceived, bounces quickly, and never returns. High bounce rates also signal low quality to search engines.
+- **Thin content under 800 words** — Short posts struggle to provide sufficient depth, rank poorly for competitive keywords, and signal low effort. If the topic can be covered in 500 words, it may be better as a social post than a blog article.
+- **No conclusion or CTA** — Posts that simply stop after the last body section feel incomplete. The reader has invested 3-5 minutes and receives no guidance on what to do next. Every post needs a clear ending and next step.
+- **Dictionary definition openings** — Starting with "[Topic] is defined as..." is the most common sign of filler content. It adds no value, wastes the most important real estate in the post, and signals that the writer has nothing original to say.
+- **Link dumping** — Placing all internal and external links in a list at the bottom of the post rather than weaving them naturally into the content. Contextual links are clicked more and provide more value to the reader.
+- **No visual breaks** — Continuous text for 500+ words without an image, list, callout, or blockquote causes reading fatigue. Even well-written content gets abandoned when it is visually monotonous.
+- **Writing for search engines instead of humans** — Unnaturally forcing keywords into every sentence makes content awkward and unpleasant to read. Write for clarity first; optimize for search second.