create-bashi-starter 1.0.0

package/template/.claude/commands/capture-idea.md

@@ -0,0 +1,73 @@
+# /capture-idea — Describe What You Want to Build
+
+> Captures the user's project idea and kicks off the planning phase.
+
+---
+
+## Procedure
+
+### Step 1: Ask for the Idea
+
+Ask the user:
+
+> "Describe your project idea in plain language. What do you want to build, and who is it for?"
+
+**Wait for the user's response before proceeding.** Do not infer or assume an idea.
+
+### Step 2: Create docs/ Directory
+
+If the `docs/` directory does not exist, create it.
+
+### Step 3: Write Idea Summary
+
+Write a brief idea summary to `docs/IDEA.md` using this format:
+
+```markdown
+# Project Idea
+
+**Captured:** [current date]
+
+## Description
+
+[User's idea in their own words, lightly formatted for readability]
+
+## Target User
+
+[Who is this for, extracted from the description]
+
+## Core Problem
+
+[What problem does this solve, extracted from the description]
+```
+
+Keep it concise. Preserve the user's phrasing.
+
+### Step 4: Emit IDEA_CAPTURED Event
+
+Append an event to `.claude/project/EVENTS.md`:
+
+```markdown
+| EVT-0001 | IDEA_CAPTURED | Idea captured: [brief title] | Unprocessed |
+```
+
+Use the next available EVT number if events already exist.
+
+### Step 5: Update STATE.md
+
+- Set `Current Phase` to `Planning`
+- Set `Last Activity` to current timestamp
+
+### Step 6: Confirm and Guide
+
+Print:
+
+> "Idea captured to `docs/IDEA.md`. Phase set to Planning."
+> "Run `/run-project` to start planning your project."
+
+---
+
+## Rules
+
+- Do not skip the user prompt in Step 1. The user must describe the idea themselves.
+- Keep the idea summary faithful to the user's words. Do not embellish or over-structure.
+- One idea per capture. If the user describes multiple ideas, ask which one to start with.

package/template/.claude/commands/run-project.md

@@ -0,0 +1,109 @@
+# /run-project — Execute Orchestration Cycles
+
+> The main execution loop. Processes events, executes tasks, and advances the project.
+
+---
+
+## Procedure
+
+### Step 1: Load Context
+
+Read the following files:
+- `.claude/project/STATE.md` — mode, active task, next task queue
+- `.claude/project/RUN_POLICY.md` — cycle limits, stop conditions
+- `.claude/project/EVENTS.md` — unprocessed events
+
+Initialize run state:
+- `Current Cycle` = 0
+- `Max Cycles` = limit from RUN_POLICY for current mode
+- `Last Run Status` = Running
+
+Update STATE.md Session Lock:
+- `Timestamp` = current time
+- `Checkpointed` = No
+
+### Step 2: Determine What to Process
+
+Evaluate in this priority order:
+
+1. **Active Task with Status = In Progress** — Resume it.
+2. **Unprocessed events in EVENTS.md** — Select the oldest (FIFO).
+3. **Tasks in the Next Task Queue** — Promote the next task to Active.
+4. **Nothing to do** — Print phase-aware guidance and stop:
+   - If Phase is `Not Started`: "Run `/capture-idea` to get started."
+   - If Phase is `Planning`: "No events to process. Waiting for planning input."
+   - If Phase is `Building`: "Queue is empty. Capture more tasks or run `/save`."
+   - If Phase is `Done`: "Project complete. Run `/save` to checkpoint."
+
+### Step 3: Route and Execute
+
+Follow the orchestrator dispatch chain:
+
+1. Look up the task or event trigger in `.claude/skills/REGISTRY.md`
+2. **If a skill matches** — Read and execute that skill's procedure
+3. **If no skill matches** — Fall back to `.claude/rules/orchestration-routing.md` to identify the agent, then execute using that agent's procedure
+4. Execute the work, writing all output to files (not chat)
+
+### Step 4: Update State
+
+After execution completes:
+- Update the task status in STATE.md (In Progress, Done, Blocked)
+- Mark processed events as `Processed` in EVENTS.md
+- Record files modified in the Active Task section
+- Set `Last Activity` to current timestamp
+
+### Step 5: Cycle Control
+
+Execute cycles based on the current mode:
+
+| Mode | Behavior |
+|------|----------|
+| Safe | 0 cycles executed. Propose the plan, then stop and wait for approval. |
+| Semi-Autonomous | Execute 1 cycle, then stop and report. |
+| Autonomous | Execute up to Max Cycles, stopping on any stop condition. |
+
+Increment `Current Cycle` after each execution. If `Current Cycle >= Max Cycles`, stop.
+
+### Step 6: Check Stop Conditions
+
+After each cycle, check stop conditions from RUN_POLICY.md:
+- Max cycles reached
+- A task is Blocked
+- A quality gate failed
+- User intervention required
+
+If any condition is met, stop the loop and report.
+
+### Step 7: Print Run Summary
+
+Print a compact summary (under 200 words):
+
+```
+== Run Complete ==
+
+Mode:           [current mode]
+Cycles:         [executed] of [max]
+Completed:      [list of completed task IDs]
+Files Modified: [list of file paths]
+Next Task:      [task ID and title, or "None"]
+Remaining:      [N tasks]
+Progress:       [X of Y (Z%)]
+Status:         [Running | Stopped | Blocked | Complete]
+```
+
+---
+
+## Output Policy
+
+- Write all artifacts (documents, code, plans) to files. Never dump large content into chat.
+- Chat output must stay under 200 words per cycle.
+- Reference file paths instead of reproducing content.
+
+---
+
+## Rules
+
+- Always load RUN_POLICY.md before executing. Respect its limits.
+- Never exceed Max Cycles for the current mode.
+- Process events before promoting queued tasks.
+- If a skill procedure defines a Definition of Done, verify it before marking the task Done.

package/template/.claude/commands/save.md

@@ -0,0 +1,78 @@
+# /save — Save Progress for Later Sessions
+
+> Persists all in-flight work to files so the next session can resume cleanly.
+
+---
+
+## Procedure
+
+### Step 1: Load Current State
+
+Read `.claude/project/STATE.md` to understand what is in progress.
+
+### Step 2: Capture Unsaved Decisions
+
+Review the current conversation for any architectural, design, or process decisions that were discussed but not yet persisted. If any are found, append them to `.claude/project/knowledge/DECISIONS.md` using the standard entry format:
+
+```markdown
+### DEC-XXXX — [Title]
+
+- **Date:** [current date]
+- **Status:** Accepted
+- **Context:** [why this decision was needed]
+- **Decision:** [what was decided]
+- **Consequences:** [what this means going forward]
+```
+
+If no unsaved decisions exist, skip this step.
+
+### Step 3: Verify Artifacts
+
+Check that all substantial outputs from this session are written to files, not only present in chat. If any artifact is only in chat, write it to the appropriate location:
+
+| Artifact Type | Location |
+|---------------|----------|
+| Documents, plans | `docs/` |
+| Code | project source directories |
+| Decisions | `.claude/project/knowledge/DECISIONS.md` |
+| Research | `.claude/project/knowledge/RESEARCH.md` |
+
+### Step 4: Update STATE.md
+
+Set:
+- `Last Run Status` = Checkpointed
+- `Session Lock > Checkpointed` = Yes
+- `Last Activity` = current timestamp
+
+If there is an active task in progress, leave its status as-is (it will resume next session).
+
+### Step 5: Log Checkpoint Event
+
+Append to `.claude/project/EVENTS.md`:
+
+```markdown
+| EVT-XXXX | CHECKPOINT | Session saved. [brief summary of progress] | Processed |
+```
+
+Use the next available EVT number.
+
+### Step 6: Print Save Summary
+
+Print a compact summary:
+
+```
+== Session Saved ==
+
+Files Updated:  [list of files modified this session]
+Work Done:      [1-2 sentence summary]
+Next Task:      [task ID — title, or "None"]
+Resume With:    /run-project
+```
+
+---
+
+## Rules
+
+- Always update STATE.md before ending. This is the single source of truth for session continuity.
+- Do not mark in-progress tasks as Done. They will resume next session.
+- Keep the save summary under 10 lines.

package/template/.claude/commands/setup.md

@@ -0,0 +1,73 @@
+# /setup — Initialize Project State Files
+
+> First-time setup for a new project. Creates state files and captures project identity.
+
+---
+
+## Procedure
+
+### Step 1: Check Existing State
+
+Check if these files exist:
+- `.claude/project/STATE.md`
+- `.claude/project/EVENTS.md`
+- `.claude/project/RUN_POLICY.md`
+
+**If all three exist**, print:
+
+> "Already initialized. Run `/start` to see your project status."
+
+Then stop. Do not proceed.
+
+### Step 2: Create Missing Files
+
+If any of the three files are missing, create them from the templates that ship with the Bashi Starter framework. For a fresh install from the template, all files should already exist, so this step handles partial or corrupted states.
+
+For each missing file, use the standard template:
+
+**STATE.md** — Initialize with:
+- Current Phase: Not Started
+- Mode: Semi-Autonomous
+- Active Task: None
+- Next Task Queue: empty
+- Session Lock: cleared
+
+**EVENTS.md** — Initialize with:
+- Header row and empty event table
+
+**RUN_POLICY.md** — Initialize with:
+- Default cycle limits per mode (Safe: 0, Semi-Auto: 1, Autonomous: 5)
+- Default stop conditions
+
+### Step 3: Capture Project Identity
+
+Ask the user three questions (wait for answers before proceeding):
+
+1. "What is the name of your project?"
+2. "What does it do? (one sentence)"
+3. "What tech stack will you use? (or say 'not sure yet')"
+
+Write the answers to `.claude/project/IDENTITY.md`:
+
+```markdown
+# Project Identity
+
+**Name:** [answer]
+**Purpose:** [answer]
+**Tech Stack:** [answer]
+**Created:** [current date]
+```
+
+### Step 4: Confirm
+
+Print:
+
+> "Setup complete. Run `/capture-idea` to describe what you want to build."
+
+---
+
+## Rules
+
+- Do not overwrite existing files. Only create files that are missing.
+- Do not skip the user prompts in Step 3. Wait for answers.
+- If the user says "not sure yet" for tech stack, write that literally. Do not suggest one.

package/template/.claude/commands/start.md

@@ -0,0 +1,55 @@
+# /start — Welcome Entry Point
+
+> **Read-only.** Shows where the user is and what to do next.
+
+---
+
+## Procedure
+
+### Step 1: Load Current State
+
+Read `.claude/project/STATE.md` to determine:
+- Current Phase
+- Mode
+- Active Task (if any)
+- Next Task Queue status (count and items)
+- Pending events in `.claude/project/EVENTS.md`
+
+If `STATE.md` does not exist, classify as **Not Initialized**.
+
+### Step 2: Classify Situation
+
+Evaluate the project state and select **one** recommendation:
+
+| Situation | Recommendation |
+|-----------|---------------|
+| `STATE.md` does not exist | "Run `/setup` to initialize your project." |
+| Phase is `Not Started`, queue is empty, no events | "Run `/capture-idea` to describe what you want to build." |
+| Unprocessed events exist in `EVENTS.md` | "Run `/run-project` to process pending events." |
+| Tasks exist in the Next Task Queue | "Run `/run-project` to execute the next task." |
+| All tasks are Done, no pending events | "All tasks complete. Run `/save` to checkpoint your progress." |
+
+### Step 3: Print Dashboard
+
+Display a compact dashboard (under 15 lines):
+
+```
+== Bashi Starter Dashboard ==
+
+Phase:       [current phase]
+Mode:        [current mode]
+Progress:    [X of Y tasks complete (Z%)]
+Active Task: [task ID and title, or "None"]
+Queue:       [N tasks remaining]
+Events:      [N pending]
+
+>> Next step: [recommendation from Step 2]
+```
+
+---
+
+## Rules
+
+- This command is **read-only**. Do not modify any files.
+- If multiple situations apply, use the highest-priority match (top of table wins).
+- Keep output concise and actionable.

package/template/.claude/commands/status.md

@@ -0,0 +1,40 @@
+# /status — Quick Project Dashboard
+
+> **Read-only.** Compact snapshot of project state.
+
+---
+
+## Procedure
+
+### Step 1: Load State
+
+Read `.claude/project/STATE.md` and `.claude/project/EVENTS.md`.
+
+If `STATE.md` does not exist, print:
+
+> "No project initialized. Run `/setup` first."
+
+Then stop.
+
+### Step 2: Print Dashboard
+
+Display a compact dashboard in **10 lines or fewer**:
+
+```
+Phase:       [current phase]
+Mode:        [current mode]
+Progress:    [X of Y tasks (Z%)]
+Active:      [task ID — title, or "None"]
+Queue:       [N remaining]
+Events:      [N pending]
+Last Run:    [last run status]
+Blockers:    [blocker description, or "None"]
+```
+
+---
+
+## Rules
+
+- This command is **read-only**. Do not modify any files.
+- If there are no tasks yet, show `Progress: 0 of 0 tasks (0%)`.
+- Keep it compact. No explanations, no suggestions. Just the data.

package/template/.claude/hooks/lib/detect-python.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+# Shared Python detection -- sourced by all hooks that need Python.
+# Sets PYTHON to the first available Python interpreter.
+
+if python3 -c "import sys" 2>/dev/null; then
+  PYTHON=python3
+elif python -c "import sys; assert sys.version_info >= (3, 6)" 2>/dev/null; then
+  PYTHON=python
+else
+  PYTHON=false
+  echo "WARNING: No Python interpreter found. Some hook checks will be skipped." >&2
+fi

package/template/.claude/hooks/pre-bash-firewall.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+# Pre-Bash Firewall -- blocks dangerous commands before execution
+# Exit code 2 = block, Exit code 0 = allow
+
+set -euo pipefail
+
+INPUT=$(cat)
+# shellcheck source=lib/detect-python.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/detect-python.sh"
+COMMAND=$(echo "$INPUT" | $PYTHON -c "
+import sys, json
+data = json.load(sys.stdin)
+print(data.get('command', ''))
+" 2>/dev/null || echo "")
+
+BLOCKED_PATTERNS=(
+  "rm -rf /[[:space:]]*$"
+  "rm -rf \*"
+  "git reset --hard"
+  "git push --force"
+  "git push -f"
+  "DROP TABLE"
+  "DROP DATABASE"
+  "truncate "
+  "chmod 777"
+  "> /etc/"
+  "sudo rm"
+  "rm -rf \."
+  "> /dev/sda"
+  "mkfs"
+  "dd if="
+)
+
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qiE "$pattern"; then
+    echo "BLOCKED by pre-bash-firewall: '$pattern' detected in command" >&2
+    echo "If this is intentional, ask the user to run the command manually." >&2
+    exit 2
+  fi
+done
+
+# Block pipe-to-shell patterns
+if echo "$COMMAND" | grep -qE "\|\s*(ba)?sh"; then
+  echo "BLOCKED by pre-bash-firewall: pipe-to-shell pattern detected" >&2
+  exit 2
+fi
+
+exit 0

package/template/.claude/hooks/pre-write-secrets-scan.sh

@@ -0,0 +1,56 @@
+#!/usr/bin/env bash
+# Pre-Write Secrets Scan -- blocks writes containing API keys, tokens, or credentials
+# Exit code 2 = block, Exit code 0 = allow
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+# shellcheck source=lib/detect-python.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/detect-python.sh"
+FOUND=$(echo "$INPUT" | $PYTHON -c "
+import sys, json, re
+
+data = json.load(sys.stdin)
+file_path = data.get('file_path', data.get('path', ''))
+text = data.get('content', '') or data.get('new_string', '')
+
+# Skip hook files to avoid self-blocking on pattern strings
+if '.claude/hooks/' in file_path or '.claude\\\\hooks\\\\' in file_path:
+    sys.exit(0)
+
+if not text:
+    sys.exit(0)
+
+patterns = [
+    (r'sk-[a-zA-Z0-9]{20,}', 'OpenAI API key'),
+    (r'sk_(live|test)_[a-zA-Z0-9]{20,}', 'Stripe secret key'),
+    (r'ghp_[a-zA-Z0-9]{36,}', 'GitHub personal access token'),
+    (r'gho_[a-zA-Z0-9]{36,}', 'GitHub OAuth token'),
+    (r'ghs_[a-zA-Z0-9]{36,}', 'GitHub server token'),
+    (r'github_pat_[a-zA-Z0-9_]{20,}', 'GitHub fine-grained PAT'),
+    (r'xox[bp]-[0-9]{10,}-[a-zA-Z0-9]{20,}', 'Slack token'),
+    (r'AKIA[0-9A-Z]{16}', 'AWS access key ID'),
+    (r'-----BEGIN (?:RSA |EC |DSA |OPENSSH )?PRIVATE KEY-----', 'Private key'),
+    (r'Bearer [a-zA-Z0-9_\-\.]{20,}', 'Bearer token'),
+    (r'password\s*=\s*[\"\\'][^\"\\']{8,}[\"\\']', 'Hardcoded password'),
+    (r'sk-ant-api[a-zA-Z0-9_-]{20,}', 'Anthropic API key'),
+    (r'(postgres|mysql|mongodb|redis)://[^:]+:[^@]+@', 'Database connection string with credentials'),
+    (r'[Aa][Pp][Ii]_?[Kk][Ee][Yy]\s*=\s*[\"\\'][^\"\\']{8,}[\"\\']', 'Generic API key assignment'),
+]
+
+for pat, name in patterns:
+    if re.search(pat, text):
+        print(f'{name}|{file_path}')
+        sys.exit(0)
+" 2>/dev/null || echo "")
+
+if [ -n "$FOUND" ]; then
+  SECRET_TYPE="${FOUND%%|*}"
+  FILE_PATH="${FOUND#*|}"
+  echo "BLOCKED by pre-write-secrets-scan: Possible $SECRET_TYPE detected in content for $FILE_PATH" >&2
+  echo "If this is a false positive, remove the secret-like pattern or write the file manually." >&2
+  exit 2
+fi
+
+exit 0

package/template/.claude/hooks/session-start.sh

@@ -0,0 +1,54 @@
+#!/usr/bin/env bash
+# Session Start -- loads project context dashboard
+# Exit code 0 -- informational only
+
+set -euo pipefail
+
+FRAMEWORK_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CLAUDE_DIR="$FRAMEWORK_ROOT/.claude"
+STATE_FILE="$CLAUDE_DIR/project/STATE.md"
+EVENTS_FILE="$CLAUDE_DIR/project/EVENTS.md"
+
+# shellcheck source=lib/detect-python.sh
+source "$(dirname "${BASH_SOURCE[0]}")/lib/detect-python.sh"
+
+echo "--- Bashi Starter Session Context ---"
+echo "Project: $(basename "$FRAMEWORK_ROOT")"
+echo ""
+
+# Extract state info
+if [ -f "$STATE_FILE" ]; then
+  if [ "$PYTHON" != "false" ]; then
+    PHASE=$($PYTHON -c "
+import re
+with open('$STATE_FILE','r',encoding='utf-8') as f: c=f.read()
+m=re.search(r'## Current Phase\s*\n+(\S.*)', c)
+print(m.group(1).strip() if m else 'Not Started')
+" 2>/dev/null || echo "Not Started")
+
+    MODE=$($PYTHON -c "
+with open('$STATE_FILE','r',encoding='utf-8') as f: c=f.read()
+import re
+m=re.search(r'## Current Mode\s*\n+(\S.*)', c)
+print(m.group(1).strip() if m else 'Unknown')
+" 2>/dev/null || echo "Unknown")
+  else
+    PHASE="Not Started"
+    MODE="Unknown"
+  fi
+
+  echo "Phase: $PHASE | Mode: $MODE"
+else
+  echo "STATE.md not found -- run /setup to initialize."
+fi
+
+# Count pending events
+if [ -f "$EVENTS_FILE" ]; then
+  PENDING=$(awk '/^## Unprocessed Events/,/^---/' "$EVENTS_FILE" 2>/dev/null | grep -c '^EVT-' || echo "0")
+  echo "Pending events: $PENDING"
+else
+  echo "EVENTS.md not found."
+fi
+
+echo "--- End Session Context ---"
+exit 0

package/template/.claude/project/EVENTS.md

@@ -0,0 +1,29 @@
+# Events Log
+
+> Events represent things that happened or need to happen. They are processed FIFO (oldest first).
+
+---
+
+## Event Format
+
+```
+EVT-XXXX | <TYPE> | <Description> | <Source> | <Timestamp>
+```
+
+- **EVT-XXXX** -- Auto-incremented event ID
+- **TYPE** -- Event type matching a skill trigger (e.g., IDEA_CAPTURED)
+- **Description** -- Brief summary of what happened or what needs to happen
+- **Source** -- Who created the event (user, agent, system)
+- **Timestamp** -- When the event was created
+
+---
+
+## Unprocessed Events
+
+*(none)*
+
+---
+
+## Processed Events
+
+*(none)*

package/template/.claude/project/IDENTITY.md

@@ -0,0 +1,12 @@
+# Project Identity
+
+> Persists project-specific identity. Managed by `/setup`.
+
+---
+
+## Fields
+
+- **Project:** (set by /setup)
+- **Status:** Not Started
+- **Stack:** (set by /setup)
+- **Purpose:** (set by /setup)