start-vibing 1.1.1

package/README.md

@@ -0,0 +1,149 @@
+# start-vibing
+
+> Setup Claude Code agents, skills, and hooks in your project with a single command.
+
+## Quick Start
+
+```bash
+# Using npx
+npx start-vibing
+
+# Using bunx (faster)
+bunx start-vibing
+```
+
+## What It Does
+
+Sets up a complete Claude Code development workflow in your project:
+
+```
+.claude/
+├── agents/          # 11 specialized AI agents
+│   ├── orchestrator.md      # Coordinates workflow
+│   ├── analyzer.md          # Analyzes change impact
+│   ├── research.md          # Researches best practices
+│   ├── tester.md            # Creates tests (Playwright + Vitest)
+│   ├── security-auditor.md  # Security audit (VETO power)
+│   ├── quality-checker.md   # Quality gates
+│   └── ...
+├── skills/          # 8 skill systems
+│   ├── test-coverage/       # E2E testing templates
+│   ├── security-scan/       # OWASP validation
+│   ├── codebase-knowledge/  # Domain mapping
+│   └── ...
+├── hooks/           # Workflow enforcement
+│   ├── pre-tool-use.py      # Blocks unapproved edits
+│   ├── post-tool-use.py     # Tracks modifications
+│   ├── stop-validation.py   # Blocks incomplete work
+│   └── workflow-manager.py  # CLI for state tracking
+└── config/          # Project configuration
+    ├── project-config.json
+    ├── quality-gates.json
+    └── ...
+```
+
+## Features
+
+### 11 Specialized Agents
+
+| Agent            | Purpose                     | VETO |
+| ---------------- | --------------------------- | ---- |
+| orchestrator     | Coordinates entire workflow | No   |
+| analyzer         | Analyzes change impact      | No   |
+| research         | Best practices research     | No   |
+| documenter       | Documentation updates       | No   |
+| tester           | Unit + E2E tests            | No   |
+| security-auditor | Security audit              | Yes  |
+| ui-ux-reviewer   | UI/UX review                | No   |
+| quality-checker  | Quality gates               | No   |
+| final-validator  | Final validation            | Yes  |
+| domain-updater   | Domain knowledge            | No   |
+| commit-manager   | Git commits                 | No   |
+
+### Smart Copy Behavior
+
+When you run `start-vibing` in an existing project:
+
+- **ALWAYS overwrites:** Agent files, hooks, settings.json
+- **PRESERVES:** Your custom domains, cached research
+- **MERGES:** New skills with existing ones
+
+Use `--force` to overwrite everything.
+
+### Workflow Enforcement
+
+Hooks enforce the workflow:
+
+1. **pre-tool-use.py** - Blocks file edits without approved task
+2. **post-tool-use.py** - Auto-tracks all modifications
+3. **stop-validation.py** - Blocks incomplete workflows
+
+## Usage
+
+### First Setup
+
+```bash
+cd your-project
+npx start-vibing
+```
+
+### Update to Latest
+
+```bash
+npx start-vibing --force
+```
+
+### After Setup
+
+```bash
+# 1. Configure your project
+edit .claude/config/project-config.json
+
+# 2. Start a task
+python .claude/hooks/workflow-manager.py start-task --type feature --description "Add feature X"
+
+# 3. Work with Claude Code
+# The agents will guide you through the workflow
+```
+
+## Configuration
+
+After setup, edit `.claude/config/project-config.json`:
+
+```json
+{
+  "stack": {
+    "runtime": "bun",
+    "language": "typescript",
+    "database": "mongodb"
+  },
+  "commands": {
+    "typecheck": "bun run typecheck",
+    "lint": "bun run lint",
+    "test": "bun run test",
+    "build": "bun run build"
+  }
+}
+```
+
+## Options
+
+| Flag        | Description                    |
+| ----------- | ------------------------------ |
+| `--force`   | Overwrite all files            |
+| `--help`    | Show help message              |
+| `--version` | Show version                   |
+
+## Requirements
+
+- Node.js >= 18 or Bun
+- Python 3.x (for hooks)
+
+## License
+
+MIT
+
+## Links
+
+- [Claude Code Documentation](https://docs.claude.dev)
+- [Report Issues](https://github.com/joaov/start-vibing/issues)

package/dist/cli.js

@@ -0,0 +1,199 @@
+#!/usr/bin/env node
+
+// src/copy.ts
+import { existsSync, mkdirSync, readdirSync, statSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+var __filename2 = fileURLToPath(import.meta.url);
+var __dirname2 = dirname(__filename2);
+var ALWAYS_OVERWRITE = [
+  "agents/",
+  "hooks/",
+  "settings.json",
+  "CLAUDE.md",
+  "commands/"
+];
+var NEVER_OVERWRITE = [
+  "skills/codebase-knowledge/domains/",
+  "skills/research-cache/cache/",
+  "config/project-config.json",
+  "workflow-state.json"
+];
+function matchesPattern(filePath, patterns) {
+  const normalized = filePath.replace(/\\/g, "/");
+  return patterns.some((pattern) => {
+    if (pattern.endsWith("/")) {
+      return normalized.includes(pattern) || normalized.startsWith(pattern);
+    }
+    return normalized.endsWith(pattern) || normalized.includes(pattern);
+  });
+}
+function copyRecursive(src, dest, options, result, basePath = "") {
+  const stats = statSync(src);
+  if (stats.isDirectory()) {
+    if (!existsSync(dest)) {
+      mkdirSync(dest, { recursive: true });
+    }
+    const entries = readdirSync(src);
+    for (const entry of entries) {
+      const srcPath = join(src, entry);
+      const destPath = join(dest, entry);
+      const relativePath = join(basePath, entry);
+      copyRecursive(srcPath, destPath, options, result, relativePath);
+    }
+  } else {
+    const relativePath = basePath;
+    if (!options.force && matchesPattern(relativePath, NEVER_OVERWRITE)) {
+      if (existsSync(dest)) {
+        result.preserved++;
+        return;
+      }
+    }
+    const shouldOverwrite = options.force || matchesPattern(relativePath, ALWAYS_OVERWRITE);
+    if (existsSync(dest) && !shouldOverwrite) {
+      result.preserved++;
+      return;
+    }
+    const destDir = dirname(dest);
+    if (!existsSync(destDir)) {
+      mkdirSync(destDir, { recursive: true });
+    }
+    copyFileSync(src, dest);
+    const normalizedPath = relativePath.replace(/\\/g, "/");
+    if (normalizedPath.startsWith("agents/") || normalizedPath.includes("/agents/")) {
+      result.agents++;
+    } else if (normalizedPath.startsWith("skills/") || normalizedPath.includes("/skills/")) {
+      result.skills++;
+    } else if (normalizedPath.startsWith("hooks/") || normalizedPath.includes("/hooks/")) {
+      result.hooks++;
+    } else if (normalizedPath.startsWith("config/") || normalizedPath.includes("/config/")) {
+      result.config++;
+    }
+  }
+}
+async function copyClaudeSetup(targetDir, options = {}) {
+  const possiblePaths = [
+    join(__dirname2, "..", "template"),
+    join(__dirname2, "..", "..", "template"),
+    join(__dirname2, "template")
+  ];
+  let templateDir = "";
+  for (const path of possiblePaths) {
+    if (existsSync(path)) {
+      templateDir = path;
+      break;
+    }
+  }
+  if (!templateDir) {
+    throw new Error(`Template directory not found. Tried: ${possiblePaths.join(", ")}`);
+  }
+  console.log(`  Using template from: ${templateDir}`);
+  console.log(`  Target directory: ${targetDir}\n`);
+  const destDir = join(targetDir, ".claude");
+  const result = {
+    agents: 0,
+    skills: 0,
+    hooks: 0,
+    config: 0,
+    preserved: 0
+  };
+  const claudeTemplate = join(templateDir, ".claude");
+  if (existsSync(claudeTemplate)) {
+    copyRecursive(claudeTemplate, destDir, options, result);
+  }
+  const claudeMdTemplate = join(templateDir, "CLAUDE.md");
+  const claudeMdDest = join(targetDir, "CLAUDE.md");
+  if (existsSync(claudeMdTemplate)) {
+    if (!existsSync(claudeMdDest) || options.force) {
+      copyFileSync(claudeMdTemplate, claudeMdDest);
+    }
+  }
+  return result;
+}
+
+// src/cli.ts
+import { existsSync as existsSync2 } from "fs";
+import { join as join2 } from "path";
+var VERSION = "1.0.0";
+var BANNER = `
+  _____ _             _    __     __ _  _      _
+ / ____| |           | |   \\ \\   / /(_)| |    (_)
+| (___ | |_  __ _ _ __| |_   \\ \\_/ /  _ | |__   _  _ __   __ _
+ \\___ \\| __|/ _\` | '__| __|   \\   /  | || '_ \\ | || '_ \\ / _\` |
+ ____) | |_| (_| | |  | |_     | |   | || |_) || || | | || (_| |
+|_____/ \\__|\\__,_|_|   \\__|    |_|   |_||_.__/ |_||_| |_| \\__, |
+                                                          __/ |
+                                                         |___/
+`;
+var HELP = `
+${BANNER}
+  Setup Claude Code agents, skills, and hooks in your project.
+
+  Usage:
+    npx start-vibing [options]
+    bunx start-vibing [options]
+
+  Options:
+    --force       Overwrite all files (including custom domains)
+    --help, -h    Show this help message
+    --version, -v Show version
+
+  What it does:
+    1. Creates .claude/ folder in current directory
+    2. Copies 11 specialized agents for development workflow
+    3. Copies 8 skills with templates and rules
+    4. Sets up hooks for workflow enforcement
+    5. Preserves your existing domains and custom skills
+
+  Smart Copy Behavior:
+    - ALWAYS overwrites: agents/*.md, hooks/*.py, settings.json
+    - PRESERVES: skills/*/domains/*.md (your custom domains)
+    - MERGES: Adds new skills, keeps your customizations
+
+  After setup:
+    1. Configure your project in .claude/config/project-config.json
+    2. Start with: python .claude/hooks/workflow-manager.py start-task --type feature --description "..."
+
+  Documentation:
+    https://github.com/joaov/start-vibing
+`;
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    process.exit(0);
+  }
+  if (args.includes("--version") || args.includes("-v")) {
+    console.log(`start-vibing v${VERSION}`);
+    process.exit(0);
+  }
+  const force = args.includes("--force");
+  const targetDir = process.cwd();
+  console.log(BANNER);
+  console.log("  Setting up Claude Code workflow...\n");
+  const claudeDir = join2(targetDir, ".claude");
+  if (existsSync2(claudeDir) && !force) {
+    console.log("  Found existing .claude/ folder.");
+    console.log("  Will preserve your custom domains and merge with new files.\n");
+  }
+  try {
+    const result = await copyClaudeSetup(targetDir, { force });
+    console.log("\n  Setup complete!\n");
+    console.log("  Files created/updated:");
+    console.log(`    - Agents: ${result.agents} files`);
+    console.log(`    - Skills: ${result.skills} files`);
+    console.log(`    - Hooks: ${result.hooks} files`);
+    console.log(`    - Config: ${result.config} files`);
+    if (result.preserved > 0) {
+      console.log(`\n  Preserved ${result.preserved} custom file(s) (domains, etc.)`);
+    }
+    console.log("\n  Next steps:");
+    console.log("    1. Edit .claude/config/project-config.json with your stack");
+    console.log('    2. Run: python .claude/hooks/workflow-manager.py start-task --type feature --description "..."');
+    console.log("    3. Follow the agent workflow for your development\n");
+  } catch (error) {
+    console.error("\n  Error during setup:", error);
+    process.exit(1);
+  }
+}
+main();

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "start-vibing",
+  "version": "1.1.1",
+  "description": "Setup Claude Code agents, skills, and hooks in your project. Smart copy that preserves your custom domains and configurations.",
+  "type": "module",
+  "bin": {
+    "start-vibing": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "template"
+  ],
+  "scripts": {
+    "build": "bun build ./src/cli.ts --outdir ./dist --target node",
+    "dev": "bun run ./src/cli.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "agents",
+    "skills",
+    "hooks",
+    "automation",
+    "workflow",
+    "cli"
+  ],
+  "author": "joaov",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/joaov/start-vibing"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0"
+  }
+}

package/template/.claude/CLAUDE.md

@@ -0,0 +1,168 @@
+# Claude Development System - Agent Context
+
+This file provides context for all agents. For user-facing rules, see `/CLAUDE.md`.
+
+---
+
+## System Architecture
+
+```
+.claude/
+├── agents/          # 11 specialized agents (READ before acting)
+├── skills/          # 8 skill systems with cache
+├── config/          # Project-specific configuration
+├── commands/        # Slash commands
+└── hooks/           # Security hooks
+```
+
+---
+
+## Configuration Files
+
+Project-specific settings are in `.claude/config/`:
+
+| File                   | Purpose                              |
+| ---------------------- | ------------------------------------ |
+| `project-config.json`  | Stack, structure, commands           |
+| `domain-mapping.json`  | File patterns to domains             |
+| `quality-gates.json`   | Quality check commands               |
+| `testing-config.json`  | Test framework and conventions       |
+| `security-rules.json`  | Security audit rules                 |
+
+**RULE:** Agents MUST read config files before acting. Do NOT hardcode project specifics.
+
+---
+
+## Agent → Skill Mapping
+
+| Agent            | Primary Skill      | Secondary                        |
+| ---------------- | ------------------ | -------------------------------- |
+| analyzer         | codebase-knowledge | -                                |
+| research         | research-cache     | codebase-knowledge               |
+| documenter       | docs-tracker       | codebase-knowledge               |
+| tester           | test-coverage      | -                                |
+| ui-ux-reviewer   | ui-ux-audit        | -                                |
+| security-auditor | security-scan      | -                                |
+| quality-checker  | quality-gate       | -                                |
+| final-validator  | final-check        | ALL                              |
+| commit-manager   | workflow-state     | docs-tracker, codebase-knowledge |
+| domain-updater   | codebase-knowledge | docs-tracker                     |
+
+---
+
+## Execution Protocol
+
+### Before ANY implementation:
+
+1. **Start task** via `workflow-manager.py start-task --type [feature|fix|refactor] --description "..."`
+2. **Read config** from `.claude/config/` for project specifics
+3. Read relevant skill SKILL.md file
+4. Check skill cache for existing data
+5. Research if needed (web search)
+6. **Approve files** via `workflow-manager.py approve-files --files "path/to/file.ts"`
+
+### After implementation:
+
+1. Update skill cache with changes
+2. Run quality gates + record results
+3. Security audit (if auth/data involved)
+4. Final validation
+5. **Mark workflow ready** via `workflow-manager.py final-validation --result approved --ready-to-commit true`
+6. **Update domains** via domain-updater agent (BEFORE commit, keeps git clean)
+7. **Commit + complete task** via commit-manager agent (FINAL step, runs complete-task)
+
+---
+
+## Workflow State Tracking
+
+Location: `.claude/workflow-state.json`
+
+### CLI Commands (MANDATORY)
+
+```bash
+# 1. Start task (MUST be first)
+python .claude/hooks/workflow-manager.py start-task --type feature --description "..."
+
+# 2. After analyzer approves, register files
+python .claude/hooks/workflow-manager.py approve-files --files "src/*.ts"
+
+# 3. After each agent
+python .claude/hooks/workflow-manager.py agent-executed --agent [name] --result approved
+
+# 4. After quality gates
+python .claude/hooks/workflow-manager.py quality-gate --gate [typecheck|lint|build] --passed true
+
+# 5. Final validation
+python .claude/hooks/workflow-manager.py final-validation --result approved --ready-to-commit true
+
+# 6. After commit
+python .claude/hooks/workflow-manager.py complete-task --commit-hash [hash]
+```
+
+### Hooks Enforcement
+
+- **PreToolUse**: Blocks file edits if task not started or file not approved
+- **PostToolUse**: Auto-tracks all file modifications
+- **Stop**: Blocks session end if workflow incomplete
+- **Husky**: Blocks commit if validation failed
+
+---
+
+## VETO Power Agents
+
+These agents CAN and MUST stop the flow if rules are violated:
+
+| Agent                | Blocks When                                        |
+| -------------------- | -------------------------------------------------- |
+| **security-auditor** | User ID from request, sensitive data, no validation |
+| **final-validator**  | Any rule violated, tests failing, docs missing      |
+
+---
+
+## Quality Requirements
+
+All implementations MUST:
+
+- [ ] Pass typecheck (command from config)
+- [ ] Pass lint (command from config)
+- [ ] Pass unit tests (command from config)
+- [ ] Pass E2E tests (command from config)
+- [ ] Pass build (command from config)
+- [ ] Have E2E tests with real auth
+- [ ] Have documentation in `docs/`
+- [ ] Be security audited
+- [ ] Be committed with conventional commits
+- [ ] Have domains updated with session learnings
+
+---
+
+## Domain Updater Agent
+
+The **domain-updater** runs BEFORE commit-manager to ensure git stays clean.
+
+### Purpose
+
+- Document **problems encountered** during the session
+- Record **solutions** applied to fix issues
+- Add **prevention tips** for future sessions
+- Update **attention points** with new learnings
+- Keep domain knowledge **current and accurate**
+
+### Trigger
+
+Runs automatically:
+1. After final-validator approves in any workflow
+2. BEFORE commit-manager (so changes are included in commit)
+3. Stop hook blocks session end until domain-updater executes (if files were modified)
+
+### Workflow Order
+
+```
+final-validator → domain-updater → commit-manager → complete-task
+                       ↑                    ↑
+              (updates domains)    (commits all + archives)
+```
+
+### Configuration
+
+Reads domain patterns from `.claude/config/domain-mapping.json`