feat(interns): add repo_read routing to using-interns + Node/repomix checks to setup-interns [v0.2.0]
using-interns: overview table 2→3 interns, routing hints for repo_read vs bulk_text_read, tool quick reference row. setup-interns: Phase 0 adds node --version check + optional repomix pre-warm. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
# Task Board
|
||||
_Updated: 2026-05-05 (active-platform-eval paused — design done, awaiting eval-set authorship decision)_
|
||||
_Updated: 2026-05-05 (interns-repo-read-skill-updates done — both skills 0.2.0)_
|
||||
|
||||
<!--
|
||||
Canonical layout. One block per task. Per-task deep context lives in
|
||||
@@ -96,11 +96,11 @@ _Updated: 2026-05-05 (active-platform-eval paused — design done, awaiting eval
|
||||
|
||||
---
|
||||
|
||||
## ⚪ [interns-repo-read-skill-updates] — Skill-side updates for the `repo_read` intern (design at claude-skills/.wiki/concepts/interns-repo-read-design.md). Two coordinated edits: (1) `using-interns/SKILL.md` routing section — add hints on when to use `repo_read` vs `bulk_text_read`, MINOR bump; (2) `setup-interns/SKILL.md` — add Node-in-PATH check + optional `npx repomix@latest --version` pre-warm step, MINOR bump. Blocked by `common#interns-repo-read-impl` only for end-to-end test; skill edits themselves can ship in parallel.
|
||||
## 🟢 [interns-repo-read-skill-updates] — Skill-side updates for the `repo_read` intern (design at claude-skills/.wiki/concepts/interns-repo-read-design.md). Two coordinated edits: (1) `using-interns/SKILL.md` routing section — add hints on when to use `repo_read` vs `bulk_text_read`, MINOR bump; (2) `setup-interns/SKILL.md` — add Node-in-PATH check + optional `npx repomix@latest --version` pre-warm step, MINOR bump. Blocked by `common#interns-repo-read-impl` only for end-to-end test; skill edits themselves can ship in parallel.
|
||||
|
||||
**Status:** ready
|
||||
**Where I stopped:** (not started)
|
||||
**Next action:** Edit `using-interns/SKILL.md` Routing section per design; bump version. Edit `setup-interns/SKILL.md` add Node-check; bump version.
|
||||
**Status:** done
|
||||
**Where I stopped:** both skills edited (0.1.0→0.2.0), rebuilt + installed, versions verified on disk
|
||||
**Next action:** (none — kept until merged)
|
||||
**Branch:** n/a
|
||||
<!-- created-by: OpeItcLoc03@DESKTOP-NSEF0UK / from: .meeting-room / 2026-05-05T20:05:05.877Z -->
|
||||
|
||||
|
||||
26
.tasks/interns-repo-read-skill-updates.md
Normal file
26
.tasks/interns-repo-read-skill-updates.md
Normal file
@@ -0,0 +1,26 @@
|
||||
# interns-repo-read-skill-updates
|
||||
|
||||
## Goal
|
||||
Add `repo_read` intern routing to `using-interns/SKILL.md` and Node.js + repomix pre-warm checks to `setup-interns/SKILL.md`, per the design at `.wiki/concepts/interns-repo-read-design.md`. Both bumps are MINOR (0.1.0 → 0.2.0).
|
||||
|
||||
## Key files
|
||||
- `skills/using-interns/SKILL.md` — routing section, overview table, tool quick reference
|
||||
- `skills/setup-interns/SKILL.md` — Phase 0 environment sanity (add Node check + repomix pre-warm)
|
||||
- `.wiki/concepts/interns-repo-read-design.md` — design doc (reference only)
|
||||
|
||||
## Decisions log
|
||||
- 2026-05-05: Task created from STATUS.md ⚪ entry. Design approved in .meeting-room. Skill edits can ship in parallel with backend impl (`common#interns-repo-read-impl`); end-to-end test blocked until backend lands.
|
||||
|
||||
## Open questions
|
||||
- [ ] none — design is approved
|
||||
|
||||
## Completed steps
|
||||
- [x] Read design doc and both SKILL.md files
|
||||
- [x] Edit `using-interns/SKILL.md`: added repo_read to Overview table, Routing hints, Tool quick reference; bumped 0.1.0→0.2.0
|
||||
- [x] Edit `setup-interns/SKILL.md`: added Node-in-PATH check + repomix pre-warm to Phase 0; bumped 0.1.0→0.2.0
|
||||
- [x] Build all .skill archives (`scripts/build.ps1`)
|
||||
- [x] Install to `~/.claude/skills/` (`scripts/install.sh`)
|
||||
- [x] Verify versions 0.2.0 and content on disk
|
||||
|
||||
## Notes
|
||||
- Backend impl (`interns_mcp/interns/repo_read.py`) is a separate task in `.common/lib/interns-mcp/`, not in this repo. Skill edits are parallel-safe.
|
||||
BIN
dist/setup-interns.skill
vendored
BIN
dist/setup-interns.skill
vendored
Binary file not shown.
BIN
dist/using-interns.skill
vendored
BIN
dist/using-interns.skill
vendored
Binary file not shown.
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: setup-interns
|
||||
version: 0.1.0
|
||||
version: 0.2.0
|
||||
description: Installs and configures the local `interns` MCP server — a FastMCP stdio app at `<project-root>/.common/lib/interns-mcp/` that delegates bulk reads, transcript distillation, and other predictable I/O to cheap intern LLMs (DeepSeek / Kimi / Ollama) so Claude saves Anthropic quota. Procedure: detect the server source, `pip install -e` it, write `.common/secrets/interns.env` with the endpoint API keys, register `mcpServers.interns` in `~/.claude.json`. Use this skill when the user says "install interns", "set up interns", "configure interns", "настрой интернов", "установи интернов", "interns не работает", "interns isn't working", or whenever the `mcp__interns__*` tools are missing in a session that needs delegation. Cross-platform — Windows / Linux / macOS. Mutates user-level config and writes secrets; pauses for confirmation before every write.
|
||||
---
|
||||
|
||||
@@ -35,6 +35,8 @@ The procedure runs `pip install`, writes `.common/secrets/interns.env` (carries
|
||||
|
||||
- Confirm Claude Code is the current harness (need `mcpServers` registration in `~/.claude.json`).
|
||||
- Confirm `python` ≥ 3.11 and `pip` are on `PATH`. Report the resolved interpreter path (`python -c "import sys; print(sys.executable)"`); the skill will pin this exact path in the MCP registration so a later `python` shadowed by another env doesn't silently take over.
|
||||
- Confirm `node` is on `PATH` (`node --version`). The `repo_read` intern runs `npx repomix@latest` as a subprocess. If `node` is absent, the user must install Node.js 20+ before proceeding — `repo_read` calls will fail at runtime with a clear "node not found" error.
|
||||
- (Optional, recommended) Pre-warm the repomix binary: `npx --yes repomix@latest --version`. This caches the package so the first real `repo_read` call is instant (5–10s first-run penalty avoided). Skip silently on failure — the call will just be slower the first time.
|
||||
- Confirm network reachability to the configured endpoints (default: `https://ollama.com/v1`). On HTTP 401 / 403 later, the API key is dead — stop and ask for a new one.
|
||||
- Pick paths: `<project-root>/.common/lib/interns-mcp/` (source), `<project-root>/.common/config/interns/config.yaml` (catalog), `<project-root>/.common/secrets/interns.env` (keys, gitignored), `~/.claude.json` (MCP registration). POSIX-style paths resolve correctly under git-bash on Windows.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: using-interns
|
||||
version: 0.1.0
|
||||
version: 0.2.0
|
||||
description: Use when delegating predictable bulk reads or summarization to cheap intern LLMs via the local `interns` MCP server (`mcp__interns__bulk_text_read`, `mcp__interns__transcript_distill`, etc.) so Claude saves Anthropic quota. Activated by `delegate to interns when allowed` in CLAUDE.md or explicit phrases like "use interns", "delegate to an intern", "разреши интернов", "allow interns". Per-session permission grant mirrors `project-discipline` Rule 4: ask-mode default, conversational grant / revoke, always-ask paths for `.env` / secrets / keys / SSH / credentials even with active grant, transitive rule (Claude can't bypass by reading the file itself and forwarding content), session-end reset. Skip for architecture, debugging, auth / payments, final commit messages, or final user-facing text.
|
||||
---
|
||||
|
||||
@@ -10,14 +10,15 @@ description: Use when delegating predictable bulk reads or summarization to chea
|
||||
|
||||
`interns` is a local stdio MCP server that exposes a catalog of cheap-LLM "interns" — DeepSeek, Kimi, Ollama-hosted models, etc. — so Claude can delegate predictable bulk I/O and summarization tasks instead of paying Anthropic quota for them. The pattern (~23× cheaper end-to-end on summarization, ~125× per-call on bulk reads) is sourced from a Reddit thread + Medium follow-up; see `.wiki/concepts/interns-design.md` for the full design and the cost numbers.
|
||||
|
||||
Two MVP interns:
|
||||
Three MVP interns:
|
||||
|
||||
| Tool | What it does | When to call |
|
||||
|---|---|---|
|
||||
| `mcp__interns__bulk_text_read` | Reads N files end-to-end and answers a focused question with file:line citations. | Claude was about to read 3+ files or one file > 400 lines just to extract context. |
|
||||
| `mcp__interns__transcript_distill` | Compresses a session transcript / log into a structured action list (decisions / open questions / next steps). | Before updating `.wiki/log.md` or producing a session summary. |
|
||||
| `mcp__interns__repo_read` | Packs a directory/repo via `repomix` and answers a focused question about the codebase. | Whole-repo or whole-directory questions — architecture, "where is X used", "what does module Y do". See Routing hints for `repo_read` vs `bulk_text_read`. |
|
||||
|
||||
Both currently run on Ollama Cloud (`deepseek-v4-flash`, ~$0.002 / call). Adding a new intern is a config-only change — see `.wiki/concepts/interns-design.md` § "Как добавить нового интерна".
|
||||
All currently run on Ollama Cloud (`deepseek-v4-flash`, ~$0.002 / call). Adding a new intern is a config-only change — see `.wiki/concepts/interns-design.md` § "Как добавить нового интерна".
|
||||
|
||||
## Prerequisites
|
||||
|
||||
@@ -103,6 +104,9 @@ Any call with estimated cost > $0.10 (per the `tokens × price_per_M` config in
|
||||
|---|---|
|
||||
| File > 400 lines, not editing it | `bulk_text_read` |
|
||||
| Need to read 3+ files for context | `bulk_text_read` |
|
||||
| Whole-repo or whole-directory question (architecture, "where is X used", "what does module Y do") | `repo_read` |
|
||||
| `bulk_text_read` vs `repo_read` | Use `bulk_text_read` when file paths are known and explicit. Use `repo_read` when you need a whole directory without cherry-picking files — repomix packs everything under the given paths. |
|
||||
| Don't delegate editing or debugging a specific file to `repo_read` | Read the file yourself. `repo_read` is for comprehension, not modification. |
|
||||
| Updating `.wiki/log.md` or session-summary doc | `transcript_distill` |
|
||||
| Compressing a long brainstorm transcript before quoting in a design doc | `transcript_distill` |
|
||||
| (Future interns in `config.yaml`) | per the description in the catalog |
|
||||
@@ -127,6 +131,7 @@ Don't pass file *contents* as arguments — only paths. The MCP server reads and
|
||||
| Tool | Required args | Optional | Purpose |
|
||||
|---|---|---|---|
|
||||
| `mcp__interns__bulk_text_read` | `paths: list[str]`, `question: str` | `max_tokens: int` | Read N files end-to-end, answer the question with citations. |
|
||||
| `mcp__interns__repo_read` | `paths: list[str]`, `question: str` | `compress: bool`, `max_tokens: int` | Pack directory/repo via repomix, answer the question. Use `compress=True` for large codebases (lossy: strips comments/whitespace). |
|
||||
| `mcp__interns__transcript_distill` | `paths: list[str]`, `question: str` | `max_tokens: int` | Distill transcript / log into structured action list. |
|
||||
|
||||
(Future interns expose tools at `mcp__interns__<intern_id>` as the catalog grows.)
|
||||
|
||||
Reference in New Issue
Block a user