Starter Harness Designer — Workspace v1

O que Starter Harness Designer — Workspace v1 faz?

"Um bom template vale mais que 100 páginas de guia."

Para quem é esta habilidade

• Pessoas criando um harness pela primeira vez
• Não desenvolvedores (planejadores, marketeiros, escritores, advogados, professores, operadores, etc.)
• Quem quer começar rapidamente com uma estrutura validada

Mantém a mesma filosofia de 3 fases (Planner → Generator → Evaluator) da versão para especialistas harness-designer-workspace, mas com complexidade de entrada e precisão de saída ajustadas para nível iniciante.

Fase	Versão para Especialistas	Starter (esta habilidade)
Planner	4 etapas de Discovery, perguntas abertas	3 perguntas de múltipla escolha → correspondência com número do exemplar
Generator	Plano → criação de arquivos/estrutura	Clonagem do exemplar + substituição
Evaluator	Verificação independente dos 8 pilares	Checklist leve — apenas substituições ausentes e referências quebradas

---

Relação com outras habilidades de harness

              │ Especialista (design livre)  │ Iniciante (clonagem de exemplar)
──────────────┼─────────────────────────────┼────────────────────────────
 Workspace    │ harness-designer-workspace  │ harness-starter-workspace ★ (esta)
──────────────┼─────────────────────────────┼────────────────────────────
 Codificação  │ harness-designer-coding     │ harness-starter-coding

Quando NÃO usar esta habilidade

• Desenvolvimento de apps, web services, APIs → use harness-starter-coding
• Usuários avançados que precisam de liberdade de design → use harness-designer-workspace
• Perguntas simples ou tarefas únicas → habilidade não necessária

---

Fluxo de execução (total 5 minutos)

1. [Planner] 3 perguntas de múltipla escolha
2. [Planner] Correspondência com número do exemplar + recomendação de preset
3. [Generator] Clonagem do exemplar do harness-100
4. [Generator] Substituição do nome do projeto e termos do domínio
5. [Evaluator] Checklist leve (5 segundos)
6. Instruções finais ("Agora use assim")

---

Fase 0: Correspondência de Padrão (Planner)

Pergunta 1 — O que você quer que seja feito? (1 frase em linguagem natural)

Peça ao usuário uma única frase. Exemplos:

• "Quero uma equipe que planeje, escreva roteiro e crie thumbnail para um vídeo do YouTube"
• "Uma equipe que, ao receber um contrato, extraia as cláusulas de risco"
• "Automação do envio de newsletter mensal"

Pergunta 2 — Qual categoria mais se aproxima? (múltipla escolha, 8 opções)

Consulte references/exemplar-index.md. Escolha uma das 8 abaixo:

Nº	Categoria	Exemplos
1	🎬 Criação de Conteúdo	YouTube, podcast, newsletter, quadrinhos, tradução
4	📊 Negócios e Estratégia	Startup, pesquisa de mercado, precificação, modelo financeiro
5	🎓 Educação e Aprendizado	Tutor de idiomas, preparação para exames, design de currículo
6	⚖️ Jurídico e Conformidade	Contratos, patentes, LGPD/privacidade de dados
7	🏃 Estilo de Vida	Dieta, fitness, contabilidade pessoal, viagem
8	📝 Comunicação e Documentos	Technical writing, SOP, propostas
9	🏢 Operações e Processos	Recrutamento, onboarding, auditoria, compras
10	🌐 Domínios Especializados	Imobiliário, ESG, portfólio de PI

Com base nas palavras-chave da Pergunta 1, sugira automaticamente de 1 a 3 opções e peça confirmação do usuário.

Tratamento de falha de correspondência (similaridade < 0.5):

• Apresente os 3 candidatos mais próximos e pergunte "Qual destes é o mais próximo?"
• Se nenhum, oriente a usar harness-designer-workspace (para especialistas)

Pergunta 3 — Qual é o nome do projeto?

Curto o suficiente para usar como nome de pasta/arquivo (ex.: producao-youtube, revisao-contrato, newsletter-mensal).

Pergunta 4 — Quer manter um histórico de mudanças? (opcional, sim/não)

"Quando você quiser melhorar esta equipe no futuro, quer um espaço para registrar o que mudou e por quê?"

• sim → Cria automático a wiki 05-flow-history/ + flow-change-protocol.md (build inicial registrado como change 0001)
• não → Não cria (pode adicionar manualmente depois)

Uso: retrospectiva de melhorias da equipe, verificação de motivos para rollback, referência ao criar equipes similares. Sem impacto no uso diário.

Princípio de gestão: Este histórico registra apenas mudanças no sistema de fluxo de trabalho (regras, procedimentos, ferramentas, CLAUDE.md). Os artefatos produzidos pelo sistema (resultados de pesquisa, relatórios, análises, registros de pauta) não são registrados. Critério de distinção: "Se esta mudança não tivesse ocorrido, o resultado da próxima execução seria diferente?" → Se sim = mudança de sistema = registrar / Se não = artefato = não registrar Detalhes em: 00-system/protocols/flow-change-protocol.md

Pergunta 3.5 (condicional — apenas para categorias de pesquisa)

Apenas para categorias 📊 Business & Strategy, 🎓 Education & Learning, 🌐 Specialized Domains. Pular para categorias de criação de conteúdo.

"Você precisará consultar pesquisas anteriores enquanto trabalha em várias pautas?"

• Sim → incluir wiki:
  • Verificar instalação da habilidade /graphify (automático: ~/.claude/skills/graphify/ ou .claude/skills/graphify/)
  • Se não instalada: explicar + opção de instalação (global/projeto/não instalar)
  • ⚠️ Se não instalar: "Funcionalidade wiki desativada. Você pode ativar depois instalando /graphify e executando /wiki-update"
• Não → não incluir wiki

---

Fase 1: Seleção de Preset (pesos de avaliação)

Após a correspondência, recomende e confirme um dos 3 presets:

Preset	Descrição	Critério de recomendação automática
[Equilibrado] (padrão)	Todos os critérios de qualidade com peso igual	Valor padrão
[Qualidade Primeiro]	Revisor, cenários de teste, seção NOT-trigger com peso 2x	Categorias jurídico, saúde, finanças, PI
[Velocidade Primeiro]	Scale Mode = Single, apenas checklist leve	Protótipo único, trabalho individual

O preset selecionado é registrado em _workspace/00_input.md.

---

Fase 2: Generator — Clonagem e Substituição do Exemplar

Etapas de clonagem (fallback automático)

Detecta automaticamente se gh está disponível para escolher a melhor forma de baixar o template. git sozinho também funciona.

EXEMPLAR="{NN}-{exemplar-name}"   # Resultado da correspondência do Planner (ex.: 01-youtube-production)
BASE="ko/$EXEMPLAR/.claude"

if command -v gh &>/dev/null && gh auth status &>/dev/null 2>&1; then
  # ── Modo A: GitHub CLI (gh) ──────────────────────────────
  echo "📡 Baixando via gh api..."
  FILES=$(gh api "repos/revfactory/harness-100/git/trees/main?recursive=1" \
    --jq ".tree[] | select(.path | startswith(\"$BASE/\")) | select(.type==\"blob\") | .path")
  mkdir -p .claude/agents .claude/skills
  while IFS= read -r filepath; do
    rel="${filepath#$BASE/}"
    dest=".claude/$rel"
    mkdir -p "$(dirname \"$dest\")"
    gh api "repos/revfactory/harness-100/contents/$filepath" \
      --jq '.content' | base64 -d > "$dest"
    echo "  ✅ $dest"
  done <<< "$FILES"
else
  # ── Modo B: git sparse checkout (sem gh) ─────────────────
  echo "📡 Baixando via git sparse checkout..."
  TMP=$(mktemp -d)
  git clone --depth 1 --filter=blob:none --sparse \
    https://github.com/revfactory/harness-100.git "$TMP"
  git -C "$TMP" sparse-checkout set "$BASE"
  mkdir -p .claude
  cp -r "$TMP/$BASE/." .claude/
  rm -rf "$TMP"
  echo "  ✅ sparse checkout concluído"
fi

Condição	Modo usado	Ferramenta necessária
gh instalado + logado	Modo A (gh api)	gh
Apenas git	Modo B (sparse checkout)	git
Nenhum disponível ou falha	Modo C (Claude gera diretamente após confirmação)	Nenhuma

Se os Modos A e B falharem, Claude orienta o usuário:

⚠️ Não foi possível obter o template do GitHub.

Motivo: gh e git indisponíveis ou sem conexão com internet.

Neste caso, Claude pode escrever os arquivos do harness diretamente, com base na descrição do exemplar. Porém, a qualidade pode ser diferente, pois não é o template validado real.

Deseja continuar?

• Sim → Claude cria os arquivos .claude/ diretamente (baseado no exemplar-index.md)
• Não → Interrompe aqui. Tente novamente com conexão à internet ou git instalado.

Se o usuário escolher Sim: Claude lê a descrição do exemplar em references/exemplar-index.md e escreve diretamente a estrutura CLAUDE.md, agents/, skills/. Se o usuário escolher Não: Interrompe imediatamente, informa como tentar novamente.

Após conclusão, estrutura:

.claude/
├── CLAUDE.md
├── agents/
│   ├── {especialista-1}.md
│   ├── {especialista-2}.md
│   ├── {especialista-3}.md
│   ├── {especialista-4}.md
│   └── {revisor}.md
└── skills/
    ├── {orquestrador}/skill.md
    └── {extensao-agente}/skill.md

3. Crie a pasta _workspace/ (para artefatos, convenção de numeração 00_input.md, 01_*.md, ...)

Regras de Substituição

Elemento original	Substituição	Exemplo
Nome do harness	Nome do projeto do usuário	01-youtube-production → meu-programa-youtube
Termos do domínio (global)	Termos do domínio do usuário	"Vídeo do YouTube" → "Episódio de podcast"
Palavras-chave de trigger	Palavras-chave do domínio do usuário	relacionado a YouTube → relacionado a podcast
Nomes dos papéis dos agentes	Substituir apenas se necessário	roteirista → manter recomendado
Frameworks de domínio	Nunca substituir	Porter's·IRAC·Bloom's são expertise central
_workspace/NN_*.md	Manter (convenção de numeração)	Nunca alterar os números

Estrutura de pastas adicional (v2):

• 50-reports/[nome-da-pauta]/v[N]/report.md — Relatórios isolados por pauta
• 60-exports/[nome-da-pauta]/ — Artefatos derivados (slides, compartilhamento externo, etc.)
• CARL frontmatter: incluir agenda:, type:, tags: YAML frontmatter nos templates de 70-playbook/
• (se wiki escolhido) 45-wiki/ — Repositório do grafo de conhecimento
• (se wiki escolhido) Habilidade research-wiki — Referência wiki com proteção de independência
• (se wiki escolhido) Comando /wiki-update — Criar e atualizar wiki
• (se resposta 4 sim) 05-flow-history/ + 00-system/protocols/flow-change-protocol.md — Wiki de histórico de mudanças do fluxo. Referenciar ~/.claude/skills/harness-designer-workspace/references/flow-history-template.md para criar 5+1 arquivos.

Lista de proibição de substituição automática:

• Nomes de frameworks embutidos (AIDA, IRAC, Bloom's, ADDIE, Porter's, DCF, Van Westendorp, SMART, etc.)
• Nome do diretório _workspace/ e números dos artefatos
• Termos de protocolo como SendMessage, TaskCreate
• Definições de Scale Modes
• Nome do diretório 45-wiki/
• Nome da habilidade research-wiki
• Texto das regras de referência wiki do protocolo de independência
• Correção automática por bkit: Proibido modificar por sugestão dos agentes bkit (code-analyzer, pm-lead, etc.) frameworks de domínio (AIDA·IRAC·Bloom's etc.), independence-protocol, protocolo SendMessage, numeração _workspace/
• Elementos de loop: Critérios de conclusão (condição de parada), ordem de revisão do Revisor (Revisor é o último), formato de julgamento do review_report — proibido substituir ou remover (loop exige Goal+Check+condição de parada para funcionar)

Termos em linguagem simples (para explicação ao usuário, estrutura interna mantida)

Os arquivos internos mantêm os termos originais. Use linguagem simples apenas ao explicar para o usuário:

Termo original	Linguagem simples
Orchestrator	Líder da equipe
Agent-Extending Skill	Livro de conhecimento especializado
Dependency DAG	Quadro de ordem das tarefas
Scale Modes	Modo de tamanho da equipe
Trigger Boundaries	Condições de acionamento
Cross-validation	Revisão cruzada

---

Fase 3: Evaluator — Checklist Leve

Em vez da verificação dos 8 pilares da versão para especialistas, verifica apenas a integridade das substituições.

Verificação automática (5 segundos)

• .claude/CLAUDE.md existe
• agents/ contém de 4 a 5 arquivos .md (incluindo Revisor)
• skills/<orquestrador>/skill.md existe
• skills/ contém pelo menos 1 habilidade de extensão de agente
• Pasta _workspace/ criada
• Nome original do harness (ex.: 01-youtube-production) não permanece em nenhum arquivo (grep = 0 ocorrências)
• Nomes de frameworks embutidos preservados (IRAC/Bloom's etc. com valores originais)
• Seção should-NOT dos Trigger Boundaries existe
• Tabela de Scale Modes existe (Full / Reduced / Single)
• Seção de 3 cenários de teste existe (Normal / Existing / Error)
• 50-reports/ contém estrutura de pastas por pauta
• Pasta 60-exports/ existe (separação de artefatos derivados)
• 70-playbook/ templates CARL incluem frontmatter
• Comando /synthesize inclui gate obrigatório de tarefas pendentes
• orchestrator skill.md contém critérios de conclusão verificáveis (condição de parada)
• Artefato do Revisor (review_report) possui formato que inclui julgamento: aprovado/precisa de modificação
• (se wiki escolhido) Pasta 45-wiki/ existe
• (se wiki escolhido) Habilidade research-wiki existe
• (se wiki escolhido) Protocolo de independência contém regras de referência à wiki

Em caso de falha

• Substituição ausente encontrada → Refaça a pergunta ao Planner ("Por qual termo devo substituir?")
• Deficiência estrutural → Reclone o exemplar e substitua novamente
• 3 falhas → Oriente a usar harness-designer-workspace

---

Fase 4: Instruções Finais (relatório em linguagem simples para não desenvolvedores)

✅ Harness pronto!

📁 Localização: /seu-projeto/.claude/
👥 Equipe (5 membros):
   - Estrategista: descoberta de tópicos, análise de concorrência
   - Roteirista: escrita do roteiro real
   - Designer de thumbnail: planejamento de imagem
   - Responsável por SEO: otimização para busca
   - Revisor: verificação de qualidade geral

🚀 Como usar:
   1. No Claude Code, digite "/meu-programa-youtube planeje o próximo vídeo"
   2. A equipe trabalha em sequência, salvando artefatos na pasta _workspace/
   3. Os resultados seguem a ordem 00_input.md ~ 05_review_report.md

🔄 Como a equipe trabalha (loop):
   A equipe trabalha em um loop de "Objetivo(Goal) → Trabalho → Revisão(Check) → Concluído se aprovado".
   O relatório do revisor final (0X_review_report.md) é o resultado da verificação.
   Se não gostar do resultado, peça novamente com mais detalhes —
   esse julgamento final é seu papel (loop externo).

📘 Próximos passos:
   - Se algo não agradar, edite .claude/agents/{papel}.md
   - Se quiser algo mais complexo, use a habilidade harness-designer-workspace

---

Materiais de referência

• exemplar-index.md — Índice de 73 exemplares de workspace
• Original: https://github.com/revfactory/harness-100 (Apache-2.0)
• Variação para especialistas: harness-designer-workspace
• Variação para codificação: harness-starter-coding