vitya
ef3d38e79d
Aligns claude-skills with secrets-out-of-common etap-1 migration: the canonical home for plain-text local-dev secrets is now ~/.config/projects-secrets/, outside any git tree. setup-interns [v0.3.0 → v0.4.0, MINOR — write target changed]: - Phase 1 drops gitignore-sanity check (no longer needed) - Phase 2 plan block drops Gitignore line - Phase 3 backs up ~/.config/projects-secrets/interns.env if present - Phase 5 writes ~/.config/projects-secrets/interns.env (mkdir -p ahead) - Phase 6 cwd documentation: secrets path no longer relative to cwd; uses INTERNS_SECRETS_PATH env var (or ~/.config default) — independent - Common-mistakes drops "missing gitignore rule" entry using-interns [v0.2.0 → v0.2.1, PATCH — wording]: - Always-ask paths section reflects new canonical secrets home - Prerequisites text updates setup-interns write target interns-design.md (wiki concept): path refs updated for ASCII layer diagram, Layer 1 example block, Phase 5 description, comparison table, and final cross-cutting note. **/projects-secrets/** added to always-ask documentation pattern. dist/: setup-interns.skill + using-interns.skill rebuilt. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
75 lines
4.1 KiB
Markdown
75 lines
4.1 KiB
Markdown
# 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 `~/.config/projects-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`](../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`](../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) |
|
|
| `~/.config/projects-secrets/interns.env` | endpoint API keys (outside any git tree) |
|
|
| `~/.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)
|
|
|
|
1. **Phase 0** — environment sanity (`python` ≥ 3.11, `pip`, network to endpoints).
|
|
2. **Phase 1** — discovery (source / module / config / keys / MCP registration).
|
|
3. **Phase 2** — plan + confirm. Wait for explicit "ok" / "go" / "поехали".
|
|
4. **Phase 3** — backup (`~/.claude.json`, existing `~/.config/projects-secrets/interns.env`).
|
|
5. **Phase 4** — `pip install -e .common/lib/interns-mcp/`.
|
|
6. **Phase 5** — write `~/.config/projects-secrets/interns.env` (per-key, missing-only).
|
|
7. **Phase 6** — register `mcpServers.interns` in `~/.claude.json` with absolute interpreter path + `cwd`.
|
|
8. **Phase 7** — best-effort smoke test (in-session caveat: real verification is after restart).
|
|
9. **Phase 8** — restart guidance + final report.
|
|
|
|
Full procedure with shell snippets and templates lives in [`SKILL.md`](SKILL.md).
|
|
|
|
## Rollback
|
|
|
|
1. Stop. Don't fix forward.
|
|
2. `cp <file>.bak-<ts> <file>` for `~/.claude.json` and `~/.config/projects-secrets/interns.env`.
|
|
3. Optional: `pip uninstall interns-mcp` to undo the editable install.
|
|
4. Restart Claude Code.
|
|
5. Confirm `mcp__interns__*` tools are gone (or back to the prior version).
|
|
|
|
## Install
|
|
|
|
From the repo root:
|
|
|
|
```bash
|
|
bash scripts/install.sh setup-interns
|
|
```
|
|
|
|
Works on Windows under git-bash, Linux, macOS.
|
|
|
|
## See also
|
|
|
|
- [`using-interns`](../using-interns/) — runtime policy + per-session permission grant for the `mcp__interns__*` tools.
|
|
- [`setup-projects-meta`](../setup-projects-meta/) — companion pattern, similar 8-phase shape.
|
|
- [`setup-context7`](../setup-context7/) — sister setup-skill for the context7 MCP plugin.
|
|
- [`project-discipline`](../project-discipline/) — Rule 4 (per-session push grant) is the prior art for the grant mechanism in `using-interns`.
|
|
- `.wiki/concepts/interns-design.md` — full architecture spec.
|