@jaimevalasek/aioson 1.6.0 → 1.7.0

package/template/.aioson/skills/process/simplify/SKILL.md

@@ -0,0 +1,173 @@
+---
+name: simplify
+description: Three-agent parallel code review for reuse, quality, and efficiency. Run after implementation and tests pass, before commit. Spawns three independent subagents simultaneously — each with a single focus — then aggregates and applies approved fixes.
+activation: |
+  You are now running the /simplify review process. Identify the scope of changed files, then spawn three parallel review agents (reuse, quality, efficiency). Aggregate their findings, filter false positives, present the report, and apply approved fixes.
+---
+
+# Skill: /simplify
+
+> Process skill. Three-agent parallel code review.
+> Run after `@dev` completes a phase and all tests pass. Before committing.
+
+## Workflow position
+
+```
+@dev implements → tests pass → /simplify → review diff → commit
+```
+
+NEVER run /simplify during implementation — only after tests pass.
+
+## Step 1 — Identify scope
+
+List all files changed during the current implementation session.
+
+If the list is larger than 15 files: ask the user to narrow the scope or confirm full review before proceeding.
+
+## Step 2 — Spawn three parallel review agents
+
+Spawn all three simultaneously. Each receives the same file list but different review instructions.
+
+**Critical:** Each agent is stateless — pass a complete, self-contained brief with file paths, review objective, what NOT to do, and output format. Do not reference conversation history.
+
+---
+
+### Agent A — Code Reuse Agent
+
+Brief template:
+```
+You are reviewing the following files for code duplication and reuse opportunities:
+[file list with paths]
+
+Your ONLY task: find duplicated logic, copy-paste patterns, and opportunities to
+extract shared utilities or abstractions that would reduce code.
+
+Rules:
+- Report only real duplications, not stylistic similarities
+- For each finding: exact file + line range + what to extract + where to put it
+- Do NOT comment on naming, performance, security, or architecture
+- Do NOT fix anything — report only
+- Skip findings where extraction would require more code than the duplication saves
+
+Output format per finding:
+### Reuse finding: [short name]
+Files: [file A: lines X-Y, file B: lines X-Y]
+Pattern: [what is duplicated]
+Suggested extraction: [function/class name + target file]
+Confidence: high | medium (skip low-confidence findings)
+```
+
+---
+
+### Agent B — Code Quality Agent
+
+Brief template:
+```
+You are reviewing the following files for code quality issues:
+[file list with paths]
+
+Also read: [CLAUDE.md path], [.aioson/rules/ path — list relevant rules]
+
+Your ONLY task: naming issues, structural problems, violations of explicit project
+conventions, and clear code smells.
+
+Rules:
+- Flag ONLY violations of explicit project rules or well-known anti-patterns
+- Do NOT flag stylistic preferences — only violations of stated conventions
+- If CLAUDE.md and .aioson/rules/ are absent, use only universal anti-patterns
+- For each finding: exact file + line + what the issue is + how to fix it
+- Do NOT comment on performance or duplication
+
+Output format per finding:
+### Quality finding: [short name]
+File: [path:line]
+Issue: [what is wrong]
+Fix: [exact change — 1-3 lines]
+Convention violated: [which rule, or "anti-pattern: [name]"]
+```
+
+**IMPORTANT:** NEVER spawn Agent B without reading CLAUDE.md first (Agent B needs project conventions to be accurate — without them it will hallucinate rules).
+
+---
+
+### Agent C — Efficiency Agent
+
+Brief template:
+```
+You are reviewing the following files for performance and efficiency issues:
+[file list with paths]
+
+Your ONLY task: N+1 queries, unnecessary re-renders, expensive operations in loops,
+missing lazy loading, concurrency issues, unnecessary allocations.
+
+Rules:
+- Report only measurable inefficiencies, not theoretical ones
+- For each finding: exact file + line + what the issue is + cost estimate + fix
+- Do NOT comment on naming or code structure
+
+Output format per finding:
+### Efficiency finding: [short name]
+File: [path:line]
+Issue: [what is inefficient]
+Cost: [why it matters — "O(N) queries per page load", "re-render per keystroke", etc]
+Fix: [exact change]
+```
+
+---
+
+## Step 3 — Aggregate results
+
+Collect all three agents' outputs.
+
+**Deduplication:** if two agents flag the same file+line for different reasons, merge into one finding with both concerns listed.
+
+**False positive filter — silently skip any finding where:**
+- Agent A says "confidence: medium" AND the extraction would add more complexity than it removes
+- Agent B flags a "violation" of a convention that doesn't exist in the project's CLAUDE.md or rules (hallucinated rule)
+- Agent C flags a theoretical inefficiency with no concrete cost estimate
+- The fix would require architectural changes outside the current implementation scope
+
+## Step 4 — Present aggregated report
+
+```
+## /simplify Report — [date]
+
+### Reuse (Agent A): N findings
+- [finding name] — [file:line] — [1-line summary]
+
+### Quality (Agent B): N findings
+- [finding name] — [file:line] — [1-line summary]
+
+### Efficiency (Agent C): N findings
+- [finding name] — [file:line] — [1-line summary]
+
+### Auto-applicable (no review needed): N
+[findings that are low-risk, high-confidence, and contained — list them]
+
+### Requires review: N
+[findings where impact is broader or confidence is medium — list them]
+
+Total: N findings across 3 agents. N auto-applicable, N require review.
+```
+
+Ask the user: "Apply auto-applicable fixes? (Y/n) | Apply all? | Select specific findings?"
+
+## Step 5 — Apply approved fixes
+
+For each approved fix:
+- Apply the exact change described in the finding
+- Do NOT refactor beyond the specific fix
+- Do NOT add comments, docstrings, or type annotations
+- Do NOT rename things not mentioned in the finding
+
+After all fixes: re-run the test suite to confirm no regression.
+If any test breaks: revert only the breaking fix and report to the user.
+
+## Hard constraints
+
+- NEVER fix more than what is described in a specific finding
+- NEVER apply a "requires review" fix without explicit user approval
+- NEVER run /simplify during implementation — only after tests pass
+- NEVER spawn Agent B without reading CLAUDE.md first
+- NEVER report a finding without a concrete file + line reference
+- For MICRO projects: /simplify is optional — suggest but do not require

package/template/.aioson/skills/static/context-budget-guide.md

@@ -0,0 +1,46 @@
+# Context Budget Guide
+
+> Load when you need to measure or manage context window usage.
+
+## Quick measurement heuristic
+
+Since agents cannot directly measure token count, use file-count proxy:
+
+| Files read | Estimated budget | Action |
+|------------|-----------------|--------|
+| 1-3 | Light (< 20%) | Proceed normally |
+| 4-6 | Moderate (20-40%) | Be selective about additional reads |
+| 7-9 | Heavy (40-60%) | Stop reading, start producing |
+| 10+ | Critical (> 60%) | Finish current step, recommend /clear |
+
+## File size estimates
+
+| File type | Typical tokens |
+|-----------|---------------|
+| `project.context.md` | 200-500 |
+| `prd.md` / `prd-{slug}.md` | 500-1500 |
+| `discovery.md` | 1000-3000 |
+| `architecture.md` | 500-1500 |
+| `spec-{slug}.md` | 300-800 |
+| `implementation-plan-{slug}.md` | 800-2000 |
+| `requirements-{slug}.md` | 500-1500 |
+| Agent instruction file | 2000-5000 |
+| Skill file + references | 500-2000 |
+| Source code file | 200-1000 |
+
+## Budget report format
+
+At session end, estimate and write to `project-pulse.md`:
+
+```
+Context budget: {N} files read, ~{estimate}k tokens consumed, budget: {light|moderate|heavy|critical}
+```
+
+## Progressive disclosure strategy
+
+When budget is moderate or higher:
+1. Read file frontmatter/headers first, full content only if needed
+2. Read `project-pulse.md` before any other file (30 lines = minimal cost)
+3. Read `dev-state.md` or `spec-{slug}.md` frontmatter next (context_package tells you what else to load)
+4. Load skills/references only when entering a phase that needs them
+5. Never read all rules, all docs, all skills upfront — scan frontmatter and load selectively

package/template/.aioson/skills/static/harness-sensors.md

@@ -0,0 +1,74 @@
+# Harness Sensors — Post-Action Verification
+
+> Load this when you need to verify that agent actions comply with project constraints.
+> Sensors run AFTER the action, not before (that's what guides/gates do).
+
+## When to run sensors
+
+| Trigger | Sensor | Agent |
+|---------|--------|-------|
+| After commit | Rule compliance check | @dev, @deyvin |
+| After spec update | Drift detection vs requirements | @dev, @analyst |
+| After architecture.md written | Constitution compliance | @architect |
+| After feature closure | AC coverage verification | @qa |
+| After session end | Context budget report | All agents |
+
+## Sensor 1 — Rule compliance check
+
+After every commit, verify:
+1. Read all `.md` files in `.aioson/rules/`
+2. For each rule, check if the committed files violate any stated convention
+3. If violation found: do not revert — log warning and continue
+4. Write violations to `project-pulse.md` under "Blockers" if severity is high
+
+**Implementation:** This sensor is agent-internal (instruction-based), not a CLI hook.
+The agent instruction says: "after committing, re-read the rules and verify your commit complies."
+
+## Sensor 2 — Spec drift check
+
+After updating `spec-{slug}.md`:
+1. Compare `requirements-{slug}.md` AC list with `spec-{slug}.md` "Edge cases handled" section
+2. If ACs exist in requirements that are not mentioned in spec: flag as potential drift
+3. Write flagged items to `pending_review` in spec frontmatter
+
+## Sensor 3 — Constitution compliance (architecture)
+
+After writing `architecture.md`:
+1. Read `constitution.md`
+2. For each article, verify:
+   - Article I: Is there a spec artifact that preceded this architecture?
+   - Article II: Is the architecture depth proportional to classification?
+   - Article VI: Does the architecture introduce unnecessary layers?
+3. Self-report: add `## Constitution check` section at end of `architecture.md`
+
+## Sensor 4 — AC coverage verification
+
+After @qa writes its report:
+1. Count ACs with status "Covered" vs total ACs
+2. Count adversarial probes executed vs minimum required (1)
+3. If coverage < 80% or probes < 1: VERDICT cannot be PASS
+
+## Sensor 5 — Context budget report
+
+At session end, before writing project-pulse.md:
+1. Estimate how many files were read during the session
+2. If > 8 large files: flag context budget concern
+3. Write to project-pulse.md: "Last session context: {N} files read, estimated {light|moderate|heavy}"
+
+## How sensors differ from gates
+
+| | Gates (guides) | Sensors (feedback) |
+|---|---|---|
+| When | Before action | After action |
+| Blocking | Yes (MEDIUM) | No — advisory |
+| Who triggers | Agent checks before proceeding | Agent checks after completing |
+| Response | Stop + ask user | Log + warn + continue |
+| Example | Gate A before @architect | Rule compliance after commit |
+
+## Progressive adoption
+
+1. **Phase 1 (current):** All sensors are agent-internal instructions. No CLI hooks.
+2. **Phase 2 (future):** Move high-value sensors to `hooks-emit.js` for automated execution.
+3. **Phase 3 (future):** Add configurable sensor severity (warn vs block) in project config.
+
+Sensors should be lightweight — a sensor that takes longer than the action it monitors is worse than no sensor.

package/template/.aioson/skills/static/multi-agent-patterns.md

@@ -0,0 +1,43 @@
+# Multi-Agent Patterns for MEDIUM Projects
+
+> Load when orchestrating a MEDIUM project with 3+ features or 5+ phases.
+
+## Pattern: Planner / Generator / Evaluator (PGE)
+
+### Roles
+
+| Role | AIOSON Agents | Responsibility |
+|------|--------------|----------------|
+| Planner | @product → @sheldon → @analyst → @architect | Produce spec pack: PRD + requirements + architecture + implementation plan |
+| Generator | @dev, @deyvin | Implement against the spec pack, one phase at a time |
+| Evaluator | @qa, @tester | Verify implementation against spec, report findings |
+
+### Feedback loops
+
+```
+Planner ──spec-pack──→ Generator ──code──→ Evaluator
+    ^                                          |
+    └──────── findings + drift report ─────────┘
+```
+
+When Evaluator finds issues:
+1. **Minor (Low/Medium findings):** Generator fixes in next phase
+2. **Major (Critical/High findings):** Generator stops, Evaluator reports to user
+3. **Spec drift detected:** Route back to Planner (@analyst or @sheldon) for spec update
+4. **Architecture issue:** Route to @architect for design revision
+
+### Session isolation
+
+Each role should run in a fresh context window:
+- Planner sessions: produce artifacts, then /clear
+- Generator sessions: read spec pack + implement, then /clear
+- Evaluator sessions: read code + spec + verify, then /clear
+
+Cross-role communication happens through artifacts on disk, not conversation history.
+
+### When NOT to use PGE
+
+- MICRO projects: skip Planner (except @product), go direct to Generator
+- SMALL projects: compressed PGE — Planner is 1-2 sessions, not 4
+- Bug fixes: Generator only, Evaluator optional
+- Exploration: not PGE at all — use @deyvin in pair mode

package/template/.aioson/skills/static/react-motion-patterns.md

@@ -575,3 +575,25 @@ Add to `app/layout.tsx`:
 - Tilt and 3D effects must be disabled on touch devices (`hover: none` media query)
 - Do not install Framer Motion just for one CSS animation — use plain CSS keyframes instead
 - Keep decorative elements (`orbs`, `mesh`, `marquee`) `aria-hidden="true"` and `pointer-events: none`
+
+## When CSS is not enough — Three.js (on-demand)
+
+The patterns above cover 95% of animation needs. When the user explicitly requests
+particle systems, WebGL scenes, holographic effects, or interactive 3D objects:
+
+Load `.aioson/skills/static/threejs-patterns.md` instead.
+
+**CSS 3D Transforms vs Three.js/WebGL:**
+
+| Technique | CSS 3D Transforms (above) | Three.js (threejs-patterns.md) |
+|---|---|---|
+| Card tilt | `perspective(700px) rotateY/X` | Not needed — CSS handles it |
+| Mesh background | `@keyframes meshDrift` on gradient | Particle aurora backdrop (3D points) |
+| Floating orbs | CSS with `border-radius: 50%` blur | Not needed — CSS is cleaner |
+| 3D object showcase | Not possible | TorusKnot/Icosahedron with OrbitControls |
+| Holographic effect | Not possible | MeshPhysicalMaterial with iridescence + bloom |
+| Scroll-driven 3D | Not possible | Camera moves through 3D scene on scroll |
+| Particle physics | Not possible | 3,000–8,000 points with drift behavior |
+
+Three.js is CDN-only (no npm install required) for all patterns in threejs-patterns.md.
+It is always additive — the design skill tokens (colors, typography, spacing) continue to govern the HTML/CSS layer.

package/template/.aioson/skills/static/static-html-patterns/checklists.md

@@ -0,0 +1,43 @@
+# Checklists — Section Map & Pre-delivery
+
+> Load when planning which sections to include or doing final QA before delivery.
+
+---
+
+## 12. Full Section Checklist (AI / SaaS Landing Page)
+
+For complete AI agency or SaaS landing pages, include these sections in order:
+
+| # | Section | Purpose |
+|---|---|---|
+| 1 | Header (sticky) | Logo + nav + CTA button |
+| 2 | Hero | Headline + sub + 2 CTAs + social proof |
+| 3 | Logos bar | "Trusted by" brand names |
+| 4 | Features grid | 3–6 cards with icon + title + description |
+| 5 | How it works | 3 numbered steps with image alternation |
+| 6 | Services | Cards with deeper service descriptions |
+| 7 | Stats / Numbers | Animated counters (clients, projects, uptime) |
+| 8 | Case studies | Portfolio cards with hover image reveal |
+| 9 | Testimonials | Swiper slider with quotes + avatars |
+| 10 | Pricing | 3-tier cards with "Most popular" badge |
+| 11 | FAQ | Accordion with open/close animation |
+| 12 | Final CTA | Single button, urgency, no distractions |
+| 13 | Footer | Dense: links + social + newsletter + copyright |
+
+**For MICRO landing pages (single page, simple product):** sections 1, 2, 4, 9, 12, 13.
+
+---
+
+## 13. Pre-delivery Checklist
+
+- [ ] Mobile menu opens/closes, body scroll locked when open
+- [ ] Sliders have correct breakpoints and accessible buttons
+- [ ] GSAP scroll animations work on mobile (use `start: 'top 85%'` for shorter viewports)
+- [ ] Hero image loads eagerly with `fetchpriority="high"`, all others `loading="lazy"`
+- [ ] No layout shift (CLS): img/video elements have explicit width+height
+- [ ] `prefers-reduced-motion: reduce` disables all animations
+- [ ] All interactive elements reachable by keyboard
+- [ ] Color contrast ≥ 4.5:1 checked
+- [ ] `<title>` and `<meta description>` are real content (not placeholders)
+- [ ] Open Graph meta tags present (`og:title`, `og:description`, `og:image`)
+- [ ] No placeholder text remains anywhere in the HTML