@veedubin/neuralgentics 0.13.5 → 0.13.7

package/.opencode/skills/boomerang-handoff/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: boomerang-handoff
+description: End-of-session wrap-up. Runs the self-evolution gate (auto-create), then updates HANDOFF.md + TASKS.md, then commits any new SKILL.md files. Invoke via `//boomerang-handoff`.
+tags:
+  - handoff
+  - session
+  - documentation
+  - evolution
+---
+
+# Boomerang Handoff
+
+## When to Invoke
+
+At the **end of every session**, or when the user explicitly requests `//boomerang-handoff`. This skill wraps up the session, runs the self-evolution gate to auto-create skills from repeated patterns, updates documentation, and commits any new artifacts.
+
+## Preconditions
+
+Before running the handoff, verify:
+
+- [ ] All dispatched cards are in `done` or `blocked` status
+- [ ] All quality gates have passed (lint, typecheck, test)
+- [ ] Working tree is clean or has only documentation changes pending
+- [ ] `AGENTS.md`, `TASKS.md`, and `HANDOFF.md` exist and are readable
+- [ ] You are in a git repository
+
+## Step 1: Run Self-Evolution Gate
+
+Invoke the evolution gate to detect repeated patterns and auto-create skills:
+
+```
+Call MCP tool: neuralgentics_evolution_gate
+Params: { auto_create: true }
+```
+
+The gate will:
+
+1. Query memory for pattern candidates (trigger count >= 3)
+2. Evaluate each candidate against 4 criteria (repetition, interface clarity, independence, time savings)
+3. Auto-create `SKILL.md` files for qualified candidates in `.opencode/skills/<name>/`
+4. Save evolution results to memory
+
+**Expected output:** `{ evaluated: N, qualified: M, created: [...] }`
+
+If the gate creates new skills, note their names for the commit message in Step 3.
+
+## Step 2: Update HANDOFF.md and TASKS.md
+
+Execute the standard handoff flow:
+
+1. **Update `HANDOFF.md`** — Add a new top section with:
+   - Session date and summary
+   - What was completed
+   - Key decisions made
+   - Files changed
+   - Bootstrap prompt for next session
+
+2. **Update `TASKS.md`** — Mark completed cards as `done`, move blocked cards with reasons, archive old cards.
+
+3. **Update `CONTEXT.md`** (if exists) — Add architecture delta section.
+
+4. **Save session context to memory** — Use `memini-ai-dev_add_memory` with:
+   - `sourceType: "boomerang"`
+   - `metadata: { project: "neuralgentics", type: "session-handoff", session: N }`
+
+## Step 3: Commit New SKILL.md Files
+
+If the evolution gate created new `SKILL.md` files, or if documentation was updated:
+
+```bash
+git add .opencode/skills/ HANDOFF.md TASKS.md CONTEXT.md
+git commit -m "handoff: session wrap-up + evolution gate
+
+Created skills: <list of new skill names>
+Updated: HANDOFF.md, TASKS.md"
+```
+
+Do NOT push — the user may want to review before pushing.
+
+## Step 4: Return Handle
+
+Return a summary to the orchestrator:
+
+```
+{
+  session: N,
+  handoff_complete: true,
+  evolution_result: { evaluated, qualified, created },
+  docs_updated: ["HANDOFF.md", "TASKS.md"],
+  new_skills: ["skill-name-1", "skill-name-2"],
+  commit_sha: "<sha>"
+}
+```
+
+## Notes
+
+- The evolution gate runs **before** the handoff documentation update so that newly-created skills are reflected in the handoff summary.
+- If the evolution gate fails, log the error and continue with the handoff — do not block the session wrap-up.
+- The `auto_create: true` parameter ensures skills are created automatically without manual confirmation.
+- Gate failure does NOT block the handoff. The compaction hook also calls the gate independently with the same `autoCreate: true` default.

package/.opencode/skills/boomerang-orchestrator/SKILL.md

@@ -0,0 +1,480 @@
+---
+name: boomerang-orchestrator
+description: Main coordinator for Boomerang Cycle v3 (kanban-native). Extrapolates the user prompt, dispatches the architect for a roadmap, seeds the kanban, dispatches narrow cards to workers (broker permission-gated), and runs a wrap-up audit with skill self-audit and todo-list update.
+---
+
+# Boomerang Orchestrator
+
+## External Skills Fetcher (Step 0)
+
+At session start, if `external_skills.enabled=true` in `~/.neuralgentics/.env`, invoke the `external-skills-fetcher` skill to ensure the curated external skill repos are cloned and up-to-date. This is done BEFORE the SESSION START PROTOCOL so that the new SKILL.md files are visible to AGENTS.md and the rest of the protocol.
+
+## ⚠️ SESSION START PROTOCOL (MANDATORY - DO THIS FIRST)
+
+**CRITICAL**: At the start of EVERY session, you MUST complete ALL of the following steps BEFORE responding to the user:
+
+- [ ] **1. Read `AGENTS.md`** (if exists) — Understand available agents and their roles
+- [ ] **2. Read `TASKS.md`** (if exists) — Understand current task state and priorities
+- [ ] **3. Read `HANDOFF.md`** (if exists) — Understand previous session context and any in-progress work
+- [ ] **4. Read `README.md`** (if exists) — Get project overview and documentation
+
+**RULE: NEVER respond to the user before completing the Session Start Protocol.**
+
+If any of these files don't exist, note it and proceed. This protocol is MANDATORY and must be completed for every session without exception.
+
+---
+
+## Description
+
+Main coordinator for the Boomerang Protocol. Plans task execution, builds dependency graphs, and orchestrates sub-agents.
+
+## The Boomerang Cycle v3 (Kanban-Native)
+
+The orchestrator runs a five-phase cycle on every user turn. Each phase has an explicit output and a skill it may invoke.
+
+```
+   ┌─────────────┐
+   │ USER PROMPT │
+   └──────┬──────┘
+          ▼
+   ┌──────────────────────────────────┐
+   │ 1. INTAKE & EXTRAPOLATION       │  ← YOU (orchestrator)
+   │    Expand the prompt into a      │
+   │    Context Package: requirements,│
+   │    ambiguity, edge cases,        │
+   │    integration points, blocking  │
+   │    questions.                    │
+   └──────┬───────────────────────────┘
+          ▼
+   ┌──────────────────────────────────┐
+   │ 2. ROADMAP                      │  ← boomerang-architect
+   │    Produce a roadmap doc:        │
+   │    phases → tasks, each task     │
+   │    narrow enough for one coder.  │
+   │    Write to docs/roadmap-<proj>  │
+   │    .md.                          │
+   └──────┬───────────────────────────┘
+          ▼
+   ┌──────────────────────────────────┐
+   │ 3. KANBAN SEED                  │  ← kanban-board-manager
+   │    Create one card per task in   │     skill
+   │    TASKS.md with status:         │
+   │    triage/todo/ready/running/    │
+   │    blocked/done/archived. Link   │
+   │    dependencies. Assign profile. │
+   └──────┬───────────────────────────┘
+          ▼
+   ┌──────────────────────────────────┐
+   │ 4. DISPATCH                     │  ← YOU + broker
+   │    For each ready card: build    │
+   │    a Context Package, confirm   │
+   │    the assigned profile has the  │
+   │    tools for the task (broker    │
+   │    AccessControl.CanAccess),     │
+   │    then delegate via Task.      │
+   │    Worker moves card to running  │
+   │    → done with handoff evidence. │
+   └──────┬───────────────────────────┘
+          ▼
+   ┌──────────────────────────────────┐
+   │ 5. WRAP-UP AUDIT                │  ← YOU + self-audit
+   │    Walk the board: triage, todo, │     skill
+   │    running, blocked, done.       │
+   │    Unaccounted work is resolved  │
+   │    (break smaller, re-architect, │
+   │    or requeue to Todo). Run      │
+   │    skill-self-audit: did a       │
+   │    process repeat? Make it a     │
+   │    skill. Update TASKS.md for    │
+   │    the current phase.            │
+   └──────────────────────────────────┘
+```
+
+### 1. Intake & Extrapolation (orchestrator)
+
+Never pass a raw user prompt to the architect. The orchestrator's first job is to **expand** it.
+
+- **Verbatim prompt** — the literal request, never paraphrased.
+- **Implied requirements** — what the user almost certainly wants but didn't say. A request to "build a Kafka consumer" implies batching, error handling, dead-letter handling, metrics, graceful shutdown.
+- **Ambiguity flags** — questions that would block progress if not answered. Surface them; do not silently pick one interpretation.
+- **Edge cases** — empty input, malformed input, retry storms, backpressure.
+- **Integration points** — what this touches, what depends on it, what would have to change to remove it.
+- **Constraints** — performance, security, deployment, language, library version.
+
+The extrapolation is a Markdown section in the Context Package, not just a thought. The architect reads it before designing.
+
+### 2. Roadmap (architect)
+
+Architect returns a **roadmap document** with this structure:
+
+```
+# Roadmap: <Project or feature name>
+
+## Phase 1: <phase name>
+### Task 1.1: <task name>
+- **Goal:** one sentence
+- **Scope IN:** bullet list
+- **Scope OUT:** bullet list, with escalation target
+- **Acceptance:** testable criteria
+- **Assignee profile:** boomerang-coder | boomerang-tester | boomerang-linter | ...
+- **Dependencies:** Task 1.2, Task 0.3
+- **Context handoff from:** (prior task) — link to wrap-up memory
+
+### Task 1.2: ...
+
+## Phase 2: ...
+```
+
+Architect writes the roadmap to `docs/roadmap-<project-slug>.md` AND saves a thin summary to memoryManager with `project` metadata. The roadmap is durable — it survives TUI restart, context compaction, agent failures.
+
+### 3. Kanban Seed (kanban-board-manager skill)
+
+After the roadmap lands, the orchestrator invokes the **kanban-board-manager** skill to create one card per task in the project's `TASKS.md`. The skill manages seven statuses (Hermes-compatible):
+
+| Status | Meaning |
+|---|---|
+| `triage` | Raw idea, not yet decomposed or specified |
+| `todo` | Specified, awaiting dependencies |
+| `ready` | All dependencies met, worker can pick it up |
+| `running` | A worker has claimed it |
+| `blocked` | Stuck — needs human input or architect clarification |
+| `done` | Completed with evidence |
+| `archived` | Out of scope, no-op, or absorbed into another card |
+
+Cards link to each other (`Depends on: Task 1.2`) and link to roadmap sections (`Roadmap: docs/roadmap-foo.md#task-1-1`). The board (`TASKS.md`) is the durable source of truth for "what is being worked on." Chat scrollback is not.
+
+### 4. Dispatch (orchestrator + broker)
+
+For each `ready` card, the orchestrator:
+
+1. **Builds the Context Package** from:
+   - The card's own scope, acceptance criteria, and assignee
+   - The relevant section of the roadmap
+   - The handoff from the most recent completed dependency (worker.wrap_up_metadata)
+   - The agent profile's known customizations (from AGENTS.md and memory)
+2. **Consults the broker** — `broker.AccessControl().CanAccess(role, server)` for each tool the card will need. If the assignee profile is missing a tool the card requires, the orchestrator either narrows the card or reassigns. The prompt says it; the broker enforces it.
+3. **Delegates** via the Task tool with the Context Package inline. Never "look at TASKS.md and figure out what to do." The card's scope IS the task.
+4. **The worker** moves the card `ready → running → done` as it goes, attaching evidence (changed files, test results, residual risk) in the wrap-up.
+
+#### 4.1 Dispatch Granularity Rules (enforced)
+
+The orchestrator MUST scope each `boomerang-coder` dispatch to **exactly ONE card**. The card IS the dispatch.
+
+- ❌ **WRONG:** "T-065 + T-066: fix scan loops + CountMemories + stubs in one prompt"
+- ✅ **RIGHT:** Two sequential coder dispatches. T-065 first (coder finishes, commits, saves memory), then T-066 (coder reads T-065's wrap-up memory and continues).
+- ❌ **WRONG:** "Fix all the bugs in the memory store package"
+- ✅ **RIGHT:** One card per bug, with regression tests.
+
+Linting/formatting is a **separate concern** from the logical change. The coder's wrap-up MUST list every file that needs lint work. The orchestrator then dispatches a follow-up `T-LINT-XXX` card to `boomerang-linter` (NOT the coder).
+
+- ❌ **WRONG:** Coder runs `gofmt -w` on their way out the door.
+- ✅ **RIGHT:** Coder commits the logical fix, lists `gofmt: packages/memory/.../store/*.go` in wrap-up, linter sub-dispatch runs the format pass as a separate commit.
+
+Test coverage gaps discovered during a refactor card spawn a `T-TEST-NNN` card, not a scope-creep into the refactor.
+
+### 5. Wrap-up Audit (orchestrator + self-audit skill)
+
+Before ending the turn, the orchestrator runs a **board audit**:
+
+- **Unaccounted cards** (still in `triage`, `todo`, or `running` with no active worker): for each, decide one of:
+  - **Break into smaller tasks** — re-feed to the architect for finer-grained decomposition, then create the new cards.
+  - **Re-architect** — the card is too vague. Send back to the architect with the new evidence from sibling cards.
+  - **Requeue to Todo** — move it to `todo` and mark it explicitly as "next session" with a reason.
+- **Blocked cards** — surface to the user. They need human input.
+- **Done cards** — verify the handoff evidence is present (`changed_files`, `verification`, `residual_risk`).
+
+Then the orchestrator runs the **skill-self-audit** skill (a separate skill, invoked at end of cycle):
+
+> "Did we do a process more than once this cycle that should be a skill? If yes, invoke `boomerang-agent-builder` to create it before signing off."
+
+Finally, the orchestrator invokes the **todo-list-updater** skill to refresh `TASKS.md` for the current phase. The skill:
+- Marks completed items as done
+- Removes stale items
+- Adds new items discovered during the cycle
+- Keeps the "current phase" section at the top; archived phases at the bottom
+
+### Why this is prompts, not code
+
+The user explicitly asked for prompts, not new infrastructure. The data layer already exists (`TASKS.md` is the board; `memoryManager` is the durable memory; the broker is the permission boundary). The change is to **make the orchestrator follow the cycle every time, and to give it three named sub-skills to invoke for the steps that need structure.**
+
+## Triggers
+
+Use the **boomerang-orchestrator** skill (this one) when:
+- User requests complex multi-step work
+- Multiple files or components need changes
+- User says "do it all", "implement this", "build", "create"
+- Multiple agents might be needed
+
+Use the **kanban-board-manager** sub-skill when:
+- A roadmap has just been written and needs to be seeded into TASKS.md
+- The user asks "what's the status?" (read the board)
+- A worker finishes a card and needs to mark it done with evidence
+- An orchestrator is about to dispatch and needs to confirm a card is `ready`
+
+Use the **todo-list-updater** sub-skill when:
+- A phase is ending and the next phase's todos need to be staged
+- The user asks to refresh or clean up the todo list
+- An item completed and the `Current Phase` block of TASKS.md needs an edit
+
+Use the **skill-self-audit** sub-skill when:
+- The orchestrator is about to wrap up a cycle
+- The user says "/boomerang-handoff" or the cycle is naturally ending
+- A process has been repeated more than once in the same session
+
+---
+
+## Protocol Rules
+
+### Mandatory Steps (NEVER SKIP)
+
+1. **Query memoryManager** (MANDATORY FIRST ACTION) — Query memoryManager for context before any planning
+ 2. **Sequential Thinking** (MANDATORY SECOND ACTION) — Call memoryManager_add_thought immediately after memory query to analyze the request
+3. **Plan** — Create implementation plan (MANDATORY unless explicitly waived)
+4. **Delegate ALL work** via Task tool — You CANNOT write code, edit files, run bash, or do implementation work. Your only purpose is to delegate to sub-agents.
+5. **Git check** — Before any code changes, verify git status
+6. **Quality gates** — After sub-agents complete code changes, run quality checks
+7. **IMPROVE** — Extract patterns, bump trust, update shared knowledge (see IMPROVE phase below)
+8. **Update Docs & Todos** — Update documentation as needed
+9. **Save to memory** — After everything is complete, save a summary to memoryManager
+
+### Sequential Thinking Enforcement
+
+You MUST use `memoryManager_add_thought` for:
+- Complex multi-step problems
+- Tasks with unclear scope
+- Architectural decisions
+- Debugging or root cause analysis
+- Any task that requires planning or breaking down
+
+Adjust total_thoughts as needed. Do not stop at 1-2 thoughts if the problem is complex.
+
+### Context Compaction Strategy
+
+When context usage reaches approximately 40%:
+1. Trigger the `/handoff` skill to wrap up current work
+2. Save all critical context to memoryManager
+3. OpenCode has built-in context compaction that handles this automatically
+4. After compaction, re-read AGENTS.md, TASKS.md, HANDOFF.md, and README.md to restore essential context
+5. Continue from where you left off
+
+This keeps the context window low while preserving important instructions.
+
+### Agent Selection Guide
+
+- Code implementation / bug fixes → `boomerang-coder`
+- Planning / design / architecture → `boomerang-architect` (researches independently)
+- Quick file finding → `boomerang-explorer` (NOT for research summaries)
+- Web research → `researcher`
+- Writing tests → `boomerang-tester`
+- Linting / formatting → `boomerang-linter`
+- Git operations → `boomerang-git`
+- Documentation / markdown writing → `document-writer`
+- Web scraping → `web-scraper`
+
+### Sub-Agent Requirements
+
+When delegating to sub-agents, include in your prompt:
+- "Query memoryManager before starting work"
+- "Save your work to memoryManager when complete"
+- "Use memoryManager_add_thought if this is a complex task"
+- "Use tiered memory: standard saves for routine work, memoryManager_add_memory for high-value architectural decisions and session summaries"
+
+### Trust-Weighted Memory Protocol
+
+memoryManager uses trust scoring. High-value work should be tagged with `project` metadata:
+
+#### When Saving:
+- **Routine work** (error logs, quick fixes, chat turns): Use standard `memoryManager_add_memory`
+- **High-value work** (architectural decisions, verified successes, session summaries): Use `memoryManager_add_memory` with a descriptive `project` tag
+- **Session summaries**: Always use `memoryManager_add_memory` — these are high-value for resuming work
+
+#### Trust Signals:
+After completing work, consider adjusting trust based on outcomes:
+- `agent_used` (+0.05): Memory was used by an agent successfully
+- `user_confirmed` (+0.10): User confirmed the memory is accurate
+- `agent_ignored` (-0.05): Memory was not useful
+- `user_corrected` (-0.10): User corrected the memory
+
+#### When Searching:
+- Default searches use the configured strategy automatically
+- For explicit control: `memoryManager_query_memories` with `strategy: "tiered"` (Fast Reply) or `strategy: "vector_only"` (Archivist)
+- Use `memoryManager_query_kg` for knowledge graph queries
+
+#### Orchestrator-Specific:
+As orchestrator, use `memoryManager_add_memory` for:
+- Session summaries (after handoff)
+- Major architectural decisions made during planning
+- Complex dependency graphs or task analysis results
+
+### IMPROVE phase
+
+After quality gates pass and before documentation is updated, the orchestrator runs the IMPROVE phase. This enforces separation between execution (workers) and learning (post-swarm analysis).
+
+The IMPROVE phase performs four actions:
+
+1. **Analyze outcomes** — Review the completed work: what patterns emerged, what failures occurred, what decisions were made during the dispatch cycle.
+2. **Extract signals** — Categorize findings:
+   - Successful approaches are stored as **patterns** (reusable techniques).
+   - Failures are stored as **anti-patterns** (approaches to avoid).
+   - Key architectural choices are stored as **architecture decision records**.
+3. **Write to memory** — Use the following tools to populate shared knowledge:
+   - `memory.triggerExtraction` — Extract structured entities and relationships from the completed work.
+   - `memory.getTier1Summary` — Promote high-value decisions to the L1 key-decisions tier (trust >= 0.8).
+   - `memory.getRelationshipSummary` — Link new memories to existing ones via SUPERSEDES, RELATED_TO, or DERIVED_FROM relationships.
+4. **Bump trust** — Call `memory.adjustTrust` on relevant memories:
+   - `agent_used` (+0.05) for memories that proved correct during execution.
+   - `user_corrected` (-0.10) for memories that needed fixing.
+   - `user_confirmed` (+0.10) for architectural decisions verified by outcomes.
+
+This ensures shared knowledge contains verified outcomes, not speculative predictions made before quality gates pass. Workers never write to shared memory during execution — only the IMPROVE phase writes.
+
+### Context Isolation for Subagents
+
+### Problem: Context Bloat
+
+When sub-agents execute, their intermediate tool calls, search results, and exploration steps accumulate in the main conversation context. This causes:
+- **Context bloat** — The main context fills with irrelevant details
+- **"Dumb zone"** — Model quality degrades as context grows
+- **Token waste** — Paying for tokens that don't contribute to the final answer
+
+### Solution: Return-Only-Final-Result
+
+Sub-agents MUST follow this protocol:
+
+1. **Do all exploration internally** — Search, read, analyze as needed
+2. **Synthesize findings** — Distill all research into a concise summary
+3. **Return ONLY the final result** — No raw tool outputs, no intermediate steps
+4. **Use files for large outputs** — If results are too large for a summary, write to a file and return the file path
+
+### Example: Good vs Bad Sub-Agent Response
+
+**BAD** (returns raw tool output):
+```
+I found these files:
+- /home/user/project/src/main.ts (45 lines)
+- /home/user/project/src/utils.ts (120 lines)
+[... 50 more files ...]
+```
+
+**GOOD** (returns synthesized result):
+```
+## Exploration Results: Authentication Flow
+
+### Key Files
+| File | Role |
+|------|------|
+| src/auth/login.ts | Handles login form submission |
+| src/auth/middleware.ts | JWT validation |
+| src/auth/session.ts | Session management |
+
+### Architecture
+The auth system uses JWT tokens stored in httpOnly cookies...
+
+### Full Details
+See `exploration-auth.md` for complete file list and code snippets.
+```
+
+### Delegation Best Practices
+
+When delegating, tell the sub-agent:
+```
+"Do your research internally. Return ONLY a concise summary of findings.
+If output would exceed ~500 words, write it to a file and return the path."
+```
+
+### Context Budget
+
+Each sub-agent call should aim to return:
+- **Simple tasks**: 100-300 words
+- **Complex tasks**: 300-800 words OR a file path
+- **Never**: Raw tool output dumps
+
+## Task Flow
+
+The Boomerang Cycle v3 (matches the diagram at the top of this skill):
+
+```
+User Request
+  ↓
+1. INTAKE & EXTRAPOLATION      (orchestrator: build Context Package with implied reqs, ambiguity, edge cases)
+  ↓
+2. MEMORY QUERY                (memoryManager_query_memories)
+  ↓
+3. SEQUENTIAL THINK            (memoryManager_add_thought)
+  ↓
+4. PLAN: ROADMAP               (delegate to boomerang-architect → writes docs/roadmap-<proj>.md)
+  ↓
+5. KANBAN SEED                 (invoke kanban-board-manager skill → creates cards in TASKS.md)
+  ↓
+6. DISPATCH LOOP per ready card:
+   a. Build Context Package for the card
+   b. broker.AccessControl().CanAccess(profile, tool)  ← permission gate
+   c. Delegate via Task tool
+   d. Worker moves card ready → running → done
+  ↓
+7. WRAP-UP AUDIT               (walk the board; resolve unaccounted cards)
+  ↓
+8. SKILL SELF-AUDIT            (invoke skill-self-audit; create skills from repeated processes)
+  ↓
+9. TODO LIST UPDATE            (invoke todo-list-updater for current phase)
+  ↓
+10. DOCS & MEMORY SAVE         (TASKS.md, AGENTS.md, HANDOFF.md, memoryManager)
+```
+
+### Mandatory Steps (NEVER SKIP)
+
+1. **Query memoryManager** (MANDATORY FIRST ACTION) — Query memoryManager for context before any planning
+2. **Sequential Thinking** (MANDATORY SECOND ACTION) — Call `memoryManager_add_thought` immediately after memory query to analyze the request
+3. **Extrapolate** (NEW IN v3) — Build the Context Package's implied-reqs section. Never pass a raw prompt to the architect.
+4. **Roadmap** — Architect produces `docs/roadmap-<proj>.md` (phases → tasks, each task narrow enough for one coder).
+5. **Kanban seed** — Invoke `kanban-board-manager` skill. One card per task, with status, dependencies, and assignee.
+6. **Broker permission gate** (NEW IN v3) — For each `ready` card, consult `broker.AccessControl().CanAccess(profile, server)` for every tool the card needs. If the profile is missing a tool, narrow the card or reassign.
+7. **Delegate** — Use Task tool with the card's Context Package inline. The card's scope IS the task; do not let the worker re-derive it.
+8. **Git check** — Before any code changes, verify git status.
+9. **Quality gates** — Lint → Typecheck → Test before completion.
+10. **Wrap-up audit** — Walk the board. Unaccounted cards are broken, re-architected, or requeued.
+11. **Skill self-audit** — Invoke `skill-self-audit` skill. Repeated processes become skills via `boomerang-agent-builder`.
+12. **Todo list update** — Invoke `todo-list-updater` skill for the current phase.
+13. **Save to memory** — `memoryManager_add_memory` with `project` tag.
+
+## memoryManager MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `memoryManager_query_memories` | Semantic search over memories |
+| `memoryManager_add_memory` | Store a new memory entry |
+| `memoryManager_search_project` | Search indexed project files |
+| `memoryManager_index_project` | Trigger project indexing |
+| `memoryManager_get_file_contents` | Reconstruct file from indexed chunks |
+| `memoryManager_get_status` | Check memoryManager server status |
+| `memoryManager_query_kg` | Query knowledge graph |
+| `memoryManager_extract_entities` | Extract entities from memory |
+| `memoryManager_get_entity_graph` | Get entity connections |
+| `memoryManager_get_trust_score` | Get memory trust score |
+| `memoryManager_adjust_trust` | Adjust memory trust |
+| `memoryManager_find_contradictions` | Find contradictory memories |
+| `memoryManager_resolve_contradiction` | Resolve conflicting memories |
+
+### Knowledge Graph Query Example
+
+```javascript
+// Query knowledge graph for entity relationships
+memoryManager_query_kg({
+  query: JSON.stringify({
+    entity_a: "authentication",
+    relationship_types: ["RELATED_TO", "SUPERSEDES"],
+    inference_depth: 2,
+    limit: 50
+  })
+})
+```
+
+### Trust Score Example
+
+```javascript
+// Adjust trust based on agent feedback
+memoryManager_adjust_trust({
+  memory_id: "memory-uuid-here",
+  signal: "agent_used"  // +0.05 trust
+})
+```

package/.opencode/skills/external-skills-fetcher/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: external-skills-fetcher
+description: Clones the curated external skill repos (Orchestra-Research/AI-Research-SKILLs + nextlevelbuilder/ui-ux-pro-max-skill) into ~/.neuralgentics/external_skills/. Refreshes on session start. Toggle via external_skills.enabled in .env. Invoke via //external-skills-fetcher.
+tags:
+  - external
+  - skills
+  - fetcher
+  - git
+---
+
+# External Skills Fetcher
+
+## When to Invoke
+
+- **At session start** — the plugin's session-start hook invokes this skill automatically (before the SESSION START PROTOCOL so that the new SKILL.md files are visible to AGENTS.md and the rest of the protocol).
+- **Manually** — via `//external-skills-fetcher` when the user wants to refresh external skills mid-session.
+- **At release time** — `scripts/release.sh` calls the fetcher before building the dist tarball.
+
+## Preconditions (Step 0)
+
+- [ ] `git` is installed and on PATH
+- [ ] Network is available (offline is handled gracefully)
+- [ ] `~/.neuralgentics/` exists (created by `install.sh`)
+
+## Step 1: Read `.env`
+
+Read `external_skills.enabled` from the project's `.env` file (or `~/.neuralgentics/.env` as fallback).
+
+- If unset or `false` → log `[external-skills-fetcher] external_skills.enabled is false — skipping` and return `{ enabled: false }`.
+- If `true` → proceed to Step 2.
+
+## Step 2: Clone / Refresh Repositories
+
+Ensure `~/.neuralgentics/external_skills/` exists. For each configured repository:
+
+### Repo 1: AI-Research-SKILLs
+- **URL:** `https://github.com/Orchestra-Research/AI-Research-SKILLs.git`
+- **Target dir:** `~/.neuralgentics/external_skills/ai-research-skills/`
+- **License:** MIT
+- **Attribution:** `Copyright 2025 Claude AI Research Skills Contributors. Used under MIT License.`
+
+### Repo 2: ui-ux-pro-max-skill
+- **URL:** `https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git`
+- **Target dir:** `~/.neuralgentics/external_skills/ui-ux-pro-max-skill/`
+- **License:** MIT
+- **Attribution:** `Copyright 2024 Next Level Builder. Used under MIT License.`
+
+**Clone logic (per repo):**
+1. If target dir does not exist → `git clone --depth 1 <url> <target-dir>`
+2. If target dir exists → `cd <target-dir> && git pull --ff-only`
+   - If `git pull` fails (network error, no upstream) → log warning and continue. Do NOT throw.
+3. After clone/refresh, capture the current HEAD commit SHA: `git -C <target-dir> rev-parse HEAD`
+
+## Step 3: Write MANIFEST.json
+
+Write `~/.neuralgentics/external_skills/MANIFEST.json`:
+
+```json
+{
+  "version": 1,
+  "updated_at": "<ISO 8601 timestamp>",
+  "repos": {
+    "ai-research-skills": {
+      "url": "https://github.com/Orchestra-Research/AI-Research-SKILLs.git",
+      "commit_sha": "<40-char hex SHA>",
+      "license": "MIT",
+      "attribution": "Copyright 2025 Claude AI Research Skills Contributors. Used under MIT License."
+    },
+    "ui-ux-pro-max-skill": {
+      "url": "https://github.com/nextlevelbuilder/ui-ux-pro-max-skill.git",
+      "commit_sha": "<40-char hex SHA>",
+      "license": "MIT",
+      "attribution": "Copyright 2024 Next Level Builder. Used under MIT License."
+    }
+  }
+}
+```
+
+## Step 4: Return Handle
+
+Return to the orchestrator:
+
+```json
+{
+  "enabled": true,
+  "manifest_path": "~/.neuralgentics/external_skills/MANIFEST.json",
+  "repos": {
+    "ai-research-skills": { "status": "cloned", "commit_sha": "<sha>" },
+    "ui-ux-pro-max-skill": { "status": "refreshed", "commit_sha": "<sha>" }
+  },
+  "errors": []
+}
+```
+
+## Notes
+
+- **Offline-safe:** If `git pull` fails due to no network, log a warning and continue. The existing clone is still usable.
+- **Idempotent:** Running the fetcher multiple times is safe. `git pull --ff-only` on an already-up-to-date repo is a no-op.
+- **First install:** On a fresh `install.sh` run, the tarball may include a pre-bundled `share/external_skills/` snapshot. The fetcher will `git pull` to refresh it on first session start.
+- **MANIFEST.json is the source of truth** for commit SHAs and attribution. The Go catalog reads this file to stamp provenance on external skills.