wb-flow 1.0.0-r01

package/CHANGELOG.md

@@ -0,0 +1,12 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0-r01] - 2026-05-10
+
+### Initial Release
+- **Zero-Dependency CLI:** Instant bootstrap via `npx wb-flow` without polluting your node_modules.
+- **31 `wb*` Command Templates:** Full suite of workflow templates injected directly into your `.wb/` directory.
+- **Multi-AI-Host Support:** Built-in parity for Claude Code, OpenCode, Gemini, and Cursor agents.
+- **Ideas Pipeline:** Enforces deterministic multi-step processes via `/wbAudit` → `/wbPlan` → `/wbWork` → `/wbValid`.
+- **Four Install Paths:** Supports global, local (npx), and offline/git-clone installation methods.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wissem Boughamoura <wissemb11@gmail.com>
+
+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,128 @@
+# 🌊 WB-Flow: The Agentic AI Workflow Engine
+
+[![npm version](https://badge.fury.io/js/wb-flow.svg)](https://badge.fury.io/js/wb-flow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+> **WB-Flow** is a zero-dependency CLI tool that instantly bootstraps a powerful, standardized Agentic AI workflow system into any repository.
+
+By copying a highly tuned set of 31 `/wb*` slash-command templates into your project, **WB-Flow** transforms generic AI coding assistants (like Claude Code, OpenCode, Gemini CLI, or Cursor) into disciplined, structured engineering teams.
+
+![wb-flow demo](assets/demo.gif)
+
+> *30-second tour: `npx wb-flow` materializes the full agentic workflow into your repo.*
+
+---
+
+## 🧐 What is it?
+WB-Flow provides a definitive "contract" between you and your AI coding agents. It installs a `.wb/` directory containing markdown templates that instruct the AI exactly **how** to behave when performing complex software engineering tasks.
+
+Instead of typing long, repetitive prompts, you simply type a command like `/wbAudit src/` or `/wbPlan`, and the AI reads the corresponding template to execute a deterministic, multi-step Standard Operating Procedure (SOP).
+
+**Universal:** WB-Flow is framework-agnostic. It works with Vue, React, Python, Go, Rust, or any codebase — the templates are pure Markdown and the bootstrapper has zero runtime dependencies beyond Node.
+
+## 🎯 What is it for?
+Unconstrained AI agents often hallucinate, drift off-task, or write "spaghetti" code when given large objectives. WB-Flow solves this by enforcing an **Ideas Pipeline**:
+1. **Audit:** Assess the codebase and identify technical debt (`/wbAudit`).
+2. **Plan:** Break down the work into a structured task backlog (`/wbPlan`).
+3. **Execute:** Work on atomic tasks one by one (`/wbWork`).
+4. **Validate:** Perform an adversarial QA review of the work (`/wbValid`).
+
+It ensures your AI follows strict monorepo conventions, maintains deep architectural context (`/wbContext`), and never goes rogue.
+
+## 🥊 Compared With...
+- **Raw AI Prompts / Chat:** You are at the mercy of the model's mood. With WB-Flow, the output format, reasoning steps, and constraints are rigidly defined in templates.
+- **Heavy Frameworks (e.g., LangChain, AutoGen):** Those require python environments, API keys, and complex orchestration. WB-Flow is **pure Markdown**. It requires zero dependencies and works locally with your existing IDE or CLI AI assistant.
+- **Persona-based agentic frameworks (e.g., BMAD-Method):** Those simulate a Scrum team — PM agent, Architect agent, Dev agent. WB-Flow inverts the model: **verbs over personas.** You don't ask "the QA agent" to audit code; you run `/wbAudit`. Tighter, more honest, less roleplay.
+
+---
+
+## 🚀 Installation
+
+WB-Flow supports **four install paths** — pick whichever fits your environment. All four invoke the same `bin/install.js` underneath, so behavior is identical.
+
+### Path 1 — One-shot via `npx` (Recommended)
+
+Zero-install, zero-pollution. Run it once to bootstrap your repo:
+```bash
+cd my-project/
+npx wb-flow
+```
+
+### Path 2 — Global install via npm
+
+For repeat use across many projects:
+```bash
+npm install -g wb-flow
+cd my-project/
+wb-flow
+```
+
+### Path 3 — Git clone + direct invocation (no npm needed)
+
+If you can't or don't want to use npm (air-gapped, restricted CI, offline dev):
+```bash
+git clone https://github.com/wissemb11/wb-flow.git ~/.wb-flow
+cd my-project/
+node ~/.wb-flow/bin/install.js
+```
+
+### Path 4 — Git clone + `npm link` (for contributors / local hacking)
+
+Same global `wb-flow` command as Path 2, but sourced from a local clone you can edit:
+```bash
+git clone https://github.com/wissemb11/wb-flow.git
+cd wb-flow
+npm link
+cd ~/my-project/
+wb-flow         # uses your local clone — edit templates and re-run instantly
+```
+
+### Bootstrap flags
+
+Once invoked, the bootstrapper accepts:
+
+- `--force` / `-f` — overwrite existing files (default: skip existing)
+- `--dry-run` / `-n` — preview without writing
+- `--list` / `-l` — print the bundled command roster (31 entries) and exit
+- `--help` / `-h` — show usage
+
+### Re-running on an existing project
+
+By default, `wb-flow` is **non-destructive** — it skips files that already exist in `.wb/`. Pass `--force` to overwrite, or `--dry-run` first to preview the diff. Your customizations to existing template copies are safe.
+
+---
+
+## ⚡ Quick Examples
+
+Once WB-Flow is installed, your AI assistant will understand the following commands (and 27 others!):
+
+* **Initialize the project AI identity:**
+  > `/wbSetup src/`
+* **Deep dive and score the code quality:**
+  > `/wbAudit src/components/`
+* **Create a task plan based on the audit:**
+  > `/wbPlan src/components/`
+* **Execute the tasks autonomously:**
+  > `/wbWork .wb/workflows/reports/.../plan_xyz.md *`
+
+> *Documentation site at [flow.wb-ui.com](https://flow.wb-ui.com) — coming soon. For now, the canonical reference is each `wbX/wbX_template.md` inside `.wb/commands/`.*
+
+---
+
+## 👨‍💻 About the Owner & Resources
+
+**WB-Flow** is created and maintained by **Wissem Boughamoura** as a standalone, framework-agnostic dev tool. It is independent of the Vue-based `wbc-ui` ecosystem (despite the shared author) and is free to use with any AI coding assistant.
+
+* 🐙 **GitHub:** [@wissemb11/wb-flow](https://github.com/wissemb11/wb-flow)
+* 📚 **Documentation (planned):** [flow.wb-ui.com](https://flow.wb-ui.com)
+* 👤 **Author:** [Wissem Boughamoura](https://github.com/wissemb11) — `wissemb11@gmail.com`
+
+### 📬 Contact & Support
+
+* Bugs / feature requests → [GitHub Issues](https://github.com/wissemb11/wb-flow/issues)
+* General questions → email `wissemb11@gmail.com`
+
+---
+*License: MIT © 2026 Wissem Boughamoura. See [LICENSE](LICENSE).*
+*Changelog: see [CHANGELOG.md](CHANGELOG.md).*

package/bin/install.js

@@ -0,0 +1,175 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+
+const TARGET_DIR = path.join(process.cwd(), '.wb');
+const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
+
+// Parse flags
+const args = process.argv.slice(2);
+const force = args.includes('--force') || args.includes('-f');
+const dryRun = args.includes('--dry-run') || args.includes('-n');
+const listCmd = args.includes('--list') || args.includes('-l');
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+  wb-flow — Bootstrap the /wb* agentic command system
+
+  Usage: npx wb-flow [options]
+
+  Options:
+    --force, -f     Overwrite existing files (default: skip existing)
+    --dry-run, -n   Show what would be copied without making changes
+    --list, -l      List the bundled command roster and exit
+    --help, -h      Show this help message
+
+  Copies templates/ into <cwd>/.wb/ to materialize the full
+  set of /wb* slash-command templates and shortcut grammar.
+  `);
+  process.exit(0);
+}
+
+
+if (listCmd) {
+  if (!fs.existsSync(TEMPLATES_DIR)) {
+    console.error('❌ Error: Internal templates directory not found.');
+    process.exit(1);
+  }
+  const manifestPath = path.join(TEMPLATES_DIR, 'commands', 'wb_commands_reference.json');
+  try {
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    console.log(`\n📦 Bundled Command Roster (${Object.keys(manifest).length} commands):\n`);
+    for (const [cmd, desc] of Object.entries(manifest)) {
+      console.log(`  - ${cmd.padEnd(15)} : ${typeof desc === 'object' ? desc.description : desc}`);
+    }
+    console.log('');
+  } catch (err) {
+    console.error('❌ Error reading command manifest:', err.message);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
+const stats = { created: 0, skipped: 0, updated: 0, errors: [] };
+
+function copyDirectory(src, dest) {
+  try {
+    if (!fs.existsSync(dest)) {
+      if (!dryRun) {
+        fs.mkdirSync(dest, { recursive: true });
+      }
+    }
+
+    const entries = fs.readdirSync(src, { withFileTypes: true });
+
+    for (const entry of entries) {
+      const srcPath = path.join(src, entry.name);
+      const destPath = path.join(dest, entry.name);
+
+      if (entry.isDirectory()) {
+        copyDirectory(srcPath, destPath);
+      } else {
+        try {
+          const exists = fs.existsSync(destPath);
+
+          if (exists && !force) {
+            stats.skipped++;
+          } else {
+            if (dryRun) {
+              const action = exists ? 'update' : 'create';
+              const relPath = path.relative(process.cwd(), destPath);
+              console.log(`  [${action}] ${relPath}`);
+            } else {
+              fs.copyFileSync(srcPath, destPath);
+            }
+
+            if (exists) {
+              stats.updated++;
+            } else {
+              stats.created++;
+            }
+          }
+        } catch (err) {
+          const relPath = path.relative(process.cwd(), destPath);
+          stats.errors.push({ file: relPath, error: err.message });
+        }
+      }
+    }
+  } catch (err) {
+    const relPath = path.relative(process.cwd(), src);
+    stats.errors.push({ file: relPath, error: err.message });
+  }
+}
+
+console.log('🚀 Initializing wb-flow inside your project...');
+
+if (dryRun) {
+  console.log('📋 DRY RUN — no files will be modified.\n');
+}
+
+if (fs.existsSync(TARGET_DIR)) {
+  if (force) {
+    console.log(`⚠️  .wb/ folder already exists in ${process.cwd()}. Overwriting (--force)...`);
+  } else {
+    console.log(`📁 .wb/ folder already exists in ${process.cwd()}. New files only (use --force to overwrite).`);
+  }
+} else {
+  console.log(`📁 Creating .wb/ folder in ${process.cwd()}...`);
+}
+
+if (!fs.existsSync(TEMPLATES_DIR)) {
+  console.error('\n❌ Error: Internal templates directory not found.');
+  console.error(`   Expected path: ${TEMPLATES_DIR}`);
+  console.error('   This usually means the package installation is corrupted. Please reinstall @wbc-ui/wb-flow.');
+  process.exit(1);
+}
+
+copyDirectory(TEMPLATES_DIR, TARGET_DIR);
+
+// Version stamp
+const pkgPath = path.join(__dirname, '..', 'package.json');
+try {
+  const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+  const wbDir = TARGET_DIR;
+  if (!dryRun) {
+    if (!fs.existsSync(wbDir)) {
+      fs.mkdirSync(wbDir, { recursive: true });
+    }
+    fs.writeFileSync(path.join(wbDir, '.wb-flow-version'), pkg.version + '\n');
+  }
+  if (dryRun) {
+    console.log(`  [create] .wb/.wb-flow-version → ${pkg.version}`);
+  }
+} catch (_) {
+  // Non-fatal: version stamp is informational only
+}
+
+// Post-install guidance
+if (!dryRun) {
+  const docsUrl = 'https://flow.wb-ui.com';
+  console.log('');
+  console.log('📍 Templates installed to: .wb/');
+  console.log('📖 Documentation: ' + docsUrl);
+  console.log('🚀 Start here: /wbSetup <your-project-path>');
+}
+
+// Summary
+if (dryRun) {
+  console.log(`\n📋 Dry run complete: ${stats.created} to create, ${stats.updated} to update, ${stats.skipped} to skip.`);
+} else {
+  const parts = [];
+  if (stats.created > 0) parts.push(`${stats.created} created`);
+  if (stats.updated > 0) parts.push(`${stats.updated} updated`);
+  if (stats.skipped > 0) parts.push(`${stats.skipped} skipped`);
+  console.log(`✅ Done! ${parts.join(', ')}.`);
+}
+
+if (stats.errors.length > 0) {
+  console.error(`\n⚠️  ${stats.errors.length} error(s) during copy:`);
+  for (const { file, error } of stats.errors) {
+    console.error(`  ✗ ${file}: ${error}`);
+  }
+  process.exit(1);
+}
+

package/bin/link.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * bin/link.js — Monorepo-internal wrapper wiring tool.
+ *
+ * PURPOSE: Rewrites .claude/commands/ wrappers to point at the local .wb/ copies
+ * instead of the raw templates/ path inside the wb-flow package.
+ *
+ * CONSUMER NOTE: This script is for MONOREPO-INTERNAL DEVELOPMENT ONLY.
+ * It writes to MONOREPO_ROOT/.claude/commands/ (5 levels up from this package).
+ * npm consumers of @wbc-ui/wb-flow cannot use this script — they should instead
+ * run `npx wb-flow` which copies templates directly to their project .wb/.
+ *
+ * USAGE: Run from the monorepo root (wb-labs/), after `npx wb-flow` has been
+ * executed to populate the .wb/ commands directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const projectRoot = process.cwd();
+
+if (projectRoot.includes('packages/wb-flow')) {
+  console.error('❌ Error: bin/link.js must be run from a consumer project root,');
+  console.error('   not from inside the wb-flow package directory.');
+  console.error('   This script writes wrappers to MONOREPO_ROOT/.claude/commands/');
+  console.error('   and is not usable by npm consumers of @wbc-ui/wb-flow.');
+  console.error('   For monorepo-internal development only.');
+  process.exit(1);
+}
+
+const claudeCommandsDir = path.join(projectRoot, '.claude', 'commands');
+const wbCommandsDir = path.join(projectRoot, '.wb', 'commands');
+
+if (!fs.existsSync(claudeCommandsDir)) {
+  console.log('No .claude/commands directory found. Nothing to link.');
+  process.exit(0);
+}
+
+if (!fs.existsSync(wbCommandsDir)) {
+  console.log('No .wb/commands directory found. Please run npx wb-flow first.');
+  process.exit(1);
+}
+
+console.log('🔗 Wiring .claude/commands/ wrappers to .wb/ template copies...');
+let updated = 0;
+
+const files = fs.readdirSync(claudeCommandsDir);
+for (const file of files) {
+  if (file.endsWith('.md')) {
+    const cmdName = file.replace('.md', '');
+    const wrapperPath = path.join(claudeCommandsDir, file);
+    
+    // Check if the corresponding command exists in .wb/commands
+    const targetTemplatePath = path.posix.join('.wb', 'commands', cmdName, `${cmdName}_template.md`);
+    if (fs.existsSync(path.join(projectRoot, targetTemplatePath))) {
+      let content = fs.readFileSync(wrapperPath, 'utf8');
+      
+      // We want to replace paths that point into frontEnd/wbc-ui/.../templates/commands/ with .wb/commands/
+      const rgx = /frontEnd\/wbc-ui\/core2\/packages\/wb-flow\/templates\/commands\/[a-zA-Z0-9_]+\/[a-zA-Z0-9_]+_template\.md/g;
+      
+      if (rgx.test(content)) {
+        content = content.replace(rgx, targetTemplatePath);
+        fs.writeFileSync(wrapperPath, content);
+        updated++;
+        console.log(`  [linked] ${file} -> ${targetTemplatePath}`);
+      }
+    }
+  }
+}
+
+console.log(`✅ Done. Updated ${updated} wrappers.`);

package/bin/verify-wrappers.js

@@ -0,0 +1,49 @@
+#!/usr/bin/env node
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+// Note: we are currently executing inside frontEnd/wbc-ui/core2/packages/wb-flow/
+// The wrappers are 5 levels up in the project root.
+const MONOREPO_ROOT = path.resolve(PKG_ROOT, '..', '..', '..', '..', '..');
+
+const TEMPLATES_DIR = path.join(PKG_ROOT, 'templates', 'commands');
+const CLAUDE_DIR = path.join(MONOREPO_ROOT, '.claude', 'commands');
+const OPENCODE_DIR = path.join(MONOREPO_ROOT, '.config', 'opencode', 'command');
+
+if (!fs.existsSync(TEMPLATES_DIR)) {
+  console.error('❌ Templates dir not found');
+  process.exit(1);
+}
+
+const manifestPath = path.join(TEMPLATES_DIR, 'wb_commands_reference.json');
+const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+const commands = Object.keys(manifest);
+
+let errors = 0;
+
+console.log('🔍 Verifying wrapper parity across clients...');
+
+for (const cmd of commands) {
+  // Check Claude
+  const claudeFile = path.join(CLAUDE_DIR, `${cmd}.md`);
+  if (!fs.existsSync(claudeFile)) {
+    console.error(`  ✗ Missing Claude wrapper: ${cmd}.md`);
+    errors++;
+  }
+  
+  // Check OpenCode
+  const opencodeFile = path.join(OPENCODE_DIR, `${cmd}.md`);
+  if (!fs.existsSync(opencodeFile)) {
+    console.error(`  ✗ Missing OpenCode wrapper: ${cmd}.md`);
+    errors++;
+  }
+}
+
+if (errors > 0) {
+  console.error(`\n❌ Wrapper drift detected: ${errors} missing wrapper(s).`);
+  process.exit(1);
+}
+
+console.log('✅ Wrapper parity confirmed (100% coverage).');
+process.exit(0);

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "wb-flow",
+  "version": "1.0.0-r01",
+  "description": "Zero-dependency CLI that bootstraps an agentic AI workflow system into any repo. Universal — works with Vue, React, Python, or any codebase. Compatible with Claude Code, OpenCode, Gemini CLI, Cursor, and other AI coding assistants.",
+  "bin": {
+    "wb-flow": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "templates/",
+    "assets/demo.gif",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "test": "node test/smoke.js && node bin/verify-wrappers.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "ai",
+    "agentic",
+    "agentic-ai",
+    "workflow",
+    "claude",
+    "claude-code",
+    "gemini",
+    "opencode",
+    "cursor",
+    "cli",
+    "sop",
+    "developer-tools",
+    "templates",
+    "scaffolding",
+    "zero-dependency"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wissemb11/wb-flow.git"
+  },
+  "homepage": "https://flow.wb-ui.com",
+  "bugs": {
+    "url": "https://github.com/wissemb11/wb-flow/issues",
+    "email": "wissemb11@gmail.com"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "author": {
+    "name": "Wissem Boughamoura",
+    "email": "wissemb11@gmail.com",
+    "url": "https://github.com/wissemb11"
+  },
+  "license": "MIT",
+  "type": "commonjs"
+}