@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/skills/static/ui-ux-modern.md

@@ -1,76 +1,76 @@
-# Modern UI/UX Guidelines
-
-## Goal
-Ship interfaces that feel intentional, modern, and production-ready without over-designing beyond project scope.
-
-## Core-Lite balance
-- Follow AIOS Core quality discipline (explicit decisions, consistency, UX clarity).
-- Keep AIOSON delivery lean (small scope, direct implementation guidance, low artifact overhead).
-
-## Core principles
-- Clarity before decoration: users should immediately understand the primary action.
-- One visual direction per product area: typography, color, and component density must be consistent.
-- Reuse before reinventing: prioritize existing stack UI libraries and primitives.
-- Accessibility is default, not optional.
-
-## Layout and hierarchy
-- Define a spacing scale (for example 4/8/12/16/24/32) and keep it consistent.
-- Keep a clear reading order:
-  1. Page intent
-  2. Primary action
-  3. Supporting data
-- Prefer shallow nesting in cards and panels to reduce cognitive load.
-
-## Typography and color
-- Use a predictable type scale with clear role mapping:
-  - page title
-  - section title
-  - body
-  - helper/meta text
-- Keep contrast high for critical text and controls.
-- Use semantic color roles (primary/success/warning/danger/info) instead of arbitrary one-off colors.
-
-## Component quality checklist
-For every major component, define:
-- default state
-- hover/focus/active/disabled states
-- loading skeleton/spinner behavior
-- empty state
-- error state with recovery action
-- success confirmation when relevant
-
-## Forms and validation
-- Put labels outside placeholders (placeholders are hints, not labels).
-- Validate as early as possible without being noisy.
-- Show inline field errors and one global summary for multi-field failures.
-- Disable destructive actions while submitting and show progress feedback.
-
-## Responsive behavior
-- Design mobile-first, then scale up.
-- Ensure key actions are reachable with one hand on mobile.
-- Avoid dense tables on small screens; use stacked cards or summary rows.
-
-## Accessibility baseline
-- Semantic HTML and proper landmarks.
-- Full keyboard navigation and visible focus states.
-- Click/tap targets large enough for touch.
-- Meaning not conveyed by color alone.
-
-## Motion and feedback
-- Use motion to clarify transitions, not as decoration.
-- Keep transitions short and consistent.
-- Avoid blocking animations for critical workflows.
-- For landing pages, sales pages, or event pages: load `landing-page-forge` skill — it covers GSAP/AnimeJS patterns, horizontal scroll, magnetic mouse, and the full performance + tracking checklist.
-
-## Stack-specific guidance
-- Laravel + TALL: prefer Livewire + Alpine patterns and existing Blade components.
-- Filament admin: prefer Resources and built-in actions before custom UI.
-- Flux UI: use Flux primitives first and keep custom wrappers minimal.
-- Next.js/React: keep component boundaries clean and avoid unnecessary client state.
-
-## Handoff quality
-When passing to implementation:
-- provide component mapping to real library components
-- include state matrix (loading/empty/error/success/permission)
-- include responsive and accessibility notes
-- keep the spec concise enough for direct coding
+# Modern UI/UX Guidelines
+
+## Goal
+Ship interfaces that feel intentional, modern, and production-ready without over-designing beyond project scope.
+
+## Core-Lite balance
+- Follow AIOS Core quality discipline (explicit decisions, consistency, UX clarity).
+- Keep AIOSON delivery lean (small scope, direct implementation guidance, low artifact overhead).
+
+## Core principles
+- Clarity before decoration: users should immediately understand the primary action.
+- One visual direction per product area: typography, color, and component density must be consistent.
+- Reuse before reinventing: prioritize existing stack UI libraries and primitives.
+- Accessibility is default, not optional.
+
+## Layout and hierarchy
+- Define a spacing scale (for example 4/8/12/16/24/32) and keep it consistent.
+- Keep a clear reading order:
+  1. Page intent
+  2. Primary action
+  3. Supporting data
+- Prefer shallow nesting in cards and panels to reduce cognitive load.
+
+## Typography and color
+- Use a predictable type scale with clear role mapping:
+  - page title
+  - section title
+  - body
+  - helper/meta text
+- Keep contrast high for critical text and controls.
+- Use semantic color roles (primary/success/warning/danger/info) instead of arbitrary one-off colors.
+
+## Component quality checklist
+For every major component, define:
+- default state
+- hover/focus/active/disabled states
+- loading skeleton/spinner behavior
+- empty state
+- error state with recovery action
+- success confirmation when relevant
+
+## Forms and validation
+- Put labels outside placeholders (placeholders are hints, not labels).
+- Validate as early as possible without being noisy.
+- Show inline field errors and one global summary for multi-field failures.
+- Disable destructive actions while submitting and show progress feedback.
+
+## Responsive behavior
+- Design mobile-first, then scale up.
+- Ensure key actions are reachable with one hand on mobile.
+- Avoid dense tables on small screens; use stacked cards or summary rows.
+
+## Accessibility baseline
+- Semantic HTML and proper landmarks.
+- Full keyboard navigation and visible focus states.
+- Click/tap targets large enough for touch.
+- Meaning not conveyed by color alone.
+
+## Motion and feedback
+- Use motion to clarify transitions, not as decoration.
+- Keep transitions short and consistent.
+- Avoid blocking animations for critical workflows.
+- For landing pages, sales pages, or event pages: load `landing-page-forge` skill — it covers GSAP/AnimeJS patterns, horizontal scroll, magnetic mouse, and the full performance + tracking checklist.
+
+## Stack-specific guidance
+- Laravel + TALL: prefer Livewire + Alpine patterns and existing Blade components.
+- Filament admin: prefer Resources and built-in actions before custom UI.
+- Flux UI: use Flux primitives first and keep custom wrappers minimal.
+- Next.js/React: keep component boundaries clean and avoid unnecessary client state.
+
+## Handoff quality
+When passing to implementation:
+- provide component mapping to real library components
+- include state matrix (loading/empty/error/success/permission)
+- include responsive and accessibility notes
+- keep the spec concise enough for direct coding

package/template/.aioson/skills/static/web-research-cache.md

@@ -1,112 +1,115 @@
-# Skill: Web Research Cache
-
-> Load this file when you are about to run a web search.
-> Check the cache first. Save results after. Never search twice for the same thing.
-
-## Cache location
-
-```
-researchs/                        ← project root (alongside plans/, prds/)
-└── {slug}/
-    ├── summary.md                ← frontmatter + consolidated findings
-    └── files/
-        └── {source-slug}.md     ← raw content from each consulted URL
-```
-
-The `slug` identifies the topic searched (e.g., `stripe-api-2026`, `nextjs-app-router`, `jwt-vs-session`). Use kebab-case, include the year when the decision may age.
-
-## Step 1 — Check cache before searching
-
-Before running any WebSearch:
-
-1. Derive the slug from the topic you are about to search
-2. Check if `researchs/{slug}/summary.md` exists
-3. Read `searched_at` from its frontmatter
-4. If `searched_at` is within the last **7 days** → use the cached result, do not search again
-5. If older than 7 days or missing → proceed to search
-
-## Step 2 — Run the search
-
-- Formulate the query including the **current year** so results are fresh
-- Maximum **4 queries per session** — focus on the decisions with highest risk of being outdated
-- If WebSearch fails for a query: record the error in `summary.md` and continue — do not block
-
-## Step 3 — Save results
-
-After searching, always save before using the results:
-
-**`researchs/{slug}/summary.md`:**
-```markdown
----
-searched_at: {ISO-date}
-agent: {agent-name}
-prd: {prd-slug or null}
-query: "{query used}"
-verdict: confirmed | has-alternatives | outdated | deprecated
----
-
-# Research: {topic title}
-
-## Verdict
-[One line with the verdict and justification]
-
-## Findings
-[Consolidated summary — maximum 5 bullets]
-
-## Sources consulted
-- [URL] — [what it contributed]
-```
-
-**`researchs/{slug}/files/{source-slug}.md`:** raw content from each URL consulted.
-
-## Step 4 — Surface only what is actionable
-
-Show the user **only** findings with verdict `has-alternatives`, `outdated`, or `deprecated`:
-
-```
-🔍 Web Intelligence — {current date}
-
-**[decision or technology]** — {verdict}
-→ {finding in 1–2 lines}
-→ Alternative: {recommended alternative, if any}
-→ Source: [URL]
-
-Want to incorporate this update?
-```
-
-If all findings are `confirmed`:
-> "✓ Decisions validated against recent research. No updates needed."
-
-`confirmed` findings are **never shown** — they are noise.
-
-## Verdicts
-
-| Verdict | Meaning |
-|---|---|
-| `confirmed` | Still the best choice — no action needed |
-| `has-alternatives` | Valid but better options now exist |
-| `outdated` | Superseded by a newer approach |
-| `deprecated` | Officially discontinued or abandoned |
-
-## Who reads and who writes
-
-| Agent | Reads cache | Writes cache |
-|---|---|---|
-| @sheldon | ✅ | ✅ — primary writer for PRD technical decisions |
-| @analyst | ✅ | ✅ — technology and integration validation |
-| @architect | ✅ | ✅ — infrastructure and library trade-offs |
-| @dev | ✅ | ✅ — library docs and implementation patterns |
-| @product | ✅ | ✅ — market and domain context |
-| @deyvin | ✅ | ✅ — continuity session lookups |
-| @orache | ✅ (read only) | ❌ — domain intelligence goes to `squad-searches/`, not here |
-
-**Why @orache does not write here:** `researchs/` uses a verdict schema (`confirmed | has-alternatives | outdated | deprecated`) designed for technical decision validation. Domain investigation findings (frameworks, anti-patterns, vocabulary) do not fit this schema and would pollute the cache with non-actionable data for other agents.
-
-## Rules
-
-- **Never search without saving** — unsaved results are lost after the session
-- **Never block on search failure** — record the error and continue
-- **Never show `confirmed` findings** — they add noise without value
-- **Never modify the PRD/plan without user confirmation** — surface findings, let the user decide
-- **Cache is shared across all agents** — if another agent already searched the same topic this week, use their result
-- The user decides whether to act on findings. Agents surface, humans decide.
+# Skill: Web Research Cache
+
+> Load this file when you are about to run a web search.
+> Check the cache first. Save results after. Never search twice for the same thing.
+> Treat `researchs/` as a temporary shared evidence layer for current and nearby sessions.
+
+## Cache location
+
+```
+researchs/                        ← project root (alongside plans/, prds/)
+└── {slug}/
+    ├── summary.md                ← frontmatter + consolidated findings
+    └── files/
+        └── {source-slug}.md     ← raw content from each consulted URL
+```
+
+The `slug` identifies the topic searched (e.g., `stripe-api-2026`, `nextjs-app-router`, `jwt-vs-session`). Use kebab-case, include the year when the decision may age.
+
+## Step 1 — Check cache before searching
+
+Before running any WebSearch:
+
+1. Derive the slug from the topic you are about to search
+2. Check if `researchs/{slug}/summary.md` exists
+3. Read `searched_at` from its frontmatter
+4. If `searched_at` is within the last **7 days** → use the cached result, do not search again
+5. If older than 7 days or missing → proceed to search
+
+## Step 2 — Run the search
+
+- Formulate the query including the **current year** so results are fresh
+- Maximum **4 queries per session** — focus on the decisions with highest risk of being outdated
+- If WebSearch fails for a query: record the error in `summary.md` and continue — do not block
+
+## Step 3 — Save results
+
+After searching, always save before using the results:
+
+**`researchs/{slug}/summary.md`:**
+```markdown
+---
+searched_at: {ISO-date}
+agent: {agent-name}
+prd: {prd-slug or null}
+query: "{query used}"
+verdict: confirmed | has-alternatives | outdated | deprecated
+---
+
+# Research: {topic title}
+
+## Verdict
+[One line with the verdict and justification]
+
+## Findings
+[Consolidated summary — maximum 5 bullets]
+
+## Sources consulted
+- [URL] — [what it contributed]
+```
+
+**`researchs/{slug}/files/{source-slug}.md`:** raw content from each URL consulted.
+
+## Step 4 — Surface only what is actionable
+
+Show the user **only** findings with verdict `has-alternatives`, `outdated`, or `deprecated`:
+
+```
+🔍 Web Intelligence — {current date}
+
+**[decision or technology]** — {verdict}
+→ {finding in 1–2 lines}
+→ Alternative: {recommended alternative, if any}
+→ Source: [URL]
+
+Want to incorporate this update?
+```
+
+If all findings are `confirmed`:
+> "✓ Decisions validated against recent research. No updates needed."
+
+`confirmed` findings are **never shown** — they are noise.
+
+## Verdicts
+
+| Verdict | Meaning |
+|---|---|
+| `confirmed` | Still the best choice — no action needed |
+| `has-alternatives` | Valid but better options now exist |
+| `outdated` | Superseded by a newer approach |
+| `deprecated` | Officially discontinued or abandoned |
+
+## Who reads and who writes
+
+| Agent | Reads cache | Writes cache |
+|---|---|---|
+| @sheldon | ✅ | ✅ — primary writer for PRD technical decisions |
+| @squad | ✅ | ✅ — lightweight domain/pattern scouting for squad packages |
+| @analyst | ✅ | ✅ — technology and integration validation |
+| @architect | ✅ | ✅ — infrastructure and library trade-offs |
+| @dev | ✅ | ✅ — library docs and implementation patterns |
+| @product | ✅ | ✅ — market and domain context |
+| @deyvin | ✅ | ✅ — continuity session lookups |
+| @orache | ✅ (read only) | ❌ — domain intelligence goes to `squad-searches/`, not here |
+
+**Why @orache does not write here:** `researchs/` uses a verdict schema (`confirmed | has-alternatives | outdated | deprecated`) designed for technical decision validation. Domain investigation findings (frameworks, anti-patterns, vocabulary) do not fit this schema and would pollute the cache with non-actionable data for other agents.
+
+## Rules
+
+- **Never search without saving** — unsaved results are lost after the session
+- **Never block on search failure** — record the error and continue
+- **Never show `confirmed` findings** — they add noise without value
+- **Never modify the PRD/plan without user confirmation** — surface findings, let the user decide
+- **Cache is shared across all agents** — if another agent already searched the same topic this week, use their result
+- `@product`, `@sheldon`, and `@squad` should derive short keyword phrases from the active task and scout the cache before finalizing substantial output
+- The user decides whether to act on findings. Agents surface, humans decide.