waitsec 0.2.0 → 0.4.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.4.0",
   "author": {
     "name": "fastroware"
   },

package/README.md

@@ -1,5 +1,11 @@
 # waitsec
 
+<p align="center">
+  <a href="https://skills.sh/fastroware/waitsec"><img src="https://skills.sh/b/fastroware/waitsec" alt="skills.sh"></a>
+  <a href="https://www.npmjs.com/package/waitsec"><img src="https://img.shields.io/npm/v/waitsec?color=crimson" alt="npm version"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-2ea44f" alt="License: MIT"></a>
+</p>
+
 > **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.
@@ -19,19 +25,13 @@ Most AI coding assistants do not fail because they lack knowledge. They fail bec
 
 ---
 
-## 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.
+## The 5 Core Guardrails
 
-### 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 +83,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
+npx skills add fastroware/waitsec/skills/waitsec-core
+```
+
+Or install only the module you need:
+
+```bash
+# 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 +106,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.mjs                    # Interactive terminal installer (Clack prompts)
+├── 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/bin/cli.mjs

@@ -0,0 +1,266 @@
+#!/usr/bin/env node
+
+import path from 'node:path';
+import fs from 'node:fs';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+import { intro, outro, select, multiselect, confirm, isCancel, cancel, log, spinner } from '@clack/prompts';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const REPO_ROOT = path.resolve(__dirname, '..');
+const SKILLS_SOURCE_DIR = path.join(REPO_ROOT, 'skills');
+const RULES_SOURCE_FILE = path.join(REPO_ROOT, 'rules', 'waitsec.md');
+
+const CORE_SKILL = 'waitsec-core';
+
+const AVAILABLE_SKILLS = [
+  {
+    value: 'waitsec-core',
+    label: 'waitsec-core',
+    hint: '5 core guardrails: ask-first, anti-overengineering, small-diff, debug-first, verify-first',
+  },
+  {
+    value: 'waitsec-quality',
+    label: 'waitsec-quality (preview)',
+    hint: 'Security audits, test discipline, data integrity',
+  },
+  {
+    value: 'waitsec-code',
+    label: 'waitsec-code (preview)',
+    hint: 'Clean code rules, anti-comment noise, dependency control',
+  },
+  {
+    value: 'waitsec-ui',
+    label: 'waitsec-ui (preview)',
+    hint: 'Anti-slop UI copy & CSS, responsive guardrails',
+  },
+];
+
+const AGENTS = [
+  { id: 'antigravity', label: 'Antigravity / Universal', skillDir: '.agents/skills', ruleFile: 'AGENTS.md' },
+  { id: 'claude',      label: 'Claude Code',            skillDir: '.claude/skills', ruleFile: 'CLAUDE.md' },
+  { id: 'cursor',      label: 'Cursor',                 skillDir: '.cursor/skills', ruleFile: '.cursorrules' },
+  { id: 'kilo',        label: 'Kilo Code (VS Code)',    skillDir: '.kilo/skills',   ruleFile: '.kilorules' },
+  { id: 'cline',       label: 'Cline / Roo Code',       skillDir: '.cline/skills',  ruleFile: '.clinerules' },
+  { id: 'codex',       label: 'Codex',                  skillDir: '.codex/skills',  ruleFile: 'AGENTS.md' },
+  { id: 'gemini',      label: 'Gemini CLI',             skillDir: '.gemini/skills', ruleFile: 'GEMINI.md' },
+];
+
+function stop(message) {
+  cancel(message);
+  process.exit(0);
+}
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+const POINTER_START = '<!-- waitsec:start -->';
+const POINTER_END = '<!-- waitsec:end -->';
+
+function getPointerBlock(skills) {
+  return [
+    POINTER_START,
+    '# waitsec: AI Coding Guardrails',
+    '> Hold on. Think first. Code less.',
+    '',
+    'Follow the waitsec engineering discipline for all tasks in this workspace:',
+    '- **Core Guardrails Active**: ' + skills.map(s => '`' + s + '`').join(', '),
+    '- When requirements are ambiguous: pause and ask 1 to 3 direct questions with concrete options.',
+    '- Keep solutions lean: reject enterprise boilerplate; never compromise security or input validation.',
+    '- Keep diffs surgical: touch only the files strictly required to solve the prompt.',
+    '- Debug from evidence: inspect stack traces and root causes before guessing.',
+    '- Verify before declaring done: run builds, tests, and verify edge cases.',
+    POINTER_END,
+  ].join('\n');
+}
+
+function updateRuleFile(filePath, content, isPointer = false) {
+  if (!fs.existsSync(filePath)) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, content, 'utf8');
+    return 'created';
+  }
+
+  const existing = fs.readFileSync(filePath, 'utf8');
+  if (isPointer) {
+    if (existing.includes(POINTER_START) && existing.includes(POINTER_END)) {
+      const regex = new RegExp(`${POINTER_START}[\\s\\S]*?${POINTER_END}`, 'g');
+      const updated = existing.replace(regex, content);
+      fs.writeFileSync(filePath, updated, 'utf8');
+      return 'updated';
+    }
+  }
+
+  if (existing.includes('waitsec: AI Coding Guardrails') || existing.includes(POINTER_START)) {
+    return 'already-configured';
+  }
+
+  fs.appendFileSync(filePath, `\n\n${content}`, 'utf8');
+  return 'appended';
+}
+
+function detectActiveAgents(baseDir) {
+  return AGENTS.filter((agent) => {
+    const rootFolder = agent.skillDir.split('/')[0];
+    const folderExists = fs.existsSync(path.join(baseDir, rootFolder));
+    const ruleExists = agent.ruleFile && fs.existsSync(path.join(baseDir, agent.ruleFile));
+    return folderExists || ruleExists;
+  }).map((a) => a.id);
+}
+
+async function main() {
+  if (process.argv.includes('--version') || process.argv.includes('-v')) {
+    const pkg = JSON.parse(fs.readFileSync(path.join(REPO_ROOT, 'package.json'), 'utf8'));
+    console.log(`waitsec v${pkg.version}`);
+    return;
+  }
+
+  console.log(`
+  ${pc.bold(pc.cyan('██╗    ██╗ █████╗ ██╗████████╗███████╗███████╗ ██████╗'))}
+  ${pc.bold(pc.cyan('██║    ██║██╔══██╗██║╚══██╔══╝██╔════╝██╔════╝██╔════╝'))}
+  ${pc.bold(pc.cyan('██║ █╗ ██║███████║██║   ██║   ███████╗█████╗  ██║     '))}
+  ${pc.bold(pc.cyan('██║███╗██║██╔══██║██║   ██║   ╚════██║██╔══╝  ██║     '))}
+  ${pc.bold(pc.cyan('╚███╔███╔╝██║  ██║██║   ██║   ███████║███████╗╚██████╗'))}
+  ${pc.bold(pc.cyan(' ╚══╝╚══╝ ╚═╝  ╚═╝╚═╝   ╚═╝   ╚══════╝╚══════╝ ╚═════╝'))}
+  ${pc.dim('        "Hold on. Think first. Code less."')}
+`);
+
+  intro(pc.bold('Install waitsec guardrails into your AI coding setup'));
+
+  log.step(pc.bold('1. Select Skills to Install'));
+  const selectedSkills = await multiselect({
+    message: 'Select the skills you want (Press Space to select, Enter to confirm):',
+    options: AVAILABLE_SKILLS,
+    initialValues: ['waitsec-core'],
+    required: 'You must select at least one skill.',
+  });
+  if (isCancel(selectedSkills)) stop('Installation cancelled.');
+
+  log.step(pc.bold('2. Choose Installation Scope'));
+  const scope = await select({
+    message: 'Where do you want waitsec to be installed?',
+    options: [
+      {
+        value: 'project',
+        label: 'This project only',
+        hint: 'Creates rules and skill folders in current workspace',
+      },
+      {
+        value: 'global',
+        label: 'Everywhere (Global)',
+        hint: 'Installs directly to your machine home directory across all projects',
+      },
+    ],
+  });
+  if (isCancel(scope)) stop('Installation cancelled.');
+
+  const baseDir = scope === 'global' ? os.homedir() : process.cwd();
+  const detectedAgentIds = detectActiveAgents(baseDir);
+
+  log.step(pc.bold('3. Choose Your AI Agents / Editors'));
+  const chosenAgentIds = await multiselect({
+    message: 'Which coding assistants or editors do you use? (Press Space to select):',
+    options: AGENTS.map((a) => ({
+      value: a.id,
+      label: a.label,
+      hint: detectedAgentIds.includes(a.id)
+        ? pc.green('found in environment')
+        : pc.dim(a.ruleFile ? `configures ${a.ruleFile}` : 'creates skill folder'),
+    })),
+    initialValues: detectedAgentIds.length > 0 ? detectedAgentIds : ['antigravity', 'cursor', 'claude', 'kilo'],
+    required: 'Please pick at least one assistant or editor.',
+  });
+  if (isCancel(chosenAgentIds)) stop('Installation cancelled.');
+
+  const chosenAgents = AGENTS.filter((a) => chosenAgentIds.includes(a.id));
+
+  let overwrite = false;
+  const existingDestinations = [];
+  for (const agent of chosenAgents) {
+    for (const skill of selectedSkills) {
+      const checkPath = path.join(baseDir, agent.skillDir, skill);
+      if (fs.existsSync(checkPath)) {
+        existingDestinations.push(checkPath);
+      }
+    }
+  }
+
+  if (existingDestinations.length > 0) {
+    const conflictAction = await select({
+      message: `${existingDestinations.length} skill folder(s) already exist. What would you like to do?`,
+      options: [
+        { value: 'overwrite', label: 'Overwrite with latest version', hint: 'recommended' },
+        { value: 'skip',      label: 'Keep existing folders',        hint: 'skip copying over existing skills' },
+      ],
+    });
+    if (isCancel(conflictAction)) stop('Installation cancelled.');
+    overwrite = conflictAction === 'overwrite';
+  }
+
+  const s = spinner();
+  s.start('Installing waitsec guardrails...');
+
+  let copiedSkillsCount = 0;
+  for (const agent of chosenAgents) {
+    for (const skill of selectedSkills) {
+      const srcDir = path.join(SKILLS_SOURCE_DIR, skill);
+      const destDir = path.join(baseDir, agent.skillDir, skill);
+
+      if (!fs.existsSync(srcDir)) continue;
+      if (fs.existsSync(destDir) && !overwrite) continue;
+
+      if (fs.existsSync(destDir) && overwrite) {
+        fs.rmSync(destDir, { recursive: true, force: true });
+      }
+
+      copyDirSync(srcDir, destDir);
+      copiedSkillsCount++;
+    }
+  }
+
+  const configuredRules = [];
+  const rulesContent = fs.existsSync(RULES_SOURCE_FILE)
+    ? fs.readFileSync(RULES_SOURCE_FILE, 'utf8')
+    : getPointerBlock(selectedSkills);
+
+  for (const agent of chosenAgents) {
+    if (!agent.ruleFile) continue;
+    const rulePath = path.join(baseDir, agent.ruleFile);
+    const isSpecialRule = agent.id === 'kilo' || agent.id === 'cline' || agent.id === 'cursor';
+    const contentToWrite = isSpecialRule ? rulesContent : getPointerBlock(selectedSkills);
+    const action = updateRuleFile(rulePath, contentToWrite, !isSpecialRule);
+    configuredRules.push({ file: agent.ruleFile, action });
+  }
+
+  s.stop(pc.green('Installation complete!'));
+
+  console.log('');
+  log.message(
+    pc.bold('Installed Skills & Configuration Details:') + '\n' +
+    chosenAgents.map(a => `  ${pc.cyan('●')} ${pc.bold(a.label)}: ${pc.dim(path.join(baseDir, a.skillDir))}`).join('\n') +
+    '\n' +
+    configuredRules.map(r => `  ${pc.green('✔')} Configured rule: ${pc.bold(r.file)} (${r.action})`).join('\n')
+  );
+
+  outro(
+    pc.bold(pc.green('waitsec is active.')) + ' ' +
+    pc.dim('Your AI will now think first, keep diffs small, and prevent overengineering.')
+  );
+}
+
+main().catch((err) => {
+  console.error(pc.red('Unexpected error:'), err);
+  process.exit(1);
+});

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "waitsec",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Practical guardrails for AI coding agents. Hold on, think first, code less.",
   "main": "rules/waitsec.md",
   "bin": {
-    "waitsec": "bin/cli.js"
+    "waitsec": "bin/cli.mjs"
   },
   "scripts": {
-    "start": "node ./bin/cli.js",
+    "start": "node ./bin/cli.mjs",
     "ship": "node ./scripts/ship.js"
   },
   "keywords": [
@@ -40,5 +40,9 @@
     "plugin.json",
     "README.md",
     "LICENSE"
-  ]
+  ],
+  "dependencies": {
+    "@clack/prompts": "^1.8.0",
+    "picocolors": "^1.1.1"
+  }
 }

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.4.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
+```

package/bin/cli.js

@@ -1,66 +0,0 @@
-#!/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();
-});