@everydaydevopsio/ballast 3.0.4 → 3.2.0

package/README.md

@@ -1,17 +1,37 @@
 # Ballast
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![CI](https://github.com/everydaydevopsio/ballast/actions/workflows/test.yml/badge.svg)](https://github.com/everydaydevopsio/ballast/actions/workflows/test.yml)
+[![Lint](https://github.com/everydaydevopsio/ballast/actions/workflows/lint.yaml/badge.svg)](https://github.com/everydaydevopsio/ballast/actions/workflows/lint.yaml)
+[![Release](https://github.com/everydaydevopsio/ballast/actions/workflows/publish.yml/badge.svg)](https://github.com/everydaydevopsio/ballast/actions/workflows/publish.yml)
+[![License](https://img.shields.io/github/license/everydaydevopsio/ballast)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/everydaydevopsio/ballast)](https://github.com/everydaydevopsio/ballast/releases)
+[![npm version](https://img.shields.io/npm/v/@everydaydevopsio/ballast.svg)](https://www.npmjs.com/package/@everydaydevopsio/ballast)
+[![npm downloads](https://img.shields.io/npm/dm/@everydaydevopsio/ballast.svg)](https://www.npmjs.com/package/@everydaydevopsio/ballast)
 
-CLI to install TypeScript AI agent rules for **Cursor**, **Claude Code**, and **OpenCode**. One package, one command—pick your platform and which agents to install.
+CLI to install TypeScript AI agent rules for **Cursor**, **Claude Code**, **OpenCode**, and **Codex**. One package, one command—pick your platform and which agents to install.
+
+## Prerequisites
+
+- [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager)
+
+After cloning the repo, install and use the project's Node version:
+
+```bash
+nvm install   # installs the version from .nvmrc
+nvm use       # switches to it (or run `nvm install` which does both)
+```
+
+Then install dependencies: `pnpm install` (or `npm install` / `yarn`).
 
 ## Agents
 
-| Agent             | Description                                                              |
-| ----------------- | ------------------------------------------------------------------------ |
-| **linting**       | ESLint, Prettier, Husky, lint-staged, GitHub Actions (full instructions) |
-| **local-dev**     | Local dev environment setup, DX, documentation (placeholder outline)     |
-| **cicd**          | CI/CD pipelines, quality gates, deployment (placeholder outline)         |
-| **observability** | Logging, tracing, metrics, SLOs (placeholder outline)                    |
+| Agent             | Description                                                                                      |
+| ----------------- | ------------------------------------------------------------------------------------------------ |
+| **linting**       | ESLint, Prettier, Husky, lint-staged, GitHub Actions (full instructions)                         |
+| **local-dev**     | Local dev environment (nvm, Docker, env), license setup (MIT default), MCP (optional)            |
+| **cicd**          | CI/CD pipelines, quality gates, deployment (placeholder outline)                                 |
+| **observability** | Logging, tracing, metrics, SLOs (placeholder outline)                                            |
+| **logging**       | Pino + Fluentd (Node/Next.js API), pino-browser to /api/logs, window.onerror, unhandledrejection |
 
 ## Using the agents
 
@@ -20,9 +40,10 @@ Once installed, rule files are loaded automatically by your AI platform (Cursor,
 | Agent             | How to use it                                                                                                                                                                        |
 | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **linting**       | In any session: _"Help me set up linting for this project"_ or _"Fix lint errors per the linting rules."_ The agent will add ESLint, Prettier, Husky, lint-staged, and CI workflows. |
-| **local-dev**     | Ask for help with local dev environment, DX, or documentation (placeholder).                                                                                                         |
+| **local-dev**     | Ask for help with local dev environment, license setup (LICENSE, package.json, README), or optional MCP integration.                                                                 |
 | **cicd**          | Ask for help with CI/CD pipelines, quality gates, or deployment (placeholder).                                                                                                       |
 | **observability** | Ask for help with logging, tracing, metrics, or SLOs (placeholder).                                                                                                                  |
+| **logging**       | Ask for help with centralized logging: Pino + Fluentd for server, pino-browser to /api/logs for console, exceptions, window.onerror, unhandledrejection.                             |
 
 ## Installation
 
@@ -48,7 +69,7 @@ npx ballast install
 
 You’ll be prompted for:
 
-1. **AI platform**: `cursor`, `claude`, or `opencode`
+1. **AI platform**: `cursor`, `claude`, `opencode`, or `codex`
 2. **Agents**: comma-separated (e.g. `linting, local-dev`) or `all`
 
 Your choices are saved to `.rulesrc.json`. Future runs reuse them (non-interactive).
@@ -67,6 +88,7 @@ npx ballast install --target cursor --agent linting --force
 
 # Non-interactive (CI): require --target and --agent/--all if no .rulesrc.json
 npx ballast install --yes --target cursor --agent linting
+ballast install --yes --target codex --all
 ```
 
 ### CI / non-interactive
@@ -94,6 +116,9 @@ Rules are written under your project root:
 | Cursor   | `.cursor/rules/` | `<agent>.mdc` |
 | Claude   | `.claude/rules/` | `<agent>.md`  |
 | OpenCode | `.opencode/`     | `<agent>.md`  |
+| Codex    | `.codex/rules/`  | `<agent>.md`  |
+
+Codex installs a root `AGENTS.md` that references the `.codex/rules/` files so Codex CLI and Codex app can load the same guidance.
 
 ## Overwrite policy
 

package/agents/cicd/templates/codex-header.md

@@ -0,0 +1,7 @@
+# CI/CD Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help design and maintain CI/CD pipelines for TypeScript/JavaScript projects.
+
+---

package/agents/linting/templates/codex-header.md

@@ -0,0 +1,7 @@
+# TypeScript Linting Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules provide TypeScript linting setup instructions following Everyday DevOps best practices from https://www.markcallen.com/typescript-linting/
+
+---

package/agents/local-dev/content-badges.md

@@ -0,0 +1,83 @@
+# README Badges
+
+When setting up or improving project documentation, add standard badges near the top of `README.md` to provide quick visibility into CI status, releases, license, and (for npm packages) npm registry info.
+
+## Your Responsibilities
+
+1. **Add badges at the top of README.md**
+   - Place badges immediately after the main title (or project description), before the first heading.
+   - Use one line of badges, separated by spaces, for a compact layout.
+   - Replace `OWNER/REPO` with the actual GitHub org/user and repository name (e.g. `markcallen/cache-cleaner`).
+   - Replace `PACKAGE_NAME` with the npm package name from `package.json` when adding npm badges.
+
+2. **Include standard badges**
+   - **CI** — links to the CI workflow (e.g. `ci.yml` or `lint.yml`).
+   - **Release** — links to the release/publish workflow (e.g. `release.yml` or `publish.yml`).
+   - **License** — links to the `LICENSE` file.
+   - **GitHub Release** — links to the releases page.
+
+3. **For npm packages**
+   - If the project has a `package.json` with `name` and is published to npm, add npm badges:
+     - **npm version** — shows the latest published version.
+     - **npm downloads** — shows weekly or monthly download count (optional but recommended).
+
+## Badge Markdown Examples
+
+### GitHub Actions (CI and Release)
+
+Use the workflow filename that exists in `.github/workflows/` (e.g. `ci.yml`, `release.yml`, `publish.yml`):
+
+```markdown
+[![CI](https://github.com/OWNER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/ci.yml)
+[![Release](https://github.com/OWNER/REPO/actions/workflows/release.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/release.yml)
+```
+
+If the workflow is named `publish.yml` instead of `release.yml`, use:
+
+```markdown
+[![Release](https://github.com/OWNER/REPO/actions/workflows/publish.yml/badge.svg)](https://github.com/OWNER/REPO/actions/workflows/publish.yml)
+```
+
+### License and GitHub Release
+
+```markdown
+[![License](https://img.shields.io/github/license/OWNER/REPO)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/OWNER/REPO)](https://github.com/OWNER/REPO/releases)
+```
+
+### npm (for published packages)
+
+```markdown
+[![npm version](https://img.shields.io/npm/v/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
+[![npm downloads](https://img.shields.io/npm/dm/PACKAGE_NAME.svg)](https://www.npmjs.com/package/PACKAGE_NAME)
+```
+
+## Complete Example (GitHub + npm)
+
+```markdown
+# Project Name
+
+[![CI](https://github.com/markcallen/cache-cleaner/actions/workflows/ci.yml/badge.svg)](https://github.com/markcallen/cache-cleaner/actions/workflows/ci.yml)
+[![Release](https://github.com/markcallen/cache-cleaner/actions/workflows/release.yml/badge.svg)](https://github.com/markcallen/cache-cleaner/actions/workflows/release.yml)
+[![License](https://img.shields.io/github/license/markcallen/cache-cleaner)](LICENSE)
+[![GitHub Release](https://img.shields.io/github/v/release/markcallen/cache-cleaner)](https://github.com/markcallen/cache-cleaner/releases)
+[![npm version](https://img.shields.io/npm/v/cache-cleaner.svg)](https://www.npmjs.com/package/cache-cleaner)
+[![npm downloads](https://img.shields.io/npm/dm/cache-cleaner.svg)](https://www.npmjs.com/package/cache-cleaner)
+
+Project description...
+```
+
+## Implementation Order
+
+1. Determine the GitHub `OWNER/REPO` (from git remote, package.json repository field, or user input).
+2. List workflows in `.github/workflows/` to identify CI and release workflow filenames.
+3. Check `package.json` for `name` and whether the package is published to npm (optional: check npm registry).
+4. Add badges at the top of `README.md`, after the title and before the first `##` heading.
+5. Use the correct workflow filenames; do not assume `ci.yml` or `release.yml` if different names exist.
+
+## When to Apply
+
+- When creating a new project with a README.
+- When a README lacks badges at the top.
+- When adding CI or release workflows and the README does not yet link to them.
+- When publishing an npm package and the README does not show npm badges.

package/agents/local-dev/content-env.md

@@ -0,0 +1,189 @@
+# Local Development Environment Agent
+
+You are a local development environment specialist for TypeScript/JavaScript projects.
+
+## Goals
+
+- **Reproducible environments**: Help set up and document local dev setup (Node version, env vars, Docker Compose, dev scripts) so anyone can run the project with minimal friction.
+- **Developer experience**: Recommend and configure tooling (debugging, hot reload, env validation) and conventions (branch naming, commit hooks) that keep local dev fast and consistent.
+- **Documentation**: Keep README and runbooks (e.g. "Getting started", "Troubleshooting") in sync with the actual setup so new contributors can self-serve.
+
+## Scope
+
+- Local run scripts, env files (.env.example), and optional containerized dev (e.g. Docker Compose for services).
+- Version managers (nvm, volta) and required Node/npm versions.
+- Pre-commit or pre-push hooks that run tests/lint locally before pushing.
+
+---
+
+## Node Version Management (nvm)
+
+When setting up or working on Node.js/TypeScript projects, use **nvm** (Node Version Manager) to ensure consistent Node versions across developers and environments.
+
+### Your Responsibilities
+
+1. **Create or update `.nvmrc`**
+   - If the project has no `.nvmrc`, create one specifying the Node version.
+   - Default to `lts/*` if no version is already specified (e.g. in `package.json` engines, existing `.nvmrc`, or CI config).
+   - If a specific version is already used elsewhere, match it (e.g. `22`, `20`, `lts/hydrogen`).
+
+2. **Use `.nvmrc` in the project**
+   - Instruct developers to run `nvm use` (or `nvm install` if the version is not yet installed) when entering the project directory.
+   - Consider adding shell integration (e.g. `direnv` with `use nvm`, or `.nvmrc` auto-switching in zsh/bash) if the team prefers automatic switching.
+
+3. **Update the README**
+   - Add a "Prerequisites" or "Getting started" subsection that instructs new contributors to:
+     1. Install nvm (e.g. `curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash` or the latest from https://github.com/nvm-sh/nvm).
+     2. Run `nvm install` (or `nvm use`) right after cloning the repo so the correct Node version is active before `pnpm install` / `npm install` / `yarn install`.
+
+### Example README Addition
+
+````markdown
+## Prerequisites
+
+- [nvm](https://github.com/nvm-sh/nvm) (Node Version Manager)
+
+After cloning the repo, install and use the project's Node version:
+
+```bash
+nvm install   # installs the version from .nvmrc
+nvm use       # switches to it (or run `nvm install` which does both)
+```
+
+Then install dependencies: `pnpm install` (or `npm install` / `yarn`).
+````
+
+### Key Commands
+
+- `nvm install` — installs the version from `.nvmrc` (or `lts/*` if `.nvmrc` is missing)
+- `nvm use` — switches the current shell to the version in `.nvmrc`
+- `nvm install lts/*` — installs the current LTS version
+
+### When to Apply
+
+- When creating a new Node/TypeScript project.
+- When a project lacks `.nvmrc` or README setup instructions.
+- When the README does not mention nvm or Node version setup after cloning.
+
+---
+
+## Dockerfile for Local Development (Node.js / TypeScript)
+
+When the user wants a Dockerfile and containerized local development for a Node.js or TypeScript app, follow the Everyday DevOps approach from https://www.markcallen.com/dockerfile-for-typescript/
+
+### Your Responsibilities
+
+1. **Create a production-style Dockerfile**
+   - Use a Node LTS image (e.g. `node:22-bookworm`).
+   - Set `WORKDIR /app`.
+   - Copy only `package.json` and lockfile (`yarn.lock`, `pnpm-lock.yaml`, or `package-lock.json`) first.
+   - Install dependencies with frozen lockfile and `--ignore-scripts` (e.g. `yarn install --frozen-lockfile --ignore-scripts`, or `pnpm install --frozen-lockfile --ignore-scripts`, or `npm ci --ignore-scripts`).
+   - Copy the rest of the application.
+   - Run the build script (e.g. `yarn build` / `pnpm run build`).
+   - Set `CMD` to start the app (e.g. `node dist/index.js` or `npm start`).
+
+2. **Add a .dockerignore**
+   - Exclude: `node_modules`, `dist`, `.env`, `.vscode`, `*.log`, `.git`, and other non-build artifacts so the Docker build context stays small.
+
+3. **Create docker-compose.yml for local development**
+   - Use `build: .` for the app service.
+   - For CLI apps, set `tty: true` so the container doesn't exit immediately.
+   - Use Compose's `develop.watch` so code changes are reflected without full rebuilds:
+     - `action: sync+restart` for source directories (e.g. `src/`) so edits sync in and the process restarts.
+     - `action: rebuild` for `package.json` (and lockfile) so dependency changes trigger an image rebuild.
+   - Set `command` to the dev script (e.g. `yarn dev`, `pnpm run dev`, or `tsx src/index.ts`) so the app runs with watch/hot reload inside the container.
+
+4. **Ensure package.json scripts**
+   - `build`: compile/bundle (e.g. `rimraf ./dist && tsc`, or project equivalent).
+   - `start`: run the built app (e.g. `node dist/index.js`).
+   - `dev`: run for local development with watch (e.g. `tsx src/index.ts` or `ts-node-dev`, etc.).
+
+### Implementation Order
+
+1. Check for existing Dockerfile and docker-compose files; do not overwrite without user confirmation (or `--force`-style intent).
+2. Identify package manager (yarn, pnpm, npm) and lockfile name.
+3. Create `.dockerignore` with appropriate exclusions.
+4. Create `Dockerfile` with multi-stage or single-stage build as above.
+5. Create or update `docker-compose.yml` with `develop.watch` and dev `command`.
+6. Verify `package.json` has `build`, `start`, and `dev` scripts; suggest additions if missing.
+7. Document in README: how to `docker compose build`, `docker compose up --watch`, and optional production `docker build` / `docker run`.
+
+### Key Snippets
+
+**Dockerfile (yarn example):**
+
+```dockerfile
+FROM node:22-bookworm
+
+WORKDIR /app
+
+COPY package.json yarn.lock ./
+RUN yarn install --frozen-lockfile --ignore-scripts
+
+COPY . .
+RUN yarn build
+
+CMD [ "yarn", "start" ]
+```
+
+**Dockerfile (pnpm example):**
+
+```dockerfile
+FROM node:22-bookworm
+
+WORKDIR /app
+
+RUN corepack enable && corepack prepare pnpm@latest --activate
+COPY package.json pnpm-lock.yaml ./
+RUN pnpm install --frozen-lockfile --ignore-scripts
+
+COPY . .
+RUN pnpm run build
+
+CMD [ "pnpm", "start" ]
+```
+
+**.dockerignore:**
+
+```
+node_modules
+dist
+.env
+.vscode
+*.log
+.git
+```
+
+**docker-compose.yml (with watch):**
+
+```yaml
+services:
+  app:
+    build: .
+    tty: true # omit or set false for long-running servers (e.g. Express)
+    develop:
+      watch:
+        - action: sync+restart
+          path: src/
+          target: /app/src
+        - action: rebuild
+          path: package.json
+    command: yarn dev
+```
+
+Use `pnpm run dev` or `npm run dev` in `command` if the project uses that package manager. Adjust `path`/`target` if the app uses a different layout (e.g. `app/` instead of `src/`).
+
+### Important Notes
+
+- Keep the Docker build context small: always use a `.dockerignore` and copy dependency manifests before copying the full tree.
+- Use `--frozen-lockfile` (yarn/pnpm) or `npm ci` so production and CI builds are reproducible.
+- For local dev, `develop.watch` with `sync+restart` on source dirs avoids full image rebuilds on every code change; reserve `rebuild` for dependency/manifest changes.
+- For web apps (e.g. Express), you may omit `tty: true` and expose a port with `ports: ["3000:3000"]` (or the app's port).
+- If the project has no `dev` script, suggest adding one (e.g. using `tsx`, `ts-node-dev`, or `node --watch`) so `docker compose up --watch` is useful.
+
+### When Completed
+
+1. Summarize what was created or updated (Dockerfile, .dockerignore, docker-compose.yml, and any script changes).
+2. Tell the user how to build and run: `docker compose build`, then `docker compose up --watch` for local development.
+3. Mention that editing files under the watched path will sync and restart the service, and changing `package.json` will trigger a rebuild.
+4. Optionally suggest adding a short "Docker" or "Local development" section to the README with these commands.

package/agents/local-dev/content-license.md

@@ -0,0 +1,94 @@
+# License Setup for Projects
+
+When setting up or working on projects, ensure proper license configuration for legal clarity and reuse.
+
+## Default Behavior
+
+**If no license is specified**, use the **MIT License**. Projects can override this in `AGENTS.md` or `CLAUDE.md` (see Configuration below).
+
+## Your Responsibilities
+
+1. **Create or update `LICENSE`**
+   - If the project has no `LICENSE` file, create one.
+   - Use the license specified in project docs (`AGENTS.md`, `CLAUDE.md`) if present; otherwise use MIT.
+   - For MIT, include the standard MIT License text with the current year and copyright holder (e.g. from `package.json` author or a placeholder).
+
+2. **Update `package.json`**
+   - Ensure the `license` field is set (e.g. `"license": "MIT"`).
+   - If `package.json` exists but has no `license` field, add it.
+   - Use [SPDX identifiers](https://spdx.org/licenses/) (e.g. `MIT`, `Apache-2.0`, `ISC`).
+
+3. **Reference LICENSE in README**
+   - Add a "License" section at the end of `README.md` that references the `LICENSE` file.
+   - Example: `MIT License - see [LICENSE](LICENSE) file for details.`
+
+## MIT License Template
+
+```
+MIT License
+
+Copyright (c) <YEAR> <COPYRIGHT HOLDER>
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+Replace `<YEAR>` with the current year and `<COPYRIGHT HOLDER>` with the author/org (e.g. from `package.json` author).
+
+## Example README Addition
+
+```markdown
+## License
+
+MIT License - see [LICENSE](LICENSE) file for details.
+```
+
+## Example package.json Addition
+
+```json
+{
+  "license": "MIT"
+}
+```
+
+## Configuration: Override Default License
+
+Projects may specify a non-MIT license in `AGENTS.md` or `CLAUDE.md`:
+
+```markdown
+## License
+
+Default license for this project: Apache-2.0 (or ISC, BSD-3-Clause, etc.)
+```
+
+When such a section exists, use the specified license instead of MIT. If both files define a license, prefer `AGENTS.md` (it is agent-facing and typically more authoritative for automation).
+
+## Implementation Order
+
+1. Check `AGENTS.md` and `CLAUDE.md` for a license override.
+2. If none, use MIT.
+3. Check if `LICENSE` exists; if not, create it with the chosen license text.
+4. Check `package.json` for the `license` field; add or update if missing.
+5. Check `README.md` for a License section at the end; add one if missing, referencing `[LICENSE](LICENSE)`.
+
+## When to Apply
+
+- When creating a new project.
+- When a project lacks a `LICENSE` file.
+- When `package.json` has no `license` field.
+- When `README.md` does not reference the LICENSE file at the end.

package/agents/local-dev/content-mcp.md

@@ -0,0 +1,64 @@
+# Optional: GitHub and Issues MCP Servers
+
+When the user has **GitHub MCP** and/or **issues MCP** (Jira, Linear, or GitHub Issues) servers enabled, use them to support local development workflow and context.
+
+## When to Use This Rule
+
+- The user asks for a summary of open work (PRs, issues, Jira/Linear items).
+- The user wants to correlate code changes with tickets or PRs.
+- The user is starting work and needs context from assigned or in-progress items.
+
+## GitHub MCP
+
+If the **GitHub MCP** server is available:
+
+- **Pull requests**: List or summarize open PRs for the current repo (or org). Help the user triage, review, or land PRs.
+- **Repos and orgs**: Use repo/org context when the user asks about “my PRs” or “our open PRs.”
+- **Branches and commits**: When relevant to local dev, use GitHub MCP to check branch status, CI status, or linked issues.
+
+Do not assume the server is present; only use it when it is configured and the user’s request fits (e.g. “summarize my PRs”, “what’s open in this repo?”).
+
+## Issues MCP (Jira / Linear / GitHub Issues)
+
+If an **issues MCP** server is available (Jira, Linear, or GitHub Issues):
+
+- **Assigned work**: When the user asks “what am I working on?” or “my issues”, use the issues MCP to list items assigned to them (and optionally filter by board, team, or project).
+- **Sprint / cycle / milestone**: For Jira (board/sprint) or Linear (team/cycle), summarize current sprint or cycle work when the user asks.
+- **Correlation with code**: When the user mentions a ticket ID (e.g. `PROJ-123`, Linear issue key), use the issues MCP to fetch details and relate them to branches or PRs if helpful.
+
+Configuration (e.g. which board, team, or filters) is typically stored in project docs (e.g. `CLAUDE.md`, `AGENTS.md`) or a config file (e.g. `work_summary` YAML). Prefer not to overwrite that config; use it to scope queries.
+
+## Scope
+
+- **Optional**: This rule applies only when the corresponding MCP servers are enabled. Do not prompt the user to install MCPs; only use them when already available.
+- **Local-dev focus**: Use these MCPs to support _local development_ context (what to work on next, PR/issue context while coding), not as a general “work summary” agent. Defer to project-specific docs for full work-summary or reporting behavior.
+- **Documentation**: If you add or change how MCPs are used, suggest updating README or runbooks (e.g. “Getting started”, “Troubleshooting”) so others know which MCPs are expected for this project.
+
+## Configuration Reference
+
+Projects may document MCP usage in a structure like:
+
+```yaml
+work_summary:
+  mcp_tools:
+    github: github
+    jira: jira # optional
+    linear: linear # optional
+  sources:
+    pull_requests: true
+    github_issues:
+      enabled: false
+      scope: { mode: repos, orgs: [], repos: [] }
+      filters: { assigned_to_me: true, labels: [] }
+    jira:
+      enabled: false
+      board: ''
+      only_assigned_to_me: true
+    linear:
+      enabled: false
+      team: ''
+      view: cycle
+      only_assigned_to_me: true
+```
+
+Respect such configuration when querying; use it to scope lists (e.g. “assigned to me”, specific board/team) rather than inventing defaults.

package/agents/local-dev/templates/claude-header-badges.md

@@ -0,0 +1,5 @@
+# Local Development: README Badges
+
+Add standard badges (CI, Release, License, GitHub Release; plus npm for published packages) to the top of README.md.
+
+---

package/agents/local-dev/templates/claude-header-license.md

@@ -0,0 +1,5 @@
+# Local Development: License Setup
+
+Ensure proper license configuration (LICENSE file, package.json, README reference). Default: MIT. Overridable in AGENTS.md or CLAUDE.md.
+
+---

package/agents/local-dev/templates/claude-header-mcp.md

@@ -0,0 +1,5 @@
+# Local Development: GitHub and Issues MCP (Optional)
+
+Use GitHub MCP and/or issues MCP (Jira, Linear, GitHub Issues) when available to support local development context. Only apply when these MCP servers are enabled.
+
+---

package/agents/local-dev/templates/claude-header.md

@@ -1,5 +1,5 @@
 # Local Development Environment Rules
 
-These rules help set up and maintain a consistent local development environment for TypeScript/JavaScript projects.
+These rules help set up and maintain a consistent local development environment for TypeScript/JavaScript projects, including Dockerfile and Docker Compose for local development following https://www.markcallen.com/dockerfile-for-typescript/
 
 ---

package/agents/local-dev/templates/codex-header-badges.md

@@ -0,0 +1,7 @@
+# Local Development: README Badges
+
+These rules are intended for Codex (CLI and app).
+
+Add standard badges (CI, Release, License, GitHub Release; plus npm for published packages) to the top of README.md.
+
+---

package/agents/local-dev/templates/codex-header-license.md

@@ -0,0 +1,7 @@
+# Local Development: License Setup
+
+These rules are intended for Codex (CLI and app).
+
+Ensure proper license configuration (LICENSE file, package.json, README reference). Default: MIT. Overridable in AGENTS.md or CLAUDE.md.
+
+---

package/agents/local-dev/templates/codex-header-mcp.md

@@ -0,0 +1,7 @@
+# Local Development: GitHub and Issues MCP (Optional)
+
+These rules are intended for Codex (CLI and app).
+
+Use GitHub MCP and/or issues MCP (Jira, Linear, GitHub Issues) when available to support local development context. Only apply when these MCP servers are enabled.
+
+---

package/agents/local-dev/templates/codex-header.md

@@ -0,0 +1,7 @@
+# Local Development Environment Rules
+
+These rules are intended for Codex (CLI and app).
+
+These rules help set up and maintain a consistent local development environment for TypeScript/JavaScript projects, including Dockerfile and Docker Compose for local development following https://www.markcallen.com/dockerfile-for-typescript/
+
+---

package/agents/local-dev/templates/cursor-frontmatter-badges.yaml

@@ -0,0 +1,8 @@
+---
+description: 'Add standard badges (CI, Release, License, GitHub Release, npm) to the top of README.md'
+alwaysApply: false
+globs:
+  - 'README*'
+  - '.github/workflows/*.yml'
+  - 'package.json'
+---

package/agents/local-dev/templates/cursor-frontmatter-env.yaml

@@ -0,0 +1,11 @@
+---
+description: 'Local development environment specialist - reproducible dev setup, DX, and documentation'
+alwaysApply: false
+globs:
+  - 'package.json'
+  - 'README*'
+  - '.nvmrc'
+  - '.env*'
+  - 'docker-compose*.yml'
+  - 'Dockerfile*'
+---

package/agents/local-dev/templates/cursor-frontmatter-license.yaml

@@ -0,0 +1,10 @@
+---
+description: 'License setup - ensure LICENSE file, package.json license field, and README reference (default MIT; overridable in AGENTS.md/CLAUDE.md)'
+alwaysApply: false
+globs:
+  - 'LICENSE'
+  - 'package.json'
+  - 'README*'
+  - '**/AGENTS.md'
+  - '**/CLAUDE.md'
+---

package/agents/local-dev/templates/cursor-frontmatter-mcp.yaml

@@ -0,0 +1,10 @@
+---
+description: 'Optional: use GitHub MCP and issues MCP (Jira/Linear/GitHub) for local-dev context'
+alwaysApply: false
+globs:
+  - 'package.json'
+  - 'README*'
+  - '.env*'
+  - '**/CLAUDE.md'
+  - '**/AGENTS.md'
+---

package/agents/local-dev/templates/opencode-frontmatter-badges.yaml

@@ -0,0 +1,16 @@
+---
+description: Add standard badges (CI, Release, License, GitHub Release, npm) to the top of README.md
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.2
+tools:
+  write: true
+  edit: true
+  bash: true
+  read: true
+  glob: true
+  grep: true
+permission:
+  bash:
+    '*': ask
+---