@opendash-ai/cli 0.1.0-beta.1

package/src/skill/compose/.bundle/feedback/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: compose:feedback
+hidden: true
+description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (sycophantic, not technical)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions through `compose:ask`, presenting interpretations as options. If no user is available, take your best interpretation and proceed.
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification through `compose:ask`, presenting your interpretations as options. If no user is available, take the most reasonable interpretation and proceed.
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+your human partner: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+❌ WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+✅ RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From your human partner
+- **Trusted** - implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with your human partner's prior decisions:
+  Stop and discuss with your human partner first
+```
+
+**your human partner's rule:** "External feedback - be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**your human partner's rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with your human partner's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve your human partner if architectural
+
+**Signal if uncomfortable pushing back out loud:** "Strange things are afoot at the Circle K"
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+✅ "Fixed. [Brief description of what changed]"
+✅ "Good catch - [specific issue]. Fixed in [location]."
+✅ [Just fix it and show in the code]
+
+❌ "You're absolutely right!"
+❌ "Great point!"
+❌ "Thanks for catching that!"
+❌ "Thanks for [anything]"
+❌ ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+**If you catch yourself about to write "Thanks":** DELETE IT. State the fix instead.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+✅ "You were right - I checked [X] and it does [Y]. Implementing now."
+✅ "Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+❌ Long apology
+❌ Defending why you pushed back
+❌ Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## Real Examples
+
+**Performative Agreement (Bad):**
+```
+Reviewer: "Remove legacy code"
+❌ "You're absolutely right! Let me remove that..."
+```
+
+**Technical Verification (Good):**
+```
+Reviewer: "Remove legacy code"
+✅ "Checking... build target is 10.15+, this API needs 13+. Need legacy for backward compat. Current impl has wrong bundle ID - fix it or drop pre-13 support?"
+```
+
+**YAGNI (Good):**
+```
+Reviewer: "Implement proper metrics tracking with database, date filters, CSV export"
+✅ "Grepped codebase - nothing calls this endpoint. Remove it (YAGNI)? Or is there usage I'm missing?"
+```
+
+**Unclear Item (Good):**
+```
+your human partner: "Fix items 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+✅ "Understand 1,2,3,6. Need clarification on 4 and 5 before implementing."
+```
+
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/src/skill/compose/.bundle/merge/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: compose:merge
+hidden: true
+description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup
+---
+
+# Finishing a Development Branch
+
+## Overview
+
+Guide completion of development work by presenting clear options and handling chosen workflow.
+
+**Core principle:** Verify tests → Detect environment → Present options → Execute choice → Clean up.
+
+**Announce at start:** "I'm using the compose:merge skill to complete this work."
+
+## The Process
+
+### Step 1: Verify Tests
+
+**Before presenting options, verify tests pass:**
+
+```bash
+# Run project's test suite
+npm test / cargo test / pytest / go test ./...
+```
+
+**If tests fail:**
+```
+Tests failing (<N> failures). Must fix before completing:
+
+[Show failures]
+
+Cannot proceed with merge/PR until tests pass.
+```
+
+Stop. Don't proceed to Step 2.
+
+**If tests pass:** Continue to Step 2.
+
+### Step 2: Detect Environment
+
+**Determine workspace state before presenting options:**
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+```
+
+This determines which menu to show and how cleanup works:
+
+| State | Menu | Cleanup |
+|-------|------|---------|
+| `GIT_DIR == GIT_COMMON` (normal repo) | Standard 4 options | No worktree to clean up |
+| `GIT_DIR != GIT_COMMON`, named branch | Standard 4 options | Provenance-based (see Step 6) |
+| `GIT_DIR != GIT_COMMON`, detached HEAD | Reduced 3 options (no merge) | No cleanup (externally managed) |
+
+### Step 3: Determine Base Branch
+
+```bash
+# Try common base branches
+git merge-base HEAD main 2>/dev/null || git merge-base HEAD master 2>/dev/null
+```
+
+If the base branch is ambiguous, confirm through `compose:ask`:
+- header: `Base Branch`
+- question: `This branch appears to have split from <detected>. Correct?`
+- options:
+  - label: `Yes, <detected>`, description: `Use <detected> as merge target`
+  - label: `Different branch`, description: `I'll specify the correct base branch`
+
+If no user is available, use the detected base branch and proceed.
+
+### Step 4: Present Options
+
+**Normal repo / named-branch worktree — use `compose:ask`:**
+- header: `Complete Work`
+- question: `Implementation complete. What would you like to do?`
+- options:
+  - label: `Merge locally`, description: `Merge back to <base-branch>`
+  - label: `Create PR`, description: `Push branch and open a Pull Request`
+  - label: `Keep as-is`, description: `Leave the branch — I'll handle it later`
+  - label: `Discard`, description: `Delete branch and all commits`
+
+If no user is available, merge locally and proceed.
+
+**Detached HEAD — use `compose:ask`:**
+- header: `Complete Work`
+- question: `Implementation complete (detached HEAD, externally managed). What would you like to do?`
+- options:
+  - label: `Create PR`, description: `Push as new branch and open a PR`
+  - label: `Keep as-is`, description: `Leave as-is — I'll handle it later`
+  - label: `Discard`, description: `Delete this work permanently`
+
+If no user is available, create a PR and proceed.
+
+### Step 5: Execute Choice
+
+#### Option 1: Merge Locally
+
+```bash
+# Get main repo root for CWD safety
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+
+# Merge first — verify success before removing anything
+git checkout <base-branch>
+git pull
+git merge <feature-branch>
+
+# Verify tests on merged result
+<test command>
+
+# Only after merge succeeds: cleanup worktree (Step 6), then delete branch
+```
+
+Then: Cleanup worktree (Step 6), then delete branch:
+
+```bash
+git branch -d <feature-branch>
+```
+
+#### Option 2: Push and Create PR
+
+```bash
+# Push branch
+git push -u origin <feature-branch>
+
+# Create PR
+gh pr create --title "<title>" --body "$(cat <<'EOF'
+## Summary
+<2-3 bullets of what changed>
+
+## Test Plan
+- [ ] <verification steps>
+EOF
+)"
+```
+
+**Do NOT clean up worktree** — user needs it alive to iterate on PR feedback.
+
+#### Option 3: Keep As-Is
+
+Report: "Keeping branch <name>. Worktree preserved at <path>."
+
+**Don't cleanup worktree.**
+
+#### Option 4: Discard
+
+**Confirm through `compose:ask`:**
+- header: `Confirm Discard`
+- question: `This will permanently delete branch <name>, all commits, and worktree at <path>. Are you sure?`
+- options:
+  - label: `Cancel`, description: `Keep branch and worktree intact`
+  - label: `Discard permanently`, description: `Cannot be undone`
+
+If no user is available, do NOT discard — keep the branch as-is. (Destructive actions never auto-approve; see `compose:ask`.)
+
+Only proceed if user selected "Discard permanently". If "Cancel", return to Step 4.
+
+If confirmed:
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+```
+
+Then: Cleanup worktree (Step 6), then force-delete branch:
+```bash
+git branch -D <feature-branch>
+```
+
+### Step 6: Cleanup Workspace
+
+**Only runs for Options 1 and 4.** Options 2 and 3 always preserve the worktree.
+
+```bash
+GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
+GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
+WORKTREE_PATH=$(git rev-parse --show-toplevel)
+```
+
+**If `GIT_DIR == GIT_COMMON`:** Normal repo, no worktree to clean up. Done.
+
+**If worktree path is under `.worktrees/`, `worktrees/`, or `~/.config/compose/worktrees/`:** Compose created this worktree — we own cleanup.
+
+```bash
+MAIN_ROOT=$(git -C "$(git rev-parse --git-common-dir)/.." rev-parse --show-toplevel)
+cd "$MAIN_ROOT"
+git worktree remove "$WORKTREE_PATH"
+git worktree prune  # Self-healing: clean up any stale registrations
+```
+
+**Otherwise:** The host environment (harness) owns this workspace. Do NOT remove it. If your platform provides a workspace-exit tool, use it. Otherwise, leave the workspace in place.
+
+## Quick Reference
+
+| Option | Merge | Push | Keep Worktree | Cleanup Branch |
+|--------|-------|------|---------------|----------------|
+| 1. Merge locally | yes | - | - | yes |
+| 2. Create PR | - | yes | yes | - |
+| 3. Keep as-is | - | - | yes | - |
+| 4. Discard | - | - | - | yes (force) |
+
+## Common Mistakes
+
+**Skipping test verification**
+- **Problem:** Merge broken code, create failing PR
+- **Fix:** Always verify tests before offering options
+
+**Open-ended questions**
+- **Problem:** "What should I do next?" is ambiguous
+- **Fix:** Present exactly 4 structured options (or 3 for detached HEAD)
+
+**Cleaning up worktree for Option 2**
+- **Problem:** Remove worktree user needs for PR iteration
+- **Fix:** Only cleanup for Options 1 and 4
+
+**Deleting branch before removing worktree**
+- **Problem:** `git branch -d` fails because worktree still references the branch
+- **Fix:** Merge first, remove worktree, then delete branch
+
+**Running git worktree remove from inside the worktree**
+- **Problem:** Command fails silently when CWD is inside the worktree being removed
+- **Fix:** Always `cd` to main repo root before `git worktree remove`
+
+**Cleaning up harness-owned worktrees**
+- **Problem:** Removing a worktree the harness created causes phantom state
+- **Fix:** Only clean up worktrees under `.worktrees/`, `worktrees/`, or `~/.config/compose/worktrees/`
+
+**No confirmation for discard**
+- **Problem:** Accidentally delete work
+- **Fix:** Require typed "discard" confirmation
+
+## Red Flags
+
+**Never:**
+- Proceed with failing tests
+- Merge without verifying tests on result
+- Delete work without confirmation
+- Force-push without explicit request
+- Remove a worktree before confirming merge success
+- Clean up worktrees you didn't create (provenance check)
+- Run `git worktree remove` from inside the worktree
+
+**Always:**
+- Verify tests before offering options
+- Detect environment before presenting menu
+- Present exactly 4 options (or 3 for detached HEAD)
+- Get typed confirmation for Option 4
+- Clean up worktree for Options 1 & 4 only
+- `cd` to main repo root before worktree removal
+- Run `git worktree prune` after removal

package/src/skill/compose/.bundle/new-skill/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: compose:new-skill
+hidden: true
+description: Use when creating new skills or editing existing skills for the project or personal skill library
+---
+
+# Writing Skills
+
+## Overview
+
+A **skill** is a reusable reference guide — techniques, patterns, or tools — that helps agents find and apply effective approaches.
+
+**Skills are:** Reusable techniques, patterns, tools, reference guides
+
+**Skills are NOT:** Narratives about how you solved a problem once
+
+## When to Create a Skill
+
+**Create when:**
+- Technique wasn't intuitively obvious
+- You'd reference this again across projects
+- Pattern applies broadly (not project-specific)
+- Others would benefit from this knowledge
+
+**Don't create for:**
+- One-off solutions
+- Standard practices well-documented elsewhere
+- Project-specific conventions (put in project config like CLAUDE.md)
+- Mechanical constraints enforceable with regex/validation (automate it instead)
+
+## Skill Types
+
+| Type | Purpose | Examples |
+|------|---------|----------|
+| **Technique** | Concrete method with steps | condition-based-waiting, root-cause-tracing |
+| **Pattern** | Way of thinking about problems | flatten-with-flags, test-invariants |
+| **Reference** | API docs, syntax guides | tool documentation, library guides |
+
+## SKILL.md Format
+
+```markdown
+---
+name: skill-name
+description: Use when [specific triggering conditions]
+---
+
+# Skill Name
+
+## Overview
+Core principle in 1-2 sentences.
+
+## When to Use
+Bullet list with symptoms and use cases.
+When NOT to use.
+
+## Core Pattern
+Before/after code comparison or step-by-step process.
+
+## Quick Reference
+Table or bullets for scanning common operations.
+
+## Common Mistakes
+What goes wrong + fixes.
+```
+
+### Frontmatter Rules
+
+- `name`: letters, numbers, hyphens only (max 64 chars)
+- `description`: third-person, starts with "Use when...", max 1024 chars
+- Description should ONLY describe triggering conditions — never summarize the skill's workflow
+
+### Description: Why This Matters
+
+Testing revealed that when a description summarizes the skill's workflow, agents may follow the description instead of reading the full skill content. A description saying "code review between tasks" caused the agent to do ONE review, even though the skill's flowchart clearly showed TWO reviews.
+
+**The trap:** Descriptions that summarize workflow create a shortcut the agent will take. The skill body becomes documentation it skips.
+
+```yaml
+# BAD: summarizes workflow — agent may follow this instead of reading skill
+description: Use when executing plans - dispatches subagent per task with code review
+
+# BAD: too much process detail
+description: Use for TDD - write test first, watch it fail, write minimal code, refactor
+
+# GOOD: just triggering conditions
+description: Use when executing implementation plans with independent tasks
+
+# GOOD: symptoms-focused
+description: Use when tests have race conditions, timing dependencies, or pass/fail inconsistently
+```
+
+### Writing Style
+
+```yaml
+# BAD: first person
+description: I can help you with async tests when they're flaky
+
+# BAD: too abstract, doesn't include when to use
+description: For async testing
+
+# GOOD: third person, starts with "Use when"
+description: Use when implementing any feature or bugfix, before writing implementation code
+```
+
+## Skill Discovery Optimization (SDO)
+
+Agents read descriptions to decide which skills to load. Make it answer: "Should I read this skill right now?"
+
+### Keyword Coverage
+
+Use words agents would search for:
+- Error messages: "Hook timed out", "ENOTEMPTY", "race condition"
+- Symptoms: "flaky", "hanging", "zombie", "pollution"
+- Synonyms: "timeout/hang/freeze", "cleanup/teardown/afterEach"
+- Tools: Actual commands, library names, file types
+
+### Descriptive Naming
+
+Use active voice, verb-first:
+- `condition-based-waiting` not `async-test-helpers`
+- `creating-skills` not `skill-creation`
+- `root-cause-tracing` not `debugging-techniques`
+
+## Directory Structure
+
+```
+skills/
+  skill-name/
+    SKILL.md              # Main reference (required)
+    supporting-file.*     # Only if needed
+```
+
+**Keep inline:** Principles, concepts, code patterns (short examples).
+
+**Separate files for:**
+1. Heavy reference (100+ lines) — API docs, comprehensive syntax
+2. Reusable tools — Scripts, utilities, templates
+
+## Skill Location
+
+Personal skills: `.opendash/skills/<name>/SKILL.md`
+
+## Token Efficiency
+
+Skills load into context — every token counts.
+
+**Target word counts:**
+- Frequently-loaded skills: < 200 words total
+- Other skills: < 500 words (still be concise)
+
+**Techniques:**
+
+```markdown
+# BAD: Document all flags inline
+search-conversations supports --text, --both, --after DATE, --before DATE
+
+# GOOD: Reference --help
+search-conversations supports multiple modes and filters. Run --help for details.
+```
+
+```markdown
+# BAD: Repeat instructions from another skill
+When searching, dispatch subagent with template...
+[20 lines of repeated instructions]
+
+# GOOD: Cross-reference
+Always use subagents (50-100x context savings). REQUIRED: Use [other-skill-name] for workflow.
+```
+
+**Cross-referencing:** Use skill name only with explicit markers:
+- `**REQUIRED BACKGROUND:** You MUST understand compose:tdd`
+- `**REQUIRED SUB-SKILL:** Use eslint-setup`
+- Never use `@` links (force-loads files, burns context)
+
+## Code Examples
+
+**One excellent example beats many mediocre ones.** Choose the most relevant language:
+- Testing techniques → TypeScript/JavaScript
+- System debugging → Shell/Python
+- Data processing → Python
+
+Don't implement in 5+ languages. Don't create fill-in-the-blank templates.
+
+## Testing
+
+Before deploying, verify the skill works:
+
+1. Run a realistic scenario WITHOUT the skill — observe baseline behavior
+2. Run the same scenario WITH the skill — verify improvement
+3. If the skill enforces discipline, test under pressure (time + sunk cost + fatigue)
+
+For discipline-enforcing skills (TDD, verification requirements), watch for rationalization:
+
+| Excuse | Reality |
+|--------|---------|
+| "Too simple to test" | Simple code breaks. Test takes 30 seconds. |
+| "I'll test after" | Tests passing immediately prove nothing. |
+| "The skill is obviously clear" | Clear to you ≠ clear to other agents. |
+
+**REQUIRED BACKGROUND:** Use compose:tdd principles for testing discipline-enforcing skills.
+
+## Checklist
+
+- [ ] Name uses only letters, numbers, hyphens
+- [ ] Description starts with "Use when..." (third person, no workflow summary)
+- [ ] Keywords throughout for search (errors, symptoms, tools)
+- [ ] Content is concise — SKILL.md under 500 lines
+- [ ] One excellent example (not multi-language)
+- [ ] Tested with realistic scenarios
+- [ ] No redundant explanations of what the agent already knows
+- [ ] Supporting files only for tools or heavy reference