From a04985390e75a4400601cd39685b801e5054497e Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 16:55:21 +0000 Subject: [PATCH 1/2] =?UTF-8?q?docs(devcontainer-features):=20=F0=9F=93=9D?= =?UTF-8?q?=20rewrite=20root=20README=20around=20current=20usage?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01YG4X8TdddFmqXDN6Exw4cb --- README.md | 89 +++++++++++++++++++++++++++---------------------------- 1 file changed, 43 insertions(+), 46 deletions(-) diff --git a/README.md b/README.md index 618913cc..68d28e9e 100644 --- a/README.md +++ b/README.md @@ -2,54 +2,25 @@ # Dev Container Features -This repository contains a collection of features that can be used to enhance the development experience in a [Visual Studio Code Dev Container](https://code.visualstudio.com/docs/remote/containers). +Ready-made [Dev Container](https://containers.dev) features for git workflow, +commit hooks, versioning, AI coding skills, Kubernetes and more. Pick the ones +you need; each is independent and documents its own options. -The features are organized in separate folders and can be used individually in a `devcontainer.json` file. +## Quick start -## Installation +Add features to `.devcontainer/devcontainer.json`: -Every feature in this repository can be installed three ways. Pick whichever fits where you're running: - -1. **As a devcontainer feature** — declare it in `.devcontainer/devcontainer.json`; the Dev Containers CLI / VS Code builds it into the container image. Nothing to run locally. See each feature's own `## Quick Start — devcontainer.json` below. -2. **Console, via `npx`** — requires Node.js/npm on the machine you run it from (host or inside the container). Resolves this repo from GitHub and runs `install.sh`. - ```sh - npx tomgrv/devcontainer-features -h - ``` -3. **Console, via `curl`** — no Node.js/npm required. Downloads this repo to a temp directory, runs `install.sh`, and cleans up after itself: - ```sh - curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- -h - ``` - Everything after `-s --` is forwarded to `install.sh` — same commands/targets as the `npx` form. Set `DEVCONTAINER_FEATURES_REF` to install from a different branch, tag, or commit. - -Methods 2 and 3 both run `install.sh`, which behaves the same on a host and inside a container (Codespaces, an already-running devcontainer): it installs the tool itself (binaries, git config, package-manager installs where a feature needs one, ...) and deploys the feature's stub files (`.devcontainer/`, `.github/`, editor config, ...) into the current project. A handful of steps genuinely only make sense in one context or the other (e.g. gateway's host CA trust-store setup, or diverting `curl` only by default inside a container) — those scripts detect where they're running and adjust themselves; you don't need to. - -#### To install only root stubs - -```sh -npx tomgrv/devcontainer-features -- init -# or, without node/npm: -curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- init -``` - -#### To install a specific devcontainer feature - -```sh -npx tomgrv/devcontainer-features -- add gitutils -# or, without node/npm: -curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- add gitutils -``` - -#### To set up a full dev environment - -```sh -npx tomgrv/devcontainer-features -- add -a -# or, without node/npm: -curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- add -a +```json +"features": { + "ghcr.io/tomgrv/devcontainer-features/gitutils:11": {}, + "ghcr.io/tomgrv/devcontainer-features/githooks:11": {} +} ``` -## Features Overview +Rebuild the container and they are ready. The id is always +`ghcr.io/tomgrv/devcontainer-features/:11`. -Each row's console command is `add ` (see [Installation](#installation)); the devcontainer.json id is `ghcr.io/tomgrv/devcontainer-features/:11`; the npm package is `@tomgrv/devcontainer-features-`. +## Features | Feature | `` | Description | | -------------------------------------------- | -------------- | ------------------------------------------------------------------------- | @@ -64,14 +35,40 @@ Each row's console command is `add ` (see [Installation](#installation) | [Scripting](./src/scripting/README.md) | `scripting` | Standard root `setup.sh` bootstrapping `zz-use` and the repo entrypoint | | [AI Coding](./src/ai-coding/README.md) | `ai-coding` | Agent-agnostic AI coding skills + Claude Code GitHub Action | -## MCP server for agents +Each feature has its own README with its options and commands. + +## Install without a dev container + +The same features install from a terminal on any machine (host, Codespaces, +running container). They set up the tool and copy the feature's files +(`.devcontainer/`, `.github/`, editor config...) into the current project. + +```sh +npx tomgrv/devcontainer-features -- add gitutils # one feature +npx tomgrv/devcontainer-features -- add -a # all of them +npx tomgrv/devcontainer-features -- init # root files only +npx tomgrv/devcontainer-features -h # all commands +``` + +No Node.js? Use curl instead (everything after `-s --` is passed through): + +```sh +curl -fsSL https://raw.githubusercontent.com/tomgrv/devcontainer-features/develop/setup.sh | sh -s -- add gitutils +``` + +Set `DEVCONTAINER_FEATURES_REF` to install from another branch, tag or commit. +Features are also published to npm as `@tomgrv/devcontainer-features-`. + +## Let an agent set it up -An MCP server under [`.mcp/`](./.mcp/README.md) lets an agent list features, read their docs, and get the exact setup command — so it can bootstrap another repo's dev environment without crawling this README by hand. +An [MCP server](./.mcp/README.md) lets an AI agent list the features, read their +docs and get the exact setup command for another repository. ## Contributing -If you have a feature that you would like to add to this repository, please open an issue or submit a pull request. +Open an issue or a pull request against `develop`. Commit and PR title rules: +[`CLAUDE.md`](./CLAUDE.md). ## License -This repository is licensed under the [MIT License](./LICENSE). +[MIT](./LICENSE). From edac4ad18baf0e7342ad436344c59628837d7595 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 23 Oct 2026 16:56:52 +0000 Subject: [PATCH 2/2] =?UTF-8?q?docs(devcontainer-features-ai-coding):=20?= =?UTF-8?q?=F0=9F=93=9D=20add=20README=20conventions=20instruction?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01YG4X8TdddFmqXDN6Exw4cb --- .agents/instructions/readme.instructions.md | 1 + .github/instructions/readme.instructions.md | 1 + .../instructions/readme.instructions.md | 24 +++++++++++++++++++ .../instructions/readme.instructions.md | 1 + 4 files changed, 27 insertions(+) create mode 120000 .agents/instructions/readme.instructions.md create mode 120000 .github/instructions/readme.instructions.md create mode 100644 src/ai-coding/stubs/.agents/instructions/readme.instructions.md create mode 120000 src/ai-coding/stubs/.github/instructions/readme.instructions.md diff --git a/.agents/instructions/readme.instructions.md b/.agents/instructions/readme.instructions.md new file mode 120000 index 00000000..069bd80a --- /dev/null +++ b/.agents/instructions/readme.instructions.md @@ -0,0 +1 @@ +../../src/ai-coding/stubs/.agents/instructions/readme.instructions.md \ No newline at end of file diff --git a/.github/instructions/readme.instructions.md b/.github/instructions/readme.instructions.md new file mode 120000 index 00000000..2cb3a7fc --- /dev/null +++ b/.github/instructions/readme.instructions.md @@ -0,0 +1 @@ +../../.agents/instructions/readme.instructions.md \ No newline at end of file diff --git a/src/ai-coding/stubs/.agents/instructions/readme.instructions.md b/src/ai-coding/stubs/.agents/instructions/readme.instructions.md new file mode 100644 index 00000000..9d6256c0 --- /dev/null +++ b/src/ai-coding/stubs/.agents/instructions/readme.instructions.md @@ -0,0 +1,24 @@ +--- +applyTo: '**/README.md' +--- + + + +## README Conventions + +Applies to every README in every repo of the family (`scripts`, `actions`, `devcontainer-features`, `vps`). + +### Any README (tool, action, feature, step) + +- **Consistent, coherent, simple, pragmatic.** Same section order across siblings; no repeated boilerplate; say it once. +- **Same skeleton per repo.** Title, one-line purpose, `Usage`/`Inputs`/`Options`, `Outputs`/`Environment variables`, `Dependencies`, `Tests`, `Example`. Keep what the siblings have, add what they lack. +- **Facts come from the code.** Usage and options from the script's `-h` or `zz-args` spec, inputs and outputs from `action.yml`, options and defaults from `devcontainer-feature.json`, variables from `package.json` `config`. When code and README disagree, fix the README. +- **Header and format.** First line ``; run `prettier` on the file before committing (4-space indent in lists). +- **Link, don't duplicate.** Document a tool once, in its own README; other READMEs link to it. + +### Root README + +- **User oriented, current usage only.** The first screen gets a reader from zero to a working install or run: what it is, a copy-paste quick start, then a catalog of what is available with one line each. +- **Exclude** past decisions, legacy flags and layouts, migration notes, "why we did it this way", internal design, test counts and release plumbing. Those belong in `UPGRADING.md`, `CHANGELOG.md` or `docs/`. +- **Keep** only what a user needs next: inputs they must provide, how to choose or remove parts, how to verify it worked, troubleshooting, and a short Contributing section (how to run tests, which branch to target). +- **Order:** purpose, quick start, catalog, how-to sections, troubleshooting, contributing, license. diff --git a/src/ai-coding/stubs/.github/instructions/readme.instructions.md b/src/ai-coding/stubs/.github/instructions/readme.instructions.md new file mode 120000 index 00000000..2cb3a7fc --- /dev/null +++ b/src/ai-coding/stubs/.github/instructions/readme.instructions.md @@ -0,0 +1 @@ +../../.agents/instructions/readme.instructions.md \ No newline at end of file