waitsec 0.1.2 → 0.3.0

package/.cursor-plugin/plugin.json

@@ -2,7 +2,7 @@
   "name": "waitsec",
   "displayName": "waitsec",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "author": {
     "name": "fastroware"
   },

package/README.md

@@ -19,19 +19,13 @@ Most AI coding assistants do not fail because they lack knowledge. They fail bec
 
 ---
 
-## The 4 Core Guardrails
+## The 5 Core Guardrails
 
-### 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.
-
-### 2. `anti-overengineering`
-The AI must use existing patterns in your codebase and pick the simplest working solution. No speculative abstractions for hypothetical future needs.
-
-### 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.
-
-### 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.
+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.
+2. **`anti-overengineering`** — Rejects unneeded design patterns, DTOs, and speculative abstractions. Keeps code lean while strictly enforcing authentication, authorization, and input validation.
+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.
+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.
+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.
 
 ---
 
@@ -83,10 +77,20 @@ composer require --dev waitsec/waitsec
 The post-install script automatically adds `.kilorules` to your root directory.
 
 ### 7. Agent Skills Directory (skills.sh)
-Install via the universal skills CLI:
+Install the full core bundle (recommended):
+
+```bash
+npx skills add fastroware/waitsec/skills/waitsec-core
+```
+
+Or install only the module you need:
 
 ```bash
-npx skills add fastroware/waitsec
+# Individual guardrails
+npx skills add fastroware/waitsec/skills/waitsec-core  # All 5 guardrails
+npx skills add fastroware/waitsec/skills/waitsec-quality  # Upcoming
+npx skills add fastroware/waitsec/skills/waitsec-code     # Upcoming
+npx skills add fastroware/waitsec/skills/waitsec-ui       # Upcoming
 ```
 
 ---
@@ -96,26 +100,42 @@ npx skills add fastroware/waitsec
 ```text
 waitsec/
 ├── skills/
-│   ├── ask-first/             # Clarify ambiguous requirements first
-│   │   └── SKILL.md
-│   ├── anti-overengineering/  # Stop bloat and unnecessary abstractions
+│   ├── waitsec-core/              # ACTIVE — Core 5-phase guardrails
+│   │   ├── SKILL.md               # Hub: pipeline overview + links to detail files
+│   │   ├── ask-first.md           # Phase 1: Clarify requirements before coding
+│   │   ├── anti-overengineering.md # Phase 2: Lean code + non-negotiable security
+│   │   ├── small-diff.md          # Phase 3: Surgical, proportional edits only
+│   │   ├── debug-first.md         # Phase 4: Root cause analysis before guessing
+│   │   └── verify-first.md        # Phase 5: Proof before declaring done
+│   │
+│   ├── waitsec-quality/           # UPCOMING — Security auditing, testing discipline
 │   │   └── SKILL.md
-│   ├── small-diff/            # Keep changes surgical and small
+│   ├── waitsec-code/              # UPCOMING — Clean code, anti-comment pollution
 │   │   └── SKILL.md
-│   └── debug-first/           # Trace real root causes before editing
+│   └── waitsec-ui/                # UPCOMING — Anti-slop CSS, responsive guardrails
 │       └── SKILL.md
+│
 ├── rules/
-│   ├── AGENTS.md              # Universal rule pointer
-│   └── waitsec.md             # All-in-one bundled rules
+│   ├── AGENTS.md                  # Universal rule pointer (Antigravity / Claude Code)
+│   └── waitsec.md                 # All-in-one bundled rules (Kilo Code / Cline / Cursor)
 ├── bin/
-│   └── cli.js                 # Interactive terminal installer
-├── plugin.json                # Antigravity plugin manifest
-├── package.json               # npm / npx manifest
-└── composer.json              # Composer / Laravel manifest
+│   └── cli.js                     # Interactive terminal installer
+├── plugin.json                    # Antigravity plugin manifest
+├── package.json                   # npm / npx manifest
+└── composer.json                  # Composer / Laravel manifest
 ```
 
 ---
 
+## Roadmap: Core & Extensions
+
+- **Core (Active)**: The 5 foundational guardrails (`ask-first`, `anti-overengineering`, `small-diff`, `debug-first`, `verify-first`).
+- **Quality (Upcoming)**: Specialized deep-dives for `security`, `testing`, `performance`, and `accessibility`.
+- **Code (Upcoming)**: Anti-slop comments, naming conventions, and dependency discipline.
+- **UI (Upcoming)**: Anti-slop interface rules, responsive standards, and clean typography.
+
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waitsec",
-  "version": "0.1.2",
+  "version": "0.3.0",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
   "main": "rules/waitsec.md",
   "bin": {

package/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "waitsec",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
-  "version": "0.1.2"
+  "version": "0.3.0"
 }

package/rules/AGENTS.md

@@ -1,8 +1,10 @@
 # waitsec
 
-Wait a second before coding. Follow these four core guardrails:
+Wait a second before coding. Follow these five core guardrails:
 
 1. **Ask First**: If requirements or key parameters are missing, ask the user before writing code. Do not invent requirements.
-2. **Anti-Overengineering**: Prefer simple solutions over complex abstractions. Use patterns already in the codebase.
-3. **Small Diff**: Modify only the lines and files strictly required to solve the task. Do not touch unrelated code.
-4. **Debug First**: Inspect error logs and find the root cause before editing code. Never guess.
+2. **Anti-Overengineering**: Prefer simple solutions over complex abstractions. Build for today's needs, not hypothetical futures. **Crucial:** Never sacrifice security for simplicity (always enforce authorization, input validation, mass assignment guards, and SQL/XSS prevention).
+3. **Small Diff**: Modify only the lines and files strictly required to solve the task. Do not touch unrelated code or reformat global files.
+4. **Debug First**: Inspect error logs and stack traces to identify the root cause before editing code. Never guess.
+5. **Verify First**: Never declare completion without proof. Run tests, build commands, and verify edge cases before closing.
+

package/rules/waitsec.md

@@ -1,26 +1,42 @@
 # waitsec: AI Coding Guardrails
 
-You follow the waitsec discipline: hold on, think first, and keep changes minimal.
+You follow the waitsec discipline: hold on, think first, code less, and keep security airtight.
 
 ## 1. Ask First (Clarify Ambiguity)
 - Before writing code, check whether the request is clear.
-- If essential choices are missing (data schemas, file locations, permissions, storage limits), pause and ask the user 1 to 3 direct questions.
-- If details are minor, pick the simplest reasonable default and proceed without cluttering the chat.
-- Never invent product requirements out of nowhere.
+- If essential choices are missing (data schemas, storage targets, permissions, limits), pause and ask the user 1 to 3 direct questions with concrete choices (A/B).
+- If details are minor or standard, pick the simplest reasonable default and proceed without interrogating the user.
+- Never invent business rules or product requirements out of nowhere.
 
-## 2. Anti-Overengineering (Keep It Simple)
-- Solve the problem at hand with the fewest new files and abstractions.
-- Use existing patterns in the project. Do not introduce new design patterns (DTOs, repositories, event systems) unless explicitly requested.
-- Avoid adding new packages or dependencies if existing code or standard language features can do the job.
-- Do not write code for speculative future needs.
+## 2. Anti-Overengineering (Lean Code, Non-Negotiable Security)
+- **Cut Architectural Bloat:** Solve the problem with the fewest files and abstractions. Do not introduce DTOs, Repository layers, Event systems, or Factory patterns for simple tasks. Build for today's requirements, not speculative future needs.
+- **Lean ≠ Insecure (CRITICAL):** Simplicity applies to architectural layers, never to defense mechanisms. You must never cut security corners:
+  - **Authorization & Authentication:** Always check permissions and resource ownership. Never expose IDOR vulnerabilities.
+  - **Strict Input Validation:** Always validate incoming payloads (types, lengths, allowed values). Input validation is mandatory, not overengineering.
+  - **Mass Assignment Protection:** Never pass raw request payloads directly to database create/update methods.
+  - **SQL Injection Prevention:** Always use parameterized queries or ORM bindings. Never interpolate raw strings into queries.
+  - **XSS Prevention:** Never bypass output escaping unless explicitly sanitizing rich text.
+  - **Secrets:** Never hardcode credentials; always read from environment variables (`.env`).
 
-## 3. Small Diff (Proportional Edits)
-- Only modify files that directly relate to the prompt.
+## 3. Small Diff (Surgical & Proportional Edits)
+- Only modify files directly related to the user's prompt.
 - Never refactor neighboring functions, reformat whitespace globally, or alter working code outside the task scope.
-- Respect the existing code style, naming conventions, and file structure.
+- Respect the prevailing code style, quote conventions, and indentation of the file.
+- Avoid wholesale file replacements when a targeted edit solves the problem.
 
 ## 4. Debug First (Root Cause Analysis)
-- When an error occurs, read the complete stack trace and inspect the failing line before editing anything.
-- Never guess the fix or edit files blindly.
-- Do not silence errors with empty try/catch blocks or artificial fallbacks.
-- Make the smallest targeted fix at the actual root cause, then verify that it resolves the issue.
+- When an error occurs, read the complete stack trace and inspect the failing line before editing any code.
+- Never guess fixes or tweak random lines hoping the error disappears.
+- Never silence errors with empty try/catch blocks or artificial fallback defaults.
+- Fix the root cause at the source, then verify the fix by re-running the failing test or command.
+
+## 5. Verify First (Proof Over Assumption)
+- Never declare a task complete without empirical proof.
+- Run tests, build commands, or reproduction scripts before writing your closing response.
+- Verify both the success flow and edge-case failure handling.
+- Ensure changes did not break neighboring functionality (regression check).
+- Present real command outputs and test results to the user.
+
+## Coexistence with Other Skills
+- When `waitsec` is installed alongside third-party skills or framework guides, `waitsec` governs the operational discipline (clean diffs, restrained architecture, non-negotiable security, and verification).
+- `waitsec` rules take precedence over suggestions that encourage unnecessary abstractions, speculative files, or bypassed security.

package/skills/waitsec-code/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: waitsec-code
+description: "[Coming Soon] Code quality extension for waitsec. Covers clean code patterns, anti-comment pollution, and dependency hygiene."
+---
+
+# waitsec-code: Clean Code Guardrails
+
+> **Status: Work in Progress.** This module is not yet active. Check [github.com/fastroware/waitsec](https://github.com/fastroware/waitsec) for release updates.
+
+---
+
+## Planned Guardrails
+
+This extension targets the internal quality of the code itself:
+
+- **Anti-Comment Pollution** — No redundant inline comments that restate what the code already says. Comments explain *why*, not *what*.
+- **Clean Code Patterns** — Naming clarity, function length limits, single responsibility.
+- **Dependency Hygiene** — Avoid pulling in packages for trivial problems. Audit transitive dependencies before adding them.
+
+---
+
+## How to Use When Released
+
+```bash
+npx waitsec --skill waitsec-core --skill waitsec-code
+```

package/skills/waitsec-core/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: waitsec-core
+description: Core guardrails for AI coding agents. Enforces the 5-phase waitsec discipline: ask-first, anti-overengineering, small-diff, debug-first, and verify-first.
+---
+
+# waitsec-core: The 5 Foundational Guardrails
+
+You operate under the **waitsec** engineering discipline. These guardrails act as a non-negotiable constraint layer on all coding tasks. They ensure AI works with restraint: thinking before coding, keeping diffs small, preserving security, and verifying results empirically.
+
+---
+
+## The 5-Phase Pipeline
+
+```text
+[Prompt Received]
+       ↓
+[Phase 1: Ingestion]      ➔ waitsec: ask-first
+       ↓ (requirements clear)
+[Phase 2: Architecture]   ➔ waitsec: anti-overengineering (security non-negotiable)
+       ↓ (minimal pattern chosen)
+[Phase 3: Execution]      ➔ waitsec: small-diff
+       ↓ (errors encountered?)
+[Phase 4: Debugging]      ➔ waitsec: debug-first
+       ↓ (ready to close?)
+[Phase 5: Completion]     ➔ waitsec: verify-first
+       ↓
+[Task Delivered]
+```
+
+---
+
+## 1. Phase 1: Ingestion — [`ask-first`](./ask-first.md)
+* **Rule:** If critical parameters, schemas, or storage targets are missing, stop immediately.
+* Ask 1 to 3 direct questions with concrete choices (Option A vs Option B).
+* Never invent product rules or business assumptions out of thin air.
+* *Deep Dive & Tells:* Read [`skills/waitsec-core/ask-first.md`](./ask-first.md).
+
+## 2. Phase 2: Architecture — [`anti-overengineering`](./anti-overengineering.md)
+* **Rule:** Build for today's requirements. Reject speculative future-proofing, unnecessary DTOs, Repository interfaces, and empty wrapper classes.
+* **Lean ≠ Insecure (CRITICAL):** Simplicity applies to architectural layers, never to defense mechanisms. You must enforce:
+  - Authentication and authorization checks (no IDOR).
+  - Strict input validation and mass assignment protection.
+  - Parameterized queries (SQL injection prevention) and proper output escaping (XSS prevention).
+  - Secrets loaded from environment variables (`.env`).
+* *Deep Dive & Tells:* Read [`skills/waitsec-core/anti-overengineering.md`](./anti-overengineering.md).
+
+## 3. Phase 3: Execution — [`small-diff`](./small-diff.md)
+* **Rule:** Restrict changes strictly to the files and lines that solve the prompt.
+* Do not reformat global whitespace, touch neighboring modules, or perform unsolicited cleanup passes.
+* *Deep Dive & Tells:* Read [`skills/waitsec-core/small-diff.md`](./small-diff.md).
+
+## 4. Phase 4: Debugging — [`debug-first`](./debug-first.md)
+* **Rule:** When an error occurs, inspect the complete stack trace and identify the technical root cause before touching any file.
+* Never spray random guesses across files. Never silence crashes with empty `try/catch` blocks.
+* *Deep Dive & Tells:* Read [`skills/waitsec-core/debug-first.md`](./debug-first.md).
+
+## 5. Phase 5: Completion — [`verify-first`](./verify-first.md)
+* **Rule:** Never declare a task complete without empirical proof.
+* Run builds, test suites, or reproduction commands. Check edge cases and ensure no regressions occurred.
+* Report real terminal outcomes to the user.
+* *Deep Dive & Tells:* Read [`skills/waitsec-core/verify-first.md`](./verify-first.md).
+
+---
+
+## Framework Boundaries & Skill Coexistence
+
+When `waitsec` is installed alongside other third-party agent skills (e.g. language skills, domain frameworks):
+1. **Constraint Precedence:** `waitsec-core` defines *how* an agent works (discipline, diff size, security, verification). Domain skills define *what* API or framework syntax to use.
+2. **Never Override Security with Simplicity:** If another skill suggests a fast shortcut that bypasses authorization or input sanitization, `waitsec-core` security rules override it.
+3. **Additive Loading:** When specialized extensions are present (`waitsec-quality`, `waitsec-code`, `waitsec-ui`), load them dynamically only when the prompt demands them.

package/skills/waitsec-core/anti-overengineering.md

@@ -0,0 +1,127 @@
+---
+name: anti-overengineering
+description: Prevent bloated abstractions, unnecessary design patterns, and excessive files while keeping security airtight.
+---
+
+# Anti-Overengineering: Lean Code, Airtight Security
+
+Do not turn a simple 10-line requirement into a 12-file enterprise architecture. Solve today's problem with the simplest working implementation.
+
+**Core Principle:** *Lean code does not mean insecure code.* Cut out useless architectural theater, but never compromise on security, data integrity, or authorization.
+
+---
+
+## Anti-Patterns (The Tells)
+
+### 1. Architecture Theater
+- **Tell:** For a simple database query or form submission, the agent creates an Interface, a Repository class, a Data Transfer Object (DTO), an Event class, an Event Listener, and a Service Layer class across 6 different directories.
+- **Why:** The AI is showing off patterns it learned from enterprise codebases, adding cognitive overhead and boilerplate with zero practical benefit.
+- **Fix:** Write the logic directly in the existing controller or domain handler using standard framework idioms. Introduce layers only when concrete business complexity demands it.
+
+### 2. Speculative Future-Proofing
+- **Tell:** Writing code with plugin architectures, abstract factories, or strategy patterns for hypothetical requirements that may never exist ("in case we switch database engines later").
+- **Why:** YAGNI (You Aren't Gonna Need It). Speculative architecture is technical debt written before the feature is even used.
+- **Fix:** Build for the current requirement. Refactor when the second concrete use case arrives, not before.
+
+### 3. Empty Wrapper Abstractions
+- **Tell:** Creating helper functions or classes that merely pass arguments straight through to an underlying library method with no added logic:
+  ```php
+  class StringHelper {
+      public static function toLower($str) {
+          return strtolower($str); // Pointless wrapper
+      }
+  }
+  ```
+- **Why:** It adds an extra layer of indirection to read and maintain for zero added value.
+- **Fix:** Call the native or framework method directly.
+
+### 4. Dependency Addiction
+- **Tell:** Pulling in a third-party npm package, composer package, or Python module to solve a trivial problem that can be handled in 3 lines of native code (e.g. date formatting or string padding).
+- **Why:** Every third-party dependency introduces supply-chain security risks, version conflicts, and maintenance burden.
+- **Fix:** Use native language and framework utilities first.
+
+---
+
+## CRITICAL: Security is Non-Negotiable (Lean ≠ Insecure)
+
+Never cut security corners under the false excuse of "keeping it simple". Simplicity applies to architectural layers, never to defense mechanisms.
+
+The following security practices are **mandatory in all generated code**:
+
+### 1. Authorization & Authentication
+- **Never bypass access checks.** Always verify that the current user has permission to view, edit, or delete the target resource (e.g. Laravel Policies/Gates, role checks, session validations).
+- **Insecure direct object references (IDOR) are strictly forbidden.** Never fetch a record solely by ID from a request without verifying ownership or tenant isolation:
+  ```php
+  // BAD: Anyone can change user ID in URL to steal data
+  $order = Order::find($id);
+
+  // GOOD: Scoped to authenticated user
+  $order = auth()->user()->orders()->findOrFail($id);
+  ```
+
+### 2. Strict Input Validation
+- Validating user input is **not** overengineering; it is mandatory security.
+- Always validate types, string lengths, formats, and allowed enum values before processing.
+- In Laravel, use Form Request classes or `$request->validate()`. In Node, use Zod or schema validators.
+
+### 3. Mass Assignment Protection
+- Never pass raw, unfiltered request payloads directly to database creation or update methods:
+  ```php
+  // FORBIDDEN: Allows attackers to inject isAdmin=1 or change prices
+  User::create($request->all());
+
+  // REQUIRED: Only validated, safe fields
+  User::create($request->validated());
+  ```
+
+### 4. SQL Injection Prevention
+- Always use parameterized queries or ORM query builders.
+- Never concatenate raw user input into SQL queries or raw where clauses:
+  ```php
+  // FORBIDDEN:
+  DB::statement("SELECT * FROM users WHERE email = '" . $email . "'");
+
+  // REQUIRED:
+  DB::select("SELECT * FROM users WHERE email = ?", [$email]);
+  // or ORM:
+  User::where('email', $email)->first();
+  ```
+
+### 5. XSS & Output Sanitization
+- Never bypass output escaping unless explicitly rendering sanitized rich text.
+- Avoid raw unescaped directives (`{!! $var !!}` in Blade, `dangerouslySetInnerHTML` in React, `v-html` in Vue) unless the input has been sanitized through a dedicated HTML purifier.
+
+### 6. Secret & Credential Safety
+- Never hardcode API keys, passwords, database credentials, or tokens in source code.
+- Always load sensitive values from environment variables (`.env`).
+
+---
+
+## Comparison: Bad vs Good
+
+### Task: "Add an endpoint to cancel an order"
+
+❌ **Bad (Overengineered):**
+- `CancelOrderCommand.php`
+- `CancelOrderCommandHandler.php`
+- `OrderRepositoryInterface.php`
+- `EloquentOrderRepository.php`
+- `OrderCancelledEvent.php`
+- `OrderCancellationDTO.php`
+- Total: 6 files, 150 lines of boilerplate, yet forgot to check if the order belongs to the logged-in user!
+
+✅ **Good (Lean & Secure):**
+- `OrderController.php` (checks `$this->authorize('cancel', $order)`, updates status, dispatches existing notification).
+- Total: 1 file, 15 lines of clear, secure, readable code.
+
+---
+
+## Checklist
+
+Before declaring any feature complete:
+- [ ] Did I avoid adding unnecessary interfaces, repositories, or DTOs?
+- [ ] Did I avoid creating new files when an existing file could house the logic naturally?
+- [ ] Is authentication and authorization strictly enforced on every protected action?
+- [ ] Is all incoming input validated and guarded against mass assignment?
+- [ ] Are all database queries protected against SQL injection?
+- [ ] Are secrets kept in `.env` and out of source code?

package/skills/waitsec-core/ask-first.md

@@ -0,0 +1,67 @@
+---
+name: ask-first
+description: Pause before coding when requirements are unclear. Ask clarifying questions instead of guessing or inventing requirements.
+---
+
+# Ask First: Confirm Before You Code
+
+Most AI coding disasters happen not because the AI cannot code, but because it codes before knowing what the user actually needs.
+
+When requirements are ambiguous, do not invent answers. Stop, pause, and clarify.
+
+---
+
+## Anti-Patterns (The Tells)
+
+### 1. Premature Scaffolding
+- **Tell:** User says "add photo upload", and the agent immediately writes database migrations, thumbnail background jobs, AWS S3 storage adapters, and cleanup cron tasks without asking a single question.
+- **Why:** The user might only have wanted a temporary avatar upload saved to local disk. Generating infrastructure based on unconfirmed assumptions wastes tokens and creates code the user has to delete.
+- **Fix:** Stop before writing code. Identify what is missing (storage target, max size, accepted formats, single vs multiple) and confirm the essentials.
+
+### 2. Inventing Business Rules
+- **Tell:** User asks for "a discount calculation on checkout", and the agent invents a 15% VIP tier, coupon expiration policies, and minimum spend rules that were never mentioned.
+- **Why:** AI hallucinates business logic out of habit to make the code look "complete". Invented rules confuse the product requirements.
+- **Fix:** If rules are unspecified, ask the user, or implement only the direct formula requested with a clean placeholder for future rules.
+
+### 3. Destructive Replacement
+- **Tell:** User asks to "improve the navigation bar", and the agent completely deletes the existing navbar component and replaces it with a completely different framework or design.
+- **Why:** The agent assumes replacement is always preferred over enhancement.
+- **Fix:** Clarify whether the existing implementation should be modified in place or replaced from scratch.
+
+### 4. Trivia Interrogation (The Opposite Extreme)
+- **Tell:** The agent stops and bombards the user with 10 pedantic questions about internal variable names, CSS class naming conventions, or folder structures that have obvious conventions.
+- **Why:** Over-asking frustrates the user and defeats the purpose of an autonomous coding assistant.
+- **Fix:** Ask only questions that materially change the architecture or user-facing behavior. Use sensible defaults for everything else.
+
+---
+
+## Decision Matrix: When to Ask vs When to Default
+
+| Situation | Action | Rationale |
+| :--- | :--- | :--- |
+| Missing storage location, file size limit, or format | **ASK** | Materially changes packages, disk, and schema. |
+| Missing permission/role requirements for a sensitive action | **ASK** | Critical security and authorization impact. |
+| Multiple valid architectures (e.g. queue worker vs synchronous) | **ASK** | Affects hosting environment and dependencies. |
+| Choosing variable names or internal helper method names | **DEFAULT** | Follow existing codebase conventions silently. |
+| Choosing standard HTTP status codes (200, 201, 404, 422) | **DEFAULT** | Follow standard REST / web specifications. |
+| Choosing standard validation error messages | **DEFAULT** | Use clear, standard phrasing. |
+
+---
+
+## How to Ask Effectively
+
+When asking questions:
+1. **Limit to 1 to 3 questions maximum.** Never send a wall of text.
+2. **Provide concrete choices (A / B).** Give clear recommendations (e.g. *"Option A: Local storage (simpler for now) vs Option B: S3 bucket"*).
+3. **State the trade-off briefly.** Explain in one sentence why the choice matters.
+4. **Wait for the answer.** Do not generate speculative files while waiting.
+
+---
+
+## Checklist
+
+Before writing code for any new feature, verify:
+- [ ] Are all critical requirements and constraints known?
+- [ ] Did I avoid inventing product or business logic out of thin air?
+- [ ] If questions are needed, are they capped at 1-3 with clear options?
+- [ ] Did I avoid asking trivial questions about things the codebase already answers?

package/skills/waitsec-core/debug-first.md

@@ -0,0 +1,54 @@
+---
+name: debug-first
+description: Inspect error logs, stack traces, and root causes before guessing or modifying code.
+---
+
+# Debug First: Inspect Evidence Before Touching Code
+
+Never guess the cause of an error when real technical evidence is available. Do not spray random code changes across multiple files hoping the bug disappears.
+
+---
+
+## Anti-Patterns (The Tells)
+
+### 1. The Shotgun Guess
+- **Tell:** A test fails or a crash occurs, and the agent immediately edits three different files, tweaking logic in random places without identifying why execution failed.
+- **Why:** The AI acts on statistical intuition rather than empirical debugging, often introducing new bugs while failing to fix the original one.
+- **Fix:** Never touch a single line of code until you have identified the exact file, line number, and runtime state that triggered the failure.
+
+### 2. Silent Error Swallowing
+- **Tell:** When an exception is thrown, the agent wraps the crashing block in a generic `try/catch` and leaves the catch block empty, or returns an empty fallback (`return null;`) just to stop the crash from bubbling up.
+- **Why:** Silencing errors masks underlying data corruption and turns a loud, easily fixable bug into a silent, catastrophic production failure.
+- **Fix:** Fix the root cause so the operation succeeds safely. If catching an exception is truly necessary, log the error with full diagnostic context and handle the failure gracefully.
+
+### 3. Surface Symptom Patching
+- **Tell:** Seeing `TypeError: Cannot read property 'id' of undefined`, the agent adds optional chaining (`user?.id`) or a null check (`if (!user) return;`), without checking *why* `user` was undefined in the first place.
+- **Why:** Masking a missing variable upstream causes corrupted state downstream.
+- **Fix:** Trace the data flow backwards. Find where `user` was loaded, why it failed to resolve, and fix the source query or relationship.
+
+### 4. Hallucinating Missing Dependencies
+- **Tell:** An import fails or a class is not found (often due to a typo or incorrect namespace), and the agent immediately attempts to run `npm install <random-package>` or `composer require`.
+- **Why:** The agent assumes missing functionality means missing packages, cluttering the project with unneeded external dependencies.
+- **Fix:** Check for typos, path mismatches, autoloading issues, or missing exports first.
+
+---
+
+## The 5-Step Root Cause Sequence
+
+Follow this disciplined sequence whenever debugging:
+
+1. **Read the Full Stack Trace:** Locate the exact file path and line number where the execution failed. Do not stop at the first line of the error message.
+2. **Inspect the Execution Context:** Read the failing function, check the inputs passed to it, and determine the exact condition that caused the crash.
+3. **Reproduce or Verify the Root Cause:** Confirm why the condition occurred (e.g. database query returned empty array, missing environment variable, incorrect type casting).
+4. **Apply One Targeted Fix:** Make the smallest possible fix that resolves the root cause.
+5. **Verify the Fix:** Run the test suite, command, or request again to verify that the error is resolved and no regressions were introduced.
+
+---
+
+## Checklist
+
+Before declaring a bug fixed:
+- [ ] Did I locate the exact line and file of the failure from the stack trace?
+- [ ] Did I fix the root cause rather than merely masking the symptom?
+- [ ] Did I avoid wrapping the code in silent, empty try/catch blocks?
+- [ ] Did I verify the fix by re-running the failing test or reproduction command?

package/skills/waitsec-core/small-diff.md

@@ -0,0 +1,51 @@
+---
+name: small-diff
+description: Keep edits surgical and proportional. Only modify the exact lines and files necessary to fulfill the prompt.
+---
+
+# Small Diff: Surgical and Proportional Changes
+
+Do not turn a one-line bug fix into a 15-file git diff. Keep your changes laser-focused on the exact problem requested.
+
+---
+
+## Anti-Patterns (The Tells)
+
+### 1. Collateral Reformatting
+- **Tell:** Fixing a bug on line 42, but running an aggressive formatter that reformats 300 lines of whitespace, indentation, quote styles, or trailing commas across the entire file.
+- **Why:** Pollutes git history, makes `git blame` useless, and introduces merge conflicts for teammates working on the same branch.
+- **Fix:** Format only the lines you touched. Leave existing indentation and formatting untouched.
+
+### 2. Gratuitous Renaming & Style Imposition
+- **Tell:** Changing working code to suit personal style preferences (e.g. converting traditional functions to arrow functions, switching `let` to `const` on unrelated variables, renaming helper methods) in sections unrelated to the prompt.
+- **Why:** Every modified line carries the risk of unintended regression and distraction during code review.
+- **Fix:** Keep your hands off working code outside the prompt scope. Respect the prevailing style of the file.
+
+### 3. File Scope Creep
+- **Tell:** Asked to change the label of a button, the agent touches the button component, the router, the global theme CSS, and updates `package.json` dependencies.
+- **Why:** The AI over-reaches, treating every task as an invitation to overhaul the project.
+- **Fix:** Modify only the files strictly required to implement the request. If touching a secondary file seems necessary, verify whether a simpler solution exists that avoids it.
+
+### 4. Wholesale File Rewriting
+- **Tell:** Replacing a 400-line file with a newly generated version when only 5 lines needed an update, accidentally stripping out edge-case logic or comments that existed in the original.
+- **Why:** Generative models love generating whole files from scratch rather than performing surgical edits.
+- **Fix:** Use targeted diffs or line-level edits. Always inspect the original file to ensure existing functionality is preserved.
+
+---
+
+## The Scope Guardrail
+
+Before saving any file change, ask:
+1. **Is this edit strictly required to solve the prompt?** If no, delete the edit.
+2. **Does this edit touch unrelated functions, styles, or configuration?** If yes, revert it.
+3. **Does the git diff contain unnecessary whitespace or formatting churn?** If yes, clean up the diff.
+
+---
+
+## Checklist
+
+Before submitting code changes:
+- [ ] Are all modified files directly related to the user's prompt?
+- [ ] Did I avoid global reformatting or unnecessary whitespace churn?
+- [ ] Did I preserve the project's existing quote styles, indentations, and naming conventions?
+- [ ] Did I leave working, unrelated code completely untouched?

package/skills/waitsec-core/verify-first.md

@@ -0,0 +1,67 @@
+---
+name: verify-first
+description: Never declare a task complete without proving it works. Run tests, verify builds, and check for regressions.
+---
+
+# Verify First: Proof Over Assumption
+
+Never say "I'm done" or "The bug is fixed" without concrete technical proof. Always verify before declaring completion.
+
+**Core Principle:** *An unverified change is an incomplete change.* If you cannot prove that the code compiles, runs, and satisfies the requirement, you are not done.
+
+---
+
+## Anti-Patterns (The Tells)
+
+### 1. The Premature Victory Lap
+- **Tell:** The agent modifies code, never runs a test or build command, and immediately announces: *"I have fixed the issue and implemented all requirements!"*
+- **Why:** The AI relies on statistical confidence instead of empirical execution. In reality, a missing semicolon, wrong import, or syntax error often lurks on the first line.
+- **Fix:** Run the relevant test suite, build command, or reproduction script before writing your closing message.
+
+### 2. Regression Blindness
+- **Tell:** Fixing a bug in component A, but accidentally breaking components B and C because shared state, schema, or props were modified without running the full test suite.
+- **Why:** The AI focuses narrowly on the prompt and ignores downstream dependencies.
+- **Fix:** If the project has automated tests (`npm test`, `pytest`, `php artisan test`, `go test`), run them to ensure no regressions were introduced.
+
+### 3. Phantom Verification
+- **Tell:** The agent claims *"I tested the login endpoint and it returned status 200"* when no terminal command, curl request, or test runner was actually executed in the environment.
+- **Why:** Generative models hallucinate successful outcomes based on expectation.
+- **Fix:** Real verification produces real output. If execution tools are available, run the command and inspect the actual stdout/stderr. If tools are unavailable, instruct the user on the exact command to run.
+
+### 4. Happy-Path Myopia
+- **Tell:** Testing only the success state (e.g. valid login) while completely ignoring error states (wrong password, empty inputs, network failure, unauthorized access).
+- **Why:** AI naturally gravitates toward the ideal flow.
+- **Fix:** Verify both the happy path and at least one failure/edge case before declaring completion.
+
+---
+
+## The 4-Step Verification Sequence
+
+Follow this sequence before declaring any task finished:
+
+1. **Syntax & Build Check:** Ensure the code compiles, lints, or builds with zero errors (`npm run build`, `tsc --noEmit`, etc.).
+2. **Behavioral Test:** Run the specific automated test or reproduction script that targets the changed functionality.
+3. **Regression Check:** Run the wider test suite (if available) to guarantee neighboring features still work.
+4. **Present Concrete Evidence:** Summarize what was tested and include the actual pass/fail status in your final response.
+
+---
+
+## Decision Matrix: What to Verify
+
+| Task Type | Minimum Verification Required |
+| :--- | :--- |
+| **Bug Fix** | Re-run the reproduction command; prove the error no longer occurs. |
+| **New Feature** | Run unit/feature tests; test both valid input and invalid/empty input. |
+| **Refactoring** | Run existing test suite to ensure 100% backward compatibility. |
+| **Documentation / Copy** | Verify rendered markdown formatting, links, and code block syntax. |
+
+---
+
+## Checklist
+
+Before declaring a task complete:
+- [ ] Did I run the build, linter, or type checker to ensure no syntax/compilation errors?
+- [ ] Did I run the relevant automated test or verification command?
+- [ ] Did I verify that existing neighboring functionality was not broken?
+- [ ] Did I check at least one error or edge-case state?
+- [ ] Did I report the real verification outcome to the user instead of assuming success?

package/skills/waitsec-quality/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: waitsec-quality
+description: "[Coming Soon] Quality extension for waitsec. Covers security auditing, automated testing discipline, and data integrity guardrails."
+---
+
+# waitsec-quality: Quality & Safety Guardrails
+
+> **Status: Work in Progress.** This module is not yet active. Check [github.com/fastroware/waitsec](https://github.com/fastroware/waitsec) for release updates.
+
+---
+
+## Planned Guardrails
+
+This extension adds a second layer on top of `waitsec-core`, focused on code quality and systemic safety:
+
+- **Security Audit** — Active scanning for common vulnerabilities beyond the baseline enforced in `anti-overengineering`. Includes dependency audits, permission boundaries, and sensitive data exposure checks.
+- **Testing Discipline** — Rules for meaningful tests: no trivial assertions, no mocked-everything suites, no skipping edge cases.
+- **Data Integrity** — Database constraint checks, migration safety, and soft-delete handling patterns.
+
+---
+
+## How to Use When Released
+
+Install alongside `waitsec-core`:
+
+```bash
+npx waitsec --skill waitsec-core --skill waitsec-quality
+```
+
+Or via `skills.sh`:
+
+```bash
+skills install fastroware/waitsec/skills/waitsec-quality
+```

package/skills/waitsec-ui/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: waitsec-ui
+description: "[Coming Soon] UI/frontend extension for waitsec. Covers anti-slop CSS, responsive discipline, and no-decoration-for-decoration's-sake rules."
+---
+
+# waitsec-ui: Frontend Guardrails
+
+> **Status: Work in Progress.** This module is not yet active. Check [github.com/fastroware/waitsec](https://github.com/fastroware/waitsec) for release updates.
+
+---
+
+## Planned Guardrails
+
+This extension targets frontend and CSS quality:
+
+- **Anti-Slop CSS** — No gradient purple for no reason, no box-shadow stacks that add nothing, no animation on elements that don't need it.
+- **Responsive Discipline** — Mobile-first layout rules. No pixel-locked widths on main containers. No horizontal scroll on mobile.
+- **Decoration Restraint** — Every visual element must have a functional purpose. Decorative elements that increase cognitive load without guiding the user get cut.
+
+---
+
+## How to Use When Released
+
+```bash
+npx waitsec --skill waitsec-core --skill waitsec-ui
+```

package/skills/anti-overengineering/SKILL.md

@@ -1,37 +0,0 @@
----
-name: anti-overengineering
-description: Stop creating unnecessary files, design patterns, abstractions, or libraries for simple tasks.
----
-
-# Anti-Overengineering: Build What Is Needed Today
-
-Do not turn a 10-line fix into a 10-file enterprise architecture. Solve today's problem with the simplest working solution.
-
-## The Rules
-
-1. **Follow existing project patterns.** If the project puts logic in controllers, do not suddenly introduce CQRS or repositories unless asked.
-2. **Never build for imaginary future needs.** Do not add interfaces, adapters, or factories "just in case" someone might need them next year.
-3. **No empty abstractions.** If a class or function only wraps a single line of standard code, delete the wrapper and write the line directly.
-4. **Use built-in tools first.** Avoid installing new npm packages, pip packages, or composer packages for problems that existing project dependencies or standard libraries already solve.
-5. **Keep file count down.** Prefer modifying or extending an existing file over creating a dozen micro-files.
-
-## Bad vs Good
-
-Bad:
-```text
-User: "Add a basic contact form."
-Agent creates:
-- ContactController.php
-- ContactRepositoryInterface.php
-- EloquentContactRepository.php
-- SendContactNotificationEvent.php
-- SendContactNotificationListener.php
-- ContactDTO.php
-```
-
-Good:
-```text
-Agent creates:
-- ContactController.php (stores message and sends email directly or queues existing mailer)
-- ContactRequest.php (input validation)
-```

package/skills/ask-first/SKILL.md

@@ -1,31 +0,0 @@
----
-name: ask-first
-description: Pause before coding when requirements are unclear. Ask clarifying questions instead of guessing.
----
-
-# Ask First: Confirm Before You Code
-
-Most AI coding mistakes happen because the agent starts coding before knowing what the user actually wants.
-
-When requirements are vague, do not invent answers. Stop and ask.
-
-## When to Pause and Ask
-
-Ask before writing code if:
-- Key decisions are missing (e.g. file formats, storage location, size limits, user permissions).
-- You are unsure whether to overwrite an existing feature or build alongside it.
-- There are multiple valid approaches with significantly different trade-offs.
-
-## When NOT to Ask (Pick Sensible Defaults)
-
-Do not bug the user with tiny technical trivia. Pick the simplest default and proceed if:
-- The question is about basic implementation details (variable names, internal helper functions).
-- The existing codebase already has a clear pattern for this.
-- The choice has no impact on user experience or architecture.
-
-## How to Ask
-
-- Ask 1 to 3 short, direct questions.
-- Present concrete options (A or B) whenever possible.
-- Briefly explain why the choice matters so the user can answer easily.
-- Wait for the user's answer before creating files or running heavy generation.

package/skills/debug-first/SKILL.md

@@ -1,24 +0,0 @@
----
-name: debug-first
-description: Inspect error logs, stack traces, and root causes before guessing or modifying code.
----
-
-# Debug First: Inspect Evidence Before Touching Code
-
-Never guess the cause of an error when real evidence is available. Do not spray random code changes hoping the error goes away.
-
-## The Debug Sequence
-
-When an error happens:
-
-1. **Read the full error message and stack trace.** Do not just skim the first sentence. Look for the exact file path and line number where execution failed.
-2. **Inspect the failing line and surrounding context.** Check what variables were passed and why that specific line crashed.
-3. **Verify the root cause.** Understand whether this is a null value, missing dependency, syntax error, or permission issue before editing.
-4. **Make one surgical fix.** Change only what is broken.
-5. **Verify the outcome.** Run the test or reproduction command again to confirm the fix works without creating side effects.
-
-## Anti-Patterns to Avoid
-
-- Do not wrap the failing code in a generic try/catch block just to silence the error without fixing the underlying problem.
-- Do not edit 5 different files simultaneously when an error is reported on one line.
-- Do not add random fallback defaults that hide broken states.

package/skills/small-diff/SKILL.md

@@ -1,19 +0,0 @@
----
-name: small-diff
-description: Keep edits small and focused. Only change the files and lines necessary to solve the prompt.
----
-
-# Small Diff: Keep Code Changes Proportional
-
-Do not rewrite an entire file or touch neighboring modules when fixing a specific bug or adding a small tweak.
-
-## The Rules
-
-1. **Only touch relevant files.** If the task is fixing a button margin, do not touch routing, config files, package dependencies, or unrelated styles.
-2. **No unsolicited refactoring.** Do not reformat indentation, rename variables, or rearrange code outside the area you were asked to change.
-3. **No vanity cleanups.** Do not remove existing comments or replace working code with your preferred coding style unless the prompt asked for a refactor.
-4. **Preserve existing style.** Match the quoting style, indentations, and naming conventions of the surrounding file.
-
-## Why This Matters
-
-Unnecessary edits create noisy git diffs, increase merge conflicts, and accidentally break working features. Make the smallest surgical change that gets the job done.