diff --git a/README.md b/README.md index 8bc8967..97a00a5 100644 --- a/README.md +++ b/README.md @@ -41,6 +41,7 @@ npm run verify - `hands-on/starter/` — dependency-free Tiny Tasks exercise - `hands-on/rules/` — dependency-free Guardrails lab; toggles rule sources into the prompt - `rules/` — bilingual case study of skills, CLI ratchets, Husky, and PR review +- `skills/` — reusable design and rules-case-study skills extracted from this implementation - `GATES.md` — acceptance ledger for the project ## Publishing @@ -74,3 +75,8 @@ skills, machine-readable repo ledgers, a UI contract ratchet, lint-staged, Husky, commitlint, specialist verifier agents, and PR review reinforce one another. Every example links to its source file in Gitea, and the page includes a copy-ready prompt for mapping the same layers in another repository. + +The implementation patterns are also packaged as project-local skills in +[skills/](skills/README.md). Use `editorial-playbook` when adding chapters or +sections, and `rules-case-study` when turning repository controls into a +source-linked teaching page. diff --git a/rules/app.js b/rules/app.js new file mode 100644 index 0000000..3a01f39 --- /dev/null +++ b/rules/app.js @@ -0,0 +1,92 @@ +const languageCopy = { + en: { + back: 'field guide', navPipeline: 'Pipeline', navExamples: 'Examples', stageContext: 'CONTEXT', stageReview: 'REVIEW', heroEyebrow: 'A real repository case study', heroTitle: 'Rules that
survive the prompt.', + heroText: 'Prompts ask for behavior. Repositories preserve it. The interview project combines written context, reusable skills, executable checks, commit hooks, and independent review so the rule is still present when the conversation is gone.', + heroAside: '8 skills · 3 agents · 4 enforcement layers', thesisLabel: 'THE SHORT VERSION', thesis: 'A prompt is advice for one run. A repository rule is reusable context plus an executable boundary.', + pipelineLabel: 'Enforcement pipeline', pipelineMeta: 'select a checkpoint', pipelineEyebrow: 'From intent to evidence', pipelineTitle: 'Five places
a rule can hold.', pipelineText: 'Not every rule belongs in a hook. Put guidance where an agent can discover it, deterministic policy in a command, cheap checks at commit time, and independent judgment at review.', + skillsLabel: 'Project-local skills', skillsMeta: 'procedures born from repeated friction', skillsEyebrow: 'Small instruction packages', skillsTitle: 'Teach the trap.
Name the trigger.', skillsText: 'These skills are not downloaded magic. They are repository-specific procedures under .agents/skills/, distilled from mistakes, commands, and architectural decisions that kept recurring.', skillGate: 'prove green is real', skillParallel: 'worktree per task', skillRepo: 'query before crawling', skillDebt: 'separate line of work', skillWriter: 'repeat twice, encode once', skillArea: 'stack-specific traps', + examplesLabel: 'Concrete examples', examplesMeta: 'open the source, then adapt', ratchetLabel: 'CLI RATCHET', ratchetTitle: 'Debt may go down.
Never silently up.', hookTitle: 'Fast checks before history.', commitLabel: 'COMMIT MESSAGE', commitTitle: 'Intent has a grammar.', reviewLabel: 'INDEPENDENT REVIEW', reviewTitle: 'A second reader checks intent.', readChecker: 'Read the checker →', readHook: 'Read the hook →', readCommit: 'Read commitlint config →', readReview: 'Read review policy →', + copyLabel: 'COPY / ADAPT', copyTitle: 'Ask your agent to map the enforcement stack.', copyText: 'Use this in the interview repository or adapt the path names to another project.', copyButton: 'COPY PROMPT', deeperLabel: 'GO DEEPER', deeperTitle: 'Read the implementation, not just this summary.', deepContext: 'Repository context', deepSkills: 'Skill catalog', deepAgents: 'Specialist agents', deepPolicy: 'Staged-file policy' + }, + pt: { + back: 'guia de campo', navPipeline: 'Pipeline', navExamples: 'Exemplos', stageContext: 'CONTEXTO', stageReview: 'REVISÃO', heroEyebrow: 'Um estudo de caso de repositório real', heroTitle: 'Regras que
sobrevivem ao prompt.', + heroText: 'Prompts pedem comportamento. Repositórios o preservam. O projeto interview combina contexto escrito, skills reutilizáveis, verificações executáveis, hooks de commit e revisão independente para que a regra continue existindo quando a conversa terminar.', + heroAside: '8 skills · 3 agentes · 4 camadas de enforcement', thesisLabel: 'A VERSÃO CURTA', thesis: 'Um prompt orienta uma execução. Uma regra de repositório é contexto reutilizável mais uma fronteira executável.', + pipelineLabel: 'Pipeline de enforcement', pipelineMeta: 'selecione um checkpoint', pipelineEyebrow: 'Da intenção à evidência', pipelineTitle: 'Cinco lugares
onde a regra segura.', pipelineText: 'Nem toda regra pertence a um hook. Coloque orientação onde o agente descobre, política determinística em um comando, checks baratos no commit e julgamento independente na revisão.', + skillsLabel: 'Skills locais do projeto', skillsMeta: 'procedimentos nascidos de atrito repetido', skillsEyebrow: 'Pequenos pacotes de instrução', skillsTitle: 'Ensine a armadilha.
Nomeie o gatilho.', skillsText: 'Estas skills não são mágica baixada. São procedimentos específicos do repositório em .agents/skills/, extraídos de erros, comandos e decisões arquiteturais recorrentes.', skillGate: 'prove que o verde é real', skillParallel: 'um worktree por tarefa', skillRepo: 'consulte antes de explorar', skillDebt: 'linha de trabalho separada', skillWriter: 'repita duas vezes, codifique uma', skillArea: 'armadilhas da stack', + examplesLabel: 'Exemplos concretos', examplesMeta: 'abra a fonte, depois adapte', ratchetLabel: 'CATRACA CLI', ratchetTitle: 'A dívida pode cair.
Nunca subir em silêncio.', hookTitle: 'Checks rápidos antes do histórico.', commitLabel: 'MENSAGEM DE COMMIT', commitTitle: 'A intenção tem gramática.', reviewLabel: 'REVISÃO INDEPENDENTE', reviewTitle: 'Um segundo leitor verifica a intenção.', readChecker: 'Ler o checker →', readHook: 'Ler o hook →', readCommit: 'Ler config do commitlint →', readReview: 'Ler política de revisão →', + copyLabel: 'COPIAR / ADAPTAR', copyTitle: 'Peça ao agente para mapear o enforcement.', copyText: 'Use isto no repositório interview ou adapte os caminhos para outro projeto.', copyButton: 'COPIAR PROMPT', deeperLabel: 'APROFUNDE', deeperTitle: 'Leia a implementação, não apenas este resumo.', deepContext: 'Contexto do repositório', deepSkills: 'Catálogo de skills', deepAgents: 'Agentes especialistas', deepPolicy: 'Política dos arquivos staged' + } +}; + +const stages = { + context: { number: '01', file: 'AGENTS.md', title: { en: 'Give every agent the same map', pt: 'Dê o mesmo mapa a cada agente' }, text: { en: 'Stack, commands, product boundaries, and known traps load before implementation. This is discoverable guidance—not an executable guarantee.', pt: 'Stack, comandos, limites do produto e armadilhas conhecidas carregam antes da implementação. É orientação descobrível — não garantia executável.' }, code: 'Read AGENTS.md\n→ query .agents/db\n→ load area skill', link: 'https://git.marcospaulo.dev.br/netcracker/interview/src/branch/main/AGENTS.md' }, + skills: { number: '02', file: '.agents/skills/', title: { en: 'Load only the relevant procedure', pt: 'Carregue apenas o procedimento relevante' }, text: { en: 'Frontend, Go API, gate discipline, parallel agents, repo databases, issues, skill writing, and tech debt each have a narrow trigger.', pt: 'Frontend, API Go, disciplina de gates, agentes paralelos, bancos do repo, issues, escrita de skills e dívida técnica têm gatilhos estreitos.' }, code: 'request + description\n→ matching SKILL.md\n→ focused workflow', link: 'https://git.marcospaulo.dev.br/netcracker/interview/src/branch/main/.agents/skills' }, + cli: { number: '03', file: 'scripts/check-ui-contract.mjs', title: { en: 'Turn measurable policy into a ratchet', pt: 'Transforme política mensurável em catraca' }, text: { en: 'The UI checker counts known violations and fails only when a count rises. Existing debt can be reduced, but a new change cannot quietly increase it.', pt: 'O checker de UI conta violações conhecidas e falha quando o total sobe. Dívida existente pode cair, mas uma mudança não pode aumentá-la em silêncio.' }, code: 'pnpm check:ui\ncurrent ≤ baseline → pass\ncurrent > baseline → fail', link: 'https://git.marcospaulo.dev.br/netcracker/interview/src/branch/main/scripts/check-ui-contract.mjs' }, + commit: { number: '04', file: '.husky/pre-commit', title: { en: 'Block cheap mistakes at the boundary', pt: 'Bloqueie erros baratos na fronteira' }, text: { en: 'Husky runs lint-staged plus the whole-tree UI ratchet. Commitlint separately enforces Conventional Commit messages.', pt: 'Husky executa lint-staged mais a catraca de UI da árvore inteira. Commitlint aplica Conventional Commits separadamente.' }, code: 'git commit\n├─ lint-staged\n├─ check:ui\n└─ commitlint', link: 'https://git.marcospaulo.dev.br/netcracker/interview/src/branch/main/.husky/pre-commit' }, + review: { number: '05', file: '.pr-review.json', title: { en: 'Reserve judgment for the PR', pt: 'Reserve julgamento para o PR' }, text: { en: 'An AI reviewer checks security, generated-code discipline, test quality, scope, and repository-specific traps. A verifier independently reruns gates before merge.', pt: 'Um revisor de IA verifica segurança, código gerado, qualidade dos testes, escopo e armadilhas do repositório. Um verifier roda os gates novamente antes do merge.' }, code: 'diff + house rules + prior review\n→ findings + risks\n→ human merge decision', link: 'https://git.marcospaulo.dev.br/netcracker/interview/src/branch/main/.pr-review.json' } +}; + +const skills = { + gate: { name: 'gate-discipline', trigger: { en: 'Before commit, PR, or merge.', pt: 'Antes de commit, PR ou merge.' }, lesson: { en: 'Run canonical gates separately, inspect exit codes, distrust convenient cache hits, and prove generated code is current.', pt: 'Rode gates separadamente, leia exit codes, desconfie de cache conveniente e prove que código gerado está atual.' }, example: 'pnpm lint; echo "lint=$?"', path: '.agents/skills/gate-discipline/SKILL.md' }, + parallel: { name: 'parallel-agents', trigger: { en: 'When independent tasks can run concurrently.', pt: 'Quando tarefas independentes podem rodar juntas.' }, lesson: { en: 'One worktree and file ownership per task; prior-art scout first, verifier last, merge sequentially.', pt: 'Um worktree e ownership por tarefa; prior-art scout primeiro, verifier por último, merges sequenciais.' }, example: 'git worktree add .claude/worktrees/task -b feat/task', path: '.agents/skills/parallel-agents/SKILL.md' }, + repo: { name: 'repo-db', trigger: { en: 'At task start and before debugging.', pt: 'No início da tarefa e antes de diagnosticar.' }, lesson: { en: 'Query the repo map, canonical commands, and known-issues ledger before crawling thousands of files.', pt: 'Consulte mapa, comandos canônicos e known-issues antes de vasculhar milhares de arquivos.' }, example: "jq -r '.verify[]' .agents/db/commands.json", path: '.agents/skills/repo-db/SKILL.md' }, + debt: { name: 'tech-debt', trigger: { en: 'When unrelated debt appears mid-task.', pt: 'Quando dívida não relacionada aparece no meio.' }, lesson: { en: 'Do not smuggle cleanup into a feature. Record it, give it its own branch, and finish the underlying condition.', pt: 'Não esconda limpeza em uma feature. Registre, dê uma branch própria e finalize a condição original.' }, example: 'feature diff ≠ debt cleanup', path: '.agents/skills/tech-debt/SKILL.md' }, + writer: { name: 'skill-writer', trigger: { en: 'When a workflow is explained twice.', pt: 'Quando um fluxo é explicado duas vezes.' }, lesson: { en: 'Procedures become skills; isolated facts become known-issues entries. Keep the body short and the trigger discriminating.', pt: 'Procedimentos viram skills; fatos isolados viram known-issues. Corpo curto e gatilho discriminante.' }, example: '.agents/skills//SKILL.md', path: '.agents/skills/skill-writer/SKILL.md' }, + area: { name: 'frontend / go-api', trigger: { en: 'When changing the matching subsystem.', pt: 'Ao alterar o subsistema correspondente.' }, lesson: { en: 'Encode version-specific traps close to the work: Next/React/AntD boundaries, Connect APIs, sqlc types, migrations, and code generation.', pt: 'Codifique armadilhas de versão perto do trabalho: Next/React/AntD, APIs Connect, tipos sqlc, migrations e codegen.' }, example: 'area → local skill → canonical checks', path: '.agents/skills/' } +}; + +const prompts = { + en: `Inspect this repository's enforcement stack before changing code.\n\n1. Read AGENTS.md.\n2. List .agents/skills and select only skills whose descriptions match the task.\n3. Query .agents/db/commands.json and .agents/db/known-issues.json.\n4. Explain what is guidance versus mechanically enforced by scripts, Husky, commitlint, CI, and PR review.\n5. For each relevant rule, cite the source path and the command that proves it.\n6. Identify gaps where documentation claims enforcement but no executable check exists.\n\nDo not modify files. Return a compact map: rule → source → enforcement point → verification command → remaining gap.`, + pt: `Inspecione a stack de enforcement deste repositório antes de alterar código.\n\n1. Leia AGENTS.md.\n2. Liste .agents/skills e selecione apenas skills cuja descrição corresponda à tarefa.\n3. Consulte .agents/db/commands.json e .agents/db/known-issues.json.\n4. Explique o que é orientação e o que é imposto mecanicamente por scripts, Husky, commitlint, CI e revisão de PR.\n5. Para cada regra relevante, cite o caminho fonte e o comando que a comprova.\n6. Identifique lacunas onde a documentação promete enforcement sem check executável.\n\nNão modifique arquivos. Retorne um mapa compacto: regra → fonte → ponto de enforcement → comando de verificação → lacuna restante.` +}; + +let language = localStorage.getItem('rules-language') === 'pt' ? 'pt' : 'en'; + +function select(selector, value, key) { + document.querySelectorAll(selector).forEach((button) => { + const active = button.dataset[key] === value; + button.classList.toggle('active', active); + button.setAttribute('aria-selected', String(active)); + }); +} + +function renderStage(id) { + const item = stages[id]; + document.querySelector('#stage-detail').innerHTML = `
${item.number}
${item.file}

${item.title[language]}

${item.text[language]}

${language === 'pt' ? 'ABRIR FONTE ↗' : 'OPEN SOURCE ↗'}
${item.code}
`; + select('[data-stage]', id, 'stage'); +} + +function renderSkill(id) { + const item = skills[id]; + document.querySelector('#skill-detail').innerHTML = `
${language === 'pt' ? 'GATILHO' : 'TRIGGER'}${item.trigger[language]}

${item.name}

${item.lesson[language]}

${item.example}
${language === 'pt' ? 'LER SKILL ↗' : 'READ SKILL ↗'}`; + select('[data-skill]', id, 'skill'); +} + +function renderLanguage(next) { + language = next; + document.documentElement.lang = language === 'pt' ? 'pt-BR' : 'en'; + document.querySelectorAll('[data-copy]').forEach((node) => { node.innerHTML = languageCopy[language][node.dataset.copy]; }); + document.querySelector('#explore-prompt').textContent = prompts[language]; + document.querySelectorAll('[data-lang]').forEach((button) => { const active = button.dataset.lang === language; button.classList.toggle('active', active); button.setAttribute('aria-pressed', String(active)); }); + renderStage(document.querySelector('[data-stage].active')?.dataset.stage || 'context'); + renderSkill(document.querySelector('[data-skill].active')?.dataset.skill || 'gate'); + localStorage.setItem('rules-language', language); +} + +async function copyPrompt() { + const value = prompts[language]; + try { + await navigator.clipboard.writeText(value); + document.querySelector('#copy-status').textContent = language === 'pt' ? 'Prompt copiado.' : 'Prompt copied.'; + } catch { + document.querySelector('#copy-status').textContent = language === 'pt' ? 'Selecione o texto manualmente.' : 'Select the text manually.'; + } +} + +document.querySelectorAll('[data-stage]').forEach((button) => button.addEventListener('click', () => renderStage(button.dataset.stage))); +document.querySelectorAll('[data-skill]').forEach((button) => button.addEventListener('click', () => renderSkill(button.dataset.skill))); +document.querySelectorAll('[data-lang]').forEach((button) => button.addEventListener('click', () => renderLanguage(button.dataset.lang))); +document.querySelector('[data-copy-prompt]').addEventListener('click', copyPrompt); +window.addEventListener('scroll', () => { const height = document.documentElement.scrollHeight - innerHeight; document.querySelector('.progress span').style.width = `${height > 0 ? scrollY / height * 100 : 0}%`; }, { passive: true }); +renderLanguage(language); diff --git a/rules/index.html b/rules/index.html new file mode 100644 index 0000000..4249452 --- /dev/null +++ b/rules/index.html @@ -0,0 +1,102 @@ + + + + + + + Rules That Survive the Prompt — AI For Dummies + + + + +
+ Afield guide + +
/
+
+ +
+
+

A real repository case study

+

Rules that
survive the prompt.

+
+

Prompts ask for behavior. Repositories preserve it. The interview project combines written context, reusable skills, executable checks, commit hooks, and independent review so the rule is still present when the conversation is gone.

+ +
+
+ +
+ THE SHORT VERSION + A prompt is advice for one run. A repository rule is reusable context plus an executable boundary. +
+ +
+
Enforcement pipelineselect a checkpoint
+

From intent to evidence

Five places
a rule can hold.

Not every rule belongs in a hook. Put guidance where an agent can discover it, deterministic policy in a command, cheap checks at commit time, and independent judgment at review.

+
+ + → + → + → + → +
+
+
+ +
+
Project-local skillsprocedures born from repeated friction
+

Small instruction packages

Teach the trap.
Name the trigger.

These skills are not downloaded magic. They are repository-specific procedures under .agents/skills/, distilled from mistakes, commands, and architectural decisions that kept recurring.

+
+
+ + + + + + +
+
+
+
+ +
+
Concrete examplesopen the source, then adapt
+
+
CLI RATCHET

Debt may go down.
Never silently up.

pnpm check:ui
+# raw buttons
+# swallowed catches
+# pages without h1
+# hardcoded colours
Read the checker →
+
HUSKY / PRE-COMMIT

Fast checks before history.

pnpm exec lint-staged
+node scripts/check-ui-contract.mjs
Read the hook →
+
COMMIT MESSAGE

Intent has a grammar.

pnpm exec commitlint --edit $1
+
+feat: add interview timer
+fix(api): scope session query
Read commitlint config →
+
INDEPENDENT REVIEW

A second reader checks intent.

.pr-review.json
+├── focus
+├── exclude_paths
+├── languages
+└── instructions
Read review policy →
+
+
+ +
+
COPY / ADAPT

Ask your agent to map the enforcement stack.

Use this in the interview repository or adapt the path names to another project.

+

+
+ +
+
GO DEEPERRead the implementation, not just this summary.
+ +
+
+ + + diff --git a/rules/styles.css b/rules/styles.css new file mode 100644 index 0000000..b09aaa4 --- /dev/null +++ b/rules/styles.css @@ -0,0 +1,6 @@ +:root{--paper:#f5f4f1;--ink:#172f42;--muted:#697b89;--accent:#7c78a8;--blue:#527f9f;--gold:#efc76b;--line:#d8dee2;--deep:#102536}*{box-sizing:border-box}html{scroll-behavior:smooth}body{min-width:320px;margin:0;color:var(--ink);background:var(--paper);font-family:Manrope,Arial,sans-serif}.progress{position:fixed;z-index:20;top:0;left:0;width:100%;height:3px;background:transparent}.progress span{display:block;width:0;height:100%;background:var(--gold)}.topbar{position:sticky;z-index:10;top:0;display:grid;grid-template-columns:1fr auto 1fr;align-items:center;min-height:72px;padding:0 clamp(24px,5vw,90px);border-bottom:1px solid var(--line);background:color-mix(in srgb,var(--paper) 94%,transparent);backdrop-filter:blur(14px)}.back{display:flex;align-items:center;gap:11px;color:var(--ink);font:700 10px 'DM Mono',monospace;text-decoration:none;text-transform:uppercase}.back b{display:grid;place-items:center;width:30px;height:30px;color:var(--paper);background:var(--accent);font-size:15px}.topbar nav{display:flex;gap:28px}.topbar nav a,.languages{color:var(--muted);font:600 9px 'DM Mono',monospace;letter-spacing:.08em;text-decoration:none;text-transform:uppercase}.languages{justify-self:end;display:flex;align-items:center;gap:7px}.languages button{padding:7px;border:0;color:var(--muted);background:transparent;cursor:pointer}.languages button.active{color:var(--paper);background:var(--blue)}main{max-width:1920px;margin:auto;padding:0 clamp(24px,5vw,90px)}.hero{min-height:700px;padding:130px 0 80px}.eyebrow,.section-label,.thesis>span{color:var(--accent);font:600 9px 'DM Mono',monospace;letter-spacing:.1em;text-transform:uppercase}.hero h1,.intro h2{margin:22px 0 50px;font-size:clamp(64px,8.3vw,148px);line-height:.82;letter-spacing:-.075em}.hero h1 em,.intro h2 em{color:var(--blue);font-family:Georgia,serif;font-weight:400}.hero-foot{display:grid;grid-template-columns:1.3fr .7fr;gap:70px;align-items:end}.hero-foot>p{max-width:750px;margin:0;color:var(--muted);font-size:16px;line-height:1.75}.hero-foot aside{display:grid;gap:8px;padding:23px;border-left:6px solid var(--gold);color:var(--paper);background:var(--deep)}.hero-foot aside span,.hero-foot aside small{color:var(--gold);font:500 8px 'DM Mono',monospace;letter-spacing:.08em}.hero-foot aside strong{font-size:32px}.thesis{display:grid;grid-template-columns:200px 1fr;gap:35px;align-items:center;margin:0 calc(clamp(24px,5vw,90px) * -1) 130px;padding:35px clamp(24px,5vw,90px);color:var(--paper);background:var(--ink)}.thesis strong{font-size:clamp(20px,2.4vw,38px);line-height:1.2}.section-label{display:flex;justify-content:space-between;padding-bottom:15px;border-bottom:1px solid var(--line)}.section-label span:last-child{color:var(--muted)}.pipeline-section,.skill-section,.examples,.copy-lab{margin-bottom:140px;padding-top:30px}.intro{display:grid;grid-template-columns:.9fr 1.1fr;gap:70px;align-items:end;margin:45px 0}.intro h2{margin:15px 0 0;font-size:clamp(48px,5.6vw,92px)}.intro>p{max-width:650px;margin:0;color:var(--muted);font-size:14px;line-height:1.75}.pipeline{display:grid;grid-template-columns:1fr auto 1fr auto 1fr auto 1fr auto 1fr;align-items:stretch;border:1px solid var(--line);background:var(--paper)}.pipeline button{display:grid;gap:8px;min-height:126px;padding:20px;border:0;color:var(--ink);background:transparent;text-align:left;cursor:pointer}.pipeline button span{color:var(--accent);font:600 9px 'DM Mono',monospace}.pipeline button strong{font:700 13px 'DM Mono',monospace}.pipeline button small{color:var(--muted);font:10px 'DM Mono',monospace}.pipeline button.active{color:var(--paper);background:var(--blue);box-shadow:inset 0 -6px var(--gold)}.pipeline button.active span,.pipeline button.active small{color:var(--gold)}.pipeline>i{align-self:center;color:var(--gold);font-style:normal}.stage-detail{display:grid;grid-template-columns:120px 1.3fr .7fr;gap:35px;min-height:330px;padding:42px;color:var(--paper);background:var(--deep)}.stage-number{color:#ffffff24;font:500 76px 'DM Mono',monospace}.stage-detail>div:nth-child(2)>span,.skill-detail header span{color:var(--gold);font:500 9px 'DM Mono',monospace;letter-spacing:.08em}.stage-detail h3,.skill-detail h3{margin:15px 0;font-size:clamp(28px,3vw,48px);letter-spacing:-.05em}.stage-detail p,.skill-detail p{max-width:650px;color:#b8c8d2;font-size:13px;line-height:1.7}.stage-detail a,.skill-detail a,.example-grid a{display:inline-block;margin-top:15px;color:var(--gold);font:600 9px 'DM Mono',monospace;letter-spacing:.07em}.stage-detail pre,.skill-detail pre,.example-grid pre,.copy-lab pre{margin:0;overflow:auto;background:#081621}.stage-detail pre{align-self:stretch;padding:28px}.stage-detail code,.skill-detail code,.example-grid code,.copy-lab code{color:#c9d5dc;font:11px/1.7 'DM Mono',monospace}.skill-console{display:grid;grid-template-columns:minmax(240px,.7fr) minmax(0,1.5fr);min-height:570px;border:1px solid var(--line);background:var(--line);gap:1px}.skill-list{display:grid;grid-template-rows:repeat(6,1fr);gap:1px;background:var(--line)}.skill-list button{display:grid;align-content:center;gap:7px;padding:18px 22px;border:0;color:var(--ink);background:var(--paper);text-align:left;cursor:pointer}.skill-list button strong{font:700 12px 'DM Mono',monospace}.skill-list button small{color:var(--muted);font-size:10px}.skill-list button.active{color:var(--paper);background:var(--accent);box-shadow:inset 6px 0 var(--gold)}.skill-list button.active small{color:#f0eef8}.skill-detail{display:grid;align-content:center;padding:50px clamp(30px,5vw,80px);color:var(--paper);background:#5b7098}.skill-detail header{display:grid;gap:9px;padding-bottom:22px;border-bottom:1px solid #ffffff3a}.skill-detail header strong{font-size:12px}.skill-detail pre{margin:20px 0 0;padding:18px}.example-grid{display:grid;grid-template-columns:1fr 1fr;gap:1px;margin-top:45px;background:var(--line)}.example-grid article{display:grid;grid-template-rows:auto auto 1fr auto;min-height:390px;padding:35px;background:var(--paper)}.example-grid article>span{color:var(--accent);font:600 9px 'DM Mono',monospace;letter-spacing:.08em}.example-grid h3{margin:22px 0;font-size:clamp(26px,3vw,42px);line-height:1.05;letter-spacing:-.045em}.example-grid pre{padding:22px}.example-grid a{color:var(--blue)}.copy-lab{display:grid;grid-template-columns:.75fr 1.25fr;gap:1px;color:var(--paper);background:var(--line)}.copy-lab>div{padding:45px;background:var(--accent)}.copy-lab>div span{color:var(--gold);font:600 9px 'DM Mono',monospace}.copy-lab h2{margin:20px 0;font-size:clamp(30px,3.4vw,56px);line-height:1}.copy-lab>div p{max-width:420px;color:#eceaf5;line-height:1.6}.copy-lab article{display:grid;grid-template-rows:auto 1fr auto;min-width:0;background:var(--deep)}.copy-lab button{justify-self:end;display:flex;gap:20px;margin:20px;padding:11px 14px;border:1px solid #ffffff50;color:var(--paper);background:transparent;font:600 9px 'DM Mono',monospace;cursor:pointer}.copy-lab pre{padding:26px;white-space:pre-wrap}.copy-lab article>p{min-height:20px;margin:12px 24px;color:var(--gold);font:600 9px 'DM Mono',monospace}.deeper{margin:0 calc(clamp(24px,5vw,90px) * -1);padding:60px clamp(24px,5vw,90px) 100px;background:var(--gold)}.deeper>div{display:flex;justify-content:space-between;gap:30px;margin-bottom:35px}.deeper>div span{color:var(--accent);font:600 9px 'DM Mono',monospace}.deeper>div strong{max-width:700px;font-size:clamp(24px,3vw,44px);line-height:1.1}.deeper nav{display:grid;grid-template-columns:repeat(4,1fr);gap:1px;background:#132b3b}.deeper nav a{display:grid;gap:9px;min-height:160px;padding:25px;color:var(--paper);background:var(--ink);text-decoration:none}.deeper nav span{color:var(--accent);font:600 10px 'DM Mono',monospace}.deeper nav b{font-size:15px}.deeper nav small{color:#9eb0bb;font:9px 'DM Mono',monospace}.topbar a:focus-visible,.topbar button:focus-visible,.pipeline button:focus-visible,.skill-list button:focus-visible,.copy-lab button:focus-visible,.deeper a:focus-visible{outline:3px solid var(--gold);outline-offset:-3px} + +@media(min-width:2200px){main{max-width:2880px;padding-inline:clamp(150px,7vw,300px)}.hero{min-height:900px}.hero h1{font-size:clamp(150px,7vw,220px)}.pipeline button{min-height:170px}.stage-detail{min-height:440px}.skill-console{min-height:720px}} +@media(max-width:900px){.topbar{grid-template-columns:1fr auto}.topbar nav{display:none}.hero{min-height:auto}.hero-foot,.intro,.copy-lab{grid-template-columns:1fr}.pipeline{grid-template-columns:1fr 1fr 1fr}.pipeline>i{display:none}.pipeline button{min-height:100px}.stage-detail{grid-template-columns:80px 1fr}.stage-detail pre{grid-column:1/-1}.skill-console{grid-template-columns:1fr}.skill-list{grid-template-columns:1fr 1fr;grid-template-rows:none}.example-grid{grid-template-columns:1fr}.deeper nav{grid-template-columns:1fr 1fr}} +@media(max-width:600px){main{padding-inline:18px}.topbar{padding-inline:18px}.hero{padding-top:80px}.hero h1{font-size:clamp(54px,17vw,78px)}.hero-foot{gap:30px}.thesis{grid-template-columns:1fr;margin-inline:-18px;padding-inline:18px}.section-label{gap:20px}.section-label span:last-child{text-align:right}.pipeline{grid-template-columns:1fr}.pipeline button{grid-template-columns:38px 1fr;grid-template-rows:auto auto;min-height:82px}.pipeline button span{grid-row:1/-1;align-self:center}.stage-detail{grid-template-columns:1fr;padding:28px 22px}.stage-number{font-size:48px}.stage-detail pre{grid-column:auto}.skill-list{grid-template-columns:1fr}.skill-detail{padding:34px 24px}.example-grid article{min-height:340px;padding:25px}.copy-lab>div{padding:30px 24px}.deeper{margin-inline:-18px;padding-inline:18px}.deeper>div{display:grid}.deeper nav{grid-template-columns:1fr}.deeper nav a{min-height:120px}} +@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}.progress span{transition:none}} diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..927dabc --- /dev/null +++ b/skills/README.md @@ -0,0 +1,10 @@ +# Reusable skills + +These project-local skills extract the design and implementation patterns used by AI For Dummies. They are intentionally small: copy a skill into an agent's skill directory, or give the `SKILL.md` path to an agent when building a new chapter. + +## Skills + +- [`editorial-playbook`](editorial-playbook/SKILL.md) — shape a content-led, responsive, bilingual explainer with small interactive islands. +- [`rules-case-study`](rules-case-study/SKILL.md) — turn repository rules, skills, CLI checks, hooks, and review policy into a source-linked teaching page. + +The reference files are deliberately disclosed beside each skill. The `evals/evals.json` files contain small prompts for checking that an agent reaches the right workflow. diff --git a/skills/editorial-playbook/SKILL.md b/skills/editorial-playbook/SKILL.md new file mode 100644 index 0000000..1ad7216 --- /dev/null +++ b/skills/editorial-playbook/SKILL.md @@ -0,0 +1,19 @@ +--- +name: editorial-playbook +description: Use when building or reshaping a content-led interactive explainer, technical playbook, or presentation-like static page; define the information architecture, visual system, responsive behavior, bilingual copy, and minimal interactive islands before coding. +--- + +# Editorial playbook + +Treat the page as a guided argument, not a dashboard. Give it one audience, one job, and one memorable thesis. + +## Workflow + +1. Write the chapter map before markup. Every section gets a stable slug, number, title, purpose, and a single interaction or proof point when useful. Reach for [page anatomy](references/page-anatomy.md) when adding a new section. +2. Compose from a few editorial primitives: label, thesis, pipeline or diagram, comparison/table, code panel, callout, source card, and next-chapter link. Keep the content model separate from rendering so more sections stay cheap. +3. Use a restrained visual system: paper background, ink text, muted copy, one cool accent, one warm signal, hairlines, and typography with a strong display/body contrast. Prefer intentional asymmetry and generous rhythm over cards everywhere. +4. Keep runtime light. Use plain HTML/CSS/JS for static, mostly content-led pages. Choose Astro or MDX only when many chapters need shared templates, content collections, or build-time localization. Preserve an existing framework when it already owns routing and tokens. +5. Make the page bilingual at the content boundary. Pair English and Portuguese strings, toggle the document language, persist the choice, and translate labels, controls, status text, and dynamic details—not paths, commands, or code. +6. Make interactions causal and inspectable. One active state should explain one idea; expose it with keyboard focus, an accessible state, a live status region, copy feedback, and a reduced-motion path. +7. Design for mobile, Full HD, and 4K. Use fluid type and spacing, cap readable measure, stack dense regions at narrow widths, keep diagrams scrollable only when semantically necessary, and test 390px, 1920px, and 3840px viewports. +8. Finish with evidence: content verification, JavaScript syntax checks, interaction tests, responsive browser checks, and a diff check. The section is done when its content, dynamic states, links, and three viewport classes pass. diff --git a/skills/editorial-playbook/evals/evals.json b/skills/editorial-playbook/evals/evals.json new file mode 100644 index 0000000..6780888 --- /dev/null +++ b/skills/editorial-playbook/evals/evals.json @@ -0,0 +1,10 @@ +[ + { + "prompt": "Add a new bilingual chapter to a dependency-free static explainer with one diagram and one copy control. What should you decide and verify first?", + "expected_behavior": "Create a chapter map and content model first; pair EN/PT strings; use a small accessible interaction; verify mobile, Full HD, and 4K behavior." + }, + { + "prompt": "The explainer needs 20 more sections but has no data source for section metadata. Recommend a lightweight implementation.", + "expected_behavior": "Keep content in structured data and render shared editorial primitives; recommend plain HTML/CSS/JS for a small static site, or Astro/MDX when shared build-time content collections justify it." + } +] diff --git a/skills/editorial-playbook/references/page-anatomy.md b/skills/editorial-playbook/references/page-anatomy.md new file mode 100644 index 0000000..2402ea3 --- /dev/null +++ b/skills/editorial-playbook/references/page-anatomy.md @@ -0,0 +1,16 @@ +# Page anatomy + +Use this as a compact design contract for a new AI For Dummies chapter. + +1. **Orientation** — eyebrow, chapter number, title, short promise, language control. +2. **Thesis** — one sentence that changes how the reader sees the topic. +3. **Model** — a pipeline, tree, timeline, or comparison that makes the relationship visible. +4. **Practice** — a copy-ready prompt, command, example, or tiny exercise. +5. **Proof** — source paths, checks, observed behavior, and the boundary between advice and enforcement. +6. **Transfer** — a small “use this next” link to the next chapter or deeper source. + +Keep the first screen editorial and calm. Let code, diagrams, and controls earn their space by teaching something. Avoid a generic hero followed by an undifferentiated card grid. + +## Section contract + +Each new section should answer: what does the reader learn, what is the visible proof, what can they copy or try, and what source supports it? Add its copy to the language map before adding a control. Add its slug to navigation only after the section has a stable purpose. diff --git a/skills/rules-case-study/SKILL.md b/skills/rules-case-study/SKILL.md new file mode 100644 index 0000000..da8ed2e --- /dev/null +++ b/skills/rules-case-study/SKILL.md @@ -0,0 +1,18 @@ +--- +name: rules-case-study +description: Use when explaining how a repository turns agent guidance into enforceable behavior across context files, skills, CLI checks, Git hooks, CI, worktrees, or PR review; build a concise, source-linked case-study page. +--- + +# Rules case study + +Show the control loop: context → skills → CLI → commit → review. The reader should see where a rule lives, what executes it, and how to verify it. + +## Workflow + +1. Inspect authoritative files before writing copy. Start with the repository context file, skill directory, command or database ledger, enforcement scripts, hooks, staged-file config, CI, and review policy. Use [the interview source map](references/interview-source-map.md) as a routing hint, then confirm paths in the target repository. +2. Separate guidance from enforcement. A context file or skill teaches an agent; a CLI check, hook, CI job, or reviewer blocks or reports behavior. Never describe prose as mechanically enforced. +3. For every example, show the rule, exact source path, enforcement point, verification command, and remaining gap. Prefer one concrete ratchet or hook example over a list of vague best practices. +4. Add a skills shelf. Each skill needs a trigger, the lesson it carries, a tiny example, and a source link. Keep examples short enough to copy into an agent prompt. +5. Include a read-only exploration prompt that asks an agent to map rules to evidence and gaps. Add copy feedback and bilingual labels if the host guide supports both languages. +6. Use a dependency-free standalone page when the case study is mostly explanatory. Link back to the main guide and exact source files. Do not modify the source repository merely to document it. +7. Verify dynamic stage and skill states, source links, copy behavior, language switching, no horizontal overflow, and the 390px/1920px/3840px viewports. The page is done when every claim has a source or is clearly labeled as a design recommendation. diff --git a/skills/rules-case-study/evals/evals.json b/skills/rules-case-study/evals/evals.json new file mode 100644 index 0000000..e3c0e1c --- /dev/null +++ b/skills/rules-case-study/evals/evals.json @@ -0,0 +1,10 @@ +[ + { + "prompt": "Explain a repository's AGENTS.md, reusable skills, UI ratchet script, Husky hooks, and PR review config as one teachable page.", + "expected_behavior": "Build a context → skills → CLI → commit → review pipeline; link every claim to an exact source path; distinguish guidance from enforcement; include a short read-only exploration prompt." + }, + { + "prompt": "A skill says all pages need an h1 and a pre-commit script checks it. How should the case study describe that relationship?", + "expected_behavior": "Describe the skill/context as guidance and the script/hook as executable enforcement, then show the verification command and any gap between local hooks and CI." + } +] diff --git a/skills/rules-case-study/references/interview-source-map.md b/skills/rules-case-study/references/interview-source-map.md new file mode 100644 index 0000000..4cda740 --- /dev/null +++ b/skills/rules-case-study/references/interview-source-map.md @@ -0,0 +1,18 @@ +# Interview source map + +This map records the implementation inspected for the rules case study. Reconfirm paths when the source repository changes. + +| Concern | Source | Role | +| --- | --- | --- | +| Shared context | `AGENTS.md` | Stack, commands, product shape, conventions, and verification expectations. | +| Reusable procedures | `.agents/skills/` | Focused workflows such as gates, frontend, Go API, repo DB, and skill writing. | +| Machine-readable routing | `.agents/db/commands.json` | Canonical checks and code-generation commands. | +| UI enforcement | `scripts/check-ui-contract.mjs` | Ratchet for buttons, catches, headings, colors, and duplicate components. | +| Ratchet state | `scripts/ui-contract-baseline.json` | Baseline counts that new violations cannot exceed. | +| Commit boundary | `.husky/pre-commit` | Runs lint-staged and the UI contract check. | +| Commit message boundary | `.husky/commit-msg` | Runs commitlint. | +| Staged-file tools | `.lintstagedrc.cjs` | Biome, ESLint, Prettier, and Buf formatting by file type. | +| Independent review | `.pr-review.json` | Review focus, exclusions, security constraints, and test expectations. | +| Agent roles | `.claude/agents/` | Prior-art scout, scoped implementer, and verifier responsibilities. | + +The source of truth is the repository. This table is a teaching map, not a replacement for reading the files.