cue-ai 0.4.0 → 0.5.0

package/resources/claude-plugins-official/plugins/plugin-dev/skills/agent-development/references/system-prompt-design.md

@@ -1,411 +0,0 @@
-# System Prompt Design Patterns
-
-Complete guide to writing effective agent system prompts that enable autonomous, high-quality operation.
-
-## Core Structure
-
-Every agent system prompt should follow this proven structure:
-
-```markdown
-You are [specific role] specializing in [specific domain].
-
-**Your Core Responsibilities:**
-1. [Primary responsibility - the main task]
-2. [Secondary responsibility - supporting task]
-3. [Additional responsibilities as needed]
-
-**[Task Name] Process:**
-1. [First concrete step]
-2. [Second concrete step]
-3. [Continue with clear steps]
-[...]
-
-**Quality Standards:**
-- [Standard 1 with specifics]
-- [Standard 2 with specifics]
-- [Standard 3 with specifics]
-
-**Output Format:**
-Provide results structured as:
-- [Component 1]
-- [Component 2]
-- [Include specific formatting requirements]
-
-**Edge Cases:**
-Handle these situations:
-- [Edge case 1]: [Specific handling approach]
-- [Edge case 2]: [Specific handling approach]
-```
-
-## Pattern 1: Analysis Agents
-
-For agents that analyze code, PRs, or documentation:
-
-```markdown
-You are an expert [domain] analyzer specializing in [specific analysis type].
-
-**Your Core Responsibilities:**
-1. Thoroughly analyze [what] for [specific issues]
-2. Identify [patterns/problems/opportunities]
-3. Provide actionable recommendations
-
-**Analysis Process:**
-1. **Gather Context**: Read [what] using available tools
-2. **Initial Scan**: Identify obvious [issues/patterns]
-3. **Deep Analysis**: Examine [specific aspects]:
-   - [Aspect 1]: Check for [criteria]
-   - [Aspect 2]: Verify [criteria]
-   - [Aspect 3]: Assess [criteria]
-4. **Synthesize Findings**: Group related issues
-5. **Prioritize**: Rank by [severity/impact/urgency]
-6. **Generate Report**: Format according to output template
-
-**Quality Standards:**
-- Every finding includes file:line reference
-- Issues categorized by severity (critical/major/minor)
-- Recommendations are specific and actionable
-- Positive observations included for balance
-
-**Output Format:**
-## Summary
-[2-3 sentence overview]
-
-## Critical Issues
-- [file:line] - [Issue description] - [Recommendation]
-
-## Major Issues
-[...]
-
-## Minor Issues
-[...]
-
-## Recommendations
-[...]
-
-**Edge Cases:**
-- No issues found: Provide positive feedback and validation
-- Too many issues: Group and prioritize top 10
-- Unclear code: Request clarification rather than guessing
-```
-
-## Pattern 2: Generation Agents
-
-For agents that create code, tests, or documentation:
-
-```markdown
-You are an expert [domain] engineer specializing in creating high-quality [output type].
-
-**Your Core Responsibilities:**
-1. Generate [what] that meets [quality standards]
-2. Follow [specific conventions/patterns]
-3. Ensure [correctness/completeness/clarity]
-
-**Generation Process:**
-1. **Understand Requirements**: Analyze what needs to be created
-2. **Gather Context**: Read existing [code/docs/tests] for patterns
-3. **Design Structure**: Plan [architecture/organization/flow]
-4. **Generate Content**: Create [output] following:
-   - [Convention 1]
-   - [Convention 2]
-   - [Best practice 1]
-5. **Validate**: Verify [correctness/completeness]
-6. **Document**: Add comments/explanations as needed
-
-**Quality Standards:**
-- Follows project conventions (check CLAUDE.md)
-- [Specific quality metric 1]
-- [Specific quality metric 2]
-- Includes error handling
-- Well-documented and clear
-
-**Output Format:**
-Create [what] with:
-- [Structure requirement 1]
-- [Structure requirement 2]
-- Clear, descriptive naming
-- Comprehensive coverage
-
-**Edge Cases:**
-- Insufficient context: Ask user for clarification
-- Conflicting patterns: Follow most recent/explicit pattern
-- Complex requirements: Break into smaller pieces
-```
-
-## Pattern 3: Validation Agents
-
-For agents that validate, check, or verify:
-
-```markdown
-You are an expert [domain] validator specializing in ensuring [quality aspect].
-
-**Your Core Responsibilities:**
-1. Validate [what] against [criteria]
-2. Identify violations and issues
-3. Provide clear pass/fail determination
-
-**Validation Process:**
-1. **Load Criteria**: Understand validation requirements
-2. **Scan Target**: Read [what] needs validation
-3. **Check Rules**: For each rule:
-   - [Rule 1]: [Validation method]
-   - [Rule 2]: [Validation method]
-4. **Collect Violations**: Document each failure with details
-5. **Assess Severity**: Categorize issues
-6. **Determine Result**: Pass only if [criteria met]
-
-**Quality Standards:**
-- All violations include specific locations
-- Severity clearly indicated
-- Fix suggestions provided
-- No false positives
-
-**Output Format:**
-## Validation Result: [PASS/FAIL]
-
-## Summary
-[Overall assessment]
-
-## Violations Found: [count]
-### Critical ([count])
-- [Location]: [Issue] - [Fix]
-
-### Warnings ([count])
-- [Location]: [Issue] - [Fix]
-
-## Recommendations
-[How to fix violations]
-
-**Edge Cases:**
-- No violations: Confirm validation passed
-- Too many violations: Group by type, show top 20
-- Ambiguous rules: Document uncertainty, request clarification
-```
-
-## Pattern 4: Orchestration Agents
-
-For agents that coordinate multiple tools or steps:
-
-```markdown
-You are an expert [domain] orchestrator specializing in coordinating [complex workflow].
-
-**Your Core Responsibilities:**
-1. Coordinate [multi-step process]
-2. Manage [resources/tools/dependencies]
-3. Ensure [successful completion/integration]
-
-**Orchestration Process:**
-1. **Plan**: Understand full workflow and dependencies
-2. **Prepare**: Set up prerequisites
-3. **Execute Phases**:
-   - Phase 1: [What] using [tools]
-   - Phase 2: [What] using [tools]
-   - Phase 3: [What] using [tools]
-4. **Monitor**: Track progress and handle failures
-5. **Verify**: Confirm successful completion
-6. **Report**: Provide comprehensive summary
-
-**Quality Standards:**
-- Each phase completes successfully
-- Errors handled gracefully
-- Progress reported to user
-- Final state verified
-
-**Output Format:**
-## Workflow Execution Report
-
-### Completed Phases
-- [Phase]: [Result]
-
-### Results
-- [Output 1]
-- [Output 2]
-
-### Next Steps
-[If applicable]
-
-**Edge Cases:**
-- Phase failure: Attempt retry, then report and stop
-- Missing dependencies: Request from user
-- Timeout: Report partial completion
-```
-
-## Writing Style Guidelines
-
-### Tone and Voice
-
-**Use second person (addressing the agent):**
-```
-✅ You are responsible for...
-✅ You will analyze...
-✅ Your process should...
-
-❌ The agent is responsible for...
-❌ This agent will analyze...
-❌ I will analyze...
-```
-
-### Clarity and Specificity
-
-**Be specific, not vague:**
-```
-✅ Check for SQL injection by examining all database queries for parameterization
-❌ Look for security issues
-
-✅ Provide file:line references for each finding
-❌ Show where issues are
-
-✅ Categorize as critical (security), major (bugs), or minor (style)
-❌ Rate the severity of issues
-```
-
-### Actionable Instructions
-
-**Give concrete steps:**
-```
-✅ Read the file using the Read tool, then search for patterns using Grep
-❌ Analyze the code
-
-✅ Generate test file at test/path/to/file.test.ts
-❌ Create tests
-```
-
-## Common Pitfalls
-
-### ❌ Vague Responsibilities
-
-```markdown
-**Your Core Responsibilities:**
-1. Help the user with their code
-2. Provide assistance
-3. Be helpful
-```
-
-**Why bad:** Not specific enough to guide behavior.
-
-### ✅ Specific Responsibilities
-
-```markdown
-**Your Core Responsibilities:**
-1. Analyze TypeScript code for type safety issues
-2. Identify missing type annotations and improper 'any' usage
-3. Recommend specific type improvements with examples
-```
-
-### ❌ Missing Process Steps
-
-```markdown
-Analyze the code and provide feedback.
-```
-
-**Why bad:** Agent doesn't know HOW to analyze.
-
-### ✅ Clear Process
-
-```markdown
-**Analysis Process:**
-1. Read code files using Read tool
-2. Scan for type annotations on all functions
-3. Check for 'any' type usage
-4. Verify generic type parameters
-5. List findings with file:line references
-```
-
-### ❌ Undefined Output
-
-```markdown
-Provide a report.
-```
-
-**Why bad:** Agent doesn't know what format to use.
-
-### ✅ Defined Output Format
-
-```markdown
-**Output Format:**
-## Type Safety Report
-
-### Summary
-[Overview of findings]
-
-### Issues Found
-- `file.ts:42` - Missing return type on `processData`
-- `utils.ts:15` - Unsafe 'any' usage in parameter
-
-### Recommendations
-[Specific fixes with examples]
-```
-
-## Length Guidelines
-
-### Minimum Viable Agent
-
-**~500 words minimum:**
-- Role description
-- 3 core responsibilities
-- 5-step process
-- Output format
-
-### Standard Agent
-
-**~1,000-2,000 words:**
-- Detailed role and expertise
-- 5-8 responsibilities
-- 8-12 process steps
-- Quality standards
-- Output format
-- 3-5 edge cases
-
-### Comprehensive Agent
-
-**~2,000-5,000 words:**
-- Complete role with background
-- Comprehensive responsibilities
-- Detailed multi-phase process
-- Extensive quality standards
-- Multiple output formats
-- Many edge cases
-- Examples within system prompt
-
-**Avoid > 10,000 words:** Too long, diminishing returns.
-
-## Testing System Prompts
-
-### Test Completeness
-
-Can the agent handle these based on system prompt alone?
-
-- [ ] Typical task execution
-- [ ] Edge cases mentioned
-- [ ] Error scenarios
-- [ ] Unclear requirements
-- [ ] Large/complex inputs
-- [ ] Empty/missing inputs
-
-### Test Clarity
-
-Read the system prompt and ask:
-
-- Can another developer understand what this agent does?
-- Are process steps clear and actionable?
-- Is output format unambiguous?
-- Are quality standards measurable?
-
-### Iterate Based on Results
-
-After testing agent:
-1. Identify where it struggled
-2. Add missing guidance to system prompt
-3. Clarify ambiguous instructions
-4. Add process steps for edge cases
-5. Re-test
-
-## Conclusion
-
-Effective system prompts are:
-- **Specific**: Clear about what and how
-- **Structured**: Organized with clear sections
-- **Complete**: Covers normal and edge cases
-- **Actionable**: Provides concrete steps
-- **Testable**: Defines measurable standards
-
-Use the patterns above as templates, customize for your domain, and iterate based on agent performance.

package/resources/claude-plugins-official/plugins/plugin-dev/skills/agent-development/references/triggering-examples.md

@@ -1,217 +0,0 @@
-# Agent Triggering: Best Practices
-
-Complete guide to writing trigger descriptions that cause an agent to be dispatched reliably.
-
-## Where trigger descriptions live
-
-An agent file has two places that talk about triggering:
-
-1. **`description:` field in YAML frontmatter.** Loaded into context whenever the agent is registered, used by the harness to decide when to dispatch. Keep it flat prose.
-2. **A "When to invoke" section in the agent body.** Loaded only when the agent is actually invoked. This is where worked scenarios live, as a bullet list of prose descriptions.
-
-## Format
-
-### `description:` field
-
-```
-description: Use this agent when [conditions]. Typical triggers include [scenario 1 phrased as a prose noun phrase], [scenario 2], and [scenario 3]. See "When to invoke" in the agent body for worked scenarios.
-```
-
-Rules:
-- Single line of flat prose within the YAML scalar.
-- Name 2-4 trigger scenarios as noun phrases.
-- End with the pointer to the body's "When to invoke" section.
-
-### "When to invoke" body section
-
-```markdown
-## When to invoke
-
-[Two to four representative scenarios as prose bullets. Each describes the situation
-in third person and what the agent should do.]
-
-- **[Short scenario name].** [What the situation looks like — what just happened or what
-  the user is asking for — and what the agent should do in response.]
-- **[Short scenario name].** [Same.]
-```
-
-## Anatomy of a good scenario
-
-### Scenario name (the bold lead)
-
-**Purpose:** A short noun phrase identifying the situation type.
-
-**Good names:**
-- *User-requested review after a feature lands.*
-- *Proactive review of newly-written code.*
-- *Pre-PR sanity check.*
-- *PR updated with new logic.*
-
-**Bad names:**
-- *Normal usage.* (not specific)
-- *User needs help.* (vague)
-
-### Scenario body (after the lead)
-
-**Purpose:** Describe what happens and what the agent should do — in prose, third person, no quoted utterances.
-
-**Good:**
-> The user has just implemented a feature (often spanning several files) and asks whether everything looks good. Run a review of the recent diff and report findings.
-
-**Bad (transcript shape — do not use):**
-> ```
-> user: "Can you check if everything looks good?"
-> assistant: "I'll use the reviewer agent..."
-> ```
-
-The bad version mixes a turn-marker shape into the agent file. Keep scenarios as situation descriptions in prose.
-
-## Trigger types to cover
-
-Aim for 2-4 scenarios that span these axes:
-
-### Explicit request
-The user directly asks for what the agent does.
-- *User-requested security check.* The user explicitly asks for a security review of recent code.
-
-### Proactive triggering
-The assistant invokes the agent without an explicit ask, after relevant work.
-- *Proactive review after writing database code.* The assistant has just authored database access code and should check for SQL injection and other database-layer risks before declaring the task done.
-
-### Implicit request
-The user implies need without naming the agent.
-- *Code-clarity complaint.* The user describes existing code as confusing or hard to follow. Treat as a request to refactor for readability.
-
-### Tool-usage pattern
-The agent should follow a particular tool-use pattern.
-- *Post-test-edit verification.* The assistant has just made multiple edits to test files. Verify the edited tests still meet quality and coverage standards before continuing.
-
-## Phrasing variation
-
-If the same intent is commonly phrased multiple ways, mention that in prose:
-
-> **Pre-PR sanity check.** The user signals (in any phrasing — "ready to open a PR", "I think we're done here", "let's ship this") that they're about to open a pull request.
-
-Don't write three near-duplicate scenarios that differ only in the literal phrase — collapse them into one prose scenario that names the variation.
-
-## How many scenarios?
-
-- **Minimum: 2.** Usually one explicit + one proactive.
-- **Recommended: 3-4.** Explicit, proactive, and one implicit or edge case.
-- **Maximum: 5.** More than that bloats the body without adding routing signal.
-
-## Worked example
-
-### Prose triggers in `description:`
-
-```yaml
-description: Use this agent when you need to review code. Typical triggers include user-requested review after a feature lands, proactive review of freshly-written code, and a pre-PR sanity check. See "When to invoke" in the agent body for worked scenarios.
-```
-
-### Scenarios as situation descriptions in the body
-
-```markdown
-## When to invoke
-
-- **User-requested review.** The user asks for a review of recent changes (any phrasing). Run a review of the unstaged diff.
-```
-
-### Trigger condition only — output format goes elsewhere
-
-```markdown
-- **Review.** The user asks for a review. Run the review and report findings as specified in the Output Format section.
-```
-
-## Template library
-
-### Code review agent
-
-```yaml
-description: Use this agent when you need to review code for adherence to project guidelines and best practices. Typical triggers include the user asking for a review of a feature they just implemented, proactive review of newly-written code before declaring a task done, and a pre-PR sanity check. See "When to invoke" in the agent body.
-```
-
-```markdown
-## When to invoke
-
-- **User-requested review after a feature lands.** The user has implemented a feature and asks whether the result looks good. Review the recent diff and report findings.
-- **Proactive review of newly-written code.** The assistant has just authored new code in response to a user request. Run a self-review before declaring the task done.
-- **Pre-PR sanity check.** The user signals readiness to open a pull request. Review the full diff first.
-```
-
-### Test generation agent
-
-```yaml
-description: Use this agent when you need to generate tests for code that lacks them. Typical triggers include the user explicitly asking for tests for a function or module, and the assistant proactively generating tests after writing new code that has no test coverage. See "When to invoke" in the agent body.
-```
-
-```markdown
-## When to invoke
-
-- **Explicit test request.** The user asks for tests covering a specific function, module, or feature. Generate a comprehensive test suite.
-- **Proactive coverage after new code.** The assistant has just written new code with no accompanying tests. Generate tests before declaring the task done.
-```
-
-### Documentation agent
-
-```yaml
-description: Use this agent when you need to write or improve documentation for code, especially APIs. Typical triggers include the user asking for docs on a specific function or endpoint, and proactive documentation generation after the assistant adds new API surface. See "When to invoke" in the agent body.
-```
-
-```markdown
-## When to invoke
-
-- **Explicit doc request.** The user asks for documentation for a specific surface (function, endpoint, module).
-- **Proactive docs for new API surface.** The assistant has just added new API endpoints or public functions without docstrings.
-```
-
-### Validation agent
-
-```yaml
-description: Use this agent when you need to validate code before commit or merge. Typical triggers include the user signaling readiness to commit, and an explicit validation request. See "When to invoke" in the agent body.
-```
-
-```markdown
-## When to invoke
-
-- **Pre-commit validation.** The user signals readiness to commit. Run validation first and surface any issues.
-- **Explicit validation request.** The user asks for the code to be validated.
-```
-
-## Debugging triggering issues
-
-### Agent not triggering
-
-Check:
-1. The `description:` prose names the right trigger scenarios.
-2. The scenarios in the body cover the actual phrasings the user uses.
-3. There isn't a more-specific competing agent winning the routing decision.
-
-Fix: add or expand scenarios in the body, and tighten the prose summary in `description:`.
-
-### Agent triggers too often
-
-Check:
-1. The trigger scenarios are too generic or overlap with other agents.
-2. The `description:` doesn't say when NOT to use the agent.
-
-Fix: narrow the scenarios; add a "Do not invoke when..." line to `description:` if needed.
-
-### Agent triggers in the wrong scenarios
-
-Check:
-1. Whether the scenarios in the body match the agent's actual capabilities.
-
-Fix: rewrite scenarios to match what the agent actually does.
-
-## Best practices summary
-
-- Keep `description:` as flat prose with a short summary of trigger scenarios
-- Put detailed scenarios in a "When to invoke" body section, as prose bullets
-- Cover both explicit and proactive triggering
-- Describe situations the agent should respond to
-- Mention phrasing variation in prose ("any phrasing — 'ready to ship', 'looks done'") rather than via multiple near-duplicate scenarios
-- Keep trigger scenarios separate from output format
-
-## Conclusion
-
-Reliable triggering comes from prose descriptions of the situations an agent should respond to.