@allthingsclaude/blueprints 0.3.0-beta.2 → 0.3.0-beta.20

package/content/commands/auto.md

@@ -0,0 +1,386 @@
+---
+description: Full autonomous development loop - from idea to committed code
+argument-hint: [--full] [feature description or plan name]
+author: "@markoradak"
+---
+
+# Auto Mode
+
+Full autonomous development loop. I'll take it from idea to committed code on a feature branch.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+
+**Git Status**:
+!`git status --short 2>/dev/null || echo "Not a git repository"`
+
+**Active Plan**:
+!`cat {{STATE_FILE}} 2>/dev/null || echo "No active plan"`
+
+**Available Plans**:
+!`ls -1 {{PLANS_DIR}}/PLAN_*.md 2>/dev/null || echo "No plans found"`
+
+**Project Detection**:
+!`ls package.json tsconfig.json Cargo.toml go.mod pyproject.toml requirements.txt 2>/dev/null || echo "No recognized project files"`
+
+---
+
+## Arguments
+
+$ARGUMENTS
+
+---
+
+## Auto Mode Protocol
+
+You are now in **AUTO MODE** — a full development loop that orchestrates the entire workflow from idea to committed code. Follow these steps precisely and in order.
+
+### Step 0: Parse Arguments
+
+Parse `$ARGUMENTS` for:
+- **`--full`** flag: If present, run the entire loop without stopping for confirmation — commit automatically, skip approval prompts, maximize autonomy. Remove this flag from the remaining arguments before further processing.
+- **Plan name**: If the first remaining word matches an existing plan in `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md`, treat it as a plan name to execute.
+- **Feature description**: Otherwise, treat remaining arguments as a feature description for brainstorming.
+
+Store the `--full` preference — you'll check it at every commit checkpoint and decision point.
+
+---
+
+### Step 1: Determine What to Work On
+
+Follow this decision tree **in order**:
+
+#### 1a. Check for Active Plan in STATE.md
+
+Read `{{STATE_FILE}}`. If it contains an active plan (status is `In Progress` or `Paused`):
+- Load the plan file referenced in STATE.md
+- Check which phase we're on and what tasks remain
+- **If there are uncompleted tasks** → skip to **Step 3** (branch) then **Step 4** (execute)
+- Report: "Resuming active plan: {NAME}, Phase {N}"
+
+#### 1b. Check if Arguments Match an Existing Plan
+
+If a plan name was provided, find the matching plan file in `{{PLANS_DIR}}/` (match by name portion, e.g., `AUTH` matches `PLAN_01_AUTH.md`):
+- Load that plan
+- **STATE UPDATE**: Update `{{STATE_FILE}}` to activate this plan. Read the existing STATE.md first to preserve the `## Overview` table and `## Plans` sections. Update the header fields:
+  ```markdown
+  **Active**: {NN}_{NAME}
+  **File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
+  **Phase**: 1
+  **Status**: 🚧 In Progress
+  **Updated**: [ISO timestamp]
+  ```
+- Update the plan's status in the Overview table to `🚧 In Progress`
+- Skip to **Step 3** (branch) then **Step 4** (execute)
+
+#### 1c. No Active Work — Enter Brainstorm
+
+If there's nothing to resume:
+
+**If arguments contain a feature description:**
+Enter brainstorm mode. You are exploring the idea, NOT implementing. Your goals:
+1. Understand the user's intent
+2. Ask 2-4 focused followup questions to clarify scope, approach, and constraints
+3. Explore the codebase for relevant context (use Read, Grep, Glob)
+4. Converge on a clear approach
+
+**If no arguments at all:**
+Ask the user: "What would you like to build? Describe the feature or change you have in mind."
+Then proceed with brainstorm as above once they respond.
+
+**Brainstorm rules:**
+- DO NOT create, modify, or implement any code
+- DO ask clarifying questions (scope, approach, edge cases)
+- DO explore existing code for context
+- Keep it to 2-3 rounds of questions max, then converge
+- Once the approach is clear, move to Step 2
+
+---
+
+### Step 2: Create the Plan
+
+After brainstorming, determine which planning mode to use:
+
+#### Detect Project Type
+
+Check if this is a **new project** (needs bootstrapping) or an **existing project** (needs a plan):
+
+**New project indicators** (if most are true):
+- No `src/` or `app/` or `lib/` directory
+- No or nearly empty `package.json` / `Cargo.toml` / `go.mod` etc.
+- Very few source files (< 5)
+- The user explicitly said "new project" or "start from scratch"
+
+**If new project:**
+Use the Task tool to launch the bootstrap agent (`subagent_type="bootstrap"`) with the feature name and brainstorm context. This will generate both a plan and a bootstrap.sh script.
+
+After the bootstrap agent completes, ask the user: "Bootstrap script is ready. Should I run it to set up the project?"
+- If yes → run `bash bootstrap.sh`
+- If no → note it and continue
+
+**UPDATE CLAUDE.md**: After bootstrap completes, run the update agent to generate an initial CLAUDE.md:
+- Use the Task tool to launch the update agent (`subagent_type="update"`) to scan the newly bootstrapped project and create CLAUDE.md
+
+**COMMIT CHECKPOINT**: After bootstrap and CLAUDE.md update complete, commit the scaffolding:
+- Stage all new project files (including CLAUDE.md)
+- Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context: "chore: bootstrap {NAME} project scaffolding"
+
+**If existing project:**
+Use the Task tool to launch the plan agent (`subagent_type="plan"`) with the feature name and brainstorm context. This will generate `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` and update `{{STATE_FILE}}`.
+
+Wait for the plan agent to complete, then load and display a brief summary of the plan.
+
+**COMMIT CHECKPOINT**: After plan is created, commit it:
+- Stage the plan file and STATE.md
+- Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context: "docs: add implementation plan for {NAME}"
+
+---
+
+### Step 3: Create Feature Branch
+
+Before starting implementation, create a feature branch:
+
+1. Determine the branch name from the plan name:
+   - Convert plan name to lowercase kebab-case
+   - Prefix with `feat/` (e.g., plan "USER_AUTH" → branch `feat/user-auth`)
+2. Check if the branch already exists:
+   - If yes and we're resuming → switch to it: `git checkout feat/{name}`
+   - If yes and NOT resuming → switch to it (it may have prior work)
+   - If no → create it: `git checkout -b feat/{name}`
+3. Confirm the branch: `git branch --show-current`
+
+Report: "Working on branch: `feat/{name}`"
+
+---
+
+### Step 4: Execute the Plan (Phase by Phase)
+
+Load the plan from `{{PLANS_DIR}}/PLAN_{NN}_{NAME}.md` and identify all phases.
+
+**For each phase**, repeat this cycle:
+
+#### 4a. Assess the Phase
+
+Count the `- [ ]` uncompleted tasks in the current phase.
+
+#### 4b. Execute the Phase
+
+**First, check if this phase involves landing page / marketing page / homepage design work.** Look for task descriptions containing: "landing page", "homepage", "marketing page", "hero section", "showcase page", or similar. If the phase is primarily about designing/building a landing page, use the **showcase agent** instead of the generic implement agent.
+
+| Phase Type | Phase Tasks | Mode | Rationale |
+|---|---|---|---|
+| Landing page | Any | `/showcase` | Specialized for high-end landing page design with animations |
+| Regular | 1-5 tasks | `/implement` | Small enough for a single agent |
+| Regular | 6+ tasks | `/parallelize` | Benefits from concurrent execution |
+
+**For `/showcase` mode:**
+Use the Task tool to launch the showcase agent (`subagent_type="showcase"`) with the plan context and any reference files from `{{TASKS_DIR}}/references/`.
+
+**For `/implement` mode:**
+Use the Task tool to launch the implement agent (`subagent_type="implement"`) with the plan name and instruction to work on the current phase only (e.g., "Execute Phase 1 only, then stop").
+
+**For `/parallelize` mode:**
+Use the Task tool to launch the parallelize orchestrator (`subagent_type="parallelize"`) with the plan name and instruction to work on the current phase only.
+
+Wait for the agent to complete. Review its summary.
+
+**If the agent reports blockers:**
+Present the blockers to the user and ask how to proceed. Do NOT continue until blockers are resolved or the user says to skip them.
+
+#### 4c. Commit the Phase
+
+**COMMIT CHECKPOINT**: After each phase completes:
+- Use the Task tool to launch the commit agent (`subagent_type="commit"`) with context describing what was accomplished in this phase
+- The commit agent will determine the appropriate prefix (`feat:`, `fix:`, `refactor:`, `chore:`, etc.) based on the nature of the changes
+- The commit message should reference the plan and phase (e.g., "feat: implement user authentication (PLAN_AUTH Phase 1)")
+
+**STATE UPDATE**: Read and update `{{STATE_FILE}}`:
+- Increment `**Phase**` to the next phase number
+- Keep `**Status**` as `🚧 In Progress`
+- Update `**Updated**` timestamp
+- Mark completed tasks as `✅` in the task tables under `## Plans`
+- Update completed phase headers from `🚧` to `✅`
+- Update the Progress column in the Overview table
+
+#### 4d. Continue to Next Phase
+
+After committing and updating STATE.md, check if there are more phases remaining:
+- **More phases** → loop back to 4a for the next phase
+- **All phases done** → proceed to Step 5
+
+---
+
+### Step 5: Validate & Fix
+
+After all phases are implemented and committed, run validation. Each step uses a subagent:
+
+#### 5a. Audit
+
+Use the Task tool to launch the audit agent (`subagent_type="audit"`).
+
+Review the audit report. If it finds **critical or important issues**:
+- Attempt auto-fix (the audit agent can do this)
+- Re-run typecheck/lint after fixes
+- If issues persist after 2 fix attempts → report to user and ask whether to proceed
+
+**COMMIT CHECKPOINT**: If the audit resulted in fixes, commit them:
+- Use the commit agent with context: "fix: address audit findings for {NAME}"
+
+#### 5b. Test
+
+Use the Task tool to launch the test agent (`subagent_type="test"`).
+
+Review test results:
+- If all tests pass → continue
+- If tests fail → attempt to fix (max 2 attempts)
+- If tests still fail → report to user with failure details and ask whether to proceed
+
+**COMMIT CHECKPOINT**: If test fixes were made, commit them:
+- Use the commit agent with context: "fix: resolve test failures for {NAME}"
+
+#### 5c. Security
+
+Use the Task tool to launch the secure agent (`subagent_type="secure"`).
+
+Review security report:
+- If no critical/high findings → continue
+- If critical findings → attempt to fix and re-scan (max 2 attempts)
+- If still failing → report to user and ask whether to proceed
+
+**COMMIT CHECKPOINT**: If security fixes were made, commit them:
+- Use the commit agent with context: "fix: address security findings for {NAME}"
+
+**If ALL validation passes cleanly**, report:
+```markdown
+**Validation Complete**
+- Audit: Passed
+- Tests: Passed
+- Security: Passed
+```
+
+---
+
+### Step 6: Update & Report
+
+**UPDATE CLAUDE.md**: Before reporting, sync CLAUDE.md with the current project state:
+- Use the Task tool to launch the update agent (`subagent_type="update"`) to scan the project and update CLAUDE.md with any new patterns, dependencies, or structural changes from this session
+- If CLAUDE.md was updated, include it in the final commit
+
+**STATE UPDATE**: Read and update `{{STATE_FILE}}` to reflect final status:
+- If all phases and validation passed: set `**Active**` to `None`, update plan's status to `✅ Complete` in Overview table, set `**Status**: ✅ Complete`
+- If partially complete (blockers, user stopped): keep `**Active**` pointing to the plan, set `**Status**: ⏸️ Paused`
+- Update `**Phase**` to the last completed phase number
+- Update `**Updated**` timestamp
+- Update all task statuses in the task tables under `## Plans` to reflect final state
+
+After everything is done (or stopped), provide a final summary:
+
+```markdown
+**Auto Mode Complete**
+
+**Branch**: `feat/{name}`
+**Plan**: {NAME}
+**Status**: {Complete / Partially Complete}
+
+**Commits Made**:
+- `{hash}` {commit message 1}
+- `{hash}` {commit message 2}
+- `{hash}` {commit message 3}
+
+**What Was Done**:
+- [Phase 1 summary]
+- [Phase 2 summary]
+
+**Validation Results**:
+- Audit: {result}
+- Tests: {result}
+- Security: {result}
+
+**Next Steps**:
+- Review changes: `git log main..feat/{name} --oneline`
+- Create PR when ready: `gh pr create`
+- Or continue working: `/auto` (will resume from STATE.md)
+```
+
+---
+
+## Commit Checkpoint Rules
+
+Auto mode commits **early and often** using the commit agent (`subagent_type="commit"`). The commit agent determines the right prefix (`feat:`, `fix:`, `refactor:`, `chore:`, `docs:`, etc.) based on the changes.
+
+**When to commit:**
+- After bootstrap scaffolding is created
+- After plan document is generated
+- After each implementation phase completes
+- After audit/test/security fixes are applied
+
+**When NOT to commit:**
+- If there are no changes (empty diff)
+- If validation is failing and fixes haven't been applied yet
+
+**`--full` behavior at commit checkpoints:**
+- With `--full`: commit agent runs automatically at every checkpoint, no user prompt
+- Without `--full` (default): commit agent still runs automatically — commits are non-destructive and keep work safe. The `--full` flag controls other approval gates (like blocker decisions), not commits.
+
+---
+
+## Critical Guidelines
+
+### Be Autonomous But Not Reckless
+- Execute the full loop without unnecessary user prompts
+- Commit after every major milestone to keep work safe
+- BUT always stop for: blockers and validation failures that can't be auto-fixed
+- Never force-push, delete branches, or make destructive changes without asking
+
+### Compose Existing Agents
+- Use the existing subagent types: `bootstrap`, `plan`, `implement`, `parallelize`, `showcase`, `audit`, `test`, `secure`, `commit`, `update`
+- Do NOT try to do their jobs inline — delegate to specialists
+- Always use the commit agent for commits — it writes proper conventional commit messages (`feat:`, `fix:`, `refactor:`, etc.)
+
+### Handle Failures Gracefully
+- Max 2 auto-fix retry attempts per validation step
+- After 2 failures, stop and ask the user
+- Never silently skip failing validation
+
+### Track State (MANDATORY)
+
+`{{STATE_FILE}}` must ALWAYS reflect current progress. Update it at these points:
+1. **Step 1b** — when activating an existing plan (set Phase 1, Status In Progress)
+2. **Step 2** — plan agent creates it (verify it exists after plan agent completes)
+3. **Step 4c** — after each phase commit (increment Phase, update timestamp, mark completed tasks as ✅ in task tables)
+4. **Step 6** — final status (Complete or Paused)
+
+**STATE.md header fields** (always keep these parseable at the top):
+```markdown
+# State
+
+**Active**: {NN}_{NAME}
+**File**: {{PLANS_DIR}}/PLAN_{NN}_{NAME}.md
+**Phase**: {current_phase_number}
+**Status**: 🚧 In Progress
+**Updated**: {ISO timestamp}
+```
+
+**When updating STATE.md**:
+- Always READ existing STATE.md first to preserve `## Overview` table and `## Plans` sections
+- Update the header fields (Active, File, Phase, Status, Updated)
+- Update the active plan's status in `## Overview` table
+- Update task statuses (`⏳` → `🚧` → `✅`) in the task tables under `## Plans`
+- Update phase status emoji in phase headers (`⏳` → `🚧` → `✅`)
+- Update the Progress column in `## Overview` table (e.g., `5/18 tasks`)
+
+**When all work on a plan is done**:
+- Set `**Active**` to `None` (or the next plan if one exists)
+- Update the plan's status in the Overview table to `✅ Complete`
+- Mark all tasks as `✅` in the plan's task tables
+- Set `**Status**` to `✅ Complete`
+
+If `/auto` is interrupted or paused, ensure STATE.md reflects where it stopped so the next `/auto` run can resume correctly. Plan document checkboxes are updated by the implement/parallelize agents.
+
+### Keep the User Informed
+- Brief status updates between major steps
+- Detailed reports only at the end or when asking for decisions
+- Don't flood with intermediate output — the subagents handle that internally

package/content/commands/bootstrap.md

@@ -26,7 +26,7 @@ $ARGUMENTS
 ## Generating Plan & Bootstrap Script
 
 Launching the bootstrap agent to analyze our brainstorming conversation and generate:
-1. `tasks/plans/PLAN_{NAME}.md` (via `/plan` command)
+1. `{{PLANS_DIR}}/PLAN_00_INITIAL.md` — the first plan is always numbered `00` for new projects
 2. `./bootstrap.sh` (executable setup script)
 
 The agent will:

package/content/commands/brainstorm.md

@@ -13,45 +13,107 @@ You are now in **BRAINSTORMING MODE**. Your goal is to explore ideas, discuss ap
 
 This is pure ideation. We're thinking, not doing.
 
+## Step 0: Detect Project State
+
+Before brainstorming, quickly assess the current project:
+
+**Project Detection**:
+!`ls package.json tsconfig.json Cargo.toml go.mod pyproject.toml requirements.txt composer.json Gemfile pom.xml build.gradle mix.exs 2>/dev/null || echo "No recognized project files"`
+
+**Source Files**:
+!`find . -maxdepth 3 -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" -o -name "*.py" -o -name "*.rs" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.ex" -o -name "*.php" \) 2>/dev/null | head -10 | wc -l`
+
+**Is this an empty/new project?** If there are fewer than 5 source files and no meaningful project configuration, this is likely a **new project**. In that case:
+- Mention to the user that this looks like a new project and brainstorming is a great starting point
+- The brainstorm should focus heavily on **tech stack decisions** (see Step 1 below)
+- When brainstorming is complete, suggest `/auto` which will handle planning, bootstrapping, and implementation end-to-end
+
 ## Brainstorming Framework
 
-### 1. **Understand the Space**
+### Step 1: **Understand the Space & Tech Stack**
+
+Start by understanding what the user wants to build, then **always ask about the tech stack**. Present suggestions with options so the user can choose.
+
+**First, clarify the idea:**
 - What problem or opportunity are we exploring?
 - What are the key constraints or requirements?
 - What context is important to consider?
 
-### 2. **Explore Possibilities**
+**Then, ask about the tech stack.** Use `AskUserQuestion` to present choices for each relevant category. Tailor the categories to the project type — not every project needs all of these. Suggest sensible defaults based on the project description, but always let the user choose.
+
+**Categories to cover (as applicable):**
+
+| Category | When to Ask | Example Options |
+|---|---|---|
+| **Language/Runtime** | Always for new projects | TypeScript, Python, Go, Rust, etc. |
+| **Frontend Framework** | If project has a UI | React, Next.js, Vue, Svelte, Astro, etc. |
+| **Styling** | If project has a UI | Tailwind CSS, CSS Modules, styled-components, Shadcn/ui, etc. |
+| **Backend Framework** | If project has server logic | Express, Fastify, Hono, Django, FastAPI, etc. |
+| **Database** | If project needs persistence | PostgreSQL, SQLite, MongoDB, Supabase, etc. |
+| **ORM/Data Layer** | If using a database | Prisma, Drizzle, SQLAlchemy, TypeORM, etc. |
+| **Authentication** | If project needs auth | NextAuth, Clerk, Lucia, Supabase Auth, etc. |
+| **Hosting/Deployment** | If deployment matters | Vercel, Railway, Fly.io, AWS, self-hosted, etc. |
+| **Package Manager** | For JS/TS projects | npm, pnpm, bun, yarn, etc. |
+| **Testing** | If testing strategy matters | Vitest, Jest, Pytest, Playwright, etc. |
+
+**Guidelines for tech stack questions:**
+- Ask 2-4 questions at a time (don't overwhelm with all categories at once)
+- Mark the recommended option with "(Recommended)" based on the project context
+- Include a brief reason in the description for each option
+- If the project already has an established stack (existing project), acknowledge it and only ask about new additions
+- Respect the user's choices — don't push back unless there's a genuine compatibility issue
+
+### Step 2: **Explore Possibilities**
 - What are 3-5 different approaches we could take?
 - What are the pros and cons of each?
 - Are there any unconventional ideas worth considering?
 
-### 3. **Deep Dive**
+### Step 3: **Deep Dive**
 - Let's examine the most promising approaches in detail
 - What technical considerations come into play?
 - What dependencies or integration points exist?
 - What could go wrong? What edge cases matter?
 
-### 4. **Refine & Converge**
+### Step 4: **Refine & Converge**
 - Which approach feels strongest and why?
 - What questions remain unanswered?
 - What research or investigation is needed?
 - What would the implementation phases look like?
 
+## Critical Thinking (Always Active)
+
+Throughout brainstorming, actively use the `/critique`, `/verify`, and `/challenge` commands to stress-test ideas **as they emerge**. Don't wait until the end — run these after each step.
+
+### When to invoke each command
+
+- **`/critique`** — After exploring approaches (Steps 2-3). Run this against the ideas on the table to get direct, unfiltered feedback on what's wrong or suboptimal.
+- **`/verify`** — After converging on a direction (Steps 3-4). Run this to sanity-check that we're solving the right problem the right way, and to catch gotchas.
+- **`/challenge`** — After the user proposes or agrees to an approach (any step). Run this to question assumptions, surface trade-offs, and suggest alternatives.
+
+### How to apply
+
+- Invoke these commands naturally throughout the conversation — not as a rigid sequence
+- You can run them multiple times as ideas evolve
+- The goal is **unfiltered, honest exploration** — not polite agreement with whatever the user suggests
+- If an idea survives all three, it's probably solid
+
 ## Discussion Guidelines
 
-- **Ask questions** to clarify and probe deeper
-- **Suggest alternatives** even if they seem unconventional
-- **Challenge assumptions** constructively
+- **Be direct** — if an idea is bad, say so and explain why
+- **Ask hard questions** to probe deeper and expose weak spots
+- **Suggest alternatives** even if they contradict the user's initial direction
 - **Think out loud** about trade-offs and implications
 - **Reference existing code** when relevant for context
 - **Draw connections** to similar patterns in the codebase
 - **Be thorough** - we're not rushing to implementation
+- **Don't hedge** — if you're confident something won't work, say it plainly
 
 ## Tools You CAN Use
 - ✅ Read files for context and understanding
 - ✅ Grep/Glob to explore existing patterns
 - ✅ Bash (read-only: ls, cat, find, git log, etc.)
 - ✅ Research agents for investigation
+- ✅ AskUserQuestion for tech stack and approach choices
 
 ## Tools You CANNOT Use
 - 🚫 Write - No creating new files
@@ -61,13 +123,23 @@ This is pure ideation. We're thinking, not doing.
 
 ## When Brainstorming is Complete
 
-Once we've thoroughly explored the problem space and converged on an approach, use:
+Once we've thoroughly explored the problem space, settled on a tech stack, and converged on an approach, suggest the appropriate next step. Present these options to the user:
+
+**For new/empty projects:**
+
+| Command | What it does |
+|---|---|
+| `/bootstrap {NAME}` | Generate a plan + bootstrap script to scaffold the project. Good when you want to review the scaffolding before building. |
+| `/auto {NAME}` | Full autonomous loop — planning, bootstrapping, implementation, and commit. Good when you want to go hands-off. |
+
+**For existing projects:**
 
-```
-/plan {DESCRIPTIVE_NAME}
-```
+| Command | What it does |
+|---|---|
+| `/plan {NAME}` | Capture brainstorming findings into a structured implementation plan. Good when you want to review before implementing. |
+| `/auto {NAME}` | Full autonomous loop — planning, implementation, validation, and commit. Good when you want to go hands-off. |
 
-This will capture our brainstorming findings into a structured implementation plan.
+Always present the relevant options and let the user choose how they want to proceed.
 
 ---
 

package/content/commands/challenge.md

@@ -1,5 +1,6 @@
 ---
 description: Challenge Mode - Critical Thinking Assistant
+argument-hint: [optional: approach or decision to challenge]
 author: "@markoradak"
 ---
 
@@ -23,4 +24,10 @@ You are now in "challenge mode." Before implementing any task or answering quest
 ## Example Response Pattern
 "Before I implement this, I want to make sure we're solving the right problem. [Question about the real need]. Also, have you considered [alternative approach] which might be more [benefit]? The approach you've outlined will work, but it does mean [trade-off]. Should I proceed with your original plan or would you like to explore the alternative?"
 
+## Scope
+
+This mode applies to the current task or topic. Once the challenge is addressed, normal conversation resumes.
+
+---
+
 $ARGUMENTS

package/content/commands/changelog.md

@@ -0,0 +1,50 @@
+---
+description: Generate a changelog from git history
+argument-hint: [optional: version tag, date range, or "unreleased"]
+author: "@markoradak"
+---
+
+# Generate Changelog
+
+I'll analyze your git history and generate a well-structured changelog.
+
+> **When to use**: You're preparing a release and need a changelog, or want to document what changed between versions. Use `/finalize` to commit and close a session, or `/docs` for general documentation.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+
+**Latest Tags**:
+!`git tag --sort=-version:refname 2>/dev/null | head -5 || echo "No tags found"`
+
+**Recent Commits**:
+!`git log --oneline -10 2>/dev/null`
+
+---
+
+## Changelog Scope
+
+$ARGUMENTS
+
+---
+
+## Launching Changelog Agent
+
+The changelog agent will:
+- Analyze git log between the specified range (or since last tag)
+- Categorize commits by type (features, fixes, breaking changes, etc.)
+- Group related changes and write clear descriptions
+- Highlight breaking changes prominently
+- Generate a changelog following Keep a Changelog format
+- Append to or create CHANGELOG.md
+
+**Workflows**:
+- No argument → Changes since the last tag (unreleased)
+- `v1.2.0` → Changes since that tag
+- `v1.1.0..v1.2.0` → Changes between two tags
+- `unreleased` → Same as no argument
+- `2024-01-01..` → Changes since a date
+
+Use the Task tool to launch the changelog agent (subagent_type="changelog") with the scope and any additional context.

package/content/commands/cleanup.md

@@ -8,11 +8,13 @@ author: "@markoradak"
 
 I'll scan your codebase for dead code, unused imports, and technical debt.
 
+> **When to use**: You want to remove things that shouldn't be there (unused imports, dead exports, stale TODOs, console.logs). Use `/dry` to consolidate duplicated code, `/refactor` for structural changes, or `/audit` to review changes before committing.
+
 ## Current State
 
 **Working Directory**: !`pwd`
 
-**Branch**: !`git branch --show-current`
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
 
 **Files to Analyze**:
 !`find . -maxdepth 5 -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" 2>/dev/null | grep -v node_modules | wc -l` source files

package/content/commands/commit.md

@@ -0,0 +1,45 @@
+---
+description: Create a well-crafted git commit from your current changes
+argument-hint: [optional: commit message hint or scope]
+author: "@markoradak"
+---
+
+# Commit Changes
+
+I'll analyze your changes and create a clean, well-structured git commit.
+
+> **When to use**: You have changes ready to commit and want a good commit message without the full session finalization. Use `/finalize` when closing out a work session with plan updates and phase summaries. Use `/audit` to review changes before committing.
+
+## Current State
+
+**Working Directory**: !`pwd`
+
+**Branch**: !`git branch --show-current 2>/dev/null || echo "Not a git repository"`
+
+**Status**:
+!`git status --short`
+
+**Changes Summary**:
+!`git diff --stat`
+
+---
+
+## Context
+
+$ARGUMENTS
+
+---
+
+## Launching Commit Agent
+
+The commit agent will:
+- Review all staged and unstaged changes
+- Understand the intent and scope of the changes
+- Determine the appropriate commit type (`feat`, `fix`, `refactor`, etc.)
+- Draft a concise, well-formatted commit message
+- Stage the relevant files and create the commit
+- Verify the commit was created successfully
+
+**This will create a git commit.** The agent will show you the proposed message before committing.
+
+Use the Task tool to launch the commit agent (subagent_type="commit") with any additional context from arguments.