diff --git a/.tasks/STATUS.md b/.tasks/STATUS.md index 2a060ac..d239754 100644 --- a/.tasks/STATUS.md +++ b/.tasks/STATUS.md @@ -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)_ diff --git a/.tasks/interns-repo-read-skill-updates.md b/.tasks/interns-repo-read-skill-updates.md new file mode 100644 index 0000000..4b2f8d6 --- /dev/null +++ b/.tasks/interns-repo-read-skill-updates.md @@ -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. \ No newline at end of file diff --git a/dist/setup-interns.skill b/dist/setup-interns.skill index a5efedc..f036a27 100644 Binary files a/dist/setup-interns.skill and b/dist/setup-interns.skill differ diff --git a/dist/using-interns.skill b/dist/using-interns.skill index eec6d16..6576bd3 100644 Binary files a/dist/using-interns.skill and b/dist/using-interns.skill differ diff --git a/skills/setup-interns/SKILL.md b/skills/setup-interns/SKILL.md index 8395564..413faad 100644 --- a/skills/setup-interns/SKILL.md +++ b/skills/setup-interns/SKILL.md @@ -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 `/.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: `/.common/lib/interns-mcp/` (source), `/.common/config/interns/config.yaml` (catalog), `/.common/secrets/interns.env` (keys, gitignored), `~/.claude.json` (MCP registration). POSIX-style paths resolve correctly under git-bash on Windows. diff --git a/skills/using-interns/SKILL.md b/skills/using-interns/SKILL.md index 198aa80..c5afdfa 100644 --- a/skills/using-interns/SKILL.md +++ b/skills/using-interns/SKILL.md @@ -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__` as the catalog grows.)