@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/docs/product/conversation-playbook.md

@@ -1,116 +1,116 @@
----
-description: "Product conversation playbook — opening messages, batching rules, proactive triggers, conversation phases, and finalize/surprise handling."
----
-
-# Product Conversation Playbook
-
-Load this module when `@product` is about to ask questions, refine an existing PRD, or continue a product conversation.
-
-## Opening message by mode
-
-Creation mode:
-
-> "Tell me about the idea — what problem does it solve and who has that problem?"
-
-Feature mode:
-
-> "What's the feature? Tell me what it should do and who it's for."
-
-Enrichment mode:
-
-> "I read the PRD. I noticed [specific gap or missing section]. Want to start there, or is there something else you'd like to refine first?"
-
-## Conversation rules
-
-1. First message = one open question only.
-2. From the second message onward, batch up to 5 numbered questions.
-3. End every batch with: `6 - Finalize — write the PRD now with what we have.`
-4. Reflect understanding before advancing to a new topic.
-5. Surface what founders usually forget: edge cases, empty states, admin roles, permissions, ownership, failure modes.
-6. Challenge confident assumptions gently with questions rather than assertions.
-7. Ruthlessly narrow scope when the discussion starts expanding.
-8. No filler openers.
-
-## Proactive domain triggers
-
-If the user did not mention a critical area, raise it when these signals appear:
-
-| Signal | Raise this |
-|--------|-----------|
-| Multiple user types | "Who manages the other users — is there an admin role?" |
-| Create/update/delete flows | "What happens if two people try to edit the same thing at the same time?" |
-| Stateful workflows | "Who can change a [state] and what happens when they do?" |
-| Potentially empty data | "What does the screen look like before the first [item] is added?" |
-| Money or subscription | "How does billing work — one-time, subscription, usage-based?" |
-| User-generated content | "What happens if a user posts something inappropriate?" |
-| External services | "What happens in the app if [service] is down?" |
-| Notifications | "What triggers a notification, and can users control which ones they get?" |
-| Team growth | "How does a new team member get access?" |
-
-## Visual and design triggers
-
-When visual quality is materially relevant:
-
-| Signal | Raise this |
-|--------|-----------|
-| "modern", "beautiful", "premium", "clean", "elegant" | "Is there an app or website whose look you admire?" |
-| Color, theme, or mood words | "What feeling should the interface transmit?" |
-| Consumer-facing product | "How important is visual quality relative to shipping speed for this first version?" |
-| Motion or interaction mentions | "Which interactions feel essential to the experience?" |
-| Existing brand mention | "Is there an existing brand guide, or are we defining the visual language from scratch?" |
-| Mobile implied | "Should mobile mirror desktop, or be adapted differently?" |
-| UI stack mention | "Is this the production UI, or a functional prototype that will be redesigned later?" |
-
-## Design skill preservation
-
-Before asking additional visual questions, read `design_skill` from `project.context.md`.
-
-Rules:
-
-- if `design_skill` is already set, preserve it
-- if `project_type=site` or `project_type=web_app` and `design_skill` is blank, ask whether to register one of the installed design skills under `.aioson/skills/design/`
-- never auto-select a design skill
-- if the user wants to postpone the decision, record `pending-selection`
-
-## Natural conversation phases
-
-The conversation normally moves through:
-
-- understand the problem
-- define the product
-- scope the first version
-- validate and close
-
-These are phases, not rigid steps. Move naturally based on what the user already answered.
-
-## Flow control
-
-Detect spontaneous finalize phrases:
-
-- `finalizar`
-- `finalize`
-- `chega de perguntas`
-- `pode gerar`
-- `wrap up`
-- `just write it`
-- `6`
-
-Detect surprise-mode phrases:
-
-- `me faça uma surpresa`
-- `surprise me`
-- `be creative`
-- `fill in the gaps`
-- `inventa você`
-
-### Finalize mode
-
-Generate the PRD immediately.
-Any undiscussed section should be written as `TBD — not discussed.`
-Do not invent content.
-
-### Surprise mode
-
-Fill undiscussed sections with explicit, reviewable judgment.
-Mark every inferred item with `_(inferred)_`.
-Do not leave sections empty.
+---
+description: "Product conversation playbook — opening messages, batching rules, proactive triggers, conversation phases, and finalize/surprise handling."
+---
+
+# Product Conversation Playbook
+
+Load this module when `@product` is about to ask questions, refine an existing PRD, or continue a product conversation.
+
+## Opening message by mode
+
+Creation mode:
+
+> "Tell me about the idea — what problem does it solve and who has that problem?"
+
+Feature mode:
+
+> "What's the feature? Tell me what it should do and who it's for."
+
+Enrichment mode:
+
+> "I read the PRD. I noticed [specific gap or missing section]. Want to start there, or is there something else you'd like to refine first?"
+
+## Conversation rules
+
+1. First message = one open question only.
+2. From the second message onward, batch up to 5 numbered questions.
+3. End every batch with: `6 - Finalize — write the PRD now with what we have.`
+4. Reflect understanding before advancing to a new topic.
+5. Surface what founders usually forget: edge cases, empty states, admin roles, permissions, ownership, failure modes.
+6. Challenge confident assumptions gently with questions rather than assertions.
+7. Ruthlessly narrow scope when the discussion starts expanding.
+8. No filler openers.
+
+## Proactive domain triggers
+
+If the user did not mention a critical area, raise it when these signals appear:
+
+| Signal | Raise this |
+|--------|-----------|
+| Multiple user types | "Who manages the other users — is there an admin role?" |
+| Create/update/delete flows | "What happens if two people try to edit the same thing at the same time?" |
+| Stateful workflows | "Who can change a [state] and what happens when they do?" |
+| Potentially empty data | "What does the screen look like before the first [item] is added?" |
+| Money or subscription | "How does billing work — one-time, subscription, usage-based?" |
+| User-generated content | "What happens if a user posts something inappropriate?" |
+| External services | "What happens in the app if [service] is down?" |
+| Notifications | "What triggers a notification, and can users control which ones they get?" |
+| Team growth | "How does a new team member get access?" |
+
+## Visual and design triggers
+
+When visual quality is materially relevant:
+
+| Signal | Raise this |
+|--------|-----------|
+| "modern", "beautiful", "premium", "clean", "elegant" | "Is there an app or website whose look you admire?" |
+| Color, theme, or mood words | "What feeling should the interface transmit?" |
+| Consumer-facing product | "How important is visual quality relative to shipping speed for this first version?" |
+| Motion or interaction mentions | "Which interactions feel essential to the experience?" |
+| Existing brand mention | "Is there an existing brand guide, or are we defining the visual language from scratch?" |
+| Mobile implied | "Should mobile mirror desktop, or be adapted differently?" |
+| UI stack mention | "Is this the production UI, or a functional prototype that will be redesigned later?" |
+
+## Design skill preservation
+
+Before asking additional visual questions, read `design_skill` from `project.context.md`.
+
+Rules:
+
+- if `design_skill` is already set, preserve it
+- if `project_type=site` or `project_type=web_app` and `design_skill` is blank, ask whether to register one of the installed design skills under `.aioson/skills/design/`
+- never auto-select a design skill
+- if the user wants to postpone the decision, record `pending-selection`
+
+## Natural conversation phases
+
+The conversation normally moves through:
+
+- understand the problem
+- define the product
+- scope the first version
+- validate and close
+
+These are phases, not rigid steps. Move naturally based on what the user already answered.
+
+## Flow control
+
+Detect spontaneous finalize phrases:
+
+- `finalizar`
+- `finalize`
+- `chega de perguntas`
+- `pode gerar`
+- `wrap up`
+- `just write it`
+- `6`
+
+Detect surprise-mode phrases:
+
+- `me faça uma surpresa`
+- `surprise me`
+- `be creative`
+- `fill in the gaps`
+- `inventa você`
+
+### Finalize mode
+
+Generate the PRD immediately.
+Any undiscussed section should be written as `TBD — not discussed.`
+Do not invent content.
+
+### Surprise mode
+
+Fill undiscussed sections with explicit, reviewable judgment.
+Mark every inferred item with `_(inferred)_`.
+Do not leave sections empty.

package/template/.aioson/docs/product/prd-contract.md

@@ -1,107 +1,107 @@
----
-description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
----
-
-# Product PRD Contract
-
-Load this module immediately before writing or updating any PRD.
-
-## Output paths
-
-- Creation / enrichment mode → `.aioson/context/prd.md`
-- Feature mode → `.aioson/context/prd-{slug}.md`
-
-`.aioson/context/` accepts only `.md` files.
-
-## Required PRD structure
-
-Use exactly these sections:
-
-```markdown
-# PRD — [Project Name]
-
-## Vision
-[One sentence. What this product is and why it matters.]
-
-## Problem
-[2–3 lines. The specific pain point and who experiences it.]
-
-## Users
-- [Role]: [what they need to accomplish]
-- [Role]: [what they need to accomplish]
-
-## MVP scope
-### Must-have 🔴
-- [Feature or capability — why it's required for launch]
-
-### Should-have 🟡
-- [Feature or capability — why it's valuable but not blocking]
-
-## Out of scope
-- [What is explicitly excluded from this version]
-
-## User flows
-### [Key flow name]
-[Step-by-step: User does X → System does Y → User sees Z]
-
-## Success metrics
-- [Metric]: [target and timeframe]
-
-## Open questions
-- [Unresolved decision that needs an answer before or during development]
-
-## Visual identity
-### Design skill
-### Aesthetic direction
-### Color & theme
-### Typography
-### Motion & interactions
-### Component style
-### Quality bar
-```
-
-## Visual identity inclusion rule
-
-Include `## Visual identity` when:
-
-- the client expressed visual preferences, or
-- `design_skill` is already set in `project.context.md`
-
-Omit it only when visual requirements were truly not discussed and no design skill was selected.
-
-### Design skill block
-
-Inside `### Design skill`:
-
-- write the selected design skill if chosen
-- if postponed, write `pending-selection`
-- add a note that `@ux-ui` must read `.aioson/skills/design/{skill}/SKILL.md` before design work when a skill is selected
-
-## Writing rules
-
-- Do not invent undiscussed content unless the user explicitly requested surprise mode
-- In standard finalize mode, unresolved sections become `TBD — not discussed.`
-- Keep the PRD focused; summarize sections that are getting too long
-- Preserve the user's product framing; do not drift into analyst or architect territory
-
-## Next-step routing
-
-After the PRD is produced:
-
-### New project (`prd.md`)
-
-| classification | Next step |
-|---|---|
-| MICRO | `@dev` |
-| SMALL | `@analyst` |
-| MEDIUM | `@analyst` then `@architect` → `@ux-ui` → `@pm` → `@orchestrator` |
-
-### New feature (`prd-{slug}.md`)
-
-| feature complexity | Next step |
-|---|---|
-| MICRO | `@dev` |
-| SMALL | `@analyst` |
-| MEDIUM | `@analyst` → `@architect` → `@dev` → `@qa` |
-
-Assess feature complexity from the conversation and state the next agent explicitly.
+---
+description: "Product PRD contract — exact PRD structure, visual identity block, output paths, and next-step routing."
+---
+
+# Product PRD Contract
+
+Load this module immediately before writing or updating any PRD.
+
+## Output paths
+
+- Creation / enrichment mode → `.aioson/context/prd.md`
+- Feature mode → `.aioson/context/prd-{slug}.md`
+
+`.aioson/context/` accepts only `.md` files.
+
+## Required PRD structure
+
+Use exactly these sections:
+
+```markdown
+# PRD — [Project Name]
+
+## Vision
+[One sentence. What this product is and why it matters.]
+
+## Problem
+[2–3 lines. The specific pain point and who experiences it.]
+
+## Users
+- [Role]: [what they need to accomplish]
+- [Role]: [what they need to accomplish]
+
+## MVP scope
+### Must-have 🔴
+- [Feature or capability — why it's required for launch]
+
+### Should-have 🟡
+- [Feature or capability — why it's valuable but not blocking]
+
+## Out of scope
+- [What is explicitly excluded from this version]
+
+## User flows
+### [Key flow name]
+[Step-by-step: User does X → System does Y → User sees Z]
+
+## Success metrics
+- [Metric]: [target and timeframe]
+
+## Open questions
+- [Unresolved decision that needs an answer before or during development]
+
+## Visual identity
+### Design skill
+### Aesthetic direction
+### Color & theme
+### Typography
+### Motion & interactions
+### Component style
+### Quality bar
+```
+
+## Visual identity inclusion rule
+
+Include `## Visual identity` when:
+
+- the client expressed visual preferences, or
+- `design_skill` is already set in `project.context.md`
+
+Omit it only when visual requirements were truly not discussed and no design skill was selected.
+
+### Design skill block
+
+Inside `### Design skill`:
+
+- write the selected design skill if chosen
+- if postponed, write `pending-selection`
+- add a note that `@ux-ui` must read `.aioson/skills/design/{skill}/SKILL.md` before design work when a skill is selected
+
+## Writing rules
+
+- Do not invent undiscussed content unless the user explicitly requested surprise mode
+- In standard finalize mode, unresolved sections become `TBD — not discussed.`
+- Keep the PRD focused; summarize sections that are getting too long
+- Preserve the user's product framing; do not drift into analyst or architect territory
+
+## Next-step routing
+
+After the PRD is produced:
+
+### New project (`prd.md`)
+
+| classification | Next step |
+|---|---|
+| MICRO | `@dev` |
+| SMALL | `@analyst` |
+| MEDIUM | `@analyst` then `@architect` → `@ux-ui` → `@pm` → `@orchestrator` |
+
+### New feature (`prd-{slug}.md`)
+
+| feature complexity | Next step |
+|---|---|
+| MICRO | `@dev` |
+| SMALL | `@analyst` |
+| MEDIUM | `@analyst` → `@architect` → `@dev` → `@qa` |
+
+Assess feature complexity from the conversation and state the next agent explicitly.

package/template/.aioson/docs/product/quality-lens.md

@@ -1,57 +1,57 @@
----
-description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
----
-
-# Product Quality Lens
-
-Load this module before writing or updating any PRD.
-
-## Positive patterns
-
-High-quality product output usually does all of this:
-
-- names a specific user and a specific pain instead of a generic audience
-- shows the tension behind the first release: what matters now and what is deliberately deferred
-- captures edge cases, empty states, permissions, and failure behavior early
-- explains why this product should be chosen instead of a generic alternative
-- leaves downstream agents with decisions they can execute, not vague aspirations
-- preserves visual ambition when visual quality changes the product outcome
-
-## Anti-patterns and replacements
-
-| Anti-pattern | Replace with |
-|---|---|
-| Generic SaaS PRD that could fit any startup | A PRD with domain nouns, real user moments, and explicit constraints |
-| Feature list without decision tension | A scoped first release with clear deferrals |
-| User story with no operator or owner | Named roles, ownership, and state transitions |
-| Competitive claim with no evidence | Research-backed differentiation or explicit uncertainty |
-| Beautiful-product language with no design bar | A concrete `## Visual identity` direction or `pending-selection` |
-
-## Elevation moves
-
-Before finalizing, force at least one improvement from each category:
-
-- sharpen the user/problem statement
-- sharpen the scope boundary
-- sharpen one risk or edge case
-- sharpen one differentiator or positioning detail
-
-## Review scorecard
-
-Score the PRD from `1-5` on:
-
-- specificity
-- differentiation
-- scope discipline
-- downstream usefulness
-- operational realism
-
-If any score is `3` or lower, revise before finalizing.
-
-## Final pass
-
-Ask silently:
-
-- Would this still read as strong if the product name were removed?
-- Does at least one section prove the product is not a template clone?
-- Can `@analyst`, `@ux-ui`, and `@dev` act on this without guessing core intent?
+---
+description: "Product quality lens — strong patterns, anti-pattern replacements, and a compact scorecard for higher-quality PRDs."
+---
+
+# Product Quality Lens
+
+Load this module before writing or updating any PRD.
+
+## Positive patterns
+
+High-quality product output usually does all of this:
+
+- names a specific user and a specific pain instead of a generic audience
+- shows the tension behind the first release: what matters now and what is deliberately deferred
+- captures edge cases, empty states, permissions, and failure behavior early
+- explains why this product should be chosen instead of a generic alternative
+- leaves downstream agents with decisions they can execute, not vague aspirations
+- preserves visual ambition when visual quality changes the product outcome
+
+## Anti-patterns and replacements
+
+| Anti-pattern | Replace with |
+|---|---|
+| Generic SaaS PRD that could fit any startup | A PRD with domain nouns, real user moments, and explicit constraints |
+| Feature list without decision tension | A scoped first release with clear deferrals |
+| User story with no operator or owner | Named roles, ownership, and state transitions |
+| Competitive claim with no evidence | Research-backed differentiation or explicit uncertainty |
+| Beautiful-product language with no design bar | A concrete `## Visual identity` direction or `pending-selection` |
+
+## Elevation moves
+
+Before finalizing, force at least one improvement from each category:
+
+- sharpen the user/problem statement
+- sharpen the scope boundary
+- sharpen one risk or edge case
+- sharpen one differentiator or positioning detail
+
+## Review scorecard
+
+Score the PRD from `1-5` on:
+
+- specificity
+- differentiation
+- scope discipline
+- downstream usefulness
+- operational realism
+
+If any score is `3` or lower, revise before finalizing.
+
+## Final pass
+
+Ask silently:
+
+- Would this still read as strong if the product name were removed?
+- Does at least one section prove the product is not a template clone?
+- Can `@analyst`, `@ux-ui`, and `@dev` act on this without guessing core intent?