@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/context/user-profile.md

@@ -1,42 +1,42 @@
----
-created: {ISO-date}
-last_updated: {ISO-date}
-questionnaire_completed: false
----
-
-# Developer Profile
-
-## Communication style
-<!-- direto | equilibrado | explicativo -->
-preference: equilibrado
-
-## Decision style
-<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
-preference: depende-do-contexto
-
-## Tech philosophy
-<!-- explícito | convencional | pragmatico -->
-preference: pragmatico
-
-## Autonomy preference
-<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
-preference: aprovacao-em-gates
-
-## Feedback style
-<!-- critica-direta | colaborativo | neutro -->
-preference: neutro
-
-## Scope tolerance
-<!-- strict | sugestoes-ok | flexible -->
-preference: sugestoes-ok
-
-## Detail level
-<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
-preference: contexto-quando-relevante
-
-## Risk tolerance
-<!-- conservador | equilibrado | arrojado -->
-preference: equilibrado
-
-## Notes
-<!-- observações específicas do usuário sobre preferências -->
+---
+created: {ISO-date}
+last_updated: {ISO-date}
+questionnaire_completed: false
+---
+
+# Developer Profile
+
+## Communication style
+<!-- direto | equilibrado | explicativo -->
+preference: equilibrado
+
+## Decision style
+<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
+preference: depende-do-contexto
+
+## Tech philosophy
+<!-- explícito | convencional | pragmatico -->
+preference: pragmatico
+
+## Autonomy preference
+<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
+preference: aprovacao-em-gates
+
+## Feedback style
+<!-- critica-direta | colaborativo | neutro -->
+preference: neutro
+
+## Scope tolerance
+<!-- strict | sugestoes-ok | flexible -->
+preference: sugestoes-ok
+
+## Detail level
+<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
+preference: contexto-quando-relevante
+
+## Risk tolerance
+<!-- conservador | equilibrado | arrojado -->
+preference: equilibrado
+
+## Notes
+<!-- observações específicas do usuário sobre preferências -->

package/template/.aioson/design-docs/code-reuse.md

@@ -1,48 +1,48 @@
----
-description: "DRY principles, reuse hierarchy, and composition patterns"
-scope: "governance"
-agents: []
----
-
-# Code Reuse — Governance Rules
-
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
-
-## Before creating any new file
-
-Always verify in this order:
-
-1. Does a shared utility already solve this? (check `utils.js`, `utils/`, `helpers/`, `shared/`)
-2. Does a domain module in `lib/`, `services/`, or `lib/` already own this responsibility?
-3. Does a similar existing file already do something close enough to extend?
-
-Create a new file only if none of the above applies.
-
-## Reuse hierarchy
-
-1. **Existing shared utility** — call it, do not reimplement
-2. **Domain module** — if the logic is domain-specific, extend the right module
-3. **Inline helper** — acceptable if single use and under ~50 lines
-4. **New file** — only when no existing location is appropriate
-
-## Composition over duplication
-
-- Never copy-paste code blocks between files — extract to a named function instead
-- If two modules import the same sequence of dependencies, consider a factory or initializer
-- If the same validation logic appears in 3+ places, it belongs in a shared validator
-- If two commands share a pattern for reading + transforming + writing, extract the pipeline
-
-## DRY with pragmatism
-
-DRY applies to **logic**, not to **structure**:
-
-- Two functions that look similar but serve different domain concepts should stay separate
-- Merging them to reduce lines often creates the wrong abstraction
-- Duplicating a string or constant is worse than a duplicate variable — always use named constants
-- Small, isolated duplication is sometimes better than a shared dependency that couples unrelated modules
-
-## When NOT to reuse
-
-- When the shared abstraction introduces coupling between unrelated modules
-- When the reused code would need flags or conditionals to serve a new caller — that signals divergence, not reuse
-- When the only shared thing is syntax, not semantics
+---
+description: "DRY principles, reuse hierarchy, and composition patterns"
+scope: "governance"
+agents: []
+---
+
+# Code Reuse — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Before creating any new file
+
+Always verify in this order:
+
+1. Does a shared utility already solve this? (check `utils.js`, `utils/`, `helpers/`, `shared/`)
+2. Does a domain module in `lib/`, `services/`, or `lib/` already own this responsibility?
+3. Does a similar existing file already do something close enough to extend?
+
+Create a new file only if none of the above applies.
+
+## Reuse hierarchy
+
+1. **Existing shared utility** — call it, do not reimplement
+2. **Domain module** — if the logic is domain-specific, extend the right module
+3. **Inline helper** — acceptable if single use and under ~50 lines
+4. **New file** — only when no existing location is appropriate
+
+## Composition over duplication
+
+- Never copy-paste code blocks between files — extract to a named function instead
+- If two modules import the same sequence of dependencies, consider a factory or initializer
+- If the same validation logic appears in 3+ places, it belongs in a shared validator
+- If two commands share a pattern for reading + transforming + writing, extract the pipeline
+
+## DRY with pragmatism
+
+DRY applies to **logic**, not to **structure**:
+
+- Two functions that look similar but serve different domain concepts should stay separate
+- Merging them to reduce lines often creates the wrong abstraction
+- Duplicating a string or constant is worse than a duplicate variable — always use named constants
+- Small, isolated duplication is sometimes better than a shared dependency that couples unrelated modules
+
+## When NOT to reuse
+
+- When the shared abstraction introduces coupling between unrelated modules
+- When the reused code would need flags or conditionals to serve a new caller — that signals divergence, not reuse
+- When the only shared thing is syntax, not semantics

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

@@ -1,47 +1,47 @@
----
-description: "When and how to extract components, modules, and abstractions"
-scope: "governance"
-agents: []
----
-
-# Componentization — Governance Rules
-
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
-
-## When to extract
-
-Extract a component, module, or function when ANY of these is true:
-
-1. **Duplication** — the same logic appears in 2 or more different places
-2. **Size** — a file is approaching 300 lines of pure logic (excluding comments and blank lines)
-3. **Testability** — the piece of logic can be tested in isolation from the rest
-4. **Description** — the responsibility can be stated in one short, specific sentence
-
-## When to keep inline
-
-Keep logic inline when ALL of these are true:
-
-- Used in exactly one place
-- Under ~50 lines
-- Extracting it would create a file with a single trivial function
-- No second confirmed use case exists
-
-## Single responsibility
-
-- One file = one primary responsibility
-- Supporting helper functions for that primary responsibility may coexist in the same file
-- Helper functions used in 2+ files → move to a shared utility or dedicated module
-
-## Avoid premature abstraction
-
-- Do not create abstractions for hypothetical future requirements
-- Three similar-but-not-identical code blocks is not always a reason to abstract — wait for the pattern to stabilize
-- An abstraction that is harder to understand than the original code is a liability, not an asset
-- The right abstraction reveals intent. If the name cannot describe what it does in 3 words or fewer, reconsider.
-
-## Signals that an abstraction is wrong
-
-- The function needs many flags or mode switches to handle different callers
-- The caller has to know internal details to use it correctly
-- Tests for the abstraction are harder to read than tests for the original code
-- Removing the abstraction and inlining the logic would make the code clearer
+---
+description: "When and how to extract components, modules, and abstractions"
+scope: "governance"
+agents: []
+---
+
+# Componentization — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## When to extract
+
+Extract a component, module, or function when ANY of these is true:
+
+1. **Duplication** — the same logic appears in 2 or more different places
+2. **Size** — a file is approaching 300 lines of pure logic (excluding comments and blank lines)
+3. **Testability** — the piece of logic can be tested in isolation from the rest
+4. **Description** — the responsibility can be stated in one short, specific sentence
+
+## When to keep inline
+
+Keep logic inline when ALL of these are true:
+
+- Used in exactly one place
+- Under ~50 lines
+- Extracting it would create a file with a single trivial function
+- No second confirmed use case exists
+
+## Single responsibility
+
+- One file = one primary responsibility
+- Supporting helper functions for that primary responsibility may coexist in the same file
+- Helper functions used in 2+ files → move to a shared utility or dedicated module
+
+## Avoid premature abstraction
+
+- Do not create abstractions for hypothetical future requirements
+- Three similar-but-not-identical code blocks is not always a reason to abstract — wait for the pattern to stabilize
+- An abstraction that is harder to understand than the original code is a liability, not an asset
+- The right abstraction reveals intent. If the name cannot describe what it does in 3 words or fewer, reconsider.
+
+## Signals that an abstraction is wrong
+
+- The function needs many flags or mode switches to handle different callers
+- The caller has to know internal details to use it correctly
+- Tests for the abstraction are harder to read than tests for the original code
+- Removing the abstraction and inlining the logic would make the code clearer

package/template/.aioson/design-docs/file-size.md

@@ -1,52 +1,52 @@
----
-description: "File size guidelines, alert thresholds, and split strategies"
-scope: "governance"
-agents: []
----
-
-# File Size — Governance Rules
-
-> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
-
-## Thresholds
-
-| Lines | Status | Action |
-|-------|--------|--------|
-| < 300 | Ideal | Continue normally |
-| 300–500 | Acceptable | Monitor growth; do not split preemptively |
-| > 500 | Alert | Propose split before writing more code |
-
-Lines are counted as pure logic — comments, blank lines, and closing braces do not count toward the threshold.
-
-## Alert protocol
-
-When estimating that a resulting file will exceed 500 lines:
-
-1. Emit the alert with the estimated line count and file path
-2. List 2–3 concrete extraction alternatives with real file paths
-3. `@dev`: wait for user confirmation before proceeding
-4. `@deyvin` pair mode: present alternatives and continue after 1 turn with no response
-
-The alert is never blocking — it is a pause to think, not an impediment.
-
-## Common split strategies
-
-| Situation | Split approach |
-|-----------|---------------|
-| Large command / controller | Extract business logic to a `service/` or `lib/` module |
-| Validation logic growing | Extract to `validate-{domain}.js` / `{domain}_validator.py` |
-| Formatting / serialization | Extract to `format-{domain}.js` or a dedicated serializer |
-| Mixed read/write concerns | Separate into a reader and a writer module |
-| Route file growing | Group into feature sub-routers |
-| Large test file | Split by domain or by test type (unit / integration / e2e) |
-| Large React component | Extract sub-components and move logic to a custom hook |
-| Large class with many methods | Extract related method groups into collaborator classes |
-
-## Exceptions
-
-These file types are exempt from the size guideline:
-
-- Internationalization / locale files (`messages.json`, `en.yml`, `pt-BR.ts`)
-- Test fixtures and factories
-- Auto-generated files (migrations with timestamps, GraphQL schemas, OpenAPI specs)
-- Configuration files with many entries (`routes.php`, `config/app.ts`, `webpack.config.js`)
+---
+description: "File size guidelines, alert thresholds, and split strategies"
+scope: "governance"
+agents: []
+---
+
+# File Size — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Thresholds
+
+| Lines | Status | Action |
+|-------|--------|--------|
+| < 300 | Ideal | Continue normally |
+| 300–500 | Acceptable | Monitor growth; do not split preemptively |
+| > 500 | Alert | Propose split before writing more code |
+
+Lines are counted as pure logic — comments, blank lines, and closing braces do not count toward the threshold.
+
+## Alert protocol
+
+When estimating that a resulting file will exceed 500 lines:
+
+1. Emit the alert with the estimated line count and file path
+2. List 2–3 concrete extraction alternatives with real file paths
+3. `@dev`: wait for user confirmation before proceeding
+4. `@deyvin` pair mode: present alternatives and continue after 1 turn with no response
+
+The alert is never blocking — it is a pause to think, not an impediment.
+
+## Common split strategies
+
+| Situation | Split approach |
+|-----------|---------------|
+| Large command / controller | Extract business logic to a `service/` or `lib/` module |
+| Validation logic growing | Extract to `validate-{domain}.js` / `{domain}_validator.py` |
+| Formatting / serialization | Extract to `format-{domain}.js` or a dedicated serializer |
+| Mixed read/write concerns | Separate into a reader and a writer module |
+| Route file growing | Group into feature sub-routers |
+| Large test file | Split by domain or by test type (unit / integration / e2e) |
+| Large React component | Extract sub-components and move logic to a custom hook |
+| Large class with many methods | Extract related method groups into collaborator classes |
+
+## Exceptions
+
+These file types are exempt from the size guideline:
+
+- Internationalization / locale files (`messages.json`, `en.yml`, `pt-BR.ts`)
+- Test fixtures and factories
+- Auto-generated files (migrations with timestamps, GraphQL schemas, OpenAPI specs)
+- Configuration files with many entries (`routes.php`, `config/app.ts`, `webpack.config.js`)

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

@@ -1,51 +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
+---
+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

@@ -1,54 +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`
+---
+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`