mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/agent-memory-design/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: agent-memory-design
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: agent memory design, short-term memory, long-term memory, memory retrieval, memory consolidation, memory decay, episodic memory, semantic memory, memory architecture, working memory, memory indexing, knowledge persistence
+---
+
+# Skill — Agent Memory Design (Multi-Layer Knowledge Persistence)
+
+## When this skill activates
+When designing memory systems for AI agents, implementing context persistence across
+sessions, building knowledge retrieval mechanisms, or architecting memory consolidation
+pipelines. Use for any agent that needs to remember information beyond a single context
+window.
+
+Core principle: **Memory is retrieval, not storage** — the value of a memory system
+is measured by: can the agent find the RIGHT information at the RIGHT time? Storage
+without retrieval is a graveyard.
+
+## Mandatory actions when this skill is active
+
+### Memory Layer Architecture
+
+1. **Four-tier memory model:**
+   ```
+   Layer 1 — Working Memory (context window)
+   - Scope: current conversation turn
+   - Capacity: model context limit (8K-200K tokens)
+   - Persistence: none (gone when context resets)
+   - Access: immediate (already in context)
+   - Priority: highest — this is what the agent "sees"
+
+   Layer 2 — Short-Term Memory (session scratchpad)
+   - Scope: current session/task
+   - Capacity: 10-50 key facts
+   - Persistence: session duration
+   - Access: explicit retrieval (agent requests it)
+   - Format: JSONL scratchpad file
+   - Use for: intermediate results, task progress, recent user preferences
+
+   Layer 3 — Medium-Term Memory (project knowledge)
+   - Scope: current project/workspace
+   - Capacity: hundreds of entries
+   - Persistence: project lifetime
+   - Access: semantic search + key lookup
+   - Format: structured markdown files, JSON indexes
+   - Use for: architectural decisions, user patterns, project conventions
+
+   Layer 4 — Long-Term Memory (permanent knowledge)
+   - Scope: cross-project, cross-session
+   - Capacity: unbounded
+   - Persistence: permanent (with decay)
+   - Access: semantic similarity search + knowledge graph traversal
+   - Format: vector DB + knowledge graph
+   - Use for: learned patterns, user preferences, domain expertise
+   ```
+
+### Retrieval Strategies
+
+2. **Retrieval by memory layer:**
+   ```
+   Working Memory:
+   - Already in context — no retrieval needed
+   - Manage carefully: don't waste on retrievable facts
+
+   Short-Term Memory:
+   - Recency-weighted retrieval (most recent = most relevant)
+   - Key-based lookup: "what was the last error message?"
+   - Cleared at session end (or explicit flush)
+
+   Medium-Term Memory:
+   - Keyword + semantic hybrid search
+   - Structured queries: "what auth pattern does this project use?"
+   - Indexed by: topic, file path, date, relevance score
+
+   Long-Term Memory:
+   - Semantic similarity search (embedding-based)
+   - Knowledge graph traversal (entity → relationship → entity)
+   - Confidence-weighted (higher confidence = higher ranking)
+   - Decay-adjusted (older unreinforced memories rank lower)
+   ```
+
+3. **Retrieval decision flow:**
+   ```
+   When agent needs information:
+   1. Check working memory (already in context?) → use it
+   2. Check short-term memory (recent session fact?) → retrieve and inject
+   3. Check medium-term memory (project knowledge?) → search and inject summary
+   4. Check long-term memory (learned pattern?) → search, verify relevance, inject
+   5. If not found anywhere → ask user or research from scratch
+   ```
+
+### Memory Consolidation
+
+4. **End-of-session consolidation pipeline:**
+   ```
+   Session ends → Consolidation triggers:
+
+   1. Extract key learnings from session:
+      - New facts learned (user preferences, project decisions)
+      - Patterns observed (what worked, what failed)
+      - Corrections received (mistakes to avoid next time)
+
+   2. Classify each learning:
+      - Short-term only (task-specific, won't matter next session) → discard
+      - Medium-term (project-relevant) → write to project memory
+      - Long-term (generalizable pattern) → write to permanent memory
+
+   3. Summarize, don't dump:
+      - Raw conversation → extract 5-10 key facts
+      - Include WHY something matters, not just WHAT happened
+      - Link to existing memories (reinforce or update)
+
+   4. Update indexes:
+      - Add new entries to search indexes
+      - Update confidence scores on existing memories
+      - Deprecate contradicted memories
+   ```
+
+   Rules:
+   - Consolidation must be LOSSY (summarize, compress, extract — not raw dump)
+   - Every memory entry needs: content, source, timestamp, confidence, tags
+   - Contradictions: new information supersedes old (but keep old as "deprecated")
+
+### Memory Decay
+
+5. **Confidence decay model:**
+   ```
+   Each memory entry has a confidence score [0.0 - 1.0]:
+
+   Initial confidence:
+   - User explicitly stated: 1.0
+   - Inferred from behavior: 0.7
+   - Assumed from patterns: 0.5
+
+   Decay rules:
+   - Unreinforced memory: confidence -= 0.05 per week
+   - Reinforced memory (used successfully): confidence = min(1.0, confidence + 0.1)
+   - Contradicted memory: confidence = 0.0 (deprecated, kept for history)
+   - Below threshold (confidence < 0.2): excluded from retrieval results
+
+   Reinforcement triggers:
+   - Agent retrieves memory and uses it successfully
+   - User confirms a remembered fact
+   - Pattern matches current observation
+   ```
+
+### Implementation Patterns
+
+6. **Storage format by layer:**
+   ```
+   Short-term (JSONL scratchpad):
+   {"key": "last_error", "value": "TypeError at line 42", "ts": "...", "confidence": 1.0}
+   {"key": "user_intent", "value": "refactoring auth module", "ts": "...", "confidence": 0.9}
+
+   Medium-term (structured markdown):
+   ## Project: MindForge
+   ### Architecture Decisions
+   - Auth: JWT with refresh tokens (decided 2024-03-15, confidence: 1.0)
+   - Database: PostgreSQL with Prisma ORM (decided 2024-03-10, confidence: 1.0)
+   ### User Preferences
+   - Prefers functional style over OOP (confidence: 0.8)
+   - Wants verbose error messages in dev (confidence: 0.9)
+
+   Long-term (vector DB + knowledge graph):
+   Entry: {id, embedding, content, source, timestamp, confidence, tags, relationships}
+   Graph: (pattern)--[applies_to]-->(domain)--[learned_from]-->(project)
+   ```
+
+7. **Working memory budget management:**
+   ```
+   Context window is finite — manage it:
+
+   Priority for inclusion in working memory:
+   1. Current user message and task context (always)
+   2. Relevant retrieved memories (top-k by relevance)
+   3. System instructions and constraints (always)
+   4. Recent conversation history (sliding window)
+
+   If context is filling up:
+   - Summarize older conversation turns (don't drop, compress)
+   - Move detailed context to short-term memory (retrieve if needed)
+   - Keep only TOP-5 most relevant retrieved memories in context
+   - Never sacrifice system instructions for conversation history
+   ```
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I define all four memory layers with clear scope and access patterns?
+- [ ] Is retrieval strategy defined per layer (recency, semantic, key-based)?
+- [ ] Is there a consolidation pipeline that extracts and summarizes key learnings?
+- [ ] Is consolidation lossy (summarize, don't dump raw conversation)?
+- [ ] Is memory decay implemented (confidence decreases without reinforcement)?
+- [ ] Are contradicted memories deprecated (not deleted)?
+- [ ] Is working memory budget managed (prioritized inclusion, compression when full)?
+- [ ] Does every memory entry have: content, source, timestamp, confidence, tags?

package/.mindforge/skills/agent-orchestration-patterns/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: agent-orchestration-patterns
+version: 1.0.0
+min_mindforge_version: 10.0.7
+status: stable
+triggers: agent orchestration pattern, supervisor worker pattern, agent pipeline topology, agent debate pattern, agent consensus protocol, map reduce agents, handoff protocol design, multi-agent coordination, agent topology design, swarm pattern design, agent composition, failure propagation pattern
+compose:
+  - tool-design
+---
+
+# Agent Orchestration Patterns
+
+## When this skill activates
+
+This skill activates when designing multi-agent systems, choosing coordination topologies, implementing handoff protocols, or debugging agent-to-agent communication failures. It applies to any system where two or more autonomous agents must collaborate, compete, or chain their outputs to accomplish a goal.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Map the problem space** — Identify all subtasks. Determine which require sequential execution (dependencies) and which are independent (parallelizable).
+2. **Assess complexity** — Single-agent tasks masquerading as multi-agent problems waste coordination overhead. Only orchestrate when genuine specialization or parallelism is needed.
+3. **Define boundaries** — Each agent must have a clear responsibility boundary. Overlapping responsibilities cause conflicts. Gaps cause dropped tasks.
+4. **Choose state strategy** — Decide upfront: shared state (agents read/write common store) or isolated state (agents communicate only via messages).
+
+### During
+
+#### Pattern Catalog
+
+**1. Supervisor/Worker (Hub and Spoke)**
+- **Topology** — One coordinator agent decomposes the task and dispatches subtasks to N worker agents. Workers report results back to the supervisor.
+- **When to use** — Task is decomposable into independent units. Workers are interchangeable or specialized but non-overlapping.
+- **Supervisor responsibilities** — Task decomposition, worker assignment, result aggregation, error handling, timeout enforcement.
+- **Worker responsibilities** — Execute assigned subtask, report structured results, signal failure early.
+- **Pitfall** — Supervisor becomes bottleneck. Mitigate with async dispatch and parallel worker execution.
+
+**2. Pipeline (Sequential Chain)**
+- **Topology** — Agent A's output becomes Agent B's input. Linear flow through N stages.
+- **When to use** — Tasks have natural ordering (research → draft → review → publish). Each stage transforms or enriches the previous output.
+- **Stage contract** — Each stage must define its input schema and output schema. Type mismatch between stages is the most common pipeline failure.
+- **Error handling** — Fail the pipeline on any stage failure. Partial results from earlier stages should be preserved for debugging.
+- **Optimization** — Streaming between stages reduces latency. Agent B can begin processing as Agent A emits output.
+
+**3. Debate (Adversarial)**
+- **Topology** — Two or more agents argue opposing positions. A synthesizer agent evaluates arguments and produces a final decision.
+- **When to use** — High-stakes decisions where bias is a risk. Architecture choices, security reviews, strategic decisions.
+- **Protocol** — Round 1: each debater states position with evidence. Round 2: each debater rebuts opponent's position. Round 3: synthesizer produces verdict with reasoning.
+- **Constraint** — Debaters must not see each other's initial positions until after Round 1. Prevents anchoring.
+- **Pitfall** — Debates can be unproductive without strict structure. Always time-box rounds.
+
+**4. Consensus (Agreement Required)**
+- **Topology** — All agents must agree on the output. Disagreement triggers re-evaluation.
+- **When to use** — Safety-critical decisions. Deployment approvals. Security assessments. Changes where false positives are acceptable but false negatives are dangerous.
+- **Protocol** — Each agent independently evaluates. If all approve: proceed. If any reject: block and surface the dissenting reasoning.
+- **Threshold variants** — Unanimous (all agree), Majority (>50%), Supermajority (>66%), Quorum (minimum N must vote).
+- **Pitfall** — Consensus is expensive. Reserve for decisions where the cost of a wrong answer far exceeds the cost of deliberation.
+
+**5. MapReduce (Parallel Processing)**
+- **Topology** — Map phase: split input into N chunks, dispatch to N parallel agents. Reduce phase: aggregate results into final output.
+- **When to use** — Large inputs that can be processed independently (code review across files, document analysis, test execution).
+- **Map function** — Must produce non-overlapping chunks. Overlap causes duplicate work or conflicting results.
+- **Reduce function** — Must handle partial failures gracefully. If 1 of 10 map workers fails, the reduce should still produce useful output from the other 9.
+- **Scaling** — Add more workers linearly. Bottleneck is the reduce step, not the map step.
+
+#### Handoff Protocol Design
+
+Every agent-to-agent handoff must include a structured message:
+
+```json
+{
+  "task_id": "unique-identifier",
+  "from_agent": "agent-name",
+  "to_agent": "agent-name",
+  "task": "clear description of what to do",
+  "context": "relevant background (minimal, not full history)",
+  "constraints": ["must not modify X", "timeout 30s"],
+  "acceptance_criteria": ["output matches schema Y", "all tests pass"],
+  "artifacts": ["file paths or data references"]
+}
+```
+
+- **Minimal context** — Send only what the receiving agent needs. Full history causes confusion and wastes tokens.
+- **Explicit acceptance criteria** — The receiving agent must know when it has succeeded.
+- **Typed artifacts** — Reference files or data by path/ID, not by embedding content in the message.
+
+#### Failure Propagation Strategies
+
+| Strategy | Behavior | Use When |
+|----------|----------|----------|
+| Fail-fast | Abort immediately, surface error | Critical path, no recovery possible |
+| Retry | Repeat N times with backoff | Transient failures (network, rate limits) |
+| Escalate | Notify supervisor, request human input | Ambiguous failures, policy decisions |
+| Degrade | Continue with partial results, flag gaps | Non-critical subtasks, best-effort acceptable |
+| Circuit-break | Stop retrying after N failures, return cached/default | Dependency is unreliable |
+
+#### State Management
+
+- **Shared state** — All agents read/write a common store (database, shared memory). Simpler but requires conflict resolution (optimistic locking, CRDTs).
+- **Isolated state** — Agents maintain private state, communicate only via messages. Safer but requires explicit state transfer in handoffs.
+- **Hybrid** — Shared read-only state (project context, configuration) + isolated write state (each agent's working memory). Best balance for most systems.
+
+#### Decision Matrix: When to Use Which Pattern
+
+| Scenario | Pattern |
+|----------|---------|
+| Task decomposes into independent subtasks | MapReduce or Supervisor/Worker |
+| Tasks must execute in order | Pipeline |
+| High-stakes decision needs scrutiny | Debate or Consensus |
+| One coordinator manages many executors | Supervisor/Worker |
+| System must tolerate partial failures | MapReduce with degraded reduce |
+| Speed is critical, tasks are independent | MapReduce with max parallelism |
+
+### After
+
+1. **Validate handoff contracts** — Test that each agent produces output matching the next agent's expected input schema.
+2. **Test failure modes** — Simulate each failure propagation path. Verify the system degrades gracefully, not catastrophically.
+3. **Measure overhead** — Coordination cost should be <20% of total execution time. If higher, simplify the topology.
+4. **Document topology** — Create a diagram showing agent relationships, handoff directions, and failure paths.
+
+## Self-check before task completion
+
+- [ ] Pattern choice is justified by task structure (not over-engineered)
+- [ ] Each agent has clear, non-overlapping responsibilities
+- [ ] Handoff protocol includes task, context, constraints, and acceptance criteria
+- [ ] Failure propagation strategy is defined for every inter-agent connection
+- [ ] State management approach is explicit (shared vs isolated vs hybrid)
+- [ ] Coordination overhead is measured and acceptable (<20% of total time)
+- [ ] All agent-to-agent contracts are typed and validated
+- [ ] System degrades gracefully under partial failure conditions

package/.mindforge/skills/agent-tool-selection/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: agent-tool-selection
+version: 1.0.0
+min_mindforge_version: 10.0.4
+status: stable
+triggers: agent tool selection, capability matching, tool routing, cost-aware tool choice, tool fallback chain, tool composition strategy, function selection, tool description optimization, tool disambiguation, tool preference, tool capability matrix, tool ranking
+compose: tool-design
+---
+
+# Skill — Agent Tool Selection (Intelligent Capability Routing)
+
+## When this skill activates
+When designing tool selection logic for AI agents, optimizing tool descriptions,
+building fallback chains, or analyzing tool usage patterns. Use for any scenario
+where an agent must choose between multiple tools to accomplish a task.
+
+Core principle: **Specificity over generality** — when two tools can both handle a
+task, prefer the more specific one. It will be faster, cheaper, and more reliable.
+A hammer works for screws, but a screwdriver is better.
+
+## Mandatory actions when this skill is active
+
+### Tool Selection Algorithm
+
+1. **Selection pipeline (in order):**
+   ```
+   Input: task description + available tools
+
+   Step 1 — Capability Match:
+   - For each tool: does its capability set cover the task requirements?
+   - Eliminate tools that CANNOT handle the task (hard filter)
+
+   Step 2 — Rank by Specificity:
+   - More specific tool > more general tool
+   - Example: "Read file" > "Bash (cat)" for reading files
+   - Specificity = how narrow is the tool's intended use case?
+
+   Step 3 — Rank by Cost-Efficiency:
+   - Among equally capable tools: prefer cheaper/faster
+   - Read (free, instant) > Bash cat (process spawn) > API call (network)
+
+   Step 4 — Rank by Reliability:
+   - Among equal cost: prefer higher success rate
+   - Check historical success rate per tool per task type
+
+   Step 5 — Verify Preconditions:
+   - Does the selected tool's preconditions hold?
+   - Example: Edit requires file was previously Read
+   - If preconditions not met: add prerequisite steps
+
+   Output: ordered list of tools to try (primary + fallbacks)
+   ```
+
+2. **Decision matrix template:**
+   ```
+   | Task Type          | Primary Tool | Fallback 1   | Fallback 2  | Anti-pattern     |
+   |--------------------|--------------|--------------|-----------  |------------------|
+   | Read file content  | Read         | Bash (cat)   | —           | Grep (wrong use) |
+   | Search for pattern | Grep         | Bash (grep)  | Read + scan | Read all files   |
+   | Edit existing file | Edit         | Write        | —           | Bash (sed)       |
+   | Create new file    | Write        | Bash (echo>) | —           | Edit (no file)   |
+   | Run tests          | Bash         | —            | —           | Read test output |
+   | Check file exists  | Bash (ls)    | Read (error) | —           | Grep for path    |
+   ```
+
+### Tool Description Optimization
+
+3. **Writing effective tool descriptions (they ARE prompts):**
+   ```
+   Good description (specific, with examples):
+   "Read a file from disk. Use when you need to see file contents.
+    Supports text, images, PDFs. Prefer over Bash cat/head/tail.
+    NOT for directories (use Bash ls)."
+
+   Bad description (vague):
+   "Reads things from the filesystem."
+
+   Good description (with when-to-use and when-NOT-to-use):
+   "Edit an existing file by replacing exact string matches.
+    Use when: modifying 1-5 specific locations in a file.
+    Do NOT use when: rewriting >50% of the file (use Write instead).
+    Requires: file must have been Read in this session first."
+
+   Bad description (missing boundaries):
+   "Edits files."
+   ```
+
+   Rules:
+   - Include WHEN to use (positive examples)
+   - Include when NOT to use (negative examples — prevents misuse)
+   - State preconditions explicitly
+   - Keep descriptions under 100 words (concise > comprehensive)
+   - Use concrete examples, not abstract capabilities
+
+### Cost-Aware Selection
+
+4. **Cost hierarchy (prefer cheaper when quality is equal):**
+   ```
+   Tier 1 — Free/Instant (prefer these):
+   - Read (file content)
+   - Edit (modify file)
+   - Write (create file)
+   - Grep (pattern search in known scope)
+
+   Tier 2 — Cheap/Fast (use when Tier 1 can't):
+   - Bash (shell commands — process spawn overhead)
+   - Glob (file path patterns)
+
+   Tier 3 — Moderate (use when necessary):
+   - LSP (language server queries)
+   - Web fetch (network requests)
+
+   Tier 4 — Expensive (use sparingly):
+   - Sub-agent spawn (full agent instantiation)
+   - Multi-file analysis (token-heavy)
+   - External API calls (rate-limited, costly)
+   ```
+
+   Rules:
+   - Always check if a Tier 1 tool can handle the task before reaching for Tier 3-4
+   - Track cumulative cost during a session (don't let tool costs compound silently)
+   - For repeated operations: batch when possible (one Bash with && vs many Bash calls)
+   - Cost includes: token consumption, time, API calls, compute resources
+
+### Fallback Chains
+
+5. **Designing robust fallback sequences:**
+   ```
+   Fallback chain structure:
+   1. Try primary tool (most specific, cheapest)
+   2. If fails (error, timeout, precondition unmet):
+      - Log failure reason
+      - Try fallback 1 (broader capability)
+   3. If fallback 1 fails:
+      - Try fallback 2 (most general/expensive)
+   4. If all fail:
+      - Escalate to user with: what was tried, why each failed, what's needed
+
+   Example:
+   Task: "Find where function X is defined"
+   1. Grep (fast, pattern-based) → found? done
+   2. LSP (semantic, language-aware) → found? done
+   3. Bash find + grep (brute force) → found? done
+   4. Escalate: "I couldn't locate function X. Can you point me to the file?"
+   ```
+
+   Rules:
+   - Fallback chains should be pre-defined per task type (not improvised)
+   - Each fallback should be DIFFERENT in approach (not just retry)
+   - Log which level of the chain succeeded (optimize primary over time)
+   - Max 3 fallback levels before escalation (avoid infinite retry loops)
+
+### Tool Composition
+
+6. **Combining tools for complex tasks:**
+   ```
+   Composition patterns:
+
+   Sequential: Tool A output → Tool B input
+   Example: Grep (find file) → Read (get content) → Edit (modify)
+
+   Parallel: Tool A + Tool B independently → merge results
+   Example: Grep (find usages) + Read (get definition) → understand full context
+
+   Conditional: If Tool A succeeds → Tool B, else → Tool C
+   Example: If Read(file) succeeds → Edit, else → Write (file doesn't exist)
+
+   Iterative: Repeat Tool A until condition met
+   Example: Bash(test) → fails → Edit(fix) → Bash(test) → passes → done
+   ```
+
+   Rules:
+   - Plan composition BEFORE executing (don't improvise mid-chain)
+   - Minimize total tool calls (combine steps where possible)
+   - Never call the same tool twice with identical inputs (cache/reuse results)
+   - If composition exceeds 5 sequential steps: consider if there's a more direct tool
+
+### Tool Disambiguation
+
+7. **When multiple tools seem equally valid:**
+   ```
+   Disambiguation criteria (in priority order):
+   1. Fewer side effects: Read-only > Read-write (prefer observation over action)
+   2. More specific: Narrow tool > broad tool (Edit > Bash sed)
+   3. Cheaper: Less resource consumption > more
+   4. More reversible: Undoable > permanent (Edit > Write for existing files)
+   5. Better error messages: Tools with clear failure modes > opaque failures
+
+   If still tied after all criteria: pick the one that appears first in the
+   tool list (convention-based tie-breaking, prevents analysis paralysis)
+   ```
+
+## Self-check before task completion
+
+Before marking a task done when this skill was active:
+
+- [ ] Did I follow the selection pipeline (capability → specificity → cost → reliability)?
+- [ ] Are tool descriptions specific, with positive AND negative usage examples?
+- [ ] Is cost hierarchy respected (cheaper tools preferred when quality is equal)?
+- [ ] Are fallback chains defined for each critical task type (max 3 levels)?
+- [ ] Is tool composition planned before execution (not improvised)?
+- [ ] Are disambiguations resolved by: side effects → specificity → cost → reversibility?
+- [ ] Are tool calls minimized (no redundant calls, batched where possible)?
+- [ ] Is escalation to user defined as the final fallback (not infinite retry)?