@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/lisa-expo/skills/agent-design-best-practices/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: agent-design-best-practices
+description: Best practices for designing Claude Code agent files (.claude/agents/*.md). This skill should be used when writing or reviewing agent markdown files to ensure proper design with focused domains, correct tool access, reusable definitions, and separation of capabilities from lifecycle. Combines Anthropic's official guidance with battle-tested patterns from agent team usage.
+---
+
+# Agent Design Best Practices
+
+## Overview
+
+This skill defines best practices for designing Claude Code agent files (`.claude/agents/*.md`). Agent files define reusable roles that can be spawned as subagents or teammates. The core principle is that **agent files define capabilities, not lifecycle** -- the team lead's spawn prompt controls when and how the agent runs.
+
+## Principles
+
+### 1. Define Capabilities, Not Lifecycle
+
+Agent files describe *what* an agent can do. The spawn prompt from the team lead controls *when* it runs and *what to focus on*.
+
+```markdown
+<!-- Wrong: Hardcodes workflow phase and interaction pattern -->
+# Security Planner Agent
+
+You are a security specialist in a plan-create Agent Team.
+Given a Research Brief from the team lead, identify security
+considerations for the planned changes.
+
+## Output Format
+
+Send your sub-plan to the team lead via `SendMessage` with this structure:
+...
+```
+
+```markdown
+<!-- Correct: Defines domain expertise, team lead controls usage -->
+# Security Specialist Agent
+
+You are a security specialist who identifies vulnerabilities,
+evaluates threats, and recommends mitigations for code changes.
+
+## Analysis Process
+1. Read affected files
+2. STRIDE analysis
+3. Check input validation
+...
+```
+
+The wrong version is coupled to one workflow ("plan-create Agent Team", "Given a Research Brief", "Send via SendMessage"). The correct version works in any context -- planning, review, ad-hoc analysis -- because the team lead's spawn prompt provides the specific instructions.
+
+### 2. One Agent Per Domain, Not Per Phase
+
+Prefer a single agent that covers a domain over multiple agents split by workflow phase. The team lead specializes the agent per phase via the spawn prompt.
+
+| Wrong | Right |
+|-------|-------|
+| `security-planner` + `security-reviewer` | `security-specialist` |
+| `test-strategist` + `test-coverage-agent` | `test-specialist` |
+| `architecture-planner` + `architecture-reviewer` | `architecture-specialist` |
+
+The same agent type can be spawned multiple times with different prompts for different phases. A `security-specialist` spawned during planning gets "evaluate this plan for security risks" while the same type spawned during review gets "review these code changes for vulnerabilities."
+
+### 3. Design Focused Domains
+
+Each agent should excel at one specific domain. The domain should be broad enough to avoid workflow coupling but narrow enough to provide real expertise.
+
+```yaml
+# Too narrow (coupled to one workflow step)
+description: Performs STRIDE analysis on Research Briefs during plan-create Phase 2
+
+# Too broad (no clear expertise)
+description: General-purpose agent that can do anything
+
+# Just right (focused domain, reusable across workflows)
+description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling.
+```
+
+### 4. Write Detailed Descriptions
+
+Claude uses the `description` field in YAML frontmatter to decide when to delegate tasks. Be specific about what the agent does and when it adds value.
+
+```yaml
+# Bad: Vague, Claude can't decide when to use it
+description: Reviews code
+
+# Good: Specific domain, clear trigger conditions
+description: Security specialist. Performs threat modeling (STRIDE), reviews code for OWASP Top 10 vulnerabilities, checks auth/validation/secrets handling, and recommends mitigations.
+```
+
+### 5. Limit Tool Access
+
+Grant only the tools necessary for the agent's domain. This enforces focus and prevents agents from exceeding their intended scope.
+
+| Agent Type | Appropriate Tools | Rationale |
+|-----------|-------------------|-----------|
+| Researcher / Reviewer | `Read, Grep, Glob, Bash` | Read-only analysis, no file modifications |
+| Implementer | `Read, Write, Edit, Bash, Grep, Glob` | Needs to modify code |
+| Planner | `Read, Grep, Glob` | Research only, no execution |
+
+Read-only agents cannot implement code. Do not assign implementation tasks to agents without `Write` and `Edit` tools.
+
+### 6. No Hardcoded Interaction Patterns
+
+Do not prescribe how the agent communicates or what input format it expects. The team lead's spawn prompt handles interaction patterns.
+
+```markdown
+<!-- Wrong: Hardcodes communication protocol -->
+## Input
+You receive a **Research Brief** from the team lead containing...
+
+## Output Format
+Send your sub-plan to the team lead via `SendMessage` with this structure:
+```
+
+```markdown
+<!-- Correct: Defines output structure without prescribing delivery mechanism -->
+## Output Format
+Structure your findings as:
+
+### Threat Model (STRIDE)
+| Threat | Applies? | Description | Mitigation |
+...
+```
+
+The output format itself is fine to define -- it provides structure. But how the agent receives input and delivers output should be left to the team lead.
+
+### 7. Context Window Isolation
+
+Each teammate has its own context window. Teammates do not share context and cannot see what other teammates have done. Account for this in agent design:
+
+- Do not assume the agent has seen previous analysis from other agents
+- Include enough domain knowledge in the agent file for independent operation
+- The team lead bridges context between agents via spawn prompts and messages
+
+### 8. File Ownership in Teams
+
+When agents work in teams, each teammate should own distinct files or directories. Two teammates editing the same file leads to conflicts and lost work.
+
+Design agent domains so their file ownership naturally separates:
+
+| Agent | Owns |
+|-------|------|
+| `implementer` | Source files (`src/`) |
+| `test-specialist` | Test files (`tests/`) |
+| `quality-specialist` | No files (read-only) |
+
+## Agent File Structure
+
+### Required Frontmatter
+
+```yaml
+---
+name: agent-name           # lowercase with hyphens
+description: When and why to use this agent. Be specific.
+tools: Read, Grep, Glob     # comma-separated, minimal set
+---
+```
+
+### Optional Frontmatter
+
+```yaml
+model: sonnet              # sonnet, opus, haiku, or inherit (default)
+permissionMode: default     # default, acceptEdits, plan, bypassPermissions, etc.
+maxTurns: 50               # limit agentic turns
+skills:                     # skills to preload
+  - skill-name
+memory: user                # persistent memory: user, project, or local
+```
+
+### Body Structure
+
+The markdown body becomes the agent's system prompt. Structure it as:
+
+1. **Role statement** -- one sentence describing what the agent is
+2. **Analysis/workflow process** -- numbered steps for the agent's approach
+3. **Output format** -- structure for findings (without prescribing delivery mechanism)
+4. **Rules/constraints** -- guardrails for the agent's behavior
+
+## Anti-Patterns
+
+### Don't Create Phase-Specific Agents
+
+```markdown
+<!-- Wrong: Two agents for the same domain, split by phase -->
+# Pre-Implementation Security Planner
+...
+# Post-Implementation Security Reviewer
+...
+
+<!-- Correct: One agent, team lead controls timing -->
+# Security Specialist
+...
+```
+
+### Don't Hardcode Workflow Dependencies
+
+```markdown
+<!-- Wrong: Agent assumes specific workflow context -->
+You are part of the plan-create Phase 2 team.
+Wait for the Research Brief from Phase 1.
+After your analysis, the Consistency Checker will validate your output.
+
+<!-- Correct: Agent is self-contained -->
+You are a security specialist who identifies vulnerabilities
+and recommends mitigations for code changes.
+```
+
+### Don't Over-Specify the Model
+
+Only set `model` when there's a clear reason. Most agents work well with `inherit` (the default), which uses the same model as the parent session. Use `haiku` for fast, simple tasks (exploration, search). Use `sonnet` or `opus` only when the domain requires stronger reasoning.
+
+## Verification Checklist
+
+Before committing an agent file, verify:
+
+1. **Description is specific** -- Claude can determine when to delegate from the description alone
+2. **Tools are minimal** -- only the tools the agent actually needs
+3. **No workflow coupling** -- no references to specific team structures, phases, or input formats
+4. **No hardcoded communication** -- no "send via SendMessage" or "given a Research Brief"
+5. **Domain is reusable** -- the agent works in planning, review, and ad-hoc contexts
+6. **Role statement is clear** -- first line of body explains what the agent is
+7. **Output format is defined** -- structured output without prescribing delivery

package/plugins/lisa-expo/skills/apollo-client/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: apollo-client
+description: This skill should be used when writing or modifying GraphQL operations, hooks, or mutations using Apollo Client 3.10. It enforces best practices for optimistic responses, cache updates, and TypeScript type generation. Use this skill when creating new queries/mutations, reviewing Apollo code, or troubleshooting cache issues.
+---
+
+# Apollo Client 3.10
+
+## Overview
+
+This skill provides best practices for Apollo Client 3.10 in this codebase, ensuring consistent patterns for GraphQL operations, optimistic UI updates, cache management, and TypeScript type safety.
+
+## Quick Reference
+
+### Generator Commands
+
+After modifying any `operations.graphql` file, run the appropriate generator:
+
+```bash
+bun run generate:types:dev        # Development environment
+bun run generate:types:staging    # Staging environment
+bun run generate:types:production # Production environment
+```
+
+> **Note:** Replace `bun` with your project's package manager (`npm`, `yarn`, `pnpm`) as needed.
+
+### Import Pattern
+
+All GraphQL types, hooks, and documents must come from generated types:
+
+```typescript
+import {
+  useGetPlayerQuery,
+  useUpdatePlayerMutation,
+  GetPlayerQuery,
+  PlayerFragment,
+  ListPlayersDocument,
+} from "@/generated/graphql";
+```
+
+## Core Rules
+
+### 1. Only Use Generated Types
+
+Import all GraphQL-related types from `@/generated/graphql`. Never define manual TypeScript types for GraphQL entities.
+
+```typescript
+// CORRECT
+import { PlayerFragment, useUpdatePlayerMutation } from "@/generated/graphql";
+
+// INCORRECT - Never do this
+type Player = { id: string; name: string };
+```
+
+### 2. Never Modify Generated Files
+
+The `generated/graphql.ts` file is auto-generated by codegen. To change types:
+
+1. Edit the appropriate `operations.graphql` file in the feature directory
+2. Run `bun run generate:types:dev`
+3. Import the newly generated types
+
+### 3. Always Run Generator After Schema Changes
+
+After modifying any `operations.graphql` file, immediately run the generator before committing. Verify changes compile with `bun run typecheck`.
+
+### 4. Always Include Optimistic Response
+
+Every mutation must include an `optimisticResponse` for instant UI feedback:
+
+```typescript
+const [updatePlayer] = useUpdatePlayerMutation({
+  optimisticResponse: variables => ({
+    __typename: "Mutation",
+    updatePlayer: {
+      __typename: "Player",
+      id: variables.id,
+      name: variables.input.name,
+      updatedAt: new Date().toISOString(),
+    },
+  }),
+});
+```
+
+Key requirements:
+
+- Always include `__typename` for every object in the response
+- Always include `id` for cache normalization
+- Use temporary IDs for new objects (e.g., `crypto.randomUUID()`)
+- Include all fields that the mutation returns
+
+### 5. Always Update Cache
+
+Every mutation must handle cache updates using one of these strategies:
+
+**Automatic Updates** - When mutation returns the full entity with `id` and `__typename`, Apollo updates automatically. No extra code needed.
+
+**cache.modify** - For adding/removing items from lists:
+
+```typescript
+const [addPlayer] = useAddPlayerMutation({
+  optimisticResponse: {
+    /* ... */
+  },
+  update(cache, { data }) {
+    cache.modify({
+      fields: {
+        players(existingPlayers = [], { readField }) {
+          const newRef = cache.writeFragment({
+            data: data.addPlayer,
+            fragment: PlayerFragmentDoc,
+          });
+          return [...existingPlayers, newRef];
+        },
+      },
+    });
+  },
+});
+```
+
+**refetchQueries** - Fallback for complex scenarios:
+
+```typescript
+const [complexMutation] = useComplexMutation({
+  refetchQueries: ["ListPlayers"],
+  awaitRefetchQueries: true,
+});
+```
+
+## Operations.graphql Structure
+
+### Fragment-First Pattern
+
+Define fragments before queries/mutations that use them:
+
+```graphql
+# 1. Fragments first
+fragment PlayerFragment on Player {
+  id
+  knownName
+  firstName
+  lastName
+  team {
+    id
+    name
+  }
+}
+
+# 2. Queries second
+query GetPlayer($id: ID!) {
+  player(id: $id) {
+    ...PlayerFragment
+  }
+}
+
+# 3. Mutations last
+mutation UpdatePlayer($id: ID!, $input: UpdatePlayerInput!) {
+  updatePlayer(id: $id, input: $input) {
+    ...PlayerFragment
+  }
+}
+```
+
+### Include Required Fields
+
+Mutations must return all fields needed for cache updates:
+
+```graphql
+mutation AddPlayerToKanban($input: AddPlayerToKanbanInput!) {
+  addPlayerToKanban(input: $input) {
+    id # Required for cache normalization
+    position
+    notes
+    kanbanPhaseId
+    kanbanPhase {
+      # Include related objects
+      id
+      name
+    }
+    createdAt
+    updatedAt
+  }
+}
+```
+
+## Query Best Practices
+
+### Fetch Policies
+
+```typescript
+// Frequently changing data - balance speed and freshness
+fetchPolicy: "cache-and-network";
+
+// Stable reference data - prioritize cache
+fetchPolicy: "cache-first";
+
+// Always-fresh data - skip cache
+fetchPolicy: "network-only";
+```
+
+### Skip When Variables Undefined
+
+```typescript
+const { data } = useGetPlayerQuery({
+  variables: { id: playerId! },
+  skip: !playerId,
+});
+```
+
+### Error Handling
+
+Use `onError` callback instead of try/catch with console.log:
+
+```typescript
+const [mutation] = useMutation(MUTATION, {
+  onError: error => {
+    setErrorState("Failed to update. Please try again.");
+  },
+});
+```
+
+## Complete Mutation Pattern
+
+Reference `references/mutation-patterns.md` for comprehensive examples of the complete mutation pattern including optimistic responses, cache updates, and error handling.
+
+## Validation Checklist
+
+When writing or reviewing Apollo code, verify:
+
+- [ ] All types imported from `@/generated/graphql`
+- [ ] No manual type definitions for GraphQL entities
+- [ ] Every mutation has `optimisticResponse`
+- [ ] Every mutation has cache update strategy
+- [ ] `__typename` included in all optimistic response objects
+- [ ] `id` included in all optimistic response objects
+- [ ] Queries use appropriate `fetchPolicy`
+- [ ] Queries use `skip` when variables may be undefined
+- [ ] Error handling via `onError` callback
+- [ ] Generator was run after operations.graphql changes