@namch/agent-assistant 1.0.0 → 1.0.1

package/skills/subagent-driven-development/SKILL.md

@@ -0,0 +1,240 @@
+---
+name: subagent-driven-development
+description: Use when executing implementation plans with independent tasks in the current session
+---
+
+# Subagent-Driven Development
+
+Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review.
+
+**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration
+
+## When to Use
+
+```dot
+digraph when_to_use {
+    "Have implementation plan?" [shape=diamond];
+    "Tasks mostly independent?" [shape=diamond];
+    "Stay in this session?" [shape=diamond];
+    "subagent-driven-development" [shape=box];
+    "executing-plans" [shape=box];
+    "Manual execution or brainstorm first" [shape=box];
+
+    "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"];
+    "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"];
+    "Tasks mostly independent?" -> "Stay in this session?" [label="yes"];
+    "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"];
+    "Stay in this session?" -> "subagent-driven-development" [label="yes"];
+    "Stay in this session?" -> "executing-plans" [label="no - parallel session"];
+}
+```
+
+**vs. Executing Plans (parallel session):**
+- Same session (no context switch)
+- Fresh subagent per task (no context pollution)
+- Two-stage review after each task: spec compliance first, then code quality
+- Faster iteration (no human-in-loop between tasks)
+
+## The Process
+
+```dot
+digraph process {
+    rankdir=TB;
+
+    subgraph cluster_per_task {
+        label="Per Task";
+        "Dispatch implementer subagent (./implementer-prompt.md)" [shape=box];
+        "Implementer subagent asks questions?" [shape=diamond];
+        "Answer questions, provide context" [shape=box];
+        "Implementer subagent implements, tests, commits, self-reviews" [shape=box];
+        "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [shape=box];
+        "Spec reviewer subagent confirms code matches spec?" [shape=diamond];
+        "Implementer subagent fixes spec gaps" [shape=box];
+        "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [shape=box];
+        "Code quality reviewer subagent approves?" [shape=diamond];
+        "Implementer subagent fixes quality issues" [shape=box];
+        "Mark task complete in TodoWrite" [shape=box];
+    }
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" [shape=box];
+    "More tasks remain?" [shape=diamond];
+    "Dispatch final code reviewer subagent for entire implementation" [shape=box];
+    "Use superpowers:finishing-a-development-branch" [shape=box style=filled fillcolor=lightgreen];
+
+    "Read plan, extract all tasks with full text, note context, create TodoWrite" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Dispatch implementer subagent (./implementer-prompt.md)" -> "Implementer subagent asks questions?";
+    "Implementer subagent asks questions?" -> "Answer questions, provide context" [label="yes"];
+    "Answer questions, provide context" -> "Dispatch implementer subagent (./implementer-prompt.md)";
+    "Implementer subagent asks questions?" -> "Implementer subagent implements, tests, commits, self-reviews" [label="no"];
+    "Implementer subagent implements, tests, commits, self-reviews" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)";
+    "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" -> "Spec reviewer subagent confirms code matches spec?";
+    "Spec reviewer subagent confirms code matches spec?" -> "Implementer subagent fixes spec gaps" [label="no"];
+    "Implementer subagent fixes spec gaps" -> "Dispatch spec reviewer subagent (./spec-reviewer-prompt.md)" [label="re-review"];
+    "Spec reviewer subagent confirms code matches spec?" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="yes"];
+    "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" -> "Code quality reviewer subagent approves?";
+    "Code quality reviewer subagent approves?" -> "Implementer subagent fixes quality issues" [label="no"];
+    "Implementer subagent fixes quality issues" -> "Dispatch code quality reviewer subagent (./code-quality-reviewer-prompt.md)" [label="re-review"];
+    "Code quality reviewer subagent approves?" -> "Mark task complete in TodoWrite" [label="yes"];
+    "Mark task complete in TodoWrite" -> "More tasks remain?";
+    "More tasks remain?" -> "Dispatch implementer subagent (./implementer-prompt.md)" [label="yes"];
+    "More tasks remain?" -> "Dispatch final code reviewer subagent for entire implementation" [label="no"];
+    "Dispatch final code reviewer subagent for entire implementation" -> "Use superpowers:finishing-a-development-branch";
+}
+```
+
+## Prompt Templates
+
+- `./implementer-prompt.md` - Dispatch implementer subagent
+- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent
+- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent
+
+## Example Workflow
+
+```
+You: I'm using Subagent-Driven Development to execute this plan.
+
+[Read plan file once: docs/plans/feature-plan.md]
+[Extract all 5 tasks with full text and context]
+[Create TodoWrite with all tasks]
+
+Task 1: Hook installation script
+
+[Get Task 1 text and context (already extracted)]
+[Dispatch implementation subagent with full task text + context]
+
+Implementer: "Before I begin - should the hook be installed at user or system level?"
+
+You: "User level (~/.config/superpowers/hooks/)"
+
+Implementer: "Got it. Implementing now..."
+[Later] Implementer:
+  - Implemented install-hook command
+  - Added tests, 5/5 passing
+  - Self-review: Found I missed --force flag, added it
+  - Committed
+
+[Dispatch spec compliance reviewer]
+Spec reviewer: ✅ Spec compliant - all requirements met, nothing extra
+
+[Get git SHAs, dispatch code quality reviewer]
+Code reviewer: Strengths: Good test coverage, clean. Issues: None. Approved.
+
+[Mark Task 1 complete]
+
+Task 2: Recovery modes
+
+[Get Task 2 text and context (already extracted)]
+[Dispatch implementation subagent with full task text + context]
+
+Implementer: [No questions, proceeds]
+Implementer:
+  - Added verify/repair modes
+  - 8/8 tests passing
+  - Self-review: All good
+  - Committed
+
+[Dispatch spec compliance reviewer]
+Spec reviewer: ❌ Issues:
+  - Missing: Progress reporting (spec says "report every 100 items")
+  - Extra: Added --json flag (not requested)
+
+[Implementer fixes issues]
+Implementer: Removed --json flag, added progress reporting
+
+[Spec reviewer reviews again]
+Spec reviewer: ✅ Spec compliant now
+
+[Dispatch code quality reviewer]
+Code reviewer: Strengths: Solid. Issues (Important): Magic number (100)
+
+[Implementer fixes]
+Implementer: Extracted PROGRESS_INTERVAL constant
+
+[Code reviewer reviews again]
+Code reviewer: ✅ Approved
+
+[Mark Task 2 complete]
+
+...
+
+[After all tasks]
+[Dispatch final code-reviewer]
+Final reviewer: All requirements met, ready to merge
+
+Done!
+```
+
+## Advantages
+
+**vs. Manual execution:**
+- Subagents follow TDD naturally
+- Fresh context per task (no confusion)
+- Parallel-safe (subagents don't interfere)
+- Subagent can ask questions (before AND during work)
+
+**vs. Executing Plans:**
+- Same session (no handoff)
+- Continuous progress (no waiting)
+- Review checkpoints automatic
+
+**Efficiency gains:**
+- No file reading overhead (controller provides full text)
+- Controller curates exactly what context is needed
+- Subagent gets complete information upfront
+- Questions surfaced before work begins (not after)
+
+**Quality gates:**
+- Self-review catches issues before handoff
+- Two-stage review: spec compliance, then code quality
+- Review loops ensure fixes actually work
+- Spec compliance prevents over/under-building
+- Code quality ensures implementation is well-built
+
+**Cost:**
+- More subagent invocations (implementer + 2 reviewers per task)
+- Controller does more prep work (extracting all tasks upfront)
+- Review loops add iterations
+- But catches issues early (cheaper than debugging later)
+
+## Red Flags
+
+**Never:**
+- Skip reviews (spec compliance OR code quality)
+- Proceed with unfixed issues
+- Dispatch multiple implementation subagents in parallel (conflicts)
+- Make subagent read plan file (provide full text instead)
+- Skip scene-setting context (subagent needs to understand where task fits)
+- Ignore subagent questions (answer before letting them proceed)
+- Accept "close enough" on spec compliance (spec reviewer found issues = not done)
+- Skip review loops (reviewer found issues = implementer fixes = review again)
+- Let implementer self-review replace actual review (both are needed)
+- **Start code quality review before spec compliance is ✅** (wrong order)
+- Move to next task while either review has open issues
+
+**If subagent asks questions:**
+- Answer clearly and completely
+- Provide additional context if needed
+- Don't rush them into implementation
+
+**If reviewer finds issues:**
+- Implementer (same subagent) fixes them
+- Reviewer reviews again
+- Repeat until approved
+- Don't skip the re-review
+
+**If subagent fails task:**
+- Dispatch fix subagent with specific instructions
+- Don't try to fix manually (context pollution)
+
+## Integration
+
+**Required workflow skills:**
+- **superpowers:writing-plans** - Creates the plan this skill executes
+- **superpowers:requesting-code-review** - Code review template for reviewer subagents
+- **superpowers:finishing-a-development-branch** - Complete development after all tasks
+
+**Subagents should use:**
+- **superpowers:test-driven-development** - Subagents follow TDD for each task
+
+**Alternative workflow:**
+- **superpowers:executing-plans** - Use for parallel session instead of same-session execution

package/skills/subagent-driven-development/code-quality-reviewer-prompt.md

@@ -0,0 +1,20 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Task tool (superpowers:code-reviewer):
+  Use template at requesting-code-review/code-reviewer.md
+
+  WHAT_WAS_IMPLEMENTED: [from implementer's report]
+  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
+  BASE_SHA: [commit before task]
+  HEAD_SHA: [current commit]
+  DESCRIPTION: [task summary]
+```
+
+**Code reviewer returns:** Strengths, Issues (Critical/Important/Minor), Assessment

package/skills/subagent-driven-development/implementer-prompt.md

@@ -0,0 +1,78 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent.
+
+```
+Task tool (general-purpose):
+  description: "Implement Task N: [task name]"
+  prompt: |
+    You are implementing Task N: [task name]
+
+    ## Task Description
+
+    [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+
+    ## Context
+
+    [Scene-setting: where this fits, dependencies, architectural context]
+
+    ## Before You Begin
+
+    If you have questions about:
+    - The requirements or acceptance criteria
+    - The approach or implementation strategy
+    - Dependencies or assumptions
+    - Anything unclear in the task description
+
+    **Ask them now.** Raise any concerns before starting work.
+
+    ## Your Job
+
+    Once you're clear on requirements:
+    1. Implement exactly what the task specifies
+    2. Write tests (following TDD if task says to)
+    3. Verify implementation works
+    4. Commit your work
+    5. Self-review (see below)
+    6. Report back
+
+    Work from: [directory]
+
+    **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+    It's always OK to pause and clarify. Don't guess or make assumptions.
+
+    ## Before Reporting Back: Self-Review
+
+    Review your work with fresh eyes. Ask yourself:
+
+    **Completeness:**
+    - Did I fully implement everything in the spec?
+    - Did I miss any requirements?
+    - Are there edge cases I didn't handle?
+
+    **Quality:**
+    - Is this my best work?
+    - Are names clear and accurate (match what things do, not how they work)?
+    - Is the code clean and maintainable?
+
+    **Discipline:**
+    - Did I avoid overbuilding (YAGNI)?
+    - Did I only build what was requested?
+    - Did I follow existing patterns in the codebase?
+
+    **Testing:**
+    - Do tests actually verify behavior (not just mock behavior)?
+    - Did I follow TDD if required?
+    - Are tests comprehensive?
+
+    If you find issues during self-review, fix them now before reporting.
+
+    ## Report Format
+
+    When done, report:
+    - What you implemented
+    - What you tested and test results
+    - Files changed
+    - Self-review findings (if any)
+    - Any issues or concerns
+```

package/skills/subagent-driven-development/spec-reviewer-prompt.md

@@ -0,0 +1,61 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance reviewer subagent.
+
+**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
+
+```
+Task tool (general-purpose):
+  description: "Review spec compliance for Task N"
+  prompt: |
+    You are reviewing whether an implementation matches its specification.
+
+    ## What Was Requested
+
+    [FULL TEXT of task requirements]
+
+    ## What Implementer Claims They Built
+
+    [From implementer's report]
+
+    ## CRITICAL: Do Not Trust the Report
+
+    The implementer finished suspiciously quickly. Their report may be incomplete,
+    inaccurate, or optimistic. You MUST verify everything independently.
+
+    **DO NOT:**
+    - Take their word for what they implemented
+    - Trust their claims about completeness
+    - Accept their interpretation of requirements
+
+    **DO:**
+    - Read the actual code they wrote
+    - Compare actual implementation to requirements line by line
+    - Check for missing pieces they claimed to implement
+    - Look for extra features they didn't mention
+
+    ## Your Job
+
+    Read the implementation code and verify:
+
+    **Missing requirements:**
+    - Did they implement everything that was requested?
+    - Are there requirements they skipped or missed?
+    - Did they claim something works but didn't actually implement it?
+
+    **Extra/unneeded work:**
+    - Did they build things that weren't requested?
+    - Did they over-engineer or add unnecessary features?
+    - Did they add "nice to haves" that weren't in spec?
+
+    **Misunderstandings:**
+    - Did they interpret requirements differently than intended?
+    - Did they solve the wrong problem?
+    - Did they implement the right feature but wrong way?
+
+    **Verify by reading code, not by trusting report.**
+
+    Report:
+    - ✅ Spec compliant (if everything matches after code inspection)
+    - ❌ Issues found: [list specifically what's missing or extra, with file:line references]
+```

package/skills/tavily-web/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: tavily-web
+description: Web search, content extraction, crawling, and research capabilities using Tavily API
+---
+
+# tavily-web
+
+## Overview
+Web search, content extraction, crawling, and research capabilities using Tavily API
+
+## When to Use
+- When you need to search the web for current information
+- When extracting content from URLs
+- When crawling websites
+
+## Installation
+```bash
+npx skills add -g BenedictKing/tavily-web
+```
+
+## Step-by-Step Guide
+1. Install the skill using the command above
+2. Configure Tavily API key
+3. Use naturally in Claude Code conversations
+
+## Examples
+See [GitHub Repository](https://github.com/BenedictKing/tavily-web) for examples.
+
+## Best Practices
+- Configure API keys via environment variables
+
+## Troubleshooting
+See the GitHub repository for troubleshooting guides.
+
+## Related Skills
+- context7-auto-research, exa-search, firecrawl-scraper, codex-review

package/skills/telegram-bot-builder/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: telegram-bot-builder
+description: "Expert in building Telegram bots that solve real problems - from simple automation to complex AI-powered bots. Covers bot architecture, the Telegram Bot API, user experience, monetization strategies, and scaling bots to thousands of users. Use when: telegram bot, bot api, telegram automation, chat bot telegram, tg bot."
+source: vibeship-spawner-skills (Apache 2.0)
+---
+
+# Telegram Bot Builder
+
+**Role**: Telegram Bot Architect
+
+You build bots that people actually use daily. You understand that bots
+should feel like helpful assistants, not clunky interfaces. You know
+the Telegram ecosystem deeply - what's possible, what's popular, and
+what makes money. You design conversations that feel natural.
+
+## Capabilities
+
+- Telegram Bot API
+- Bot architecture
+- Command design
+- Inline keyboards
+- Bot monetization
+- User onboarding
+- Bot analytics
+- Webhook management
+
+## Patterns
+
+### Bot Architecture
+
+Structure for maintainable Telegram bots
+
+**When to use**: When starting a new bot project
+
+```python
+## Bot Architecture
+
+### Stack Options
+| Language | Library | Best For |
+|----------|---------|----------|
+| Node.js | telegraf | Most projects |
+| Node.js | grammY | TypeScript, modern |
+| Python | python-telegram-bot | Quick prototypes |
+| Python | aiogram | Async, scalable |
+
+### Basic Telegraf Setup
+```javascript
+import { Telegraf } from 'telegraf';
+
+const bot = new Telegraf(process.env.BOT_TOKEN);
+
+// Command handlers
+bot.start((ctx) => ctx.reply('Welcome!'));
+bot.help((ctx) => ctx.reply('How can I help?'));
+
+// Text handler
+bot.on('text', (ctx) => {
+  ctx.reply(`You said: ${ctx.message.text}`);
+});
+
+// Launch
+bot.launch();
+
+// Graceful shutdown
+process.once('SIGINT', () => bot.stop('SIGINT'));
+process.once('SIGTERM', () => bot.stop('SIGTERM'));
+```
+
+### Project Structure
+```
+telegram-bot/
+├── src/
+│   ├── bot.js           # Bot initialization
+│   ├── commands/        # Command handlers
+│   │   ├── start.js
+│   │   ├── help.js
+│   │   └── settings.js
+│   ├── handlers/        # Message handlers
+│   ├── keyboards/       # Inline keyboards
+│   ├── middleware/      # Auth, logging
+│   └── services/        # Business logic
+├── .env
+└── package.json
+```
+```
+
+### Inline Keyboards
+
+Interactive button interfaces
+
+**When to use**: When building interactive bot flows
+
+```python
+## Inline Keyboards
+
+### Basic Keyboard
+```javascript
+import { Markup } from 'telegraf';
+
+bot.command('menu', (ctx) => {
+  ctx.reply('Choose an option:', Markup.inlineKeyboard([
+    [Markup.button.callback('Option 1', 'opt_1')],
+    [Markup.button.callback('Option 2', 'opt_2')],
+    [
+      Markup.button.callback('Yes', 'yes'),
+      Markup.button.callback('No', 'no'),
+    ],
+  ]));
+});
+
+// Handle button clicks
+bot.action('opt_1', (ctx) => {
+  ctx.answerCbQuery('You chose Option 1');
+  ctx.editMessageText('You selected Option 1');
+});
+```
+
+### Keyboard Patterns
+| Pattern | Use Case |
+|---------|----------|
+| Single column | Simple menus |
+| Multi column | Yes/No, pagination |
+| Grid | Category selection |
+| URL buttons | Links, payments |
+
+### Pagination
+```javascript
+function getPaginatedKeyboard(items, page, perPage = 5) {
+  const start = page * perPage;
+  const pageItems = items.slice(start, start + perPage);
+
+  const buttons = pageItems.map(item =>
+    [Markup.button.callback(item.name, `item_${item.id}`)]
+  );
+
+  const nav = [];
+  if (page > 0) nav.push(Markup.button.callback('◀️', `page_${page-1}`));
+  if (start + perPage < items.length) nav.push(Markup.button.callback('▶️', `page_${page+1}`));
+
+  return Markup.inlineKeyboard([...buttons, nav]);
+}
+```
+```
+
+### Bot Monetization
+
+Making money from Telegram bots
+
+**When to use**: When planning bot revenue
+
+```javascript
+## Bot Monetization
+
+### Revenue Models
+| Model | Example | Complexity |
+|-------|---------|------------|
+| Freemium | Free basic, paid premium | Medium |
+| Subscription | Monthly access | Medium |
+| Per-use | Pay per action | Low |
+| Ads | Sponsored messages | Low |
+| Affiliate | Product recommendations | Low |
+
+### Telegram Payments
+```javascript
+// Create invoice
+bot.command('buy', (ctx) => {
+  ctx.replyWithInvoice({
+    title: 'Premium Access',
+    description: 'Unlock all features',
+    payload: 'premium_monthly',
+    provider_token: process.env.PAYMENT_TOKEN,
+    currency: 'USD',
+    prices: [{ label: 'Premium', amount: 999 }], // $9.99
+  });
+});
+
+// Handle successful payment
+bot.on('successful_payment', (ctx) => {
+  const payment = ctx.message.successful_payment;
+  // Activate premium for user
+  await activatePremium(ctx.from.id);
+  ctx.reply('🎉 Premium activated!');
+});
+```
+
+### Freemium Strategy
+```
+Free tier:
+- 10 uses per day
+- Basic features
+- Ads shown
+
+Premium ($5/month):
+- Unlimited uses
+- Advanced features
+- No ads
+- Priority support
+```
+
+### Usage Limits
+```javascript
+async function checkUsage(userId) {
+  const usage = await getUsage(userId);
+  const isPremium = await checkPremium(userId);
+
+  if (!isPremium && usage >= 10) {
+    return { allowed: false, message: 'Daily limit reached. Upgrade?' };
+  }
+  return { allowed: true };
+}
+```
+```
+
+## Anti-Patterns
+
+### ❌ Blocking Operations
+
+**Why bad**: Telegram has timeout limits.
+Users think bot is dead.
+Poor experience.
+Requests pile up.
+
+**Instead**: Acknowledge immediately.
+Process in background.
+Send update when done.
+Use typing indicator.
+
+### ❌ No Error Handling
+
+**Why bad**: Users get no response.
+Bot appears broken.
+Debugging nightmare.
+Lost trust.
+
+**Instead**: Global error handler.
+Graceful error messages.
+Log errors for debugging.
+Rate limiting.
+
+### ❌ Spammy Bot
+
+**Why bad**: Users block the bot.
+Telegram may ban.
+Annoying experience.
+Low retention.
+
+**Instead**: Respect user attention.
+Consolidate messages.
+Allow notification control.
+Quality over quantity.
+
+## Related Skills
+
+Works well with: `telegram-mini-app`, `backend`, `ai-wrapper-product`, `workflow-automation`