@every-env/compound-plugin 0.1.1 → 0.3.0

package/plugins/compound-engineering/skills/create-agent-skills/references/skill-structure.md

@@ -1,372 +1,152 @@
-<overview>
-Skills have three structural components: YAML frontmatter (metadata), pure XML body structure (content organization), and progressive disclosure (file organization). This reference defines requirements and best practices for each component.
-</overview>
-
-<xml_structure_requirements>
-<critical_rule>
-**Remove ALL markdown headings (#, ##, ###) from skill body content.** Replace with semantic XML tags. Keep markdown formatting WITHIN content (bold, italic, lists, code blocks, links).
-</critical_rule>
-
-<required_tags>
-Every skill MUST have these three tags:
-
-- **`<objective>`** - What the skill does and why it matters (1-3 paragraphs)
-- **`<quick_start>`** - Immediate, actionable guidance (minimal working example)
-- **`<success_criteria>`** or **`<when_successful>`** - How to know it worked
-</required_tags>
-
-<conditional_tags>
-Add based on skill complexity and domain requirements:
-
-- **`<context>`** - Background/situational information
-- **`<workflow>` or `<process>`** - Step-by-step procedures
-- **`<advanced_features>`** - Deep-dive topics (progressive disclosure)
-- **`<validation>`** - How to verify outputs
-- **`<examples>`** - Multi-shot learning
-- **`<anti_patterns>`** - Common mistakes to avoid
-- **`<security_checklist>`** - Non-negotiable security patterns
-- **`<testing>`** - Testing workflows
-- **`<common_patterns>`** - Code examples and recipes
-- **`<reference_guides>` or `<detailed_references>`** - Links to reference files
-
-See [use-xml-tags.md](use-xml-tags.md) for detailed guidance on each tag.
-</conditional_tags>
-
-<tag_selection_intelligence>
-**Simple skills** (single domain, straightforward):
-- Required tags only
-- Example: Text extraction, file format conversion
-
-**Medium skills** (multiple patterns, some complexity):
-- Required tags + workflow/examples as needed
-- Example: Document processing with steps, API integration
-
-**Complex skills** (multiple domains, security, APIs):
-- Required tags + conditional tags as appropriate
-- Example: Payment processing, authentication systems, multi-step workflows
-</tag_selection_intelligence>
-
-<xml_nesting>
-Properly nest XML tags for hierarchical content:
-
-```xml
-<examples>
-<example number="1">
-<input>User input</input>
-<output>Expected output</output>
-</example>
-</examples>
-```
+# Skill Structure Reference
 
-Always close tags:
-```xml
-<objective>
-Content here
-</objective>
-```
-</xml_nesting>
+Skills have three structural components: YAML frontmatter (metadata), standard markdown body (content), and progressive disclosure (file organization).
 
-<tag_naming_conventions>
-Use descriptive, semantic names:
-- `<workflow>` not `<steps>`
-- `<success_criteria>` not `<done>`
-- `<anti_patterns>` not `<dont_do>`
+## Body Format
 
-Be consistent within your skill. If you use `<workflow>`, don't also use `<process>` for the same purpose (unless they serve different roles).
-</tag_naming_conventions>
-</xml_structure_requirements>
+Use **standard markdown headings** for structure. Keep markdown formatting within content (bold, italic, lists, code blocks, links).
 
-<yaml_requirements>
-<required_fields>
-```yaml
+```markdown
 ---
-name: skill-name-here
-description: What it does and when to use it (third person, specific triggers)
+name: my-skill
+description: What it does and when to use it
 ---
-```
-</required_fields>
-
-<name_field>
-**Validation rules**:
-- Maximum 64 characters
-- Lowercase letters, numbers, hyphens only
-- No XML tags
-- No reserved words: "anthropic", "claude"
-- Must match directory name exactly
-
-**Examples**:
-- ✅ `process-pdfs`
-- ✅ `manage-facebook-ads`
-- ✅ `setup-stripe-payments`
-- ❌ `PDF_Processor` (uppercase)
-- ❌ `helper` (vague)
-- ❌ `claude-helper` (reserved word)
-</name_field>
-
-<description_field>
-**Validation rules**:
-- Non-empty, maximum 1024 characters
-- No XML tags
-- Third person (never first or second person)
-- Include what it does AND when to use it
-
-**Critical rule**: Always write in third person.
-- ✅ "Processes Excel files and generates reports"
-- ❌ "I can help you process Excel files"
-- ❌ "You can use this to process Excel files"
 
-**Structure**: Include both capabilities and triggers.
-
-**Effective examples**:
-```yaml
-description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
-```
+# Skill Name
 
-```yaml
-description: Analyze Excel spreadsheets, create pivot tables, generate charts. Use when analyzing Excel files, spreadsheets, tabular data, or .xlsx files.
-```
+## Quick Start
+Immediate actionable guidance...
 
-```yaml
-description: Generate descriptive commit messages by analyzing git diffs. Use when the user asks for help writing commit messages or reviewing staged changes.
-```
+## Instructions
+Step-by-step procedures...
 
-**Avoid**:
-```yaml
-description: Helps with documents
-```
+## Examples
+Concrete usage examples...
 
-```yaml
-description: Processes data
+## Guidelines
+Rules and constraints...
 ```
-</description_field>
-</yaml_requirements>
 
-<naming_conventions>
-Use **verb-noun convention** for skill names:
+## Recommended Sections
 
-<pattern name="create">
-Building/authoring tools
+Every skill should have:
 
-Examples: `create-agent-skills`, `create-hooks`, `create-landing-pages`
-</pattern>
+- **Quick Start** - Immediate, actionable guidance (minimal working example)
+- **Instructions** - Core step-by-step guidance
+- **Success Criteria** - How to know it worked
 
-<pattern name="manage">
-Managing external services or resources
+Add based on complexity:
 
-Examples: `manage-facebook-ads`, `manage-zoom`, `manage-stripe`, `manage-supabase`
-</pattern>
+- **Context** - Background/situational information
+- **Workflow** - Multi-step procedures
+- **Examples** - Concrete input/output pairs
+- **Advanced Features** - Deep-dive topics (link to reference files)
+- **Anti-Patterns** - Common mistakes to avoid
+- **Guidelines** - Rules and constraints
 
-<pattern name="setup">
-Configuration/integration tasks
-
-Examples: `setup-stripe-payments`, `setup-meta-tracking`
-</pattern>
-
-<pattern name="generate">
-Generation tasks
-
-Examples: `generate-ai-images`
-</pattern>
-
-<avoid_patterns>
-- Vague: `helper`, `utils`, `tools`
-- Generic: `documents`, `data`, `files`
-- Reserved words: `anthropic-helper`, `claude-tools`
-- Inconsistent: Directory `facebook-ads` but name `facebook-ads-manager`
-</avoid_patterns>
-</naming_conventions>
-
-<progressive_disclosure>
-<principle>
-SKILL.md serves as an overview that points to detailed materials as needed. This keeps context window usage efficient.
-</principle>
-
-<practical_guidance>
-- Keep SKILL.md body under 500 lines
-- Split content into separate files when approaching this limit
-- Keep references one level deep from SKILL.md
-- Add table of contents to reference files over 100 lines
-</practical_guidance>
+## YAML Frontmatter
 
-<pattern name="high_level_guide">
-Quick start in SKILL.md, details in reference files:
+### Required/Recommended Fields
 
-```markdown
+```yaml
 ---
-name: pdf-processing
-description: Extracts text and tables from PDF files, fills forms, and merges documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+name: skill-name-here
+description: What it does and when to use it (specific triggers included)
 ---
-
-<objective>
-Extract text and tables from PDF files, fill forms, and merge documents using Python libraries.
-</objective>
-
-<quick_start>
-Extract text with pdfplumber:
-
-```python
-import pdfplumber
-with pdfplumber.open("file.pdf") as pdf:
-    text = pdf.pages[0].extract_text()
-```
-</quick_start>
-
-<advanced_features>
-**Form filling**: See [forms.md](forms.md)
-**API reference**: See [reference.md](reference.md)
-</advanced_features>
 ```
 
-Claude loads forms.md or reference.md only when needed.
-</pattern>
+### Name Field
 
-<pattern name="domain_organization">
-For skills with multiple domains, organize by domain to avoid loading irrelevant context:
-
-```
-bigquery-skill/
-├── SKILL.md (overview and navigation)
-└── reference/
-    ├── finance.md (revenue, billing metrics)
-    ├── sales.md (opportunities, pipeline)
-    ├── product.md (API usage, features)
-    └── marketing.md (campaigns, attribution)
-```
+**Validation rules:**
+- Maximum 64 characters
+- Lowercase letters, numbers, hyphens only
+- Must match directory name
+- No reserved words: "anthropic", "claude"
 
-When user asks about revenue, Claude reads only finance.md. Other files stay on filesystem consuming zero tokens.
-</pattern>
+**Examples:**
+- `triage-prs`
+- `deploy-production`
+- `review-code`
+- `setup-stripe-payments`
 
-<pattern name="conditional_details">
-Show basic content in SKILL.md, link to advanced in reference files:
+**Avoid:** `helper`, `utils`, `tools`, generic names
 
-```xml
-<objective>
-Process DOCX files with creation and editing capabilities.
-</objective>
+### Description Field
 
-<quick_start>
-<creating_documents>
-Use docx-js for new documents. See [docx-js.md](docx-js.md).
-</creating_documents>
+**Validation rules:**
+- Maximum 1024 characters
+- Include what it does AND when to use it
+- Third person voice
 
-<editing_documents>
-For simple edits, modify XML directly.
+**Good:**
+```yaml
+description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
+```
 
-**For tracked changes**: See [redlining.md](redlining.md)
-**For OOXML details**: See [ooxml.md](ooxml.md)
-</editing_documents>
-</quick_start>
+**Bad:**
+```yaml
+description: Helps with documents
 ```
 
-Claude reads redlining.md or ooxml.md only when the user needs those features.
-</pattern>
+### Optional Fields
 
-<critical_rules>
-**Keep references one level deep**: All reference files should link directly from SKILL.md. Avoid nested references (SKILL.md → advanced.md → details.md) as Claude may only partially read deeply nested files.
+| Field | Description |
+|-------|-------------|
+| `argument-hint` | Usage hints. Example: `[issue-number]` |
+| `disable-model-invocation` | `true` to prevent auto-loading. Use for side-effect workflows. |
+| `user-invocable` | `false` to hide from `/` menu. Use for background knowledge. |
+| `allowed-tools` | Tools without permission prompts. Example: `Read, Bash(git *)` |
+| `model` | `haiku`, `sonnet`, or `opus` |
+| `context` | `fork` for isolated subagent execution |
+| `agent` | Subagent type: `Explore`, `Plan`, `general-purpose`, or custom |
 
-**Add table of contents to long files**: For reference files over 100 lines, include a table of contents at the top.
+## Naming Conventions
 
-**Use pure XML in reference files**: Reference files should also use pure XML structure (no markdown headings in body).
-</critical_rules>
-</progressive_disclosure>
+Use descriptive names that indicate purpose:
 
-<file_organization>
-<filesystem_navigation>
-Claude navigates your skill directory using bash commands:
+| Pattern | Examples |
+|---------|----------|
+| Action-oriented | `triage-prs`, `deploy-production`, `review-code` |
+| Domain-specific | `setup-stripe-payments`, `manage-facebook-ads` |
+| Descriptive | `git-worktree`, `frontend-design`, `dhh-rails-style` |
 
-- Use forward slashes: `reference/guide.md` (not `reference\guide.md`)
-- Name files descriptively: `form_validation_rules.md` (not `doc2.md`)
-- Organize by domain: `reference/finance.md`, `reference/sales.md`
-</filesystem_navigation>
+## Progressive Disclosure
 
-<directory_structure>
-Typical skill structure:
+Keep SKILL.md under 500 lines. Split into reference files:
 
 ```
-skill-name/
-├── SKILL.md (main entry point, pure XML structure)
-├── references/ (optional, for progressive disclosure)
-│   ├── guide-1.md (pure XML structure)
-│   ├── guide-2.md (pure XML structure)
-│   └── examples.md (pure XML structure)
-└── scripts/ (optional, for utility scripts)
-    ├── validate.py
-    └── process.py
-```
-</directory_structure>
-</file_organization>
-
-<anti_patterns>
-<pitfall name="markdown_headings_in_body">
-❌ Do NOT use markdown headings in skill body:
-
-```markdown
-# PDF Processing
-
-## Quick start
-Extract text...
-
-## Advanced features
-Form filling...
+my-skill/
+├── SKILL.md           # Entry point (required, overview + navigation)
+├── reference.md       # Detailed docs (loaded when needed)
+├── examples.md        # Usage examples (loaded when needed)
+└── scripts/
+    └── helper.py      # Utility script (executed, not loaded)
 ```
 
-✅ Use pure XML structure:
-
-```xml
-<objective>
-PDF processing with text extraction, form filling, and merging.
-</objective>
-
-<quick_start>
-Extract text...
-</quick_start>
-
-<advanced_features>
-Form filling...
-</advanced_features>
-```
-</pitfall>
-
-<pitfall name="vague_descriptions">
-- ❌ "Helps with documents"
-- ✅ "Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction."
-</pitfall>
-
-<pitfall name="inconsistent_pov">
-- ❌ "I can help you process Excel files"
-- ✅ "Processes Excel files and generates reports"
-</pitfall>
-
-<pitfall name="wrong_naming_convention">
-- ❌ Directory: `facebook-ads`, Name: `facebook-ads-manager`
-- ✅ Directory: `manage-facebook-ads`, Name: `manage-facebook-ads`
-- ❌ Directory: `stripe-integration`, Name: `stripe`
-- ✅ Directory: `setup-stripe-payments`, Name: `setup-stripe-payments`
-</pitfall>
-
-<pitfall name="deeply_nested_references">
-Keep references one level deep from SKILL.md. Claude may only partially read nested files (SKILL.md → advanced.md → details.md).
-</pitfall>
-
-<pitfall name="windows_paths">
-Always use forward slashes: `scripts/helper.py` (not `scripts\helper.py`)
-</pitfall>
-
-<pitfall name="missing_required_tags">
-Every skill must have: `<objective>`, `<quick_start>`, and `<success_criteria>` (or `<when_successful>`).
-</pitfall>
-</anti_patterns>
-
-<validation_checklist>
-Before finalizing a skill, verify:
-
-- ✅ YAML frontmatter valid (name matches directory, description in third person)
-- ✅ No markdown headings in body (pure XML structure)
-- ✅ Required tags present: objective, quick_start, success_criteria
-- ✅ Conditional tags appropriate for complexity level
-- ✅ All XML tags properly closed
-- ✅ Progressive disclosure applied (SKILL.md < 500 lines)
-- ✅ Reference files use pure XML structure
-- ✅ File paths use forward slashes
-- ✅ Descriptive file names
-</validation_checklist>
+**Rules:**
+- Keep references one level deep from SKILL.md
+- Add table of contents to reference files over 100 lines
+- Use forward slashes in paths: `scripts/helper.py`
+- Name files descriptively: `form_validation_rules.md` not `doc2.md`
+
+## Validation Checklist
+
+Before finalizing:
+
+- [ ] YAML frontmatter valid (name matches directory, description specific)
+- [ ] Uses standard markdown headings (not XML tags)
+- [ ] Has Quick Start, Instructions, and Success Criteria sections
+- [ ] `disable-model-invocation: true` if skill has side effects
+- [ ] SKILL.md under 500 lines
+- [ ] Reference files linked properly from SKILL.md
+- [ ] File paths use forward slashes
+- [ ] Tested with real usage
+
+## Anti-Patterns
+
+- **XML tags in body** - Use standard markdown headings
+- **Vague descriptions** - Be specific with trigger keywords
+- **Deep nesting** - Keep references one level from SKILL.md
+- **Missing invocation control** - Side-effect workflows need `disable-model-invocation: true`
+- **Inconsistent naming** - Directory name must match `name` field
+- **Windows paths** - Always use forward slashes

package/plugins/compound-engineering/skills/document-review/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: document-review
+description: This skill should be used to refine brainstorm or plan documents before proceeding to the next workflow step. It applies when a brainstorm or plan document exists and the user wants to improve it.
+---
+
+# Document Review
+
+Improve brainstorm or plan documents through structured review.
+
+## Step 1: Get the Document
+
+**If a document path is provided:** Read it, then proceed to Step 2.
+
+**If no document is specified:** Ask which document to review, or look for the most recent brainstorm/plan in `docs/brainstorms/` or `docs/plans/`.
+
+## Step 2: Assess
+
+Read through the document and ask:
+
+- What is unclear?
+- What is unnecessary?
+- What decision is being avoided?
+- What assumptions are unstated?
+- Where could scope accidentally expand?
+
+These questions surface issues. Don't fix yet—just note what you find.
+
+## Step 3: Evaluate
+
+Score the document against these criteria:
+
+| Criterion | What to Check |
+|-----------|---------------|
+| **Clarity** | Problem statement is clear, no vague language ("probably," "consider," "try to") |
+| **Completeness** | Required sections present, constraints stated, open questions flagged |
+| **Specificity** | Concrete enough for next step (brainstorm → can plan, plan → can implement) |
+| **YAGNI** | No hypothetical features, simplest approach chosen |
+
+If invoked within a workflow (after `/workflows:brainstorm` or `/workflows:plan`), also check:
+- **User intent fidelity** — Document reflects what was discussed, assumptions validated
+
+## Step 4: Identify the Critical Improvement
+
+Among everything found in Steps 2-3, does one issue stand out? If something would significantly improve the document's quality, this is the "must address" item. Highlight it prominently.
+
+## Step 5: Make Changes
+
+Present your findings, then:
+
+1. **Auto-fix** minor issues (vague language, formatting) without asking
+2. **Ask approval** before substantive changes (restructuring, removing sections, changing meaning)
+3. **Update** the document inline—no separate files, no metadata sections
+
+### Simplification Guidance
+
+Simplification is purposeful removal of unnecessary complexity, not shortening for its own sake.
+
+**Simplify when:**
+- Content serves hypothetical future needs, not current ones
+- Sections repeat information already covered elsewhere
+- Detail exceeds what's needed to take the next step
+- Abstractions or structure add overhead without clarity
+
+**Don't simplify:**
+- Constraints or edge cases that affect implementation
+- Rationale that explains why alternatives were rejected
+- Open questions that need resolution
+
+## Step 6: Offer Next Action
+
+After changes are complete, ask:
+
+1. **Refine again** - Another review pass
+2. **Review complete** - Document is ready
+
+### Iteration Guidance
+
+After 2 refinement passes, recommend completion—diminishing returns are likely. But if the user wants to continue, allow it.
+
+Return control to the caller (workflow or user) after selection.
+
+## What NOT to Do
+
+- Do not rewrite the entire document
+- Do not add new sections or requirements the user didn't discuss
+- Do not over-engineer or add complexity
+- Do not create separate review files or add metadata sections

package/plugins/compound-engineering/skills/file-todos/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: file-todos
 description: This skill should be used when managing the file-based todo tracking system in the todos/ directory. It provides workflows for creating todos, managing status and dependencies, conducting triage, and integrating with slash commands and code review processes.
+disable-model-invocation: true
 ---
 
 # File-Based Todo Tracking Skill

package/plugins/compound-engineering/skills/git-worktree/scripts/worktree-manager.sh

@@ -91,14 +91,6 @@ create_worktree() {
   echo -e "${BLUE}Creating worktree: $branch_name${NC}"
   echo "  From: $from_branch"
   echo "  Path: $worktree_path"
-  echo ""
-  echo "Proceed? (y/n)"
-  read -r response
-
-  if [[ "$response" != "y" ]]; then
-    echo -e "${YELLOW}Cancelled${NC}"
-    return
-  fi
 
   # Update main branch
   echo -e "${BLUE}Updating $from_branch...${NC}"
@@ -134,7 +126,7 @@ list_worktrees() {
 
   local count=0
   for worktree_path in "$WORKTREE_DIR"/*; do
-    if [[ -d "$worktree_path" && -d "$worktree_path/.git" ]]; then
+    if [[ -d "$worktree_path" && -e "$worktree_path/.git" ]]; then
       count=$((count + 1))
       local worktree_name=$(basename "$worktree_path")
       local branch=$(git -C "$worktree_path" rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
@@ -231,7 +223,7 @@ cleanup_worktrees() {
   local to_remove=()
 
   for worktree_path in "$WORKTREE_DIR"/*; do
-    if [[ -d "$worktree_path" && -d "$worktree_path/.git" ]]; then
+    if [[ -d "$worktree_path" && -e "$worktree_path/.git" ]]; then
       local worktree_name=$(basename "$worktree_path")
 
       # Skip if current worktree