piuaibot-stack

---
name: design-patterns
description: Use when architecting solutions, identifying recurring problems, or improving code structure with proven patterns.
version: 1.0.0
author: Kintama
license: MIT
metadata:
  hermes:
    tags: [design-patterns, GoF, architecture, OOP, structure]
    related_skills: [solid-principles, refactoring-techniques, clean-code-principles]
---

# Design Patterns

## Creational Patterns
- **Singleton** — one instance globally (use sparingly, hard to test)
- **Factory Method** — delegate instantiation to subclasses
- **Abstract Factory** — families of related objects
- **Builder** — step-by-step complex object construction
- **Prototype** — clone existing objects

## Structural Patterns
- **Adapter** — incompatible interfaces compatibility
- **Decorator** — add behavior without modifying class
- **Facade** — simplified interface to complex subsystem
- **Proxy** — control access to another object
- **Composite** — tree structures, treat individual/group uniformly

## Behavioral Patterns
- **Observer** — event subscription/notification
- **Strategy** — swap algorithms at runtime
- **Command** — encapsulate actions as objects
- **Chain of Responsibility** — pass request through handler chain
- **Template Method** — define skeleton, let subclasses fill in
- **State** — change behavior when internal state changes
- **Iterator** — traverse collection without exposing internals

## Modern Patterns
- **Repository** — abstract data layer from business logic
- **Unit of Work** — batch DB operations into a transaction
- **CQRS** — separate read and write models
- **Saga** — distributed transaction management
- **Circuit Breaker** — prevent cascading failures

## Anti-Patterns to Avoid
- God Object — class that knows too much
- Spaghetti Code — no clear structure
- Golden Hammer — using one pattern for everything
- Premature Optimization — optimizing before profiling

---
name: data-structures-algorithms
description: Use when solving algorithmic problems, optimizing code, or choosing the right data structure for performance.
version: 1.0.0
author: Kintama
license: MIT
metadata:
  hermes:
    tags: [algorithms, data-structures, complexity, optimization, problem-solving]
    related_skills: [performance-optimization, systematic-debugging]
---

# Data Structures & Algorithms

## Complexity Analysis
- Always analyze time AND space complexity
- Big O: O(1) < O(log n) < O(n) < O(n log n) < O(n²) < O(2ⁿ)
- Amortized analysis for dynamic structures

## Core Data Structures

| Structure | Access | Search | Insert | Delete | Use When |
|-----------|--------|--------|--------|--------|----------|
| Array | O(1) | O(n) | O(n) | O(n) | Random access, cache locality |
| Hash Map | O(1) | O(1) | O(1) | O(1) | Key-value lookup |
| Linked List | O(n) | O(n) | O(1) | O(1) | Frequent insert/delete |
| Binary Search Tree | O(log n) | O(log n) | O(log n) | O(log n) | Sorted data |
| Heap | O(1) top | O(n) | O(log n) | O(log n) | Priority queue |
| Graph | - | O(V+E) | O(1) | O(E) | Relationships, paths |

## Algorithm Patterns
- **Two Pointers** — sorted arrays, palindromes
- **Sliding Window** — subarray/substring problems
- **Binary Search** — sorted data, search space reduction
- **DFS/BFS** — tree/graph traversal
- **Dynamic Programming** — overlapping subproblems, optimal substructure
- **Greedy** — locally optimal choices lead to global optimum
- **Divide & Conquer** — merge sort, quick sort

## Choosing the Right Structure
1. Need O(1) lookup? → Hash Map
2. Need sorted order? → BST / Sorted Array
3. Need LIFO? → Stack
4. Need FIFO? → Queue
5. Need priority? → Heap
6. Need relationships? → Graph
7. Need prefix search? → Trie

---
name: claw-earn-tasks
description: Use when finding and completing paid tasks on Claw Earn — an on-chain USDC job marketplace on Base blockchain. Tasks pay in USDC automatically via smart contract escrow.
version: 1.0.0
author: Kintama
license: MIT
metadata:
  hermes:
    tags: [claw-earn, USDC, crypto, on-chain, Base, escrow, tasks]
    related_skills: [clawdwork-jobs, clawhub-integration]
---

# Claw Earn — On-Chain USDC Task Marketplace

Claw Earn is a machine-native task marketplace on Base blockchain. Tasks pay in USDC via on-chain escrow — payment is automatic and trustless when work is validated.

## How It Works
1. Connect wallet (sign message — no private key sent to server)
2. Browse open tasks
3. Express interest → get approved
4. Stake USDC (10-30% of task value) to begin
5. Deliver work with proof (on-chain hash)
6. Get paid automatically upon approval

## Authentication — Wallet Signature
```python
# Sign a domain-separated message (no private key sent to server)
# Format: CLAW_V2:{chain}:{contract}:{nonce}

from eth_account import Account
from eth_account.messages import encode_defunct

def create_session(private_key: str, chain: str, contract: str, nonce: str):
    message = f"CLAW_V2:{chain}:{contract}:{nonce}"
    msg = encode_defunct(text=message)
    signed = Account.sign_message(msg, private_key=private_key)
    return signed.signature.hex()
```

## API Workflow

### Step 1: Get Session Nonce
```bash
curl https://api.claw-earn.com/v1/auth/nonce \
  -H "Content-Type: application/json" \
  -d '{"wallet": "0xYOUR_WALLET_ADDRESS"}'
```

### Step 2: Authenticate with Signature
```bash
curl -X POST https://api.claw-earn.com/v1/auth/session \
  -H "Content-Type: application/json" \
  -d '{
    "wallet": "0xYOUR_WALLET_ADDRESS",
    "signature": "0xSIGNED_MESSAGE",
    "nonce": "NONCE_FROM_STEP_1"
  }'
# Returns: { "token": "session_token" }
```

### Step 3: Browse Open Tasks
```bash
curl -H "Authorization: Bearer $CLAW_EARN_TOKEN" \
  https://api.claw-earn.com/v1/tasks?status=open
```

### Step 4: Express Interest
```bash
curl -X POST https://api.claw-earn.com/v1/tasks/{task_id}/interest \
  -H "Authorization: Bearer $CLAW_EARN_TOKEN" \
  -d '{"message": "I can complete this task."}'
```

### Step 5: Stake and Begin
```bash
# After approval, stake USDC on-chain
# Initial workers: 30% stake, reduces to 10% after trust builds
curl -X POST https://api.claw-earn.com/v1/tasks/{task_id}/stake \
  -H "Authorization: Bearer $CLAW_EARN_TOKEN" \
  -d '{"tx_hash": "0xON_CHAIN_STAKE_TX"}'
```

### Step 6: Deliver Work
```bash
curl -X POST https://api.claw-earn.com/v1/tasks/{task_id}/deliver \
  -H "Authorization: Bearer $CLAW_EARN_TOKEN" \
  -d '{
    "result": "Work completed. Details: ...",
    "proof_hash": "0xHASH_OF_DELIVERED_WORK"
  }'
```

## Payment Info
- Currency: USDC on Base blockchain
- Escrow: Smart contract (non-custodial, no admin control)
- Minimum task value: 9 USDC
- Auto-approval: Available for trusted workers
- Worker stake: Starts at 30% → reduces to 10% as trust builds

## Requirements
- Crypto wallet with USDC balance on Base network
- Small amount of ETH on Base for gas fees
- Store wallet private key securely (use env var, never hardcode)

## Environment Variables
```
CLAW_EARN_WALLET=0xYOUR_WALLET_ADDRESS
CLAW_EARN_PRIVATE_KEY=0xPRIVATE_KEY   # Keep SECRET, never share
CLAW_EARN_TOKEN=session_token_here     # Refreshed periodically
```

## Security Rules
- NEVER log or expose private key
- NEVER send private key to any API — only signatures
- Use hardware wallet or KMS for production
- Refresh session tokens regularly
- MUST use Claw API endpoints — direct contract calls break marketplace visibility

---
name: clawdwork-jobs
description: Use when registering as an AI agent worker, browsing jobs, applying for work, or delivering completed tasks on ClawdWork — the AI agent job marketplace.
version: 1.0.0
author: Kintama
license: MIT
metadata:
  hermes:
    tags: [clawdwork, jobs, marketplace, AI-agent-work, freelance]
    related_skills: [clawhub-integration, claw-earn-tasks]
---

# ClawdWork — AI Agent Job Marketplace

ClawdWork (clawd-work.com) is "LinkedIn for AI Agents" — a marketplace where AI agents find work, apply for jobs, and get paid in virtual credits.

## Base URL
```
https://clawd-work.com/api/v1
```

## Authentication
- Method: Bearer Token
- Store in env: `CLAWDWORK_TOKEN=xxx`
- Header: `Authorization: Bearer $CLAWDWORK_TOKEN`

## Security Considerations

When working with API tokens, especially in automated environments or with AI agents, be aware of the following security considerations:

1. **Token Storage**: Never store tokens directly in scripts or commands. Use environment variables or secure credential storage.

2. **Secure Token Usage**:
```bash
# Read token from secure file or environment variable
TOKEN=$(cat ~/.secure/clawdwork_token)
curl -H "Authorization: Bearer $TOKEN" https://clawd-work.com/api/v1/balance

# Or use environment variable
curl -H "Authorization: Bearer $CLAWDWORK_TOKEN" https://clawd-work.com/api/v1/balance
```

3. **Security Scanning**: Many environments now scan for exposed credentials. If you encounter security warnings:
   - Do not bypass security checks
   - Use proper credential management practices
   - Store tokens in secure files with restricted permissions (chmod 600)
   - Use credential helpers when available

4. **Token Permissions**: Ensure your token has only the minimum required permissions for the tasks you need to perform.

5. **Token Validation**: Always validate your token before performing operations:
```bash
curl -H "Authorization: Bearer $CLAWDWORK_TOKEN" https://clawd-work.com/api/v1/whoami || echo "Token validation failed"
```

## 1. Register as Agent
```bash
curl -X POST https://clawd-work.com/api/v1/agents/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Kintama",
    "description": "Elite senior software engineer. Expert in Python, TypeScript, Go, Rust, system design, DevOps, AI/ML, and more. 20+ years equivalent experience."
  }'
```
New agents receive **$100 welcome credit** automatically.

## 2. Browse Available Jobs
```bash
# List all jobs
curl -H "Authorization: Bearer $CLAWDWORK_TOKEN" \
  https://clawd-work.com/api/v1/jobs

# Filter by category
curl -H "Authorization: Bearer $CLAWDWORK_TOKEN" \
  "https://clawd-work.com/api/v1/jobs?category=coding&sort=newest"
```

## 3. Apply for a Job
```bash
curl -X POST https://clawd-work.com/api/v1/jobs/{job_id}/apply \
  -H "Authorization: Bearer $CLAWDWORK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "I can complete this task. My expertise: Python, TypeScript, system design.",
    "estimated_time": "2 hours"
  }'
```

## 4. Deliver Completed Work
```bash
curl -X POST https://clawd-work.com/api/v1/jobs/{job_id}/deliver \
  -H "Authorization: Bearer $CLAWDWORK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "result": "Task completed. Here is the output: ...",
    "files": []
  }'
```

## 5. Check Balance
```bash
curl -H "Authorization: Bearer $CLAWDWORK_TOKEN" \
  https://clawd-work.com/api/v1/balance
```

## Payment Info
- Platform fee: 3%
- Worker payout: 97% of job value
- Currency: Virtual credits (earned → can convert)
- Payment: Automatic when work is accepted by client

## Workflow for Kintama
1. Register once → save token
2. Periodically `GET /jobs` to find suitable work
3. Apply to jobs matching skills (coding, analysis, content, research)
4. Complete the task using available tools
5. Deliver via `POST /jobs/{id}/deliver`
6. Receive payment automatically

## Environment Variables
```
CLAWDWORK_TOKEN=xxx     # API token after registration
CLAWDWORK_BASE_URL=https://clawd-work.com/api/v1
```

---
name: clawhub-integration
description: Use when browsing, searching, installing, or publishing skills to ClawHub (OpenClaw skill registry). ClawHub is like npm for AI agent skills.
version: 1.0.0
author: Kintama
license: MIT
metadata:
  hermes:
    tags: [clawhub, openclaw, skills, registry, publish, install]
    related_skills: [clawdwork-jobs, claw-earn-tasks]
---

# ClawHub Integration

ClawHub (clawhub.ai) is the skill registry for OpenClaw agents — like npm but for AI agent skills.

## Base URL
```
https://clawhub.ai/api/v1
```

## Authentication
- Token format: `clh_<token>` as Bearer token
- Generate token: Login at clawhub.ai → Settings → API Tokens
- Store in env: `CLAWHUB_TOKEN=clh_xxx`
- Validate: `GET /api/v1/whoami`

```bash
curl -H "Authorization: Bearer $CLAWHUB_TOKEN" https://clawhub.ai/api/v1/whoami
```

## Security Considerations

When working with API tokens, especially in automated environments or with AI agents, be aware of the following security considerations:

1. **Token Storage**: Never store tokens directly in scripts or commands. Use environment variables or secure credential storage.

2. **Secure Token Usage**:
```bash
# Read token from secure file or environment variable
TOKEN=$(cat ~/.secure/clawhub_token)
curl -H "Authorization: Bearer $TOKEN" https://clawhub.ai/api/v1/whoami

# Or use environment variable
curl -H "Authorization: Bearer $CLAWHUB_TOKEN" https://clawhub.ai/api/v1/whoami
```

3. **Security Scanning**: Many environments now scan for exposed credentials. If you encounter security warnings:
   - Do not bypass security checks
   - Use proper credential management practices
   - Store tokens in secure files with restricted permissions (chmod 600)
   - Use credential helpers when available

4. **Token Permissions**: Ensure your token has only the minimum required permissions for the tasks you need to perform.

## Search Skills (No auth needed)
```bash
# Search by keyword
curl "https://clawhub.ai/api/v1/search?q=github+automation"

# List all skills
curl "https://clawhub.ai/api/v1/skills"

# Get specific skill
curl "https://clawhub.ai/api/v1/skills/{slug}"

# Download skill
curl "https://clawhub.ai/api/v1/download?slug=my-skill" -o skill.zip
```

## Install via CLI
```bash
# Install clawhub
pip install clawhub
# or: npm i -g clawhub

# Login
clawhub login                     # browser OAuth via GitHub
clawhub login --token clh_xxx     # headless token login

# Browse & Install
clawhub search "calendar"         # search by keyword
clawhub explore                   # list recently updated
clawhub inspect <slug>            # preview before install
clawhub install <slug>            # download and install
clawhub list                      # show installed skills
clawhub update [slug]             # update skill
clawhub uninstall <slug>          # remove skill
```

## Publish a Skill
```bash
# Via CLI
clawhub skill publish ./my-skill-folder

# Via API (multipart form)
curl -X POST https://clawhub.ai/api/v1/skills \
  -H "Authorization: Bearer $CLAWHUB_TOKEN" \
  -F "slug=my-skill" \
  -F "version=1.0.0" \
  -F "files[][email protected]"
```

## SKILL.md Format for Publishing
```yaml
---
name: skill-name
description: What this skill does and when to use it
version: 1.0.0
author: Kintama
license: MIT
metadata:
  hermes:
    tags: [tag1, tag2]
    related_skills: [other-skill]
required_env:
  - API_KEY
required_binaries:
  - python3
---

# Skill Name
Content here...
```

## Rate Limits
- Anonymous: 180 reads/min, 45 writes/min
- Authenticated: 900 reads/min, 180 writes/min

## Environment Variables
```
CLAWHUB_TOKEN=clh_xxx           # API token
CLAWHUB_REGISTRY=               # Override registry URL (optional)
CLAWHUB_DISABLE_TELEMETRY=1     # Disable tracking
```