sinapse-ai 1.0.0

package/squad-claude/tasks/multi-agent-orchestration.md

@@ -0,0 +1,107 @@
+---
+task: multi-agent-orchestration
+responsavel: "@swarm-orchestrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Multi-Agent Orchestration
+
+## Objective
+
+Design a multi-agent orchestration system that coordinates multiple specialized AI agents to complete complex tasks. Define agent roles, communication protocols, delegation patterns, conflict resolution, and workflow sequencing for efficient collaborative AI operations.
+
+## Pre-Conditions
+
+- Complex task requiring multiple expertise domains identified
+- Individual agent personas defined (or to be created via agent-persona-creation task)
+- Orchestration framework or tool available (Claude Code subagents, custom orchestration)
+- Success criteria for the orchestrated workflow defined
+- Context budget and performance constraints established
+
+## Steps
+
+1. **Decompose the Task** — Break the complex task into sub-tasks that map to agent expertise domains. Each sub-task must have: clear input, clear output, single responsible agent, and defined completion criteria. Identify dependencies between sub-tasks.
+2. **Assign Agent Roles** — Map each sub-task to the most appropriate agent based on expertise. Identify the orchestrator agent responsible for coordinating the overall workflow. Ensure no agent is overloaded (max 3-4 sub-tasks per agent).
+3. **Design Communication Protocol** — Define how agents communicate: handoff format (structured YAML artifact with context, decisions, files modified), message passing rules (what to include, what to omit), and escalation paths (when an agent cannot complete its sub-task).
+4. **Build Delegation Matrix** — Create a matrix showing: which agent can delegate to which, what operations are exclusive to each agent, what requires orchestrator approval, and what can be done autonomously. Reference the agent-authority rules.
+5. **Design Workflow Sequencing** — Map the execution order: which sub-tasks run sequentially (output of one feeds input of next), which run in parallel (independent sub-tasks), and which are conditional (only run if previous sub-task produces certain output). Create a workflow diagram.
+6. **Implement Context Compaction** — Design how context is managed across agent switches: use the agent-handoff protocol to compact outgoing agent context (~379 tokens), load incoming agent's full persona, and preserve critical state (story ID, branch, decisions). Target < 500 token overhead per switch.
+7. **Create Conflict Resolution Protocol** — Define how conflicts between agents are resolved: expertise conflicts (two agents claim authority), resource conflicts (agents need the same file), decision conflicts (agents disagree on approach). Escalation hierarchy: peer negotiation -> orchestrator mediation -> human decision.
+8. **Design Quality Gates** — Place quality checkpoints between agent transitions: output validation (does the output meet the receiving agent's input requirements?), completeness check (are all required fields present?), and consistency check (does the output align with previous decisions?).
+9. **Implement Monitoring and Logging** — Design the orchestration log: which agent is active, what sub-task is being executed, time spent per sub-task, handoff events, and escalation events. Enable debugging of orchestration failures.
+10. **Test the Orchestration** — Execute the full orchestrated workflow end-to-end: verify each agent transition preserves necessary context, verify quality gates catch invalid outputs, verify conflict resolution works, and measure total execution time vs. single-agent execution.
+11. **Create Orchestration Template** — Package the orchestration design as a reusable template: workflow definition, agent assignments, communication protocol, and configuration. Enable teams to adapt the template for similar complex tasks.
+
+## Output
+
+```markdown
+# Multi-Agent Orchestration Design
+
+## Task Decomposition
+| Sub-Task | Agent | Input | Output | Dependencies |
+|----------|-------|-------|--------|-------------|
+
+## Delegation Matrix
+| Agent | Can Delegate To | Exclusive Operations |
+|-------|----------------|---------------------|
+
+## Workflow Sequence
+```mermaid
+graph TD
+    A[Start] --> B[Agent 1: Sub-task 1]
+    B --> C{Quality Gate}
+    C -->|Pass| D[Agent 2: Sub-task 2]
+    C -->|Fail| B
+    D --> E[Agent 3: Sub-task 3]
+    E --> F[End]
+```
+
+## Communication Protocol
+### Handoff Format
+```yaml
+handoff:
+  from_agent: "{agent}"
+  to_agent: "{agent}"
+  context: "{summary}"
+  decisions: ["{decision}"]
+  files_modified: ["{file}"]
+  next_action: "{action}"
+```
+
+## Conflict Resolution
+| Conflict Type | Resolution | Escalation |
+|--------------|-----------|-----------|
+
+## Quality Gates
+| Gate | Between | Checks | Pass Criteria |
+|------|---------|--------|--------------|
+
+## Monitoring
+- Log location: {path}
+- Metrics tracked: {list}
+```
+
+## Quality Criteria
+
+- Every sub-task must have exactly one responsible agent (no ambiguity)
+- Context compaction must keep handoff overhead under 500 tokens per transition
+- Quality gates must catch at least 90% of invalid outputs before they reach the next agent
+- Conflict resolution must handle all three conflict types with documented procedures
+- End-to-end orchestration must complete within 2x the time of the longest sequential path
+- Orchestration template must be reusable for at least 2 different task types

package/squad-claude/tasks/multi-project-setup.md

@@ -0,0 +1,72 @@
+---
+task: multi-project-setup
+responsavel: "@project-integrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Multi-Project Setup
+
+## Objective
+
+Configure Claude Code for multi-repo or monorepo setups where multiple projects or packages share common conventions but have distinct configurations. Design the configuration hierarchy to maximize reuse and minimize duplication.
+
+## Inputs
+
+- Repository structure (monorepo with packages/ or multi-repo)
+- Shared conventions (common to all projects)
+- Per-project differences (different stacks, different rules)
+- Workspace tooling (npm workspaces, pnpm, Turborepo, Nx, Lerna)
+- Shared MCP servers vs per-project MCP servers
+
+## Steps
+
+1. **Map Project Topology** — Enumerate all projects/packages with their stacks, dependencies, and unique requirements. Identify shared patterns and divergences.
+2. **Design Configuration Hierarchy** — For monorepo: root CLAUDE.md (shared) + per-package CLAUDE.md (specific). For multi-repo: shared template + per-repo customization.
+3. **Create Root Configuration** — Write root-level CLAUDE.md and settings.json with conventions that apply to ALL projects: coding standards, git conventions, CI/CD patterns.
+4. **Create Per-Project Overrides** — For each project/package, create directory-level CLAUDE.md files with stack-specific instructions that override or extend root conventions.
+5. **Design Shared Rules** — Create .claude/rules/ files for patterns that span multiple projects (e.g., testing standards, API conventions). Use `paths:` to scope them correctly.
+6. **Configure MCP Per-Scope** — Determine which MCP servers are shared (GitHub, Supabase) vs per-project (framework-specific tools). Configure accordingly.
+7. **Test Cross-Project Navigation** — Verify Claude Code loads the correct configuration when navigating between projects/packages within the workspace.
+
+## Quality Gates
+
+- Root configuration must not contain project-specific instructions
+- Per-project configurations must not duplicate root instructions
+- Navigation between projects must load correct context
+- Total configuration size must be within budget for the largest project
+
+## Output Format
+
+```markdown
+# Multi-Project Configuration
+
+## Topology
+{project map}
+
+## Hierarchy
+- Root: {shared config}
+- Project A: {overrides}
+- Project B: {overrides}
+
+## Shared Resources
+{rules, MCP servers, conventions}
+
+## Per-Project Specifics
+{deviations from root}
+```

package/squad-claude/tasks/multi-turn-conversation-design.md

@@ -0,0 +1,93 @@
+---
+task: multi-turn-conversation-design
+responsavel: "@skill-craftsman"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Multi-Turn Conversation Design
+
+## Objective
+
+Design multi-turn conversation flows for AI agents that maintain context coherence, handle branching dialogue paths, manage state across turns, and gracefully handle interruptions, topic switches, and clarification loops.
+
+## Pre-Conditions
+
+- Agent persona and domain scope defined
+- Target conversation scenarios identified (onboarding, troubleshooting, data collection, etc.)
+- Maximum expected conversation length established
+- State management requirements documented
+- Error recovery patterns needed identified
+
+## Steps
+
+1. **Map Conversation Goals** — Identify the primary goals a conversation must achieve: information gathering, task completion, decision support, or knowledge transfer. For each goal, define the minimum turns required and the success criteria.
+2. **Design Conversation States** — Create a state machine for the conversation: initial state, intermediate states (gathering info, processing, confirming), terminal states (success, failure, escalation). Define transitions between states with trigger conditions.
+3. **Build Turn Templates** — For each conversation state, design the agent's turn template: what information to request, how to acknowledge previous input, what context to reference, and what options to present. Include both the prompt text and the expected response format.
+4. **Implement Context Tracking** — Design how the agent tracks information across turns: accumulated data (user preferences, collected inputs), conversation history summary, current state, and pending actions. Define what gets stored vs. what can be re-derived.
+5. **Handle Branching Paths** — Map decision points where the conversation can diverge: user provides unexpected input, user asks a side question, user wants to go back. For each branch, define how to handle it and how to return to the main flow.
+6. **Design Clarification Loops** — Create patterns for handling ambiguous or incomplete inputs: ask for clarification with specific options, provide examples of valid inputs, offer defaults, and set a maximum clarification attempts (3) before escalating.
+7. **Implement Interruption Recovery** — Design how the agent handles mid-conversation interruptions: topic switches (park current topic, address new one, offer to resume), corrections (update stored state, acknowledge the correction), and abandonment (summarize progress, offer to save state).
+8. **Add Progressive Disclosure** — Structure information delivery across turns: start with high-level overview, drill down based on user interest, avoid overwhelming with all details at once. Define depth levels and triggers for going deeper.
+9. **Test Conversation Flows** — Walk through each conversation path manually: happy path (goal achieved in minimum turns), extended path (clarifications needed), interrupted path (topic switches), and failure path (goal cannot be achieved). Document friction points.
+10. **Create Flow Diagrams** — Produce visual conversation flow diagrams showing states, transitions, decision points, and terminal states. Include turn counts and branching probabilities for common paths.
+11. **Write Integration Specs** — Document how the conversation design integrates with the system prompt, tool calls, and external state storage. Specify handoff points for human escalation.
+
+## Output
+
+```markdown
+# Multi-Turn Conversation Design: {Scenario}
+
+## Conversation Goals
+| Goal | Min Turns | Success Criteria |
+|------|-----------|-----------------|
+
+## State Machine
+| State | Entry Condition | Agent Action | Next States |
+|-------|----------------|-------------|-------------|
+
+## Turn Templates
+### State: {state_name}
+**Agent says:** {template with placeholders}
+**Expects:** {input format}
+**Transitions:** {conditions -> next states}
+
+## Context Tracking
+| Field | Source Turn | Persists Until | Usage |
+|-------|-----------|---------------|-------|
+
+## Branching Handlers
+| Branch Type | Detection | Handler | Return Path |
+|-------------|-----------|---------|-------------|
+
+## Flow Diagram
+{mermaid or ASCII diagram}
+
+## Test Paths
+| Path | Turns | Outcome | Issues Found |
+|------|-------|---------|-------------|
+```
+
+## Quality Criteria
+
+- Conversation must reach its goal in under 10 turns for the happy path
+- Every state must have at least one exit transition (no dead ends)
+- Clarification loops must resolve within 3 attempts or escalate
+- Interruption recovery must preserve all previously collected state
+- Flow diagrams must be provided for at least 3 conversation paths
+- Context tracking must not accumulate unbounded state (define cleanup rules)

package/squad-claude/tasks/optimize-context.md

@@ -0,0 +1,75 @@
+---
+task: optimize-context
+responsavel: "@skill-craftsman"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Optimize Context
+
+## Objective
+
+Analyze and optimize the total context window usage of a Claude Code project. Reduce token waste from CLAUDE.md, rules, and knowledge bases while preserving essential information. Target measurable improvement in context efficiency.
+
+## Inputs
+
+- All CLAUDE.md files (root and directory-level)
+- All .claude/rules/ files
+- Knowledge base files (if any)
+- Current pain points (context overflow? slow responses? missing context?)
+- Token budget target
+
+## Steps
+
+1. **Measure Current Footprint** — Estimate token count for each context source: root CLAUDE.md, directory CLAUDE.md files, each rules file, each knowledge base file. Sum for total.
+2. **Score Information Density** — For each section of each file, rate 1-5: 1=noise (generic advice Claude already knows), 3=useful (project-specific but verbose), 5=essential (unique knowledge, high value per token).
+3. **Identify Redundancy** — Find information duplicated across files: same instructions in CLAUDE.md and rules, repeated patterns across directory-level files, knowledge base content also in CLAUDE.md.
+4. **Identify Staleness** — Flag outdated information: references to removed features, old file paths, deprecated patterns, completed TODOs still listed.
+5. **Compress Low-Density Sections** — Rewrite sections scored 1-2: convert paragraphs to tables, remove explanations of things Claude Code knows, replace verbose examples with concise ones.
+6. **Restructure for Conditional Loading** — Move context-specific content from always-loaded CLAUDE.md into .claude/rules/ with `paths:` frontmatter so it only loads when relevant.
+7. **Validate Optimized Context** — Verify no essential information was lost. Re-measure token footprint. Calculate savings percentage.
+
+## Quality Gates
+
+- Total token footprint must decrease by >= 15%
+- No essential information (scored 4-5) may be removed
+- All moved content must have correct `paths:` frontmatter
+- Optimized CLAUDE.md must pass readability check (clear, well-structured)
+
+## Output Format
+
+```markdown
+# Context Optimization Report
+
+## Before
+- Total tokens: {X}
+- Files: {count}
+
+## After
+- Total tokens: {Y}
+- Files: {count}
+- Savings: {percentage}%
+
+## Changes Made
+| File | Action | Token Impact |
+|------|--------|-------------|
+
+## Moved to Rules
+| Content | From | To (rules file) | Path Pattern |
+|---------|------|-----------------|-------------|
+```

package/squad-claude/tasks/optimize-workflow.md

@@ -0,0 +1,75 @@
+---
+task: optimize-workflow
+responsavel: "@skill-craftsman"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Optimize Workflow
+
+## Objective
+
+Analyze and optimize Claude Code interaction workflows to minimize round-trips, reduce context consumption, and maximize output quality. Identify patterns that waste tokens or cause unnecessary back-and-forth and replace them with efficient alternatives.
+
+## Inputs
+
+- Current workflow patterns (how the team uses Claude Code)
+- Common tasks and their typical interaction count
+- Pain points (slow responses, context overflow, repetitive prompts)
+- Available tools and skills
+
+## Steps
+
+1. **Map Current Workflows** — Document the most common interaction patterns: how many messages per typical task, what tools are invoked, how much context is consumed per interaction.
+2. **Identify Anti-Patterns** — Find workflow inefficiencies: over-explaining tasks Claude Code can infer, reading the same files multiple times, not using batch operations, manual steps that could be automated.
+3. **Measure Round-Trip Cost** — For each common task, count the number of human-AI round-trips. Calculate the theoretical minimum (what could be done in one prompt with proper context).
+4. **Design Skill Extractions** — For repeated multi-step workflows, design slash command skills that encapsulate the steps into a single invocable unit.
+5. **Optimize Tool Usage** — Identify cases where better tool selection would reduce interactions: using Glob instead of multiple Read calls, using Edit instead of Write for small changes, batching parallel tool calls.
+6. **Improve Prompt Patterns** — Rewrite common prompt templates for maximum clarity and minimum tokens. Include examples of effective vs. wasteful prompting.
+7. **Validate Improvements** — Estimate the reduction in round-trips, tokens, and time for each optimized workflow. Target >= 30% improvement.
+
+## Quality Gates
+
+- At least 3 workflow optimizations must be identified
+- Each optimization must have measurable improvement (round-trips, tokens, or time)
+- Skill extractions must be practically implementable
+- Prompt pattern improvements must be tested against real scenarios
+
+## Output Format
+
+```markdown
+# Workflow Optimization Report
+
+## Current State
+| Workflow | Avg Round-Trips | Avg Tokens | Pain Point |
+|----------|----------------|------------|------------|
+
+## Optimizations
+### 1. {optimization name}
+- **Before:** {current pattern}
+- **After:** {optimized pattern}
+- **Improvement:** {metrics}
+
+## Extracted Skills
+| Skill | Trigger | Steps Encapsulated |
+|-------|---------|-------------------|
+
+## Prompt Pattern Guide
+| Pattern | Bad Example | Good Example |
+|---------|-------------|--------------|
+```

package/squad-claude/tasks/parallel-decomposition.md

@@ -0,0 +1,77 @@
+---
+task: parallel-decomposition
+responsavel: "@swarm-orchestrator"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Parallel Decomposition
+
+## Objective
+
+Decompose a complex task into parallelizable work units that can be executed by multiple Claude Code subagents simultaneously. Produce a dependency graph, work unit definitions, and aggregation strategy.
+
+## Inputs
+
+- Complex task description
+- Files involved (full list)
+- Known dependencies between files or features
+- Available parallelism (max concurrent agents)
+- Time constraint (if any)
+
+## Steps
+
+1. **Analyze Dependencies** — Map all file-level and feature-level dependencies. Build a dependency graph identifying which work can proceed independently.
+2. **Identify Parallel Units** — Group work into units that have no shared file writes. Each unit must be completable by one agent without needing another agent's output.
+3. **Apply Independence Test** — For each pair of units, verify: no shared file writes, no data dependency (unit B needs unit A's output), no ordering constraint (unit B must follow A).
+4. **Design Synchronization Points** — Where units must reconverge (e.g., all feature code done before integration tests), define explicit sync points with completion criteria.
+5. **Plan Merge Strategy** — Define how parallel outputs are combined: git merge (for worktree isolation), file concatenation (for documentation), or manual review (for conflicting concerns).
+6. **Estimate Speedup** — Calculate theoretical speedup: total sequential time vs. critical path time with N agents. Account for coordination overhead (typically 10-20%).
+7. **Generate Work Unit Specs** — For each parallel unit, produce a complete specification: scope, files, expected output, dependencies, and completion criteria.
+
+## Quality Gates
+
+- No two parallel units may write to the same file
+- Dependency graph must be acyclic (no circular dependencies between units)
+- Every file in the original task must be assigned to exactly one unit
+- Merge strategy must handle all identified conflict scenarios
+- Estimated speedup must be >= 1.5x to justify parallelization overhead
+
+## Output Format
+
+```markdown
+# Parallel Decomposition: {task name}
+
+## Dependency Graph
+{ASCII diagram}
+
+## Work Units
+| Unit | Files | Dependencies | Agent | Est. Time |
+|------|-------|-------------|-------|-----------|
+
+## Synchronization Points
+1. {point}: {criteria}
+
+## Merge Strategy
+{description}
+
+## Estimated Speedup
+- Sequential: {X} min
+- Parallel ({N} agents): {Y} min
+- Speedup: {ratio}x
+```

package/squad-claude/tasks/permission-strategy.md

@@ -0,0 +1,74 @@
+---
+task: permission-strategy
+responsavel: "@config-engineer"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Permission Strategy
+
+## Objective
+
+Design a comprehensive permission strategy for Claude Code that balances security, productivity, and developer experience. Define allow, deny, and auto-approve lists with clear rationale for each decision.
+
+## Inputs
+
+- Project security classification (public / internal / confidential)
+- Team trust level (new team / established / solo developer)
+- Sensitive files and directories (secrets, credentials, production configs)
+- Dangerous commands to restrict (destructive git ops, system commands, network access)
+- Desired automation level (high friction / balanced / low friction)
+
+## Steps
+
+1. **Classify Operations by Risk** — Create a risk matrix of all Claude Code operations: file read/write, bash execution, web access, MCP tool calls. Rate each as low/medium/high/critical risk.
+2. **Define Deny List** — Block operations that should never be executed: reading .env files with secrets, executing destructive system commands, accessing production databases, pushing to protected branches.
+3. **Define Allow List** — Permit with confirmation: operations that are useful but carry moderate risk. File writes outside project scope, network requests, git operations beyond local.
+4. **Define Auto-Approve List** — Permit without confirmation: low-risk, high-frequency operations. File reads within project, grep/glob searches, local git status/diff/log.
+5. **Design File-Level Permissions** — Create glob patterns for sensitive paths that should be read-only or completely blocked: `**/.env*`, `**/credentials/**`, `**/secrets/**`.
+6. **Plan Escalation Path** — Define what happens when Claude Code encounters a blocked operation: clear error message, suggestion for alternative, manual override instructions.
+7. **Document Rationale** — For every permission decision, document why it was made. This enables future teams to adjust without guessing.
+
+## Quality Gates
+
+- Every critical-risk operation must be in the deny list
+- Auto-approve list must not contain any high-risk operations
+- Permission strategy must be implementable in settings.json
+- Rationale must be documented for every deny and auto-approve entry
+
+## Output Format
+
+```markdown
+# Permission Strategy
+
+## Risk Classification
+| Operation | Risk | Permission | Rationale |
+|-----------|------|------------|-----------|
+
+## Deny List (settings.json format)
+...
+
+## Allow List
+...
+
+## Auto-Approve List
+...
+
+## File-Level Restrictions
+...
+```

package/squad-claude/tasks/prompt-testing-framework.md

@@ -0,0 +1,86 @@
+---
+task: prompt-testing-framework
+responsavel: "@skill-craftsman"
+responsavel_type: Agent
+atomic_layer: Task
+elicit: false
+Entrada:
+  - campo: context
+    tipo: object
+    origem: "workflow ou manual"
+    obrigatorio: true
+Saida:
+  - campo: resultado
+    tipo: document
+    destino: "stakeholders"
+Checklist:
+  - "[ ] Validar inputs"
+  - "[ ] Executar steps"
+  - "[ ] Verificar qualidade"
+  - "[ ] Gerar output"
+---
+
+# Prompt Testing Framework
+
+## Objective
+
+Create a systematic framework for testing, evaluating, and iterating on prompts. Establish repeatable test suites with defined metrics, regression detection, and A/B comparison capabilities to ensure prompt quality over time.
+
+## Pre-Conditions
+
+- Prompts to be tested are documented and versioned
+- Test cases with expected outputs are available or can be created
+- Evaluation criteria defined (accuracy, format compliance, tone, safety)
+- Access to run prompts against the target model
+- Baseline metrics established for comparison
+
+## Steps
+
+1. **Define Test Dimensions** — Establish what aspects of prompt output to evaluate: factual accuracy, format compliance, tone consistency, safety adherence, completeness, latency, and token efficiency. Weight each dimension by importance for the use case.
+2. **Create Test Case Categories** — Organize test cases into: happy path (standard inputs), edge cases (boundary conditions), adversarial (attempting to break the prompt), regression (previously fixed issues), and performance (token/latency benchmarks).
+3. **Build Test Suite Structure** — Design the test suite format: each test case includes input, expected output pattern, evaluation criteria, category tag, and priority level. Use a structured format (YAML or JSON) for automation compatibility.
+4. **Design Evaluation Rubrics** — For each test dimension, create a 1-5 scoring rubric with concrete examples at each level. Define pass/fail thresholds (e.g., format compliance must score 4+, accuracy must score 3+).
+5. **Implement Comparison Protocol** — Define how to compare prompt versions: run identical test suites against both versions, compute dimension-level scores, flag regressions (any dimension drops by 1+ points), and compute overall quality delta.
+6. **Create Regression Test Suite** — Build a permanent set of test cases from past failures. Every time a prompt bug is found and fixed, add the trigger input to the regression suite. This suite must pass before any prompt version is promoted.
+7. **Design Reporting Format** — Create a test report template showing: overall score, per-dimension scores, pass/fail per test case, regressions detected, comparison with previous version, and recommended actions.
+8. **Build Iteration Protocol** — Define the prompt improvement cycle: run tests, identify lowest-scoring dimensions, hypothesize improvements, implement changes, re-test, compare, promote or revert. Maximum 5 iterations per improvement cycle.
+9. **Establish Quality Gates** — Define promotion criteria: minimum overall score, no regressions from previous version, all critical test cases pass, regression suite 100% pass rate. Document the gate checklist.
+10. **Document the Framework** — Write a complete guide: how to add test cases, how to run the suite, how to interpret results, how to iterate, and how to maintain the framework over time.
+
+## Output
+
+```markdown
+# Prompt Testing Framework
+
+## Test Dimensions
+| Dimension | Weight | Pass Threshold | Rubric Reference |
+|-----------|--------|---------------|------------------|
+
+## Test Suite
+| ID | Category | Input | Expected Pattern | Dimensions Tested |
+|----|----------|-------|-----------------|-------------------|
+
+## Evaluation Rubric
+### {Dimension}
+| Score | Description | Example |
+|-------|------------|---------|
+
+## Quality Gates
+- [ ] Overall score >= {threshold}
+- [ ] Zero regressions
+- [ ] Critical tests 100% pass
+- [ ] Regression suite 100% pass
+
+## Iteration Log
+| Version | Date | Score | Delta | Changes |
+|---------|------|-------|-------|---------|
+```
+
+## Quality Criteria
+
+- Framework must include at least 20 test cases across all categories
+- Evaluation rubrics must have concrete examples at every score level
+- Regression suite must be automated (no manual scoring for pass/fail)
+- Test reports must be generated in under 5 minutes for a standard suite
+- Framework must detect prompt regressions with at least 90% accuracy
+- Documentation must enable a new team member to run tests independently