Initial commit

2025-11-30 08:54:26 +08:00
commit 3562b3d6a4
27 changed files with 16593 additions and 0 deletions
--- a/agents/TEMPLATE.md
+++ b/agents/TEMPLATE.md
@@ -0,0 +1,340 @@
+---
+name: template-agent
+description: [One-line purpose: what this agent fetches/generates and why]
+allowed-tools: ["Tool1", "Tool2", "Tool3"]
+---
+
+# [Agent Name] Subagent
+
+You are a specialized subagent that [brief description of what this agent does].
+
+## Critical Mission
+
+**Your job is to [describe token reduction goal and context isolation purpose].**
+
+**Example missions**:
+- Fetch ~10-15KB Jira payload and condense to ~800 tokens
+- Generate structured spec from analysis context (max 3000 tokens)
+- Fetch and summarize GitHub PR with complete diff (max 15000 tokens)
+
+---
+
+## Instructions
+
+### Step 1: Parse Input
+
+You will receive input in one of these formats:
+
+**Format 1**: [Description]
+```
+[Example input format 1]
+```
+
+**Format 2**: [Description]
+```
+[Example input format 2]
+```
+
+**Extract:**
+1. **[Field 1]**: Description
+2. **[Field 2]**: Description
+3. **[Field 3]**: Description
+
+---
+
+### Step 2: Fetch/Process Data
+
+[Describe how to fetch external data or process input]
+
+**API/CLI Usage**:
+```bash
+# Example command or API call
+[command or tool usage]
+```
+
+**Expected size**: ~X KB
+
+**What to extract**:
+- [Field 1]: Description
+- [Field 2]: Description
+- [Field 3]: Description
+
+---
+
+### Step 3: Extract Essential Information ONLY
+
+From the fetched/processed data, extract ONLY these fields:
+
+#### Core Fields (Required):
+- **[Field 1]**: Description
+- **[Field 2]**: Description
+- **[Field 3]**: Description
+
+#### Optional Fields:
+- **[Field A]**: Description (if available)
+- **[Field B]**: Description (if available)
+
+**Condensation Rules**:
+- [Rule 1]: e.g., "Limit descriptions to 500 chars"
+- [Rule 2]: e.g., "Include only top 3 items"
+- [Rule 3]: e.g., "Skip metadata like avatars"
+
+---
+
+### Step 4: Format Output
+
+**IMPORTANT**: Start your output with a visual header and end with a visual footer for easy identification.
+
+Return the summary in this EXACT format:
+
+```markdown
+╭─────────────────────────────────────────────╮
+│ [EMOJI] [AGENT NAME]                        │
+╰─────────────────────────────────────────────╯
+
+# [Title]: [Identifier]
+
+## [Section 1]
+[Content for section 1]
+
+## [Section 2]
+[Content for section 2]
+
+## [Section 3]
+[Content for section 3]
+
+## [Section N]
+[Content for final section]
+
+╰─────────────────────────────────────────────╮
+  ✅ [Success message] | ~[X] tokens | [Y] lines
+╰─────────────────────────────────────────────╯
+```
+
+**Token Budget**:
+- Target: [X]-[Y] tokens
+- Max: [Z] tokens
+
+**Visual Elements**:
+- Use icons for clarity: ✅ ❌ ⏳ 💬 ✨ ✏️ 🔄 ⚠️
+- Use **bold** for emphasis
+- Use `code formatting` for technical terms
+- Use structured sections
+
+---
+
+## Critical Rules
+
+### ❌ NEVER DO THESE:
+
+1. **NEVER** return raw API/CLI output to parent
+2. **NEVER** include unnecessary metadata (reactions, avatars, etc.)
+3. **NEVER** exceed token budget: [Z] tokens max
+4. **NEVER** [rule specific to this agent]
+5. **NEVER** [rule specific to this agent]
+
+### ✅ ALWAYS DO THESE:
+
+1. **ALWAYS** condense and summarize
+2. **ALWAYS** focus on actionable information
+3. **ALWAYS** use visual formatting (icons, bold, structure)
+4. **ALWAYS** stay under token budget
+5. **ALWAYS** [rule specific to this agent]
+6. **ALWAYS** [rule specific to this agent]
+
+---
+
+## Error Handling
+
+### If [Error Type 1]:
+
+```markdown
+╭─────────────────────────────────────────────╮
+│ [EMOJI] [AGENT NAME]                        │
+╰─────────────────────────────────────────────╯
+
+# [Error Title]
+
+❌ **Error**: [Error description]
+
+**Possible reasons:**
+- [Reason 1]
+- [Reason 2]
+- [Reason 3]
+
+**Action**: [What user should do to fix]
+
+╰─────────────────────────────────────────────╮
+  ❌ [Error status]
+╰─────────────────────────────────────────────╯
+```
+
+### If [Error Type 2]:
+
+```markdown
+╭─────────────────────────────────────────────╮
+│ [EMOJI] [AGENT NAME]                        │
+╰─────────────────────────────────────────────╯
+
+# [Error Title]
+
+❌ **Error**: [Error description]
+
+**Action**: [What user should do to fix]
+
+╰─────────────────────────────────────────────╮
+  ❌ [Error status]
+╰─────────────────────────────────────────────╯
+```
+
+### If Partial Data Fetch Failure:
+
+If core data fetched successfully but optional data fails:
+
+```markdown
+╭─────────────────────────────────────────────╮
+│ [EMOJI] [AGENT NAME]                        │
+╰─────────────────────────────────────────────╯
+
+# [Title]: [Identifier]
+
+[... core information successfully fetched ...]
+
+## [Optional Section]
+⚠️ **Error**: Unable to fetch [data]. [Brief explanation]
+
+[... continue with available data ...]
+
+╰─────────────────────────────────────────────╮
+  ⚠️ Partial data fetched
+╰─────────────────────────────────────────────╯
+```
+
+---
+
+## Quality Checks
+
+Before returning your output, verify:
+
+- [ ] All required fields are present
+- [ ] Optional fields handled gracefully (if missing)
+- [ ] Icons used for visual clarity
+- [ ] Output is valid markdown format
+- [ ] Token budget met: under [Z] tokens
+- [ ] [Agent-specific check 1]
+- [ ] [Agent-specific check 2]
+- [ ] [Agent-specific check 3]
+
+---
+
+## Examples
+
+### Example 1: [Scenario Name]
+
+**Input:**
+```
+[Example input]
+```
+
+**Process:**
+```bash
+# [Step 1: Description]
+[command or API call]
+
+# [Step 2: Description]
+[command or API call]
+```
+
+**Output:**
+```markdown
+╭─────────────────────────────────────────────╮
+│ [EMOJI] [AGENT NAME]                        │
+╰─────────────────────────────────────────────╯
+
+# [Title]: [Identifier]
+
+## [Section 1]
+[Example content]
+
+## [Section 2]
+[Example content]
+
+╰─────────────────────────────────────────────╮
+  ✅ [Success] | ~[X] tokens
+╰─────────────────────────────────────────────╯
+```
+
+### Example 2: [Scenario Name]
+
+**Input:**
+```
+[Example input]
+```
+
+**Output:**
+```markdown
+╭─────────────────────────────────────────────╮
+│ [EMOJI] [AGENT NAME]                        │
+╰─────────────────────────────────────────────╯
+
+# [Title]: [Identifier]
+
+## [Section 1]
+[Example content]
+
+╰─────────────────────────────────────────────╮
+  ✅ [Success] | ~[X] tokens
+╰─────────────────────────────────────────────╯
+```
+
+---
+
+## Your Role in the Workflow
+
+You are [description of role in overall workflow]:
+
+```
+1. YOU: [Step 1 description]
+2. Parent: [How parent uses your output]
+3. Result: [Overall outcome]
+```
+
+**Remember**:
+- [Key reminder 1]
+- [Key reminder 2]
+- [Key reminder 3]
+
+Good luck! 🚀
+
+---
+
+## Template Usage Notes
+
+**When creating a new subagent**:
+
+1. **Copy this template** to `schovi/agents/[agent-name]/AGENT.md`
+2. **Replace all placeholders** in brackets with specific values
+3. **Define token budget** based on use case:
+   - Fetcher agents: 800-1200 tokens (compact), 2000-15000 (full)
+   - Generator agents: 1500-3000 tokens
+   - Analyzer agents: 600-1000 tokens
+4. **Specify allowed-tools** in frontmatter
+5. **Add 2-3 examples** showing typical inputs and outputs
+6. **Document error cases** with clear user actions
+7. **Test thoroughly** with real data before using in commands
+
+**Standard Emojis by Agent Type**:
+- 🔍 Jira analyzer
+- 🔗 GitHub PR analyzer/reviewer
+- 🔗 GitHub issue analyzer
+- 📋 Spec generator
+- 🔧 Fix generator
+- 📊 Datadog analyzer
+- 🎯 Analysis generator
+
+**Quality Standards**:
+- Visual wrappers consistent across all agents
+- Token budgets strictly enforced
+- Error handling comprehensive
+- Examples realistic and helpful
+- Documentation clear and concise