sinapse-ai 1.0.0

package/squad-claude/tasks/knowledge-base-architecture.md

@@ -0,0 +1,107 @@
+---
+task: knowledge-base-architecture
+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"
+---
+
+# Knowledge Base Architecture
+
+## Objective
+
+Design a knowledge base architecture for AI-assisted projects that organizes reference material, patterns, and domain knowledge into an efficient, searchable, and maintainable structure. Ensure knowledge is accessible to AI agents at the right time with minimal context window overhead.
+
+## Pre-Conditions
+
+- Knowledge domains and categories identified for the project
+- Content sources available (documentation, code patterns, decision records, guides)
+- Token budget constraints defined per knowledge category
+- Claude Code rules system understood (for integration with retrieval)
+- Maintenance ownership and update cadence established
+
+## Steps
+
+1. **Audit Existing Knowledge** — Inventory all existing knowledge scattered across the project: README files, inline comments, wiki pages, Slack messages, code patterns, architectural decisions, and tribal knowledge. Estimate the total volume and identify gaps.
+2. **Define Knowledge Taxonomy** — Create a hierarchical taxonomy: top-level domains (architecture, patterns, tools, processes), mid-level categories (per domain), and leaf-level topics (specific knowledge items). Each node should have a clear scope statement.
+3. **Design File Structure** — Map the taxonomy to a file structure: one file per major category, consistent naming convention (kebab-case, descriptive names), clear directory hierarchy, and index files for navigation. Balance between too many small files (hard to find) and too few large files (wasteful token loading).
+4. **Create Content Templates** — Design templates for each knowledge type: reference guides (structured tables, concise explanations), pattern libraries (name, context, solution, example), decision records (context, decision, consequences), and how-to guides (steps with examples).
+5. **Write Content Guidelines** — Establish quality standards for KB entries: write for AI consumption (structured, scannable, no fluff), include concrete examples, use tables over paragraphs, keep entries self-contained (no cross-file dependencies for understanding), and version each entry.
+6. **Design Search and Retrieval** — Create retrieval mechanisms: consistent headers and tags for grep-based search, file naming that enables glob-based discovery, integration with Claude Code rules system (path-conditional loading), and a KB index file listing all entries with descriptions.
+7. **Implement Tiered Loading** — Classify KB content into loading tiers: always-loaded (critical conventions, under 1000 tokens), path-conditional (loaded when working on related files), and on-demand (searched and loaded when needed). Minimize always-loaded content.
+8. **Build Maintenance Workflow** — Define how the KB stays current: who owns each section, review schedule (monthly for active areas, quarterly for stable), contribution process (how to add new entries), deprecation process (how to retire outdated entries), and quality review checklist.
+9. **Create Cross-Reference System** — Design how KB entries reference each other: use consistent link format, maintain a dependency graph (which entries reference which), and detect broken references automatically. Avoid circular dependencies.
+10. **Validate Architecture** — Test the KB architecture: can an AI agent find the right knowledge for 10 sample questions? Is the token overhead acceptable? Are there gaps in coverage? Is the structure intuitive for new contributors?
+
+## Output
+
+```markdown
+# Knowledge Base Architecture
+
+## Taxonomy
+```
+knowledge-base/
+├── {domain-1}/
+│   ├── {category-1}.md
+│   └── {category-2}.md
+├── {domain-2}/
+│   ├── {category-1}.md
+│   └── {category-2}.md
+└── KB-INDEX.md
+```
+
+## Content Templates
+### Reference Guide Template
+{template}
+
+### Pattern Library Template
+{template}
+
+### Decision Record Template
+{template}
+
+## Loading Tiers
+| Tier | Content | Token Budget | Loading Method |
+|------|---------|-------------|---------------|
+
+## Maintenance Schedule
+| Section | Owner | Review Cycle | Last Reviewed |
+|---------|-------|-------------|--------------|
+
+## Search Guide
+| Query Type | Method | Example |
+|-----------|--------|---------|
+| Find by topic | Grep header | `grep "## {topic}"` |
+| Find by tag | Grep tag | `grep "tags:.*{tag}"` |
+| Browse domain | Glob | `ls knowledge-base/{domain}/` |
+
+## Quality Metrics
+| Metric | Target | Current |
+|--------|--------|---------|
+| Coverage (domains with KB) | 100% | {%} |
+| Freshness (entries updated < 90d) | 80% | {%} |
+| Token efficiency (useful/total) | > 70% | {%} |
+```
+
+## Quality Criteria
+
+- Taxonomy must cover all identified knowledge domains with no orphan entries
+- Always-loaded content must total under 1000 tokens
+- Every KB entry must follow the appropriate content template
+- Search must return relevant results for 90% of test queries within 2 attempts
+- Maintenance workflow must have clear ownership for every section
+- Architecture must be extensible (adding a new domain requires no structural changes)

package/squad-claude/tasks/knowledge-retrieval-optimization.md

@@ -0,0 +1,90 @@
+---
+task: knowledge-retrieval-optimization
+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"
+---
+
+# Knowledge Retrieval Optimization
+
+## Objective
+
+Optimize knowledge retrieval patterns for Claude Code projects so that the right information is available at the right time without wasting context tokens on irrelevant content. Design tiered retrieval strategies that balance immediacy with token efficiency.
+
+## Pre-Conditions
+
+- Knowledge base files exist (KBs, docs, reference material)
+- Usage patterns observed (which knowledge is accessed when)
+- Context window budget constraints established
+- Claude Code rules system understood (paths: frontmatter, directory CLAUDE.md)
+- Project workflow stages documented
+
+## Steps
+
+1. **Catalog Knowledge Assets** — Inventory all knowledge sources: KB files, documentation, reference tables, code examples, API specs, and decision records. For each, record: token count, access frequency, usage context (which tasks need it), and staleness risk.
+2. **Analyze Access Patterns** — Map which knowledge is needed for which tasks: development tasks need API specs and code patterns, review tasks need quality criteria, setup tasks need configuration references. Create a task-to-knowledge dependency matrix.
+3. **Design Retrieval Tiers** — Create a tiered retrieval system: Tier 1 (always in context) — critical rules and conventions, < 2000 tokens; Tier 2 (loaded by path trigger) — file-specific knowledge, loaded via rules with `paths:` frontmatter; Tier 3 (on-demand) — searchable reference material, retrieved via Grep when needed.
+4. **Optimize Tier 1 Content** — Review always-loaded content ruthlessly: every token must earn its place. Compress tables, remove explanatory prose Claude already understands, use shorthand notation, and link to Tier 2/3 for details instead of including them.
+5. **Configure Tier 2 Triggers** — For each piece of path-conditional knowledge, define the optimal trigger pattern: which file paths should load this knowledge? Too broad = wasted tokens, too narrow = knowledge missing when needed. Test trigger patterns against real workflow scenarios.
+6. **Build Tier 3 Search Index** — Organize on-demand knowledge for efficient retrieval: use consistent file naming, add searchable headers and tags, structure content with clear sections that can be extracted independently, and create a search guide documenting what is available and where.
+7. **Implement Preloading Heuristics** — Design rules that preload knowledge based on context signals: if the user mentions "database", preload schema reference; if working on tests, preload test patterns; if in a specific directory, preload that component's documentation.
+8. **Create Knowledge Freshness Protocol** — Define how knowledge stays current: review schedule per knowledge category, staleness indicators (references to deprecated APIs, old file paths), automated freshness checks (grep for referenced paths that no longer exist), and update workflow.
+9. **Measure Retrieval Effectiveness** — Design metrics to evaluate the retrieval system: hit rate (was the right knowledge available when needed?), waste rate (was irrelevant knowledge loaded?), miss rate (was needed knowledge not available?), and latency (how quickly was knowledge retrieved?).
+10. **Document Retrieval Architecture** — Create a complete document showing: the tiered system, how to add new knowledge, how to configure triggers, how to search, and how to maintain the system.
+
+## Output
+
+```markdown
+# Knowledge Retrieval Optimization
+
+## Knowledge Inventory
+| Asset | Tokens | Tier | Trigger | Access Frequency |
+|-------|--------|------|---------|-----------------|
+
+## Tier Architecture
+| Tier | Strategy | Budget | Content Types |
+|------|----------|--------|--------------|
+| 1 | Always loaded | {tokens} | {types} |
+| 2 | Path-conditional | {tokens max} | {types} |
+| 3 | On-demand search | unlimited | {types} |
+
+## Tier 2 Trigger Map
+| Knowledge File | Path Pattern | Estimated Loads/Day |
+|---------------|-------------|-------------------|
+
+## Preloading Heuristics
+| Context Signal | Knowledge Preloaded | Trigger Method |
+|---------------|-------------------|---------------|
+
+## Freshness Protocol
+| Category | Review Cycle | Staleness Check | Owner |
+|----------|-------------|----------------|-------|
+
+## Effectiveness Metrics
+| Metric | Target | Measurement Method |
+|--------|--------|-------------------|
+```
+
+## Quality Criteria
+
+- Tier 1 content must be under 2000 tokens total
+- Tier 2 triggers must have zero false-negative rate (never miss loading needed knowledge)
+- Tier 3 search must return relevant results within 2 search queries
+- Overall retrieval system must reduce token waste by at least 25% vs. flat loading
+- Freshness protocol must catch stale references within one review cycle
+- Documentation must enable a new team member to understand and extend the system

package/squad-claude/tasks/mcp-integration-audit.md

@@ -0,0 +1,98 @@
+---
+task: mcp-integration-audit
+responsavel: "@mcp-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"
+---
+
+# MCP Integration Audit
+
+## Objective
+
+Audit all existing MCP server integrations in a project for health, security, performance, and usage patterns. Identify unused servers, misconfigured tools, security vulnerabilities, and optimization opportunities. Produce an actionable audit report with prioritized remediation steps.
+
+## Pre-Conditions
+
+- Access to project MCP configuration (settings.json, .claude.json, Docker MCP config)
+- List of all configured MCP servers and their purposes
+- Access to run diagnostic commands against each server
+- Understanding of which tools are actively used vs. dormant
+- Security policy for credential management
+
+## Steps
+
+1. **Inventory All MCP Servers** — Scan all configuration sources: project settings.json, user .claude.json, Docker MCP catalog, and any custom server registrations. List every server with its name, transport type, tool count, and configuration status.
+2. **Test Connectivity** — For each server, perform a health check: attempt connection, verify handshake, list available tools, and measure connection latency. Flag servers that fail to connect or have latency above 5 seconds.
+3. **Audit Security Configuration** — For each server, check: are credentials stored in environment variables (not hardcoded)? Are API keys rotated regularly? Is network access scoped appropriately? Are tool permissions restrictive or permissive? Flag any security violations.
+4. **Analyze Usage Patterns** — Review recent usage data: which tools are called frequently, which are never used, which have high error rates. Cross-reference with project needs to identify servers that are no longer needed.
+5. **Check for Redundancy** — Identify overlapping capabilities: multiple servers providing similar tools (e.g., two web search servers), tools duplicating native Claude Code capabilities, or servers with overlapping resource access.
+6. **Assess Performance Impact** — Measure the performance overhead of each server: startup time, per-tool latency, memory usage, and impact on Claude Code context window (tool descriptions consume tokens). Calculate total MCP overhead.
+7. **Verify Error Handling** — For each server, trigger common error scenarios: invalid input, auth failure, timeout. Verify that error messages are informative, non-leaking (no credentials in errors), and that failures don't crash the Claude Code session.
+8. **Review Configuration Drift** — Compare current configuration against the documented integration plan (if one exists). Identify configuration that has drifted: changed environment variables, updated server versions, added/removed tools without documentation.
+9. **Generate Remediation Plan** — Prioritize findings by severity (Critical/High/Medium/Low). For each finding, provide: description, impact, remediation steps, estimated effort, and responsible party. Group related findings.
+10. **Produce Audit Report** — Compile all findings into a structured report with executive summary, detailed findings, server-by-server health cards, and the prioritized remediation plan.
+
+## Output
+
+```markdown
+# MCP Integration Audit Report
+
+## Executive Summary
+- Servers audited: {count}
+- Healthy: {count} | Degraded: {count} | Failed: {count}
+- Critical findings: {count}
+- Estimated remediation effort: {hours}
+
+## Server Health Cards
+### {Server Name}
+| Metric | Value | Status |
+|--------|-------|--------|
+| Connectivity | {pass/fail} | {emoji} |
+| Security | {score}/5 | {emoji} |
+| Usage (30d) | {call count} | {active/dormant} |
+| Latency (p95) | {ms} | {ok/slow} |
+| Error rate | {%} | {ok/high} |
+
+## Findings
+| # | Severity | Server | Finding | Remediation |
+|---|----------|--------|---------|-------------|
+
+## Remediation Plan
+### Critical (fix immediately)
+1. {finding + steps}
+
+### High (fix this sprint)
+1. {finding + steps}
+
+### Medium (schedule)
+1. {finding + steps}
+
+## Recommendations
+- Remove: {servers to decommission}
+- Upgrade: {servers needing updates}
+- Add: {missing capabilities}
+```
+
+## Quality Criteria
+
+- Every configured MCP server must be tested (zero skipped)
+- Security audit must check credentials storage, network scope, and permission breadth
+- Usage analysis must cover at least 30 days of activity (or available history)
+- Remediation plan must have estimated effort for every Critical and High finding
+- Audit report must be actionable without requiring additional investigation
+- Redundant servers must be identified with a specific recommendation (keep/remove/merge)

package/squad-claude/tasks/mcp-integration-plan.md

@@ -0,0 +1,75 @@
+---
+task: mcp-integration-plan
+responsavel: "@mcp-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"
+---
+
+# MCP Integration Plan
+
+## Objective
+
+Design a comprehensive MCP integration plan for a project, selecting the right servers, transport types, and security configurations. Produce ready-to-use configuration entries for settings.json.
+
+## Inputs
+
+- Project requirements (what external services are needed)
+- Available MCP servers (from marketplace or custom)
+- Infrastructure constraints (Docker available? Network restrictions?)
+- Security requirements (authentication, network isolation)
+- Budget for external services
+
+## Steps
+
+1. **Inventory Requirements** — List all external service integrations needed: database (Supabase), version control (GitHub), design (Figma), communication (Slack, Gmail), documentation (Notion), etc.
+2. **Match Servers to Requirements** — For each requirement, identify the best MCP server. Check official registry, community servers, and evaluate if a custom server is needed.
+3. **Select Transport Types** — For each server, choose transport: stdio for local CLI tools, SSE for remote HTTP services, Docker for isolated/managed deployments. Document the rationale.
+4. **Design Security Configuration** — For each server: define required environment variables, authentication method, network access scope, and tool-level permissions.
+5. **Plan Installation Order** — Sequence server installations to handle dependencies. Some servers may depend on others being available first.
+6. **Generate Configuration** — Produce the complete MCP server configuration block for settings.json with all servers, their transports, commands, args, and env references.
+7. **Create Test Plan** — For each server, define a smoke test: connect, list tools, execute one representative tool call, verify response.
+
+## Quality Gates
+
+- Every requirement must map to at least one MCP server
+- No server should have hardcoded credentials (environment variables only)
+- Transport type must match infrastructure constraints
+- Each server must have a documented smoke test
+- Total number of MCP servers should not exceed reasonable limits (< 15 for performance)
+
+## Output Format
+
+```markdown
+# MCP Integration Plan
+
+## Server Registry
+| # | Server | Transport | Purpose | Auth Method |
+|---|--------|-----------|---------|-------------|
+
+## Configuration (settings.json)
+{JSON block}
+
+## Environment Variables Required
+{list with descriptions}
+
+## Smoke Tests
+{per-server test instructions}
+
+## Installation Order
+1. ...
+```

package/squad-claude/tasks/mcp-server-design.md

@@ -0,0 +1,94 @@
+---
+task: mcp-server-design
+responsavel: "@mcp-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"
+---
+
+# MCP Server Design
+
+## Objective
+
+Design a custom MCP (Model Context Protocol) server architecture from scratch, including tool definitions, resource endpoints, transport configuration, authentication, error handling, and deployment strategy. Produce a complete technical specification ready for implementation.
+
+## Pre-Conditions
+
+- Use case requiring custom MCP server identified (no existing server covers the need)
+- Target API or service to wrap is documented and accessible
+- MCP SDK version and transport requirements known (stdio, SSE, streamable HTTP)
+- Security and authentication requirements defined
+- Performance requirements established (latency, throughput, concurrent connections)
+
+## Steps
+
+1. **Define Server Scope** — Document exactly what the MCP server will expose: list of tools (actions the model can take), list of resources (data the model can read), and list of prompts (templates the model can use). Each must have a clear purpose statement.
+2. **Design Tool Schemas** — For each tool, define: name (verb-noun format), description (what it does and when to use it), input schema (JSON Schema with required/optional fields, types, validation), and output schema (response structure with examples).
+3. **Design Resource Endpoints** — For each resource, define: URI pattern, MIME type, description, and access pattern (direct read, template with parameters, subscription for updates). Include pagination strategy for large resources.
+4. **Plan Transport Layer** — Select and configure the transport: stdio for CLI integration, SSE for HTTP streaming, or streamable HTTP for modern deployments. Define connection lifecycle, reconnection strategy, and timeout configuration.
+5. **Architect Authentication** — Design the auth flow: API key injection via environment variables, OAuth2 token management, or custom auth headers. Define how credentials are stored (never hardcoded), rotated, and validated on each request.
+6. **Design Error Handling** — Create an error taxonomy: auth failures (401/403), rate limits (429), service unavailable (503), invalid input (400), and internal errors (500). For each, define the MCP error response format and recovery suggestion.
+7. **Plan Rate Limiting and Caching** — Design rate limit handling: detect limits from upstream API, implement backoff strategy, queue requests when throttled. Design caching layer for repeated reads: TTL per resource type, cache invalidation triggers.
+8. **Write Server Configuration Schema** — Define the configuration file format: server name, version, transport settings, auth configuration, tool toggles (enable/disable individual tools), logging level, and custom options.
+9. **Design Logging and Observability** — Plan structured logging: request/response logging (with PII redaction), performance metrics (latency per tool), error rates, and health check endpoint. Define log levels and rotation policy.
+10. **Create Deployment Specification** — Document deployment options: npm package (for stdio), Docker container (for isolated deployment), or cloud function (for serverless). Include Dockerfile, package.json scripts, and CI/CD pipeline requirements.
+11. **Write Integration Test Plan** — Define integration tests: connect to server, list tools/resources, execute each tool with valid input, execute with invalid input, test auth failure, test rate limit handling, test concurrent requests.
+
+## Output
+
+```markdown
+# MCP Server Design: {Server Name}
+
+## Overview
+- Purpose: {what this server enables}
+- Transport: {stdio | SSE | streamable HTTP}
+- Tools: {count}
+- Resources: {count}
+
+## Tool Definitions
+### {tool_name}
+- Description: {description}
+- Input Schema: {JSON Schema}
+- Output Schema: {JSON Schema}
+- Error Cases: {list}
+
+## Resource Definitions
+### {resource_uri}
+- MIME Type: {type}
+- Access Pattern: {direct | template | subscription}
+
+## Configuration Schema
+{JSON Schema for server config}
+
+## Deployment
+- Primary: {deployment method}
+- Dockerfile: {included}
+- CI/CD: {pipeline spec}
+
+## Integration Tests
+| Test | Tool/Resource | Input | Expected | Priority |
+|------|--------------|-------|----------|----------|
+```
+
+## Quality Criteria
+
+- Every tool must have a complete JSON Schema for input and output
+- Error handling must cover all 5 error categories with specific recovery suggestions
+- Authentication must never expose credentials in logs or error messages
+- Server must handle graceful shutdown (complete in-flight requests before exit)
+- Design must include at least one caching strategy for read-heavy tools
+- Deployment spec must include health check endpoint and readiness probe

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

@@ -0,0 +1,75 @@
+---
+task: mcp-workflow
+responsavel: "@mcp-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"
+---
+
+# MCP Workflow
+
+## Objective
+
+Create MCP-powered workflows that combine multiple MCP servers into coherent automation pipelines. Design tool chains where the output of one MCP tool feeds into another, enabling complex cross-service automations.
+
+## Inputs
+
+- Workflow goal (e.g., "sync Figma designs to code", "auto-create GitHub issues from Notion tasks")
+- Available MCP servers (already configured)
+- Trigger condition (manual, hook-based, scheduled)
+- Data flow requirements (what data moves between services)
+
+## Steps
+
+1. **Map Data Flow** — Draw the data flow between MCP servers: Source -> Transform -> Destination. Identify what data each tool needs and produces.
+2. **Identify Tool Chain** — For each step in the flow, identify the specific MCP tool to call. Verify each tool's input/output schema is compatible with the chain.
+3. **Design Error Handling** — For each step: what happens on failure? Retry? Skip? Compensate (undo previous steps)? Alert?
+4. **Handle Authentication Flow** — Ensure each server in the chain has valid credentials and that token refresh or re-authentication is handled gracefully.
+5. **Build Orchestration Logic** — Write the orchestration as either a hook chain (for event-driven), a Claude Code skill (for manual trigger), or a CI/CD step (for scheduled).
+6. **Add Monitoring** — Design health checks and logging for each step in the workflow. Include latency tracking and error rate monitoring.
+7. **Test End-to-End** — Create a test scenario that exercises the full workflow with representative data.
+
+## Quality Gates
+
+- Data flow must be fully mapped with no gaps
+- Every tool in the chain must have compatible input/output schemas
+- Error handling must cover all failure modes
+- Authentication must not require manual intervention during workflow execution
+- End-to-end test must pass
+
+## Output Format
+
+```markdown
+# MCP Workflow: {name}
+
+## Data Flow Diagram
+{ASCII diagram or description}
+
+## Tool Chain
+| Step | MCP Server | Tool | Input | Output |
+|------|-----------|------|-------|--------|
+
+## Error Handling Matrix
+| Step | Failure Mode | Action |
+|------|-------------|--------|
+
+## Orchestration
+{hook config / skill definition / CI step}
+
+## Test Plan
+{end-to-end test scenario}
+```

package/squad-claude/tasks/memory-system-design.md

@@ -0,0 +1,103 @@
+---
+task: memory-system-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"
+---
+
+# Memory System Design
+
+## Objective
+
+Design a persistent memory system for Claude Code projects that retains important context across sessions, manages agent-specific memories, and provides efficient retrieval of historical decisions, patterns, and learnings without overwhelming the context window.
+
+## Pre-Conditions
+
+- Project with multi-session workflow (context lost between sessions)
+- Important decisions and patterns that need to persist identified
+- Agent or role-specific memory requirements documented
+- Storage location and format preferences established
+- Context budget for memory loading defined
+
+## Steps
+
+1. **Identify Memory Categories** — Define what types of information need persistence: architectural decisions (ADRs), coding patterns established, user preferences, project conventions, error resolutions, performance baselines, and workflow configurations. Categorize as critical (always load), frequent (load on demand), and archival (search when needed).
+2. **Design Memory Schema** — Create a structured format for memory entries: unique ID, category, creation date, last accessed date, relevance score, content, source (which agent/session created it), and expiration policy. Use YAML or JSON for machine readability.
+3. **Plan Storage Architecture** — Define where memories are stored: MEMORY.md files per agent (simple, git-tracked), a centralized memory database (structured, queryable), or a hybrid approach. Consider git-friendliness, searchability, and token efficiency.
+4. **Implement Memory Lifecycle** — Design the full lifecycle: creation (when new memory is added), validation (is it worth remembering?), consolidation (merge related memories), retrieval (find relevant memories for current task), deprecation (mark outdated), and pruning (remove expired/low-value entries).
+5. **Design Retrieval Strategy** — Create rules for loading memories into context: always-load memories go in CLAUDE.md or rules, task-triggered memories load based on file paths or agent activation, and search-based memories are retrieved on demand via grep or index.
+6. **Build Memory Scoring System** — Implement a scoring system that prioritizes memories: recency (recently created/accessed score higher), frequency (frequently accessed score higher), impact (memories that prevented errors score higher), and relevance (memories matching current task context score higher).
+7. **Create Memory Compaction** — Design how memories are compressed over time: detailed entries age into summaries, multiple related entries merge into patterns, and specific examples generalize into rules. Define compaction triggers (memory count threshold, age threshold).
+8. **Implement Cross-Agent Memory Sharing** — Design how agents share memories: shared memory space for team-wide decisions, agent-specific memory for persona-related learnings, and handoff memories for agent-to-agent transitions (reference the agent-handoff protocol).
+9. **Add Memory Validation Gates** — Create quality gates for new memories: is this information not already known by Claude? Is it specific enough to be useful? Is it stable (not likely to change next session)? Does it fit within the memory budget? Reject memories that fail validation.
+10. **Design Memory Dashboard** — Create a memory health report: total memory entries, token budget usage, memory age distribution, most/least accessed entries, candidates for compaction, and candidates for pruning.
+
+## Output
+
+```markdown
+# Memory System Design
+
+## Memory Categories
+| Category | Load Strategy | Max Entries | Token Budget |
+|----------|-------------|-------------|-------------|
+
+## Memory Schema
+```yaml
+memory:
+  id: "{uuid}"
+  category: "{category}"
+  created: "{date}"
+  last_accessed: "{date}"
+  relevance_score: {1-10}
+  source_agent: "{agent_id}"
+  content: "{memory content}"
+  expiration: "{policy}"
+```
+
+## Storage Architecture
+- Primary: {storage method}
+- Index: {search/retrieval method}
+- Backup: {backup strategy}
+
+## Lifecycle Rules
+| Phase | Trigger | Action | Output |
+|-------|---------|--------|--------|
+
+## Retrieval Rules
+| Context | Memories Loaded | Method |
+|---------|----------------|--------|
+
+## Compaction Rules
+| Trigger | Action | Example |
+|---------|--------|---------|
+
+## Memory Budget
+- Total budget: {tokens}
+- Always-load: {tokens} ({%})
+- On-demand: {tokens} ({%})
+- Search: unlimited (not pre-loaded)
+```
+
+## Quality Criteria
+
+- Memory system must operate within defined token budget (no context overflow)
+- Retrieval must surface relevant memories with at least 80% precision
+- Compaction must reduce memory token count by at least 30% without losing critical information
+- Cross-agent memory sharing must respect agent boundaries (no leaking persona-specific memories)
+- Memory validation gates must reject at least 40% of candidate memories (ensuring quality)
+- Memory dashboard must accurately report current state and actionable recommendations