@jaimevalasek/aioson 1.7.2 → 1.8.0

package/template/.aioson/design-docs/folder-structure.md

@@ -0,0 +1,51 @@
+---
+description: "Universal folder organization rules — hierarchy, depth, naming, grouping"
+scope: "governance"
+agents: []
+---
+
+# Folder Structure — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Depth
+
+- Maximum 3 levels of nesting before splitting into a separate module.
+- If you need a 4th level, the responsibility likely belongs in its own module or package.
+
+## Naming
+
+- **kebab-case** for all folder names: `user-auth/`, `squad-dashboard/`, `context-cache/`
+- **Singular** for a single entity or specific responsibility: `service/`, `command/`, `handler/`
+- **Plural** for collections of items of the same type: `services/`, `commands/`, `handlers/`
+- Never mix styles within the same directory level
+
+## Grouping strategy
+
+Prefer **domain-based grouping** over layer-based when the project grows beyond 5–6 modules:
+
+```
+src/
+  auth/         ← domain: everything related to authentication
+  billing/      ← domain: everything related to billing
+  shared/       ← cross-domain: utilities, types, helpers
+```
+
+Layer-based is valid for small projects or when the framework enforces it:
+
+```
+src/
+  controllers/  ← HTTP layer
+  services/     ← business logic
+  models/       ← data layer
+  utils/        ← shared helpers
+```
+
+Choose one strategy and stay consistent within the same project.
+
+## Anti-patterns
+
+- Never use generic folders: `misc/`, `stuff/`, `temp/`, `old/`, `helpers/`
+- Never leave unrelated files loose in `src/` root — every file belongs to a domain
+- Never create a folder with a single file (except `index.js` / `index.ts` as a public module entry point)
+- Never nest a folder that has the same semantic scope as its parent

package/template/.aioson/design-docs/naming.md

@@ -0,0 +1,54 @@
+---
+description: "Naming conventions for files, variables, functions, and classes"
+scope: "governance"
+agents: []
+---
+
+# Naming — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Files
+
+- **kebab-case** for all source files: `user-auth.js`, `billing-service.ts`, `context-writer.py`
+- When inside a flat directory, use a domain prefix to group related files: `user-create.js`, `user-update.js`, `user-delete.js`
+- Avoid generic suffixes when the domain name already conveys the type: prefer `auth.js` over `auth-helper.js`
+- Test files mirror the source file name: `user-auth.test.js`, `billing_service_test.py`
+
+## Variables and constants
+
+| Type | JS / TS | Python / Ruby | Go / Rust |
+|------|---------|---------------|-----------|
+| Local variables | camelCase | snake_case | camelCase / snake_case |
+| Global constants | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE |
+| Environment variables | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE | SCREAMING_SNAKE_CASE |
+
+## Functions and methods
+
+Pattern: **verb + noun** — describes what the function does and to what.
+
+Good: `loadUser()`, `parseManifest()`, `validateEmail()`, `sendInvoice()`, `buildQuery()`
+Avoid: `doUser()`, `process()`, `handle()` — too vague to understand intent
+Avoid: `userLoader()`, `manifestParser()` — noun-first reads as a class or object, not a function
+
+## Booleans
+
+Always use a prefix that makes the boolean read as a yes/no question:
+
+- `is` — state: `isReady`, `isEmpty`, `isAuthenticated`, `isValid`
+- `has` — possession: `hasErrors`, `hasChildren`, `hasPermission`
+- `should` — intent: `shouldRetry`, `shouldRedirect`, `shouldNotify`
+- `can` — capability: `canEdit`, `canDelete`, `canPublish`
+
+## Classes and components
+
+- **PascalCase**: `UserService`, `BillingController`, `AuthModal`, `InvoiceJob`
+- Singular: `User`, not `Users` — a class represents one entity, not a collection
+- React / Vue / Svelte components: same PascalCase rule, filename in kebab-case: `UserCard.tsx` → `user-card.tsx`
+
+## Avoid
+
+- Abbreviations unless they are industry-standard: `url`, `id`, `api`, `html`, `dto` are fine; `usrCtx`, `mngr`, `cfg`, `hlpr` are not
+- Single-letter variables except for loop indices (`i`, `j`, `k`) and math/geometry variables
+- Names that describe the type instead of the intent: `dataObject`, `listArray`, `stringValue`
+- Negative booleans: `isNotReady`, `hasNoErrors` — flip to positive: `isReady`, `isValid`

package/template/.aioson/docs/LAYERS.md

@@ -5,7 +5,7 @@ agents: []
 
 # AIOSON Project Memory Layers
 
-Three directories accumulate project knowledge over time.
+Four directories accumulate project knowledge over time.
 Each has a different purpose and a different update cadence.
 
 ---
@@ -42,7 +42,16 @@ See `docs/README.md` for format and naming conventions.
 
 ---
 
-## Layer 3 — `.aioson/context/design-doc*.md`
+## Layer 3 — `.aioson/design-docs/`
+
+**What it is:** structural code governance: folder structure, componentization, reuse, naming, and file-size thresholds.
+**Who writes it:** installed by AIOSON, then edited by the project team when conventions change.
+**When to use:** before architectural structure decisions and before implementation that creates files, splits modules, introduces reusable code, or names APIs.
+**Cadence:** stable. These files are project-local and preserved on update.
+
+---
+
+## Layer 4 — `.aioson/context/design-doc*.md`
 
 **What it is:** living decision document for the current feature or project scope.
 **Who writes it:** @discovery-design-doc.
@@ -58,6 +67,7 @@ See `docs/README.md` for format and naming conventions.
 |-----------|--------------|
 | Enforce a coding convention for this project | `rules/` |
 | Agents must always know about an external API behavior | `docs/` |
+| Enforce structural code quality guidance | `design-docs/` |
 | Document the scope and decisions for a specific feature | `design-doc-{slug}.md` |
 | Log a global project-wide architecture decision | `design-doc.md` |
 | Promote a recurring @dev pattern | `rules/` via @dev promotion |

package/template/.aioson/docs/dev/execution-discipline.md

@@ -0,0 +1,106 @@
+---
+description: "Dev execution discipline — semantic commits, learnings, task tracking, planning, atomic execution, verification gates, skeleton updates, and debugging."
+---
+
+# Dev Execution Discipline
+
+Load this module when the work is multi-file, ambiguous, near completion, or requires repeated verification.
+
+## Semantic commit format
+
+Use:
+
+- `feat(module): ...`
+- `fix(module): ...`
+- `refactor(module): ...`
+- `test(module): ...`
+- `docs(module): ...`
+- `chore(module): ...`
+
+## Session learnings
+
+At the end of productive sessions, look for:
+
+- user corrections
+- repeated successful patterns
+- new domain facts
+- quality failures or bugs
+
+Capture only the top 3 to 5 concise learnings in `spec.md` under session learnings.
+
+## Working memory
+
+Use task tooling when available:
+
+- `TaskCreate` — create slices
+- `TaskUpdate (in_progress)` — mark in-progress
+- `TaskUpdate (completed)` — mark completed with a one-line summary
+- `TaskList` — review before starting new slices
+
+`dev-state.md` is the persistent human-readable summary, not the live task board.
+
+## Self-directed planning
+
+Before ambiguous or multi-file work:
+
+1. declare planning mode
+2. list touched files and why
+3. sequence the implementation
+4. define verification criteria
+5. exit planning mode before coding
+
+Single-file, obvious changes do not need a full planning pass.
+
+## Working rules
+
+- reuse skills before reinventing patterns
+- load detailed skills and docs on demand
+- decide the minimum context package before coding
+- stop if a recurring pattern already exists in `.aioson/skills/static/` or `.aioson/installed-skills/`
+
+## Atomic execution
+
+Work in small validated steps:
+
+1. declare the next step
+2. write the test first when business logic is new
+3. implement only that slice
+4. verify with the actual command output
+5. commit the working slice
+6. repeat
+
+Unexpected output means stop and investigate. Do not stack speculative fixes.
+
+## Done gate
+
+Before marking any task or feature done:
+
+1. run the verification command
+2. read the complete output
+3. confirm exit code `0`
+4. only then mark done
+
+Update `skeleton-system.md` whenever files are created, deleted, or materially changed.
+
+## `*update-skeleton`
+
+If the user types `*update-skeleton`, rewrite `.aioson/context/skeleton-system.md` to reflect:
+
+- file map status
+- module status
+- key routes
+- update date
+
+## Debugging
+
+If a failing issue survives one attempt:
+
+- stop random fixing
+- load `.aioson/skills/static/debugging-protocol.md`
+- follow the protocol from root-cause analysis onward
+
+After 3 failed attempts on the same issue, question the architecture instead of pushing patches blindly.
+
+## Git worktrees
+
+For SMALL or MEDIUM work, consider `.aioson/skills/static/git-worktrees.md` if the user wants a cleaner parallel workflow.

package/template/.aioson/docs/dev/stack-conventions.md

@@ -0,0 +1,83 @@
+---
+description: "Dev stack conventions — Laravel, UI/UX, design skill, motion, Web3, and any-stack separation rules."
+---
+
+# Dev Stack Conventions
+
+Load this module when the active task touches framework-specific implementation details or user-facing UI.
+
+## Laravel conventions
+
+Respect this layout:
+
+- `app/Actions/`
+- `app/Http/Controllers/`
+- `app/Http/Requests/`
+- `app/Models/`
+- `app/Policies/`
+- `app/Events/` + `app/Listeners/`
+- `app/Jobs/`
+- `app/Livewire/`
+- `resources/views/<resource>/`
+
+Rules:
+
+- controllers orchestrate; they do not own business logic
+- use Form Requests for validation
+- use Policies for authorization
+- use Actions for business logic
+- use queued events/listeners for side effects
+- use Jobs for heavy processing
+- eager-load to avoid N+1 queries
+- implement `down()` in every migration
+
+## UI / UX conventions
+
+- use the project's component library when it exists
+- do not reinvent standard controls
+- mobile-responsive by default
+- always implement loading, empty, and error states
+- always provide visual feedback
+
+## Design skill conventions
+
+Read `design_skill` from `project.context.md` before implementing user-facing UI.
+
+If `design_skill` is set:
+
+- load `.aioson/skills/design/{design_skill}/SKILL.md`
+- load only the references needed for the current screen or component
+- treat it as the only active visual system
+
+If `design_skill` is blank and the task clearly depends on visual direction:
+
+- stop and ask whether to route through `@ux-ui` or proceed explicitly without a registered design skill
+
+## Motion and animation
+
+When the framework is React or Next.js and motion is relevant:
+
+- load `.aioson/skills/static/react-motion-patterns.md`
+- prefer Framer Motion
+- provide `prefers-reduced-motion` fallback
+- do not add heavy motion to admin/CRUD interfaces without a clear reason
+
+## Web3 conventions
+
+For `project_type=dapp`:
+
+- validate inputs on-chain and off-chain
+- never trust client-provided values for sensitive contract calls
+- use typed ABIs
+- test contract interactions before UI wiring
+- document gas implications for user-facing transactions
+
+## Any-stack conventions
+
+For stacks without a dedicated section:
+
+- separate business logic from request handlers
+- validate input at the boundary
+- follow the framework's conventions first
+- check `.aioson/skills/static/`, `.aioson/skills/dynamic/`, and `.aioson/skills/design/` before inventing patterns
+- document deviations in `architecture.md` when needed

package/template/.aioson/docs/deyvin/continuity-recovery.md

@@ -0,0 +1,57 @@
+---
+description: "Deyvin continuity recovery — session start order, resumption rules, brownfield guardrails, SDD bridge, and Git fallback."
+---
+
+# Deyvin Continuity Recovery
+
+Load this module at the start of every `@deyvin` session before touching code.
+
+## Session start order
+
+Build context in this order:
+
+1. If `aioson` is available, run `aioson memory:summary . --last=5` as the fast continuity bootstrap
+2. Read `.aioson/context/project.context.md`
+3. Check `.aioson/rules/`; load universal rules and rules targeted at `deyvin`
+4. Check `.aioson/docs/`; load docs referenced by rules or relevant to the task
+5. If the task is specific, run `aioson context:pack . --agent=deyvin --goal="<task>"` and read the generated pack
+6. Read `.aioson/context/memory-index.md` if present
+7. Read `.aioson/context/spec-current.md` and `.aioson/context/spec-history.md` if present
+8. Read `.aioson/context/spec.md` if present
+9. Read `.aioson/context/features.md` if present; if a feature is in progress, also read `prd-{slug}.md`, `requirements-{slug}.md`, and `spec-{slug}.md`
+10. Read `.aioson/context/skeleton-system.md`, `discovery.md`, and `architecture.md` as needed
+11. When the task matches procedural tags, run `aioson brain:query . --tags=<tags> --min-quality=4`
+12. Inspect recent runtime state in `.aioson/runtime/aios.sqlite` when memory summary is insufficient
+13. Use Git only as a fallback after memory + runtime + rules/docs
+
+If the user asks what happened recently, answer from memory and runtime first. Go to Git only if those sources are insufficient.
+
+## SDD bridge
+
+When continuation depends on spec or execution state:
+
+1. Load `.aioson/skills/process/aioson-spec-driven/SKILL.md`
+2. Then load only `references/deyvin.md`
+3. Follow that router to `maintenance-and-state.md` and `approval-gates.md` as needed
+4. Treat shared SDD references as read-only process sources used by multiple agents
+
+Do not duplicate or rewrite the shared SDD references inside `@deyvin`.
+
+## Brownfield guardrails
+
+If `framework_installed=true` in `project.context.md` and the task depends on existing system behavior:
+
+- prefer `discovery.md` + `spec.md` as the primary memory pair
+- use `skeleton-system.md` or `memory-index.md` first for faster orientation
+- if `discovery.md` is missing but scan artifacts exist, stop and hand off to `@analyst`
+- if broad architecture decisions are required, hand off to `@architect`
+
+## Git fallback
+
+Git is a fallback, not your first source of truth.
+
+Use Git only when:
+
+- AIOSON memory does not explain recent work well enough
+- runtime data is missing or too shallow
+- the user explicitly asks for commit-level history

package/template/.aioson/docs/deyvin/debugging-escalation.md

@@ -0,0 +1,30 @@
+---
+description: "Deyvin debugging and escalation — root-cause protocol, retry limits, and when to hand off."
+---
+
+# Deyvin Debugging and Escalation
+
+Load this module when the request is bug diagnosis, failing test repair, or when the first fix attempt fails.
+
+## Debugging protocol
+
+When a bug or failing test cannot be resolved in one attempt:
+
+1. STOP trying random fixes
+2. Load `.aioson/skills/static/debugging-protocol.md`
+3. Follow the protocol from step 1 (root cause investigation)
+
+## Retry threshold
+
+After 3 failed fix attempts on the same issue:
+
+- question the architecture, not the code
+- decide whether the issue still fits pair mode
+- hand off when structural redesign, broader planning, or formal QA is needed
+
+## Escalation hints
+
+- `@dev` -> larger structured implementation batch once root cause is known
+- `@architect` -> structural or system-level flaw
+- `@analyst` -> missing domain rules or unclear brownfield behavior
+- `@qa` -> formal risk review, regression sweep, or broader test design

package/template/.aioson/docs/deyvin/pair-execution.md

@@ -0,0 +1,44 @@
+---
+description: "Deyvin pair execution — working mode, small-slice loop, memory updates, and implementation governance."
+---
+
+# Deyvin Pair Execution
+
+Load this module when `@deyvin` is about to inspect, explain, fix, or implement a small continuity slice.
+
+## Pair working style
+
+- summarize the latest confirmed context first
+- ask what the user wants to do now if the next step is unclear
+- propose the smallest sensible next step
+- implement, inspect, or fix one small batch at a time
+- validate before moving on
+
+## Implementation governance
+
+Before changing code:
+
+1. load the relevant project rules and docs already discovered during recovery
+2. if `.aioson/design-docs/` contains implementation governance docs, load the relevant ones for the touched area
+3. if a recurring pattern already exists in `.aioson/skills/static/` or `.aioson/installed-skills/`, reuse it instead of improvising
+
+## Small-slice loop
+
+Work in this order:
+
+1. define the immediate slice
+2. inspect the relevant files and runtime context
+3. implement only that slice
+4. verify with the real command or observable behavior
+5. summarize what changed
+6. decide whether the next slice still fits pair mode
+
+If the work stops being small, validated, and reviewable, hand off.
+
+## Memory update rules
+
+- update `spec.md` when the session changes project-wide engineering knowledge, decisions, or current state
+- in feature mode, update `spec-{slug}.md` for feature-specific progress and decisions
+- treat `spec-current.md` and `spec-history.md` as read-optimized derivatives; prefer updating `spec.md` / `spec-{slug}.md`
+- update `skeleton-system.md` when files, routes, or module status change materially
+- if the task becomes broad and context starts to sprawl, suggest or regenerate `context:pack`

package/template/.aioson/docs/deyvin/runtime-handoffs.md

@@ -0,0 +1,36 @@
+---
+description: "Deyvin runtime and handoffs — tracked session behavior, live milestones, direct sessions, and dashboard visibility."
+---
+
+# Deyvin Runtime and Handoffs
+
+Load this module when the session is tracked or when the user asks about runtime visibility.
+
+## Runtime principle
+
+The AIOSON execution gateway records tasks, runs, and events in the project runtime automatically. Focus on accurate step summaries, clean handoffs, and updated memory.
+
+## Live-session behavior
+
+If the user entered through `aioson live:start`, do not open a parallel `runtime:session:*` session. Reuse the live session and emit compact milestones instead:
+
+1. When clearly starting a new user-visible slice, run `aioson runtime:emit . --agent=deyvin --type=task_started --title="<short slice title>"`
+2. After each completed user-visible task, run `aioson runtime:emit . --agent=deyvin --type=task_completed --summary="<what was just completed>" --refs="<files>"`
+3. When the session is linked to a plan and you complete a named step, run `aioson runtime:emit . --agent=deyvin --type=plan_checkpoint --plan-step="<step-id>" --summary="<what was completed>"`
+4. For meaningful progress or risk, run `aioson runtime:emit . --agent=deyvin --type=milestone|correction|block --summary="<what changed>"`
+5. If the request clearly belongs to another AIOSON agent, hand the same live session over with `aioson live:handoff . --agent=deyvin --to=<next-agent> --reason="<why the handoff is needed>"`
+6. If the user wants to monitor the session in another terminal, recommend `aioson live:status . --agent=deyvin --watch=2`
+7. Let the session owner close it with `aioson live:close . --agent=<active-agent> --summary="<one-line summary>"`
+
+## Direct-session behavior
+
+If the user did not enter through `aioson live:start`, keep one direct session open while the pair session is active:
+
+1. At session start or when resuming work, run `aioson runtime:session:start . --agent=deyvin --title="<current focus>"`
+2. After each completed user-visible task, run `aioson runtime:session:log . --agent=deyvin --message="<what was just completed>"`
+3. On handoff, explicit pause, or session end, run `aioson runtime:session:finish . --agent=deyvin --summary="<one-line summary>"`
+4. If the user wants to monitor the session in another terminal, recommend `aioson runtime:session:status . --agent=deyvin --watch=2`
+
+## Dashboard visibility
+
+Plain natural-language agent activation in an external client does not create runtime records by itself. If the user wants tracked dashboard visibility, they must enter through `aioson workflow:next`, `aioson agent:prompt`, or `aioson live:start` first.

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

@@ -0,0 +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.