@ngxtm/devkit 3.7.0 → 3.8.0

package/merged-commands/blockrun.md

@@ -0,0 +1,292 @@
+---
+name: blockrun
+description: Use when user needs capabilities Claude lacks (image generation, real-time X/Twitter data) or explicitly requests external models ("blockrun", "use grok", "use gpt", "dall-e", "deepseek")
+allowed-tools: Read, Bash(python:*), Bash(python3:*), Bash(pip:*), Bash(source:*)
+---
+
+# BlockRun
+
+**BlockRun works with Claude Code and Google Antigravity.**
+
+You can't generate images. You have no real-time X/Twitter access. BlockRun gives you these capabilities.
+
+## Philosophy
+
+You have a wallet. When you need a capability you lack, you pay for it autonomously.
+
+| You Need | You Call | Pricing |
+|----------|----------|---------|
+| Image generation | DALL-E | $0.04/image |
+| Real-time X data | Grok + Live Search | $0.025/source |
+| Second opinion | GPT-5.2 | $1.75/M input, $14/M output |
+| Cheaper processing | DeepSeek | $0.14/M input, $0.28/M output |
+
+**How it works:** BlockRun uses x402 micropayments to route your requests to OpenAI, xAI, Google, and other providers. No API keys needed - your wallet pays per token.
+
+## Budget Control (Optional)
+
+If the user specifies a budget (e.g., "use at most $1"), track spending and stop when budget is reached:
+
+```python
+from blockrun_llm import setup_agent_wallet
+
+client = setup_agent_wallet()
+budget = 1.0  # User's budget
+
+# Before each call, check if within budget
+spending = client.get_spending()
+if spending['total_usd'] >= budget:
+    print(f"Budget reached: ${spending['total_usd']:.4f} spent")
+    # Stop making calls
+else:
+    response = client.chat("openai/gpt-5.2", "Hello!")
+
+# At the end, report spending
+spending = client.get_spending()
+print(f"💰 Total spent: ${spending['total_usd']:.4f} across {spending['calls']} calls")
+```
+
+## When to Use
+
+| Trigger | Your Action |
+|---------|-------------|
+| User explicitly requests ("blockrun second opinion with GPT on...", "use grok to check...", "generate image with dall-e") | Execute via BlockRun |
+| User needs something you can't do (images, live X data) | Suggest BlockRun, wait for confirmation |
+| You can handle the task fine | Do it yourself, don't mention BlockRun |
+
+## Example User Prompts
+
+Users will say things like:
+
+| User Says | What You Do |
+|-----------|-------------|
+| "blockrun generate an image of a sunset" | Call DALL-E via ImageClient |
+| "use grok to check what's trending on X" | Call Grok with `search=True` |
+| "blockrun GPT review this code" | Call GPT-5.2 via LLMClient |
+| "what's the latest news about AI agents?" | Suggest Grok (you lack real-time data) |
+| "generate a logo for my startup" | Suggest DALL-E (you can't generate images) |
+| "blockrun check my balance" | Show wallet balance via `get_balance()` |
+| "blockrun deepseek summarize this file" | Call DeepSeek for cost savings |
+
+## Wallet & Balance
+
+Use `setup_agent_wallet()` to auto-create a wallet and get a client. This shows the QR code and welcome message on first use.
+
+**Initialize client (always start with this):**
+```python
+from blockrun_llm import setup_agent_wallet
+
+client = setup_agent_wallet()  # Auto-creates wallet, shows QR if new
+```
+
+**Check balance (when user asks "show balance", "check wallet", etc.):**
+```python
+balance = client.get_balance()  # On-chain USDC balance
+print(f"Balance: ${balance:.2f} USDC")
+print(f"Wallet: {client.get_wallet_address()}")
+```
+
+**Show QR code for funding:**
+```python
+from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
+
+# ASCII QR for terminal display
+print(generate_wallet_qr_ascii(get_wallet_address()))
+```
+
+## SDK Usage
+
+**Prerequisite:** Install the SDK with `pip install blockrun-llm`
+
+### Basic Chat
+```python
+from blockrun_llm import setup_agent_wallet
+
+client = setup_agent_wallet()  # Auto-creates wallet if needed
+response = client.chat("openai/gpt-5.2", "What is 2+2?")
+print(response)
+
+# Check spending
+spending = client.get_spending()
+print(f"Spent ${spending['total_usd']:.4f}")
+```
+
+### Real-time X/Twitter Search (xAI Live Search)
+
+**IMPORTANT:** For real-time X/Twitter data, you MUST enable Live Search with `search=True` or `search_parameters`.
+
+```python
+from blockrun_llm import setup_agent_wallet
+
+client = setup_agent_wallet()
+
+# Simple: Enable live search with search=True
+response = client.chat(
+    "xai/grok-3",
+    "What are the latest posts from @blockrunai on X?",
+    search=True  # Enables real-time X/Twitter search
+)
+print(response)
+```
+
+### Advanced X Search with Filters
+
+```python
+from blockrun_llm import setup_agent_wallet
+
+client = setup_agent_wallet()
+
+response = client.chat(
+    "xai/grok-3",
+    "Analyze @blockrunai's recent content and engagement",
+    search_parameters={
+        "mode": "on",
+        "sources": [
+            {
+                "type": "x",
+                "included_x_handles": ["blockrunai"],
+                "post_favorite_count": 5
+            }
+        ],
+        "max_search_results": 20,
+        "return_citations": True
+    }
+)
+print(response)
+```
+
+### Image Generation
+```python
+from blockrun_llm import ImageClient
+
+client = ImageClient()
+result = client.generate("A cute cat wearing a space helmet")
+print(result.data[0].url)
+```
+
+## xAI Live Search Reference
+
+Live Search is xAI's real-time data API. Cost: **$0.025 per source** (default 10 sources = ~$0.26).
+
+To reduce costs, set `max_search_results` to a lower value:
+```python
+# Only use 5 sources (~$0.13)
+response = client.chat("xai/grok-3", "What's trending?",
+    search_parameters={"mode": "on", "max_search_results": 5})
+```
+
+### Search Parameters
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `mode` | string | "auto" | "off", "auto", or "on" |
+| `sources` | array | web,news,x | Data sources to query |
+| `return_citations` | bool | true | Include source URLs |
+| `from_date` | string | - | Start date (YYYY-MM-DD) |
+| `to_date` | string | - | End date (YYYY-MM-DD) |
+| `max_search_results` | int | 10 | Max sources to return (customize to control cost) |
+
+### Source Types
+
+**X/Twitter Source:**
+```python
+{
+    "type": "x",
+    "included_x_handles": ["handle1", "handle2"],  # Max 10
+    "excluded_x_handles": ["spam_account"],        # Max 10
+    "post_favorite_count": 100,  # Min likes threshold
+    "post_view_count": 1000      # Min views threshold
+}
+```
+
+**Web Source:**
+```python
+{
+    "type": "web",
+    "country": "US",  # ISO alpha-2 code
+    "allowed_websites": ["example.com"],  # Max 5
+    "safe_search": True
+}
+```
+
+**News Source:**
+```python
+{
+    "type": "news",
+    "country": "US",
+    "excluded_websites": ["tabloid.com"]  # Max 5
+}
+```
+
+## Available Models
+
+| Model | Best For | Pricing |
+|-------|----------|---------|
+| `openai/gpt-5.2` | Second opinions, code review, general | $1.75/M in, $14/M out |
+| `openai/gpt-5-mini` | Cost-optimized reasoning | $0.30/M in, $1.20/M out |
+| `openai/o4-mini` | Latest efficient reasoning | $1.10/M in, $4.40/M out |
+| `openai/o3` | Advanced reasoning, complex problems | $10/M in, $40/M out |
+| `xai/grok-3` | Real-time X/Twitter data | $3/M + $0.025/source |
+| `deepseek/deepseek-chat` | Simple tasks, bulk processing | $0.14/M in, $0.28/M out |
+| `google/gemini-2.5-flash` | Very long documents, fast | $0.15/M in, $0.60/M out |
+| `openai/dall-e-3` | Photorealistic images | $0.04/image |
+| `google/nano-banana` | Fast, artistic images | $0.01/image |
+
+*M = million tokens. Actual cost depends on your prompt and response length.*
+
+## Cost Reference
+
+All LLM costs are per million tokens (M = 1,000,000 tokens).
+
+| Model | Input | Output |
+|-------|-------|--------|
+| GPT-5.2 | $1.75/M | $14.00/M |
+| GPT-5-mini | $0.30/M | $1.20/M |
+| Grok-3 (no search) | $3.00/M | $15.00/M |
+| DeepSeek | $0.14/M | $0.28/M |
+
+| Fixed Cost Actions | |
+|-------|--------|
+| Grok Live Search | $0.025/source (default 10 = $0.25) |
+| DALL-E image | $0.04/image |
+| Nano Banana image | $0.01/image |
+
+**Typical costs:** A 500-word prompt (~750 tokens) to GPT-5.2 costs ~$0.001 input. A 1000-word response (~1500 tokens) costs ~$0.02 output.
+
+## Setup & Funding
+
+**Wallet location:** `$HOME/.blockrun/.session` (e.g., `/Users/username/.blockrun/.session`)
+
+**First-time setup:**
+1. Wallet auto-creates when `setup_agent_wallet()` is called
+2. Check wallet and balance:
+```python
+from blockrun_llm import setup_agent_wallet
+client = setup_agent_wallet()
+print(f"Wallet: {client.get_wallet_address()}")
+print(f"Balance: ${client.get_balance():.2f} USDC")
+```
+3. Fund wallet with $1-5 USDC on Base network
+
+**Show QR code for funding (ASCII for terminal):**
+```python
+from blockrun_llm import generate_wallet_qr_ascii, get_wallet_address
+print(generate_wallet_qr_ascii(get_wallet_address()))
+```
+
+## Troubleshooting
+
+**"Grok says it has no real-time access"**
+→ You forgot to enable Live Search. Add `search=True`:
+```python
+response = client.chat("xai/grok-3", "What's trending?", search=True)
+```
+
+**Module not found**
+→ Install the SDK: `pip install blockrun-llm`
+
+## Updates
+
+```bash
+pip install --upgrade blockrun-llm
+```

package/merged-commands/brainstorming.md

@@ -0,0 +1,230 @@
+---
+name: brainstorming
+description: >
+  Use this skill before any creative or constructive work
+  (features, components, architecture, behavior changes, or functionality).
+  This skill transforms vague ideas into validated designs through
+  disciplined, incremental reasoning and collaboration.
+---
+
+# Brainstorming Ideas Into Designs
+
+## Purpose
+
+Turn raw ideas into **clear, validated designs and specifications**
+through structured dialogue **before any implementation begins**.
+
+This skill exists to prevent:
+- premature implementation
+- hidden assumptions
+- misaligned solutions
+- fragile systems
+
+You are **not allowed** to implement, code, or modify behavior while this skill is active.
+
+---
+
+## Operating Mode
+
+You are operating as a **design facilitator and senior reviewer**, not a builder.
+
+- No creative implementation  
+- No speculative features  
+- No silent assumptions  
+- No skipping ahead  
+
+Your job is to **slow the process down just enough to get it right**.
+
+---
+
+## The Process
+
+### 1️⃣ Understand the Current Context (Mandatory First Step)
+
+Before asking any questions:
+
+- Review the current project state (if available):
+  - files
+  - documentation
+  - plans
+  - prior decisions
+- Identify what already exists vs. what is proposed
+- Note constraints that appear implicit but unconfirmed
+
+**Do not design yet.**
+
+---
+
+### 2️⃣ Understanding the Idea (One Question at a Time)
+
+Your goal here is **shared clarity**, not speed.
+
+**Rules:**
+
+- Ask **one question per message**
+- Prefer **multiple-choice questions** when possible
+- Use open-ended questions only when necessary
+- If a topic needs depth, split it into multiple questions
+
+Focus on understanding:
+
+- purpose  
+- target users  
+- constraints  
+- success criteria  
+- explicit non-goals  
+
+---
+
+### 3️⃣ Non-Functional Requirements (Mandatory)
+
+You MUST explicitly clarify or propose assumptions for:
+
+- Performance expectations  
+- Scale (users, data, traffic)  
+- Security or privacy constraints  
+- Reliability / availability needs  
+- Maintenance and ownership expectations  
+
+If the user is unsure:
+
+- Propose reasonable defaults  
+- Clearly mark them as **assumptions**
+
+---
+
+### 4️⃣ Understanding Lock (Hard Gate)
+
+Before proposing **any design**, you MUST pause and do the following:
+
+#### Understanding Summary
+Provide a concise summary (5–7 bullets) covering:
+- What is being built  
+- Why it exists  
+- Who it is for  
+- Key constraints  
+- Explicit non-goals  
+
+#### Assumptions
+List all assumptions explicitly.
+
+#### Open Questions
+List unresolved questions, if any.
+
+Then ask:
+
+> “Does this accurately reflect your intent?  
+> Please confirm or correct anything before we move to design.”
+
+**Do NOT proceed until explicit confirmation is given.**
+
+---
+
+### 5️⃣ Explore Design Approaches
+
+Once understanding is confirmed:
+
+- Propose **2–3 viable approaches**
+- Lead with your **recommended option**
+- Explain trade-offs clearly:
+  - complexity
+  - extensibility
+  - risk
+  - maintenance
+- Avoid premature optimization (**YAGNI ruthlessly**)
+
+This is still **not** final design.
+
+---
+
+### 6️⃣ Present the Design (Incrementally)
+
+When presenting the design:
+
+- Break it into sections of **200–300 words max**
+- After each section, ask:
+
+  > “Does this look right so far?”
+
+Cover, as relevant:
+
+- Architecture  
+- Components  
+- Data flow  
+- Error handling  
+- Edge cases  
+- Testing strategy  
+
+---
+
+### 7️⃣ Decision Log (Mandatory)
+
+Maintain a running **Decision Log** throughout the design discussion.
+
+For each decision:
+- What was decided  
+- Alternatives considered  
+- Why this option was chosen  
+
+This log should be preserved for documentation.
+
+---
+
+## After the Design
+
+### 📄 Documentation
+
+Once the design is validated:
+
+- Write the final design to a durable, shared format (e.g. Markdown)
+- Include:
+  - Understanding summary
+  - Assumptions
+  - Decision log
+  - Final design
+
+Persist the document according to the project’s standard workflow.
+
+---
+
+### 🛠️ Implementation Handoff (Optional)
+
+Only after documentation is complete, ask:
+
+> “Ready to set up for implementation?”
+
+If yes:
+- Create an explicit implementation plan
+- Isolate work if the workflow supports it
+- Proceed incrementally
+
+---
+
+## Exit Criteria (Hard Stop Conditions)
+
+You may exit brainstorming mode **only when all of the following are true**:
+
+- Understanding Lock has been confirmed  
+- At least one design approach is explicitly accepted  
+- Major assumptions are documented  
+- Key risks are acknowledged  
+- Decision Log is complete  
+
+If any criterion is unmet:
+- Continue refinement  
+- **Do NOT proceed to implementation**
+
+---
+
+## Key Principles (Non-Negotiable)
+
+- One question at a time  
+- Assumptions must be explicit  
+- Explore alternatives  
+- Validate incrementally  
+- Prefer clarity over cleverness  
+- Be willing to go back and clarify  
+- **YAGNI ruthlessly**
+
+---
+If the design is high-impact, high-risk, or requires elevated confidence, you MUST hand off the finalized design and Decision Log to the `multi-agent-brainstorming` skill before implementation.

package/merged-commands/brand-guidelines-anthropic.md

@@ -0,0 +1,73 @@
+---
+name: brand-guidelines
+description: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
+license: Complete terms in LICENSE.txt
+---
+
+# Anthropic Brand Styling
+
+## Overview
+
+To access Anthropic's official brand identity and style resources, use this skill.
+
+**Keywords**: branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design
+
+## Brand Guidelines
+
+### Colors
+
+**Main Colors:**
+
+- Dark: `#141413` - Primary text and dark backgrounds
+- Light: `#faf9f5` - Light backgrounds and text on dark
+- Mid Gray: `#b0aea5` - Secondary elements
+- Light Gray: `#e8e6dc` - Subtle backgrounds
+
+**Accent Colors:**
+
+- Orange: `#d97757` - Primary accent
+- Blue: `#6a9bcc` - Secondary accent
+- Green: `#788c5d` - Tertiary accent
+
+### Typography
+
+- **Headings**: Poppins (with Arial fallback)
+- **Body Text**: Lora (with Georgia fallback)
+- **Note**: Fonts should be pre-installed in your environment for best results
+
+## Features
+
+### Smart Font Application
+
+- Applies Poppins font to headings (24pt and larger)
+- Applies Lora font to body text
+- Automatically falls back to Arial/Georgia if custom fonts unavailable
+- Preserves readability across all systems
+
+### Text Styling
+
+- Headings (24pt+): Poppins font
+- Body text: Lora font
+- Smart color selection based on background
+- Preserves text hierarchy and formatting
+
+### Shape and Accent Colors
+
+- Non-text shapes use accent colors
+- Cycles through orange, blue, and green accents
+- Maintains visual interest while staying on-brand
+
+## Technical Details
+
+### Font Management
+
+- Uses system-installed Poppins and Lora fonts when available
+- Provides automatic fallback to Arial (headings) and Georgia (body)
+- No font installation required - works with existing system fonts
+- For best results, pre-install Poppins and Lora fonts in your environment
+
+### Color Application
+
+- Uses RGB color values for precise brand matching
+- Applied via python-pptx's RGBColor class
+- Maintains color fidelity across different systems

package/merged-commands/brand-guidelines-community.md

@@ -0,0 +1,73 @@
+---
+name: brand-guidelines
+description: Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.
+license: Complete terms in LICENSE.txt
+---
+
+# Anthropic Brand Styling
+
+## Overview
+
+To access Anthropic's official brand identity and style resources, use this skill.
+
+**Keywords**: branding, corporate identity, visual identity, post-processing, styling, brand colors, typography, Anthropic brand, visual formatting, visual design
+
+## Brand Guidelines
+
+### Colors
+
+**Main Colors:**
+
+- Dark: `#141413` - Primary text and dark backgrounds
+- Light: `#faf9f5` - Light backgrounds and text on dark
+- Mid Gray: `#b0aea5` - Secondary elements
+- Light Gray: `#e8e6dc` - Subtle backgrounds
+
+**Accent Colors:**
+
+- Orange: `#d97757` - Primary accent
+- Blue: `#6a9bcc` - Secondary accent
+- Green: `#788c5d` - Tertiary accent
+
+### Typography
+
+- **Headings**: Poppins (with Arial fallback)
+- **Body Text**: Lora (with Georgia fallback)
+- **Note**: Fonts should be pre-installed in your environment for best results
+
+## Features
+
+### Smart Font Application
+
+- Applies Poppins font to headings (24pt and larger)
+- Applies Lora font to body text
+- Automatically falls back to Arial/Georgia if custom fonts unavailable
+- Preserves readability across all systems
+
+### Text Styling
+
+- Headings (24pt+): Poppins font
+- Body text: Lora font
+- Smart color selection based on background
+- Preserves text hierarchy and formatting
+
+### Shape and Accent Colors
+
+- Non-text shapes use accent colors
+- Cycles through orange, blue, and green accents
+- Maintains visual interest while staying on-brand
+
+## Technical Details
+
+### Font Management
+
+- Uses system-installed Poppins and Lora fonts when available
+- Provides automatic fallback to Arial (headings) and Georgia (body)
+- No font installation required - works with existing system fonts
+- For best results, pre-install Poppins and Lora fonts in your environment
+
+### Color Application
+
+- Uses RGB color values for precise brand matching
+- Applied via python-pptx's RGBColor class
+- Maintains color fidelity across different systems