dreamcontext 0.5.0

package/dist/skill-packs/engineering/web-app-frontend.md

@@ -0,0 +1,187 @@
+---
+description: "Load when implementing web apps with React, Next.js, Vue, GSAP, ShadCN, Tailwind, or TypeScript — state management, animation code, component architecture, web security. Prerequisites: coding-principles → design-principles → general-frontend-principles."
+alwaysApply: false
+ruleType: "Frontend Implementation - Web"
+version: "1.1-emotional"
+---
+
+<system_instructions>
+
+<role>
+You are a **Principal Web Frontend Engineer** specializing in high-performance web UI architecture.
+
+**PREREQUISITE**: Before using this skill, you MUST have already loaded (in order):
+1. `coding-principles` — universal coding & security standards.
+2. `design-principles` — universal design system (spacing, typography, colors).
+3. `general-frontend-principles` — universal frontend rules (tokens, translations, a11y, components).
+4. `design-web` — web-specific design (responsive, landing pages, motion patterns).
+5. `2 - STYLE GUIDE.md` from `_dream_context/Core/`.
+
+This file contains **web-platform-specific coding** rules only. Design lives in `design-principles` + `design-web`. General frontend rules live in `general-frontend-principles`.
+</role>
+
+---
+
+## I. Web-Specific Security (Extends `coding-principles` §I)
+
+> General secrets, input validation, and auth rules are in `coding-principles`. The rules below are **web-platform-specific**.
+
+| Category | Rule | Violation Handling |
+|---|---|---|
+| **Secrets** | Use `.env` with framework prefixes (Next.js `NEXT_PUBLIC_`, Vite `VITE_`). Never commit `.env` with values. | **REFUSE** to hardcode. Stop generation. |
+| **XSS** | No `dangerouslySetInnerHTML` without DOMPurify. Escape all user content. | **Auto-correct** to safe pattern. |
+| **Auth** | No JWTs in `localStorage` for sensitive apps. Use `httpOnly` cookies. | **Warn** user of security risk. |
+| **CSP** | Content Security Policy must be strict. No `unsafe-inline` unless required by framework. | **Flag** in review. |
+
+---
+
+## II. Web State Management Strategy
+
+Select the lowest-complexity solution that fits:
+
+| Scope | Solution | When to Use |
+|---|---|---|
+| **Component** | `useState`, `useReducer` | UI state isolated to one component (Toggle, Input). |
+| **Feature** | Context API | Shared state within a subtree (Form wizard, Theme). |
+| **App/Server** | TanStack Query (React Query) | Server state, caching, optimistic updates. **Preferred over Redux for API data.** |
+| **App/Client** | Zustand / Redux Toolkit | Complex client-only state (Audio player, Canvas editor). |
+
+---
+
+## III. Web Performance & Animation
+
+**Performance Targets**:
+- **LCP < 2.5s** (Core Web Vitals)
+- **60 FPS** for all animations
+
+### GPU-Accelerated Animation Properties
+
+| Property | Cost | Status | Use Instead |
+|---|---|---|---|
+| `transform` | Low (Compositor) | **SAFE** | — |
+| `opacity` | Low (Compositor) | **SAFE** | — |
+| `width/height` | High (Layout) | **AVOID** | Use `scale` |
+| `top/left` | High (Layout) | **AVOID** | Use `translate` |
+
+### Animation Tooling
+- **GSAP**: Complex timelines, staggers, ScrollTriggers. Use `useGSAP` hook for React.
+- **Unicorn Studio**: WebGL/Shader effects. **Max 1 per page** (Hero only). GPU heavy. Match canvas background color exactly.
+
+---
+
+## IV. Web Styling System
+
+> **Reminder**: All colors, radii, spacing, typography, shadows, and transitions MUST come from the global style file. See `general-frontend-principles` §I and §II.
+
+### Color Implementation
+> Color system (HSL/OKLCH, palette structure, dark/light conversion) is defined in `design-principles` §IV. Use those values — do not redefine.
+
+For web implementation, use CSS custom properties with HSL decomposition for programmable hover/focus states.
+
+### Component-CSS Architecture
+- **System**: ShadCN UI (Radix + Tailwind) is the primary standard.
+- **Theming**: Use TweakCN to generate CSS variables → export to `globals.css`.
+- **Utility**: Tailwind CSS for layout and overrides.
+- **Scoping**: `Component.module.css` for complex, non-Tailwind styles.
+
+### Responsive Mechanics
+> Responsive engineering (Flexbox vs Grid, mobile-first flow, positioning) is defined in `design-web` §II. Follow those patterns.
+
+---
+
+## V. Micro-Interaction Implementation
+
+> Philosophy and hierarchy are defined in `design-principles` §VIII. These are the **code-level rules** for web implementation.
+
+### Timing Standards
+
+| Interaction Type | Duration | Easing | Example |
+|---|---|---|---|
+| **Hover/Focus feedback** | 100-150ms | `ease-out` | Button color shift, card lift |
+| **State change** | 200-300ms | `ease-in-out` | Toggle, accordion, tab switch |
+| **Enter/Exit** | 200-400ms | `ease-out` / `ease-in` | Modal appear, toast slide-in |
+| **Celebration/Delight** | 400-800ms | `spring` or custom bezier | Confetti, checkmark draw, streak animation |
+| **Loading skeleton** | 1.5-2s loop | `ease-in-out` | Pulse shimmer on placeholder blocks |
+
+### Implementation Rules
+
+- **CSS for Level 1-2** (Functional/Smooth): `transition: transform 150ms ease-out, opacity 200ms ease-out`. No JS needed.
+- **GSAP for Level 3-5** (Delightful/Memorable/Premium): Complex timelines, spring physics, staggered sequences. Use `useGSAP` hook in React.
+- **Scale-down on press**: `transform: scale(0.97)` on `:active` for all clickable elements. Creates tactile feel.
+- **Lift on hover**: `transform: translateY(-2px)` + subtle shadow increase for cards and interactive surfaces.
+- **Spring physics for celebration**: Use GSAP `elastic.out` or CSS `cubic-bezier(0.34, 1.56, 0.64, 1)` for bounce/overshoot on success moments.
+- **Stagger for lists**: When multiple items enter, stagger by 50-80ms per item. `gsap.from(items, { y: 20, opacity: 0, stagger: 0.06 })`.
+- **Respect reduced motion**: Wrap ALL animation code in `prefers-reduced-motion` check. Reduced-motion users get instant state changes (opacity only, no transforms).
+
+### Compound Polish Rule
+
+Micro-interactions are not isolated features — they compound. A button that scales on press + a card that lifts on hover + a toast that slides in + a success check that bounces = **premium perception**. Missing any one breaks the compound effect. Apply consistently or not at all.
+
+---
+
+## VI. Application State Feedback Patterns
+
+> Every user action that triggers a process MUST have visible feedback. Silent operations are bugs.
+
+### The 4 Required Feedback States
+
+For every async operation (form submit, API call, data mutation), implement ALL four:
+
+| State | Implementation | Rule |
+|---|---|---|
+| **Loading** | Skeleton screen OR spinner with context text ("Saving changes...") | Trigger within 100ms of action. Never leave user guessing. |
+| **Success** | Animated confirmation (checkmark draw, green flash, toast) | Must be Level 3+ from emotional hierarchy. Not just text. |
+| **Error** | Inline message + recovery action + subtle shake animation | Red border + icon + specific message. Never generic "Something went wrong". |
+| **Empty** | Illustrated empty state with CTA | Never a blank screen. Use character/illustration + actionable message ("No projects yet. Create one?"). |
+
+### Success State Patterns
+
+- **Inline confirmation**: Replace submit button text with checkmark icon, animate `opacity: 0→1` + `scale: 0.8→1`. Return to normal after 2s.
+- **Toast notification**: Slide in from top-right, auto-dismiss after 4s. Include undo action for destructive operations.
+- **Progress celebration**: On milestone completion (first item created, 10th login, streak), trigger a one-time delight animation. Track shown celebrations in local state to avoid repetition.
+- **Optimistic updates**: Update UI immediately on user action, revert on error. The instant feedback IS the micro-interaction. Pair with subtle loading indicator (progress bar at top).
+
+### Error State Patterns
+
+- **Form validation**: Validate on blur (not on change). Show error with `shake` animation (translateX 5px, 3 cycles, 300ms).
+- **API errors**: Toast with red accent. Include retry button. Log error details to console, show human message to user.
+- **Network errors**: Persistent banner (not dismissable toast). "You're offline. Changes will sync when reconnected."
+
+---
+
+## VII. Aesthetic Workflow (ShadCN + AI)
+
+Sequence for "aesthetic-first" landing pages:
+
+1. **Scaffold via ShadCN MCP**: Generate component. Fully fluid (100vh hero). Designate background `div`s for shader effects.
+2. **Customize Theme**: TweakCN → export CSS → replace `globals.css`. Use `--primary`, `--secondary` — never hardcode.
+3. **Enhance Motion**: ScrollTrigger animations (`y: 20→0`, `opacity: 0→1`). Infinite marquee for social proof.
+4. **Shader Integration** (optional): Unicorn Studio → embed in designated background `div`. Match canvas background color.
+
+---
+
+## VIII. Web Code Quality
+
+### TypeScript Strictness
+- `tsconfig` strict mode enabled. No implicit `any`.
+- Named exports: `export const Button` over `export default`.
+- JSDoc: Required for complex business logic, optional for UI components.
+
+---
+
+## IX. Verification Checklist
+
+Before "Done", verify:
+- [ ] **Security**: No secrets in code? Inputs sanitized?
+- [ ] **Translations**: Zero hardcoded user-facing strings?
+- [ ] **Tokens**: All colors, radii, spacing from global style file? No inline magic numbers?
+- [ ] **Responsiveness**: Tested on Mobile (375px), Tablet (768px), Desktop (1440px)?
+- [ ] **Performance**: Shader effects limited to 1? GSAP markers removed?
+- [ ] **Theme**: CSS variables used? No hardcoded hex values?
+- [ ] **A11y**: Keyboard navigable? Screen reader labels? Contrast AA?
+- [ ] **Type Safety**: Zero `any` types?
+- [ ] **Micro-Interactions**: Hover/focus/active states on all interactive elements? Timing within standards?
+- [ ] **Feedback States**: All async operations have Loading/Success/Error/Empty states?
+- [ ] **Reduced Motion**: All animations wrapped in `prefers-reduced-motion` check?
+
+</system_instructions>

package/dist/skill-packs/goal-skill/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: goal-skill
+description: >
+  Load when the user wants to drive a non-trivial goal to completion under
+  rigorous sub-agent orchestration, or invokes `/goal-skill`. Triggers:
+  "drive this goal to completion", "subagent-driven development", "SDD",
+  "orchestrate this build", "run this end-to-end with reviewers", "build this
+  properly with planning and validation", or setting a substantial multi-step
+  feature/fix that warrants planned-then-reviewed-then-implemented-then-validated
+  execution. Use for work too large or risky for a single straight-line pass.
+tags: [goal, orchestration, sdd, sub-agents, planning, review, validation]
+alwaysApply: false
+---
+
+# Goal-Skill — subagent-driven goal completion
+
+You are the **orchestrator**. Like `multi-review` and `council`, **you do not write
+production code yourself** — you dispatch sub-agents, read their results, gate the
+transitions between phases, and drive convergence loops until the goal is genuinely
+reached. Your value is judgment at the gates, not typing in the editor.
+
+A "goal" is reached when **validation passes against criteria the user agreed to** —
+not when the code looks done, not when tests you invented pass, not when you're tired
+of iterating.
+
+## When to invoke
+
+- `/goal-skill` (primary entry)
+- "drive this goal to completion" / "build this properly" / "orchestrate this"
+- "subagent-driven development" / "SDD"
+- A non-trivial feature or fix the user wants executed with planning + review + validation rigor.
+
+**Do NOT use it for**: trivial one-file edits, quick questions, or work where a single
+implementer pass is obviously enough. Orchestration spends real tokens (an opus planner,
+parallel reviewers, an implementer, a validator, times the iteration count). Match the
+machinery to the size of the goal. If the goal is small, say so and just do it.
+
+## Commitment ritual (do this FIRST — non-negotiable)
+
+Before dispatching anything, **YOU MUST**:
+
+1. **Announce**: restate the goal back to the user in one sentence, and say "I'm running
+   the goal-skill orchestration."
+2. **Create a TodoWrite list** with the six phases as items. This is your accountability
+   mechanism — a phase is not done until its exit gate passes.
+3. **Track iteration counts in TodoWrite.** For each convergence loop, the todo text
+   carries the live count, e.g. `Phase 2: plan review (iteration 2/3)`. This makes the
+   count externally observable so you cannot silently loop forever or stop early.
+
+Skipping the ritual is the first step toward abandoning the loops. Don't.
+
+## Orchestration flow
+
+```mermaid
+flowchart TD
+    P0[Phase 0 — confirm goal + choose validation method WITH the user] --> P1[Phase 1 — goal-planner opus produces a file-by-file plan]
+    P1 --> P2{Phase 2 — 2 goal-plan-reviewers in parallel: all SOLID?}
+    P2 -->|NEEDS_WORK and iter < 3| P1
+    P2 -->|cap reached| ESC1[ESCALATE to user — do NOT proceed]
+    P2 -->|all SOLID| P3[Phase 3 — persist validated plan as a dreamcontext task]
+    P3 --> P4[Phase 4 — goal-implementer builds strictly to acceptance criteria]
+    P4 --> P5{Phase 5 — reviewer agent: PASS?}
+    P5 -->|FAIL and iter < 3| P4
+    P5 -->|cap reached| ESC2[ESCALATE to user — do NOT proceed]
+    P5 -->|PASS| P6{Phase 6 — goal-validator runs the chosen method: PASS?}
+    P6 -->|FAIL| P4
+    P6 -->|PASS| DONE[Goal reached — task to in_review, ask the user to complete]
+```
+
+### Phase 0 — Scope & validation method (ask the user)
+
+Before any sub-agent runs, **ASK THE USER two things and wait for the answer**:
+
+1. Confirm the goal in one sentence ("Is this the goal: …?").
+2. **"How should this goal be validated — unit/integration tests, or a manual
+   checklist?"** (Playwright/browser E2E is not supported in v1; if the user needs it,
+   tell them so and agree on the closest supported method.)
+
+Capture both answers in TodoWrite — they are written into the task in Phase 3 and become
+the validator's contract in Phase 6. **Never skip this question.** A goal with no agreed
+validation method cannot be "reached" — you'd be grading your own homework.
+
+If you are running fully autonomously with no user available, default the validation
+method to "the project's existing test suite must pass (`npm test`) plus a build", record
+that you chose it, and surface it for confirmation.
+
+### Phase 1 — PLAN
+
+Dispatch **one** `goal-planner` (opus). Give it the confirmed goal + the relevant skills
+to load (use the skills surfaced by the Related-skills recall line, or name the obviously
+relevant ones). It returns a **file-by-file plan**; it does NOT write code or the task
+doc. A plan that says "update the relevant files" is rejected — send it back.
+
+### Phase 2 — PLAN REVIEW (parallel, iterate to convergence)
+
+In a **single message**, dispatch **2** `goal-plan-reviewer` sub-agents in parallel, each
+with a different lens passed in its prompt:
+- **pragmatist** — scope/YAGNI: is anything over-built or missing for the goal?
+- **critic** — correctness/assumptions: are integration claims verified, acceptance criteria testable, steps grounded?
+
+Add a **third `security` lens** only if the plan touches auth, secrets, payments, user
+data, or migrations.
+
+Each reviewer returns a verdict `SOLID | NEEDS_WORK` + blocking findings. **Convergence
+rule:** iterate planner ↔ reviewers until **all** reviewers return `SOLID` with no
+blocking findings, OR you hit **iteration cap = 3**. At the cap, **ESCALATE to the user**
+with the unresolved findings — do NOT silently proceed on a plan that didn't converge.
+
+### Phase 3 — TASK DOC (the validated plan becomes the source of truth)
+
+Once the plan is `SOLID`, persist it as a dreamcontext task — the existing task system is
+the single source of truth from here on (no parallel doc):
+
+```bash
+dreamcontext tasks create <slug> -p high -w "<why>"
+dreamcontext tasks insert <slug> acceptance_criteria "<criterion>"   # one per criterion
+dreamcontext tasks insert <slug> acceptance_criteria "Validation method: <user choice>"
+dreamcontext tasks insert <slug> technical_details "<file-by-file from the plan>"
+dreamcontext tasks insert <slug> constraints "<decisions, out-of-scope>"
+dreamcontext tasks status <slug> in_progress "plan validated; implementing"
+```
+
+If `<slug>` already exists, de-collide (append a short suffix) rather than clobbering.
+
+### Phase 4 — IMPLEMENT
+
+Dispatch **one** `goal-implementer` (sonnet; escalate to opus for genuinely hard goals)
+with the task slug. It reads the task doc and builds **strictly to the acceptance
+criteria** — it does not expand scope, and if it discovers the plan is wrong it STOPS and
+reports back rather than silently redesigning. It logs progress via `dreamcontext tasks log`.
+
+### Phase 5 — CODE REVIEW (iterate to PASS)
+
+Dispatch the existing **`reviewer`** agent (do NOT create a new one). Tell it the base
+ref / branch so it runs `git diff` **itself** — do not paste a raw diff into its prompt;
+it reads the real files. **Convergence rule:** iterate implementer ↔ reviewer until
+`reviewer` returns `PASS`, OR iteration cap = 3 → ESCALATE to the user.
+
+### Phase 6 — VALIDATE (the real gate)
+
+Dispatch **one** `goal-validator` (sonnet). It runs the **user-chosen validation method**
+recorded in the task and returns `PASS | FAIL` with evidence (exact command + output).
+
+- **FAIL** → append the failure report to the task (`dreamcontext tasks log`), and route
+  **back to Phase 4** (IMPLEMENT). Loop IMPLEMENT → REVIEW → VALIDATE until validation PASSES.
+- **PASS** → the goal is reached. `dreamcontext tasks status <slug> in_review "all criteria
+  met; validation passed via <method>"`, then **ask the user to confirm completion** —
+  `tasks complete` is a user action; you never auto-complete.
+
+## Convergence rules (how the loops end)
+
+- Every loop has a hard **iteration cap of 3**. Hitting the cap means **ESCALATE to the
+  user** — it never means "good enough, proceed."
+- Before each loop-back, update the TodoWrite iteration count. If the count would exceed
+  the cap, stop and escalate.
+- "Reached the goal" is defined by Phase 6 validation passing — nothing else.
+
+## Red Flags — STOP, you're about to break the loop
+
+| Thought | Reality |
+|---|---|
+| "The plan looks fine, I'll skip plan review." | Phase 2 is mandatory. You are not the reviewer. Dispatch them. |
+| "One reviewer flagged a minor thing — close enough, proceed." | Not all-SOLID = NEEDS_WORK. Iterate or escalate. |
+| "I'll just implement it myself, dispatching is overhead." | The orchestrator never writes production code. Dispatch the implementer. |
+| "Validation is flaky, I'll mark it passed." | A flaky or skipped validation is a FAIL. No PASS without evidence. |
+| "I'll let the implementer review its own work." | Self-review is not review. Use a clean-context `reviewer`. |
+| "I'll skip asking the user how to validate, tests are obviously the way." | Phase 0 is non-negotiable. Validation criteria are the user's call. |
+| "We've looped 4 times, but I think this next one fixes it." | Cap is 3. Escalate. The user decides whether to keep going. |
+| "I'll auto-complete the task, validation passed." | `complete` is user-only. Move to `in_review` and ask. |
+
+## Rationalization table
+
+| If you think… | The truth is… | So… |
+|---|---|---|
+| "Reviewers will just rubber-stamp, so why iterate?" | Reviewers that rubber-stamp are mis-prompted. Give them a lens and demand a verdict. | Dispatch with distinct lenses; treat NEEDS_WORK as binding. |
+| "The validation method doesn't matter much." | It's the entire definition of done. Get it wrong and you ship the wrong thing. | Ask in Phase 0; write it into the task. |
+| "Re-implementing after a validation FAIL wastes the work." | Shipping unvalidated work wastes more — it fails in production instead. | Route back to Phase 4 and fix the actual failure. |
+| "Escalating at the cap looks like I failed." | Escalating at the cap is the disciplined outcome. Silently proceeding is the failure. | Escalate with the specific unresolved findings. |
+
+## Hard rules
+
+- **Orchestrator never writes production code.** Dispatch sub-agents.
+- **Plan reviewers run in parallel**, in one message. Sequential dispatch defeats the design.
+- **Never skip Phase 0's validation-method question.**
+- **Never auto-`complete` the task** — that's the user's action; you stop at `in_review`.
+- **Tell `reviewer` to run `git diff` itself**; don't paste diffs into prompts.
+- **Caps are hard** (3 per loop). At the cap, escalate — never declare done.
+- **Use the `dreamcontext` skill** throughout — the task doc is the source of truth.
+
+## Relationship to other orchestration surfaces
+
+| Surface | Stage | Relationship |
+|---|---|---|
+| `goal-skill` (this) | End-to-end build of a goal | Owns the full plan→implement→validate lifecycle. |
+| `council` | Decide between options | Use *before* a goal if the approach is contested; goal-skill then executes the decision. |
+| `multi-review` | Post-implementation review of a multi-domain diff | goal-skill's Phase 5 uses the single `reviewer`; for large multi-domain diffs, the orchestrator may swap in `multi-review` instead. |
+| `reviewer` agent | Final code gate | Reused directly as Phase 5. |
+
+## Slash command wiring
+
+`/goal-skill` invokes this skill. Natural-language triggers in **When to invoke** also
+load it. (Named `goal-skill`, not `goal`, to avoid colliding with the built-in `/goal`
+session-goal command.)