assimilate

Assimilate Overview Use this skill when the user asks the framework to improve itself, or when EVOLVE identifies a capability gap that should be benchmarked against other codebases. When to Use User request: "improve the framework", "compare to competitor repos", "adopt best ideas" EVOLVE phase where external pattern benchmarking is needed before creating new artifacts Reflection/recommend-evolution output calls for concrete upgrade candidates Iron Laws NEVER implement borrowed ideas directly — always produce a comparable feature map, explicit gap list, and TDD backlog with checkpoints before writing any code; direct copying without analysis creates undetected regressions. ALWAYS create workspace under .claude/context/runtime/assimilate// — never clone repos to arbitrary or project-root locations; contained workspaces enable clean teardown and prevent accidental overwrites. ALWAYS use shallow clones ( --depth=1 ) when possible — full history is unnecessary for feature analysis and wastes disk; only use full clone when commit history is part of the comparison surface. NEVER execute external project scripts during assimilation — no npm install , make , or ./setup.sh from cloned repos; analysis is read-only; untrusted scripts can modify the host environment. ALWAYS score gaps by impact×feasibility before writing the TDD backlog — an unordered backlog wastes implementation effort on low-value items; prioritize by expected benefit divided by complexity. Anti-Patterns Anti-Pattern Why It Fails Correct Approach Implementing external patterns without gap analysis Blind copying introduces incompatible assumptions Always produce feature map and gap list first Cloning repos outside assimilate workspace Leftover files pollute project root, hard to clean Use .claude/context/runtime/assimilate// Running npm install / project scripts from clones Untrusted scripts can modify host environment Read-only analysis only; never execute external scripts Writing TDD backlog items without acceptance criteria Developers can't verify completion objectively Every backlog item needs RED test + measurable GREEN criteria Including gaps without complexity/risk scoring Low-value work gets implemented over high-value gaps Score all gaps: impact, complexity (S/M/L), risk (low/med/high) Four-Phase Execution Default kickoff message: I’ll do this in four phases: clone competitor repos into a temp workspace, extract comparable features/tooling surfaces, build a gap list against our repo, then convert that into a concrete TDD backlog with checkpoints to implement and validate improvements. I’m starting by creating the temp comparison workspace and cloning the repos. Phase 1: Clone + Stage Create workspace under .claude/context/runtime/assimilate// . Clone target repos into externals// using shallow clones where possible. Capture inventory: commit hash default branch top-level structure snapshot Never execute untrusted project scripts during assimilation. Phase 2: Comparable Surface Extraction Extract structured comparisons for each external repo and local repo across these surfaces: Memory model (tiers, retrieval APIs, persistence, indexing) Search stack (lexical, semantic, hybrid, daemon/prewarm, ranking) Agent communication/orchestration (task protocol, hooks, event/state flow) Creator system (templates, validators, CI gates, policy enforcement) Observability/quality (metrics, eval harnesses, state guards) Output one normalized comparison table per surface. Phase 3: Gap List Build a local gap list with: gap_id current state reference pattern (external source + path) expected benefit complexity ( S|M|L ) risk ( low|medium|high ) recommended artifact type ( skill|workflow|hook|schema|tool|agent ) Prioritize by impact and implementation feasibility. Phase 4: TDD Upgrade Backlog Convert prioritized gaps into implementable TDD items: RED: failing test(s) and measurable acceptance criteria GREEN: minimal implementation path REFACTOR: hardening/cleanup VERIFY: integration checks, hook/CI gates, docs updates Each backlog item must include: owner agent target files command-level validation steps rollback/safety notes Output Contract Return markdown with sections in this order:

Repo Set

Comparable Surfaces

Gap List

TDD Backlog

Execution Checkpoints

If comparison repos are missing, return a blocked state with exact clone commands needed. Tooling Notes Prefer pnpm search:code / ripgrep in local repo for precise parity checks. Use research-synthesis when external research context is needed before scoring gaps. Use framework-context before writing system-level recommendations. Use recommend-evolution to record high-priority changes after backlog generation. Memory Protocol (MANDATORY) Before work: cat .claude/context/memory/learnings.md After work: Record assimilated patterns: .claude/context/memory/learnings.md Record adoption risks/tradeoffs: .claude/context/memory/decisions.md Record unresolved blockers: .claude/context/memory/issues.md