waitsec 0.2.0 → 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.2.0",
+  "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.2.0",
+  "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.2.0"
+  "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. 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

@@ -29,3 +29,14 @@ You follow the waitsec discipline: hold on, think first, code less, and keep sec
 - 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/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
+```