@heyai-rules/pilo-masterkit 1.2.2 → 3.1.0

package/.agent/skills/claude-api/SKILL.md

@@ -0,0 +1,337 @@
+---
+name: claude-api
+description: Anthropic Claude API patterns for Python and TypeScript. Covers Messages API, streaming, tool use, vision, extended thinking, batches, prompt caching, and Claude Agent SDK. Use when building applications with the Claude API or Anthropic SDKs.
+origin: ECC
+---
+
+# Claude API
+
+Build applications with the Anthropic Claude API and SDKs.
+
+## When to Activate
+
+- Building applications that call the Claude API
+- Code imports `anthropic` (Python) or `@anthropic-ai/sdk` (TypeScript)
+- User asks about Claude API patterns, tool use, streaming, or vision
+- Implementing agent workflows with Claude Agent SDK
+- Optimizing API costs, token usage, or latency
+
+## Model Selection
+
+| Model | ID | Best For |
+|-------|-----|----------|
+| Opus 4.1 | `claude-opus-4-1` | Complex reasoning, architecture, research |
+| Sonnet 4 | `claude-sonnet-4-0` | Balanced coding, most development tasks |
+| Haiku 3.5 | `claude-3-5-haiku-latest` | Fast responses, high-volume, cost-sensitive |
+
+Default to Sonnet 4 unless the task requires deep reasoning (Opus) or speed/cost optimization (Haiku). For production, prefer pinned snapshot IDs over aliases.
+
+## Python SDK
+
+### Installation
+
+```bash
+pip install anthropic
+```
+
+### Basic Message
+
+```python
+import anthropic
+
+client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env
+
+message = client.messages.create(
+    model="claude-sonnet-4-0",
+    max_tokens=1024,
+    messages=[
+        {"role": "user", "content": "Explain async/await in Python"}
+    ]
+)
+print(message.content[0].text)
+```
+
+### Streaming
+
+```python
+with client.messages.stream(
+    model="claude-sonnet-4-0",
+    max_tokens=1024,
+    messages=[{"role": "user", "content": "Write a haiku about coding"}]
+) as stream:
+    for text in stream.text_stream:
+        print(text, end="", flush=True)
+```
+
+### System Prompt
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-0",
+    max_tokens=1024,
+    system="You are a senior Python developer. Be concise.",
+    messages=[{"role": "user", "content": "Review this function"}]
+)
+```
+
+## TypeScript SDK
+
+### Installation
+
+```bash
+npm install @anthropic-ai/sdk
+```
+
+### Basic Message
+
+```typescript
+import Anthropic from "@anthropic-ai/sdk";
+
+const client = new Anthropic(); // reads ANTHROPIC_API_KEY from env
+
+const message = await client.messages.create({
+  model: "claude-sonnet-4-0",
+  max_tokens: 1024,
+  messages: [
+    { role: "user", content: "Explain async/await in TypeScript" }
+  ],
+});
+console.log(message.content[0].text);
+```
+
+### Streaming
+
+```typescript
+const stream = client.messages.stream({
+  model: "claude-sonnet-4-0",
+  max_tokens: 1024,
+  messages: [{ role: "user", content: "Write a haiku" }],
+});
+
+for await (const event of stream) {
+  if (event.type === "content_block_delta" && event.delta.type === "text_delta") {
+    process.stdout.write(event.delta.text);
+  }
+}
+```
+
+## Tool Use
+
+Define tools and let Claude call them:
+
+```python
+tools = [
+    {
+        "name": "get_weather",
+        "description": "Get current weather for a location",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "location": {"type": "string", "description": "City name"},
+                "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
+            },
+            "required": ["location"]
+        }
+    }
+]
+
+message = client.messages.create(
+    model="claude-sonnet-4-0",
+    max_tokens=1024,
+    tools=tools,
+    messages=[{"role": "user", "content": "What's the weather in SF?"}]
+)
+
+# Handle tool use response
+for block in message.content:
+    if block.type == "tool_use":
+        # Execute the tool with block.input
+        result = get_weather(**block.input)
+        # Send result back
+        follow_up = client.messages.create(
+            model="claude-sonnet-4-0",
+            max_tokens=1024,
+            tools=tools,
+            messages=[
+                {"role": "user", "content": "What's the weather in SF?"},
+                {"role": "assistant", "content": message.content},
+                {"role": "user", "content": [
+                    {"type": "tool_result", "tool_use_id": block.id, "content": str(result)}
+                ]}
+            ]
+        )
+```
+
+## Vision
+
+Send images for analysis:
+
+```python
+import base64
+
+with open("diagram.png", "rb") as f:
+    image_data = base64.standard_b64encode(f.read()).decode("utf-8")
+
+message = client.messages.create(
+    model="claude-sonnet-4-0",
+    max_tokens=1024,
+    messages=[{
+        "role": "user",
+        "content": [
+            {"type": "image", "source": {"type": "base64", "media_type": "image/png", "data": image_data}},
+            {"type": "text", "text": "Describe this diagram"}
+        ]
+    }]
+)
+```
+
+## Extended Thinking
+
+For complex reasoning tasks:
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-0",
+    max_tokens=16000,
+    thinking={
+        "type": "enabled",
+        "budget_tokens": 10000
+    },
+    messages=[{"role": "user", "content": "Solve this math problem step by step..."}]
+)
+
+for block in message.content:
+    if block.type == "thinking":
+        print(f"Thinking: {block.thinking}")
+    elif block.type == "text":
+        print(f"Answer: {block.text}")
+```
+
+## Prompt Caching
+
+Cache large system prompts or context to reduce costs:
+
+```python
+message = client.messages.create(
+    model="claude-sonnet-4-0",
+    max_tokens=1024,
+    system=[
+        {"type": "text", "text": large_system_prompt, "cache_control": {"type": "ephemeral"}}
+    ],
+    messages=[{"role": "user", "content": "Question about the cached context"}]
+)
+# Check cache usage
+print(f"Cache read: {message.usage.cache_read_input_tokens}")
+print(f"Cache creation: {message.usage.cache_creation_input_tokens}")
+```
+
+## Batches API
+
+Process large volumes asynchronously at 50% cost reduction:
+
+```python
+import time
+
+batch = client.messages.batches.create(
+    requests=[
+        {
+            "custom_id": f"request-{i}",
+            "params": {
+                "model": "claude-sonnet-4-0",
+                "max_tokens": 1024,
+                "messages": [{"role": "user", "content": prompt}]
+            }
+        }
+        for i, prompt in enumerate(prompts)
+    ]
+)
+
+# Poll for completion
+while True:
+    status = client.messages.batches.retrieve(batch.id)
+    if status.processing_status == "ended":
+        break
+    time.sleep(30)
+
+# Get results
+for result in client.messages.batches.results(batch.id):
+    print(result.result.message.content[0].text)
+```
+
+## Claude Agent SDK
+
+Build multi-step agents:
+
+```python
+# Note: Agent SDK API surface may change — check official docs
+import anthropic
+
+# Define tools as functions
+tools = [{
+    "name": "search_codebase",
+    "description": "Search the codebase for relevant code",
+    "input_schema": {
+        "type": "object",
+        "properties": {"query": {"type": "string"}},
+        "required": ["query"]
+    }
+}]
+
+# Run an agentic loop with tool use
+client = anthropic.Anthropic()
+messages = [{"role": "user", "content": "Review the auth module for security issues"}]
+
+while True:
+    response = client.messages.create(
+        model="claude-sonnet-4-0",
+        max_tokens=4096,
+        tools=tools,
+        messages=messages,
+    )
+    if response.stop_reason == "end_turn":
+        break
+    # Handle tool calls and continue the loop
+    messages.append({"role": "assistant", "content": response.content})
+    # ... execute tools and append tool_result messages
+```
+
+## Cost Optimization
+
+| Strategy | Savings | When to Use |
+|----------|---------|-------------|
+| Prompt caching | Up to 90% on cached tokens | Repeated system prompts or context |
+| Batches API | 50% | Non-time-sensitive bulk processing |
+| Haiku instead of Sonnet | ~75% | Simple tasks, classification, extraction |
+| Shorter max_tokens | Variable | When you know output will be short |
+| Streaming | None (same cost) | Better UX, same price |
+
+## Error Handling
+
+```python
+import time
+
+from anthropic import APIError, RateLimitError, APIConnectionError
+
+try:
+    message = client.messages.create(...)
+except RateLimitError:
+    # Back off and retry
+    time.sleep(60)
+except APIConnectionError:
+    # Network issue, retry with backoff
+    pass
+except APIError as e:
+    print(f"API error {e.status_code}: {e.message}")
+```
+
+## Environment Setup
+
+```bash
+# Required
+export ANTHROPIC_API_KEY="your-api-key-here"
+
+# Optional: set default model
+export ANTHROPIC_MODEL="claude-sonnet-4-0"
+```
+
+Never hardcode API keys. Always use environment variables.

package/.agent/skills/claude-devfleet/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: claude-devfleet
+description: Orchestrate multi-agent coding tasks via Claude DevFleet — plan projects, dispatch parallel agents in isolated worktrees, monitor progress, and read structured reports.
+origin: community
+---
+
+# Claude DevFleet Multi-Agent Orchestration
+
+## When to Use
+
+Use this skill when you need to dispatch multiple Claude Code agents to work on coding tasks in parallel. Each agent runs in an isolated git worktree with full tooling.
+
+Requires a running Claude DevFleet instance connected via MCP:
+```bash
+claude mcp add devfleet --transport http http://localhost:18801/mcp
+```
+
+## How It Works
+
+```
+User → "Build a REST API with auth and tests"
+  ↓
+plan_project(prompt) → project_id + mission DAG
+  ↓
+Show plan to user → get approval
+  ↓
+dispatch_mission(M1) → Agent 1 spawns in worktree
+  ↓
+M1 completes → auto-merge → auto-dispatch M2 (depends_on M1)
+  ↓
+M2 completes → auto-merge
+  ↓
+get_report(M2) → files_changed, what_done, errors, next_steps
+  ↓
+Report back to user
+```
+
+### Tools
+
+| Tool | Purpose |
+|------|---------|
+| `plan_project(prompt)` | AI breaks a description into a project with chained missions |
+| `create_project(name, path?, description?)` | Create a project manually, returns `project_id` |
+| `create_mission(project_id, title, prompt, depends_on?, auto_dispatch?)` | Add a mission. `depends_on` is a list of mission ID strings (e.g., `["abc-123"]`). Set `auto_dispatch=true` to auto-start when deps are met. |
+| `dispatch_mission(mission_id, model?, max_turns?)` | Start an agent on a mission |
+| `cancel_mission(mission_id)` | Stop a running agent |
+| `wait_for_mission(mission_id, timeout_seconds?)` | Block until a mission completes (see note below) |
+| `get_mission_status(mission_id)` | Check mission progress without blocking |
+| `get_report(mission_id)` | Read structured report (files changed, tested, errors, next steps) |
+| `get_dashboard()` | System overview: running agents, stats, recent activity |
+| `list_projects()` | Browse all projects |
+| `list_missions(project_id, status?)` | List missions in a project |
+
+> **Note on `wait_for_mission`:** This blocks the conversation for up to `timeout_seconds` (default 600). For long-running missions, prefer polling with `get_mission_status` every 30–60 seconds instead, so the user sees progress updates.
+
+### Workflow: Plan → Dispatch → Monitor → Report
+
+1. **Plan**: Call `plan_project(prompt="...")` → returns `project_id` + list of missions with `depends_on` chains and `auto_dispatch=true`.
+2. **Show plan**: Present mission titles, types, and dependency chain to the user.
+3. **Dispatch**: Call `dispatch_mission(mission_id=<first_mission_id>)` on the root mission (empty `depends_on`). Remaining missions auto-dispatch as their dependencies complete (because `plan_project` sets `auto_dispatch=true` on them).
+4. **Monitor**: Call `get_mission_status(mission_id=...)` or `get_dashboard()` to check progress.
+5. **Report**: Call `get_report(mission_id=...)` when missions complete. Share highlights with the user.
+
+### Concurrency
+
+DevFleet runs up to 3 concurrent agents by default (configurable via `DEVFLEET_MAX_AGENTS`). When all slots are full, missions with `auto_dispatch=true` queue in the mission watcher and dispatch automatically as slots free up. Check `get_dashboard()` for current slot usage.
+
+## Examples
+
+### Full auto: plan and launch
+
+1. `plan_project(prompt="...")` → shows plan with missions and dependencies.
+2. Dispatch the first mission (the one with empty `depends_on`).
+3. Remaining missions auto-dispatch as dependencies resolve (they have `auto_dispatch=true`).
+4. Report back with project ID and mission count so the user knows what was launched.
+5. Poll with `get_mission_status` or `get_dashboard()` periodically until all missions reach a terminal state (`completed`, `failed`, or `cancelled`).
+6. `get_report(mission_id=...)` for each terminal mission — summarize successes and call out failures with errors and next steps.
+
+### Manual: step-by-step control
+
+1. `create_project(name="My Project")` → returns `project_id`.
+2. `create_mission(project_id=project_id, title="...", prompt="...", auto_dispatch=true)` for the first (root) mission → capture `root_mission_id`.
+   `create_mission(project_id=project_id, title="...", prompt="...", auto_dispatch=true, depends_on=["<root_mission_id>"])` for each subsequent task.
+3. `dispatch_mission(mission_id=...)` on the first mission to start the chain.
+4. `get_report(mission_id=...)` when done.
+
+### Sequential with review
+
+1. `create_project(name="...")` → get `project_id`.
+2. `create_mission(project_id=project_id, title="Implement feature", prompt="...")` → get `impl_mission_id`.
+3. `dispatch_mission(mission_id=impl_mission_id)`, then poll with `get_mission_status` until complete.
+4. `get_report(mission_id=impl_mission_id)` to review results.
+5. `create_mission(project_id=project_id, title="Review", prompt="...", depends_on=[impl_mission_id], auto_dispatch=true)` — auto-starts since the dependency is already met.
+
+## Guidelines
+
+- Always confirm the plan with the user before dispatching, unless they said to go ahead.
+- Include mission titles and IDs when reporting status.
+- If a mission fails, read its report before retrying.
+- Check `get_dashboard()` for agent slot availability before bulk dispatching.
+- Mission dependencies form a DAG — do not create circular dependencies.
+- Each agent runs in an isolated git worktree and auto-merges on completion. If a merge conflict occurs, the changes remain on the agent's worktree branch for manual resolution.
+- When manually creating missions, always set `auto_dispatch=true` if you want them to trigger automatically when dependencies complete. Without this flag, missions stay in `draft` status.

package/.agent/skills/click-path-audit/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: click-path-audit
+description: "Trace every user-facing button/touchpoint through its full state change sequence to find bugs where functions individually work but cancel each other out, produce wrong final state, or leave the UI in an inconsistent state. Use when: systematic debugging found no bugs but users report broken buttons, or after any major refactor touching shared state stores."
+origin: community
+---
+
+# /click-path-audit — Behavioural Flow Audit
+
+Find bugs that static code reading misses: state interaction side effects, race conditions between sequential calls, and handlers that silently undo each other.
+
+## The Problem This Solves
+
+Traditional debugging checks:
+- Does the function exist? (missing wiring)
+- Does it crash? (runtime errors)
+- Does it return the right type? (data flow)
+
+But it does NOT check:
+- **Does the final UI state match what the button label promises?**
+- **Does function B silently undo what function A just did?**
+- **Does shared state (Zustand/Redux/context) have side effects that cancel the intended action?**
+
+Real example: A "New Email" button called `setComposeMode(true)` then `selectThread(null)`. Both worked individually. But `selectThread` had a side effect resetting `composeMode: false`. The button did nothing. 54 bugs were found by systematic debugging — this one was missed.
+
+---
+
+## How It Works
+
+For EVERY interactive touchpoint in the target area:
+
+```
+1. IDENTIFY the handler (onClick, onSubmit, onChange, etc.)
+2. TRACE every function call in the handler, IN ORDER
+3. For EACH function call:
+   a. What state does it READ?
+   b. What state does it WRITE?
+   c. Does it have SIDE EFFECTS on shared state?
+   d. Does it reset/clear any state as a side effect?
+4. CHECK: Does any later call UNDO a state change from an earlier call?
+5. CHECK: Is the FINAL state what the user expects from the button label?
+6. CHECK: Are there race conditions (async calls that resolve in wrong order)?
+```
+
+---
+
+## Execution Steps
+
+### Step 1: Map State Stores
+
+Before auditing any touchpoint, build a side-effect map of every state store action:
+
+```
+For each Zustand store / React context in scope:
+  For each action/setter:
+    - What fields does it set?
+    - Does it RESET other fields as a side effect?
+    - Document: actionName → {sets: [...], resets: [...]}
+```
+
+This is the critical reference. The "New Email" bug was invisible without knowing that `selectThread` resets `composeMode`.
+
+**Output format:**
+```
+STORE: emailStore
+  setComposeMode(bool) → sets: {composeMode}
+  selectThread(thread|null) → sets: {selectedThread, selectedThreadId, messages, drafts, selectedDraft, summary} RESETS: {composeMode: false, composeData: null, redraftOpen: false}
+  setDraftGenerating(bool) → sets: {draftGenerating}
+  ...
+
+DANGEROUS RESETS (actions that clear state they don't own):
+  selectThread → resets composeMode (owned by setComposeMode)
+  reset → resets everything
+```
+
+### Step 2: Audit Each Touchpoint
+
+For each button/toggle/form submit in the target area:
+
+```
+TOUCHPOINT: [Button label] in [Component:line]
+  HANDLER: onClick → {
+    call 1: functionA() → sets {X: true}
+    call 2: functionB() → sets {Y: null} RESETS {X: false}  ← CONFLICT
+  }
+  EXPECTED: User sees [description of what button label promises]
+  ACTUAL: X is false because functionB reset it
+  VERDICT: BUG — [description]
+```
+
+**Check each of these bug patterns:**
+
+#### Pattern 1: Sequential Undo
+```
+handler() {
+  setState_A(true)     // sets X = true
+  setState_B(null)     // side effect: resets X = false
+}
+// Result: X is false. First call was pointless.
+```
+
+#### Pattern 2: Async Race
+```
+handler() {
+  fetchA().then(() => setState({ loading: false }))
+  fetchB().then(() => setState({ loading: true }))
+}
+// Result: final loading state depends on which resolves first
+```
+
+#### Pattern 3: Stale Closure
+```
+const [count, setCount] = useState(0)
+const handler = useCallback(() => {
+  setCount(count + 1)  // captures stale count
+  setCount(count + 1)  // same stale count — increments by 1, not 2
+}, [count])
+```
+
+#### Pattern 4: Missing State Transition
+```
+// Button says "Save" but handler only validates, never actually saves
+// Button says "Delete" but handler sets a flag without calling the API
+// Button says "Send" but the API endpoint is removed/broken
+```
+
+#### Pattern 5: Conditional Dead Path
+```
+handler() {
+  if (someState) {        // someState is ALWAYS false at this point
+    doTheActualThing()    // never reached
+  }
+}
+```
+
+#### Pattern 6: useEffect Interference
+```
+// Button sets stateX = true
+// A useEffect watches stateX and resets it to false
+// User sees nothing happen
+```
+
+### Step 3: Report
+
+For each bug found:
+
+```
+CLICK-PATH-NNN: [severity: CRITICAL/HIGH/MEDIUM/LOW]
+  Touchpoint: [Button label] in [file:line]
+  Pattern: [Sequential Undo / Async Race / Stale Closure / Missing Transition / Dead Path / useEffect Interference]
+  Handler: [function name or inline]
+  Trace:
+    1. [call] → sets {field: value}
+    2. [call] → RESETS {field: value}  ← CONFLICT
+  Expected: [what user expects]
+  Actual: [what actually happens]
+  Fix: [specific fix]
+```
+
+---
+
+## Scope Control
+
+This audit is expensive. Scope it appropriately:
+
+- **Full app audit:** Use when launching or after major refactor. Launch parallel agents per page.
+- **Single page audit:** Use after building a new page or after a user reports a broken button.
+- **Store-focused audit:** Use after modifying a Zustand store — audit all consumers of the changed actions.
+
+### Recommended agent split for full app:
+
+```
+Agent 1: Map ALL state stores (Step 1) — this is shared context for all other agents
+Agent 2: Dashboard (Tasks, Notes, Journal, Ideas)
+Agent 3: Chat (DanteChatColumn, JustChatPage)
+Agent 4: Emails (ThreadList, DraftArea, EmailsPage)
+Agent 5: Projects (ProjectsPage, ProjectOverviewTab, NewProjectWizard)
+Agent 6: CRM (all sub-tabs)
+Agent 7: Profile, Settings, Vault, Notifications
+Agent 8: Management Suite (all pages)
+```
+
+Agent 1 MUST complete first. Its output is input for all other agents.
+
+---
+
+## When to Use
+
+- After systematic debugging finds "no bugs" but users report broken UI
+- After modifying any Zustand store action (check all callers)
+- After any refactor that touches shared state
+- Before release, on critical user flows
+- When a button "does nothing" — this is THE tool for that
+
+## When NOT to Use
+
+- For API-level bugs (wrong response shape, missing endpoint) — use systematic-debugging
+- For styling/layout issues — visual inspection
+- For performance issues — profiling tools
+
+---
+
+## Integration with Other Skills
+
+- Run AFTER `/superpowers:systematic-debugging` (which finds the other 54 bug types)
+- Run BEFORE `/superpowers:verification-before-completion` (which verifies fixes work)
+- Feeds into `/superpowers:test-driven-development` — every bug found here should get a test
+
+---
+
+## Example: The Bug That Inspired This Skill
+
+**ThreadList.tsx "New Email" button:**
+```
+onClick={() => {
+  useEmailStore.getState().setComposeMode(true)   // ✓ sets composeMode = true
+  useEmailStore.getState().selectThread(null)      // ✗ RESETS composeMode = false
+}}
+```
+
+Store definition:
+```
+selectThread: (thread) => set({
+  selectedThread: thread,
+  selectedThreadId: thread?.id ?? null,
+  messages: [],
+  drafts: [],
+  selectedDraft: null,
+  summary: null,
+  composeMode: false,     // ← THIS silent reset killed the button
+  composeData: null,
+  redraftOpen: false,
+})
+```
+
+**Systematic debugging missed it** because:
+- The button has an onClick handler (not dead)
+- Both functions exist (no missing wiring)
+- Neither function crashes (no runtime error)
+- The data types are correct (no type mismatch)
+
+**Click-path audit catches it** because:
+- Step 1 maps `selectThread` resets `composeMode`
+- Step 2 traces the handler: call 1 sets true, call 2 resets false
+- Verdict: Sequential Undo — final state contradicts button intent