mindforge-cc 10.0.2 → 10.7.0

package/.mindforge/skills/autonomous-agent-harness/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: autonomous-agent-harness
+version: 1.0.0
+min_mindforge_version: 10.0.6
+status: stable
+triggers: autonomous harness, persistent agent, background agent, scheduled execution, agent cron, task queue agent, self-monitoring agent, persistent memory agent, long-running agent, agent daemon, agent lifecycle, always-on agent
+---
+
+# Skill — Autonomous Agent Harness
+
+## When this skill activates
+
+When designing, implementing, or operating agents that persist beyond single
+conversation sessions. Use when building infrastructure for agents that run on
+schedules, maintain state across invocations, process task queues, self-monitor
+their health, or operate as background daemons.
+
+This skill covers the architecture layer between "single-shot agent conversation"
+and "production autonomous system" — the harness that manages lifecycle, memory,
+scheduling, and self-regulation.
+
+## Mandatory actions when this skill is active
+
+### Before designing the harness
+
+1. **Define the autonomy level:**
+
+   | Level | Description | Human oversight | Example |
+   |-------|-------------|-----------------|---------|
+   | L1 — Scheduled | Runs on cron, reports results | Review output post-run | Daily code review bot |
+   | L2 — Reactive | Triggers on events, acts within bounds | Alert on anomaly | PR auto-labeler |
+   | L3 — Proactive | Identifies tasks, proposes actions | Approve before execute | Dependency updater |
+   | L4 — Autonomous | Full loop with self-correction | Exception-only review | Incident responder |
+
+2. **Identify persistence requirements:**
+   - What state must survive between sessions? (task history, learned patterns, config)
+   - What is the acceptable data loss window? (none, last hour, last day)
+   - What is the memory format? (markdown files, SQLite, MCP server, JSON)
+   - How large will accumulated state grow over time?
+
+3. **Define boundaries and kill switches:**
+   - Maximum actions per invocation (prevent runaway loops)
+   - Maximum cost per session (token budget ceiling)
+   - Forbidden actions list (no force-push, no production deploys without approval)
+   - Human escalation triggers (confidence < threshold, high-impact decisions)
+   - Emergency stop mechanism (file-based kill switch, API endpoint)
+
+### During harness implementation
+
+**Core architecture components:**
+
+```
++------------------+     +------------------+     +------------------+
+|   Scheduler      |---->|   Task Queue     |---->|   Agent Core     |
+|  (cron/events)   |     |  (FIFO+priority) |     |  (LLM session)   |
++------------------+     +------------------+     +------------------+
+                                                         |
+                         +------------------+            |
+                         |  Self-Monitor    |<-----------+
+                         |  (health/budget) |            |
+                         +------------------+            v
+                                                  +------------------+
+                         +------------------+     |  Persistent      |
+                         |  Kill Switch     |     |  Memory          |
+                         |  (emergency stop)|     |  (MCP/markdown)  |
+                         +------------------+     +------------------+
+```
+
+**1. Persistent Memory System:**
+```
+.agent-harness/
+  memory/
+    knowledge-base.md      # Accumulated learnings and patterns
+    task-history.jsonl     # Every task executed with outcome
+    config.json            # Runtime configuration
+    state.json             # Current operational state
+  queues/
+    pending.jsonl          # Tasks awaiting execution
+    in-progress.jsonl      # Currently executing tasks
+    completed.jsonl        # Finished tasks (rotate after 30 days)
+    dead-letter.jsonl      # Failed tasks after max retries
+```
+
+- Knowledge base uses markdown for human-readable, agent-writable state
+- Task history is append-only JSONL for auditability
+- State file tracks: last run time, current task, health metrics, budget remaining
+- Integration with MindForge memory: read from `.mindforge/memory/`, write learnings back
+
+**2. Scheduled Execution:**
+```json
+{
+  "schedules": [
+    {
+      "name": "daily-review",
+      "cron": "0 9 * * 1-5",
+      "task": "review-open-prs",
+      "timeout_minutes": 30,
+      "max_retries": 2
+    },
+    {
+      "name": "continuous-monitor",
+      "interval_minutes": 15,
+      "task": "check-deployments",
+      "timeout_minutes": 5,
+      "max_retries": 1
+    }
+  ]
+}
+```
+
+- Cron expressions for periodic tasks
+- Interval-based polling for monitoring
+- Event-triggered execution (webhook, file watcher, git hook)
+- Each schedule entry defines timeout and retry policy independently
+
+**3. Task Queue:**
+```json
+{
+  "id": "task-uuid",
+  "created_at": "ISO-8601",
+  "priority": 1,
+  "type": "review-pr",
+  "payload": { "pr_number": 42, "repo": "org/project" },
+  "status": "pending",
+  "attempts": 0,
+  "max_attempts": 3,
+  "timeout_seconds": 1800,
+  "dead_letter_after": 3
+}
+```
+
+- FIFO within same priority level; higher priority preempts
+- Retry with exponential backoff: 1min, 5min, 25min
+- Dead letter queue for tasks that exceed max attempts
+- Idempotency keys prevent duplicate execution
+
+**4. Self-Monitoring:**
+```json
+{
+  "health": {
+    "last_heartbeat": "ISO-8601",
+    "consecutive_failures": 0,
+    "token_budget_remaining": 45000,
+    "token_budget_period": "daily",
+    "drift_score": 0.12,
+    "uptime_minutes": 1440
+  },
+  "alerts": [
+    {
+      "condition": "consecutive_failures > 3",
+      "action": "pause_and_notify"
+    },
+    {
+      "condition": "token_budget_remaining < 5000",
+      "action": "enter_low_power_mode"
+    },
+    {
+      "condition": "drift_score > 0.5",
+      "action": "request_human_review"
+    }
+  ]
+}
+```
+
+- Heartbeat every execution cycle (detect stalls)
+- Token budget tracking with low-power mode (reduce scope, not stop)
+- Drift detection: compare recent outputs to baseline patterns
+- Alert escalation: log → notify → pause → kill
+
+**5. Lifecycle Management:**
+
+```
+STARTUP → RUNNING → IDLE → WAKE → RUNNING → ... → SHUTDOWN
+   |         |                                         ^
+   |         +------- ERROR -----> RECOVERING ---------+
+   |                                    |
+   +--- BLOCKED (kill switch) ----------+
+```
+
+- **Startup:** Load config, validate memory integrity, check kill switch, announce ready
+- **Running:** Process task queue, update heartbeat, track budget
+- **Idle:** No pending tasks, reduce polling frequency, maintain heartbeat
+- **Wake:** New task arrived or schedule triggered, resume full operation
+- **Recovering:** After error, attempt self-repair, reload state, retry last task
+- **Shutdown:** Graceful — complete current task, flush state, log final report
+- **Blocked:** Kill switch active — cease all operations, preserve state, await unblock
+
+### After harness deployment
+
+1. **Operational verification:**
+   - Run a canary task through the full pipeline (schedule → queue → execute → report)
+   - Verify memory persistence across restarts
+   - Test kill switch responsiveness (must halt within 1 execution cycle)
+   - Confirm dead letter queue captures failed tasks correctly
+   - Validate budget tracking accuracy
+
+2. **Monitoring setup:**
+   - Dashboard showing: queue depth, success rate, token spend, last heartbeat
+   - Alerts for: stall (no heartbeat in 2x interval), budget exhaustion, error spike
+   - Weekly summary: tasks completed, failures, cost, learnings accumulated
+
+3. **Maintenance cadence:**
+   - Daily: review dead letter queue, check for stale tasks
+   - Weekly: rotate completed task log, prune knowledge base, verify budget projections
+   - Monthly: review drift trends, update boundaries, assess autonomy level appropriateness
+
+## Self-check before task completion
+
+Before marking an autonomous harness task done:
+
+- [ ] Did I define the autonomy level and appropriate human oversight?
+- [ ] Did I implement all 5 core components (memory, scheduler, queue, monitor, lifecycle)?
+- [ ] Did I define explicit boundaries (max actions, budget ceiling, forbidden actions)?
+- [ ] Did I implement a kill switch that halts within one execution cycle?
+- [ ] Did I set up retry logic with dead letter queue for failed tasks?
+- [ ] Did I configure self-monitoring with escalating alert thresholds?
+- [ ] Did I test the full lifecycle (startup through shutdown)?
+- [ ] Did I integrate with MindForge's existing memory and autonomous engine?

package/.mindforge/skills/autonomous-agents/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: autonomous-agents
+version: 1.0.0
+min_mindforge_version: 10.5.0
+status: stable
+triggers: autonomous agent design, agent loop architecture, tool use orchestration, AI planning system, agent self-correction, agentic workflow, agent reasoning loop, multi-agent collaboration, agent task decomposition, agent goal pursuit, agent reflection pattern, autonomous decision making
+compose:
+  - agent-orchestration-patterns
+---
+
+# Autonomous Agents & Reasoning Loops
+
+## When this skill activates
+
+This skill activates when building autonomous agents that pursue goals independently, implement planning and reasoning loops, use tools dynamically, self-correct errors, or coordinate across multiple agents. It applies to systems where AI must operate with minimal human intervention across multi-step tasks.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. **Define agent scope and boundaries** — Specify what the agent can do (available tools, permitted actions) and cannot do (restricted tools, human approval required). Define goal structure: explicit goals (user-provided task), implicit goals (system constraints, safety rules), and emergent goals (agent-discovered subgoals). Unbounded agents are dangerous.
+2. **Design the reasoning loop** — Choose loop architecture: ReAct (Reasoning + Acting), Plan-Act-Reflect, or Chain-of-Thought with Tool Use. Define loop termination conditions: goal achieved, max iterations reached (prevent infinite loops), error threshold exceeded, or human intervention requested. Document loop explicitly.
+3. **Select tool inventory** — Identify tools the agent can use: APIs (web search, database queries), code execution (sandboxed interpreters), file operations (read/write), external services (send email, create tickets). For each tool, define input schema, output schema, error modes, and safety constraints (rate limits, authorization).
+4. **Establish self-correction mechanisms** — Agents make mistakes (hallucinations, tool errors, reasoning failures). Design self-correction: validation (check outputs against constraints), reflection (analyze failures and adjust strategy), and retry logic (re-attempt with modified approach). Define max retry count to prevent infinite loops.
+
+### During implementation
+
+- **Implement explicit planning phase** — Before acting, the agent should decompose the goal into subtasks (task decomposition), estimate feasibility, and select tools. Plan structure: {goal, subtasks: [{action, tool, expected_outcome}], constraints, success_criteria}. Plans must be inspectable and modifiable by humans.
+- **Design tool calling with error handling** — Wrap every tool call in try-catch with explicit error handling: retry on transient errors (network failures, rate limits), escalate on permanent errors (invalid credentials, malformed inputs), and degrade gracefully (skip optional steps, use fallback tools). Log all tool calls with inputs, outputs, and errors.
+- **Build reflection and self-critique loops** — After each action or subtask completion, the agent should reflect: "Did this action achieve the expected outcome? If not, why? What should I try next?" Use structured reflection prompts: {action_taken, expected_outcome, actual_outcome, error_analysis, next_action}. Reflection improves multi-step task success rates by 20-40%.
+- **Implement goal-state tracking** — Maintain explicit state: current goal, progress toward goal (% complete, subtasks finished), blockers (errors, missing information), and next planned action. State must be serializable and resumable (agent can pause and resume later). Use structured state representations (JSON, database records).
+- **Design safety constraints** — Prevent harmful actions via pre-execution checks: validate tool inputs against safety rules (no file deletion without confirmation, no email to external addresses without review), enforce rate limits (max N API calls per minute), and require human approval for high-risk actions (financial transactions, data deletion).
+- **Implement multi-agent coordination** — When multiple agents collaborate, define communication protocols: message passing (agents send structured messages), shared state (agents read/write common store), or supervisor coordination (central agent dispatches tasks). Avoid race conditions and deadlocks: use locks, optimistic concurrency, or single-writer patterns.
+
+### After implementation
+
+- **Validate goal completion accuracy** — Test the agent on a suite of goals with known correct solutions. Measure success rate (% of goals fully achieved), partial success rate (% of goals partially achieved), and failure modes (why did the agent fail?). Target: >80% success rate for well-defined goals.
+- **Measure loop efficiency** — Track iterations per goal (how many reasoning steps until completion). More iterations = higher cost and latency. Target: <10 iterations for most tasks. If higher, improve planning quality or provide better tools.
+- **Test self-correction effectiveness** — Simulate tool errors (API returns invalid data, file not found, timeout) and validate that the agent recovers gracefully. Measure recovery rate (% of errors successfully handled without human intervention). Target: >70% recovery rate.
+- **Audit for infinite loops and runaway costs** — Test with adversarial goals designed to trigger infinite loops (unsolvable tasks, circular dependencies). Validate that termination conditions activate (max iterations, timeout, error threshold). Monitor token usage and cost per goal in production.
+
+## Self-check before task completion
+
+- [ ] Agent scope is defined with explicit permitted and restricted tools
+- [ ] Goal structure includes explicit (user-provided), implicit (system constraints), and emergent goals
+- [ ] Reasoning loop architecture (ReAct/Plan-Act-Reflect/CoT+Tools) is selected and documented
+- [ ] Loop termination conditions prevent infinite loops (max iterations, timeout, error threshold)
+- [ ] Tool inventory is documented with input/output schemas and error modes per tool
+- [ ] Self-correction mechanisms include validation, reflection, and retry logic with max retry limits
+- [ ] Planning phase decomposes goals into subtasks with feasibility estimates
+- [ ] Tool calls are wrapped with error handling (retry transient, escalate permanent, degrade gracefully)
+- [ ] Reflection loops analyze action outcomes and adjust strategy ({action, expected, actual, error_analysis, next})
+- [ ] Goal-state tracking maintains serializable, resumable state (progress, blockers, next action)
+- [ ] Safety constraints validate tool inputs pre-execution and enforce rate limits
+- [ ] Multi-agent coordination uses message passing, shared state, or supervisor patterns without race conditions
+- [ ] Goal completion accuracy is validated at >80% success rate on test suite
+- [ ] Loop efficiency is measured (target <10 iterations per task)
+- [ ] Self-correction effectiveness is tested with simulated tool errors (target >70% recovery rate)
+- [ ] Infinite loop prevention is validated with adversarial goals and termination condition testing

package/.mindforge/skills/autonomous-loops/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: autonomous-loops
+version: 1.0.0
+min_mindforge_version: 10.0.3
+status: stable
+triggers: autonomous mode, headless, unattended, pipeline pattern, DAG execution, RFC-driven, infinite loop, agentic loop, auto mode, background execution
+compose:
+  - agent-loops
+---
+
+# Skill — Autonomous Loops
+
+## When this skill activates
+When designing or executing autonomous agent workflows that run without
+human intervention across multiple tasks. Covers pattern selection, safety
+rails, and state management for headless operation.
+
+## Mandatory actions when this skill is active
+
+### Before starting autonomous execution
+1. Define the **exit conditions** — when does the loop STOP?
+2. Define the **escalation path** — what triggers a human interrupt?
+3. Checkpoint the current state — autonomous mode must be resumable
+4. Verify SHARED_TASK_NOTES.md exists and is readable
+
+### Loop Pattern Selection
+
+**Pattern 1 — Sequential Pipeline**
+```
+Plan → Task 1 → Verify → Task 2 → Verify → ... → Ship
+```
+- Use when: tasks have strict ordering, output of one feeds next
+- Safety: verify after EACH task, halt pipeline on failure
+- State: HANDOFF.json tracks position in pipeline
+
+**Pattern 2 — Parallel Wave Execution**
+```
+Wave 1: [Task A, Task B, Task C] → all verify → Wave 2: [Task D, Task E] → ...
+```
+- Use when: multiple independent tasks can run simultaneously
+- Safety: all tasks in a wave must pass before next wave starts
+- State: wave-executor.md manages group completion
+
+**Pattern 3 — RFC-Driven DAG**
+```
+Spec → Decompose into dependency graph → Execute respecting dependencies
+         ↓
+   [A] → [B, C] → [D depends on B+C] → [E depends on D]
+```
+- Use when: complex feature with interdependent work units
+- Safety: each node independently verifiable, DAG prevents circular deps
+- State: DAG stored in HANDOFF.json with per-node status
+
+**Pattern 4 — Infinite Agentic Loop (with stuck detection)**
+```
+while (work_exists):
+    pick_next_task()
+    execute()
+    verify()
+    if stuck_for(3_iterations): escalate()
+```
+- Use when: continuous improvement, ongoing maintenance
+- Safety: stuck-detector.md monitors for non-progress
+- CRITICAL: must have hard time limit OR task count limit
+
+### Safety Rails (ALL patterns)
+
+1. **Hard limits** — Set before starting, never removed during execution:
+   - Max iterations: configurable (default 20 tasks)
+   - Max duration: configurable (default 2 hours)
+   - Max cost: from config.json `[COST_HARD_LIMIT_USD]`
+
+2. **Stuck detection** — If 3 consecutive iterations produce no meaningful progress:
+   - Write diagnostic to SHARED_TASK_NOTES.md
+   - Attempt self-repair (different approach) ONCE
+   - If self-repair fails: HALT and escalate to user
+
+3. **Checkpoint protocol**:
+   - Write state to HANDOFF.json after EVERY task completion
+   - Write reasoning to SHARED_TASK_NOTES.md for cross-iteration context
+   - On interruption: state is always resumable from last checkpoint
+
+4. **Escalation triggers** (always halt for human):
+   - Security-sensitive changes detected (auth/payment/PII)
+   - Merge conflict requiring judgment
+   - Test failures that resist 2 fix attempts
+   - Any change scoring difficulty > 8
+
+### During autonomous execution
+- Fresh context per task (no context accumulation)
+- Load HANDOFF.json + SHARED_TASK_NOTES.md at each task start
+- Run verification-loop (minimum Phase 4+5+6) after each task
+- Log every task completion/failure in AUDIT
+
+### After autonomous execution completes
+- Produce execution summary (tasks completed, failed, time, cost)
+- Archive SHARED_TASK_NOTES.md to `.planning/history/`
+- Run full verification-loop (all 6 phases) on combined changes
+- Report results to user for review before any merge/push
+
+## Self-check before task completion
+- [ ] Did I define exit conditions BEFORE starting the loop?
+- [ ] Did I verify stuck detection fires after 3 iterations of no progress?
+- [ ] Did I confirm SHARED_TASK_NOTES.md is being written after each task?
+- [ ] Did I run verification-loop on the combined changes before reporting complete?

package/.mindforge/skills/build-system-optimization/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: build-system-optimization
+version: 1.0.0
+min_mindforge_version: 10.7.0
+status: stable
+triggers: build system optimization, build cache architecture, incremental build design, remote build execution, dependency graph optimization, build farm design, Bazel Buck optimization, build time reduction, distributed build, build artifact caching, hermetic build, build reproducibility
+---
+
+# Skill — Build System Optimization
+
+## When this skill activates
+
+This skill activates when the user is optimizing build systems for speed and reliability. This includes build cache architecture, incremental builds, remote build execution, dependency graph optimization, build farm design, Bazel/Buck/Gradle optimization, build time reduction, distributed builds, artifact caching, hermetic builds, and build reproducibility.
+
+## Mandatory actions when this skill is active
+
+### Before writing any code
+
+1. Establish baseline build times: clean build (no cache), incremental build (single file change), and CI build. Measure p50, p95, p99.
+2. Profile the build to identify bottlenecks: dependency resolution, compilation, linking, testing, packaging. Use build system profiling tools (Gradle Build Scan, Bazel analyze-profile).
+3. Audit dependency graph: identify unnecessary dependencies, circular dependencies, and overly-coupled modules.
+4. Assess cache hit rates: local cache, remote cache, CI cache. Identify cache invalidation causes (non-deterministic inputs, timestamp dependencies).
+5. Determine build reproducibility: same source + same toolchain = identical binary. Test by building twice and comparing checksums.
+
+### During implementation
+
+- **Incremental Builds:** Only rebuild changed modules and their dependents. Requires accurate dependency tracking. Bazel and Buck are incremental by design. Gradle requires careful task input/output declaration. Target: single-file change rebuild in under 30 seconds.
+- **Build Caching:** Layer caching at multiple levels: local (developer machine), shared (team), remote (CI). Use content-addressable storage (hash inputs to determine cache key). Cache should serve 80%+ of CI builds from cache.
+- **Remote Build Execution:** Offload compilation and tests to remote workers (Bazel Remote Execution, BuildBuddy, Gradle Enterprise). Provides massive parallelism (100+ workers). Requires hermetic builds.
+- **Dependency Graph Optimization:** Reduce fan-out (modules with many dependents). Split large modules into smaller ones. Use interface modules to break circular dependencies. Visualize graph with Bazel query or Gradle's dependency graph plugin.
+- **Hermetic Builds:** All inputs (source, toolchain, dependencies) must be explicit. No reliance on global state (env vars, system tools, internet access during build). Hermetic builds enable reproducibility and remote caching.
+- **Build Artifact Caching:** Cache compiled binaries, test results, and packaged artifacts. Use content-addressable storage (Artifactory, Nexus, S3). Artifacts should be immutable (never overwrite).
+- **Parallelization:** Build independent modules in parallel. Bazel parallelizes by default. Gradle requires `org.gradle.parallel=true`. Monitor CPU utilization (target: 80%+ during build).
+- **Build Farm Design:** Centralized build cluster with auto-scaling workers. Use spot instances for cost savings. Workers should be stateless and ephemeral. Monitor queue depth and scale workers accordingly.
+- **Build Time Reduction Targets:** Clean build under 10 minutes. Incremental build under 1 minute. CI build (with cache) under 5 minutes.
+
+### After implementation
+
+- Verify incremental builds only rebuild changed modules and dependents (use build system logs to confirm).
+- Confirm cache hit rates exceed 80% in CI and 90% for developers (for incremental builds).
+- Validate remote build execution distributes work across workers (monitor parallelism and CPU utilization).
+- Ensure builds are hermetic by building in a clean container and comparing output checksums.
+- Check that build artifact cache is content-addressable and serves artifacts in under 2 seconds.
+
+## Self-check before task completion
+
+- [ ] Baseline build times are measured (clean, incremental, CI) and tracked over time.
+- [ ] Incremental builds only rebuild changed modules (verified via build logs).
+- [ ] Build caching achieves 80%+ cache hit rate in CI.
+- [ ] Remote build execution distributes work across workers with 80%+ CPU utilization.
+- [ ] Dependency graph is optimized (reduced fan-out, no circular dependencies).
+- [ ] Builds are hermetic (no reliance on global state or internet access).
+- [ ] Build artifacts are cached in content-addressable storage and immutable.
+- [ ] Build time targets are met: clean <10min, incremental <1min, CI <5min.

package/.mindforge/skills/build-vs-buy/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: build-vs-buy
+version: 1.0.0
+min_mindforge_version: 10.1.0
+status: stable
+triggers: build vs buy, make or buy, vendor evaluation, total cost ownership, buy decision, vendor lock-in assessment, outsource vs build, third-party evaluation, SaaS vs self-hosted, dependency vs custom, commercial vs open-source, build internally
+---
+
+# Build vs Buy Decision Framework
+
+## When this skill activates
+
+This skill activates when the team faces a decision about whether to build a capability
+internally or acquire it from an external vendor, open-source project, or SaaS provider.
+It provides a structured framework for evaluating total cost of ownership, strategic
+alignment, and long-term maintainability of both paths.
+
+## Mandatory actions when this skill is active
+
+### Before
+
+1. **Identify the capability boundary** — Define exactly what the system needs to do.
+   Separate the core problem from adjacent concerns.
+2. **Gather constraints** — Timeline pressure, team capacity, budget ceiling, compliance
+   requirements, and existing technology stack compatibility.
+3. **Catalog candidates** — List all viable buy options (commercial SaaS, open-source
+   libraries, managed services) alongside the build option.
+
+### During
+
+4. **Calculate Total Cost of Ownership (TCO) for BUY path:**
+   - License/subscription fees (year 1 + projected 3-year)
+   - Integration effort (API adapters, data transformation, auth hookup)
+   - Ongoing maintenance (version upgrades, breaking changes, support tickets)
+   - Opportunity cost of vendor limitations (features you cannot customize)
+   - Exit cost (data migration, API decoupling, replacement timeline)
+
+5. **Calculate Total Cost of Ownership (TCO) for BUILD path:**
+   - Initial development effort (design + implementation + testing)
+   - Ongoing maintenance (bug fixes, feature requests, security patches)
+   - Ownership benefit (full control, no per-seat pricing, no vendor roadmap dependency)
+   - Knowledge investment (team learns the domain deeply)
+
+6. **Assess vendor lock-in risk:**
+   - Data portability — Can you export all data in standard formats?
+   - API coupling — How deeply does the vendor API penetrate your codebase?
+   - Exit cost — What is the realistic effort to replace this vendor?
+   - Contractual traps — Auto-renewal, price escalation clauses, minimum commitments.
+
+7. **Apply the decision matrix:**
+   - Strategic importance HIGH + Competitive advantage = **BUILD**
+   - Strategic importance LOW + Commodity capability = **BUY**
+   - Timeline pressure HIGH + Team capacity LOW = **BUY** (short-term), plan migration
+   - Timeline pressure LOW + Team capacity HIGH = **BUILD**
+   - Differentiating capability = **BUILD** (never outsource your moat)
+   - Undifferentiated heavy lifting = **BUY**
+
+8. **Evaluate team capacity:**
+   - Does the team have domain expertise to build and maintain this?
+   - Will building this distract from higher-priority work?
+   - Is there a realistic staffing plan for long-term ownership?
+
+### After
+
+9. **Document the decision** — Record the rationale, TCO comparison, and risk assessment
+   as an Architecture Decision Record (ADR).
+10. **Define review triggers** — Set conditions that would cause re-evaluation (e.g.,
+    vendor price increase >30%, team growth enabling build, vendor acquisition).
+11. **Plan the exit path** — Even when buying, design integration layers that allow
+    future replacement without full rewrite.
+
+## Self-check before task completion
+
+- [ ] TCO calculated for both paths with 3-year projection
+- [ ] Vendor lock-in risk explicitly assessed with exit cost estimate
+- [ ] Decision matrix applied with clear justification
+- [ ] Team capacity and opportunity cost considered
+- [ ] ADR written with rationale and review triggers
+- [ ] Integration designed with abstraction layer regardless of buy/build choice
+- [ ] Stakeholders informed of trade-offs, not just the recommendation