waitsec 0.1.0

package/.cursor-plugin/plugin.json

@@ -0,0 +1,6 @@
+{
+  "name": "waitsec",
+  "displayName": "waitsec",
+  "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
+  "version": "0.1.0"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 waitsec contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+# waitsec
+
+> **Hold on. Think first. Code less.**
+
+`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.
+
+---
+
+## Why waitsec?
+
+Most AI coding assistants do not fail because they lack knowledge. They fail because they move too fast and assume too much:
+
+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.
+2. **They over-engineer.** You ask for a simple login check, and the AI creates twelve new files with DTOs, factories, and repository interfaces.
+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.
+4. **They guess when errors happen.** A test fails on one line, and the AI changes five unrelated files hoping something sticks.
+
+`waitsec` acts as a brake: pause, verify, keep the change small, and fix the root problem.
+
+---
+
+## The 4 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.
+
+---
+
+## Quick Install
+
+### 1. In Any Project (Recommended)
+Run this in your project terminal:
+
+```bash
+npx waitsec
+```
+
+Pick your editor (Kilo Code, Cline, Cursor, or Antigravity), and the installer places the rules file directly in your workspace.
+
+### 2. Kilo Code or Cline (VS Code)
+Copy [rules/waitsec.md](rules/waitsec.md) to your project root as `.kilorules` (or `.clinerules`):
+
+```bash
+curl -o .kilorules https://raw.githubusercontent.com/your-username/waitsec/main/rules/waitsec.md
+```
+
+You can also paste the contents of `rules/waitsec.md` into the **Custom Instructions** field in your Kilo Code extension settings.
+
+### 3. Google Antigravity
+Install the plugin using the Antigravity CLI:
+
+```bash
+agy plugin install https://github.com/your-username/waitsec
+```
+
+### 4. Claude Code
+Add the marketplace and install:
+
+```text
+/plugin marketplace add https://github.com/your-username/waitsec
+/plugin install waitsec@waitsec
+```
+
+### 5. Cursor
+Copy [rules/waitsec.md](rules/waitsec.md) to `.cursorrules` in your project root, or add this repository as a plugin under `.cursor-plugin/`.
+
+### 6. Laravel / PHP (Composer)
+Install into your project development dependencies:
+
+```bash
+composer require --dev waitsec/waitsec
+```
+
+The post-install script automatically adds `.kilorules` to your root directory.
+
+---
+
+## Structure
+
+```text
+waitsec/
+├── skills/
+│   ├── ask-first/             # Clarify ambiguous requirements first
+│   │   └── SKILL.md
+│   ├── anti-overengineering/  # Stop bloat and unnecessary abstractions
+│   │   └── SKILL.md
+│   ├── small-diff/            # Keep changes surgical and small
+│   │   └── SKILL.md
+│   └── debug-first/           # Trace real root causes before editing
+│       └── SKILL.md
+├── rules/
+│   ├── AGENTS.md              # Universal rule pointer
+│   └── waitsec.md             # All-in-one bundled rules
+├── bin/
+│   └── cli.js                 # Interactive terminal installer
+├── plugin.json                # Antigravity plugin manifest
+├── package.json               # npm / npx manifest
+└── composer.json              # Composer / Laravel manifest
+```
+
+---
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,66 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const rl = readline.createInterface({
+  input: process.stdin,
+  output: process.stdout
+});
+
+const sourceRulePath = path.join(__dirname, '..', 'rules', 'waitsec.md');
+
+console.log(`
+=========================================
+  waitsec: AI Coding Guardrails Installer
+  "Hold on. Think first. Code less."
+=========================================
+`);
+
+console.log('Select your editor / coding agent:\n');
+console.log('  1) Kilo Code (.kilorules)');
+console.log('  2) Cline / Roo Code (.clinerules)');
+console.log('  3) Cursor (.cursorrules)');
+console.log('  4) Antigravity / Universal (AGENTS.md)');
+console.log('  5) All of the above\n');
+
+rl.question('Enter number [1-5] (default: 1): ', (answer) => {
+  const choice = (answer || '1').trim();
+  const cwd = process.cwd();
+
+  if (!fs.existsSync(sourceRulePath)) {
+    console.error(`Error: Rule template not found at ${sourceRulePath}`);
+    rl.close();
+    process.exit(1);
+  }
+
+  const ruleContent = fs.readFileSync(sourceRulePath, 'utf8');
+
+  const targets = [];
+  if (choice === '1') targets.push('.kilorules');
+  else if (choice === '2') targets.push('.clinerules');
+  else if (choice === '3') targets.push('.cursorrules');
+  else if (choice === '4') targets.push('AGENTS.md');
+  else if (choice === '5') targets.push('.kilorules', '.clinerules', '.cursorrules', 'AGENTS.md');
+  else {
+    console.log('Unknown choice, defaulting to .kilorules');
+    targets.push('.kilorules');
+  }
+
+  targets.forEach((filename) => {
+    const destPath = path.join(cwd, filename);
+    if (fs.existsSync(destPath)) {
+      console.log(`[!] ${filename} already exists. Appending waitsec rules...`);
+      fs.appendFileSync(destPath, `\n\n${ruleContent}`);
+    } else {
+      fs.writeFileSync(destPath, ruleContent, 'utf8');
+      console.log(`[+] Created ${filename}`);
+    }
+  });
+
+  console.log('\nSuccess! waitsec rules are now active in this project.');
+  console.log('Your AI assistant will now pause, check requirements, and avoid bloated code.\n');
+
+  rl.close();
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "waitsec",
+  "version": "0.1.0",
+  "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
+  "main": "rules/waitsec.md",
+  "bin": {
+    "waitsec": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node ./bin/cli.js"
+  },
+  "keywords": [
+    "ai",
+    "coding-agent",
+    "guardrails",
+    "anti-slop",
+    "cursor",
+    "cline",
+    "kilo-code",
+    "antigravity",
+    "claude-code",
+    "developer-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "files": [
+    "bin/",
+    "rules/",
+    "skills/",
+    ".cursor-plugin/",
+    "plugin.json",
+    "README.md",
+    "LICENSE"
+  ]
+}

package/plugin.json

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

package/rules/AGENTS.md

@@ -0,0 +1,8 @@
+# waitsec
+
+Wait a second before coding. Follow these four 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.

package/rules/waitsec.md

@@ -0,0 +1,26 @@
+# waitsec: AI Coding Guardrails
+
+You follow the waitsec discipline: hold on, think first, and keep changes minimal.
+
+## 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.
+
+## 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.
+
+## 3. Small Diff (Proportional Edits)
+- Only modify files that directly relate to the 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.
+
+## 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.

package/skills/anti-overengineering/SKILL.md

@@ -0,0 +1,37 @@
+---
+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

@@ -0,0 +1,31 @@
+---
+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

@@ -0,0 +1,24 @@
+---
+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

@@ -0,0 +1,19 @@
+---
+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.