Files

vitya 0eb7dd1d7c 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>

2026-05-05 17:41:11 +03:00

4.1 KiB

Raw Blame History

setup-interns

One-time skill that brings up the local interns MCP server on a new (or freshly broken) machine. Detects the runtime source at <project-root>/.common/lib/interns-mcp/, runs pip install -e, writes .common/secrets/interns.env with the endpoint API keys, and registers mcpServers.interns in ~/.claude.json.

The runtime policy for using the resulting tools lives in using-interns — setup-interns is the only place that touches user-level config or the project's secrets directory.

Full design (Layer 1 / 2 / 3, MVP catalog, always-ask paths, routing hints): .wiki/concepts/interns-design.md (in this repo).

When it triggers

User says: "install interns", "set up interns", "configure interns", "настрой интернов", "установи интернов", "interns не работает", "interns isn't working".
using-interns detects missing mcp__interns__* tools and delegates here via its Prerequisites section.
A new machine in the multi-machine fleet — install once per machine that wants delegation.

What it touches

Path	Role
`<project-root>/.common/lib/interns-mcp/`	server source (must already exist; not created here)
`<project-root>/.common/config/interns/config.yaml`	catalog of interns + endpoints (read-only here)
`<project-root>/.common/secrets/interns.env`	endpoint API keys (gitignored)
`~/.claude.json` (`mcpServers.interns`)	MCP registration
`pip` site-packages	editable install of `interns_mcp`

Hard rules

Never auto-mutate. Phase 1 (discovery) and Phase 2 (plan) always pause for explicit confirmation. A trigger phrase grants permission to inspect, not to run pip install or write secrets.
Never echo endpoint API keys in chat. Edit / Write tool calls inevitably contain them (that's how they land in .env); chat output must not.
Never run on absent source. If .common/lib/interns-mcp/pyproject.toml is missing, stop and tell the user — initializing a fresh runtime is a separate task.
Always chmod 600 .env on Linux / macOS. Token leak otherwise.
Pin the absolute Python interpreter path in mcpServers.interns.command. A bare python resolves to whatever shadows it on PATH at session start.

Procedure (high-level)

Phase 0 — environment sanity (python ≥ 3.11, pip, network to endpoints).
Phase 1 — discovery (source / module / config / keys / MCP registration / .gitignore).
Phase 2 — plan + confirm. Wait for explicit "ok" / "go" / "поехали".
Phase 3 — backup (~/.claude.json, existing .common/secrets/interns.env).
Phase 4 — pip install -e .common/lib/interns-mcp/.
Phase 5 — write .common/secrets/interns.env (per-key, missing-only) + ensure .gitignore rule.
Phase 6 — register mcpServers.interns in ~/.claude.json with absolute interpreter path + cwd.
Phase 7 — best-effort smoke test (in-session caveat: real verification is after restart).
Phase 8 — restart guidance + final report.

Full procedure with shell snippets and templates lives in SKILL.md.

Rollback

Stop. Don't fix forward.
cp <file>.bak-<ts> <file> for ~/.claude.json and .common/secrets/interns.env.
Optional: pip uninstall interns-mcp to undo the editable install.
Restart Claude Code.
Confirm mcp__interns__* tools are gone (or back to the prior version).

Install

From the repo root:

bash scripts/install.sh setup-interns

Works on Windows under git-bash, Linux, macOS.

4.1 KiB Raw Blame History