@nockdev/awf 6.2.0 → 6.2.2

package/.agent/skills/ai-ml/prompt-engineering/SKILL.md

@@ -0,0 +1,217 @@
+# Prompt Engineering Patterns v2.0
+
+> 🧠 **LLM prompt design for production AI systems**
+> **Patterns**: 155+ | **Providers**: 3 | **Categories**: 6
+
+---
+
+## Quick Reference
+
+| What You Need                           | Data File                 | Patterns |
+| --------------------------------------- | ------------------------- | -------- |
+| Reasoning (CoT, ReAct, ToT)             | `reasoning-patterns.yaml` | 35       |
+| Output (JSON, structured, formatting)   | `output-patterns.yaml`    | 30       |
+| Safety (injection, guardrails)          | `safety-patterns.yaml`    | 30       |
+| Provider-specific (OpenAI, Claude, etc) | `provider-patterns.yaml`  | 25       |
+| **Gemini 3 (agentic, thinking, XML)**   | `gemini3-patterns.yaml`   | 20       |
+| **Tool use (FC, MCP, multi-tool)**      | `tool-patterns.yaml`      | 15       |
+
+---
+
+## Prompting Hierarchy
+
+```
+┌──────────────────────────────────────────┐
+│  Level 1: Zero-Shot (no examples)        │
+│  Level 2: Few-Shot (1-5 examples)        │
+│  Level 3: Chain-of-Thought (reasoning)   │
+│  Level 4: ReAct (reasoning + tools)      │
+│  Level 5: Tree-of-Thought (exploration)  │
+│  Level 6: Multi-agent (delegation)       │
+│  Level 7: Agentic (Gemini 3 template)    │ ← NEW
+└──────────────────────────────────────────┘
+```
+
+---
+
+## Core Techniques
+
+| Technique            | When to Use                  | Accuracy |
+| -------------------- | ---------------------------- | -------- |
+| **Zero-shot**        | Simple tasks, strong model   | ~70%     |
+| **Few-shot**         | Pattern matching, formatting | ~80%     |
+| **Chain-of-thought** | Math, logic, multi-step      | ~90%     |
+| **Self-consistency** | High-stakes decisions        | ~92%     |
+| **ReAct**            | Tool use, research           | ~88%     |
+| **Tree-of-thought**  | Creative/exploration tasks   | ~85%     |
+
+---
+
+## Gemini 3 Agentic Template (NEW)
+
+Google's official 9-rule agentic system instruction template:
+
+```xml
+<role>You are [role]. Your goal is [goal].</role>
+
+<instructions>
+1. [Primary instruction]
+2. [Secondary instruction]
+...
+</instructions>
+
+<constraints>
+- [Constraint 1]
+- [Constraint 2]
+</constraints>
+
+<output_format>
+[Expected format: JSON, markdown, etc.]
+</output_format>
+
+<context>
+[Background information, domain knowledge]
+</context>
+
+<task>
+[Specific task to complete]
+</task>
+```
+
+**Best Practices**:
+
+- Use XML tags for structured sections
+- Positive patterns > negative patterns ("do X" not "don't do Y")
+- Put examples WITHIN output_format for few-shot
+- Completion strategy gives output prefix to guide direction
+
+---
+
+## Thinking Controls (NEW)
+
+| Level    | Name        | Use Case                    | Budget          |
+| -------- | ----------- | --------------------------- | --------------- |
+| `off`    | No thinking | Simple lookups              | 0               |
+| `low`    | Quick       | Classification, formatting  | 1K-2K           |
+| `medium` | Balanced    | General tasks               | 4K-8K           |
+| `high`   | Deep        | Math, code analysis         | 16K-32K         |
+| `max`    | Maximum     | Research, complex reasoning | Up to model max |
+
+```python
+# Thinking level (Gemini 3)
+response = model.generate_content(
+    "prompt",
+    generation_config={"thinking_config": {"thinking_level": "high"}}
+)
+
+# Thinking budget (token limit)
+response = model.generate_content(
+    "prompt",
+    generation_config={"thinking_config": {"thinking_budget": 8192}}
+)
+```
+
+---
+
+## Structured Output (NEW)
+
+| Pattern                | Schema Tool                            | When to Use           |
+| ---------------------- | -------------------------------------- | --------------------- |
+| **Pydantic** (Python)  | `response_schema=Recipe`               | Type-safe Python apps |
+| **Zod** (JavaScript)   | `responseMimeType: "application/json"` | Node.js/TS apps       |
+| **JSON Schema** (REST) | `responseSchema: {...}`                | Direct API calls      |
+| **Enum**               | `enum: ["cat", "dog"]`                 | Classification tasks  |
+
+**Best Practices**:
+
+- Use `description` field in schema for model guidance
+- Strong typing (`integer`, `enum`) > loose typing (`string`)
+- Validate semantically even if syntactically correct
+
+---
+
+## Function Calling Patterns (NEW)
+
+| Pattern                | Description                       | Use Case                              |
+| ---------------------- | --------------------------------- | ------------------------------------- |
+| **Single**             | One function declaration          | Simple API calls                      |
+| **Parallel**           | Multiple functions at once        | Independent data fetching             |
+| **Compositional**      | Chained function results          | `get_location()` → `get_weather(loc)` |
+| **MCP Built-in**       | Gemini SDK auto-calls MCP tools   | MCP server integration                |
+| **Multi-tool**         | Combine Search + Code + Functions | Complex agentic workflows             |
+| **Automatic** (Python) | SDK handles full loop             | Rapid prototyping                     |
+
+**Modes**: `AUTO` (default) | `ANY` (force call) | `NONE` (disable)
+
+---
+
+## Prompt Structure
+
+```
+[System Prompt]
+  - Role definition
+  - Capabilities and limitations
+  - Output format requirements
+  - Safety guardrails
+
+[User Prompt]
+  - Context/background
+  - Specific task description
+  - Input data
+  - Expected output format
+  - Examples (few-shot)
+
+[Assistant prefill] (Claude-specific)
+  - Guide initial response direction
+```
+
+---
+
+## Chain-of-Thought Patterns
+
+| Pattern              | Description                                  |
+| -------------------- | -------------------------------------------- |
+| **Basic CoT**        | "Think step by step"                         |
+| **Zero-shot CoT**    | "Let's think about this carefully"           |
+| **Few-shot CoT**     | Provide examples WITH reasoning steps        |
+| **Self-consistency** | Generate N answers, pick majority            |
+| **Auto-CoT**         | Let model generate its own reasoning prompts |
+
+---
+
+## Output Formatting
+
+| Format       | Prompt Pattern                                             |
+| ------------ | ---------------------------------------------------------- |
+| **JSON**     | "Respond in valid JSON matching this schema: {...}"        |
+| **Markdown** | "Format as markdown with headers and bullet points"        |
+| **Code**     | "Write [language] code with comments explaining each step" |
+| **Table**    | "Present results in a markdown table with columns: [...]"  |
+| **XML**      | "Wrap your response in <answer>...</answer> tags"          |
+
+---
+
+## Safety Patterns
+
+| Threat               | Defense                                        |
+| -------------------- | ---------------------------------------------- |
+| **Prompt injection** | Input sanitization + delimiter tags            |
+| **Jailbreaking**     | Constitutional AI rules + refusal training     |
+| **Data leakage**     | PII filtering + output validation              |
+| **Hallucination**    | RAG grounding + citation requirements          |
+| **Bias**             | Balanced examples + explicit fairness criteria |
+
+---
+
+## HSA Integration
+
+Data powered by HSA BM25 search engine. Query YAML data via skill search:
+
+| Domain    | Query Examples                            |
+| --------- | ----------------------------------------- |
+| Reasoning | "chain of thought step by step reasoning" |
+| Output    | "JSON schema structured output format"    |
+| Safety    | "prompt injection defense guardrail"      |
+| Provider  | "OpenAI function calling Claude tool use" |
+| Gemini 3  | "agentic template thinking budget XML"    |
+| Tools     | "MCP compositional parallel function"     |

package/.agent/skills/ai-ml/prompt-engineering/data/gemini3-patterns.yaml

@@ -0,0 +1,170 @@
+# =============================================================================
+# gemini3-patterns.yaml — Gemini 3 Agentic Prompt Patterns
+# =============================================================================
+# 20 patterns for Gemini 3 agentic system instructions, thinking, and output
+# Source: https://ai.google.dev/gemini-api/docs/prompting-strategies
+# =============================================================================
+
+version: "2.0.0"
+total_patterns: 20
+
+# =============================================================================
+# AGENTIC SYSTEM INSTRUCTIONS
+# =============================================================================
+
+agentic_template:
+  description: "Google's official 9-rule agentic system instruction format"
+  xml_tags:
+    - role: "Agent identity and primary goal"
+    - instructions: "Numbered step-by-step instructions"
+    - constraints: "Boundaries and limitations"
+    - output_format: "Expected response structure"
+    - context: "Background information and domain knowledge"
+    - task: "Specific task to complete"
+  best_practices:
+    - "Use XML tags for structured sections"
+    - "Positive patterns over negative: 'do X' not 'don't do Y'"
+    - "Put examples WITHIN output_format for few-shot"
+    - "Use completion strategy: give output prefix to guide direction"
+    - "Be specific: 'summarize in 3 bullet points' > 'summarize'"
+
+system_instruction_rules:
+  - rule: identity
+    desc: "Define agent's role, expertise, and personality"
+    example: "<role>You are a senior software architect specializing in distributed systems.</role>"
+  - rule: task_scope
+    desc: "Define what the agent should and should NOT do"
+    example: "Focus on architectural patterns. Do not write implementation code."
+  - rule: output_format
+    desc: "Specify exact format with examples"
+    example: '<output_format>Respond in JSON: {"pattern": "...", "pros": [...], "cons": [...]}</output_format>'
+  - rule: constraints
+    desc: "Set boundaries: length, tone, style, safety"
+    example: "<constraints>Max 200 words. Professional tone. No speculation.</constraints>"
+  - rule: context
+    desc: "Provide domain-specific knowledge"
+    example: "<context>The system uses PostgreSQL 16, Go 1.23, and gRPC.</context>"
+  - rule: examples
+    desc: "Include 2-3 examples of expected output"
+    example: "Input: X → Output: Y (embedded in output_format section)"
+  - rule: fallback
+    desc: "Define behavior when uncertain or unable"
+    example: "If you're unsure, say 'I need more context about X' instead of guessing."
+  - rule: iteration
+    desc: "Allow self-correction and multi-step reasoning"
+    example: "Think step by step. If initial approach seems wrong, reconsider."
+  - rule: safety
+    desc: "Set safety guardrails for harmful content"
+    example: "Never provide advice on harmful activities."
+
+# =============================================================================
+# THINKING CONTROLS
+# =============================================================================
+
+thinking_levels:
+  description: "Gemini 3 thinking level controls"
+  levels:
+    - name: "off"
+      desc: "No internal reasoning"
+      use_case: "Simple lookups, classification"
+      latency: "Fastest"
+    - name: "low"
+      desc: "Minimal reasoning"
+      use_case: "Formatting, translation"
+      latency: "Fast"
+    - name: "medium"
+      desc: "Balanced reasoning (default)"
+      use_case: "General tasks, Q&A"
+      latency: "Moderate"
+    - name: "high"
+      desc: "Deep reasoning"
+      use_case: "Math, code analysis, debugging"
+      latency: "Slower"
+    - name: "max"
+      desc: "Maximum reasoning effort"
+      use_case: "Research, complex multi-step problems"
+      latency: "Slowest"
+
+thinking_budgets:
+  description: "Token budget for thinking process"
+  config:
+    python: |
+      generation_config={"thinking_config": {"thinking_budget": 8192}}
+    javascript: |
+      generationConfig: { thinkingConfig: { thinkingBudget: 8192 } }
+  guidelines:
+    - "Set budget=0 to disable thinking"
+    - "Budget acts as upper limit, model may use less"
+    - "Higher budget ≠ always better (diminishing returns)"
+    - "Use thought summaries for transparency"
+
+thought_summaries:
+  description: "Access model's reasoning process"
+  usage: "Check response.candidates[0].content.parts for thought parts"
+  billing: "Thinking tokens are billed as output tokens"
+  signatures: "Opaque signature string for conversation continuity"
+
+# =============================================================================
+# STRUCTURED OUTPUT
+# =============================================================================
+
+structured_output:
+  description: "Type-safe JSON output with schema enforcement"
+  schema_tools:
+    - name: "Pydantic"
+      language: "Python"
+      example: "response_schema=list[Recipe]"
+    - name: "Zod"
+      language: "JavaScript/TypeScript"
+      example: "responseMimeType: 'application/json', responseSchema: schema"
+    - name: "JSON Schema"
+      language: "REST API"
+      example: "type: OBJECT, properties: {...}"
+  best_practices:
+    - "Use description field in schema for model guidance"
+    - "Strong typing (integer, enum) > loose typing (string)"
+    - "Validate semantically even if syntactically correct"
+    - "Use propertyOrdering for Gemini 2.0 compatibility"
+  supported_types:
+    - "STRING, INTEGER, NUMBER, BOOLEAN"
+    - "ARRAY (with items)"
+    - "OBJECT (with properties)"
+    - "Enum (restricted values)"
+    - "Nullable fields"
+
+# =============================================================================
+# PROMPTING STRATEGIES
+# =============================================================================
+
+prompting_strategies:
+  few_shot:
+    desc: "Include 2-5 examples of expected input → output"
+    tips:
+      - "Examples should cover edge cases"
+      - "Few-shot > zero-shot for formatting tasks"
+      - "Include reasoning steps in examples for CoT"
+
+  completion:
+    desc: "Provide partial output to guide model direction"
+    tips:
+      - "Start JSON response with opening brace"
+      - "Begin sentence to set tone and style"
+      - "Works across all providers"
+
+  positive_framing:
+    desc: "Tell model what TO do, not what NOT to do"
+    tips:
+      - "'Respond in formal English' > 'Don't use slang'"
+      - "'Output exactly 3 items' > 'Don't output more than 3'"
+
+  iterative_refinement:
+    desc: "Chain prompts for complex tasks"
+    steps:
+      - "Generate initial draft"
+      - "Self-critique the draft"
+      - "Refine based on critique"
+      - "Final quality check"
+
+# =============================================================================
+# _DOMYH Awesome Code • Gemini 3 Patterns v2.0_
+# =============================================================================

package/.agent/skills/ai-ml/prompt-engineering/data/output-patterns.yaml

@@ -0,0 +1,73 @@
+# Output Patterns for Prompt Engineering
+
+patterns:
+  - name: json-mode
+    description: "Force structured JSON output"
+    providers:
+      openai: "response_format: { type: 'json_object' }"
+      anthropic: "Respond ONLY with valid JSON. No markdown, no explanation."
+      google: "responseMimeType: 'application/json'"
+    template: |
+      Return a JSON object matching this schema:
+      {
+        "name": "string",
+        "score": "number (0-100)",
+        "issues": ["string array"]
+      }
+
+  - name: xml-tags
+    description: "Use XML tags for structured sections"
+    when: "Claude/Anthropic models (optimized for XML)"
+    template: |
+      <context>
+      [background information]
+      </context>
+      <task>
+      [what to do]
+      </task>
+      <output_format>
+      [expected format]
+      </output_format>
+
+  - name: markdown-format
+    description: "Request formatted markdown output"
+    template: |
+      Format your response as markdown with:
+      - H2 headers for main sections
+      - Bullet points for lists
+      - Code blocks with language identifiers
+      - Bold for key terms
+
+  - name: tabular-output
+    description: "Request data in table format"
+    template: |
+      Present results as a markdown table with columns:
+      | Column 1 | Column 2 | Column 3 |
+      Include all entries, sorted by [criteria].
+
+  - name: constrained-output
+    description: "Limit output to specific format/length"
+    variants:
+      length: "Respond in exactly 3 sentences."
+      format: "Answer with ONLY one of: YES, NO, MAYBE"
+      vocabulary: "Use only words a 5th grader would understand"
+      style: "Write in the style of [author/format]"
+
+  - name: prefill-technique
+    description: "Pre-fill assistant response to guide output (Claude)"
+    when: "Need specific format from the start"
+    example: |
+      Human: Analyze this code for bugs.
+      Assistant: ```json
+      {
+        "bugs": [
+    note: "Claude will continue from the prefill point"
+
+  - name: delimiter-separation
+    description: "Use delimiters to separate input sections"
+    delimiters: ["###", "---", "===", "```", "<<<>>>", '"""']
+    example: |
+      Translate the text between triple backticks:
+      ```
+      Hello, how are you?
+      ```

package/.agent/skills/ai-ml/prompt-engineering/data/provider-patterns.yaml

@@ -0,0 +1,82 @@
+# Provider-Specific Patterns
+
+providers:
+  - name: openai
+    models: ["gpt-4o", "gpt-5.3-codex", "o3-mini"]
+    features:
+      function_calling:
+        description: "Structured tool use via function definitions"
+        format: |
+          tools: [{
+            type: "function",
+            function: {
+              name: "get_weather",
+              parameters: { type: "object", properties: { city: { type: "string" } } }
+            }
+          }]
+      json_mode:
+        description: "Force valid JSON output"
+        format: "response_format: { type: 'json_schema', json_schema: {...} }"
+      structured_outputs:
+        description: "Guaranteed schema-conformant JSON"
+        note: "Use strict: true for 100% schema compliance"
+    best_practices:
+      - "Use system message for role and constraints"
+      - "Function calling > JSON mode for tool use"
+      - "Temperature 0 for deterministic outputs"
+      - "Use seed parameter for reproducibility"
+
+  - name: anthropic
+    models: ["claude-sonnet-4", "claude-opus-4.6"]
+    features:
+      tool_use:
+        description: "Tool definitions with input schemas"
+        format: |
+          tools: [{
+            name: "get_weather",
+            description: "Get weather for a city",
+            input_schema: { type: "object", properties: { city: { type: "string" } } }
+          }]
+      xml_tags:
+        description: "Optimized for XML-structured prompts"
+        note: "Claude excels with <tag> structured input"
+      extended_thinking:
+        description: "Let Claude reason before answering"
+        format: "thinking: { type: 'enabled', budget_tokens: 10000 }"
+      prefill:
+        description: "Pre-fill assistant response"
+        note: "Guide output format by starting the response"
+    best_practices:
+      - "Use XML tags for structured input sections"
+      - "Prefill assistant response for format control"
+      - "Enable extended thinking for complex tasks"
+      - "Put examples in <example> tags"
+
+  - name: google
+    models: ["gemini-2.5-pro", "gemini-2.5-flash"]
+    features:
+      function_calling:
+        description: "Tool declarations similar to OpenAI"
+      grounding:
+        description: "Ground responses in Google Search"
+        note: "Reduces hallucination for factual queries"
+      code_execution:
+        description: "Built-in Python sandbox for computation"
+        note: "Model can write and run Python to verify answers"
+    best_practices:
+      - "Use grounding for factual accuracy"
+      - "Leverage code execution for math/data tasks"
+      - "System instructions in systemInstruction field"
+
+  - name: cross-provider
+    patterns:
+      - name: provider-agnostic-prompt
+        description: "Write prompts that work across all providers"
+        guidelines:
+          - "Use natural language, not provider-specific syntax"
+          - "Define output format explicitly in the prompt"
+          - "Include examples for consistency"
+          - "Test on 2+ providers before production"
+      - name: fallback-chain
+        description: "Try primary provider, fallback to secondary"
+        strategy: "Claude → GPT-4o → Gemini"

package/.agent/skills/ai-ml/prompt-engineering/data/reasoning-patterns.yaml

@@ -0,0 +1,86 @@
+# Reasoning Patterns for Prompt Engineering
+
+patterns:
+  - name: zero-shot
+    description: "Direct instruction without examples"
+    when: "Simple, well-defined tasks"
+    template: |
+      [Task description]
+      [Input]
+      [Output format]
+
+  - name: few-shot
+    description: "Provide 1-5 examples of desired I/O"
+    when: "Pattern matching, specific format, classification"
+    template: |
+      [Task description]
+      Example 1: Input → Output
+      Example 2: Input → Output
+      Now process: [new input]
+    tips:
+      - "Use 3-5 diverse, representative examples"
+      - "Order examples from simple to complex"
+      - "Include edge cases in examples"
+
+  - name: chain-of-thought
+    description: "Instruct model to show reasoning steps"
+    when: "Math, logic, multi-step reasoning"
+    variants:
+      basic: "Think step by step before answering."
+      detailed: "Break down your reasoning into numbered steps. Show your work."
+      structured: |
+        Analyze this problem:
+        1. Identify the key information
+        2. Determine the approach
+        3. Execute step by step
+        4. Verify the answer
+
+  - name: self-consistency
+    description: "Generate N answers, pick majority/best"
+    when: "High-stakes decisions, uncertain answers"
+    process:
+      - "Ask same question N times (N=5-10) with temperature > 0"
+      - "Collect all answers"
+      - "Pick answer that appears most frequently"
+      - "Or use a judge prompt to select best answer"
+
+  - name: react-pattern
+    description: "Interleave Reasoning, Action, Observation"
+    when: "Tool use, research, multi-step execution"
+    format: |
+      Thought: I need to find the user's order
+      Action: search_orders(user_id="123")
+      Observation: Found 3 orders: [...]
+      Thought: Now I need to check the latest
+      Action: get_order(id="order_789")
+      Observation: Order #789, status: shipped
+      Answer: Your latest order #789 is shipped.
+
+  - name: tree-of-thought
+    description: "Explore multiple reasoning paths, evaluate, prune"
+    when: "Creative tasks, complex planning, ambiguous problems"
+    process:
+      - "Generate 3-5 initial approaches"
+      - "Evaluate each approach (score 1-10)"
+      - "Expand top 2-3 approaches"
+      - "Evaluate again"
+      - "Select best path"
+
+  - name: meta-prompting
+    description: "Ask model to improve its own prompt"
+    template: |
+      Given this task: [description]
+      Write the optimal prompt that would produce the best result.
+      Consider: clarity, specificity, format, and examples needed.
+
+  - name: role-playing
+    description: "Assign expert role for domain-specific responses"
+    template: |
+      You are a senior [role] with 15+ years experience in [domain].
+      Your expertise includes: [specific areas].
+      Approach this as you would in a professional setting.
+    effective_roles:
+      - "Senior security architect"
+      - "Staff software engineer at Google"
+      - "Academic researcher in [field]"
+      - "Expert debugger / troubleshooter"