create-bashi-starter 1.0.0

package/template/.claude/skills/prd-to-tasks/SKILL.md

@@ -0,0 +1,207 @@
+---
+id: SKL-0003
+name: PRD to Tasks
+description: |
+  Break down a Product Requirements Document into executable tasks with
+  priorities and dependencies. Use this skill when a PRD has been created or
+  updated and needs to be converted into a task queue.
+version: 1.0
+owner: Orchestrator
+triggers:
+  - PRD_UPDATED
+inputs:
+  - docs/PRD.md
+  - .claude/project/STATE.md
+  - .claude/project/knowledge/OPEN_QUESTIONS.md (optional)
+outputs:
+  - .claude/project/STATE.md (Next Task Queue updated)
+  - .claude/project/knowledge/OPEN_QUESTIONS.md (optional new entries)
+tags:
+  - planning
+  - tasks
+  - prd
+---
+
+# Skill: PRD to Tasks
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | SKL-0003 |
+| **Version** | 1.0 |
+| **Owner** | Orchestrator |
+| **Inputs** | `docs/PRD.md`, `.claude/project/STATE.md`, `.claude/project/knowledge/OPEN_QUESTIONS.md` (optional) |
+| **Outputs** | Updated `.claude/project/STATE.md` Next Task Queue (8-15 tasks), optional new entries in `.claude/project/knowledge/OPEN_QUESTIONS.md` |
+| **Triggers** | `PRD_UPDATED` |
+
+---
+
+## Purpose
+
+Convert a completed or updated PRD into a concrete, ordered, beginner-friendly task queue so the system becomes self-planning. This eliminates the need for manual task creation after writing a PRD.
+
+---
+
+## Procedure
+
+### A) Extract PRD Content
+
+Read `docs/PRD.md` and extract:
+
+1. **Core goal** --- from the Overview or Goals section.
+2. **Target user** --- from the Target Users section.
+3. **MVP scope** --- individual features from the MVP Scope section.
+4. **Non-goals** --- from the NOT in Scope section (to avoid generating tasks for these).
+5. **Risks and assumptions** --- from the Risks and Assumptions section.
+
+If any section is missing, proceed with what is available and note the gap.
+
+### B) Generate Task List
+
+Produce an ordered list of **8 to 15 tasks** following these rules:
+
+1. **Beginner-friendly titles** --- Use short, plain language. Write "Build login screen", not "Implement authentication UI component with OAuth flow".
+2. **Name the target file or folder** --- Each task must reference the expected output location when known (e.g., `src/`, `docs/`, `lib/`, `manuscript/`, `tests/`).
+3. **Priority tagging** --- Assign each task one of: `High`, `Medium`, or `Low`.
+4. **Logical order** --- Tasks should follow a natural build sequence:
+   - Planning and design tasks first (High priority)
+   - Core feature build tasks next (High/Medium priority)
+   - Polish, testing, and review tasks last (Medium/Low priority)
+5. **No tasks for non-goals** --- Cross-check against the NOT in Scope section. Do not generate tasks for anything explicitly excluded.
+
+6. **Skill assignment** --- Assign each task a Skill ID from `.claude/skills/REGISTRY.md`. This is the **primary mechanism** by which skills are invoked during the build phase. Use the task format defined in `.claude/project/knowledge/TASK-FORMAT.md` (includes column definitions, skill assignment rules, and common mappings).
+
+### B2) Phase Grouping (Conditional)
+
+**Trigger:** Check if `docs/ARCHITECTURE.md` exists and contains real content (not just the placeholder template).
+
+**If ARCHITECTURE.md exists:** Group the generated tasks into phases. Each phase gets its own header in the task queue. Tasks are numbered sequentially across all phases.
+
+| Phase | Contains | Typical Priority |
+|-------|----------|-----------------|
+| **Phase 1: Foundation** | Project setup, config, tooling, environment | High |
+| **Phase 2: Core** | Data model, auth, core APIs, database schema | High |
+| **Phase 3: Features** | User-facing functionality, UI, business logic | High/Medium |
+| **Phase 4: Integration** | Third-party APIs, webhooks, external services | Medium |
+| **Phase 5: Quality** | Testing, code review, polish, accessibility | Medium |
+| **Phase 6: Ship** | Deployment, documentation, launch prep | Medium/Low |
+
+**Output format with phases:**
+
+```
+### Phase 1: Foundation
+| # | Task | Priority | Skill |
+|---|------|----------|-------|
+| 1 | ... | High | SKL-0008 |
+| 2 | ... | High | --- |
+
+### Phase 2: Core
+| # | Task | Priority | Skill |
+|---|------|----------|-------|
+| 3 | ... | High | SKL-0006 |
+...
+```
+
+**If ARCHITECTURE.md does not exist:** Skip phase grouping. Output a flat task list as in Step B. This scales naturally: simple projects get flat lists, complex projects with architecture docs get phased breakdown.
+
+**Rules:**
+- Tasks are still numbered sequentially across all phases (1, 2, 3... not restarting per phase)
+- Empty phases are omitted (don't create a phase with no tasks)
+- The Orchestrator processes tasks in order regardless of phase headers
+- Phase headers are organizational only --- they help humans understand the sequence
+
+### C) Write to STATE.md (Idempotency Rules)
+
+Read `.claude/project/STATE.md` and locate the `## Next Task Queue` section.
+
+**Determine queue state using these patterns:**
+
+A queue is **empty/placeholder-only** if it matches ANY of:
+- Contains only `(none)` or `*(none)*`
+- Contains only `- (none)`
+- Contains only table headers with no data rows
+- The section is completely empty
+
+**If the queue is empty or placeholder-only:**
+- Replace the placeholder content with the generated task table.
+
+**If the queue already contains real tasks:**
+- Do NOT replace the existing queue.
+- Instead, append a new section below the Completed Tasks Log:
+
+```
+---
+
+## Proposed Task Queue (from PRD_UPDATED --- YYYY-MM-DD)
+
+| # | Task | Priority | Skill |
+|---|------|----------|-------|
+| 1 | ... | ... | SKL-XXXX |
+| ... | ... | ... | ... |
+
+> These tasks were auto-generated from docs/PRD.md. Review and merge into the Next Task Queue manually or by running /run-project.
+```
+
+### D) Handle Open Questions
+
+While reading the PRD, if any requirements are ambiguous or underspecified:
+
+1. Read `.claude/project/knowledge/OPEN_QUESTIONS.md`.
+2. Check if the question already exists (avoid duplicates).
+3. If the question is novel, append it using the next available `OQ-XXXX` ID:
+
+```
+---
+
+### OQ-XXXX: <Question title>
+
+- **Date:** YYYY-MM-DD
+- **Source:** PRD analysis via skill-prd-to-tasks
+- **Context:** <What prompted this question>
+- **Status:** Open
+- **Impact:** <What decision is blocked by this question>
+```
+
+### E) Event Suggestion
+
+After completing task generation, recommend emitting:
+
+```
+TASK_QUEUE_PROPOSED | .claude/project/STATE.md updated with tasks from PRD
+```
+
+Print: `"Suggest emitting: TASK_QUEUE_PROPOSED --- use /trigger to create it."`
+
+(Skills do not emit events directly; the orchestrator or user handles emission.)
+
+---
+
+## Primary Agent
+
+Orchestrator (handles PRD analysis and task decomposition internally).
+
+## Review
+
+Orchestrator self-reviews task titles for beginner clarity. For deeper quality review, emit `QUALITY_REVIEW_REQUESTED` via `/trigger`.
+
+---
+
+## Definition of Done
+
+- [ ] 8-15 tasks generated from PRD content
+- [ ] Tasks written to .claude/project/STATE.md (seeded or proposed, per idempotency rules)
+- [ ] Each task has a plain-language title, target location, priority, and Skill ID
+- [ ] Skill IDs assigned by cross-referencing REGISTRY.md (or `---` if no skill applies)
+- [ ] No tasks generated for items listed in NOT in Scope
+- [ ] Any ambiguous requirements logged to .claude/project/knowledge/OPEN_QUESTIONS.md
+- [ ] Event suggestion printed for TASK_QUEUE_PROPOSED
+- [ ] .claude/project/STATE.md updated with outputs produced and files modified
+
+## Output Contract
+
+| Field | Value |
+|-------|-------|
+| **Artifacts** | `.claude/project/STATE.md` (Next Task Queue updated with 8-15 tasks), `.claude/project/knowledge/OPEN_QUESTIONS.md` (optional new entries) |
+| **State Update** | `.claude/project/STATE.md` --- mark task complete, log files modified |
+| **Handoff Event** | `TASK_QUEUE_PROPOSED` (task queue ready for execution) |

package/template/.claude/skills/prd-writing/SKILL.md

@@ -0,0 +1,226 @@
+---
+id: SKL-0004
+name: PRD Writing
+description: |
+  Write a Product Requirements Document through user interview, including user
+  stories, requirements, and acceptance criteria. Includes a Vision Challenge
+  mode (CEO review) to ensure the right problem is being solved at the right
+  scope before writing begins. Use this skill when a new PRD needs to be
+  created for a project.
+version: 2.0
+owner: orchestrator
+triggers:
+  - PRD_CREATION_REQUESTED
+inputs:
+  - User's product idea or description
+  - docs/PRD.md (if exists)
+  - .claude/project/knowledge/DECISIONS.md
+  - TODOS.md (if exists)
+outputs:
+  - docs/PRD.md (created or updated)
+  - .claude/project/STATE.md (updated)
+  - .claude/project/knowledge/DECISIONS.md (updated with scope decisions)
+tags:
+  - planning
+  - prd
+  - vision
+---
+
+# Skill: PRD Writing
+
+## Metadata
+
+| Field | Value |
+|-------|-------|
+| **Skill ID** | SKL-0004 |
+| **Version** | 2.0 |
+| **Owner** | orchestrator |
+| **Inputs** | User's product idea, existing PRD (if any), DECISIONS.md, TODOS.md |
+| **Outputs** | `docs/PRD.md`, STATE.md updated, DECISIONS.md updated |
+| **Triggers** | `PRD_CREATION_REQUESTED` |
+
+---
+
+## Purpose
+
+Interview the user conversationally and produce a structured PRD at `docs/PRD.md` that downstream skills can parse. Before writing, run a Vision Challenge to ensure the right problem is being solved at the right ambition level.
+
+---
+
+## Cognitive Mode
+
+**Founder Thinking.** You are not a note-taker. You are a co-founder helping shape the product vision. Challenge assumptions, expand thinking where warranted, and ensure the product is worth building before defining how to build it.
+
+---
+
+## Procedure
+
+### Step 0 --- Vision Challenge (CEO Review Mode)
+
+Before any interview questions, establish the right scope and ambition level.
+
+#### 0A. Premise Challenge
+
+Ask the user these three questions (one at a time, wait for each response):
+
+1. **"What problem are you solving, and how do you know it's real?"** --- Is this a genuine pain point or a hypothetical one? What evidence exists?
+2. **"What happens if you build nothing?"** --- If the answer is "not much changes," the problem may not be worth solving yet.
+3. **"Who specifically has this problem, and how are they solving it today?"** --- The current workaround reveals what the product must beat.
+
+#### 0B. Scope Posture Selection
+
+Present three postures and ask the user to choose:
+
+1. **SCOPE EXPANSION** --- Dream big. What would make this product so good users tell their friends? What's the 10x version that only costs 2x the effort? You have permission to push scope UP.
+2. **HOLD SCOPE** --- The idea is right-sized. Focus on making it bulletproof --- cover every edge case, define clear boundaries, ensure nothing important is missed.
+3. **SCOPE REDUCTION** --- Cut to the bone. What is the absolute minimum that delivers value? Everything else is deferred. Be ruthless.
+
+**Default guidance:**
+- Brand new idea with no constraints -> suggest EXPANSION
+- Clear idea with defined boundaries -> suggest HOLD SCOPE
+- Overwhelmed user or tight timeline -> suggest REDUCTION
+
+Once selected, commit fully. Do not drift toward a different posture during the interview.
+
+#### 0C. Dream State Mapping (EXPANSION and HOLD only)
+
+Ask: **"Imagine this product is wildly successful 12 months from now. What does it look like? What can users do that they can't do today?"**
+
+Map the response:
+```
+CURRENT STATE              THIS PRD               12-MONTH IDEAL
+[how things work now] ---> [what we're building] ---> [the vision]
+```
+
+This anchors every subsequent decision. If a feature doesn't move toward the 12-month ideal, it may not belong in v1.
+
+#### 0D. Existing Solutions Check
+
+Before proceeding, check:
+- Read `DECISIONS.md` --- has related work already been decided?
+- Read `TODOS.md` (if exists) --- are there deferred items that relate to this idea?
+- Ask: **"Is there anything already built (by you or others) that partially solves this?"**
+
+Log findings. Avoid rebuilding what already exists.
+
+**Once Step 0 is complete, proceed to the interview. Reference the chosen posture throughout.**
+
+---
+
+### Step 1 --- Check for Existing PRD
+
+Read `docs/PRD.md` if it exists. If found, summarize and ask whether to update or start fresh.
+
+---
+
+### Step 2 --- Run the Interview
+
+Wait for the user's response after each round. Adapt depth based on the chosen scope posture.
+
+**Round 1 --- Problem and Users:**
+- What problem? Who has it? How do you know?
+- (EXPANSION) What adjacent problems could this also solve?
+- (REDUCTION) What is the single most painful aspect?
+
+**Round 2 --- Goals and Scope:**
+- Success metric? What does "working" look like?
+- 3-5 MVP features --- what must v1 do?
+- What's NOT in v1? (minimum 3 exclusions)
+- (EXPANSION) What would make this a "10-star" experience? What's the version users would pay double for?
+- (REDUCTION) Can any of the 3-5 features be cut further?
+- Where will users experience the most friction in this flow?
+- What's the minimum number of steps for the core action?
+
+**Round 3 --- Constraints and Kill Rule:**
+- Real constraints (budget, timeline, platform, skills)?
+- Biggest risk --- what could make this fail?
+- Kill rule --- what signal means "stop building this"?
+- (EXPANSION) Which constraints are real vs. assumed? Challenge one.
+
+**Round 4 --- Confirmation:**
+- Summarize everything so far in 5-8 bullets
+- Ask: **"Anything wrong or missing?"**
+
+---
+
+### Step 3 --- Confirm Before Writing
+
+Summarize the PRD in 5-8 bullets. Include:
+- Problem + evidence
+- Target user
+- Scope posture chosen
+- Key features (in/out)
+- Success metric
+- Kill rule
+
+Ask: **"Anything wrong or missing?"**
+
+---
+
+### Step 4 --- Write docs/PRD.md
+
+Use exact section headings (prd-to-tasks skill depends on them):
+
+1. **Overview** --- One-paragraph product summary
+2. **Problem Statement** --- The problem, evidence, who has it, current workarounds
+3. **Vision** --- The 12-month dream state (from Step 0C)
+4. **Goals** --- Success metrics with baseline, target, timeframe
+5. **Target Users** --- Who they are, what they need
+6. **MVP Scope** --- Features in v1, with brief descriptions
+7. **NOT in Scope** --- Features explicitly excluded from v1, with one-line rationale each
+8. **User Stories** --- As a [user], I want [action], so that [outcome]
+9. **Risks and Assumptions** --- Including Kill Rule
+10. **Constraints** --- Budget, timeline, platform, skills
+11. **Open Questions** --- Unresolved items that need answers before building
+
+**Scope posture adjustments:**
+- EXPANSION: Add a "Delight Opportunities" subsection under MVP Scope --- 3-5 small wins (<30 min each) that would make users think "they thought of everything"
+- REDUCTION: MVP Scope should be ruthlessly minimal. Move anything questionable to NOT in Scope.
+
+---
+
+### Step 5 --- Log Decisions and Emit Event
+
+1. Write scope posture and key product decisions to `DECISIONS.md`
+2. Print: `"Suggest emitting: PRD_UPDATED --- use /trigger to create it."`
+3. Update `STATE.md`
+
+---
+
+## Constraints
+
+- Never overwrites existing PRD without confirmation
+- Interview is conversational --- never dump all questions at once
+- Never skip the problem statement
+- Never write solutions before the problem is established
+- Scale to context: solo = lean PRD
+- Once a scope posture is chosen, commit to it --- do not silently drift
+- Step 0 (Vision Challenge) is mandatory --- never skip it
+
+---
+
+## Primary Agent
+
+orchestrator
+
+---
+
+## Definition of Done
+
+- [ ] Vision Challenge completed (Step 0) --- posture selected, premise challenged
+- [ ] docs/PRD.md exists with all required sections
+- [ ] Problem statement includes evidence
+- [ ] Success metric has baseline, target, timeframe
+- [ ] NOT in Scope has at least 3 exclusions with rationale
+- [ ] Kill rule defined
+- [ ] Key decisions logged in DECISIONS.md
+- [ ] STATE.md updated
+
+## Output Contract
+
+| Field | Value |
+|-------|-------|
+| **Artifacts** | `docs/PRD.md` (created or updated) |
+| **State Update** | `.claude/project/STATE.md` --- mark task complete, log files modified |
+| **Decision Log** | `.claude/project/knowledge/DECISIONS.md` --- scope posture and key product decisions |
+| **Handoff Event** | `PRD_UPDATED` (triggers task breakdown via SKL-0003) |

package/template/.claudeignore

@@ -0,0 +1,14 @@
+node_modules/
+dist/
+build/
+coverage/
+*.min.js
+*.min.css
+.env
+.env.*
+!.env.example
+.DS_Store
+Thumbs.db
+*.log
+package-lock.json
+yarn.lock

package/template/FRAMEWORK_VERSION

@@ -0,0 +1 @@
+1.0.0

package/template/README.md

@@ -0,0 +1,95 @@
+# Bashi Starter
+
+> A lightweight AI orchestration framework for building your first project with AI.
+
+**You have ideas. You can direct, design, and decide. Writing code line-by-line is what blocks you.** Bashi Starter gives you the structure to build real software by directing AI agents through a proven pipeline.
+
+## What You Get
+
+- **3 agents** -- Orchestrator (routes work), Builder (writes code), Reviewer (checks quality)
+- **6 skills** -- Plan, PRD, task breakdown, frontend development, code review, deployment
+- **6 commands** -- Everything you need from idea to shipped product
+- **3 safety hooks** -- Blocks dangerous commands, catches secrets before they're written
+
+## Quick Start
+
+```bash
+cd your-project
+npx create-bashi-starter
+```
+
+Then open the project in VS Code with Claude Code and run:
+
+```
+/start
+```
+
+## The Pipeline
+
+Every project follows the same path:
+
+```
+Idea -> PRD -> Tasks -> Build -> Review -> Ship
+```
+
+| Step | What Happens | Command |
+|------|-------------|---------|
+| 1 | Describe your idea | `/capture-idea` |
+| 2 | Generate a PRD and task queue | `/run-project` |
+| 3 | Build tasks one by one | `/run-project` (repeat) |
+| 4 | Save progress between sessions | `/save` |
+
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `/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 |
+
+## How It Works
+
+1. **You describe what you want to build.** The framework helps you write a Product Requirements Document (PRD) in plain language.
+
+2. **The framework creates tasks.** Your PRD gets broken into small, specific steps that AI can execute one at a time.
+
+3. **You build one task at a time.** The orchestrator routes each task to the right agent (builder or reviewer) with the right skill. You review after each step.
+
+4. **Safety hooks watch your back.** They block dangerous commands and catch secrets before they're written to files.
+
+5. **State management remembers where you are.** Close your laptop, come back tomorrow, and pick up exactly where you left off.
+
+## Modes
+
+| Mode | Behavior |
+|------|----------|
+| **Safe** | Propose actions only. Nothing gets modified. |
+| **Semi-Autonomous** | Execute one task, then pause for your review. (Default) |
+| **Autonomous** | Execute up to 5 tasks in a row, then pause. |
+
+## Prerequisites
+
+1. **A computer** (Windows, Mac, or Linux)
+2. **[Node.js](https://nodejs.org)** -- click the LTS button and install with defaults
+3. **[Claude Code](https://docs.anthropic.com/en/docs/claude-code)** -- the AI coding tool
+4. **A Claude subscription** (Pro or Team)
+
+## Want More?
+
+Bashi Starter covers the core pipeline: idea to shipped product. The full Bashi framework adds:
+
+- 12 specialized agents (product manager, architect, designer, and more)
+- 40+ skills (backend, mobile, security audits, analytics, game development)
+- Overnight mode for unattended multi-hour runs
+- Parallel task execution across git worktrees
+- Cortex MCP for on-demand knowledge serving
+- Self-improving agents with cross-agent feedback
+
+Learn more in **"The Syntax Wall"** by Bashar Amso.
+
+## License
+
+MIT