From a21b2f031791e40976a7b533fdbc07fdc65c4dcc Mon Sep 17 00:00:00 2001 From: lglucas Date: Sat, 8 Aug 2026 13:04:19 -0300 Subject: [PATCH 1/3] =?UTF-8?q?feat(wizard)!:=20reestrutura=20em=205=20fas?= =?UTF-8?q?es=20e=20move=20o=20prot=C3=B3tipo=20para=20antes=20da=20spec?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Unifica as quatro numerações incompatíveis do wizard (README 15 passos, Overview 17 itens, headings Stage 0-14, docs/wizard 01-08) em uma só: 5 fases com sub-estágios inteiros, mapeadas 1:1 nas 5 tags de commit. FASE 1 Largada 1.1-1.3 / FASE 2 Ideacao 2.1-2.8 / FASE 3 Prototipo 3.1-3.3 FASE 4 Documentacao 4.1-4.4 / FASE 5 Chegada 5.1 Mudanças principais: - Prototype Lab sobe para a Fase 3, antes do Product Brief e do Technical Plan, que passam a ser engenharia reversa do protótipo aprovado. - Estágios fracionários eliminados: 0.5 -> 1.2; 11.5 -> 3.1 (packs de design) + 4.3 (packs de stack). - Conserta bug preexistente nas tags: PROTOTIPO vinha cronologicamente depois de DOCUMENTACAO. Os 5 valores de tag não mudaram. - Novo artefato docs/product/DESIGN-DIRECTION.md como ponte Fase 3 -> 4, com tabela obrigatória de lacunas ("implied but never shown"). - Sprint -1 muda de função: de construir o protótipo para consolidá-lo em design system. - docs/wizard/ consolidado de 8 arquivos de tópico para 5 de fase, incluindo o Technical Plan que nunca teve arquivo próprio. BREAKING CHANGE: referências a estágios por número mudaram. "Stage 0.5" agora é 1.2 e "Stage 11.5" foi dividido em 3.1 e 4.3. Registros históricos (CHANGELOG, RELEASE-NOTES, session-logs antigos) foram deixados intactos de propósito. Co-Authored-By: Claude Opus 5 (1M context) --- .aios-self | 2 +- .claude/commands/registry-pick.md | 3 +- .claude/rules/documentation-layers.md | 3 +- .claude/rules/wizard-flow.md | 22 +- .claude/rules/wizard-stage-tags.md | 44 ++- .claude/skills/product-brief/SKILL.md | 23 +- .claude/skills/project-genesis/SKILL.md | 18 +- .claude/skills/prototype-lab/SKILL.md | 19 +- .claude/skills/registry-pick/SKILL.md | 23 +- .claude/skills/sprint-roadmap/SKILL.md | 16 +- CHANGELOG.md | 53 ++++ CLAUDE.md | 18 +- README.md | 56 ++-- START-HERE.md | 7 +- WIZARD.md | 250 +++++++++++++----- docs/documentation-layers.md | 4 + docs/installation.md | 2 +- docs/registry/packs/ui-ux-pro-max.md | 2 +- docs/wizard/01-ideation.md | 7 - docs/wizard/02-research-waves.md | 9 - docs/wizard/03-business-plan.md | 12 - docs/wizard/04-business-plan-review.md | 7 - docs/wizard/05-product-brief.md | 11 - docs/wizard/06-sprint-planning.md | 7 - docs/wizard/07-prototype-lab.md | 7 - docs/wizard/08-first-coding-sprint.md | 5 - docs/wizard/README.md | 29 +- docs/wizard/phase-1-largada.md | 42 +++ docs/wizard/phase-2-ideacao.md | 56 ++++ docs/wizard/phase-3-prototipo.md | 66 +++++ docs/wizard/phase-4-documentacao.md | 61 +++++ docs/wizard/phase-5-chegada.md | 32 +++ .../2026-08-08-v0.5.0-wizard-5-phases.md | 108 ++++++++ session-log/INDEX.md | 1 + .../product/DESIGN-DIRECTION.template.md | 115 ++++++++ 35 files changed, 932 insertions(+), 208 deletions(-) delete mode 100644 docs/wizard/01-ideation.md delete mode 100644 docs/wizard/02-research-waves.md delete mode 100644 docs/wizard/03-business-plan.md delete mode 100644 docs/wizard/04-business-plan-review.md delete mode 100644 docs/wizard/05-product-brief.md delete mode 100644 docs/wizard/06-sprint-planning.md delete mode 100644 docs/wizard/07-prototype-lab.md delete mode 100644 docs/wizard/08-first-coding-sprint.md create mode 100644 docs/wizard/phase-1-largada.md create mode 100644 docs/wizard/phase-2-ideacao.md create mode 100644 docs/wizard/phase-3-prototipo.md create mode 100644 docs/wizard/phase-4-documentacao.md create mode 100644 docs/wizard/phase-5-chegada.md create mode 100644 session-log/2026-08-08-v0.5.0-wizard-5-phases.md create mode 100644 templates/product/DESIGN-DIRECTION.template.md diff --git a/.aios-self b/.aios-self index d04945f..67f29fa 100644 --- a/.aios-self +++ b/.aios-self @@ -1,6 +1,6 @@ This file marks the AI Dev Operating System repository itself. -Its presence tells `scripts/detach-os.{sh,ps1}` and the WIZARD Stage 0.5 to SKIP detach actions, because we ARE the OS repo (not a derived project). +Its presence tells `scripts/detach-os.{sh,ps1}` and WIZARD stage 1.2 (Phase 1 — Largada) to SKIP detach actions, because we ARE the OS repo (not a derived project). DO NOT delete this file from the AI Dev OS repo. DO NOT copy this file to a derived project — if you used "Use this template" or cloned this repo, the marker should NOT travel with you (template copy excludes it via `.gitattributes` export-ignore). diff --git a/.claude/commands/registry-pick.md b/.claude/commands/registry-pick.md index d0b772a..8d2a05b 100644 --- a/.claude/commands/registry-pick.md +++ b/.claude/commands/registry-pick.md @@ -26,7 +26,8 @@ If arguments are omitted, the skill will read project signals from `docs/busines ## When to use -- Right after `WIZARD.md` Stage 11.5 (between Technical Plan and Sprint roadmap). +- At `WIZARD.md` **stage 3.1** — design-scoped pass, before the Prototype Lab. Output: `docs/technical/registry-pick-design.md`. +- At `WIZARD.md` **stage 4.3** — full stack pass, after the Technical Plan. Output: `docs/technical/registry-pick.md`. - When a new domain need surfaces mid-build. - After a new pack is added to `docs/registry/`. diff --git a/.claude/rules/documentation-layers.md b/.claude/rules/documentation-layers.md index 5e814a2..4514c1b 100644 --- a/.claude/rules/documentation-layers.md +++ b/.claude/rules/documentation-layers.md @@ -3,7 +3,8 @@ Each document has one responsibility: - `BUSINESS-PLAN.md`: business narrative. -- `PRODUCT-BRIEF.md`: operational product understanding. +- `DESIGN-DIRECTION.md`: the approved prototype direction — tokens, screens, flow. Written in Phase 3, read by Phase 4. +- `PRODUCT-BRIEF.md`: operational product understanding, reverse-engineered from the prototype. - `TECHNICAL-PLAN.md`: architecture, stack, security, tests. - `SPRINTS.md`: roadmap and execution plan. - `CHANGELOG.md`: what changed. diff --git a/.claude/rules/wizard-flow.md b/.claude/rules/wizard-flow.md index 63700e7..365843a 100644 --- a/.claude/rules/wizard-flow.md +++ b/.claude/rules/wizard-flow.md @@ -2,4 +2,24 @@ The Project Genesis Wizard must not be simplified. -New projects must go through ideation, ten questions, research plan approval, research waves, red team, consolidation, BP v0.0.1, human review, BP v0.0.2, product brief, technical plan, sprint roadmap, prototype lab, and first coding sprint. +The canonical flow is [`WIZARD.md`](../../WIZARD.md). It runs in **5 phases**, and none may be skipped: + +| Phase | Must include | +|---|---| +| **1 — Largada** | repository comprehension, detach from OS-origin, friendly opening | +| **2 — Ideação** | raw ideation, ten strategic questions, research plan approval, Wave 1 (market + competitors), Wave 2 (red team), Wave 3 (consolidation), BP v0.0.1, human review, BP v0.0.2 with impact review | +| **3 — Protótipo** | design pack pick, Prototype Lab with three distinct directions, direction approval, design tokens extracted to `docs/product/DESIGN-DIRECTION.md` | +| **4 — Documentação** | Product Brief, Technical Plan, stack pack pick, sprint roadmap | +| **5 — Chegada** | Sprint 0 / Sprint 1 | + +## Ordering rules that are not negotiable + +1. **Phase 3 runs before Phase 4.** The prototype is built from BP v0.0.2 and the research — never from a Product Brief, which does not exist yet. +2. **Phase 4 is reverse engineering, not invention.** The Product Brief and Technical Plan must be derived from the approved prototype and `DESIGN-DIRECTION.md`. Anything the prototype implies but does not show must be recorded as a gap, not filled in silently. +3. **Coding waits for Phase 5.** No production code before BP v0.0.2, the prototype direction, the Product Brief, the Technical Plan, and the sprint roadmap are all approved. + +## Referring to stages + +Use the phase as the handle: "Phase 3", "we're in Phase 4". Stage numbers (`3.2`, `4.1`) order steps inside a phase and may shift when a step is inserted. Phase names do not shift. + +Do not reintroduce fractional stages. If a new step is needed, add it as an integer stage inside the phase it belongs to. diff --git a/.claude/rules/wizard-stage-tags.md b/.claude/rules/wizard-stage-tags.md index 2c87fa2..743016e 100644 --- a/.claude/rules/wizard-stage-tags.md +++ b/.claude/rules/wizard-stage-tags.md @@ -1,40 +1,58 @@ # Wizard stage tags (opt-in) -Convenção opcional para marcar em qual estágio do WIZARD um commit pertence. Útil pra rastreamento automático de progresso (ex.: dashboards, métricas, relatórios). Quem não usa **não perde nada**. +Convenção opcional para marcar em qual fase do WIZARD um commit pertence. Útil pra rastreamento automático de progresso (ex.: dashboards, métricas, relatórios). Quem não usa **não perde nada**. ## Como usar -Adicione `[STAGE:X]` no fim da mensagem de commit. Os 5 estágios reconhecidos são: +Adicione `[STAGE:X]` no fim da mensagem de commit. As 5 tags correspondem **1:1 às 5 fases** do [`WIZARD.md`](../../WIZARD.md) — não existe tabela de tradução: um commit `[STAGE:PROTOTIPO]` *é* um commit da Fase 3. -| Tag | Significado | Quando aparece | -|---|---|---| -| `[STAGE:LARGADA]` | Repositório criado, primeiro commit feito. | Logo após "Use this template" + `git init` ou primeiro commit. | -| `[STAGE:IDEACAO]` | WIZARD Stages 1–4 (ideação, 10 perguntas, plano de pesquisa). | Commits de ideação raw, brainstorming, BP rascunho. | -| `[STAGE:DOCUMENTACAO]` | WIZARD Stages 5–12 (research, BP, Brief, Technical Plan, sprint roadmap). | Commits que adicionam ou revisam BP, Brief, TP, registry picks, sprint plan. | -| `[STAGE:PROTOTIPO]` | WIZARD Stage 13 (Prototype Lab). | Primeiro código no `prototype-lab/`. | -| `[STAGE:CHEGADA]` | Stage 14 — Sprint 1 começou ou primeiro deploy/run local. | Ambiente rodando, fluxo principal funcional. | +| Tag | Fase | Significado | Quando aparece | +|---|---|---|---| +| `[STAGE:LARGADA]` | **Fase 1** | Repositório é seu, desacoplado e seguro pra commitar. | Logo após "Use this template" + `git init` ou primeiro commit. | +| `[STAGE:IDEACAO]` | **Fase 2** | O pensamento: ideação, 10 perguntas, pesquisa, red team, BP v0.0.1 → v0.0.2. | Commits de ideação raw, brainstorming, pesquisa em `knowledge-base/`, BP e suas revisões. | +| `[STAGE:PROTOTIPO]` | **Fase 3** | O produto fica visível: marca, cores, UI, UX. | Primeiro código no `prototype-lab/`, as 3 direções, e o `DESIGN-DIRECTION.md`. | +| `[STAGE:DOCUMENTACAO]` | **Fase 4** | Engenharia reversa do protótipo aprovado + plano de execução. | Product Brief, Technical Plan, registry picks, sprint roadmap. | +| `[STAGE:CHEGADA]` | **Fase 5** | Sprint 1 começou ou primeiro deploy/run local. | Ambiente rodando, fluxo principal funcional. | ## Exemplos ``` feat: setup inicial e estrutura canônica [STAGE:LARGADA] docs: 10 perguntas estratégicas respondidas [STAGE:IDEACAO] -docs(business): BP v0.0.2 com correções do red team [STAGE:DOCUMENTACAO] -feat(prototype): primeiro fluxo de login com mock data [STAGE:PROTOTIPO] +docs(business): BP v0.0.2 com correções do red team [STAGE:IDEACAO] +feat(prototype): três direções visuais com mock data compartilhado [STAGE:PROTOTIPO] +docs(product): Product Brief derivado do protótipo aprovado [STAGE:DOCUMENTACAO] feat: app rodando no localhost com fluxo principal [STAGE:CHEGADA] ``` +## Por que as tags agora são cronológicas + +Até a v0.4.5 o WIZARD colocava o Prototype Lab **depois** do Product Brief, do Technical Plan e do roadmap. Isso deixava `PROTOTIPO` cronologicamente *depois* de `DOCUMENTACAO` — as tags saíam fora de ordem, e qualquer sistema que inferisse progresso pela sequência das tags via o projeto "andar pra trás". + +A reordenação da v0.5.0 (protótipo antes da documentação) conserta isso. As 5 tags agora aparecem na ordem em que estão listadas acima, sempre. + +**Os 5 valores de tag não mudaram.** Commits antigos continuam válidos; só a ordem esperada mudou. + ## Por que existe Sistemas externos (ex.: o "Grand Prix do Trilho" do `course/systems/grand-prix/`) podem ler os commits via GitHub API e inferir progresso automaticamente — sem precisar que o usuário marque manualmente. Isto torna possível dashboards de turma, métricas de adoção, relatórios de uso. ## Detecção como fallback -Se você esquecer a tag, ferramentas que dependem dela podem inferir o estágio a partir dos arquivos modificados (ex.: criação de `docs/business/BUSINESS-PLAN.md` → `DOCUMENTACAO`). Tags explícitas são preferidas porque eliminam ambiguidade. +Se você esquecer a tag, ferramentas que dependem dela podem inferir a fase a partir dos arquivos modificados: + +| Arquivos tocados | Fase inferida | +|---|---| +| `knowledge-base/`, `docs/business/BUSINESS-PLAN.md` | `IDEACAO` | +| `prototype-lab/`, `docs/product/DESIGN-DIRECTION.md` | `PROTOTIPO` | +| `docs/product/PRODUCT-BRIEF.md`, `docs/technical/`, `docs/SPRINTS.md` | `DOCUMENTACAO` | +| `src/`, `app/` | `CHEGADA` | + +Tags explícitas são preferidas porque eliminam ambiguidade. ## Quando NÃO usar -- Em commits que não correspondem a um estágio do WIZARD (ex.: ajuste de typo, fix de CI). Apenas omita a tag. +- Em commits que não correspondem a uma fase do WIZARD (ex.: ajuste de typo, fix de CI). Apenas omita a tag. - Em projetos que não seguem o WIZARD do AI Dev OS. ## Convenção é opt-in diff --git a/.claude/skills/product-brief/SKILL.md b/.claude/skills/product-brief/SKILL.md index 718f39c..0b0bdfb 100644 --- a/.claude/skills/product-brief/SKILL.md +++ b/.claude/skills/product-brief/SKILL.md @@ -1,5 +1,24 @@ # Product Brief Skill -Use after BP v0.0.2 is accepted. +Runs at **Phase 4.1** of `WIZARD.md`. -Create `docs/product/PRODUCT-BRIEF.md` as the operational product document. +Use after BP v0.0.2 is accepted **and** a prototype direction has been approved in Phase 3. + +Create `docs/product/PRODUCT-BRIEF.md` as the operational product document. Not investor copy — that is the Business Plan's job. + +## Method: reverse engineering, not invention + +The product was designed in Phase 3. This skill reads `docs/product/DESIGN-DIRECTION.md` and `prototype-lab//` and writes down what is already there. + +Required checks: + +- Every screen in the approved prototype appears in the brief, or is explicitly marked as cut. +- The user flow section matches the flow that was actually clickable in the prototype. +- UX tone is derived from `DESIGN-DIRECTION.md`, not invented. +- **Anything the prototype implied but never showed — empty states, errors, permissions, offline, edge cases — is listed as a gap, not silently filled in.** + +That last check is the reason the prototype comes first. A written spec invents its own completeness; a prototype makes the holes visible. + +## Contents + +One-liner, personas, jobs to be done, user flows, MVP, Phase 1, Phase 2, non-goals, activation moment, retention loop, monetization logic, trust/compliance requirements, UX tone, product risks. diff --git a/.claude/skills/project-genesis/SKILL.md b/.claude/skills/project-genesis/SKILL.md index 8dd625a..2d7c2d7 100644 --- a/.claude/skills/project-genesis/SKILL.md +++ b/.claude/skills/project-genesis/SKILL.md @@ -2,4 +2,20 @@ Use this skill when starting a new project from the AI Dev Operating System. -Follow `WIZARD.md` exactly. Do not skip ideation, ten questions, research plan approval, three research/review waves, BP v0.0.1, human review, BP v0.0.2, Product Brief, Technical Plan, sprint roadmap, or Prototype Lab. +Follow `WIZARD.md` exactly. It runs in **5 phases**, and none may be skipped: + +| Phase | Must include | +|---|---| +| **1 — Largada** | repository comprehension, detach from OS-origin, friendly opening | +| **2 — Ideação** | raw ideation, ten questions, research plan approval, three research/review waves, BP v0.0.1, human review, BP v0.0.2 | +| **3 — Protótipo** | design pack pick, Prototype Lab (3 directions), direction approved, `DESIGN-DIRECTION.md` written | +| **4 — Documentação** | Product Brief, Technical Plan, stack pack pick, sprint roadmap | +| **5 — Chegada** | Sprint 0 / Sprint 1 | + +## The one ordering mistake to avoid + +**Phase 3 comes before Phase 4.** Prototype first, then reverse-engineer the Product Brief and Technical Plan from the direction the user approves. + +Do not write the Product Brief and then prototype against it. That was the order until v0.4.5 and it was inverted deliberately: a spec written against a clickable prototype names the gaps that a spec written against a paragraph quietly invents. + +If the prototype seems to need the Product Brief, what it actually needs is missing from BP v0.0.2. Go back and add it there. diff --git a/.claude/skills/prototype-lab/SKILL.md b/.claude/skills/prototype-lab/SKILL.md index c9890a8..8c10677 100644 --- a/.claude/skills/prototype-lab/SKILL.md +++ b/.claude/skills/prototype-lab/SKILL.md @@ -2,4 +2,21 @@ Create three distinct HTML/CSS/JS prototype directions using the same mock data. -All prototypes must reflect the BP, personas, and Product Brief. Do not contaminate the production app with prototype code. +Runs at **Phase 3** of `WIZARD.md` — before the Product Brief and the Technical Plan, not after. + +## Inputs + +All prototypes must reflect `BP v0.0.2` (personas, positioning, MVP scope, primary flow) and the research in `knowledge-base/`. + +**The Product Brief is NOT an input.** It does not exist yet — Phase 4 derives it from the direction approved here. If you find yourself needing the Product Brief, the thing you actually need is missing from BP v0.0.2; go add it there. + +## Rules + +- Three directions, genuinely distinct — not three shades of one idea. +- Same mock data and same core flows across all three, so the comparison is about design and not content. +- Each direction carries an explicit brand hypothesis: palette, typography, density, tone. +- Do not contaminate the production app with prototype code. + +## Output + +After the user picks a direction, write `docs/product/DESIGN-DIRECTION.md` — tokens, typography scale, spacing, component inventory, screens, the flow as actually clicked, and what was rejected. That file is what Phase 4 reads. diff --git a/.claude/skills/registry-pick/SKILL.md b/.claude/skills/registry-pick/SKILL.md index 6fe2ee4..002d079 100644 --- a/.claude/skills/registry-pick/SKILL.md +++ b/.claude/skills/registry-pick/SKILL.md @@ -1,6 +1,6 @@ --- name: registry-pick -description: Recommend external repo packs from docs/registry/ that fit a project's stack, domain, and constraints. Use during /project-start (after the Technical Plan), when the user asks "que repos eu deveria usar?", or whenever a new need (security review, design system, deploy guidance) appears mid-build. +description: Recommend external repo packs from docs/registry/ that fit a project's stack, domain, and constraints. Runs twice in the WIZARD — a design-scoped pass at stage 3.1 (before the Prototype Lab) and a full stack pass at stage 4.3 (after the Technical Plan). Also use when the user asks "que repos eu deveria usar?", or whenever a new need (security review, design system, deploy guidance) appears mid-build. --- # Registry Pick @@ -13,7 +13,19 @@ This skill does NOT install anything. It shortlists what is worth installing for ## When to invoke -- During WIZARD Stage 11.5 (after Technical Plan, before Sprint roadmap). +The wizard invokes this skill **twice**, in two differently-scoped passes: + +| Pass | WIZARD stage | Scope | Output | +|---|---|---|---| +| **Design** | 3.1 — before the Prototype Lab | Only design-oriented packs: UI systems, design tokens, component libraries, diagramming, screenshot/asset tooling | `docs/technical/registry-pick-design.md` | +| **Stack** | 4.3 — after the Technical Plan | The whole catalog | `docs/technical/registry-pick.md` | + +The split is deliberate: design packs are worthless once the prototype is already built, and stack packs are guesswork before the Technical Plan exists. + +**Signals available differ between passes.** In the design pass there is no Product Brief, no Technical Plan, and no `prototype-lab/` yet — read `BP v0.0.2` and `knowledge-base/` instead, and do not ask for artifacts that Phase 3 has not produced. + +Also invoke: + - When the user asks "que repos eu uso aqui?", "tem algum pack pra X?", "que skill externa ajuda nisso?". - When a new domain need surfaces mid-build (compliance, design system, malware analysis, web3 integration). - After adding a new pack to the registry, to retest the recommendation for the current project. @@ -27,9 +39,9 @@ Before recommending, gather these from the project: | Signal | Source | Example | |--------|--------|---------| | Stack | `package.json`, `Anchor.toml`, `requirements.txt`, `Gemfile`, `Cargo.toml` | `@solana/web3.js` → web3/Solana | -| Domain | `docs/business/BUSINESS-PLAN.md`, `docs/product/PRODUCT-BRIEF.md` | "PHI" → healthcare, "pagamentos" → fintech | -| Compliance | `docs/technical/TECHNICAL-PLAN.md` security/privacy section | LGPD, GDPR, HIPAA, PCI | -| UI surface | Product Brief, prototype-lab presence | mobile, dashboard, B2C web | +| Domain | `docs/business/BUSINESS-PLAN.md`, `docs/product/PRODUCT-BRIEF.md` *(stack pass only)* | "PHI" → healthcare, "pagamentos" → fintech | +| Compliance | `docs/technical/TECHNICAL-PLAN.md` security/privacy section *(stack pass only)*; BP v0.0.2 risk section in the design pass | LGPD, GDPR, HIPAA, PCI | +| UI surface | BP v0.0.2 personas and positioning in the design pass; Product Brief + `prototype-lab/` in the stack pass | mobile, dashboard, B2C web | | Public/private | repo metadata, deploy intent | public GitHub → enables `gitleaks` | | Team familiarity | user statement | "primeira vez com Claude Code" → start with `#foundations` only | @@ -98,6 +110,7 @@ Project signals detected: - **Never recommend `archived` packs.** - **Flag missing license info.** If a pack has `License: check upstream`, surface that as an open question. - **Re-run after changes.** If the Technical Plan or Product Brief changes, re-invoke the skill. +- **Respect the pass scope.** In the design pass (stage 3.1), recommend only design-oriented packs and do not ask for the Product Brief, the Technical Plan, or the prototype — none of them exist yet. --- diff --git a/.claude/skills/sprint-roadmap/SKILL.md b/.claude/skills/sprint-roadmap/SKILL.md index 30aca6c..cdc4bcc 100644 --- a/.claude/skills/sprint-roadmap/SKILL.md +++ b/.claude/skills/sprint-roadmap/SKILL.md @@ -1,5 +1,17 @@ # Sprint Roadmap Skill -Use after BP, Product Brief, and Technical Plan exist. +Runs at **Phase 4.4** of `WIZARD.md` — last step before coding. -Create a 14–20 sprint roadmap and include Sprint -1 Prototype Lab before Foundation. +Use after BP v0.0.2, the approved prototype direction, the Product Brief, and the Technical Plan all exist. + +Create a 14–20 sprint roadmap. Sequencing and clarity matter more than time accuracy. + +## Sprint -1 changed job in v0.5.0 + +Sprint -1 used to build the Prototype Lab. The prototype now happens in Phase 3, before this roadmap is written, so Sprint -1 has a different purpose: + +**Sprint -1 — Design System.** Consolidate the approved prototype and `docs/product/DESIGN-DIRECTION.md` into real design tokens, components, and layout primitives that Sprint 1 can build on. + +Required file: `docs/sprints/sprint--1-design-system.md`. + +Do not generate a `sprint--1-prototype-lab.md` — that sprint no longer exists. diff --git a/CHANGELOG.md b/CHANGELOG.md index c1ddc35..5b86b20 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,59 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), --- +## [Unreleased] — v0.5.0 in progress + +> v0.5.0 is being delivered in four independent PRs. This section accumulates until the last one lands, then gets cut as a release. +> +> - [x] **PR 1** — WIZARD restructured into 5 phases, prototype before spec *(this entry)* +> - [ ] **PR 2** — Pitch artifact + "BP/Pitch online?" decision +> - [ ] **PR 3** — Skill frontmatter fix + audit +> - [ ] **PR 4** — awesome-selfhosted catalog + managed-vs-self-hosted question + +### Changed — WIZARD is now 5 phases, and the prototype comes before the spec + +**Breaking for anyone referencing stages by number.** The four competing numberings (`README.md` 15 steps, `WIZARD.md` overview 17 items, `WIZARD.md` stage headings `0`–`14`, `docs/wizard/` files `01`–`08`) were unified into one: + +| Phase | Stages | Commit tag | +|---|---|---| +| 1 — Largada | 1.1–1.3 | `[STAGE:LARGADA]` | +| 2 — Ideação | 2.1–2.8 | `[STAGE:IDEACAO]` | +| 3 — Protótipo | 3.1–3.3 | `[STAGE:PROTOTIPO]` | +| 4 — Documentação | 4.1–4.4 | `[STAGE:DOCUMENTACAO]` | +| 5 — Chegada | 5.1 | `[STAGE:CHEGADA]` | + +- **Prototype Lab moved from last-before-coding to Phase 3** — before the Product Brief and Technical Plan, which are now reverse-engineered from the approved prototype. +- **Fractional stages eliminated.** `Stage 0.5` (detach) → `1.2`. `Stage 11.5` (registry pick) → split into `3.1` (design packs, before prototyping) and `4.3` (stack packs, after the Technical Plan). +- **Phases map 1:1 onto the five commit tags** in `.claude/rules/wizard-stage-tags.md`. No translation table. This also fixes a pre-existing bug: under the old order `PROTOTIPO` came chronologically *after* `DOCUMENTACAO`, so systems inferring progress from tag sequence saw projects moving backwards. The five tag values are unchanged; old commits stay valid. +- **Sprint -1 changed job** from building the prototype to consolidating it into a design system. `docs/sprints/sprint--1-prototype-lab.md` → `docs/sprints/sprint--1-design-system.md`. +- **BP v0.0.2 gained an exit condition** at stage 2.8: it must explicitly state personas, positioning, MVP scope, and the primary user flow, because Phase 3 has no Product Brief to read. + +### Added + +- `docs/product/DESIGN-DIRECTION.md` as a required Phase 3 artifact — the bridge to Phase 4. Records chosen direction, color tokens, typography scale, spacing, component inventory, screens, the flow as actually clicked, and a mandatory **"implied but never shown"** gaps table (empty states, errors, permissions, long data, offline, mobile, accessibility). +- `templates/product/DESIGN-DIRECTION.template.md`. +- `docs/technical/registry-pick-design.md` as the output of the new design-scoped registry pass. +- `docs/wizard/phase-1-largada.md` … `phase-5-chegada.md` — five phase files replacing the eight `01`–`08` topic files. Includes Technical Plan guidance, which `docs/wizard/` never had. + +### Removed + +- `docs/wizard/01-ideation.md`, `02-research-waves.md`, `03-business-plan.md`, `04-business-plan-review.md`, `05-product-brief.md`, `06-sprint-planning.md`, `07-prototype-lab.md`, `08-first-coding-sprint.md` — consolidated into the five phase files. Migration table kept in `docs/wizard/README.md`. + +### Why + +A written spec invents its own completeness: it says "the user manages their projects" and moves on. A prototype forces the question *what does this screen look like when the list is empty?* — and either it was answered or the hole is visible. Phase 4 is now required to record those gaps rather than silently fill them. + +The Technical Plan gets a second benefit: its data model is derived from `prototype-lab/shared/mock-data.js`. Mock data written to make three screens look real contains exactly the fields the product displays and nothing speculative. + +Phases were chosen over a renumbered flat list because inserting a step into a flat list renumbers everything downstream — which is precisely how `0.5` and `11.5` came to exist. Under phases, insertion only renumbers within one phase, and the five phase names never move. + +### Migration notes + +- Historical records (`CHANGELOG.md` entries below, `RELEASE-NOTES-v0.4.*.md`, prior session logs) still say "Stage 0.5" / "Stage 11.5". They were deliberately not rewritten — they accurately record what was true at the time. +- `course/` content still references the old ordering and will drift until updated separately. + +--- + ## [0.4.5] — 2026-05-04 — Course vertical: workshop em 3 aulas (Experience Learning) + 2 sistemas planejados ### Added — Vertical educacional `course/` diff --git a/CLAUDE.md b/CLAUDE.md index 6206f0a..3333312 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -9,7 +9,7 @@ The purpose of this repo is to provide a day-zero operating system for AI-assist ## Golden rules 1. Do not code before context. -2. Use `START-HERE.md` and `WIZARD.md` for new projects. +2. Use `START-HERE.md` and `WIZARD.md` for new projects. Prototype (Phase 3) before specifying (Phase 4). 3. Keep documentation layers separate. 4. Preserve decision memory in `session-log/`. 5. Human review is mandatory for BP v0.0.1 before BP v0.0.2. @@ -39,6 +39,18 @@ prototype-lab/README.md ## Project Genesis Wizard -The canonical wizard is `WIZARD.md`. +The canonical wizard is `WIZARD.md`. It runs in **5 phases**: -Do not simplify it. Do not skip phases. Do not move to code before ideation, research, BP, human review, product brief, technical plan, sprint roadmap, and prototype lab are complete. +| Phase | Name | Produces | +|---|---|---| +| 1 | Largada | detached repo, project intro | +| 2 | Ideação | research, red team, BP v0.0.2 | +| 3 | Protótipo | brand, color, UI, UX — three clickable directions | +| 4 | Documentação | Product Brief + Technical Plan reverse-engineered from the prototype, then the roadmap | +| 5 | Chegada | Sprint 0 / Sprint 1 | + +Do not simplify it. Do not skip phases. + +**Phase 3 runs before Phase 4, deliberately.** The prototype is built from BP v0.0.2 and the research; the Product Brief and Technical Plan are then derived from the approved prototype. Never write the Product Brief first and prototype against it — that is the old order and it was inverted on purpose in v0.5.0. + +Do not move to code before all of Phase 1–4 is complete and approved. diff --git a/README.md b/README.md index 2e84afe..da9149c 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ **Day-zero operating system for serious vibe coding and AI-assisted SaaS development.** -Clone this repo, open it in your IDE, run Claude Code in the terminal, and let the **Project Genesis Wizard** take you from raw idea to product brief, business plan, prototype lab, sprint roadmap, and first coding sprint. +Clone this repo, open it in your IDE, run Claude Code in the terminal, and let the **Project Genesis Wizard** take you from raw idea to business plan, prototype lab, product brief, technical plan, sprint roadmap, and first coding sprint. This repo is not a finished SaaS template. It is the **operating layer** you put around a new SaaS so AI coding agents do not start from chaos. @@ -42,7 +42,7 @@ bash scripts/detach-os.sh # Linux/macOS powershell scripts/detach-os.ps1 # Windows ``` -The script walks you through detaching `origin` and (optionally) re-initializing Git. WIZARD Stage 0.5 also handles this educationally on first run. +The script walks you through detaching `origin` and (optionally) re-initializing Git. WIZARD Stage 1.2 also handles this educationally on first run. @@ -52,7 +52,7 @@ After you have your own repo set up, open the folder in your IDE and run Claude Claude, vamos iniciar um novo projeto. Leia primeiro o arquivo START-HERE.md e siga exatamente as instruções dele. ``` -Claude should read the repo structure, understand the operating system, and start the **Project Genesis Wizard** — including Stage 0.5 (detach from OS-origin) if you used the fallback `git clone` path. +Claude should read the repo structure, understand the operating system, and start the **Project Genesis Wizard** — including Stage 1.2 (detach from OS-origin) if you used the fallback `git clone` path. 📘 Need help setting up your IDE, Git, GitHub account, or Claude Code? Start here: [`docs/installation.md`](docs/installation.md). @@ -67,7 +67,7 @@ Claude should read the repo structure, understand the operating system, and star - A guided wizard for ideation, research, business planning, review, sprint planning, prototyping, and first implementation. - Agent workflows for market research, competitor analysis, red-team critique, technical/security review, coordination, and investor-ready copywriting. - Documentation layers: `PRODUCT-BRIEF.md`, `BUSINESS-PLAN.md`, `TECHNICAL-PLAN.md`, `SPRINTS.md`, `CHANGELOG.md`, and `session-log/`. -- A disposable `prototype-lab/` for 3 HTML prototype directions before building the real app. +- A disposable `prototype-lab/` for 3 HTML prototype directions — built before the Product Brief and Technical Plan, which are then reverse-engineered from the direction you approve. - Security, privacy, changelog, sprint, and coding rules from day zero. - Optional stack packs for SaaS, Next.js/Supabase, Solana, marketplace products, and other specialized projects. @@ -83,7 +83,7 @@ A curated, on-demand catalog of trusted external repository packs that can plug | [`docs/registry/packs/`](docs/registry/packs) | One-pager per repo: when to install, when NOT to install, install command, fit signals, conflicts. | | [`docs/registry/tags/`](docs/registry/tags) | Auxiliary indexes by tag (`security`, `design`, `foundations`, `stack-pack`, `ecosystem`). | | [`/registry-pick`](.claude/commands/registry-pick.md) | Slash command — reads the registry and outputs a prioritized recommendation for the current project. Never installs. | -| [`registry-pick` skill](.claude/skills/registry-pick/SKILL.md) | Powers the slash command and `WIZARD.md` Stage 11.5. | +| [`registry-pick` skill](.claude/skills/registry-pick/SKILL.md) | Powers the slash command and `WIZARD.md` Stages 3.1 (design packs) and 4.3 (stack packs). | **Adding new packs is one-pager-fast** — copy the template in [`docs/registry/README.md`](docs/registry/README.md), fill the fields, link from `INDEX.md` and the relevant tag file. Cross-link in `UPSTREAM-SOURCES.md` only if the pack also influenced this OS itself. @@ -143,24 +143,22 @@ A coordinated set of agents, skills, and templates designed for **non-developers ## 🧭 Core flow -1. Repository comprehension. -2. Friendly opening and user introduction. -3. Raw ideation: “Tell me about your project.” -4. Ideation polish and exactly 10 strategic questions. -5. Research plan approval. -6. Wave 1: competitor and market research. -7. Wave 2: red-team critique. -8. Wave 3: consolidation and BP writing. -9. Business Plan v0.0.1. -10. Human review. -11. Business Plan v0.0.2 with impact review. -12. Product Brief and Technical Plan. -13. 14–20 sprint roadmap. -14. Prototype Lab with 3 HTML prototype directions. -15. Sprint 0 / Sprint 1 implementation. +The wizard runs in **5 phases**. Phases are the handle you remember; the stages inside them are just ordering. + +| Phase | What happens | Commit tag | +|---|---|---| +| **1 — Largada** | Repo comprehension → detach from OS-origin → "Me fale sobre teu projeto." | `[STAGE:LARGADA]` | +| **2 — Ideação** | Raw ideation → 10 strategic questions → research plan approval → Wave 1 (market + competitors) → Wave 2 (red team) → Wave 3 (consolidation + BP v0.0.1) → human review → **BP v0.0.2** | `[STAGE:IDEACAO]` | +| **3 — Protótipo** | Design pack pick → **Prototype Lab: 3 HTML directions** (brand, color, UI, UX) → direction approved + design tokens extracted | `[STAGE:PROTOTIPO]` | +| **4 — Documentação** | **Product Brief** and **Technical Plan reverse-engineered from the approved prototype** → stack pack pick → 14–20 sprint roadmap | `[STAGE:DOCUMENTACAO]` | +| **5 — Chegada** | Sprint 0 / Sprint 1 implementation | `[STAGE:CHEGADA]` | The wizard intentionally prevents coding too early. +**The prototype comes before the spec, on purpose.** Phase 3 makes the product visible — three real directions you can click — and Phase 4 writes the Product Brief and Technical Plan from what is actually there. A spec written against a prototype names the gaps (empty states, errors, permissions) that a spec written against a paragraph quietly invents. Full rationale in [`WIZARD.md`](WIZARD.md#why-phase-3-comes-before-phase-4). + +The five phases map 1:1 onto the commit-tag convention in [`.claude/rules/wizard-stage-tags.md`](.claude/rules/wizard-stage-tags.md), so progress is inferable straight from git history. + --- ## 🧙 Project Genesis Wizard @@ -178,16 +176,19 @@ Me fale sobre teu projeto. Behind the scenes, Claude is instructed to create and maintain: ```txt -docs/product/PRODUCT-BRIEF.md docs/business/BUSINESS-PLAN.md +prototype-lab/ +docs/product/DESIGN-DIRECTION.md +docs/product/PRODUCT-BRIEF.md docs/technical/TECHNICAL-PLAN.md docs/SPRINTS.md CHANGELOG.md session-log/ knowledge-base/ -prototype-lab/ ``` +The order above is the order the wizard produces them in. + --- ## 🤖 Agents @@ -232,8 +233,9 @@ Important skills include: |---|---| | `START-HERE.md` | First file Claude reads. | | `WIZARD.md` | Full Project Genesis Wizard flow. | -| `docs/product/PRODUCT-BRIEF.md` | Operational product understanding. | | `docs/business/BUSINESS-PLAN.md` | Business/investor/hackathon document. | +| `docs/product/DESIGN-DIRECTION.md` | The approved prototype direction: tokens, screens, flow. Bridge from Phase 3 to Phase 4. | +| `docs/product/PRODUCT-BRIEF.md` | Operational product understanding, reverse-engineered from the prototype. | | `docs/technical/TECHNICAL-PLAN.md` | Stack, architecture, data, security, test plan. | | `docs/SPRINTS.md` | Detailed sprint roadmap. | | `CHANGELOG.md` | What changed by version. | @@ -245,7 +247,7 @@ Important skills include: ## 🧪 Prototype Lab -Before building the production app, the wizard creates a separate prototype space: +Phase 3 of the wizard — **before** the Product Brief and the Technical Plan, not after. This is where brand, color, typography, and the real user flow get decided. The wizard creates a separate prototype space: ```txt prototype-lab/ @@ -260,10 +262,12 @@ Rules: - Use plain HTML/CSS/JS. - Use the same mock data across all prototypes. -- Make the prototypes visually distinct. -- Match the personas and positioning from the Product Brief and Business Plan. +- Make the prototypes visually distinct — three directions, not three shades of one. +- Match the personas, positioning, and MVP scope from **BP v0.0.2** and the research in `knowledge-base/`. The Product Brief is not an input here — Phase 4 derives it from the prototype you approve. - Do not mix prototype files with production source code. +The approved direction is written up in `docs/product/DESIGN-DIRECTION.md`, which is what Phase 4 reads. + --- ## 🧱 Golden rules diff --git a/START-HERE.md b/START-HERE.md index c199049..79e290d 100644 --- a/START-HERE.md +++ b/START-HERE.md @@ -25,7 +25,7 @@ Read these files and directories before asking the user about the project: 5. `.claude/agents/` 6. `.claude/skills/` 7. `.claude/commands/` -8. `docs/wizard/README.md` +8. `docs/wizard/README.md` (and the five `phase-*.md` files it indexes) 9. `docs/documentation-layers.md` 10. `docs/agent-system.md` 11. `docs/skill-system.md` @@ -38,7 +38,7 @@ After reading, respond with: 1. A short confirmation that you read and understood the operating system. 2. A concise list of the main layers available. 3. A friendly wizard header. -4. A short explanation of the journey from idea to business plan, product brief, sprint roadmap, prototype lab, and first coding sprint. +4. A short explanation of the 5-phase journey: **Largada** (the repo becomes yours) → **Ideação** (research, red team, business plan) → **Protótipo** (brand, color, UI, UX in three clickable directions) → **Documentação** (product brief and technical plan reverse-engineered from the approved prototype) → **Chegada** (first coding sprint). 5. The first task: ask the user to tell you about their project. ## Required opening question @@ -55,7 +55,8 @@ Pode explicar livremente: nome do projeto, ideia central, produto ou serviço, c - Do not start coding. - Do not create a technical stack before understanding the idea. -- Do not skip research, BP, product brief, sprint planning, or prototype lab. +- Do not skip research, BP, prototype lab, product brief, technical plan, or sprint planning. +- Do not write the Product Brief before the Prototype Lab. Phase 3 comes before Phase 4 — the brief is derived from the approved prototype, not the other way around. - Do not summarize the wizard into a shorter process unless the user explicitly asks to bypass steps. - Always document material decisions in `session-log/` when files begin to be created. - Always keep `CHANGELOG.md` updated when project artifacts are created or modified. diff --git a/WIZARD.md b/WIZARD.md index 569a0e1..9585d63 100644 --- a/WIZARD.md +++ b/WIZARD.md @@ -4,44 +4,61 @@ This is the canonical wizard for turning a raw project idea into a structured Sa The wizard is intentionally detailed. Claude must follow it step by step and must not compress it into a shorter process unless the user explicitly asks to bypass the operating system. -The goal is not to produce code quickly. The goal is to produce a project that is clear, researched, documented, stress-tested, planned, prototyped, and only then coded. +The goal is not to produce code quickly. The goal is to produce a project that is clear, researched, documented, stress-tested, visually materialized, planned, and only then coded. --- -## Overview - -The wizard moves through these stages: - -1. Repository comprehension -1.5. **Detach from OS-origin (Stage 0.5)** — disconnect new project from the AI Dev OS repo before any commit. Educational + executable. -2. Friendly opening and user introduction -3. Raw ideation -4. Ideation expansion and ten strategic questions -5. Research plan approval -6. Wave 1 — market and competitor research -7. Wave 2 — red team critique -8. Wave 3 — consolidation and BP writing -9. Business Plan v0.0.1 delivery -10. Human review instructions -11. Business Plan v0.0.2 revision -12. Product Brief derivation -13. Technical Plan derivation -14. **External repo registry pick (Stage 11.5)** — recommend packs from `docs/registry/` -15. Sprint roadmap planning -16. Prototype Lab planning -17. Sprint 0 and first coding sprint preparation +## How this wizard is numbered + +The wizard has **5 phases**. Each phase contains numbered stages written as `phase.stage` (for example `3.2`). + +Phases are the primary handle. When someone says "we're in Phase 3", that is enough to locate the work. Stage numbers exist only to order the steps inside a phase. + +**Why phases and not one long list of stages:** inserting a step used to force a fractional stage (`0.5`, `11.5`) or renumber everything downstream. With phases, a new step only renumbers inside its own phase, and the five phase names never move. + +### Phase map + +| Phase | Name | Produces | Commit tag | +|---|---|---|---| +| **1** | Largada | A repo that is yours, detached and safe to commit to | `[STAGE:LARGADA]` | +| **2** | Ideação | The thinking: research, red team, Business Plan v0.0.2 | `[STAGE:IDEACAO]` | +| **3** | Protótipo | The product made visible: brand, color, UI, UX | `[STAGE:PROTOTIPO]` | +| **4** | Documentação | Reverse engineering: Product Brief, Technical Plan, roadmap | `[STAGE:DOCUMENTACAO]` | +| **5** | Chegada | Sprint 0 / Sprint 1 — real code | `[STAGE:CHEGADA]` | + +The five phases map 1:1 onto the commit-tag convention in [`.claude/rules/wizard-stage-tags.md`](.claude/rules/wizard-stage-tags.md). A commit tagged `[STAGE:PROTOTIPO]` *is* a Phase 3 commit. No translation table. + +### Why Phase 3 comes before Phase 4 + +Earlier versions of this wizard put the Prototype Lab after the Product Brief, the Technical Plan, and the sprint roadmap. That order asks the founder to specify a product they have not yet seen. + +The current order inverts it deliberately: + +- **Phase 3 materializes the product.** Three visual directions, built from the Business Plan and the research. This is where brand, color, typography, layout, and the actual user flows get decided — by looking at them, not by describing them. +- **Phase 4 reverse-engineers the documentation from the approved prototype.** The Product Brief describes screens that exist. The Technical Plan specifies a system whose surface is already known. + +A Technical Plan written against a prototype you can click is more honest than one written against a paragraph. + +**Consequence for Phase 3:** the prototype cannot depend on the Product Brief, because it does not exist yet. Its inputs are BP v0.0.2 (which already carries personas, positioning, and MVP scope per Stage 2.8), the research in `knowledge-base/`, and the ten strategic questions. --- -## Stage 0 — Repository comprehension +# PHASE 1 — LARGADA + +**Goal:** the user has a repository that belongs to them and is safe to commit to. +**Commit tag:** `[STAGE:LARGADA]` -Claude must first read `START-HERE.md`, `README.md`, `CLAUDE.md`, this file, `.claude/`, and the wizard docs. +--- + +## 1.1 — Repository comprehension + +Claude must first read `START-HERE.md`, `README.md`, `CLAUDE.md`, this file, `.claude/`, and the wizard docs in `docs/wizard/`. Claude must confirm it understood the operating system and must not start coding. --- -## Stage 0.5 — Detach from OS-origin (educate-and-execute) +## 1.2 — Detach from OS-origin (educate-and-execute) **This stage is mandatory for derived projects and skipped automatically when running inside the AI Dev OS repo itself.** @@ -95,12 +112,12 @@ This stage is the first time a non-developer user learns about Git, remotes, and ### Required output - `origin` no longer points to the OS repo (or `.git/` was re-initialized). -- User has a target repo URL of their own (or has explicitly chosen to defer Git/GitHub setup, in which case Stage 0.5 records the deferral and the wizard continues with a warning that no commit should happen until detach is complete). +- User has a target repo URL of their own (or has explicitly chosen to defer Git/GitHub setup, in which case this stage records the deferral and the wizard continues with a warning that no commit should happen until detach is complete). - `session-log/` records the detach decision and the reasoning. --- -## Stage 1 — Friendly opening +## 1.3 — Friendly opening Claude should greet the user and explain the wizard simply. @@ -114,7 +131,14 @@ Pode explicar livremente: nome do projeto, ideia central, produto ou serviço, c --- -## Stage 2 — Raw ideation capture +# PHASE 2 — IDEAÇÃO + +**Goal:** a researched, stress-tested Business Plan the founder actually believes in. +**Commit tag:** `[STAGE:IDEACAO]` + +--- + +## 2.1 — Raw ideation capture Capture project name, category, core idea, problem, personas, revenue model hypothesis, product/service nature, operational model, references, constraints, founder assumptions, unknowns, and gaps. @@ -122,7 +146,7 @@ Do not overcorrect yet. --- -## Stage 3 — Ideation expansion and ten strategic questions +## 2.2 — Ideation expansion and ten strategic questions Claude must respond with: @@ -139,7 +163,7 @@ Claude must stop after asking the ten questions and wait for the user's answers. --- -## Stage 4 — Research plan approval +## 2.3 — Research plan approval After the user answers the ten questions, Claude must present a research and agent execution plan and ask for approval. @@ -184,7 +208,7 @@ Claude must wait for explicit user approval. --- -## Stage 5 — Execute Wave 1 +## 2.4 — Execute Wave 1 (market and competitors) When approved, execute research. @@ -203,7 +227,7 @@ Each research file must distinguish source-backed facts, inferences, assumptions --- -## Stage 6 — Execute Wave 2 Red Team +## 2.5 — Execute Wave 2 (red team) Required outputs: @@ -217,7 +241,7 @@ Each red team report must include risks, contradictions, weak assumptions, failu --- -## Stage 7 — Execute Wave 3 Consolidation and BP writing +## 2.6 — Execute Wave 3 (consolidation and BP v0.0.1) Required outputs: @@ -232,7 +256,7 @@ After creating BP v0.0.1, update `CHANGELOG.md`, `session-log/INDEX.md`, and a d --- -## Stage 8 — Human BP review task +## 2.7 — Human BP review task Claude must instruct the user: @@ -247,7 +271,7 @@ Claude must stop and wait. --- -## Stage 9 — BP v0.0.2 impact-aware revision +## 2.8 — BP v0.0.2 impact-aware revision When the user returns corrections, Claude must perform two waves: @@ -262,7 +286,7 @@ Examples: - Persona changed → update copy, GTM, competitors, UX, MVP scope. - Stack changed → update technical plan, costs, sprint roadmap, risks. - Revenue model changed → update pricing, financials, GTM, metrics. -- MVP scope changed → update roadmap, sprint plan, prototype lab, DoD. +- MVP scope changed → update roadmap, sprint plan, prototype direction, DoD. - Compliance requirement changed → update security/privacy, legal risk, architecture, sprint gates. Required outputs: @@ -275,11 +299,101 @@ docs/business/BUSINESS-PLAN.md BP version becomes `v0.0.2`. +**BP v0.0.2 is the contract that Phase 3 builds against.** Before leaving this phase, confirm the BP explicitly states: personas, positioning, MVP scope, and the primary user flow. Phase 3 has no Product Brief to lean on — these four items are its only specification. + --- -## Stage 10 — Product Brief +# PHASE 3 — PROTÓTIPO + +**Goal:** the product becomes visible. Brand, color, typography, UI, and UX are decided by looking at three real options, not by describing them. +**Commit tag:** `[STAGE:PROTOTIPO]` + +**Inputs:** BP v0.0.2, `knowledge-base/` research, the ten strategic questions. +**Not an input:** the Product Brief — it does not exist yet, and Phase 4 derives it from what this phase produces. + +--- + +## 3.1 — Design pack pick + +Before prototyping, Claude must recommend which external **design-oriented** packs (from `docs/registry/`) fit this project. -After BP v0.0.2, Claude must create: +Trigger the `registry-pick` skill (or invoke `/registry-pick`) scoped to design: UI systems, design-token workflows, component libraries, diagramming, screenshot and asset tooling. + +Required output: + +```txt +docs/technical/registry-pick-design.md +``` + +The skill MUST NOT install anything. It shortlists and surfaces install commands. The user decides. + +> The stack-wide registry pick happens later, at Stage 4.3, once the Technical Plan knows the real stack. Splitting the pick in two is deliberate: design packs are useless after the prototype is built, and stack packs are guesswork before the Technical Plan exists. + +--- + +## 3.2 — Prototype Lab + +Claude must plan and generate a prototype lab with three distinct visual directions. + +Required folder: + +```txt +prototype-lab/ +├── README.md +├── index.html +├── shared/mock-data.js +├── shared/prototype-nav.css +├── prototype-a/index.html +├── prototype-a/styles.css +├── prototype-b/index.html +├── prototype-b/styles.css +├── prototype-c/index.html +└── prototype-c/styles.css +``` + +Rules: + +- Use plain HTML/CSS/JS unless the user asks otherwise. +- Prototypes are disposable and isolated from the real app. +- All three prototypes must use the same mock data and the same core flows. +- Each prototype must have a distinct UI/UX direction — not three shades of the same idea. +- Directions must fit the BP v0.0.2 personas, positioning, MVP scope, and the market research. +- Each direction must carry an explicit brand hypothesis: color palette, typography, density, tone, and what kind of company it makes the product look like. + +`prototype-lab/README.md` must state, per direction: who it is for, what it optimizes for, and what it sacrifices. + +--- + +## 3.3 — Direction approval and design tokens + +The user picks one direction (or an explicit combination of directions). + +Claude must then extract the decisions from the chosen prototype into a document that Phase 4 can consume: + +```txt +docs/product/DESIGN-DIRECTION.md +``` + +It must record: chosen direction and why, color tokens, typography scale, spacing and density rules, component inventory observed in the prototype, the screens that exist, the primary user flow as actually clicked, and what was explicitly rejected from the other two directions. + +**This document is the bridge between Phase 3 and Phase 4.** Without it, the reverse engineering in Phase 4 has nothing concrete to read. + +Claude must stop and wait for explicit approval of the direction before entering Phase 4. + +--- + +# PHASE 4 — DOCUMENTAÇÃO + +**Goal:** reverse-engineer the formal documentation from the approved prototype, then plan the execution. +**Commit tag:** `[STAGE:DOCUMENTACAO]` + +**Method:** this phase does not invent the product. It reads `docs/product/DESIGN-DIRECTION.md` and `prototype-lab//`, and writes down what is already there — plus everything the prototype implies but does not show. + +--- + +## 4.1 — Product Brief + +Claude must create: ```txt docs/product/PRODUCT-BRIEF.md @@ -287,9 +401,18 @@ docs/product/PRODUCT-BRIEF.md It must include product one-liner, personas, jobs to be done, user flows, MVP, Phase 1, Phase 2, non-goals, activation moment, retention loop, monetization logic, trust/compliance requirements, UX tone, and product risks. +**Reverse-engineering requirements specific to this order:** + +- Every screen in the approved prototype must appear in the Product Brief, or be explicitly marked as cut. +- The user flow section must match the flow that was actually clickable in the prototype. +- The UX tone section must be derived from `DESIGN-DIRECTION.md`, not invented. +- Anything the prototype implied but never showed (empty states, errors, permissions, offline, edge cases) must be listed as a gap, not silently filled in. + +The last item is the point of the reordering: a prototype makes gaps visible that a written spec hides. + --- -## Stage 11 — Technical Plan +## 4.2 — Technical Plan Claude must create: @@ -299,13 +422,15 @@ docs/technical/TECHNICAL-PLAN.md It must include recommended stack, rationale, architecture assumptions, data model assumptions, auth model, API conventions, security baseline, privacy/compliance baseline, testing strategy, CI/CD, environment variables, deployment assumptions, risks, and open questions. +The data model must be derived from the entities visible in the prototype's mock data (`prototype-lab/shared/mock-data.js`), not designed in the abstract. + No alpha/beta stack should be recommended unless explicitly accepted. --- -## Stage 11.5 — External repo registry pick +## 4.3 — Stack pack pick -Before the sprint roadmap, Claude must recommend which external repository packs (from `docs/registry/`) to install for THIS project. +Now that the stack is known, run the second registry pass — this time across the whole catalog. Trigger the `registry-pick` skill (or invoke `/registry-pick`). @@ -316,7 +441,7 @@ The skill reads `docs/registry/INDEX.md` and the relevant `packs/.md` one- - **Optional** — situational; depends on growth path. - **Skipped (and why)** — explicit non-recommendation with reason. -Required outputs: +Required output: ```txt docs/technical/registry-pick.md @@ -328,7 +453,7 @@ If a new pack is added to `docs/registry/` later in the project's life, re-invok --- -## Stage 12 — Sprint roadmap planning +## 4.4 — Sprint roadmap planning Claude must ask additional questions focused on sprint planning. @@ -339,47 +464,26 @@ Required files: ```txt docs/SPRINTS.md docs/sprints/sprint-00-setup.md -docs/sprints/sprint--1-prototype-lab.md +docs/sprints/sprint--1-design-system.md docs/sprints/sprint-01-foundation.md ``` Each sprint should include objective, DoD, deliverables, agents, skills, security gates, tests, risks, dependencies, expected artifacts, changelog, and session-log requirements. ---- - -## Stage 13 — Prototype Lab +**Note on Sprint -1.** In earlier versions this sprint built the prototype. The prototype now exists before the roadmap is written, so Sprint -1 changed job: it consolidates the approved prototype and `DESIGN-DIRECTION.md` into a real design system (tokens, components, layout primitives) that Sprint 1 can build on. -Before building the real app, Claude must plan and generate a prototype lab. - -Required folder: - -```txt -prototype-lab/ -├── README.md -├── index.html -├── shared/mock-data.js -├── shared/prototype-nav.css -├── prototype-a/index.html -├── prototype-a/styles.css -├── prototype-b/index.html -├── prototype-b/styles.css -├── prototype-c/index.html -└── prototype-c/styles.css -``` +--- -Rules: +# PHASE 5 — CHEGADA -- Use plain HTML/CSS/JS unless user asks otherwise. -- Prototypes are disposable and isolated from the real app. -- All three prototypes must use the same mock data and same core flows. -- Each prototype must have a distinct UI/UX direction. -- Directions must fit the BP, personas, product brief, and market. +**Goal:** real code, in the real app. +**Commit tag:** `[STAGE:CHEGADA]` --- -## Stage 14 — Start coding only after approval +## 5.1 — Start coding only after approval -Only after the user approves BP v0.0.2, Product Brief, Technical Plan, sprint roadmap, and prototype direction may Claude begin Sprint 0 / Sprint 1 implementation. +Only after the user approves BP v0.0.2, the prototype direction, the Product Brief, the Technical Plan, and the sprint roadmap may Claude begin Sprint 0 / Sprint 1 implementation. The first coding sprint must follow `.claude/rules/`. diff --git a/docs/documentation-layers.md b/docs/documentation-layers.md index 9d00f0b..d08394d 100644 --- a/docs/documentation-layers.md +++ b/docs/documentation-layers.md @@ -8,6 +8,10 @@ Each document type has a job. Avoid mixing them. | Rules | What constraints should agents obey? | `.claude/rules/*.md` | | Skills | How should a recurring workflow be executed? | `.claude/skills/**/SKILL.md` | | Commands | How does the user trigger a workflow? | `.claude/commands/*.md` | +| Business plan | Is this worth building, and for whom? | `docs/business/BUSINESS-PLAN.md` | +| Design direction | What did the approved prototype actually decide? | `docs/product/DESIGN-DIRECTION.md` | +| Product brief | What is the product, operationally? | `docs/product/PRODUCT-BRIEF.md` | +| Technical plan | How is it built, and what are the risks? | `docs/technical/TECHNICAL-PLAN.md` | | Sprint doc | What are we building in this execution cycle? | `docs/sprints/sprint-XX.md` | | Changelog | What changed in a release? | `CHANGELOG.md` | | Session log | Why did we decide something? | `session-log/YYYY-MM-DD-topic.md` | diff --git a/docs/installation.md b/docs/installation.md index 383e01b..d1d89ce 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -102,7 +102,7 @@ cd my-new-saas powershell scripts/detach-os.ps1 # Windows ``` -- Or let WIZARD Stage 0.5 walk you through it on first run. +- Or let WIZARD stage 1.2 (Phase 1 — Largada) walk you through it on first run. The script (and the wizard) will explain what `origin` is, how to create a new GitHub repo, how to swap remotes, and how to keep `.env` out of the repo. diff --git a/docs/registry/packs/ui-ux-pro-max.md b/docs/registry/packs/ui-ux-pro-max.md index de43955..8ac73d7 100644 --- a/docs/registry/packs/ui-ux-pro-max.md +++ b/docs/registry/packs/ui-ux-pro-max.md @@ -41,7 +41,7 @@ Install upstream as a Claude plugin/skill — do not vendor unless license allow ## Local mapping -Conceptually inspired the Prototype Lab phase in this OS (`docs/wizard/07-prototype-lab.md`). +Conceptually inspired the Prototype Lab phase in this OS (`docs/wizard/phase-3-prototipo.md`). Since v0.5.0 that phase runs *before* the Product Brief and Technical Plan, which makes this pack a stage 3.1 (design pass) candidate rather than a late-stage addition. ## Notes diff --git a/docs/wizard/01-ideation.md b/docs/wizard/01-ideation.md deleted file mode 100644 index 7dca0cd..0000000 --- a/docs/wizard/01-ideation.md +++ /dev/null @@ -1,7 +0,0 @@ -# 01 — Ideation - -The first user response is expected to be incomplete and informal. - -Claude should extract structure from the user's idea, then return a polished understanding and exactly ten tailored questions. - -Do not ask generic questions when the user already provided enough context. Ask sharper questions that mature the project. diff --git a/docs/wizard/02-research-waves.md b/docs/wizard/02-research-waves.md deleted file mode 100644 index 0bced27..0000000 --- a/docs/wizard/02-research-waves.md +++ /dev/null @@ -1,9 +0,0 @@ -# 02 — Research Waves - -The research phase begins only after the user approves the 3-wave plan. - -Wave 1: competitor research and market research. -Wave 2: devil's advocate, business/finance red team, and technical/security red team. -Wave 3: coordinator consolidation and copywriter business-plan writing. - -Every claim must separate facts, inferences, assumptions, and open questions. diff --git a/docs/wizard/03-business-plan.md b/docs/wizard/03-business-plan.md deleted file mode 100644 index 32abfea..0000000 --- a/docs/wizard/03-business-plan.md +++ /dev/null @@ -1,12 +0,0 @@ -# 03 — Business Plan - -The business plan is the investor/hackathon/partner-facing document. - -First version: `v0.0.1`. -After human review and impact review: `v0.0.2`. - -Required file: - -```txt -docs/business/BUSINESS-PLAN.md -``` diff --git a/docs/wizard/04-business-plan-review.md b/docs/wizard/04-business-plan-review.md deleted file mode 100644 index 68e8aa7..0000000 --- a/docs/wizard/04-business-plan-review.md +++ /dev/null @@ -1,7 +0,0 @@ -# 04 — Business Plan Review - -BP v0.0.1 is not final. - -The user must read it and return corrections by chapter/subchapter. - -Claude then applies corrections and runs an impact review to catch downstream inconsistencies. diff --git a/docs/wizard/05-product-brief.md b/docs/wizard/05-product-brief.md deleted file mode 100644 index 139e8fb..0000000 --- a/docs/wizard/05-product-brief.md +++ /dev/null @@ -1,11 +0,0 @@ -# 05 — Product Brief - -The product brief is derived from BP v0.0.2. - -It is not investor copy. It is the operational product document used by agents and developers. - -Required file: - -```txt -docs/product/PRODUCT-BRIEF.md -``` diff --git a/docs/wizard/06-sprint-planning.md b/docs/wizard/06-sprint-planning.md deleted file mode 100644 index 39a093b..0000000 --- a/docs/wizard/06-sprint-planning.md +++ /dev/null @@ -1,7 +0,0 @@ -# 06 — Sprint Planning - -The sprint document is the operational roadmap for AI-assisted coding. - -Recommended size: 14–20 weekly sprints. - -Each sprint should include objective, DoD, deliverables, agents, skills, security gates, tests, risks, dependencies, expected artifacts, and changelog/session-log requirements. diff --git a/docs/wizard/07-prototype-lab.md b/docs/wizard/07-prototype-lab.md deleted file mode 100644 index 3f3ef22..0000000 --- a/docs/wizard/07-prototype-lab.md +++ /dev/null @@ -1,7 +0,0 @@ -# 07 — Prototype Lab - -Prototype Lab happens before the real app foundation. - -It creates three distinct HTML prototype directions using the same data and same core flows. - -The goal is to compare design direction, not content differences. diff --git a/docs/wizard/08-first-coding-sprint.md b/docs/wizard/08-first-coding-sprint.md deleted file mode 100644 index 4303186..0000000 --- a/docs/wizard/08-first-coding-sprint.md +++ /dev/null @@ -1,5 +0,0 @@ -# 08 — First Coding Sprint - -Coding starts only after approval of BP v0.0.2, Product Brief, Technical Plan, sprint roadmap, and prototype direction. - -The first implementation sprint must follow `.claude/rules/`. diff --git a/docs/wizard/README.md b/docs/wizard/README.md index f5c69d9..9a7ae62 100644 --- a/docs/wizard/README.md +++ b/docs/wizard/README.md @@ -6,11 +6,24 @@ The canonical flow is `WIZARD.md` at the repository root. These files help Claud ## Files -- `01-ideation.md` -- `02-research-waves.md` -- `03-business-plan.md` -- `04-business-plan-review.md` -- `05-product-brief.md` -- `06-sprint-planning.md` -- `07-prototype-lab.md` -- `08-first-coding-sprint.md` +One file per phase, matching the 5 phases in `WIZARD.md` and the 5 commit tags in `.claude/rules/wizard-stage-tags.md`. + +| File | Phase | Commit tag | +|---|---|---| +| [`phase-1-largada.md`](phase-1-largada.md) | Largada — detach, repo comprehension, opening | `[STAGE:LARGADA]` | +| [`phase-2-ideacao.md`](phase-2-ideacao.md) | Ideação — 10 questions, 3 research waves, BP v0.0.2 | `[STAGE:IDEACAO]` | +| [`phase-3-prototipo.md`](phase-3-prototipo.md) | Protótipo — brand, color, UI, UX in 3 directions | `[STAGE:PROTOTIPO]` | +| [`phase-4-documentacao.md`](phase-4-documentacao.md) | Documentação — Brief + Technical Plan reverse-engineered, roadmap | `[STAGE:DOCUMENTACAO]` | +| [`phase-5-chegada.md`](phase-5-chegada.md) | Chegada — Sprint 0 / Sprint 1 | `[STAGE:CHEGADA]` | + +## Renamed in v0.5.0 + +This directory used to hold eight topic files numbered `01`–`08`, which was a fourth competing numbering alongside `README.md`, `WIZARD.md`'s overview, and `WIZARD.md`'s stage headings. They were consolidated into the five phase files above. + +| Old file | Now in | +|---|---| +| `01-ideation.md`, `02-research-waves.md`, `03-business-plan.md`, `04-business-plan-review.md` | `phase-2-ideacao.md` | +| `05-product-brief.md`, `06-sprint-planning.md` | `phase-4-documentacao.md` | +| `07-prototype-lab.md` | `phase-3-prototipo.md` | +| `08-first-coding-sprint.md` | `phase-5-chegada.md` | +| *(did not exist)* | Technical Plan, now covered in `phase-4-documentacao.md` | diff --git a/docs/wizard/phase-1-largada.md b/docs/wizard/phase-1-largada.md new file mode 100644 index 0000000..7873fb3 --- /dev/null +++ b/docs/wizard/phase-1-largada.md @@ -0,0 +1,42 @@ +# Phase 1 — Largada + +**Commit tag:** `[STAGE:LARGADA]` +**Canonical source:** [`WIZARD.md`](../../WIZARD.md) stages 1.1–1.3 + +--- + +## Goal + +The user ends this phase with a repository that belongs to them, is detached from the OS origin, and is safe to commit to. + +--- + +## 1.1 — Repository comprehension + +Claude reads the operating system before doing anything else: `START-HERE.md`, `README.md`, `CLAUDE.md`, `WIZARD.md`, `.claude/`, and this directory. + +The success criterion is that Claude can state what the OS expects of it — not that it read the files. + +No code. No scaffolding. No "let me just set up the project structure first." + +--- + +## 1.2 — Detach from OS-origin + +The single most common way a new user damages something is pushing their project into the public OS repo, or hitting "permission denied" and not understanding why. + +This stage intercepts before the first commit. It is educational as much as mechanical: the user should leave it understanding what `origin` is, not just having run a script. + +Skipped automatically when running inside the AI Dev OS repo itself. See `WIZARD.md` stage 1.2 for the full detection table and the three paths offered to the user. + +--- + +## 1.3 — Friendly opening + +One question, deliberately open: + +```txt +Me fale sobre teu projeto. +``` + +The user is not expected to answer well. Phase 2 exists to fix that. diff --git a/docs/wizard/phase-2-ideacao.md b/docs/wizard/phase-2-ideacao.md new file mode 100644 index 0000000..0927339 --- /dev/null +++ b/docs/wizard/phase-2-ideacao.md @@ -0,0 +1,56 @@ +# Phase 2 — Ideação + +**Commit tag:** `[STAGE:IDEACAO]` +**Canonical source:** [`WIZARD.md`](../../WIZARD.md) stages 2.1–2.8 + +--- + +## Goal + +A researched, stress-tested Business Plan the founder actually believes in — `BP v0.0.2`. + +--- + +## 2.1–2.2 — Ideation and the ten questions + +The first user response is expected to be incomplete and informal. + +Claude extracts structure from it, then returns a polished understanding, a stronger version of the concept, visible risks, and **exactly ten tailored questions**. + +Do not ask generic startup questions when the user already provided context. Ask sharper questions that mature the project. Then stop and wait. + +--- + +## 2.3 — Research plan approval + +Research does not begin until the user approves the 3-wave plan. Claude presents which agents run, what they look for, and where findings land — and waits for an explicit yes. + +--- + +## 2.4–2.6 — The three waves + +| Wave | Agents | Output | +|---|---|---| +| **1** | Competitor Research, Market Research | `knowledge-base/competitors/`, `knowledge-base/market/` | +| **2** | Devil's Advocate, Business/Finance Red Team, Technical/Security Red Team | `docs/business/_review/wave-2-*.md` | +| **3** | Coordinator, Copywriter | `docs/business/_review/wave-3-coordinator.md`, `docs/business/BUSINESS-PLAN.md` v0.0.1 | + +Every claim must separate facts, inferences, assumptions, and open questions. Every red team critique must propose a fix, not just an objection. + +--- + +## 2.7 — Human review + +`BP v0.0.1` is not final. The user reads it with a notepad and returns corrections by chapter and subchapter, in one long pass. + +This is a hard stop. Claude waits. + +--- + +## 2.8 — BP v0.0.2 with impact review + +Claude applies the corrections, then runs a second pass checking every change for downstream effects: a price change moves projections, LTV, and positioning; a persona change moves GTM, UX, and MVP scope. + +`BP v0.0.2` becomes the contract that Phase 3 builds against. + +**Before leaving this phase**, confirm the BP explicitly states four things: personas, positioning, MVP scope, and the primary user flow. Phase 3 has no Product Brief to lean on — these four are its only specification. diff --git a/docs/wizard/phase-3-prototipo.md b/docs/wizard/phase-3-prototipo.md new file mode 100644 index 0000000..43e2cc2 --- /dev/null +++ b/docs/wizard/phase-3-prototipo.md @@ -0,0 +1,66 @@ +# Phase 3 — Protótipo + +**Commit tag:** `[STAGE:PROTOTIPO]` +**Canonical source:** [`WIZARD.md`](../../WIZARD.md) stages 3.1–3.3 + +--- + +## Goal + +The product becomes visible. Brand, color, typography, UI, and UX are decided by looking at three real options, not by describing them. + +--- + +## Why this phase moved + +Until v0.4.5 the Prototype Lab ran *after* the Product Brief, the Technical Plan, and the sprint roadmap. That order asks a founder to specify a product they have never seen. + +Since v0.5.0 the order is inverted: prototype first, then reverse-engineer the documentation from the direction that gets approved. + +**What this buys you:** a written spec invents its own completeness. It says "the user manages their projects" and moves on. A prototype forces the question *what does this screen look like when the list is empty?* — and either you answered it or the gap is visible. Phase 4 is required to record those gaps rather than quietly fill them. + +--- + +## Inputs + +| Is an input | Is not an input | +|---|---| +| `BP v0.0.2` — personas, positioning, MVP scope, primary flow | `PRODUCT-BRIEF.md` — does not exist yet | +| `knowledge-base/` — market and competitor research | `TECHNICAL-PLAN.md` — does not exist yet | +| The ten strategic questions and their answers | The sprint roadmap — does not exist yet | + +If you find yourself wanting the Product Brief here, the thing you actually want is missing from BP v0.0.2. Go back and add it there. + +--- + +## 3.1 — Design pack pick + +A design-scoped pass over `docs/registry/`: UI systems, design-token workflows, component libraries, diagramming, screenshot tooling. + +Runs before prototyping because design packs are worthless once the prototype is built. Output: `docs/technical/registry-pick-design.md`. + +The full stack-wide pick happens later, at stage 4.3, once the Technical Plan knows the real stack. + +--- + +## 3.2 — Prototype Lab + +Three distinct HTML/CSS/JS directions, same mock data, same core flows. + +The goal is to compare **design direction**, not content. If the three prototypes differ in what they show, the comparison is worthless — differences must be in how it looks and how it feels to move through. + +Each direction carries an explicit brand hypothesis: palette, typography, density, tone, and what kind of company it makes the product look like. `prototype-lab/README.md` states, per direction: who it is for, what it optimizes for, and what it sacrifices. + +Prototypes are disposable and never mixed with production source. + +--- + +## 3.3 — Direction approval and design tokens + +The user picks one direction, or an explicit combination. + +Claude then writes `docs/product/DESIGN-DIRECTION.md`: chosen direction and why, color tokens, typography scale, spacing and density, component inventory, screens that exist, the primary flow as actually clicked, and what was rejected from the other two. + +**This file is the bridge to Phase 4.** Without it, the reverse engineering has nothing concrete to read. + +Hard stop — Claude waits for explicit approval before entering Phase 4. diff --git a/docs/wizard/phase-4-documentacao.md b/docs/wizard/phase-4-documentacao.md new file mode 100644 index 0000000..485ef61 --- /dev/null +++ b/docs/wizard/phase-4-documentacao.md @@ -0,0 +1,61 @@ +# Phase 4 — Documentação + +**Commit tag:** `[STAGE:DOCUMENTACAO]` +**Canonical source:** [`WIZARD.md`](../../WIZARD.md) stages 4.1–4.4 + +--- + +## Goal + +Reverse-engineer the formal documentation from the approved prototype, then plan the execution. + +--- + +## The method: read, don't invent + +This phase does not design the product. The product was designed in Phase 3. This phase reads `docs/product/DESIGN-DIRECTION.md` and `prototype-lab//` and writes down what is already there — **plus everything the prototype implies but does not show.** + +That second part is the whole point. A prototype has three screens; a real product has those three screens plus empty states, error states, permission failures, loading, offline, and the long tail of what happens when the data is ugly. The prototype makes their absence visible. This phase is required to list them as gaps, not to quietly invent answers. + +--- + +## 4.1 — Product Brief + +`docs/product/PRODUCT-BRIEF.md` — the operational product document used by agents and developers. Not investor copy; that is the Business Plan's job. + +Contains: one-liner, personas, jobs to be done, user flows, MVP, Phase 1, Phase 2, non-goals, activation moment, retention loop, monetization logic, trust/compliance requirements, UX tone, product risks. + +Reverse-engineering checks specific to the new order: + +- Every screen in the approved prototype appears here, or is explicitly marked as cut. +- The user flow section matches the flow that was actually clickable. +- UX tone comes from `DESIGN-DIRECTION.md`, not from imagination. +- Implied-but-unshown behavior is listed as a gap. + +--- + +## 4.2 — Technical Plan + +`docs/technical/TECHNICAL-PLAN.md` — stack, rationale, architecture assumptions, data model, auth model, API conventions, security baseline, privacy/compliance baseline, testing strategy, CI/CD, environment variables, deployment assumptions, risks, open questions. + +The data model is derived from the entities visible in `prototype-lab/shared/mock-data.js`. Mock data written to make three screens look real is a surprisingly honest first schema — it contains exactly the fields the product actually displays, and nothing speculative. + +No alpha/beta stack unless the user explicitly accepts it. + +--- + +## 4.3 — Stack pack pick + +The second registry pass, now across the whole catalog, because the stack is finally known. + +Output: `docs/technical/registry-pick.md`, with packs sorted into must-install / recommended / optional / skipped-and-why. The skill never installs anything — the user decides. + +--- + +## 4.4 — Sprint roadmap + +`docs/SPRINTS.md` plus the individual sprint files. Target 14–20 sprints. Sequencing and clarity matter more than time accuracy. + +Each sprint carries objective, DoD, deliverables, agents, skills, security gates, tests, risks, dependencies, expected artifacts, and changelog/session-log requirements. + +**Sprint -1 changed job.** It used to build the prototype. The prototype now exists before this roadmap is written, so Sprint -1 consolidates the approved prototype and `DESIGN-DIRECTION.md` into a real design system — tokens, components, layout primitives — that Sprint 1 builds on. diff --git a/docs/wizard/phase-5-chegada.md b/docs/wizard/phase-5-chegada.md new file mode 100644 index 0000000..f26c1e0 --- /dev/null +++ b/docs/wizard/phase-5-chegada.md @@ -0,0 +1,32 @@ +# Phase 5 — Chegada + +**Commit tag:** `[STAGE:CHEGADA]` +**Canonical source:** [`WIZARD.md`](../../WIZARD.md) stage 5.1 + +--- + +## Goal + +Real code, in the real app. + +--- + +## 5.1 — Start coding only after approval + +Coding starts only after the user approves all five of: + +1. `BP v0.0.2` +2. The prototype direction (`DESIGN-DIRECTION.md`) +3. `PRODUCT-BRIEF.md` +4. `TECHNICAL-PLAN.md` +5. The sprint roadmap + +The first implementation sprint must follow `.claude/rules/` — feature-based architecture, code style, secrets, security baseline, git workflow. + +--- + +## What Phase 5 inherits + +By the time code starts, the project already has a validated business case, a chosen visual direction with extracted tokens, a product spec whose gaps are named rather than hidden, a technical plan whose data model came from real mock data, and a sequenced roadmap. + +That is the point of the four phases before it. The wizard is slow at the start so that this phase is not. diff --git a/session-log/2026-08-08-v0.5.0-wizard-5-phases.md b/session-log/2026-08-08-v0.5.0-wizard-5-phases.md new file mode 100644 index 0000000..8dcd540 --- /dev/null +++ b/session-log/2026-08-08-v0.5.0-wizard-5-phases.md @@ -0,0 +1,108 @@ +# 2026-08-08 — v0.5.0 PR 1: WIZARD restructured into 5 phases, prototype moved before the spec + +## What was true before + +The wizard was described in **four mutually incompatible numberings**: + +| Source | Numbering | "Product Brief" was | "Prototype Lab" was | +|---|---|---|---| +| `README.md` "Core flow" | 15 flat steps | step 12 | step 14 | +| `WIZARD.md` Overview list | 17 items incl. `1.5` | item 12 | item 16 | +| `WIZARD.md` stage headings | `Stage 0, 0.5, 1–11, 11.5, 12, 13, 14` | Stage 10 | Stage 13 | +| `docs/wizard/` filenames | `01`–`08` | `05-product-brief.md` | `07-prototype-lab.md` | + +Saying "move stage 14 to position 12" therefore had no single translation. + +Two fractional stages existed (`0.5` detach, `11.5` registry pick), both bolted on after the fact — the symptom of a flat numbering with no room to insert. + +The Prototype Lab ran **after** the Product Brief, the Technical Plan, and the sprint roadmap. + +## What changed + +### 1. Five phases replace four numberings + +``` +FASE 1 — LARGADA [STAGE:LARGADA] 1.1 – 1.3 +FASE 2 — IDEAÇÃO [STAGE:IDEACAO] 2.1 – 2.8 +FASE 3 — PROTÓTIPO [STAGE:PROTOTIPO] 3.1 – 3.3 +FASE 4 — DOCUMENTAÇÃO [STAGE:DOCUMENTACAO] 4.1 – 4.4 +FASE 5 — CHEGADA [STAGE:CHEGADA] 5.1 +``` + +Phases are the handle; `phase.stage` orders steps inside them. + +### 2. Phase 3 (prototype) now runs before Phase 4 (Product Brief + Technical Plan) + +The documentation is reverse-engineered from the approved prototype rather than written ahead of it. + +### 3. Fractional stages eliminated + +`0.5` → `1.2`. `11.5` → split into `3.1` (design pack pick) and `4.3` (stack pack pick). + +### 4. Two new artifacts + +- `docs/product/DESIGN-DIRECTION.md` — the bridge from Phase 3 to Phase 4. Template added at `templates/product/DESIGN-DIRECTION.template.md`. +- `docs/technical/registry-pick-design.md` — output of the design-scoped registry pass. + +### 5. `docs/wizard/` consolidated 8 → 5 + +## Why + +### Why prototype before spec + +A written spec invents its own completeness. It says "the user manages their projects" and moves on. A prototype forces *what does this screen look like when the list is empty?* — and either it was answered or the hole is visible. + +Phase 4 is therefore **required to record gaps rather than fill them**. `DESIGN-DIRECTION.md` has a mandatory "implied but never shown" table (empty states, errors, permissions, long data, offline, mobile, accessibility), and the `product-brief` skill must carry those forward as gaps. + +The Technical Plan gains a second benefit: its data model is now derived from `prototype-lab/shared/mock-data.js`. Mock data written to make three screens look real contains exactly the fields the product displays and nothing speculative — a more honest first schema than one designed in the abstract. + +### Why phases and not one renumbered flat list + +Considered three options: + +| Option | Insert a step | Fractionals return? | Handles to memorize | Maps to commit tags | +|---|---|---|---|---| +| Flat 1–20 | renumbers everything downstream | yes, inevitably | 20 | needs a translation table | +| **Phases (chosen)** | renumbers inside one phase | structurally impossible | **5** | **1:1** | +| Names only, no numbers | free | n/a | n/a | 1:1, but loses progress-bar reading | + +The deciding factor was the last column. `.claude/rules/wizard-stage-tags.md` already defined five commit tags — `LARGADA`, `IDEACAO`, `DOCUMENTACAO`, `PROTOTIPO`, `CHEGADA` — consumed by the Grand Prix system via the GitHub API. Making the wizard's phases *be* those five tags removes the translation table permanently. + +### The reordering fixed a pre-existing bug in the tags + +Under the old order, `PROTOTIPO` (Stage 13) came chronologically **after** `DOCUMENTACAO` (Stages 5–12). Any system inferring progress from tag sequence saw projects moving backwards. Moving the prototype earlier makes the five tags monotonic for the first time. + +**The five tag values did not change.** Old commits stay valid; only the expected order moved. + +## Decisions worth preserving + +1. **BP v0.0.2 is now a hard contract.** Since Phase 3 has no Product Brief to read, stage 2.8 gained an exit condition: the BP must explicitly state personas, positioning, MVP scope, and the primary user flow. If a prototype seems to need the Product Brief, what it actually needs is missing from the BP. + +2. **`registry-pick` split into two passes rather than moved.** Design packs are worthless after the prototype exists; stack packs are guesswork before the Technical Plan exists. One pass could not serve both. The skill now documents which signals are available in each pass and forbids asking for artifacts the phase has not produced. + +3. **Sprint -1 changed job, not name.** It used to build the Prototype Lab. The prototype now precedes the roadmap, so Sprint -1 consolidates the approved prototype + `DESIGN-DIRECTION.md` into a design system. File renamed `sprint--1-prototype-lab.md` → `sprint--1-design-system.md`. + +4. **`docs/wizard/` consolidated by phase, not renumbered by topic.** Keeping eight topic files with a `phase-N-` prefix would have preserved a fourth numbering in disguise. Five files, one per phase, is the only arrangement that cannot drift from the canon. + +5. **Historical records left untouched.** `CHANGELOG.md`, all `RELEASE-NOTES-v0.4.x.md`, and prior session logs still say "Stage 0.5" and "Stage 11.5". Those are accurate records of what was true at the time and were deliberately not rewritten. + +6. **`.aios-self` edited safely.** Verified first that `scripts/detach-os.{sh,ps1}` only test the file's *existence* (`[ -f ]` / `Test-Path`) and never parse its contents, so updating the prose changed no behavior. + +## Verification performed + +- CI canon check reproduced locally — all 6 required root files present, all 4 `.claude/` directories present. +- Root-duplicate check: `rules/` exists locally as an empty untracked directory; `git ls-files rules/` is empty, so CI (which checks out from git) will not see it. +- All relative `.md` links across the repo resolved — zero broken. +- Grep sweep for `Stage 0.5`, `Stage 11.5`, `sprint--1-prototype-lab`, `07-prototype-lab` in live files: zero remaining outside the intentional migration table in `docs/wizard/README.md` and the historical records listed above. + +## Skipped / deferred + +- **Stage 2.9 (Pitch + "BP/Pitch online?") not added here.** It belongs to PR 2. Adding it now would have meant a placeholder stage. Because insertion inside a phase is cheap under the new scheme, PR 2 appends `2.9` without renumbering anything — which is the design working as intended. +- **Skill frontmatter not touched.** Six core wizard skills (`project-genesis`, `research-waves`, `business-plan-impact-review`, `product-brief`, `prototype-lab`, `sprint-roadmap`) have no YAML frontmatter and therefore no usable auto-invocation description. That is PR 3. This PR corrected only the *content* those skills got wrong via the reordering. +- **PR #9 left open.** Open since 2026-05-05 with `mergeStateStatus: DIRTY`; contains the Grand Prix system, which reads the stage tags changed here. User chose to proceed with v0.5.0 first and reconcile #9 afterwards. +- **`os-self-test` not run** — the skill exists but was not invoked; the manual equivalents above were run instead. + +## Open questions + +- The Grand Prix system in PR #9 will need its tag-ordering logic reviewed against the now-monotonic sequence. Worth checking whether it assumed the old backwards order. +- `course/` content references the old stage ordering in several places (`aula-1-fundacao`, `curso-overview.md`). Not touched here — the course vertical is deliberately separate, but it will drift until updated. diff --git a/session-log/INDEX.md b/session-log/INDEX.md index ebc78e4..54f1e5c 100644 --- a/session-log/INDEX.md +++ b/session-log/INDEX.md @@ -6,6 +6,7 @@ Each entry captures the reasoning behind a material decision: what was true befo | Date | Topic | File | |---|---|---| +| 2026-08-08 | v0.5.0 PR 1 — WIZARD restructured into 5 phases (1:1 with commit tags), Prototype Lab moved before Product Brief/Technical Plan, fractional stages eliminated, `registry-pick` split into design + stack passes | [`2026-08-08-v0.5.0-wizard-5-phases.md`](2026-08-08-v0.5.0-wizard-5-phases.md) | | 2026-05-09 | Registry additions — 14 new packs cataloged, 3 refreshed (Phase 2 cadence) | [`2026-05-09-registry-additions.md`](2026-05-09-registry-additions.md) | | 2026-05-04 | v0.4.5 course vertical — workshop em 3 aulas (Experience Learning Perestroika) + 2 sistemas planejados + easter egg `[STAGE:X]` | [`2026-05-04-v0.4.5-course-vertical.md`](2026-05-04-v0.4.5-course-vertical.md) | | 2026-05-04 | v0.4.4 repo hardening — branch protection, GitHub Template, WIZARD Stage 0.5 (detach from OS-origin), CONTRIBUTING flow | [`2026-05-04-v0.4.4-repo-hardening.md`](2026-05-04-v0.4.4-repo-hardening.md) | diff --git a/templates/product/DESIGN-DIRECTION.template.md b/templates/product/DESIGN-DIRECTION.template.md new file mode 100644 index 0000000..89bc41b --- /dev/null +++ b/templates/product/DESIGN-DIRECTION.template.md @@ -0,0 +1,115 @@ +# DESIGN-DIRECTION.md + +> Produced at WIZARD stage 3.3, after the user approves one of the three prototype directions. +> This file is the bridge between Phase 3 (Protótipo) and Phase 4 (Documentação). Phase 4 reads it to reverse-engineer the Product Brief and the Technical Plan. +> Replace every `<...>` placeholder. Delete this block when done. + +- **Project:** `` +- **Chosen direction:** `` +- **Approved on:** `` +- **Approved by:** `` + +--- + +## Why this direction won + +`` + +## What the other directions did better + +`` + +--- + +## Color tokens + +| Token | Value | Used for | +|---|---|---| +| `--color-bg` | `<#FFFFFF>` | `` | +| `--color-surface` | `<#F8FAFC>` | `` | +| `--color-text` | `<#0F172A>` | `` | +| `--color-text-muted` | `<#64748B>` | `` | +| `--color-primary` | `<#2563EB>` | `` | +| `--color-border` | `<#E2E8F0>` | `` | +| `--color-danger` | `<#DC2626>` | `` | + +State whether a dark variant exists. If it does not, say so — that is a Phase 4 gap, not an omission. + +## Typography + +| Role | Family | Size | Weight | Line height | +|---|---|---|---|---| +| Display | `<...>` | `<...>` | `<...>` | `<...>` | +| Heading | `<...>` | `<...>` | `<...>` | `<...>` | +| Body | `<...>` | `<...>` | `<...>` | `<...>` | +| Caption / label | `<...>` | `<...>` | `<...>` | `<...>` | +| Mono (if used) | `<...>` | `<...>` | `<...>` | `<...>` | + +## Spacing and density + +- Base unit: `<4px | 8px>` +- Scale: `<4, 8, 12, 16, 24, 32, 48, 64>` +- Container max width: `<...>` +- Density stance: `` — and who that serves. +- Border radius: `<...>` +- Elevation / shadow: `<...>` + +--- + +## Component inventory + +Everything that actually appears in the approved prototype. + +| Component | Where it appears | Variants seen | Notes | +|---|---|---|---| +| `