@struq/skill 0.0.0-stage → 0.2.2

package/skills/struq/cinematic/references/11-agent-workflows.md

@@ -0,0 +1,246 @@
+# Agent Workflows
+
+## General behavior
+
+The agent should direct the experience before generating large amounts of code. It should maintain a live model of:
+
+- experience thesis,
+- chapters and progress ranges,
+- active state owners,
+- camera shots,
+- handoff contracts,
+- implementation status,
+- unresolved risks,
+- tuning decisions.
+
+When new information conflicts with an earlier decision, update the relevant artifacts and identify downstream effects.
+
+## Workflow A: Design from a brief
+
+### Step 1: Extract usable facts
+
+Separate:
+
+- content facts,
+- visual references,
+- emotional goals,
+- required interactions,
+- technical constraints,
+- unknowns that materially affect design.
+
+### Step 2: Propose the experience thesis
+
+Provide one strong default thesis rather than many vague directions. State assumptions.
+
+### Step 3: Establish the experience contract
+
+Define:
+
+- persistent-stage model,
+- chapter count,
+- transition language,
+- camera character,
+- typography language,
+- input ownership,
+- responsive strategy,
+- prohibited patterns.
+
+### Step 4: Map chapters
+
+Create a chapter table. Each row must describe a state transformation, not merely content.
+
+Weak:
+
+```text
+Chapter 2, Features: show three features.
+```
+
+Strong:
+
+```text
+Chapter 2, Disassembly: the hero object separates into three functional layers. The camera trucks left to reveal depth; each layer becomes the spatial anchor for one feature statement. The outer ring remains as the bridge into the systems chapter.
+```
+
+### Step 5: Specify handoffs
+
+Do not leave handoffs as “transition TBD.” At minimum define the bridge and continuity principle.
+
+### Step 6: Produce the implementation architecture
+
+Only after direction is coherent, assign responsibilities to GSAP, ScrollTrigger, Lenis, R3F, Motion, and plugins.
+
+### Step 7: Define acceptance criteria
+
+Use observable outcomes.
+
+## Workflow B: Guide implementation
+
+### Step 1: Establish current state
+
+Inspect or ask for:
+
+- relevant files,
+- current scene graph,
+- timeline construction,
+- scrolling setup,
+- route lifecycle,
+- known bugs,
+- a recording or screenshots when perceptual timing matters.
+
+### Step 2: Choose one vertical slice
+
+Select the smallest slice that proves the architecture, normally one chapter plus its handoff.
+
+### Step 3: Explain the target behavior
+
+Before code, state:
+
+- starting state,
+- ending state,
+- owners,
+- labels,
+- phase windows,
+- responsive behavior,
+- validation method.
+
+### Step 4: Implement by responsibility
+
+Identify which files own:
+
+- direction data,
+- registry,
+- timeline,
+- scene rig,
+- DOM layer,
+- lifecycle,
+- debug controls.
+
+### Step 5: Validate
+
+Check forward, reverse, resize, route leave, reduced motion, and the target device class.
+
+### Step 6: Record tuning decisions
+
+When values change, update the direction register rather than only changing local code.
+
+### Step 7: Move to the next slice
+
+Carry the established patterns forward. Do not create a new architecture for every chapter.
+
+## Workflow C: Audit and improve
+
+### Step 1: Observe symptoms
+
+Examples:
+
+- “each section feels separate,”
+- “camera movement feels floaty,”
+- “the page is impressive but tiring,”
+- “mobile composition breaks,”
+- “reverse scroll jumps,”
+- “the Three.js scene requires constant patching.”
+
+### Step 2: Trace causes
+
+Classify as:
+
+- experience architecture,
+- state ownership,
+- timeline structure,
+- handoff design,
+- camera composition,
+- input conflict,
+- responsive direction,
+- performance,
+- lifecycle.
+
+### Step 3: Build a continuity map
+
+For each chapter boundary, record:
+
+- persistent elements,
+- reset elements,
+- bridge,
+- camera relation,
+- handoff quality,
+- visible discontinuity.
+
+### Step 4: Build a property-conflict map
+
+Find properties written by several systems.
+
+```text
+camera.position:
+- GSAP chapter timeline
+- pointer effect in useFrame
+- route transition
+Result: visible drift and non-deterministic final pose
+Correction: nested narrative/reaction/route rigs
+```
+
+### Step 5: Prioritize structural fixes
+
+Fix in this order:
+
+1. state continuity,
+2. ownership conflicts,
+3. camera and target architecture,
+4. handoff coverage,
+5. timeline hierarchy,
+6. responsive behavior,
+7. performance,
+8. decorative polish.
+
+### Step 6: Specify before/after behavior
+
+Do not merely say “refactor the timeline.” State what the viewer should experience after the correction.
+
+### Step 7: Provide a staged remediation plan
+
+Each stage should be independently testable and preserve a working page.
+
+## Agent session protocol
+
+At the beginning of a substantial session, maintain a short status block:
+
+```text
+Mode: Design / Implementation / Audit
+Current chapter or slice:
+Active decision artifacts:
+Known constraints:
+Unresolved risks:
+```
+
+At the end, report:
+
+- decisions made,
+- files or artifacts changed,
+- values requiring visual tuning,
+- validation completed,
+- next recommended slice.
+
+## Agent anti-patterns
+
+The agent must not:
+
+- generate a generic hero/features/projects/contact structure unless the brief requires it,
+- equate “cinematic” with constant camera movement,
+- suggest pinning every section without a stage-continuity plan,
+- produce a monolithic component containing scene, timelines, state, and copy,
+- add post-processing before the composition works,
+- use vague words instead of progress ranges and states,
+- ignore reverse scroll,
+- ignore route cleanup,
+- let GSAP and Motion own the same transform,
+- assume desktop choreography scales directly to mobile,
+- hide uncertainty about untested visual values.
+
+## How the agent should handle visual tuning
+
+The agent should distinguish:
+
+- **architectural certainty:** ownership, lifecycle, state boundaries, cleanup;
+- **direction hypothesis:** likely camera path, timing, ease, phase range;
+- **visual tuning value:** exact position, FOV, scale, light intensity, shader amount.
+
+It should provide strong starting values and identify which values require in-browser judgment. It should not pretend that exact composition can be finalized without seeing the running result.

package/skills/struq/cinematic/references/12-audit-rubric.md

@@ -0,0 +1,176 @@
+# Audit Rubric
+
+Score each category from 0 to 5.
+
+- `0`: absent or broken
+- `1`: severely weak
+- `2`: inconsistent or generic
+- `3`: functional and intentional
+- `4`: strong and polished
+- `5`: exceptional, coherent, and resilient
+
+## 1. Experience thesis
+
+**Question:** Can the whole experience be described as one visual and emotional transformation?
+
+- 0: no unifying idea
+- 3: clear idea but not consistently expressed
+- 5: every major beat reinforces the thesis
+
+## 2. Persistent-world continuity
+
+**Question:** Does the page feel like one evolving world?
+
+Inspect:
+
+- persistent stage,
+- retained subjects,
+- environment continuity,
+- chapter resets,
+- route continuity.
+
+## 3. Chapter purpose
+
+**Question:** Does each chapter perform a distinct narrative action rather than merely display content?
+
+## 4. Handoff quality
+
+**Question:** Is every boundary an authored transfer with a bridge, coverage, ownership, and reverse behavior?
+
+## 5. State continuity
+
+**Question:** Do shared end and start states match without hidden jumps?
+
+## 6. Property ownership
+
+**Question:** Can every animated property be traced to one authoritative writer?
+
+Red flags:
+
+- GSAP and Motion on one transform,
+- pointer and narrative writing the same camera object,
+- callbacks creating irreversible state,
+- local components mutating global experience values.
+
+## 7. Timeline hierarchy
+
+**Question:** Are route, chapter, handoff, and discrete timelines separated and composed clearly?
+
+## 8. Semantic cues
+
+**Question:** Are important moments named and used to coordinate systems?
+
+## 9. Rhythm and pacing
+
+**Question:** Does the experience contain contrast between motion, holds, accents, and resolution?
+
+## 10. Camera direction
+
+**Question:** Are shots, targets, FOV, paths, and composition intentionally authored?
+
+Red flags:
+
+- constant orbit,
+- camera movement with no target plan,
+- excessive float,
+- no stable hero pose,
+- large mobile travel copied from desktop.
+
+## 11. Subject choreography
+
+**Question:** Does the principal object have clear placement, role changes, and material behavior?
+
+## 12. Typography choreography
+
+**Question:** Does type share beats and spatial logic with the visual world?
+
+Red flags:
+
+- every heading uses the same fade-up,
+- type ignores camera and safe areas,
+- SplitText breaks on resize,
+- unreadable motion density.
+
+## 13. SVG and graphic integration
+
+**Question:** Are vector effects meaningful bridges or explanatory systems rather than decoration?
+
+## 14. Input arbitration
+
+**Question:** Are scroll, pointer, hover, click, drag, and time assigned distinct responsibilities?
+
+## 15. Interaction envelopes
+
+**Question:** Are interactions enabled, attenuated, and disabled at deliberate states?
+
+## 16. Reverse behavior
+
+**Question:** Can a user reverse through scrubbed sequences without discontinuity or stale state?
+
+## 17. Responsive choreography
+
+**Question:** Does each viewport class preserve intent through authored composition changes?
+
+## 18. Reduced motion
+
+**Question:** Is there a coherent reduced-motion experience rather than a broken or entirely static fallback?
+
+## 19. Performance architecture
+
+**Question:** Are effects, assets, render settings, and frame work budgeted by device capability?
+
+## 20. Lifecycle and cleanup
+
+**Question:** Are timelines, triggers, listeners, ticker callbacks, styles, and GPU resources cleaned up?
+
+## 21. Tuning readiness
+
+**Question:** Can important values be inspected and changed from a central direction system?
+
+## 22. Validation coverage
+
+**Question:** Has the experience been tested across input, viewport, performance, motion preference, asset readiness, and route lifecycle?
+
+## Audit output template
+
+```md
+# Audit Summary
+
+## Executive diagnosis
+[One paragraph identifying the dominant structural issue.]
+
+## Scorecard
+| Category | Score | Evidence | Priority |
+|---|---:|---|---|
+
+## Structural findings
+### Finding
+- Symptom:
+- Cause:
+- Perceptual consequence:
+- Correction:
+- Validation:
+
+## Continuity map
+| Boundary | Persistent bridge | Camera continuity | Ownership transfer | Reverse-safe | Result |
+
+## Property conflict map
+| Property | Writers | Conflict | Correction |
+
+## Remediation sequence
+1. Foundation
+2. First corrected vertical slice
+3. Remaining chapter migrations
+4. Responsive and performance pass
+5. Final direction pass
+```
+
+## Score interpretation
+
+- `90 to 110`: exceptional architecture; focus on art direction and microtiming.
+- `70 to 89`: strong foundation with identifiable weaknesses.
+- `50 to 69`: impressive moments but inconsistent system quality.
+- `30 to 49`: effect-driven page with structural continuity problems.
+- `<30`: rebuild the experience architecture before adding polish.
+
+The numerical score supports prioritization. The written evidence is more important than the total.

package/skills/struq/cinematic/references/13-official-docs.md

@@ -0,0 +1,53 @@
+# Official Documentation Index
+
+Use official documentation to verify current APIs, imports, lifecycle guidance, and plugin behavior before applying code to a live project.
+
+## GSAP
+
+- GSAP documentation: https://gsap.com/docs/v3/
+- Installation: https://gsap.com/docs/v3/Installation/
+- React `useGSAP`: https://gsap.com/resources/React/
+- ScrollTrigger: https://gsap.com/docs/v3/Plugins/ScrollTrigger/
+- SplitText: https://gsap.com/docs/v3/Plugins/SplitText/
+- DrawSVGPlugin: https://gsap.com/docs/v3/Plugins/DrawSVGPlugin/
+- MorphSVGPlugin: https://gsap.com/docs/v3/Plugins/MorphSVGPlugin/
+- MotionPathPlugin: https://gsap.com/docs/v3/Plugins/MotionPathPlugin/
+- Flip: https://gsap.com/docs/v3/Plugins/Flip/
+- Observer: https://gsap.com/docs/v3/Plugins/Observer/
+- CustomEase: https://gsap.com/docs/v3/Eases/CustomEase/
+- Official GSAP skills repository: https://github.com/greensock/gsap-skills
+
+## Lenis
+
+- Lenis repository and integration guidance: https://github.com/darkroomengineering/lenis
+- React integration: https://github.com/darkroomengineering/lenis/tree/main/packages/react
+
+## React Three Fiber
+
+- Documentation: https://r3f.docs.pmnd.rs/
+- Canvas: https://r3f.docs.pmnd.rs/api/canvas
+- Hooks and `useFrame`: https://r3f.docs.pmnd.rs/api/hooks
+- Performance pitfalls: https://r3f.docs.pmnd.rs/advanced/pitfalls
+
+## Three.js
+
+- Documentation: https://threejs.org/docs/
+- Scene graph manual: https://threejs.org/manual/en/scenegraph.html
+- Render targets: https://threejs.org/manual/en/rendertargets.html
+- Post-processing: https://threejs.org/manual/en/post-processing.html
+
+## Motion for React
+
+- React documentation: https://motion.dev/docs/react
+- Installation: https://motion.dev/docs/react-installation
+- AnimatePresence: https://motion.dev/docs/react-animate-presence
+- Accessibility: https://motion.dev/docs/react-accessibility
+
+## Frameworks
+
+- Next.js documentation: https://nextjs.org/docs
+- Vite documentation: https://vite.dev/guide/
+
+## Verification note
+
+Package APIs and recommended imports can change. Treat examples in directed mode as architectural patterns. Before copying imports into a project, verify them against the project's installed versions and the official sources above.

package/skills/struq/cinematic/templates/01-experience-brief.md

@@ -0,0 +1,105 @@
+# Experience Brief
+
+## Project
+
+**Name:**
+
+**Route or page:**
+
+**Primary objective:**
+
+**Audience:**
+
+**Required action or outcome:**
+
+## Central idea
+
+**Principal subject, product, story, or metaphor:**
+
+**What should the viewer feel at the beginning?**
+
+**What should the viewer feel at the end?**
+
+**One-sentence transformation:**
+
+> The viewer moves from [starting perception] to [ending perception] while [the visual world performs its central transformation].
+
+## Content
+
+**Required chapters or messages:**
+
+1.
+2.
+3.
+
+**Required copy:**
+
+**Required calls to action:**
+
+## Assets
+
+| Asset | Available | Format | Notes | Required by |
+|---|---|---|---|---|
+| Hero model | | | | |
+| Supporting models | | | | |
+| Images | | | | |
+| Video | | | | |
+| SVG | | | | |
+| Typeface | | | | |
+| Audio | | | | |
+| Data | | | | |
+
+## Visual direction
+
+**References:**
+
+**Material language:**
+
+**Lighting language:**
+
+**Typography language:**
+
+**Motion character:**
+
+**Transition motifs:**
+
+## Interaction
+
+**Primary navigation model:** continuous scroll / snap-assisted / discrete chapters / hybrid
+
+**Pointer behavior:**
+
+**Click or tap behavior:**
+
+**Drag behavior:**
+
+**Route transitions:**
+
+## Constraints
+
+**Framework:** Next.js / Vite
+
+**Core stack:**
+
+**Target devices:**
+
+**Performance floor:**
+
+**Accessibility requirements:**
+
+**Reduced-motion expectation:**
+
+**Content-management requirements:**
+
+**Deadline or implementation phases:**
+
+## Prohibited patterns
+
+- 
+- 
+- 
+
+## Unknowns that materially affect direction
+
+- 
+-

package/skills/struq/cinematic/templates/02-experience-contract.md

@@ -0,0 +1,80 @@
+# Experience Contract
+
+## Experience thesis
+
+[One paragraph describing the viewer's action, the world's transformation, emotional progression, continuity mechanism, and final resolution.]
+
+## Persistent-stage strategy
+
+- Stage duration:
+- Persistent elements:
+- Semantic document structure:
+- Canvas ownership:
+- DOM overlay ownership:
+- Route lifecycle:
+
+## Narrative chapters
+
+| ID | Name | Purpose | Main transformation | Scroll budget | Bridge to next |
+|---|---|---|---|---:|---|
+
+## Motion language
+
+**Camera character:**
+
+**Subject movement:**
+
+**Typography movement:**
+
+**SVG and graphic movement:**
+
+**Ambient movement:**
+
+**Primary transition language:**
+
+## Input ownership
+
+| Input | Responsibility | Influence | Gating rule |
+|---|---|---|---|
+| Scroll | | | |
+| Time | | | |
+| Pointer | | | |
+| Velocity | | | |
+| Hover | | | |
+| Click/tap | | | |
+| Keyboard | | | |
+
+## Stack responsibility
+
+| System | Responsibility | Must not own |
+|---|---|---|
+| GSAP | | |
+| ScrollTrigger | | |
+| Lenis | | |
+| R3F / Three.js | | |
+| Motion | | |
+| SVG plugins | | |
+
+## Responsive contract
+
+**Desktop:**
+
+**Tablet:**
+
+**Mobile:**
+
+**Reduced motion:**
+
+**Low-performance tier:**
+
+## Prohibited generic patterns
+
+- No independent chapter reset without a narrative reason.
+- No opacity-only handoff as the complete transition.
+- No repeated copy-paste reveal language across all chapters.
+- No competing writers for the same transform.
+- [Add project-specific rules.]
+
+## Acceptance statement
+
+The experience is accepted when [observable description of continuity, hierarchy, performance, and interaction quality].