vitya
0eb7dd1d7c
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>
115 lines
5.1 KiB
Markdown
115 lines
5.1 KiB
Markdown
# project-bootstrap
|
||
|
||
Initializes or upgrades a project workspace in one pass: git, `.gitignore`,
|
||
`README.md`, `.wiki/` (Karpathy's LLM Wiki layout), `.tasks/` (per-task board),
|
||
and `CLAUDE.md` with skill triggers.
|
||
|
||
Operates in two modes, picked automatically:
|
||
|
||
- **init** — empty or near-empty folder. Creates everything from scratch.
|
||
- **upgrade** — existing project. Detects what's already there, only fills the
|
||
gaps. Never overwrites without explicit confirmation.
|
||
|
||
## When it triggers
|
||
|
||
The skill auto-activates on phrases like:
|
||
|
||
- "initialize project", "bootstrap", "setup project"
|
||
- "upgrade project", "add wiki", "add tasks"
|
||
- "start project", "set everything up"
|
||
- "let's start a project", "init"
|
||
|
||
It also triggers when an agent is launched in a fresh folder that the user
|
||
clearly intends to turn into a workspace.
|
||
|
||
## Prerequisites
|
||
|
||
`project-bootstrap` does not lay out `.wiki/` or `.tasks/` by itself — it
|
||
delegates to two companion skills, which must be installed on the machine
|
||
running it:
|
||
|
||
- [`setup-wiki`](../setup-wiki/) — creates the canonical `.wiki/` layout.
|
||
- [`setup-tasks`](../setup-tasks/) — creates the canonical `.tasks/` layout.
|
||
|
||
If either is missing, `project-bootstrap` stops with a clear error rather
|
||
than falling back to ad-hoc creation. This keeps layout drift between
|
||
projects bootstrapped at different times debuggable.
|
||
|
||
## What it creates
|
||
|
||
| Path | Source | Notes |
|
||
|---|---|---|
|
||
| `.git/` | `git init` | Skipped if repo already initialized. |
|
||
| `.gitignore` | `assets/.gitignore.template` | Skipped if file exists. |
|
||
| `README.md` | minimal stub | Skipped if file exists. |
|
||
| `.wiki/` | delegated to `setup-wiki` | Karpathy LLM Wiki layout — `CLAUDE.md`, `index.md`, `log.md`, `overview.md`, `raw/`, `entities/`, `concepts/`, `packages/`, `sources/`. |
|
||
| `.tasks/` | delegated to `setup-tasks` | Canonical board — `STATUS.md` plus per-task `<task-slug>.md` files. |
|
||
| `CLAUDE.md` | `assets/CLAUDE.md.template` | Skill triggers (`use superpowers`, `use project wiki`, etc.). On non-Windows hosts, swap the `we're on Windows` line for `we're on Linux` / `we're on macOS`. On upgrade, the template is treated as a canonical set and merged idempotently — only missing trigger lines are appended after user confirm. Re-runs are no-ops. |
|
||
| `.wiki/concepts/bootstrap-manifest.md` | generated | Records which skill versions initialized the project, so cross-project layout drift is debuggable. |
|
||
|
||
## Workflow
|
||
|
||
1. **Detect mode.** Inspect the current directory — git, `.wiki/`, `.tasks/`,
|
||
`CLAUDE.md`, `README.md` — and print a single summary block: what was
|
||
found, what will be created, what will be skipped.
|
||
2. **Confirm.** One question, one confirmation. Nothing is written before the
|
||
user agrees.
|
||
3. **Steps 1–5.** Create or skip each piece in order — git, README, `.wiki/`,
|
||
`.tasks/`, `CLAUDE.md`. Steps 3 and 4 delegate to the setup-skills.
|
||
4. **Step 5.5.** Write `bootstrap-manifest.md` recording the versions of
|
||
`project-bootstrap`, `setup-wiki`, `setup-tasks`, `project-discipline`,
|
||
`setup-interns`, and `using-interns` used.
|
||
5. **Step 5.6.** Detect the official `superpowers@claude-plugins-official`
|
||
plugin via `~/.claude/plugins/installed_plugins.json`. If absent, print
|
||
a one-time chat recommendation with the install command and upstream
|
||
link. Never auto-installs, never modifies project files.
|
||
6. **Commit.** `chore: bootstrap project structure` for fresh repos, or
|
||
`chore: upgrade project structure` adding only the new files for existing
|
||
ones. Pushes only on explicit user request.
|
||
7. **Summary.** Final report — what was created, what was skipped, suggested
|
||
next step.
|
||
|
||
## Rules
|
||
|
||
- Never overwrite an existing file without explicit user confirmation.
|
||
- Always show the plan before touching the filesystem.
|
||
- Never invent project details — read what's already there.
|
||
- Commit only files just created — never touch the rest of the tree.
|
||
- Push only after the user explicitly says so.
|
||
|
||
## Install
|
||
|
||
From the repo root:
|
||
|
||
**Windows (PowerShell):**
|
||
|
||
```powershell
|
||
bash scripts/install.sh project-bootstrap
|
||
```
|
||
|
||
**Linux / macOS (bash):**
|
||
|
||
```bash
|
||
bash scripts/install.sh project-bootstrap
|
||
```
|
||
|
||
`install.sh` works on Windows under git-bash. A native `install.ps1` is
|
||
[planned](../../.tasks/STATUS.md) but not required.
|
||
|
||
The skill installs to `~/.claude/skills/project-bootstrap/`. Override the
|
||
target with `CLAUDE_SKILLS_DIR=/path bash scripts/install.sh …`.
|
||
|
||
## See also
|
||
|
||
- [`setup-wiki`](../setup-wiki/) — companion, owns `.wiki/` layout.
|
||
- [`setup-tasks`](../setup-tasks/) — companion, owns `.tasks/` layout.
|
||
- [`using-wiki`](../using-wiki/) — runtime policy for working with `.wiki/`.
|
||
- [`using-tasks`](../using-tasks/) — runtime policy for working with `.tasks/`.
|
||
- [`project-discipline`](../project-discipline/) — cross-project rules
|
||
activated by the `follow project discipline` trigger.
|
||
- [`setup-interns`](../setup-interns/), [`using-interns`](../using-interns/) —
|
||
pair behind the `delegate to interns when allowed` trigger; cheap-LLM
|
||
delegation under a per-session permission grant.
|
||
- Karpathy's LLM Wiki gist:
|
||
<https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f>
|