waitsec 0.5.5 → 0.5.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (7) hide show
  1. package/.cursor-plugin/plugin.json +1 -1
  2. package/README.md +98 -115
  3. package/package.json +1 -1
  4. package/plugin.json +1 -1
  5. package/skills/waitsec-pagemaker/SKILL.md +49 -3
  6. package/skills/waitsec-pagemaker/references/image-sourcing.md +113 -0
  7. package/skills/waitsec-pagemaker/references/motion-and-3d.md +179 -0
package/.cursor-plugin/plugin.json CHANGED
@@ -2,7 +2,7 @@
2
2
  "name": "waitsec",
3
3
  "displayName": "waitsec",
4
4
  "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
5
- "version": "0.5.5",
5
+ "version": "0.5.9",
6
6
  "author": {
7
7
  "name": "fastroware"
8
8
  },
package/README.md CHANGED
@@ -1,148 +1,140 @@
1
- # waitsec
1
+ <p align="center">
2
+ <a href="https://github.com/fastroware/waitsec">
3
+ <img src="https://raw.githubusercontent.com/fastroware/waitsec/main/assets/banner-waitsec.png" alt="waitsec banner: Hold on. Think first. Code less." width="100%">
4
+ </a>
5
+ </p>
6
+
7
+ <h1 align="center">
8
+ <img src="https://raw.githubusercontent.com/fastroware/waitsec/main/assets/logo-waitsec.png" alt="waitsec logo" width="88" height="88">
9
+ <br>
10
+ waitsec
11
+ </h1>
2
12
 
3
13
  <p align="center">
4
14
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="License: MIT"></a>
5
15
  <a href="https://github.com/fastroware/waitsec/tags"><img src="https://img.shields.io/github/v/tag/fastroware/waitsec?label=version&color=1f6feb" alt="Version"></a>
6
16
  <a href="https://www.npmjs.com/package/waitsec"><img src="https://img.shields.io/npm/v/waitsec?color=crimson" alt="npm version"></a>
7
- </p>
8
-
9
- <p align="center">
10
17
  <a href="https://skills.sh/fastroware/waitsec"><img src="https://img.shields.io/badge/skills.sh-waitsec-black?logo=vercel&logoColor=white" alt="skills.sh"></a>
11
18
  </p>
12
19
 
13
20
  > **Hold on. Think first. Code less.**
14
21
 
15
- `waitsec` gives your AI coding agent practical guardrails. It prevents AI from writing hundreds of unneeded lines, inventing imaginary requirements, or over-complicating simple tasks.
16
-
17
22
  ---
18
23
 
19
- ## Why waitsec?
24
+ ## What is waitsec?
20
25
 
21
- Most AI coding assistants do not fail because they lack knowledge. They fail because they move too fast and assume too much:
26
+ waitsec is a set of plain instruction files for your AI coding agent. It is not a library you import and not a program you run in your app. It is a set of rules your agent reads so it behaves better while it works on your code.
22
27
 
23
- 1. **They code before asking.** You ask for a photo upload feature, and the AI starts writing database migrations, thumbnail generators, and cloud bucket scripts before even asking where files should be stored.
24
- 2. **They over-engineer.** You ask for a simple login check, and the AI creates twelve new files with DTOs, factories, and repository interfaces.
25
- 3. **They touch too many files.** You ask to fix button alignment, and the AI reformats your router, updates project dependencies, and rewrites global styles.
26
- 4. **They guess when errors happen.** A test fails on one line, and the AI changes five unrelated files hoping something sticks.
28
+ Think of it as a checklist taped to your agent's desk. When you ask for a feature, the agent follows the checklist: ask when something is unclear, keep the change small, read the error before fixing it, and prove the work before saying it is done.
27
29
 
28
- `waitsec` acts as a brake: pause, verify, keep the change small, and fix the root problem.
30
+ If you have ever asked for a small change and got twelve new files, or reported a one line bug and watched the agent edit five unrelated files, waitsec is for that problem.
29
31
 
30
- ---
32
+ ## What "global" means
31
33
 
32
- ## The 5 Core Guardrails
34
+ When you install waitsec, the installer asks for a scope. That is only about where the rule files are saved.
33
35
 
34
- 1. **`ask-first`**: If the prompt is missing essential decisions (schemas, storage locations, permissions), the AI must pause and ask 1 to 3 direct questions instead of guessing.
35
- 2. **`anti-overengineering`**: Rejects unneeded design patterns, DTOs, and speculative abstractions. Keeps code lean while strictly enforcing authentication, authorization, and input validation.
36
- 3. **`small-diff`**: Modifications stay strictly scoped to what solves the prompt. No cleaning up surrounding files, no global formatting passes, and no unnecessary dependency changes.
37
- 4. **`debug-first`**: When something breaks, the AI must read the complete error message and stack trace. Never guess fixes or hide errors behind empty try/catch blocks.
38
- 5. **`verify-first`**: Never declare a task complete without proof. Run tests, verify builds, test edge cases, and ensure no regressions occurred before reporting done.
36
+ | Scope | Where the files go | Best for |
37
+ | :--- | :--- | :--- |
38
+ | **This project only** | Inside the current folder, for example `.agents/skills/` or `.claude/skills/`, plus a rules file | Teams. The rules travel with the repository and can be committed. |
39
+ | **Everywhere (Global)** | Your home directory, for example `~/.agents/skills` or `~/.claude/skills` | You. Every project on this computer gets the guardrails, even brand new ones. |
39
40
 
40
- ---
41
+ You can install both. A project install wins inside that project.
41
42
 
42
- ## Quick Install
43
+ Full explanation: [docs/installation.md](https://github.com/fastroware/waitsec/blob/main/docs/installation.md) or [Bahasa Indonesia](https://github.com/fastroware/waitsec/blob/main/docs/installation-id.md).
43
44
 
44
- ### 1. In Any Project (Recommended)
45
- Run this in your project terminal:
45
+ ## Features
46
46
 
47
- ```bash
48
- npx waitsec
49
- ```
47
+ | Skill | What it does | Use it when |
48
+ | :--- | :--- | :--- |
49
+ | `waitsec` | Core 5 guardrails: ask-first, anti-overengineering, small-diff, debug-first, verify-first | Always. This is the base every extension builds on. |
50
+ | `waitsec-pagemaker` | Builds clean web pages: project recon, design preferences, responsive layout, UX, SEO and GEO, Schema.org, auth pages, motion, 3D, and image sourcing | You build or redesign web pages. |
51
+ | `waitsec-code` | Clean code: no comment noise, small focused functions, no unnecessary dependencies | You write or refactor source code. |
52
+ | `waitsec-ui` | Frontend restraint: anti-slop visuals, mobile-first layout, clean UI copy | You work on UI or design systems. |
53
+ | `waitsec-quality` | Security auditing, realistic tests, safe database migrations | You touch auth, payments, tests, or migrations. |
50
54
 
51
- Pick your editor (Kilo Code, Cline, Cursor, or Antigravity), and the installer places the rules file directly in your workspace.
55
+ ## Install
52
56
 
53
- ### 2. Kilo Code or Cline (VS Code)
54
- Copy [rules/waitsec.md](rules/waitsec.md) to your project root as `.kilorules` (or `.clinerules`):
57
+ Use the interactive installer in your project folder. It handles every editor and puts the files in the right place:
55
58
 
56
59
  ```bash
57
- curl -o .kilorules https://raw.githubusercontent.com/fastroware/waitsec/main/rules/waitsec.md
60
+ npx waitsec
58
61
  ```
59
62
 
60
- You can also paste the contents of `rules/waitsec.md` into the **Custom Instructions** field in your Kilo Code extension settings.
63
+ All five skills are selected by default. Press `Space` to unselect any you do not want, then `Enter`.
61
64
 
62
- ### 3. Google Antigravity
63
- Install the plugin using the Antigravity CLI:
65
+ Prefer a non-interactive install? Use the universal skills CLI:
64
66
 
65
67
  ```bash
66
- agy plugin install https://github.com/fastroware/waitsec
67
- ```
68
-
69
- ### 4. Claude Code
70
- Add the marketplace and install:
71
-
72
- ```text
73
- /plugin marketplace add https://github.com/fastroware/waitsec
74
- /plugin install waitsec@waitsec
68
+ npx skills add fastroware/waitsec -y
75
69
  ```
76
70
 
77
- ### 5. Cursor
78
- Copy [rules/waitsec.md](rules/waitsec.md) to `.cursorrules` in your project root, or add this repository as a plugin under `.cursor-plugin/`.
79
-
80
- ### 6. Laravel / PHP (Composer)
81
- Install into your development dependencies:
71
+ ### Partial install
82
72
 
83
- ```bash
84
- composer require --dev waitsec/waitsec
85
- ```
86
-
87
- Then run the interactive setup command:
73
+ Partial install works for any extension, not just the page builder. Extensions depend on the core skill, so always include `waitsec`.
88
74
 
89
75
  ```bash
90
- vendor/bin/waitsec
76
+ npx skills add fastroware/waitsec --skill waitsec # core only
77
+ npx skills add fastroware/waitsec --skill waitsec waitsec-pagemaker # core plus page builder
78
+ npx skills add fastroware/waitsec --skill waitsec waitsec-ui # core plus UI
79
+ npx skills add fastroware/waitsec --skill waitsec waitsec-code # core plus code
80
+ npx skills add fastroware/waitsec --skill waitsec waitsec-quality # core plus quality
81
+
82
+ # several extensions at once
83
+ npx skills add fastroware/waitsec --skill waitsec waitsec-pagemaker waitsec-ui
91
84
  ```
92
85
 
93
- ### 7. Agent Skills Directory (skills.sh)
94
- Listed on [skills.sh/fastroware/waitsec](https://skills.sh/fastroware/waitsec).
86
+ In the interactive installer `npx waitsec`, you do this in the first prompt: all skills are checked, so just unselect the ones you do not want and keep the rest.
95
87
 
96
- The skills CLI does not pre-select anything for a GitHub repo, so you must choose at least one skill. To install every skill without any prompt:
88
+ ## How to use it
97
89
 
98
- ```bash
99
- npx skills add fastroware/waitsec -y
100
- ```
90
+ 1. Install it once, either for a project or globally.
91
+ 2. Open your project in your editor and work as usual.
92
+ 3. When a task matches a skill, the agent reads that skill and follows it. You do not run anything.
101
93
 
102
- To install only the core guardrails:
94
+ For example, just ask:
103
95
 
104
- ```bash
105
- npx skills add fastroware/waitsec --skill waitsec
106
- ```
96
+ - "Build a landing page for my SaaS."
97
+ - "Add a login page with a forgot password flow."
98
+ - "Fix this failing test."
99
+ - "Review this endpoint for security issues."
107
100
 
108
- To pick a specific set:
101
+ The full guide, including per-editor setup, manual install, update, uninstall, and troubleshooting, is here:
109
102
 
110
- ```bash
111
- npx skills add fastroware/waitsec --skill waitsec waitsec-pagemaker
112
- ```
103
+ - English: [docs/installation.md](https://github.com/fastroware/waitsec/blob/main/docs/installation.md)
104
+ - Bahasa Indonesia: [docs/installation-id.md](https://github.com/fastroware/waitsec/blob/main/docs/installation-id.md)
113
105
 
114
- Available skills:
106
+ ## Security notice
115
107
 
116
- | Skill | Purpose |
117
- | :--- | :--- |
118
- | `waitsec` | Core 5 guardrails: ask-first, anti-overengineering, small-diff, debug-first, verify-first |
119
- | `waitsec-pagemaker` | Page architect: project recon, design preferences, SEO/GEO, Schema.org, auth and UX rules |
120
- | `waitsec-code` | Clean code, anti-comment noise, dependency hygiene |
121
- | `waitsec-ui` | Anti-slop UI, responsive discipline, UI copy cleanup |
122
- | `waitsec-quality` | Security auditing, test discipline, migration safety |
108
+ Read this before you use waitsec.
123
109
 
124
- Tip: the CLI preselects all skills only when you install from a skills.sh pack URL. For a one-command install that selects everything by default, create a pack on [skills.sh](https://skills.sh) (sign in with Vercel, import this repository) and share the pack URL `https://skills.sh/p/<pack-id>`.
110
+ - waitsec is a set of instruction documents for AI agents. It is guidance, not a runtime library.
111
+ - We do not audit your application and we cannot guarantee that generated code, third party skills, or dependencies are safe, correct, or free of vulnerabilities.
112
+ - Skills run with the same permissions as your AI agent, which can read and write files and run commands on your machine. Always review what the agent changed before you run or ship it.
113
+ - Be especially careful with authentication, authorization, payments, secrets, and database migrations. Never let an agent push secrets or run destructive migrations unattended.
114
+ - The security advice inside these skills is advice only. You are responsible for testing and securing your own project.
125
115
 
126
- ---
116
+ In short: use waitsec to make your agent more careful, not as a guarantee that your code is secure.
127
117
 
128
118
  ## Structure
129
119
 
130
120
  ```text
131
121
  waitsec/
122
+ ├── docs/
123
+ │ ├── installation.md # Full install and usage guide (English)
124
+ │ └── installation-id.md # Panduan instalasi (Bahasa Indonesia)
132
125
  ├── skills/
133
- │ ├── waitsec/ # ACTIVE: Core 5-phase guardrails
126
+ │ ├── waitsec/ # Core 5-phase guardrails
134
127
  │ │ ├── SKILL.md # Hub: pipeline overview + links to detail files
135
- │ │ └── references/ # Deep-dive guardrails & UI copy rules
136
- │ │ ├── ask-first.md # Phase 1: Clarify requirements before coding
137
- │ │ ├── anti-overengineering.md # Phase 2: Lean code + non-negotiable security
138
- │ │ ├── small-diff.md # Phase 3: Surgical, proportional edits only
139
- │ │ ├── debug-first.md # Phase 4: Root cause analysis before guessing
140
- │ │ ├── verify-first.md # Phase 5: Proof before declaring done
141
- │ │ └── write-info-analyzer.md # Simple rules for UI text and clean labels
142
- │ │
143
- │ ├── waitsec-ui/ # ACTIVE: Anti-slop CSS, UI copy restraint, responsive
128
+ │ │ └── references/ # Deep-dive guardrails and UI copy rules
129
+ │ │ ├── ask-first.md
130
+ │ │ ├── anti-overengineering.md
131
+ │ │ ├── small-diff.md
132
+ │ │ ├── debug-first.md
133
+ │ │ ├── verify-first.md
134
+ │ │ └── write-info-analyzer.md
135
+ │ ├── waitsec-ui/ # Anti-slop CSS, UI copy restraint, responsive
144
136
  │ │ └── SKILL.md
145
- │ ├── waitsec-pagemaker/ # ACTIVE: Page architect (landing, blog, articles, auth, contact)
137
+ │ ├── waitsec-pagemaker/ # Page architect (landing, blog, articles, auth, contact)
146
138
  │ │ ├── SKILL.md # Recon, design preferences, SEO/GEO, Schema.org, UX
147
139
  │ │ └── references/ # Blueprints per archetype
148
140
  │ │ ├── landing-page.md
@@ -150,57 +142,48 @@ waitsec/
150
142
  │ │ ├── article-single.md
151
143
  │ │ ├── about-me.md
152
144
  │ │ ├── contact-page.md
153
- │ │ └── auth-pages.md # Login, register, password reset, lockout states
154
- │ ├── waitsec-code/ # ACTIVE: Clean code, anti-comment pollution
145
+ │ │ ├── auth-pages.md # Login, register, password reset, lockout states
146
+ │ │ ├── motion-and-3d.md # anime.js motion, parallax, three.js 3D
147
+ │ │ └── image-sourcing.md # Reuse project media, Pexels fallback, aspect ratios
148
+ │ ├── waitsec-code/ # Clean code, anti-comment pollution
155
149
  │ │ └── SKILL.md
156
- │ └── waitsec-quality/ # ACTIVE: Security auditing, testing discipline
150
+ │ └── waitsec-quality/ # Security auditing, testing discipline
157
151
  │ └── SKILL.md
158
152
  │
159
153
  ├── rules/
160
154
  │ ├── AGENTS.md # Universal rule pointer (Antigravity / Claude Code)
161
155
  │ └── waitsec.md # All-in-one bundled rules (Kilo Code / Cline / Cursor)
156
+ ├── assets/
157
+ │ ├── banner-waitsec.png
158
+ │ └── logo-waitsec.png
162
159
  ├── bin/
163
160
  │ └── cli.mjs # Interactive terminal installer (Clack prompts)
161
+ ├── skills.sh.json # skills.sh repo page grouping
164
162
  ├── plugin.json # Antigravity plugin manifest
165
163
  ├── package.json # npm / npx manifest
166
164
  └── composer.json # Composer / Laravel manifest
167
165
  ```
168
166
 
169
- ---
170
-
171
- ## Roadmap: Core & Extensions
172
-
173
- - **Core (Active)**: The 5 foundational guardrails (`ask-first`, `anti-overengineering`, `small-diff`, `debug-first`, `verify-first`).
174
- - **Extensions (Active)**: `waitsec-pagemaker` for page building, `waitsec-code` for code hygiene, `waitsec-ui` for UI restraint, and `waitsec-quality` for security and testing discipline.
175
-
176
- ---
177
-
178
167
  ## Feedback, Bugs & Contributing
179
168
 
180
169
  Found a bug, want to suggest a new guardrail, or want to contribute? Everything is tracked through GitHub.
181
170
 
182
- ### 1. Found a Bug or Have a Complaint?
183
- If an AI agent bypassed a guardrail, generated unexpected boilerplate, or an installer command failed:
171
+ ### 1. Found a bug or have a complaint?
172
+ If an agent bypassed a guardrail, generated unexpected boilerplate, or an installer command failed:
184
173
  1. Go to [GitHub Issues](https://github.com/fastroware/waitsec/issues).
185
174
  2. Click **New Issue**.
186
- 3. Include:
187
- - Your AI assistant or editor (Cursor, Claude Code, Antigravity, Kilo, Cline).
188
- - The prompt you ran.
189
- - What the agent did wrong and what behavior was expected instead.
175
+ 3. Include your editor, the prompt you ran, and what the agent did wrong.
190
176
 
191
- ### 2. Suggesting a New Guardrail or Feature
192
- If you have an idea for a rule that prevents AI slop in specific languages or workflows:
177
+ ### 2. Suggesting a new guardrail or feature
193
178
  1. Open a ticket on [GitHub Issues](https://github.com/fastroware/waitsec/issues) titled `[Feature] your idea`.
194
- 2. Provide a before-and-after example showing the bad AI output vs the desired clean solution.
179
+ 2. Provide a before-and-after example showing the bad output and the clean solution.
195
180
 
196
- ### 3. Submitting a Pull Request
181
+ ### 3. Submitting a pull request
197
182
  1. Fork this repository on GitHub.
198
- 2. Create a feature branch: `git checkout -b feature/my-guardrail`.
199
- 3. Keep instructions concise, actionable, and strictly free of generic AI slop.
183
+ 2. Create a branch: `git checkout -b feature/my-guardrail`.
184
+ 3. Keep instructions concise, actionable, and free of generic AI slop.
200
185
  4. Submit a **Pull Request** to `main`.
201
186
 
202
- ---
203
-
204
187
  ## License
205
188
 
206
189
  MIT
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "waitsec",
3
- "version": "0.5.5",
3
+ "version": "0.5.9",
4
4
  "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
5
5
  "main": "rules/waitsec.md",
6
6
  "bin": {
package/plugin.json CHANGED
@@ -1,5 +1,5 @@
1
1
  {
2
2
  "name": "waitsec",
3
3
  "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
4
- "version": "0.5.5"
4
+ "version": "0.5.9"
5
5
  }
package/skills/waitsec-pagemaker/SKILL.md CHANGED
@@ -27,6 +27,9 @@ Treat this section as the prompt you must satisfy every time you generate a page
27
27
  10. **Meet the SEO and GEO bar.** One H1, a unique title and meta description, a canonical URL, Open Graph tags, and answer-first content that machines can quote.
28
28
  11. **Finish with the Pre-Flight Checklist.** Do not report the page as done until every box is checked.
29
29
  12. **Translate vague style words.** When the user says minimalist, modern, clean, premium, bold, or similar, convert the word into concrete tokens using Part 10, reuse the project tokens first, and state the translation before generating. Never treat a style word as a license for gradients, glass, or heavy shadows.
30
+ 13. **Motion must earn its place.** Reuse the project's motion library, or anime.js when real motion is requested: CDN in static projects, npm in build projects. Animate only `transform` and `opacity`, and honor `prefers-reduced-motion`.
31
+ 14. **3D only when it explains something.** Use three.js or the project's 3D library, lazy-load it after the content, cap the device pixel ratio, and always provide a poster and a no-WebGL fallback.
32
+ 15. **Reuse the project's images first.** Only when no existing image fits, source from Pexels with no identifiable people (prefer plants, landscapes, and textures), match the slot's aspect ratio, and vendor important images.
30
33
 
31
34
  ---
32
35
 
@@ -42,6 +45,8 @@ Activate this skill whenever:
42
45
  - Writing layout containers, responsive grids, navigation bars, and design themes.
43
46
  - Adding SEO metadata, Open Graph tags, or Schema.org structured data to a page.
44
47
  - Building authentication screens (login, register, password reset) or account lockout and rate-limit pages.
48
+ - Adding animation, parallax, scroll effects, or 3D graphics to a page.
49
+ - Choosing, sourcing, or placing images and other media on a page.
45
50
 
46
51
  ---
47
52
 
@@ -115,7 +120,22 @@ Report the final decision in one line: styling system, load method (local or CDN
115
120
  ```
116
121
  - Never hand-write raw inline SVG markup. Never use an emoji as an icon. Never use a raster image as a stand-in for a UI icon.
117
122
 
118
- ### 6. Hard Content Rules
123
+ ### 6. Detect Motion, 3D, and Media Assets
124
+
125
+ Find out what animation, 3D, and image tooling already exists before adding any:
126
+
127
+ - **Motion libraries:** GSAP, anime.js, Framer Motion, Motion One, AOS, ScrollReveal. Check `package.json` and script tags. Record the version and whether it loads locally or from a CDN.
128
+ - **3D libraries:** three.js, `@react-three/fiber`, Babylon.js, `model-viewer`. Record the same details.
129
+ - **Media assets:** scan `public/`, `public/images/`, `assets/`, `static/`, `img/`, `images/`, `resources/`, `storage/`, `uploads/`, and `media/` for existing logos, product shots, and photos. Note formats and dimensions.
130
+
131
+ Then decide:
132
+
133
+ 1. Reuse the motion or 3D library already in the project.
134
+ 2. Use the project's own images before sourcing any new ones.
135
+ 3. If the user asks for animation, parallax, or 3D, follow [`references/motion-and-3d.md`](./references/motion-and-3d.md).
136
+ 4. If the project has no suitable image for a slot, follow [`references/image-sourcing.md`](./references/image-sourcing.md).
137
+
138
+ ### 7. Hard Content Rules
119
139
 
120
140
  These rules apply to every generated page without exception:
121
141
 
@@ -124,7 +144,7 @@ These rules apply to every generated page without exception:
124
144
  - No em dash and no en dash. Use colons, commas, periods, parentheses, or plain hyphens.
125
145
  - Icons come from the detected icon library or from Lucide CDN.
126
146
 
127
- ### 7. State Findings and Ask Only What Matters
147
+ ### 8. State Findings and Ask Only What Matters
128
148
 
129
149
  Post a short recon summary before building, for example:
130
150
 
@@ -132,7 +152,7 @@ Post a short recon summary before building, for example:
132
152
 
133
153
  Then ask at most one or two questions, only about decisions that are expensive to reverse (styling system, template target, icon library). Everything else uses sensible defaults, and you state the defaults you chose.
134
154
 
135
- ### 8. Recon Pitfalls
155
+ ### 9. Recon Pitfalls
136
156
 
137
157
  #### 1. Assuming the Stack
138
158
 
@@ -729,6 +749,28 @@ Local slang works the same way. "Estetik", "kece", "clean banget", "kayak startu
729
749
 
730
750
  ---
731
751
 
752
+ ## Part 11: Motion, 3D & Media Routing
753
+
754
+ ### 1. Animation and Parallax
755
+
756
+ When the user asks for animation, parallax, or scroll effects, read [`references/motion-and-3d.md`](./references/motion-and-3d.md). Default to anime.js, reuse any existing motion library, use a pinned CDN for static projects and npm for build projects, animate only `transform` and `opacity`, and honor `prefers-reduced-motion`.
757
+
758
+ ### 2. 3D and Graphics
759
+
760
+ When the user asks for 3D or other graphics, read the same guide. Default to three.js, lazy-load it after the content, cap the device pixel ratio, and always ship a poster image and a no-WebGL fallback. If a static image or a short video does the job, prefer that instead.
761
+
762
+ ### 3. Images and Media
763
+
764
+ When the page needs images, read [`references/image-sourcing.md`](./references/image-sourcing.md). Scan the project's asset folders first and reuse what exists. Only when nothing fits, source from Pexels with no identifiable people, preferring close-up plants, landscapes, and textures, and match the image ratio to the slot.
765
+
766
+ ### 4. Load Method
767
+
768
+ - Static project without a build step: load anime.js or three.js from a pinned CDN.
769
+ - Project with a build step: install locally and import only what is used.
770
+ - Always report the library, version, and load method before generating.
771
+
772
+ ---
773
+
732
774
  ## Pre-Flight Checklist
733
775
 
734
776
  Before returning generated page code to the user, verify:
@@ -752,3 +794,7 @@ Before returning generated page code to the user, verify:
752
794
  - [ ] If the requested page is outside the listed archetypes, did I state the closest blueprint I adapted and keep the general preferences?
753
795
  - [ ] If the user gave a vague style word, did I translate it into concrete tokens (palette, type, spacing, radius, border and shadow policy, motion) and state the translation?
754
796
  - [ ] Did I reuse the project's design tokens before inventing new ones?
797
+ - [ ] If animation was requested, did I reuse or add the motion library with the right load method, and honor `prefers-reduced-motion`?
798
+ - [ ] If 3D was requested, is it lazy-loaded with a poster and a no-WebGL fallback?
799
+ - [ ] Did I check the project's own images first, and if sourcing, avoid people and match the aspect ratio?
800
+
package/skills/waitsec-pagemaker/references/image-sourcing.md ADDED
@@ -0,0 +1,113 @@
1
+ # Image Sourcing Blueprint (waitsec-pagemaker)
2
+
3
+ Use this guide when a page needs images. The rule is simple: reuse the project's own media first. Only go external when the project has nothing that fits.
4
+
5
+ ---
6
+
7
+ ## Part 1: Check the Project First
8
+
9
+ Before downloading anything, look for existing media:
10
+
11
+ - Common folders: `public/`, `public/images/`, `assets/`, `static/`, `img/`, `images/`, `resources/`, `storage/`, `uploads/`, `media/`.
12
+ - Also check template asset folders, CMS uploads, and existing CDN configuration.
13
+ - List what exists: logos, product shots, icons, backgrounds, photos. Note the format, dimensions, and license.
14
+ - Prefer an existing image over a new one. Reuse keeps the bundle small and the brand consistent.
15
+ - If an existing image only needs cropping, resizing, or compression, do that instead of downloading a new one.
16
+ - Never replace a project's real product screenshots with generic stock photos.
17
+
18
+ ## Part 2: When to Source Externally
19
+
20
+ Only source externally when the project has no suitable image for the section.
21
+
22
+ - Default source: **Pexels**, which is royalty-free. Use the Pexels CDN URL or download into the project's asset folder.
23
+ - Content rules, in order of priority:
24
+ - **No identifiable people.** Skip faces, crowds, portraits, and hands. The user asked for no people.
25
+ - Prefer close-up plants, leaves, flowers, moss, water, rocks, textures, landscapes, mountains, sky, and abstract nature.
26
+ - No text, watermarks, brand logos, or recognizable trademarks inside the photo.
27
+ - No violent, political, medical, or otherwise sensitive imagery.
28
+ - Because Pexels has no reliable "no people" filter, verify each chosen image visually before using it. If a person appears even in the background, pick another.
29
+
30
+ ## Part 3: Match the Aspect Ratio
31
+
32
+ Pick the image ratio that matches the slot, and set explicit `width` and `height` so the layout does not shift.
33
+
34
+ | Slot | Ratio | Suggested size |
35
+ | :--- | :--- | :--- |
36
+ | Hero | 16:9 | 1600x900 |
37
+ | Wide banner | 21:9 | 2100x900 |
38
+ | Card thumbnail | 4:3 | 800x600 |
39
+ | Square card or avatar | 1:1 | 600x600 or 400x400 |
40
+ | Open Graph image | 1.91:1 | 1200x630 |
41
+ | Full-bleed section | 16:9 desktop, 4:5 mobile crop | 1600x900 and 1000x1250 |
42
+
43
+ Request the right size and crop from Pexels with URL parameters, for example:
44
+
45
+ ```text
46
+ https://images.pexels.com/photos/<id>/pexels-photo-<id>.jpeg?auto=compress&cs=tinysrgb&w=1600&h=900&fit=crop
47
+ ```
48
+
49
+ Adjust `w` and `h` to the slot ratio. Use `fit=crop` so the subject stays centered instead of stretched.
50
+
51
+ ## Part 4: Delivery
52
+
53
+ - When the project vendors its own media, download the image into the asset folder instead of hotlinking in production.
54
+ - For quick static pages, a direct Pexels CDN URL is acceptable, but record the URL so it can be replaced later.
55
+ - Compress to WebP or AVIF when the stack supports it. Keep a JPEG or PNG fallback only if needed.
56
+ - Load below-the-fold images with `loading="lazy"` and `decoding="async"`.
57
+ - Load the hero image eagerly with `fetchpriority="high"` so it does not delay Largest Contentful Paint.
58
+ - Always set a descriptive `alt`. Decorative images get `alt=""`.
59
+ - When a license or project rule requires it, record the source and credit in a comment or a credits file.
60
+
61
+ ## Part 5: Pitfalls
62
+
63
+ ### 1. Downloading New Images When the Project Already Has Them
64
+
65
+ * **The Bad Habit:** Reaching for a stock photo before checking the project's own asset folders.
66
+ * **The Problem:** The page ends up with two visual styles, and the real product shots go unused.
67
+ * **Why It Fails:** Inconsistent branding looks unprofessional, and the bundle grows for no reason.
68
+ * **Clean Fix:** Scan `public/`, `assets/`, `static/`, and `storage/` first. Reuse or lightly crop what exists.
69
+ * **The Waitsec Way:** The project's own media is the source of truth. Add only what is truly missing.
70
+
71
+ ### 2. People in Stock Photos
72
+
73
+ * **The Bad Habit:** Dropping a smiling stock model into a hero because the search looked good.
74
+ * **The Problem:** A generic person weakens the message and often clashes with the brand.
75
+ * **Why It Fails:** It reads as filler, and the user explicitly asked for images without people.
76
+ * **Clean Fix:** Filter and visually verify for no people. Prefer plants, landscapes, and textures.
77
+ * **The Waitsec Way:** Choose imagery that supports the message, not a face that distracts from it.
78
+
79
+ ### 3. Wrong Aspect Ratio
80
+
81
+ * **The Bad Habit:** Using a long landscape photo inside a square card, or stretching an image to fit.
82
+ * **The Problem:** The subject gets cropped badly or the image looks distorted.
83
+ * **Why It Fails:** Broken proportions look careless and hurt trust.
84
+ * **Clean Fix:** Request or crop the exact ratio the slot needs, and use `object-fit: cover` for flexible containers.
85
+ * **The Waitsec Way:** Match the media to the frame. Do not force the frame to the media.
86
+
87
+ ### 4. Hotlinking Unstable URLs in Production
88
+
89
+ * **The Bad Habit:** Pointing production pages at a temporary stock URL that later changes or disappears.
90
+ * **The Problem:** The image breaks and the section renders empty.
91
+ * **Why It Fails:** Broken images look like a bug and can take down a hero.
92
+ * **Clean Fix:** Download and vendor important images, or record and verify every external URL.
93
+ * **The Waitsec Way:** Own the assets your page depends on.
94
+
95
+ ### 5. Unsized Images Causing Layout Shift
96
+
97
+ * **The Bad Habit:** Inserting images with no width or height, or with only a CSS width.
98
+ * **The Problem:** The page jumps as images load and text shifts position.
99
+ * **Why It Fails:** Layout shift is jarring and it hurts Core Web Vitals and SEO.
100
+ * **Clean Fix:** Set explicit `width` and `height` attributes that match the ratio, and let CSS scale them down.
101
+ * **The Waitsec Way:** Reserve the space before the pixels arrive.
102
+
103
+ ---
104
+
105
+ ## Pre-Flight Checklist for Image Sourcing
106
+
107
+ - [ ] Did I check the project's own asset folders before sourcing new images?
108
+ - [ ] Does every external image come from a royalty-free source such as Pexels, with no identifiable people?
109
+ - [ ] Does each image's aspect ratio match its slot (hero 16:9, card 4:3 or 1:1, Open Graph 1200x630)?
110
+ - [ ] Are important images downloaded and vendored instead of hotlinked in production?
111
+ - [ ] Do all images have explicit width and height to prevent layout shift?
112
+ - [ ] Are below-the-fold images lazy, and is the hero image prioritized?
113
+ - [ ] Does every meaningful image have a descriptive `alt`, with `alt=""` for decorative ones?
package/skills/waitsec-pagemaker/references/motion-and-3d.md ADDED
@@ -0,0 +1,179 @@
1
+ # Motion & 3D Blueprint (waitsec-pagemaker)
2
+
3
+ Use this guide when a page needs animation, parallax, scroll effects, or 3D graphics. Motion and 3D are expensive, so they must earn their place and must never block the content.
4
+
5
+ ---
6
+
7
+ ## Part 1: Motion & Animation
8
+
9
+ ### 1. When Motion Is Allowed
10
+
11
+ - Only when it communicates state or hierarchy: entrances, transitions, feedback, progress, or drawing attention to something that just changed.
12
+ - Never as looping decoration, never to hide slow loading, and never to delay the content.
13
+ - Parallax, scroll reveals, and hero animation are allowed when the user explicitly asks for them.
14
+
15
+ ### 2. Choose the Library
16
+
17
+ - If the project already has a motion library (GSAP, Framer Motion, Motion One, AOS, anime.js), use it.
18
+ - If the user names a library, use that.
19
+ - Otherwise, for scroll and timeline animation, default to **anime.js**.
20
+ - Static project or no build step: load from CDN.
21
+ - Project with a build step: install through the package manager and import only what is used.
22
+ - Keep small reveals in plain CSS. Do not pull in a library just for a simple fade.
23
+
24
+ ### 3. anime.js Rules
25
+
26
+ - Load the CDN build only when there is no build step:
27
+ ```html
28
+ <script src="https://cdn.jsdelivr.net/npm/animejs@3.2.2/lib/anime.min.js"></script>
29
+ ```
30
+ - For npm projects: `npm i animejs` and import only the functions you use.
31
+ - Animate `transform` and `opacity` only. Never animate layout properties (`width`, `height`, `top`, `margin`) because they thrash the browser.
32
+ - Keep durations short: 150ms to 400ms for UI, up to 800ms for a hero reveal. Keep easing consistent.
33
+ - Start animations on view with `IntersectionObserver`, not on page load.
34
+ - Respect `prefers-reduced-motion`: skip or reduce the motion.
35
+ - Never animate more than a few elements at once. Reveal long lists in groups.
36
+
37
+ ### 4. Parallax Rules
38
+
39
+ - Keep parallax subtle. A background that moves a lot is nauseating and hurts reading.
40
+ - Never parallax body text. Move only backgrounds or decorative layers.
41
+ - Use `transform: translate3d()` and `will-change` during the animation, then remove `will-change`.
42
+ - Provide a static layout when motion is disabled or the device is low power.
43
+
44
+ ### 5. Motion Pitfalls
45
+
46
+ #### 1. Motion on Everything
47
+
48
+ * **The Bad Habit:** Animating every section, card, and button on entrance.
49
+ * **The Problem:** The page feels busy, and the user waits for content to settle before reading.
50
+ * **Why It Fails:** Decoration competes with the message, and repeated motion tires the eye.
51
+ * **Clean Fix:** Animate only what changes state or needs attention. Prefer one calm reveal per section.
52
+ * **The Waitsec Way:** Motion is a signal, not wallpaper. Use it only when it means something.
53
+
54
+ #### 2. Layout-Thrashing Animation
55
+
56
+ * **The Bad Habit:** Animating `width`, `top`, or `margin` to move or resize an element.
57
+ * **The Problem:** Every frame forces the browser to recalculate layout, so the animation stutters.
58
+ * **Why It Fails:** Jank on mid-range phones makes the page feel broken, and the battery drain is real.
59
+ * **Clean Fix:** Animate `transform` and `opacity` only. Move elements with `translate`, resize with `scale`.
60
+ * **The Waitsec Way:** Animate the cheap properties. Keep the main thread free.
61
+
62
+ #### 3. Ignoring prefers-reduced-motion
63
+
64
+ * **The Bad Habit:** Shipping full parallax and auto-playing animation with no reduced-motion path.
65
+ * **The Problem:** Users with motion sensitivity get a page they cannot comfortably use.
66
+ * **Why It Fails:** It is an accessibility failure, and some people will close the tab immediately.
67
+ * **Clean Fix:** Wrap motion in `@media (prefers-reduced-motion: reduce)` and disable or shorten it.
68
+ * **The Waitsec Way:** Motion is optional for the user. Always offer the still version.
69
+
70
+ #### 4. Scroll Jank From Too Many Observers
71
+
72
+ * **The Bad Habit:** Creating an `IntersectionObserver` per element and animating dozens at once.
73
+ * **The Problem:** Many observers and simultaneous animations overload the main thread.
74
+ * **Why It Fails:** Scrolling stutters on mobile, which is where most visitors are.
75
+ * **Clean Fix:** Use one shared observer, animate in small groups, and stop observing after the reveal.
76
+ * **The Waitsec Way:** Budget the work per frame. Fewer, cleaner animations win.
77
+
78
+ #### 5. Animation That Blocks First Paint
79
+
80
+ * **The Bad Habit:** Loading a heavy motion library in the head and starting animation before content renders.
81
+ * **The Problem:** The hero stays invisible or half-drawn while the script loads.
82
+ * **Why It Fails:** Largest Contentful Paint suffers, and users see a blank or frozen screen.
83
+ * **Clean Fix:** Load motion after the content, keep it small, and never hide content behind an animation gate.
84
+ * **The Waitsec Way:** Content comes first. Motion loads after.
85
+
86
+ ---
87
+
88
+ ## Part 2: 3D with three.js
89
+
90
+ ### 1. When 3D Is Allowed
91
+
92
+ - Only when 3D is the product or genuinely helps explain it: a product viewer, a configurator, a data globe, or a hero centerpiece.
93
+ - Never for a generic spinning cube or a decorative background that adds no meaning.
94
+ - If a static image or a short video explains it just as well, use that instead.
95
+
96
+ ### 2. Choose the Library
97
+
98
+ - If the project already uses three.js, `@react-three/fiber`, or Babylon.js, use it.
99
+ - Otherwise default to **three.js**: CDN for static pages, npm for build projects.
100
+ - Import only the modules you need, or use a tree-shakeable build, so the bundle stays small.
101
+
102
+ ### 3. Performance Rules
103
+
104
+ - Lazy-load the 3D bundle after the main content. It must not block Largest Contentful Paint.
105
+ - Cap the device pixel ratio at 2 so high-DPI phones do not render four times the pixels.
106
+ - Keep geometry low-poly, compress textures (KTX2 or WebP), and use instancing for repeated meshes.
107
+ - Pause rendering when the canvas is off-screen or the tab is hidden.
108
+ - Provide a poster image and a static fallback for devices without WebGL.
109
+ - Respect `prefers-reduced-motion`: no fast or perpetual auto-rotation.
110
+
111
+ ### 4. Accessibility and Fallback
112
+
113
+ - A canvas is not accessible text. Always provide an equivalent description or a labeled image.
114
+ - The page must stay fully usable if the 3D layer fails to load.
115
+ - Never trap focus or block page scrolling on the canvas.
116
+
117
+ ### 5. 3D Pitfalls
118
+
119
+ #### 1. 3D as Decoration
120
+
121
+ * **The Bad Habit:** Adding a rotating 3D object to the hero because it looks impressive.
122
+ * **The Problem:** It adds weight and load time without explaining anything.
123
+ * **Why It Fails:** The page gets slower, and visitors still do not understand the product better.
124
+ * **Clean Fix:** Use 3D only when interaction with a real object is the point. Otherwise use an image or video.
125
+ * **The Waitsec Way:** 3D must do a job. If it only decorates, remove it.
126
+
127
+ #### 2. Blocking First Paint
128
+
129
+ * **The Bad Habit:** Importing three.js at the top of the bundle and rendering before the page content.
130
+ * **The Problem:** The whole page waits on a large 3D library.
131
+ * **Why It Fails:** Slow first paint loses visitors before they see anything.
132
+ * **Clean Fix:** Code-split the 3D module, load it after content, and show a poster until it is ready.
133
+ * **The Waitsec Way:** Never let a feature starve the page it lives on.
134
+
135
+ #### 3. Ignoring Mobile GPU Limits
136
+
137
+ * **The Bad Habit:** Shipping high-poly models and uncompressed textures straight from the desktop build.
138
+ * **The Problem:** Mid-range phones drop frames or fail to render at all.
139
+ * **Why It Fails:** The centerpiece becomes a stutter or a blank box on the devices most people use.
140
+ * **Clean Fix:** Lower the polygon count, compress textures, cap the pixel ratio, and test on a mid-range phone.
141
+ * **The Waitsec Way:** Design for the weakest device that matters, then enhance upward.
142
+
143
+ #### 4. No Fallback
144
+
145
+ * **The Bad Habit:** Assuming WebGL always works and rendering nothing else.
146
+ * **The Problem:** Older devices and blocked GPUs see an empty rectangle.
147
+ * **Why It Fails:** A blank centerpiece looks broken and hides the product.
148
+ * **Clean Fix:** Detect WebGL, show a poster image and the key text when it is missing.
149
+ * **The Waitsec Way:** Every heavy feature needs a light path.
150
+
151
+ #### 5. Perpetual Motion
152
+
153
+ * **The Bad Habit:** Auto-rotating the model forever at high speed.
154
+ * **The Problem:** It distracts, drains battery, and bothers motion-sensitive users.
155
+ * **Why It Fails:** The eye keeps chasing the motion instead of reading the page.
156
+ * **Clean Fix:** Rotate slowly only on interaction, pause when idle, and honor reduced-motion.
157
+ * **The Waitsec Way:** Let the user drive the motion.
158
+
159
+ ---
160
+
161
+ ## Part 3: Load Method and Version
162
+
163
+ 1. Detect any existing motion or 3D library and version in the project, then reuse it.
164
+ 2. Static project without a build step: load from a CDN and pin the version.
165
+ 3. Project with a build step: install locally and import only what is used.
166
+ 4. Report the library, version, and load method before generating.
167
+ 5. If the user asked for motion or 3D but the page does not need it, say so and offer the simpler option.
168
+
169
+ ---
170
+
171
+ ## Pre-Flight Checklist for Motion & 3D
172
+
173
+ - [ ] Did I reuse the project's existing motion or 3D library before adding a new one?
174
+ - [ ] Is the library loaded from a pinned CDN in static projects and installed locally in build projects?
175
+ - [ ] Do animations use only `transform` and `opacity`, with short durations and consistent easing?
176
+ - [ ] Does `prefers-reduced-motion` disable or reduce all motion?
177
+ - [ ] Is 3D loaded after the main content, with a poster image and a no-WebGL fallback?
178
+ - [ ] Is the device pixel ratio capped and the model or texture budget kept small?
179
+ - [ ] Does the page stay fully usable if the motion or 3D layer never loads?