feat(interns-skills-mvp): ship setup-interns + using-interns v0.1.0; project-bootstrap 1.5.0 -> 1.6.0

setup-interns (v0.1.0) — 8-phase install of the local `interns` MCP server:
detect `.common/lib/interns-mcp/` source, `pip install -e`, write
`.common/secrets/interns.env` with endpoint API keys (gitignored), register
`mcpServers.interns` in `~/.claude.json` with absolute Python interpreter
path + `cwd` so the runtime resolves config relative to project root.
Mirrors setup-projects-meta / setup-context7 confirmation-gate shape.
Description 899 chars (under the 900 budget per
feedback_skill_description_length_limit).

using-interns (v0.1.0) — runtime policy for `mcp__interns__*`. Per-session
permission grant mirrors project-discipline Rule 4: ask-mode default,
conversational grant ("разреши интернов" / "allow interns"), conversational
revoke, always-ask paths for `**/.env`, `**/secrets/**`, `**/*.key`,
`**/.ssh/**`, `**/.aws/credentials` etc with transitive rule (Claude can't
bypass by reading the file with the local Read tool and forwarding content),
cost-cap >$0.10 always asks, session-end automatic reset. Routing hints for
`bulk_text_read` (3+ files or one file >400 lines) and `transcript_distill`
(before .wiki/log.md updates / session summaries). Description 814 chars.

project-bootstrap (1.5.0 -> 1.6.0, MINOR — capability added):
* assets/CLAUDE.md.template: insert `delegate to interns when allowed`
  between `follow project discipline` and `we're on Windows`.
* SKILL.md Step 5: same insertion in inline template + new commentary
  paragraph explaining the trigger, no-op semantics, install pointer.
* SKILL.md Step 5.5: bootstrap-manifest table extended with
  `setup-interns`, `using-interns`, `project-discipline` rows.
* README.md: Workflow Step 5.5 description + See also section both pick up
  the new skills.

Root CLAUDE.md dogfood: `delegate to interns when allowed` line added.
.wiki/log.md decision entry. .tasks/STATUS.md task moved to 🟢 done.
.tasks/interns-skills-mvp.md per-task file with goal / key-files /
decisions log / open questions.

Build + install verified: `dist/{setup-interns,using-interns,
project-bootstrap}.skill` rebuilt; `bash scripts/install.sh ...` succeeded;
harness skill listing shows full descriptions for all three (no H1
fallback) — confirms the description budget held.

Versioning per project-discipline Rule 3:
* setup-interns: 0.1.0 (first edit of unversioned artifact, MAJOR=0).
* using-interns: 0.1.0 (first edit of unversioned artifact, MAJOR=0).
* project-bootstrap: 1.5.0 -> 1.6.0 (MINOR — adds capability without
  breaking existing CLAUDE.md merge or manifest consumers).

Server runtime itself (`.common/lib/interns-mcp/`) is out of scope for this
task — the skills land lifecycle, policy, and bootstrap integration so any
machine where the MCP server is later installed already has Claude's
policy in place.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-05-05 17:41:11 +03:00
parent 7464ae4bc4
commit 0eb7dd1d7c
14 changed files with 632 additions and 8 deletions

View File

@@ -0,0 +1,68 @@
# using-interns
Runtime policy for the local `interns` MCP server. Delegates predictable bulk I/O and summarization tasks to cheap intern LLMs (DeepSeek / Kimi / Ollama-hosted) so Claude saves Anthropic quota.
`using-interns` governs *usage* of an installed server. Initial setup (`pip install`, `.env` write, MCP registration) is owned by [`setup-interns`](../setup-interns/).
Full design: `.wiki/concepts/interns-design.md` (in this repo) — Layer 1 / 2 / 3 architecture, MVP catalog, always-ask paths, routing hints.
## When it triggers
- CLAUDE.md contains `delegate to interns when allowed` (added by `project-bootstrap` 1.6.0+).
- User says: "use interns", "delegate to an intern", "разреши интернов", "allow interns", "go ahead with interns".
- Claude is about to read 3+ files, or one file > 400 lines, just to build context.
- Claude is about to update `.wiki/log.md` or write a session summary from a long transcript.
- If `mcp__interns__*` tools are missing, this skill delegates to [`setup-interns`](../setup-interns/) before doing anything else.
## What it does
- **Picks the right intern** for the task from a routing table (`bulk_text_read` for reads, `transcript_distill` for summaries; future interns added in `.common/config/interns/config.yaml`).
- **Guards every call** with a per-session permission grant that mirrors `project-discipline` Rule 4 — ask-mode default, conversational grant / revoke, session-end reset.
- **Enforces always-ask paths** — `.env`, `**/secrets/**`, `**/*.key`, `**/*.pem`, `**/.ssh/**`, `**/.aws/credentials`, `**/.netrc` etc. — even when delegation is granted. Server-side enforcement plus a transitive rule: Claude can't bypass by reading the file with the local `Read` tool and forwarding the content.
- **Caps cost** — calls with estimated cost > $0.10 always go to ask-mode regardless of grant.
- **Tells Claude what NOT to delegate** — architecture, debugging, auth / payments, final commit messages, final user-facing answers.
## Permission grant cheat-sheet
| Phrase | Effect |
|---|---|
| (default) | Ask before every `mcp__interns__*` call. |
| "разреши интернов" / "allow interns" | Free delegation until session end (subject to always-ask paths + cost cap). |
| "отзови интернов" / "revoke interns" | Back to ask-mode. |
| (session ends) | Reset to ask-mode. The next session asks again. |
## Tool quick reference
| Tool | Required args | Optional | Purpose |
|---|---|---|---|
| `mcp__interns__bulk_text_read` | `paths: list[str]`, `question: str` | `max_tokens: int` | Read N files, answer with file:line citations. |
| `mcp__interns__transcript_distill` | `paths: list[str]`, `question: str` | `max_tokens: int` | Distill transcript / log into structured action list. |
Pass **paths**, not file contents. The MCP server reads and applies the always-ask matcher server-side; forwarding content as a string arg bypasses the gate.
## When NOT to use
- Architecture / design decisions — Claude's job.
- Debugging — cheap models miss subtle bugs.
- Auth / payments / PII / production data — recommendation, not enforced, but obvious.
- Final commit messages, PR descriptions, user-facing answers — don't sub-delegate the deliverable.
- A single 50-line file you can read yourself for free.
Full policy and examples in [`SKILL.md`](SKILL.md).
## Install
From the repo root:
```bash
bash scripts/install.sh using-interns
```
Works on Windows under git-bash, Linux, macOS.
## See also
- [`setup-interns`](../setup-interns/) — companion, owns the server install + `mcpServers.interns` registration.
- [`project-discipline`](../project-discipline/) — Rule 4 (per-session push grant) is the prior art for the grant mechanism here.
- [`using-projects-meta`](../using-projects-meta/), [`using-context7`](../using-context7/) — sister `using-X` skills for other MCP servers (same shape).
- `.wiki/concepts/interns-design.md` — full architecture spec.