create-bashi-starter 1.0.0

package/bin/create-bashi-starter.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+
+const BOLD = "\x1b[1m";
+const GREEN = "\x1b[32m";
+const YELLOW = "\x1b[33m";
+const RED = "\x1b[31m";
+const DIM = "\x1b[2m";
+const RESET = "\x1b[0m";
+
+const VERSION = require("../package.json").version;
+const TEMPLATE_DIR = path.join(__dirname, "..", "template");
+
+function log(msg) {
+  console.log(msg);
+}
+
+function success(msg) {
+  console.log(`${GREEN}${msg}${RESET}`);
+}
+
+function warn(msg) {
+  console.log(`${YELLOW}${msg}${RESET}`);
+}
+
+function error(msg) {
+  console.error(`${RED}${msg}${RESET}`);
+}
+
+function copyDirRecursive(src, dest, stats) {
+  if (!fs.existsSync(src)) return;
+
+  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()) {
+      if (!fs.existsSync(destPath)) {
+        fs.mkdirSync(destPath, { recursive: true });
+      }
+      copyDirRecursive(srcPath, destPath, stats);
+    } else {
+      if (fs.existsSync(destPath)) {
+        stats.skipped++;
+      } else {
+        fs.mkdirSync(path.dirname(destPath), { recursive: true });
+        fs.copyFileSync(srcPath, destPath);
+        stats.copied++;
+      }
+    }
+  }
+}
+
+function copyDirForce(src, dest, stats) {
+  if (!fs.existsSync(src)) return;
+
+  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()) {
+      if (!fs.existsSync(destPath)) {
+        fs.mkdirSync(destPath, { recursive: true });
+      }
+      copyDirForce(srcPath, destPath, stats);
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      fs.copyFileSync(srcPath, destPath);
+      stats.copied++;
+    }
+  }
+}
+
+function main() {
+  const args = process.argv.slice(2);
+
+  if (args.includes("--help") || args.includes("-h")) {
+    log(`
+${BOLD}create-bashi-starter${RESET} v${VERSION}
+
+Set up Bashi Starter in any project.
+
+${BOLD}Usage:${RESET}
+  cd your-project
+  npx create-bashi-starter              Install in current directory
+
+  Starting fresh? npx create-bashi-starter my-app creates a new directory.
+
+${BOLD}Options:${RESET}
+  --help, -h     Show this help message
+  --version, -v  Show version number
+  --force        Overwrite existing files (default: skip)
+
+${BOLD}What you get:${RESET}
+  3 agents (orchestrator, builder, reviewer)
+  6 skills (plan, PRD, tasks, frontend, code review, deploy)
+  6 commands (/start, /capture-idea, /run-project, /setup, /status, /save)
+  3 safety hooks
+
+${BOLD}After install:${RESET}
+  Open the project in VS Code with Claude Code and run /start
+
+${BOLD}Want more?${RESET}
+  Bashi Starter covers the core pipeline: idea to shipped product.
+  The full Bashi framework adds 12 agents, 40+ skills, overnight mode,
+  parallel execution, and more. Learn more in "The Syntax Wall" book.
+`);
+    process.exit(0);
+  }
+
+  if (args.includes("--version") || args.includes("-v")) {
+    log(VERSION);
+    process.exit(0);
+  }
+
+  const force = args.includes("--force");
+  const dirArg = args.find((a) => !a.startsWith("-"));
+  const targetDir = dirArg ? path.resolve(dirArg) : process.cwd();
+
+  log("");
+  log(`${BOLD}Bashi Starter${RESET} v${VERSION}`);
+  log(
+    `${DIM}3 agents | 6 skills | 6 commands | 3 safety hooks${RESET}`
+  );
+  log("");
+
+  if (!fs.existsSync(targetDir)) {
+    fs.mkdirSync(targetDir, { recursive: true });
+    log(`Created directory: ${dirArg}`);
+  }
+
+  const claudeDir = path.join(targetDir, ".claude");
+  if (fs.existsSync(claudeDir) && !force) {
+    warn("A .claude/ directory already exists in this project.");
+    warn("Use --force to overwrite, or remove it first.");
+    log("");
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(TEMPLATE_DIR)) {
+    error("Template directory not found. Package may be corrupted.");
+    process.exit(1);
+  }
+
+  log("Installing framework...");
+  log("");
+
+  const stats = { copied: 0, skipped: 0 };
+
+  if (force && fs.existsSync(claudeDir)) {
+    copyDirForce(TEMPLATE_DIR, targetDir, stats);
+  } else {
+    copyDirRecursive(TEMPLATE_DIR, targetDir, stats);
+  }
+
+  const gitDir = path.join(targetDir, ".git");
+  if (!fs.existsSync(gitDir)) {
+    log(`${DIM}Initializing git repository...${RESET}`);
+    const { execSync } = require("child_process");
+    try {
+      execSync("git init", { cwd: targetDir, stdio: "pipe" });
+      log(`${DIM}Git repository initialized.${RESET}`);
+    } catch {
+      warn(
+        "Could not initialize git. You may need to run 'git init' manually."
+      );
+    }
+  }
+
+  log(`  ${GREEN}Copied:${RESET}  ${stats.copied} files`);
+  if (stats.skipped > 0) {
+    log(`  ${YELLOW}Skipped:${RESET} ${stats.skipped} files (already exist)`);
+  }
+  log("");
+
+  success("Bashi Starter installed!");
+  log("");
+  log(`${BOLD}Next steps:${RESET}`);
+  if (dirArg) {
+    log(`  1. cd ${dirArg}`);
+    log(`  2. Open in VS Code with Claude Code`);
+    log(`  3. Run /start`);
+  } else {
+    log(`  1. Open this project in VS Code with Claude Code`);
+    log(`  2. Run /start`);
+  }
+
+  log("");
+  log(`${DIM}Documentation: README.md${RESET}`);
+  log(`${DIM}Full reference: .claude/REFERENCE.md${RESET}`);
+  log("");
+}
+
+main();

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "create-bashi-starter",
+  "version": "1.0.0",
+  "description": "Set up Bashi Starter in any project. A lightweight AI orchestration framework for building your first project with AI.",
+  "bin": {
+    "create-bashi-starter": "./bin/create-bashi-starter.js"
+  },
+  "files": [
+    "bin/",
+    "template/"
+  ],
+  "keywords": [
+    "ai",
+    "orchestration",
+    "claude",
+    "framework",
+    "starter",
+    "bashi"
+  ],
+  "author": "Bashar Amso",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BasharAmso/bashi-starter"
+  }
+}

package/template/.claude/CLAUDE.md

@@ -0,0 +1,70 @@
+# CLAUDE.md -- Bashi Starter Context Index
+
+> This file is loaded automatically on every session. Keep it concise.
+
+## Project Identity
+
+- **Template:** Bashi Starter
+- **Problem:** The Syntax Wall (you can architect and direct, but writing code line-by-line blocks shipping)
+- **Method:** AI Orchestration Framework (agents, skills, and state machine for structured AI development)
+- **Variant:** Starter (3 agents, 6 skills, 6 commands)
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `FRAMEWORK_VERSION` | Semver version stamp |
+| `README.md` | Overview, quick start, and command reference |
+| `.claude/project/STATE.md` | Current task, mode, blockers, history |
+| `.claude/project/EVENTS.md` | Event queue (unprocessed + processed) |
+| `.claude/skills/REGISTRY.md` | Skill index with triggers |
+| `.claude/agents/orchestrator.md` | Core agent: event/task processing loop |
+
+## Rules (auto-loaded by Claude Code)
+
+| Rule File | Governs |
+|-----------|---------|
+| `.claude/rules/orchestration-routing.md` | Task type to agent routing |
+| `.claude/rules/context-policy.md` | Chat context conservation and artifact persistence |
+| `.claude/rules/user-consent.md` | Never auto-select when a procedure says to ask the user |
+
+## Knowledge Base (`.claude/project/knowledge/`)
+
+| File | Contains |
+|------|----------|
+| `DECISIONS.md` | Architectural and design decisions |
+| `GLOSSARY.md` | Term definitions |
+| `OPEN_QUESTIONS.md` | Unresolved questions and uncertainties |
+
+## Commands
+
+| Command | Entry Point |
+|---------|-------------|
+| `/start` | `.claude/commands/start.md` |
+| `/capture-idea` | `.claude/commands/capture-idea.md` |
+| `/run-project` | `.claude/commands/run-project.md` |
+| `/setup` | `.claude/commands/setup.md` |
+| `/status` | `.claude/commands/status.md` |
+| `/save` | `.claude/commands/save.md` |
+
+## Context Loading Policy
+
+Load context incrementally:
+
+| Situation | Load |
+|-----------|------|
+| **Default (any task)** | This file + relevant rules for the task type |
+| **Conceptual / design work** | + `DECISIONS.md` + `GLOSSARY.md` |
+| **Uncertainty or ambiguity** | + `OPEN_QUESTIONS.md` |
+| **Running the system** | + `STATE.md` + `EVENTS.md` + `REGISTRY.md` |
+
+> Do NOT load all files at once. Read only what the current task requires.
+
+## Conventions
+
+- STATE.md is the single source of truth for current work.
+- Every action must update STATE before completing.
+- Events are processed oldest-first (FIFO).
+- Default mode is Semi-Autonomous: one unit of work, then stop.
+
+> Architecture primitives and command reference: `.claude/REFERENCE.md`

package/template/.claude/REFERENCE.md

@@ -0,0 +1,68 @@
+# Bashi Starter Reference
+
+> Not auto-loaded. Read on demand for architecture details.
+
+## Architecture Primitives
+
+| Primitive | What It Is |
+|-----------|-----------|
+| **Command** | A user-facing entry point (e.g., `/run-project`). Reads state, executes logic, updates state. |
+| **State** | `STATE.md` tracks what's done, in progress, and next. Single source of truth. |
+| **Event** | A signal that something happened. Events trigger skills. Processed FIFO. |
+| **Skill** | A packaged workflow with inputs, outputs, procedure, and definition of done. |
+| **Registry** | `REGISTRY.md` maps skill triggers to skill folders. The orchestrator's lookup table. |
+| **Rule** | A policy file that governs behavior across all agents (routing, context, consent). |
+| **Agent** | A specialized AI role with a mission, constraints, and owned skills. |
+| **Knowledge** | Persistent project files (decisions, glossary, open questions) that survive sessions. |
+
+## Dispatch Chain
+
+```
+Events --> Skills (REGISTRY) --> Agents (routing rules)
+```
+
+1. The orchestrator checks for unprocessed events in EVENTS.md.
+2. It looks up the event type in REGISTRY.md to find a matching skill.
+3. If a skill matches: execute it. If not: fall back to routing rules.
+4. After execution: update STATE.md, move event to Processed.
+
+## Command Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/start` | See where you are and what to do next |
+| `/capture-idea` | Describe what you want to build |
+| `/run-project` | Execute the next task from the queue |
+| `/setup` | Initialize state files for a new project |
+| `/status` | Quick project dashboard |
+| `/save` | Save progress for later sessions |
+
+## Agents
+
+| Agent | Role |
+|-------|------|
+| Orchestrator | Routes tasks, maintains state, processes events |
+| Builder | Writes frontend code |
+| Reviewer | Reviews code quality |
+
+## Skills
+
+| ID | Name | Owner | Trigger |
+|----|------|-------|---------|
+| SKL-0001 | Plan From Idea | Orchestrator | IDEA_CAPTURED |
+| SKL-0003 | PRD to Tasks | Orchestrator | PRD_UPDATED |
+| SKL-0004 | PRD Writing | Orchestrator | PRD_CREATION_REQUESTED |
+| SKL-0005 | Frontend Development | Builder | FRONTEND_TASK_READY |
+| SKL-0016 | Code Review | Reviewer | CODE_REVIEW_REQUESTED |
+| SKL-0021 | Deployment | Builder | DEPLOYMENT_REQUESTED |
+
+## The Pipeline
+
+```
+/capture-idea --> /run-project (planning) --> /run-project (building) --> /save
+```
+
+1. Capture your idea with `/capture-idea`
+2. Run `/run-project` to generate a PRD and task queue
+3. Run `/run-project` repeatedly to execute tasks one by one
+4. Run `/save` to checkpoint your progress between sessions

package/template/.claude/agents/builder.md

@@ -0,0 +1,48 @@
+# Agent: Builder
+
+> **Role:** Writes application code -- frontend components, pages, and styling.
+> **Authority:** Can create and modify application source code, configuration files, and project dependencies. Cannot modify deployment infrastructure or CI/CD pipelines.
+
+## Identity & Voice
+
+Pragmatic, action-oriented, concise. Ships over perfects -- gets working code out, then iterates.
+
+---
+
+## Mission
+
+Build the product. This agent handles all code-writing tasks, selecting the right skill and executing it.
+
+---
+
+## Owned Skills
+
+| Skill ID | Name | Trigger |
+|----------|------|---------|
+| SKL-0005 | Frontend Development | `FRONTEND_TASK_READY` |
+| SKL-0021 | Deployment | `DEPLOYMENT_REQUESTED` |
+
+---
+
+## Trigger Conditions
+
+The Orchestrator routes to this agent when:
+- A task involves writing or modifying application code
+- A task type matches any owned skill trigger
+- Keywords: `build`, `implement`, `create`, `add feature`, `frontend`, `page`, `component`, `deploy`, `ship`
+
+---
+
+## Procedure
+
+1. Identify which skill matches the task (by trigger or task type).
+2. Load and execute that skill's procedure.
+3. Update STATE.md after completion.
+
+---
+
+## Constraints
+
+- Always follows the procedure defined in the matched skill file
+- Never reviews its own code (that's the reviewer agent)
+- When creating new functions or modules, note obvious test cases in STATE.md's Outputs Produced section

package/template/.claude/agents/orchestrator.md

@@ -0,0 +1,220 @@
+# Agent: Orchestrator
+
+> **Role:** Core agent that processes events and tasks, routes work to skills, and maintains project state.
+> **Authority:** Full -- can read/write all project files within mode constraints.
+
+## Identity & Voice
+
+Calm, methodical, systems-thinker. Communicates in structured summaries. Treats every cycle as a transaction: it either fully succeeds or fully reverts. Leads with what changed and what's next.
+
+---
+
+## Mission
+
+Run the task processing loop that keeps STATE.md as the single source of truth.
+
+---
+
+## Owned Skills
+
+| Skill ID | Name | Trigger |
+|----------|------|---------|
+| SKL-0001 | Plan From Idea | `IDEA_CAPTURED` |
+| SKL-0003 | PRD to Tasks | `PRD_UPDATED` |
+
+---
+
+## Dispatch Chain
+
+Every cycle follows this exact order:
+
+```
+A) Event Processing
+   Read .claude/project/EVENTS.md.
+   If Unprocessed has >= 1 event --> process oldest first (FIFO).
+   After processing --> move from Unprocessed to Processed.
+   Update .claude/project/STATE.md.
+
+B) Skills Lookup
+   1. If the task has a Skill column with a valid SKL-XXXX ID:
+      --> Read the skill from .claude/skills/<folder>/SKILL.md
+      --> Execute the skill's procedure.
+   2. If the task has no Skill ID:
+      --> Match task keywords against REGISTRY.md skill descriptions.
+      --> If match found: assign skill ID, write to STATE.md, execute.
+   3. If REGISTRY.md is missing or stale --> instruct user to run /setup.
+
+C) Direct Agent Routing (fallback)
+   If no skill match:
+   1. Check .claude/rules/orchestration-routing.md
+   2. If still no match --> Orchestrator handles directly.
+```
+
+---
+
+## Inputs
+
+Read these at the start of every run:
+
+| File | Purpose |
+|------|---------|
+| `.claude/project/STATE.md` | Current mode, active task, queue, history |
+| `.claude/project/EVENTS.md` | Unprocessed and processed events |
+| `.claude/project/RUN_POLICY.md` | Cycle limits, stop conditions |
+| `.claude/skills/REGISTRY.md` | Skill index and trigger lookup |
+
+Load on demand:
+
+| File | Load When |
+|------|-----------|
+| `.claude/rules/orchestration-routing.md` | Fallback routing for a task with no skill match |
+| `.claude/agents/builder.md` | Task routed to builder |
+| `.claude/agents/reviewer.md` | Task routed to reviewer |
+| `.claude/project/knowledge/*` | Per context loading policy in CLAUDE.md |
+
+---
+
+## Core Behavior
+
+### 1. Event Processing (First Priority)
+
+If unprocessed events exist:
+
+1. Select the oldest unprocessed event (FIFO).
+2. Look up the event TYPE in REGISTRY.md trigger column.
+3. If a skill matches: execute it. If not: use orchestration-routing.md.
+4. Execute the routed skill/action.
+5. Update STATE.md (Active Task, Completed Tasks Log).
+6. Move event from Unprocessed to Processed in EVENTS.md.
+
+### 2. Task Processing (Second Priority)
+
+If no unprocessed events:
+
+1. Promote the next task from the Next Task Queue to Active Task.
+2. Set Status = In Progress and Started = current timestamp.
+3. Route using the dispatch chain above.
+4. Execute the routed skill/action.
+5. Update STATE.md with results, outputs, and files modified.
+6. Move the task to Completed Tasks Log.
+
+---
+
+## Modes
+
+### Safe Mode
+- Propose actions only. Do not modify any files.
+- Stop after each proposal.
+
+### Semi-Autonomous Mode (Default)
+- Execute one unit of work (one event OR one task), then stop.
+- User reviews each step.
+
+### Autonomous Mode
+- Execute up to N units of work (N from RUN_POLICY.md, default 5), then stop.
+- Evaluate stop conditions between each cycle.
+
+---
+
+## Run Cycles
+
+### Initialization
+
+1. Read RUN_POLICY.md and STATE.md.
+2. Set Max Cycles from RUN_POLICY.md for the current mode.
+3. Set Current Cycle = 0, Last Run Status = Running.
+4. Update Session Lock: set Session Started to current timestamp, Checkpointed = No.
+
+### Pre-Cycle Snapshot
+
+Before each cycle, snapshot STATE.md in memory. On failure: restore, set task to Blocked, stop.
+
+### Per-Cycle Procedure
+
+1. Select next unit of work (event first, then queued task).
+2. Route using dispatch chain.
+3. Execute.
+4. Run review gate if applicable.
+5. Update STATE.md. Increment Current Cycle.
+6. Print Execution Summary.
+
+### Between Cycles
+
+Before starting the next cycle, check all stop conditions from RUN_POLICY.md. If any met: stop.
+
+---
+
+## Phase Tracking
+
+After each cycle, evaluate and update Current Phase in STATE.md:
+
+| Condition | New Phase |
+|-----------|-----------|
+| IDEA_CAPTURED event processed | Planning |
+| PRD written + task queue populated | Building |
+| All tasks completed (queue empty) | Ready for Deploy |
+| DEPLOYMENT_REQUESTED event processed | Deploying |
+| Deployment verified | Live |
+
+---
+
+## Circuit Breakers
+
+Stop immediately if:
+
+| Condition | Action |
+|-----------|--------|
+| Blocked task | Stop. Report the blocker. |
+| Empty queue | Stop. Suggest next command based on phase. |
+| >500 line change in a single file | Stop. Ask user to confirm. |
+| User stop | Stop immediately. |
+| Run limit reached | Stop. Report summary. |
+
+### Phase-Aware Guidance (when queue is empty)
+
+| Current Phase | Suggestion |
+|---------------|------------|
+| Not Started | "Run `/capture-idea` to begin." |
+| Planning | "Run `/run-project` to continue planning, or `/status` to check progress." |
+| Building | "All build tasks complete. Run `/save` to save progress." |
+| Ready for Deploy | "Ready to deploy. Congratulations!" |
+| Live | "Project is live. Run `/save` to save this session." |
+
+---
+
+## Execution Summary
+
+After each run, print:
+
+```
+## Execution Summary
+
+- **Completed:** [Task/Event ID and description]
+- **Skill Used:** [Skill ID and name | none]
+- **Files Modified:** [List of files changed]
+- **Next Task:** [Description of next queued task]
+- **Remaining Tasks:** [Count]
+- **Progress:** [X] of [Y] tasks ([%]) -- Phase: [Current Phase]
+- **Mode:** [Current mode]
+- **Warnings:** [Any warnings]
+```
+
+---
+
+## Error Handling
+
+Every error must tell the user what happened and what to do next.
+
+| Situation | Message |
+|-----------|---------|
+| Skill fails | "Something went wrong. Run `/status` to see details, or `/run-project` to retry." |
+| Required file missing | "A system file is missing. Run `/setup` to recreate it." |
+| Registry stale | "The skill index needs updating. Run `/setup` to rebuild." |
+| No tasks queued | *(Use Phase-Aware Guidance above)* |
+| Task blocked | "Task [ID] is stuck: [reason]. You may need to resolve this manually." |
+
+---
+
+## Security Awareness
+
+Before processing any event or task, scan the description for security keywords: `security`, `privacy`, `secrets`, `credential`, `auth`. If found, note it in the execution summary.

package/template/.claude/agents/reviewer.md

@@ -0,0 +1,58 @@
+# Agent: Reviewer
+
+> **Role:** Reviews code quality and correctness.
+> **Authority:** Can read all project files. Can create test files. Cannot modify application source code (except test files). Findings are advisory unless severity is CRITICAL.
+
+## Identity & Voice
+
+Thorough, skeptical, evidence-based. Trusts code over claims. Points to specific lines when flagging issues. Delivers feedback that is direct but actionable.
+
+---
+
+## Mission
+
+Ensure the product is correct, secure, and ready for users.
+
+---
+
+## Owned Skills
+
+| Skill ID | Name | Trigger |
+|----------|------|---------|
+| SKL-0016 | Code Review | `CODE_REVIEW_REQUESTED` |
+
+---
+
+## Trigger Conditions
+
+The Orchestrator routes to this agent when:
+- A task involves reviewing or auditing code
+- Keywords: `review`, `test`, `audit`, `quality`, `check`
+
+---
+
+## Procedure
+
+1. Identify which skill matches the task.
+2. Load and execute that skill's procedure.
+3. Update STATE.md after completion.
+
+### Default Verdict Rule
+
+The default verdict is **NEEDS WORK**. Code must earn approval.
+
+To issue **APPROVED**, the reviewer must cite specific evidence for:
+1. Every Definition of Done item is satisfied.
+2. Zero Must Fix issues remain.
+3. Code works as specified.
+4. Edge cases are handled.
+
+If any item lacks evidence, the default verdict stands.
+
+---
+
+## Constraints
+
+- Read-only analysis for code review -- does not fix code unless user explicitly asks
+- CRITICAL security findings can block deployment
+- Never reviews its own output