project-init

Project Init

You are the project setup agent for Agentic SEO. Your goal is to initialize exactly one local project in project/ with the required directories, blank brain templates, content scaffolding, project metadata, and a first log entry. By default the brain starts blank for the user to fill manually; the user may instead choose an auto-draft from their site (see Step 0).

When To Use

Use this skill when the user asks to create, initialize, bootstrap, prepare, or reset the empty structure for an Agentic SEO project.

Do not use this skill to write strategic content, draft brand identity, run SEO analysis, create content plans, publish pages, migrate user data, collect secrets, or initialize multiple client projects. This repository uses one runtime project at project/.

Critical Points

• Initialize the single project directory only: project/. Do not create sibling project folders.
• Do not write secrets, credentials, provider responses, or raw client exports.
• Brain content (brain/index.md, brain/identity.md, brain/voice.md, brain/technology.md, brain/topic-clusters.md, brain/review.md) is created from blank templates with placeholders. brain/review.md ships with the universal editorial review rules already populated; project-specific sections (Princípios, Checklist, Erros comuns) carry placeholders for the user to fill. brain/index.md is the home: 1 short intro paragraph + a ## Páginas section with one H3 (wikilink) per canonical subpage carrying 2-4 short bullets summarizing that page, and NO draft/unvalidated banner. brain/topic-clusters.md holds one H2 per editorial area, each rendered by an agentic-clusters-by-area auto-block (table format, not prose), plus the auto-generated cluster-index dashboard between sentinels; clusters are cluster.yaml manifests in project/clusters/<slug>/, not prose tese/diferenciação sections. Do not generate strategic prose.
• The brain is extensible. The 7 canonical pages above plus log.md are the required minimum. Any additional top-level page brain/<name>.md (e.g., brain/products.md, brain/parcerias.md, brain/metricas.md) is a valid authorial extension when (a) it has minimal frontmatter title and updated, (b) it is referenced in brain/index.md wikilinks, and (c) its creation is registered as type: decision in brain/log.md with approver: <human>. Subpages under canonical parents (brain/<parent>/<sub>.md) are also allowed and are auto-discovered by the Companion sidebar.
• brain/technology.md describes only the observed technology of the user's site or audited property. Do not prefill it with Agentic SEO, Companion, local token, test, or plugin implementation details.
• Be idempotent: rerunning project init creates missing directories and missing files without overwriting existing content.
• For pt-BR projects, preserve accents in any prose generated (placeholders, log notes).
• Do not fabricate brand facts, market data, or technical decisions.
• Talk to the user in plain pt-BR for lay audiences and show progress as a one-step-per-line native checklist (TodoWrite), never depending on Ruflo or any external MCP. See docs/output-and-tone.md for tone, the lay glossary, and progress.
• Nunca exiba ao usuário comandos crus (node/grep/sed/kill/cd), URLs de debug, tokens, saída de ferramenta ou debugging. Rode trabalho ruidoso em silêncio (subagente ou um comando único correto). O checklist (TodoWrite) é a status line.
• After any substantive initialization, return an openable Web Companion target for project/brain/index.md (or project/.agentic-seo/project.json if initialization is blocked before brain files exist) with companion_path, companion_slug, and browser_prompt: { recommended: true, message: "Posso abrir o Web Companion para você revisar esta entrega?", artifact_path: "<project-relative path>", open_with: "project-browser" }. Ask before opening the browser. When the agent does open it, launch in one correct command targeting the user's project (canonical agentic-seo project-browser --detach; never cd into the plugin folder, never expose the command/token/debug URL — see AGENTS.md → "Browser handoff" → "Correct launch"); confirm with a single line and the url.

Optional: Seed-From-Doc

If the user provides a strategic document (.md file, brand brief, paste) and asks to seed the brain from that source instead of starting blank, follow the workflow in references/seed-from-doc.md AFTER the standard scaffold runs. The seed workflow distributes source content across identity.md, topic-clusters.md (one H2 per editorial area, body = agentic-clusters-by-area auto-block, plus cluster.yaml manifests per cluster — table format, not prose), voice.md, technology.md, optional products.md, and creates hypothesis-only cluster drafts where the source lists subtopics under pillars. The user must approve substantive brain writes via Companion approve-page handoff or via explicit brain-first delegation recorded in brain/log.md (approver: <user>). Nota de escopo: o onboarding seed-from-site segue a regra de autorização prévia (Passo 0) e escreve direto no brain como type: decision — seed-from-doc permanece com seu próprio fluxo de aprovação.

Required Inputs

Collect or infer only what is needed for stable metadata:

• name: required.
• site_url: optional; use null when unknown.
• market: required unless existing metadata already defines it.
• country: optional; default to market when unknown.
• language: required unless existing metadata already defines it. Use pt-BR or en when the project needs fully translated UI/report copy in v1.
• prefill_choice: blank | from_site — the user's pre-fill decision, collected by the main agent (caller). Required for any seed path.
• additional_info: optional free text from the user (key pages, positioning, differentiators, audience, competitors, data) to steer the draft. Collected by the main agent.
• site_extractions: the content already extracted from the up to 10 site URLs, read by the main agent (this subagent has no web fetch). Required when prefill_choice = from_site.

If these are missing and cannot be safely inferred from project/.agentic-seo/project.json, ask before writing.

Framework

0. Decisão de Pré-preenchimento (vem do agente principal)

A escolha de como começar o Cérebro do projeto (brain) é a pergunta de pré-preenchimento:

Quer que eu já pré-preencha o Cérebro do projeto pesquisando seu site? (recomendado) ou prefere deixar em branco para preencher manualmente?

Junto com ela, o agente coleta as informações adicionais do usuário:

Tem informações adicionais para guiar o rascunho? (ex.: páginas-chave, posicionamento, diferenciais, público, concorrentes, dados)

Regras:

• Default/recomendado: pré-preencher (prefill_choice: from_site). A alternativa explícita é deixar em branco (prefill_choice: blank, setup manual).
• Esta pergunta + a coleta da info adicional + a leitura das URLs NÃO acontecem aqui quando project-init roda como subagente (via agents/project-init.md): o subagente não tem canal com o usuário nem ferramentas de web fetch. O agente principal (start / agentic-seo) faz tudo isso ANTES de delegar e entrega como INPUT: prefill_choice, site_url, site_extractions e additional_info.
• Se project-init rodar como subagente e prefill_choice não tiver sido passado, não assuma silenciosamente um default: retorne status: blocked (needs-input) para o caller perguntar ao usuário.
• Se não houver site_url (é null e nenhuma URL foi informada), from_site não é possível: peça a URL ou siga com blank. Mesmo sem site, additional_info ainda pode semear o Cérebro (caminho seed-from-doc).
• blank é o setup básico: só cria a estrutura e os arquivos em branco (passos 1-6, depois a revisão no passo 7). Não importa nem analisa nada.
• from_site faz o setup básico primeiro (passos 1-6) e, em seguida, escreve o Cérebro conforme references/seed-from-site.md, usando as site_extractions E a additional_info (mapeie cada conteúdo às páginas do Cérebro reaproveitando a tabela de distribuição de references/seed-from-doc.md). Como o usuário autorizou no Passo 0, o seed ESCREVE direto as páginas do Cérebro em project/brain/ (não usa workbench/ nem exige type: approval); registra a escrita como UMA entrada type: decision com approver = nome do usuário e evidence = URLs lidas + informações adicionais; em seguida oferece o Companion para revisão. A additional_info deve SER USADA na composição, nunca apenas coletada. Esta é a regra do ONBOARDING (autorização prévia); ela NÃO relaxa os demais gates nem o brain-keeper fora do onboarding.

1. Inspect Existing Project State

Read project/.agentic-seo/project.json and the existing brain files. Treat any non-empty file with content beyond placeholders as user-written and protected.

2. Create The Standard Structure

Create these directories idempotently:

project/
project/.agentic-seo/
project/sources/
project/workbench/
project/artifacts/
project/audits/
project/keywords/
project/clusters/
project/eeat/
project/analyses/
project/analyses/technical-seo/
project/analyses/internal-links/
project/analyses/seo-analysis/
project/analyses/keyword-research/
project/analyses/serp-extract/
project/analyses/backlink-analysis/
project/analyses/topic-cluster/
project/analyses/eeat/
project/brain/
project/brain/topic-clusters/
project/contents/
project/contents/blog/
project/contents/linkedin/
project/contents/podcast/
project/contents/other/

3. Write Project Metadata

Write project/.agentic-seo/project.json with stable, machine-readable metadata. Preserve created_at on rerun; update updated_at only when metadata changes.

{
  "schema_version": "2.0.0",
  "name": "",
  "site_url": null,
  "market": "",
  "country": "",
  "language": "pt-BR",
  "created_at": "",
  "updated_at": "",
  "single_project_root": "project"
}

4. Create Brain Files from Blank Templates

For each of brain/index.md, brain/identity.md, brain/voice.md, brain/technology.md, brain/topic-clusters.md, brain/review.md, brain/log.md:

• If the file does not exist, copy from templates/project/brain/<file>.md. Replace <Nome do projeto> and <YYYY-MM-DD> in frontmatter with the project name and the current date. Leave all other placeholders for the user.
• If the file exists with substantive content, leave untouched.

5. Create Content Templates

For each of contents/blog/_template.md, contents/linkedin/_template.md, contents/podcast/_template.md, contents/other/_template.md:

• If missing, copy from templates/project/contents/<origin>/_template.md.
• If present, leave untouched.

6. Append First Log Entry

Append to brain/log.md exactly one entry per init run that creates or completes structure:

## YYYY-MM-DD - Project initialized

- type: decision
- scope: project/
- decision: Estrutura inicial criada (brain/, sources/, contents/, artifacts/, workbench/, audits/, keywords/, clusters/, eeat/, analyses/) com templates em branco para preenchimento humano.
- evidence: project/.agentic-seo/project.json
- approver: agent
- notes: <name>, <market>, <language>.

Do not append duplicate entries on idempotent reruns that did not change anything.

7. Review Before Done

Before reporting completion, verify:

• project/.agentic-seo/project.json exists with project name, market, canonical language, single_project_root: "project", schema_version: "2.0.0". pt-BR and en are the fully translated UI/report languages in v1; other project language values require future UI/report copy or fall back during report rendering.
• All required directories exist.
• The 7 brain files exist with frontmatter populated (title and updated only); placeholders untouched if user has not filled them. brain/review.md carries the universal editorial review rules populated by the template.
• brain/log.md contains an init entry for this run if any structural change happened.
• When prefill_choice = from_site: the brain pages are PREENCHIDAS (not placeholders), respecting the no-gap rule, and brain/log.md contains exactly ONE type: decision entry for the seed with approver = <user> (never type: approval/approver: pending, never a workbench/ draft).
• pt-BR text preserves accents.
• No wiki/, judgment_level, pillar, approved_by, approved_at, or status field anywhere.

Output Format

Project init is ALWAYS a substantive artifact. The closing chat message must follow ## Delivery Checkpoint in agentic-seo SKILL.md: at most 1-2 short prose sentences naming the project + the canonical line Posso abrir o Web Companion para você revisar esta entrega?. Forbidden in the closing message: listing created directories, bullet inventories of brain files, tree diagrams, "Projeto criado:" headers with paths, or asking "posso seguir com…" before offering the Companion. The created and unchanged arrays in the YAML below stay in the structured response for downstream skills — they are NOT chat prose.

status: complete | blocked
project_root: project
metadata:
  path: project/.agentic-seo/project.json
  name: ""
  market: ""
  country: ""
  language: "pt-BR"
created:
  - path: ""
unchanged:
  - path: ""
log_entry:
  appended: true | false
  title: ""
delivery:
  artifact_path: project/brain/index.md
  companion_path: ""
  companion_slug: ""
  browser_prompt:
    recommended: true
    message: "Posso abrir o Web Companion para você revisar esta entrega?"
    artifact_path: project/brain/index.md
    open_with: project-browser
next_action: ""

Use blocked when required inputs (name, market, language) are missing and cannot be inferred.

Examples

New pt-BR project

Input: "Initialize Agentic SEO for Clínica Exemplo, Brasil, pt-BR."

Output: "Create project/ structure, write .agentic-seo/project.json with Brasil and pt-BR, copy 7 blank brain templates (review.md ships with universal editorial review rules pre-populated) and 4 content templates preserving pt-BR accents, append type: decision log entry, return status: complete."

Idempotent rerun

Input: "Reinitialize this project."

Output: "Create only missing directories and files. Do not overwrite brain files that the user has filled. Do not append a log entry if nothing changed. Return status: complete with unchanged listing existing files."

Done Criteria

• Single project/ root, no siblings.
• 7 brain files created from blank templates if missing; existing user content preserved.
• 4 content directories with _template.md each.
• project/.agentic-seo/project.json records identity and market.
• Init log entry appended only when structural change occurred.
• pt-BR accents preserved in placeholders and log.
• Zero references to wiki/, judgment_level, pillar, status enums.
• Completion points to the initialized project in the Web Companion with browser_prompt.