@jaimevalasek/aioson 1.6.0 → 1.7.2

package/template/.aioson/skills/process/design-hybrid-forge/references/output-contract.md

@@ -234,6 +234,21 @@ Must show:
 - Hybrid accent gradient on hero heading or CTA
 - AIOSON badge
 
+### Three.js modifier preview requirements
+
+When `threejs-spatial` is a modifier, both preview HTMLs must include a Three.js scene as the background layer. The preview must demonstrate:
+
+- Three.js canvas is `position: fixed; inset: 0; z-index: 0` — behind all HTML content
+- Canvas is `alpha: true` — CSS aurora gradient shows through
+- Particle count: ≤ 6,000 on desktop, ≤ 1,500 on mobile (use `navigator.userAgent` check)
+- WebGL support check with CSS fallback: `if (!canvas.getContext('webgl')) { canvas.style.display = "none"; document.body.style.background = "linear-gradient(...)"; }`
+- `prefers-reduced-motion` check: disables canvas, shows static aurora CSS background
+- Accent colors from the hybrid's accent gradient flow into Three.js point light colors and particle palette
+- `requestAnimationFrame` render loop with `IntersectionObserver` to pause when off-screen
+- Three.js CDN loaded via importmap: `<script type="importmap">{"imports":{"three":"https://unpkg.com/three@0.160.0/build/three.module.js"}}</script>`
+
+---
+
 ### Technical requirements (both previews)
 
 - Single `.html` file (no external CSS or JS files)

package/template/.aioson/skills/process/design-hybrid-forge/references/pair-compatibility.md

@@ -78,6 +78,38 @@ Each base skill has a primary role:
 |---|---|
 | `bold-editorial-ui` × `cognitive-core-ui` | Dark editorial command — large display type + mono rails, red-orange × teal tension |
 | `neo-brutalist-ui` × `warm-craft-ui` | Crafted brutalism — raw structure + handmade warmth, artisan dev aesthetic |
+
+---
+
+## Three.js Spatial — Modifier (not a primary parent)
+
+`threejs-spatial` is a **special modifier category** — it is not a standalone design skill
+and can never be a primary parent. It layers WebGL/Three.js spatial effects on top of any
+design skill, adding a 3D scene or particle system as the visual substrate.
+
+**How it works as a modifier:**
+- Applied as a modifier (up to 3 modifiers allowed in advanced mode)
+- Governs: background scene layer, particle systems, 3D object showcase, holographic effects
+- Does NOT govern: tokens, typography, component structure, layout rhythm
+- Accent colors from the primary parents MUST flow through the Three.js parameters
+- The Three.js scene is always alpha: true — CSS gradient background shows through
+
+**Three.js × Design Skill combinations:**
+
+| Primary parent | Three.js layer | Result | Best for |
+|---|---|---|---|
+| `glassmorphism-ui` | Particle aurora backdrop | Frosted 3D glass — glass panels float over real particle scenes | AI tools, crypto, modern SaaS landing |
+| `aurora-command-ui` | Holographic glass object | Holographic command center — glass panels reveal 3D object inside | SOC dashboards, security platforms |
+| `neo-brutalist-ui` | Raw geometry + particles | Particle brutalism — hard geometric forms with particle swarms | Dev tools, indie platforms |
+| `bold-editorial-ui` | Scroll-driven 3D parallax | Editorial 3D depth — typography and images move through a 3D scene | Premium marketing, product launches |
+| `cognitive-core-ui` | Floating data cards (3D boxes) | Command 3D — dense data cards as 3D objects floating in space | Monitoring dashboards, metrics platforms |
+| `warm-craft-ui` | Organic particle drift | Warm particle field — particles drift like embers or dust motes | Wellness, creative tools, B2C |
+
+**Anti-blend rules for Three.js modifier:**
+- Three.js never replaces the CSS/HTML layout — it enhances the background/scene layer only
+- No particle count above 8,000 on desktop, 2,000 on mobile
+- WebGL support check + CSS fallback is mandatory
+- Three.js is never the primary story — the product message comes first
 | `clean-saas-ui` × `bold-editorial-ui` | Enterprise editorial — clean precision + cinematic moments, professional drama |
 
 ---

package/template/.aioson/skills/process/design-hybrid-forge/references/quality-gates.md

@@ -159,6 +159,26 @@ Fail: Return to Phase 4 and fix the metadata before distribution.
 
 ---
 
+## Gate J — Three.js modifier validation (only when `threejs-spatial` is a modifier)
+
+**Question:** Does the Three.js layer enhance without dominating?
+
+Checklist:
+- [ ] WebGL support check present — graceful CSS fallback when WebGL unavailable
+- [ ] `prefers-reduced-motion: reduce` disables the canvas entirely
+- [ ] Mobile particle count ≤ 30% of desktop count
+- [ ] Canvas is `alpha: true` — CSS gradient background visible through it
+- [ ] Accent colors from primary parents flow through Three.js scene parameters (point lights, particle colors, glow)
+- [ ] Three.js scene is background/scene layer only — HTML layout and CSS components are unaffected
+- [ ] No external texture/model URLs — all assets are procedural (geometry, gradients, shaders)
+- [ ] `IntersectionObserver` or equivalent stops render loop when canvas is off-screen — uses `cancelAnimationFrame` + null guard, not `renderer.setAnimationLoop(null)` (which only controls the renderer's internal loop, not `requestAnimationFrame`)
+- [ ] `beforeunload` disposes renderer, geometries, and materials — no memory leaks on page unload
+
+Pass: Three.js enhances without violating the design skill's visual language.
+Fail: Fix the specific violation. Three.js is a modifier — it serves the hybrid, not the other way around.
+
+---
+
 ## Final ship checklist — project-local mode
 
 Before marking the project-local hybrid as done:

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/landing-page-deploy.md

@@ -0,0 +1,192 @@
+---
+name: landing-page-deploy
+description: Deploy workflows for landing pages and static sites — Vercel (Git-connected, CDN) and Hostinger VPS (LiteSpeed). Load when the user asks to deploy a site or when project_type=site is ready for production.
+---
+
+# Landing Page Deploy
+
+Two production-ready deploy paths. Choose based on where your domain is registered and your cost preference.
+
+---
+
+## Path A — Vercel (recommended for Cloudflare domains + automated CI/CD)
+
+**Requirements:**
+- Vercel account (Pro plan minimum — $20/mo — for custom domain on production)
+- Domain registered in Cloudflare (or any DNS provider with CNAME/A record access)
+- Git repository (GitHub, GitLab, or Bitbucket)
+
+### Step A1 — Create Vercel project
+```bash
+# If Vercel CLI is installed
+vercel login
+vercel --prod
+```
+
+Or via dashboard: vercel.com → New Project → Import Git Repository
+
+### Step A2 — Configure project settings
+- Framework Preset: `Other` (for plain HTML) or the correct framework
+- Build Command: leave blank for plain HTML
+- Output Directory: `.` or `dist` (wherever index.html lives)
+- Install Command: leave blank for plain HTML
+
+### Step A3 — Connect domain (Cloudflare DNS)
+1. In Vercel: Settings → Domains → Add `yourdomain.com` and `www.yourdomain.com`
+2. Vercel shows you DNS records to add
+3. In Cloudflare: DNS → Add records as shown by Vercel
+   - Type A: `@` → Vercel IP (proxied OFF — orange cloud OFF for Vercel)
+   - Type CNAME: `www` → `cname.vercel-dns.com`
+4. Wait for propagation (5–30 min)
+
+### Step A4 — Verify SSL
+Vercel auto-provisions SSL via Let's Encrypt. Verify:
+- `https://yourdomain.com` loads without warnings
+- `https://www.yourdomain.com` redirects correctly
+
+### Step A5 — Set environment variables (if needed)
+Vercel Dashboard → Settings → Environment Variables
+Add tracking IDs, API keys as env vars — never hardcode them.
+
+### Step A6 — Post-deploy validation checklist
+- [ ] Production URL loads correctly
+- [ ] SSL certificate active (green padlock)
+- [ ] www → non-www redirect working (or vice versa — consistent)
+- [ ] Preview URL from Vercel PR/branch works
+- [ ] Analytics receiving data (Vercel Analytics or GA)
+- [ ] Meta Pixel fires on production URL (verify with Pixel Helper)
+- [ ] GTM fires on production URL (verify with Tag Assistant)
+- [ ] Test UTM: `https://yourdomain.com?utm_source=test` → check sessionStorage
+
+### Vercel MCP integration (for automated deploy from Claude Code)
+If the Vercel MCP is configured in Claude Code:
+```
+# Deploy current project to Vercel production
+vercel deploy --prod
+```
+Claude Code can trigger deploys directly via MCP without leaving the session.
+
+---
+
+## Path B — Hostinger VPS (recommended for BRL billing + Brazilian users)
+
+**Requirements:**
+- Hostinger VPS plan (R$29.90+/mo, includes free domain on some plans)
+- Domain registered in Hostinger (or any DNS provider)
+- SSH access to the VPS
+
+### Step B1 — Prepare VPS
+```bash
+# SSH into VPS
+ssh root@YOUR_VPS_IP
+
+# Update system
+apt update && apt upgrade -y
+
+# Install LiteSpeed (or use OpenLiteSpeed — pre-installed on some plans)
+# Check if already installed
+litespeed -v
+
+# Create site directory
+mkdir -p /var/www/yourdomain.com/public_html
+```
+
+### Step B2 — Upload site files
+```bash
+# From local machine — upload entire site folder
+scp -r ./dist/* root@YOUR_VPS_IP:/var/www/yourdomain.com/public_html/
+
+# Or use rsync for incremental updates
+rsync -avz --delete ./dist/ root@YOUR_VPS_IP:/var/www/yourdomain.com/public_html/
+```
+
+### Step B3 — Configure virtual host (LiteSpeed)
+Via Hostinger hPanel → Websites → Add Website → point to your folder.
+
+Or via CLI if you have direct LiteSpeed access:
+```
+# /usr/local/lsws/conf/vhosts/yourdomain.com/vhconf.conf
+docRoot /var/www/yourdomain.com/public_html/
+```
+
+### Step B4 — SSL certificate
+```bash
+# Using Let's Encrypt via certbot
+apt install certbot python3-certbot-apache -y
+certbot --apache -d yourdomain.com -d www.yourdomain.com
+
+# Auto-renewal
+certbot renew --dry-run
+```
+
+Or use Hostinger's built-in SSL (hPanel → SSL → Free SSL).
+
+### Step B5 — Set up domain DNS
+In Hostinger hPanel → Domains → DNS Zone:
+- Type A: `@` → your VPS IP
+- Type A: `www` → your VPS IP
+
+Or in Cloudflare if domain is there:
+- Type A: `@` → VPS IP (proxied ON for DDoS protection)
+- Type A: `www` → VPS IP (proxied ON)
+
+### Step B6 — Start web service
+```bash
+# LiteSpeed
+service lsws start
+
+# Verify site is accessible
+curl -I https://yourdomain.com
+```
+
+### Step B7 — Post-deploy validation checklist
+- [ ] Production URL loads correctly
+- [ ] SSL active (no mixed content warnings)
+- [ ] PageSpeed score ≥ 90 (LiteSpeed cache helps significantly)
+- [ ] `curl -I https://yourdomain.com` returns `200 OK`
+- [ ] Meta Pixel fires on production URL
+- [ ] GTM fires on production URL
+- [ ] UTM capture working end-to-end
+- [ ] Form submissions go to the correct endpoint
+
+---
+
+## Deploy decision matrix
+
+| Factor | Vercel | Hostinger VPS |
+|---|---|---|
+| Domain in Cloudflare | ✓ Best | Works |
+| Domain in Hostinger | Works | ✓ Best |
+| Pay in BRL | ✗ USD only | ✓ BRL |
+| Automated CI/CD | ✓ Git-push deploys | Manual rsync |
+| MCP integration | ✓ Available | SSH only |
+| Serverless functions | ✓ Edge functions | ✗ Not native |
+| Cache/CDN | Vercel Edge Network | LiteSpeed cache |
+| Cheapest option | $20/mo USD | R$29.90/mo BRL |
+| Best for Brazilian users | Both | LiteSpeed + BR server |
+
+---
+
+## Deploy from within Claude Code (no manual steps)
+
+### Vercel via MCP
+If Vercel MCP is connected in Claude Code settings, the agent can deploy directly:
+```
+Deploy this project to Vercel production with domain yourdomain.com
+```
+
+### Hostinger via SSH
+Claude Code can SSH into the VPS and run the deploy:
+```bash
+# The agent executes this sequence
+ssh root@VPS_IP "cd /var/www/yourdomain.com/public_html && rm -rf *"
+scp -r ./dist/* root@VPS_IP:/var/www/yourdomain.com/public_html/
+ssh root@VPS_IP "service lsws restart"
+```
+
+### Post-deploy automated check
+After any deploy, run:
+```bash
+curl -o /dev/null -s -w "%{http_code}" https://yourdomain.com
+# Should return 200
+```