From 6945ef8c2fae5807d5c39329dc961c5c0e9e143b Mon Sep 17 00:00:00 2001 From: rdwj Date: Mon, 4 May 2026 12:26:09 -0500 Subject: [PATCH] docs: Document patch-for-agents in CLAUDE.md and README, add v0.9.0 changelog Updates the "Current Status" line in CLAUDE.md to reflect that `patch` is type-aware and lists the per-type subcommand surface. Restructures the README's "Patch Commands" section into shared (`check`, `all`) followed by per-type category tables, and notes that MCP-only and agent-only subcommands are gated on the project's `template.type`. Adds the v0.9.0 changelog block. Assisted-by: Claude Code (Opus 4.7) --- CLAUDE.md | 7 +++++- README.md | 66 ++++++++++++++++++++++++++++--------------------------- 2 files changed, 40 insertions(+), 33 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 36ff07a..15a0fc2 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -6,7 +6,12 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co **fips-agents-cli** is a Python-based CLI tool for scaffolding FIPS-compliant AI agent projects. It scaffolds MCP (Model Context Protocol) servers and AI agent projects from production-ready templates, customizes them for new projects, and prepares them for immediate development use. -**Current Status:** Scaffolding commands implemented: `create mcp-server`, `create agent`, `create gateway`, `create ui`, `create sandbox`, `create model-car`. Post-scaffolding commands: `generate` (tool, resource, prompt, middleware), `patch` (check, generators, core, docs, build, all), `add` (code-executor), `vendor`. Note: `create workflow` exists in code but is not yet working. +**Current Status:** Scaffolding commands implemented: `create mcp-server`, `create agent`, `create gateway`, `create ui`, `create sandbox`, `create model-car`. Post-scaffolding commands: `generate` (tool, resource, prompt, middleware), `patch` (check, all + type-specific category subcommands — see below), `add` (code-executor), `vendor`. Note: `create workflow` exists in code but is not yet working. + +The `patch` command is type-aware via `template.type` in `.template-info`: +- **MCP server** projects expose `patch generators | core | docs | build`. +- **Agent / workflow** projects expose `patch chart | docs | build | claude`. +Running an MCP-only subcommand inside an agent project (or vice versa) exits with a clear "available categories" error. `patch check` and `patch all` work for any supported type. ## Development Commands diff --git a/README.md b/README.md index 2eab717..6bba68d 100644 --- a/README.md +++ b/README.md @@ -524,7 +524,9 @@ When using `--params` with `generate tool` or `generate prompt`, provide a JSON ### Patch Commands -The `patch` command group updates files in existing MCP server projects from the upstream template repository without overwriting your custom code. It shows interactive diffs for files that may contain customizations. +The `patch` command group updates files in existing projects from the upstream template repository without overwriting your custom code. It shows interactive diffs for files that may contain customizations. + +Supported project types: **MCP server**, **agent**, **workflow**. The available category subcommands depend on the project type — `patch` reads `template.type` from `.template-info` and surfaces a clear error if you run a category that doesn't apply (e.g. `patch generators` inside an agent project). Run these commands from within your project directory. @@ -534,47 +536,35 @@ Run these commands from within your project directory. fips-agents patch check ``` -Check for available template updates. Shows what files have changed in the template since your project was created, organized by category. - -#### `patch generators` - -```bash -fips-agents patch generators [--dry-run] -``` - -Update code generator templates (Jinja2 templates in `.fips-agents-cli/generators/`). - -#### `patch core` - -```bash -fips-agents patch core [--dry-run] -``` - -Update core infrastructure files (loaders, server bootstrap). +Check for available template updates. Shows what files have changed in the template since your project was created, organized by category. Works for any supported project type. -#### `patch docs` +#### `patch all` ```bash -fips-agents patch docs [--dry-run] +fips-agents patch all [--dry-run] [--skip-confirmation] ``` -Update documentation files and examples. - -#### `patch build` +Update every category that applies to the current project type. Prompts for confirmation before starting unless `--skip-confirmation` is passed. -```bash -fips-agents patch build [--dry-run] -``` +#### MCP server categories -Update build and deployment files (Makefile, Containerfile). +| Subcommand | Patches | +|----------------------|--------------------------------------------------------------------------| +| `patch generators` | Jinja2 templates in `.fips-agents-cli/generators/` | +| `patch core` | Core infrastructure (loaders, server bootstrap) | +| `patch docs` | Documentation files and examples | +| `patch build` | Build and deployment files (Makefile, Containerfile) | -#### `patch all` +#### Agent / workflow categories -```bash -fips-agents patch all [--dry-run] [--skip-confirmation] -``` +| Subcommand | Patches | +|----------------|-------------------------------------------------------------------------------| +| `patch chart` | Helm chart templates (`chart/templates/**`, `chart/Chart.yaml`) | +| `patch docs` | `CLAUDE.md`, `AGENTS.md`, `docs/**` | +| `patch build` | `Makefile`, `Containerfile`, `deploy.sh`, `redeploy.sh` | +| `patch claude` | Claude Code slash commands shipped with the template (`.claude/commands/**`) | -Update all patchable file categories at once. Prompts for confirmation before starting unless `--skip-confirmation` is passed. +User-customized files are never patched: for MCP this means `src/tools/`, `src/resources/`, `src/prompts/`, `src/middleware/`, `pyproject.toml`, etc. For agent/workflow it means `src/agent.py`, `agent.yaml`, `chart/values.yaml`, `src/fipsagents/**` (managed by `fips-agents vendor`), and `pyproject.toml`. All patch subcommands (except `check`) accept `--dry-run` to preview changes without modifying files. @@ -913,6 +903,18 @@ MIT License - see LICENSE file for details ## Changelog +### Version 0.9.0 + +- Feature: `fips-agents patch` now supports agent and workflow projects in addition to MCP servers (#12) +- Feature: New `patch chart` and `patch claude` subcommands for agent/workflow projects (#15) +- Feature: `.template-info` now records `template.type` and (for monorepo templates) `template.subdir` so post-scaffolding commands can route by project type (#13) +- Feature: New `find_fips_project_root()` walks up to `.template-info`, replacing the MCP-only fastmcp-dependency probe in patch commands (#14) +- Improvement: `_clone_template_for_patch()` resolves the monorepo subdir during patching, so glob/compare runs against `templates/agent-loop/` instead of the monorepo root (#16) +- Improvement: Running an MCP-only subcommand inside an agent project (or vice versa) now exits with a clear "available categories" error +- Improvement: `patch all` enumerates the project's actual category set instead of assuming MCP layout +- Backwards compat: Projects scaffolded before `template.type` existed default to `mcp-server`; no migration required +- Tests: 20 new tests in `tests/test_patch.py` covering the type-aware patch flow end-to-end against a fake-scaffolded agent project + ### Version 0.8.2 - Test: New `TestGenerateMiddlewareRealTemplate` integration test renders the real v3.x middleware Jinja2 template against each `--hook-type` and the no-flag case, with templates committed under `tests/fixtures/middleware_template/` so the suite runs offline (#3)