Address review feedback: clarify approval gate before file creation

- Made step 11 explicitly a gate before file creation - Added explicit conditional ("If user declines/approves") flow - Added note at Phase 6 start: "Only execute this phase after user approval" - Added error handling notes for directory creation and file writes The step ordering was already correct (approval step 11 before file creation steps 12-13), but the flow is now more explicit about the conditional nature. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Add /create-capability command with validation and interactive guidance
2026-01-10 19:51:01 +01:00 · 2026-01-10 19:19:43 +01:00
33 changed files with 240 additions and 550 deletions
--- a/agents/code-reviewer/AGENT.md
+++ b/agents/code-reviewer/AGENT.md
@@ -17,67 +17,18 @@ You are a code review specialist that provides immediate, structured feedback on
 You will receive a PR number to review. Follow this process:
 1. Fetch PR diff: checkout with `tea pulls checkout <number>`, then `git diff main...HEAD`
-2. Detect and run project linter (see Linter Detection below)
+2. Analyze the diff for issues in these categories:
 3. Analyze the diff for issues in these categories:
   - **Code Quality**: Readability, maintainability, complexity
   - **Bugs**: Logic errors, edge cases, null checks
   - **Security**: Injection vulnerabilities, auth issues, data exposure
-   - **Lint Issues**: Linter warnings and errors (see below)
+   - **Style**: Naming conventions, formatting, consistency
   - **Test Coverage**: Missing tests, untested edge cases
-4. Generate a structured review comment
+3. Generate a structured review comment
-5. Post the review using `tea comment <number> "<review body>"`
+4. Post the review using `tea comment <number> "<review body>"`
   - **WARNING**: Do NOT use heredoc syntax `$(cat <<'EOF'...)` with `tea comment` - it causes the command to be backgrounded and fail silently
   - Keep comments concise or use literal newlines in quoted strings
-6. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`, then clean up with `tea pulls clean <number>`
+5. **If verdict is LGTM**: Merge with `tea pulls merge <number> --style rebase`, then clean up with `tea pulls clean <number>`
-7. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
+6. **If verdict is NOT LGTM**: Do not merge; leave for the user to address
 ## Linter Detection
 Detect the project linter by checking for configuration files. Run the linter on changed files only.
 ### Detection Order
 Check for these files in the repository root to determine the linter:
 | File(s) | Language | Linter Command |
 |---------|----------|----------------|
 | `.eslintrc*`, `eslint.config.*` | JavaScript/TypeScript | `npx eslint <files>` |
 | `pyproject.toml` with `[tool.ruff]` | Python | `ruff check <files>` |
 | `ruff.toml`, `.ruff.toml` | Python | `ruff check <files>` |
 | `setup.cfg` with `[flake8]` | Python | `flake8 <files>` |
 | `.pylintrc`, `pylintrc` | Python | `pylint <files>` |
 | `go.mod` | Go | `golangci-lint run <files>` or `go vet <files>` |
 | `Cargo.toml` | Rust | `cargo clippy -- -D warnings` |
 | `.rubocop.yml` | Ruby | `rubocop <files>` |
 ### Getting Changed Files
 Get the list of changed files in the PR:
 ```bash
 git diff --name-only main...HEAD
 ```
 Filter to only files matching the linter's language extension.
 ### Running the Linter
 1. Only lint files that were changed in the PR
 2. Capture both stdout and stderr
 3. If linter is not installed, note this in the review (non-blocking)
 4. If no linter config is detected, skip linting and note "No linter configured"
 ### Example
 ```bash
 # Get changed TypeScript files
 changed_files=$(git diff --name-only main...HEAD | grep -E '\.(ts|tsx|js|jsx)$')
 # Run ESLint if files exist
 if [ -n "$changed_files" ]; then
  npx eslint $changed_files 2>&1
 fi
 ```
 ## Review Comment Format
@@ -103,11 +54,8 @@ Post reviews in this structured format:
 #### Security Concerns
 - [Finding or "No issues found"]
-#### Lint Issues
+#### Style Notes
- [Linter output or "No lint issues" or "No linter configured"]
+- [Finding or "Consistent with codebase"]
 Note: Lint issues are stylistic and formatting concerns detected by automated tools.
 They are separate from logic bugs and security vulnerabilities.
 #### Test Coverage
 - [Finding or "Adequate coverage"]
@@ -119,16 +67,12 @@ They are separate from logic bugs and security vulnerabilities.
 ## Verdict Criteria
 - **LGTM**: No blocking issues, code meets quality standards, ready to merge
- **Needs Changes**: Minor issues worth addressing before merge (including lint issues)
+- **Needs Changes**: Minor issues worth addressing before merge
 - **Blocking Issues**: Security vulnerabilities, logic errors, or missing critical functionality
 **Note**: Lint issues alone should result in "Needs Changes" at most, never "Blocking Issues".
 Lint issues are style/formatting concerns, not functional problems.
 ## Guidelines
 - Be specific: Reference exact lines and explain *why* something is an issue
 - Be constructive: Suggest alternatives when pointing out problems
 - Be kind: Distinguish between blocking issues and suggestions
 - Acknowledge good solutions when you see them
 - Clearly separate lint issues from logic/security issues in your feedback
--- a/agents/issue-worker/agent.md
+++ b/agents/issue-worker/agent.md
@@ -1,11 +1,6 @@
 ---
 name: issue-worker
 model: haiku
 description: Autonomous agent that implements a single issue in an isolated git worktree
 # Model: sonnet provides balanced speed and capability for implementation tasks.
 # Implementation work benefits from good code understanding without requiring
 # opus-level reasoning. Faster iteration through the implement-commit-review cycle.
 model: sonnet
 tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite
 skills: gitea, issue-writing, software-architecture
 ---
--- a/agents/pr-fixer/agent.md
+++ b/agents/pr-fixer/agent.md
@@ -1,11 +1,6 @@
 ---
 name: pr-fixer
 model: haiku
 description: Autonomous agent that addresses PR review feedback in an isolated git worktree
 # Model: sonnet provides balanced speed and capability for addressing feedback.
 # Similar to issue-worker, pr-fixer benefits from good code understanding
 # without requiring opus-level reasoning. Quick iteration on review feedback.
 model: sonnet
 tools: Bash, Read, Write, Edit, Glob, Grep, TodoWrite, Task
 skills: gitea, code-review
 ---
--- a/commands/arch-refine-issue.md
+++ b/commands/arch-refine-issue.md
@@ -1,6 +1,5 @@
 ---
 description: Refine an issue with architectural perspective. Analyzes existing codebase patterns and provides implementation guidance.
 model: opus
 argument-hint: <issue-number>
 ---
--- a/commands/arch-review-repo.md
+++ b/commands/arch-review-repo.md
@@ -1,6 +1,5 @@
 ---
 description: Perform a full architecture review of the current repository. Analyzes structure, patterns, dependencies, and generates prioritized recommendations.
 model: opus
 argument-hint:
 context: fork
 ---
--- a/commands/commit.md
+++ b/commands/commit.md
@@ -1,86 +0,0 @@
 ---
 description: Create a commit with an auto-generated conventional commit message. Analyzes staged changes and proposes a message for approval.
 argument-hint:
 ---
 # Commit Changes
 ## Process
 1. **Check for staged changes**:
   ```bash
   git diff --staged --stat
   ```
   If no staged changes, inform the user and suggest staging files first:
   - Show unstaged changes with `git status`
   - Ask if they want to stage all changes (`git add -A`) or specific files
 2. **Analyze staged changes**:
   ```bash
   git diff --staged
   ```
   Examine the diff to understand:
   - What files were changed, added, or deleted
   - The nature of the changes (new feature, bug fix, refactor, docs, etc.)
   - Key details worth mentioning
 3. **Generate commit message**:
   Create a conventional commit message following this format:
   ```
   <type>(<scope>): <description>
   [optional body with more details]
   Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
   ```
   **Types:**
   - `feat`: New feature or capability
   - `fix`: Bug fix
   - `refactor`: Code restructuring without behavior change
   - `docs`: Documentation changes
   - `style`: Formatting, whitespace (no code change)
   - `test`: Adding or updating tests
   - `chore`: Maintenance tasks, dependencies, config
   **Scope:** The component or area affected (optional, use when helpful)
   **Description:**
   - Imperative mood ("add" not "added")
   - Lowercase first letter
   - No period at the end
   - Focus on the "why" when the "what" is obvious
 4. **Present message for approval**:
   Show the proposed message and ask the user to:
   - **Approve**: Use the message as-is
   - **Edit**: Let them modify the message
   - **Regenerate**: Create a new message with different focus
 5. **Create the commit**:
   Once approved, execute:
   ```bash
   git commit -m "$(cat <<'EOF'
   <approved message>
   EOF
   )"
   ```
 6. **Confirm success**:
   Show the commit result and suggest next steps:
   - Push to remote: `git push`
   - Continue working and commit more changes
 ## Guidelines
 - Only commits what's staged (respects partial staging)
 - Never auto-commits without user approval
 - Keep descriptions concise (50 chars or less for first line)
 - Include body for non-obvious changes
 - Always include Co-Authored-By attribution
--- a/commands/create-capability.md
+++ b/commands/create-capability.md
@@ -1,123 +1,256 @@
 ---
-description: Create a new capability (skill, command, agent, or a cohesive set) for the architecture repository.
+description: Create new capabilities (skills, commands, agents) with validation and guided design decisions.
 argument-hint: <description>
 model: sonnet
 ---
 # Create Capability
@~/.claude/skills/capability-writing/SKILL.md
-Create new capabilities following established patterns. A capability may be a single component or a cohesive set (skill + command + agent).
+Create new capabilities for the architecture repository with validation and interactive guidance.
 ## Process
-1. **Understand the capability**: Analyze "$1" to understand what the user wants to build
+### Phase 1: Understand Intent
   - What domain or workflow does this cover?
   - What user need does it address?
   - What existing capabilities might overlap?
-2. **Determine components needed**: Based on the description, recommend which components:
+1. **Parse the description** from `$1` or ask for one:
   - "What capability do you want to add? Describe what it should do."
-   | Pattern | When to Use |
+2. **Ask clarifying questions** to determine component type:
   |---------|-------------|
   | Skill only | Knowledge to apply automatically (reused across commands) |
   | Command only | User-invoked workflow using existing skills |
   | Command + Skill | New knowledge + workflow to use it |
   | Command + Agent | Workflow with isolated worker for complex subtasks |
   | Full set | New domain expertise + workflow + isolated work |
-   Present recommendation with reasoning:
+   | Question | Purpose |
-   ```
+   |----------|---------|
-   ## Recommended Components for: $1
+   | "Will this knowledge apply automatically, or is it user-invoked?" | Skill vs Command |
   | "Does this need isolated context for complex work?" | Agent needed? |
   | "Is this read-only analysis or does it modify files?" | Tool restrictions |
   | "Will this be used repeatedly, or is it one-time?" | Worth encoding? |
-   Based on your description, I recommend:
+3. **Recommend components** based on answers:
-   - **Skill**: `name` - [why this knowledge is needed]
+   - **Skill only**: Knowledge Claude applies automatically
-   - **Command**: `/name` - [what user action this enables]
+   - **Command only**: Workflow using existing skills
-   - **Agent**: `name` - [why isolation/specialization is needed] (optional)
+   - **Command + Skill**: New knowledge + workflow
   - **Command + Agent**: Workflow with isolated worker
   - **Full set**: Skill + Command + Agent
-   Reasoning: [explain why this combination fits the need]
+### Phase 2: Gather Details
   ```
-3. **Gather information**: For each recommended component, ask:
+4. **Collect information for each component**:
   **For all components:**
   - Name (kebab-case, descriptive)
   - Description (one-line summary)
   **For Skills:**
-   - What domain/knowledge does this cover?
+   - Name (kebab-case): skill name matching directory
-   - What are the key concepts to teach?
+   - Description: what it teaches + trigger conditions
-   - What patterns or templates should it include?
+   - Core sections to include
   **For Commands:**
-   - What triggers this workflow?
+   - Name (kebab-case): verb-phrase action name
-   - What are the key steps?
+   - Description: one-line summary
-   - What approval points are needed?
+   - Arguments: required `<arg>` and optional `[arg]`
-   - What skills should it reference?
+   - Skills to reference
   **For Agents:**
-   - What specialized role does this fill?
+   - Name (kebab-case): role-based specialist name
-   - What skills does it need?
+   - Description: what it does + when to spawn
-   - Should it be read-only (no Edit/Write)?
+   - Skills it needs
   - Tool restrictions (read-only?)
-4. **Select appropriate models**:
+### Phase 3: Model Selection
-   | Model | Use For |
+5. **Recommend appropriate models** with explanation:
   |-------|---------|
   | `haiku` | Simple fetch/display commands, formatting tasks |
   | `sonnet` | Most commands and agents (default) |
   | `opus` | Deep reasoning, architectural analysis, complex judgment |
-   For each component, recommend a model with reasoning.
+   | Capability Pattern | Model | Rationale |
   |-------------------|-------|-----------|
   | Simple display/fetch | `haiku` | Speed for mechanical tasks |
   | Most commands | `sonnet` | Balanced for workflows |
   | Code generation | `sonnet` | Good reasoning for code |
   | Deep analysis/review | `opus` | Complex judgment needed |
   | Read-only agents | `sonnet` | Standard agent work |
   | Architectural decisions | `opus` | High-stakes reasoning |
-5. **Generate files**: Create content using templates from capability-writing skill
+   Say something like:
   - "This seems like a simple display task - I recommend haiku for speed"
   - "This involves code generation - I recommend sonnet"
   - "This requires architectural analysis - I recommend opus"
-   Ensure proper inter-references:
+### Phase 4: Generate and Validate
-   - Command references skill via `@~/.claude/skills/name/SKILL.md`
+
-   - Agent lists skills in `skills:` frontmatter (names only, not paths)
+6. **Generate file content** using templates from capability-writing skill
-   - Command spawns agent via Task tool if agent is part of the set
+
 7. **Run validation checks** before showing preview:
   #### Frontmatter Validation
   | Check | Component | Rule |
   |-------|-----------|------|
   | Required fields | All | `name` for skills/agents, `description` for all |
   | Model value | All | Must be `haiku`, `sonnet`, or `opus` (or absent) |
   | Tools list | Agents | Only valid tool names: `Bash`, `Read`, `Write`, `Edit`, `Glob`, `Grep`, `Task`, `TodoWrite` |
   | Skills reference | Agents | Each skill in list must exist in `skills/*/SKILL.md` |
   #### Content Validation
   | Check | Component | Rule |
   |-------|-----------|------|
   | Trigger conditions | Skills | Description must explain when to use (not just what) |
   | Step instructions | Commands | Must have numbered steps with `**Step**:` format |
   | Behavior sections | Agents | Must have "When Invoked" or process section |
   | Skill references | Commands | `@~/.claude/skills/name/SKILL.md` paths must be valid |
   #### Convention Checks
   | Check | Rule |
   |-------|------|
   | Skill file name | Must be `SKILL.md` (uppercase) |
   | Command file name | Must be lowercase kebab-case |
   | Agent file name | Must be `AGENT.md` (uppercase) |
   | Directory structure | `skills/<name>/`, `commands/`, `agents/<name>/` |
   | No duplicates | Name must not match existing capability |
 8. **Check for anti-patterns** and warn:
   | Anti-pattern | Detection | Warning |
   |--------------|-----------|---------|
   | Trigger in body | Skill body contains "when to use" | "Move trigger conditions to description frontmatter" |
   | No tool restrictions | Read-only agent without `disallowedTools` | "Consider adding `disallowedTools: [Edit, Write]` for read-only agents" |
   | Missing skill refs | Command mentions domain without `@` reference | "Add explicit skill reference: `@~/.claude/skills/name/SKILL.md`" |
   | Overly broad tools | Agent allows all tools but does specific task | "Consider restricting tools to what's actually needed" |
   | Generic naming | Name like `utils`, `helper`, `misc` | "Use specific domain-focused naming" |
   | God capability | Single component handling multiple unrelated concerns | "Consider splitting into focused components" |
 ### Phase 5: Present and Confirm
 9. **Show validation results**:
 6. **Present for approval**: Show all generated files with their full content:
   ```
-   ## Generated Files
+   ## Validation Results
-   ### skills/name/SKILL.md
+   [PASS] Frontmatter: All required fields present
-   [full content]
+   [PASS] Model: sonnet is valid
   [WARN] Anti-pattern: Agent allows all tools but only reads files
         Recommendation: Add disallowedTools: [Edit, Write]
   [PASS] Conventions: File names follow patterns
   [PASS] No duplicates: Name is unique
-   ### commands/name.md
+   Proceed with warnings? (y/n)
   [full content]
   ### agents/name/AGENT.md (if applicable)
   [full content]
   Ready to create these files?
   ```
-7. **Create files** in correct locations after approval:
+10. **Show file preview** with full content:
    ```
    ## Files to Create
    ### skills/migration-review/SKILL.md
    ```yaml
    ---
    name: migration-review
    description: >
      Knowledge for reviewing database migrations...
    ---
    ```
    ### commands/review-migration.md
    ```yaml
    ---
    description: Review database migrations for safety and best practices
    ---
    ```
    ```
 11. **Ask for approval** (gate before file creation):
    - "Create these files? (y/n)"
    - If warnings exist: "There are warnings. Proceed anyway? (y/n)"
    - **If user declines**: Stop here. Offer to adjust the generated content or cancel.
    - **If user approves**: Proceed to Phase 6.
 ### Phase 6: Create Files
 **Only execute this phase after user approval in step 11.**
 12. **Create directories** if needed:
    ```bash
    mkdir -p skills/<name>
    mkdir -p agents/<name>
    ```
    If directory creation fails, report the error and stop.
 13. **Write files** to correct locations:
    - `skills/<name>/SKILL.md`
    - `commands/<name>.md`
    - `agents/<name>/AGENT.md`
-8. **Report success**:
+    If any file write fails, report which files were created and which failed.
 14. **Report success**:
    ```
-   ## Capability Created: name
+    ## Capability Created
    Files created:
-   - skills/name/SKILL.md
+    - skills/migration-review/SKILL.md
-   - commands/name.md
+    - commands/review-migration.md
   - agents/name/AGENT.md (if applicable)
    Next steps:
    1. Run `make install` to symlink to ~/.claude/
-   2. Test with: /name (for commands)
+    2. Test with: /review-migration
-   3. Skills will auto-activate based on context
+    3. Refine based on usage
    ```
 ## Validation Error Messages
 Provide clear, actionable error messages:
 | Error | Message |
 |-------|---------|
 | Missing name | "Skill requires `name` field in frontmatter" |
 | Invalid model | "Model must be `haiku`, `sonnet`, or `opus`. Got: `gpt-4`" |
 | Unknown tool | "Unknown tool `Search` in disallowedTools. Valid tools: Bash, Read, Write, Edit, Glob, Grep, Task, TodoWrite" |
 | Missing skill | "Agent references skill `foo` but `skills/foo/SKILL.md` does not exist" |
 | Invalid path | "Skill reference `@~/.claude/skills/bar/SKILL.md` invalid - directory `skills/bar/` not found" |
 | Duplicate name | "Capability `gitea` already exists at `skills/gitea/SKILL.md`" |
 | Wrong file name | "Skill file must be named `SKILL.md`, not `skill.md`" |
 ## Example Session
 ```
 User: /create-capability I want to add support for reviewing database migrations
 Claude: I'll help you create a migration review capability. Let me ask a few questions:
 1. Will this knowledge apply automatically when Claude sees migrations,
   or should users explicitly invoke it?
 User: Users should invoke it explicitly
 Claude: 2. Does this need isolated context for deep analysis, or can it work
   in the main conversation?
 User: Isolated would be good for complex migrations
 Claude: 3. Is this read-only analysis, or will it modify migration files?
 User: Just analysis, read-only
 Claude: Based on your answers, I recommend:
 - **Command**: `/review-migration` - Entry point for users
 - **Skill**: `migration-review` - Knowledge about safe migrations
 - **Agent**: `migration-reviewer` - Isolated analysis (read-only)
 For model selection:
 - Command: `sonnet` (standard workflow)
 - Agent: `sonnet` with `opus` upgrade path for complex cases
 Let me gather details for each component...
 [Continues with file generation, validation, and creation]
 ```
 ## Guidelines
- Follow all conventions from capability-writing skill
+- Always run full validation before showing preview
- Reference existing skills rather than duplicating knowledge
+- Show warnings but allow override with explicit confirmation
- Keep components focused - split if scope is too broad
+- Validate skill references exist before creating dependent components
- Commands should have approval checkpoints before significant actions
+- Suggest related existing skills that could be referenced
- Default to `sonnet` model unless there's a clear reason for haiku/opus
+- Keep generated content minimal - users can expand after testing
 - Skills should have descriptive `description` fields for auto-activation
--- a/commands/create-issue.md
+++ b/commands/create-issue.md
@@ -1,6 +1,5 @@
 ---
 description: Create a new Gitea issue. Can create single issues or batch create from a plan.
 model: haiku
 argument-hint: [title] or "batch"
 ---
--- a/commands/create-repo.md
+++ b/commands/create-repo.md
@@ -1,6 +1,5 @@
 ---
 description: Create a new repository with standard structure. Scaffolds vision.md, CLAUDE.md, and CI configuration.
 model: haiku
 argument-hint: <repo-name>
 context: fork
 ---
--- a/commands/dashboard.md
+++ b/commands/dashboard.md
@@ -1,88 +1,13 @@
 ---
 description: Show dashboard of open issues, PRs awaiting review, and CI status.
 # Model: haiku is sufficient for fetching and displaying data.
 # This command only reads from Gitea and formats output - no complex reasoning needed.
 model: haiku
 ---
 # Repository Dashboard
@~/.claude/skills/gitea/SKILL.md
-Fetch and display the following sections:
+Fetch and display:
 1. All open issues
 2. All open PRs
-## 1. Open Issues
+Format as tables showing number, title, and author.
 Run `tea issues` to list all open issues.
 Format as a table showing:
 - Number
 - Title
 - Author
 ## 2. Open Pull Requests
 Run `tea pulls` to list all open PRs.
 Format as a table showing:
 - Number
 - Title
 - Author
 ## 3. CI Status (Recent Workflow Runs)
 Run `tea actions runs` to list recent workflow runs.
 **Output formatting:**
 - Show the most recent 10 workflow runs maximum
 - For each run, display:
  - Status (use indicators: [SUCCESS], [FAILURE], [RUNNING], [PENDING])
  - Workflow name
  - Branch or PR reference
  - Commit (short SHA)
  - Triggered time
 **Highlighting:**
 - **Highlight failed runs** by prefixing with a warning indicator and ensuring they stand out visually
 - Example: "**[FAILURE]** build - PR #42 - abc1234 - 2h ago"
 **Handling repos without CI:**
 - If `tea actions runs` returns "No workflow runs found" or similar, display:
  "No CI workflows configured for this repository."
 - Do not treat this as an error - simply note it and continue
 ## Output Format
 Present each section with a clear header. Example:
 \`\`\`
 ## Open Issues (3)
 | #  | Title                  | Author |
 |----|------------------------|--------|
 | 15 | Fix login timeout      | alice  |
 | 12 | Add dark mode          | bob    |
 | 8  | Update documentation   | carol  |
 ## Open Pull Requests (2)
 | #  | Title                  | Author |
 |----|------------------------|--------|
 | 16 | Fix login timeout      | alice  |
 | 14 | Refactor auth module   | bob    |
 ## CI Status
 | Status      | Workflow | Branch/PR   | Commit  | Time    |
 |-------------|----------|-------------|---------|---------|
 | **[FAILURE]** | build    | PR #16      | abc1234 | 2h ago  |
 | [SUCCESS]   | build    | main        | def5678 | 5h ago  |
 | [SUCCESS]   | lint     | main        | def5678 | 5h ago  |
 \`\`\`
 If no CI is configured:
 \`\`\`
 ## CI Status
 No CI workflows configured for this repository.
 \`\`\`
--- a/commands/groom.md
+++ b/commands/groom.md
@@ -1,6 +1,5 @@
 ---
 description: Groom and improve issues. Without argument, reviews all open issues. With argument, grooms specific issue.
 model: sonnet
 argument-hint: [issue-number]
 ---
--- a/commands/improve.md
+++ b/commands/improve.md
@@ -1,6 +1,5 @@
 ---
 description: Identify improvement opportunities based on product vision. Analyzes gaps between vision goals and current backlog.
 model: sonnet
 argument-hint:
 context: fork
 ---
--- a/commands/manifesto.md
+++ b/commands/manifesto.md
@@ -1,6 +1,5 @@
 ---
 description: View and manage the organization manifesto. Shows identity, personas, beliefs, and principles.
 model: haiku
 argument-hint:
 ---
--- a/commands/plan-issues.md
+++ b/commands/plan-issues.md
@@ -1,6 +1,5 @@
 ---
 description: Plan and create issues for a feature or improvement. Breaks down work into well-structured issues with vision alignment.
 model: sonnet
 argument-hint: <feature-description>
 context: fork
 ---
@@ -17,24 +16,12 @@ context: fork
 3. **Identify job**: Which job to be done does this enable?
 4. **Understand the feature**: Analyze what "$1" involves
 5. **Explore the codebase** if needed to understand context
-
+6. **Break down** into discrete, actionable issues:
 6. **Discovery phase**: Before proposing issues, walk through the user workflow:
   - Who is the specific user?
   - What is their goal?
   - What is their step-by-step workflow to reach that goal?
   - What exists today?
   - Where does the workflow break or have gaps?
   - What's the MVP that delivers value?
   Present this as a workflow walkthrough before proposing any issues.
 7. **Break down** into discrete, actionable issues:
   - Derive issues from the workflow gaps identified in discovery
   - Each issue should be independently completable
   - Clear dependencies between issues
   - Appropriate scope (not too big, not too small)
-8. **Present the plan** (include vision alignment if vision exists):
+7. **Present the plan** (include vision alignment if vision exists):
   ```
   ## Proposed Issues for: $1
@@ -43,15 +30,12 @@ context: fork
   Supports: [Milestone/Goal name]
   1. [Title] - Brief description
      Addresses gap: [which workflow gap this solves]
      Dependencies: none
   2. [Title] - Brief description
      Addresses gap: [which workflow gap this solves]
      Dependencies: #1
   3. [Title] - Brief description
      Addresses gap: [which workflow gap this solves]
      Dependencies: #1, #2
   ```
@@ -61,7 +45,7 @@ context: fork
   - This should be added as a non-goal
   - Proceed anyway (with justification)
-9. **Ask for approval** before creating issues
+8. **Ask for approval** before creating issues
-10. **Create issues** in dependency order (blockers first)
+9. **Create issues** in dependency order (blockers first)
-11. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
+10. **Link dependencies** using `tea issues deps add <issue> <blocker>` for each dependency
-12. **Present summary** with links to created issues and dependency graph
+11. **Present summary** with links to created issues and dependency graph
--- a/commands/pr.md
+++ b/commands/pr.md
@@ -1,147 +0,0 @@
 ---
 description: Create a PR from current branch. Auto-generates title and description from branch name and commits.
 ---
 # Create Pull Request
@~/.claude/skills/gitea/SKILL.md
 Quick PR creation from current branch - lighter than full `/work-issue` flow for when you're already on a branch with commits.
 ## Prerequisites
 - Current branch is NOT main/master
 - Branch has commits ahead of main
 - Changes have been pushed to origin (or will be pushed)
 ## Process
 ### 1. Verify Branch State
 ```bash
 # Check current branch
 git branch --show-current
 # Ensure we're not on main
 # If on main, abort with message: "Cannot create PR from main branch"
 # Check for commits ahead of main
 git log main..HEAD --oneline
 ```
 ### 2. Push if Needed
 ```bash
 # Check if branch is tracking remote
 git status -sb
 # If not pushed or behind, push with upstream
 git push -u origin <branch-name>
 ```
 ### 3. Generate PR Title
 **Option A: Branch contains issue number** (e.g., `issue-42-add-feature`)
 Extract issue number and use format: `[Issue #<number>] <issue-title>`
 ```bash
 tea issues <number>  # Get the actual issue title
 ```
 **Option B: No issue number**
 Generate from branch name or recent commit messages:
 - Convert branch name from kebab-case to title case: `add-user-auth` -> `Add user auth`
 - Or use the most recent commit subject line
 ### 4. Generate PR Description
 Analyze the diff and commits to generate a description:
 ```bash
 # Get diff against main
 git diff main...HEAD --stat
 # Get commit messages
 git log main..HEAD --format="- %s"
 ```
 Structure the description:
 ```markdown
 ## Summary
 [1-2 sentences describing the overall change]
 ## Changes
 [Bullet points summarizing commits or key changes]
 [If issue linked: "Closes #<number>"]
 ```
 ### 5. Create PR
 Use tea CLI to create the PR:
 ```bash
 tea pulls create --title "<generated-title>" --description "<generated-description>"
 ```
 Capture the PR number from the output (e.g., "Pull Request #42 created").
 ### 6. Auto-review
 Inform the user that auto-review is starting, then spawn the `code-reviewer` agent in background:
 ```
 Task tool with:
  - subagent_type: "code-reviewer"
  - run_in_background: true
  - prompt: |
      Review PR #<PR_NUMBER> in the repository at <REPO_PATH>.
      1. Checkout the PR: tea pulls checkout <PR_NUMBER>
      2. Get the diff: git diff main...HEAD
      3. Analyze for code quality, bugs, security, style, test coverage
      4. Post structured review comment with tea comment
      5. Merge with rebase if LGTM, otherwise leave for user
 ```
 ### 7. Display Result
 Show the user:
 - PR URL/number
 - Generated title and description
 - Status of auto-review (spawned in background)
 ## Issue Linking
 To detect if branch is linked to an issue:
 1. Check branch name for patterns:
   - `issue-<number>-*`
   - `<number>-*`
   - `*-#<number>`
 2. If issue number found:
   - Fetch issue title from Gitea
   - Use `[Issue #N] <issue-title>` format for PR title
   - Add `Closes #N` to description
 ## Example Output
 ```
 Created PR #42: [Issue #15] Add /pr command
 ## Summary
 Adds /pr command for quick PR creation from current branch.
 ## Changes
 - Add commands/pr.md with auto-generation logic
 - Support issue linking from branch name
 Closes #15
 ---
 Auto-review started in background. Check status with: tea pulls 42 --comments
 ```
--- a/commands/retro.md
+++ b/commands/retro.md
@@ -1,6 +1,5 @@
 ---
 description: Run a retrospective on completed work. Captures insights as issues for later encoding into skills/commands/agents.
 model: haiku
 argument-hint: [task-description]
 ---
--- a/commands/review-pr.md
+++ b/commands/review-pr.md
@@ -1,6 +1,5 @@
 ---
 description: Review a Gitea pull request. Fetches PR details, diff, and comments. Includes both code review and software architecture review.
 model: sonnet
 argument-hint: <pr-number>
 ---
--- a/commands/roadmap.md
+++ b/commands/roadmap.md
@@ -1,9 +1,5 @@
 ---
 description: View current issues as a roadmap. Shows open issues organized by status and dependencies.
 # Model: haiku is sufficient for fetching and organizing issue data.
 # This command reads issues and dependencies, then displays them in categories.
 # Basic categorization logic doesn't require advanced reasoning.
 model: haiku
 argument-hint:
 ---
--- a/commands/spawn-issues.md
+++ b/commands/spawn-issues.md
@@ -1,6 +1,5 @@
 ---
 allowed-tools: Bash, Task, Read, TaskOutput
 model: haiku
 description: Orchestrate parallel issue implementation with review cycles
 argument-hint: <issue-number> [<issue-number>...]
 ---
--- a/commands/spawn-pr-fixes.md
+++ b/commands/spawn-pr-fixes.md
@@ -1,6 +1,5 @@
 ---
 allowed-tools: Bash, Task, Read
 model: haiku
 description: Spawn parallel background agents to address PR review feedback
 argument-hint: [pr-number...]
 ---
--- a/commands/update-claude-md.md
+++ b/commands/update-claude-md.md
@@ -1,6 +1,5 @@
 ---
 description: Update or create CLAUDE.md with current project context. Explores the project and ensures organization context is present.
 model: haiku
 argument-hint:
 context: fork
 ---
--- a/commands/vision.md
+++ b/commands/vision.md
@@ -1,6 +1,5 @@
 ---
 description: View the product vision and goal progress. Manages vision.md and Gitea milestones.
 model: haiku
 argument-hint: [goals]
 ---
--- a/commands/work-issue.md
+++ b/commands/work-issue.md
@@ -1,6 +1,5 @@
 ---
 description: Work on a Gitea issue. Fetches issue details and sets up branch for implementation.
 model: haiku
 argument-hint: <issue-number>
 ---
--- a/skills/backlog-grooming/SKILL.md
+++ b/skills/backlog-grooming/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: backlog-grooming
 model: haiku
 description: Review and improve existing issues for clarity and actionability. Use when grooming the backlog, reviewing issue quality, cleaning up stale issues, or when the user wants to improve existing issues.
 user-invocable: false
 ---
--- a/skills/capability-writing/SKILL.md
+++ b/skills/capability-writing/SKILL.md
@@ -133,7 +133,7 @@ Location: `commands/<name>.md`
 ---
 description: What this command does (one-line summary)
 argument-hint: <required> [optional]
-model: haiku
+model: sonnet
 ---
 # Command Title
@@ -165,7 +165,7 @@ Location: `agents/<name>/AGENT.md`
 ---
 name: agent-name
 description: What this agent does and when to spawn it
-model: haiku
+model: sonnet
 skills: skill1, skill2
 disallowedTools:
  - Edit
--- a/skills/claude-md-writing/SKILL.md
+++ b/skills/claude-md-writing/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: claude-md-writing
 model: haiku
 description: Write effective CLAUDE.md files that give AI assistants the context they need. Use when creating new repos, improving existing CLAUDE.md files, or setting up projects.
 user-invocable: false
 ---
--- a/skills/code-review/SKILL.md
+++ b/skills/code-review/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: code-review
 model: haiku
 description: Review code for quality, bugs, security, and style issues. Use when reviewing pull requests, checking code quality, looking for bugs or security vulnerabilities, or when the user asks for a code review.
 user-invocable: false
 ---
--- a/skills/gitea/SKILL.md
+++ b/skills/gitea/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: gitea
 model: haiku
 description: View, create, and manage Gitea issues and pull requests using tea CLI. Use when working with issues, PRs, viewing issue details, creating pull requests, adding comments, merging PRs, or when the user mentions tea, gitea, issue numbers, or PR numbers.
 user-invocable: false
 ---
--- a/skills/issue-writing/SKILL.md
+++ b/skills/issue-writing/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: issue-writing
 model: haiku
 description: Write clear, actionable issues with proper structure and acceptance criteria. Use when creating issues, writing bug reports, feature requests, or when the user needs help structuring an issue.
 user-invocable: false
 ---
--- a/skills/repo-conventions/SKILL.md
+++ b/skills/repo-conventions/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: repo-conventions
 model: haiku
 description: Standard structure and conventions for Flowmade repositories. Use when creating new repos, reviewing repo structure, or setting up projects.
 user-invocable: false
 ---
--- a/skills/roadmap-planning/SKILL.md
+++ b/skills/roadmap-planning/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: roadmap-planning
 model: haiku
 description: Plan features and break down work into implementable issues. Use when planning a feature, creating a roadmap, breaking down large tasks, or when the user needs help organizing work into issues.
 user-invocable: false
 ---
@@ -16,33 +15,7 @@ How to plan features and create issues for implementation.
 - Who benefits and how?
 - What's the success criteria?
-### 2. Discovery Phase
+### 2. Break Down the Work
 Before breaking down work into issues, understand the user's workflow:
 | Question | Why It Matters |
 |----------|----------------|
 | **Who** is the user? | Specific persona, not "users" |
 | **What's their goal?** | The job they're trying to accomplish |
 | **What's their workflow?** | Step-by-step actions to reach the goal |
 | **What exists today?** | Current state and gaps |
 | **What's the MVP?** | Minimum to deliver value |
 **Walk through the workflow step by step:**
 1. User starts at: [starting point]
 2. User does: [action 1]
 3. System responds: [what happens]
 4. User does: [action 2]
 5. ... continue until goal is reached
 **Identify the gaps:**
 - Where does the workflow break today?
 - Which steps are missing or painful?
 - What's the smallest change that unblocks value?
 **Derive issues from workflow gaps** - not from guessing what might be needed. Each issue should address a specific gap in the user's workflow.
 ### 3. Break Down the Work
 - Identify distinct components
 - Define boundaries between pieces
 - Aim for issues that are:
@@ -50,12 +23,12 @@ Before breaking down work into issues, understand the user's workflow:
  - Independently testable
  - Clear in scope
-### 4. Identify Dependencies
+### 3. Identify Dependencies
 - Which pieces must come first?
 - What can be parallelized?
 - Are there external blockers?
-### 5. Create Issues
+### 4. Create Issues
 - Follow issue-writing patterns
 - Reference dependencies explicitly
 - Use consistent labeling
--- a/skills/software-architecture/SKILL.md
+++ b/skills/software-architecture/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: software-architecture
 model: haiku
 description: >
  Architectural patterns for building systems: DDD, Event Sourcing, event-driven communication.
  Use when implementing features, reviewing code, planning issues, refining architecture,
--- a/skills/vision-management/SKILL.md
+++ b/skills/vision-management/SKILL.md
@@ -1,6 +1,5 @@
 ---
 name: vision-management
 model: haiku
 description: Create, maintain, and evolve organization manifesto and product visions. Use when working with manifesto.md, vision.md, milestones, or aligning work with organizational direction.
 user-invocable: false
 ---