@jaimevalasek/aioson 1.8.0 → 1.9.1

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

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

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

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

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

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