git:20260717.008f8cd to git:20260717.5791e4f

11 added, 0 removed. Audit A to A.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is an **agent skills repository** — 9 self-contained skills that teach an AI coding agent (Claude Code/Cowork, Codex, Cursor, OpenCode, or any agent supporting the skills format) how to do one software-delivery job well. It is not an application: no root build system, no package manager, no top-level test suite. Individual skills ship their own helper scripts.

`README.md` is the authoritative human catalogue — it lists all 9 skills grouped by delivery phase (Bid/Discover/Design, Build, Review/Verify, Maintain, Communicate/Deliver, Measure). Read it before assuming what a skill does.

## Skill Anatomy

Each skill lives in its own top-level directory and follows the same shape:

- `SKILL.md` — the authoritative skill definition the agent loads. Changing it directly changes agent behavior when the skill triggers.

- `README.md` — human documentation (where present).

- `references/` — checklists, catalogues, templates the skill loads on demand.

- `agents/` — sub-agent definitions, for skills that fan out work (`research-plan-implement`, `code-review-expert`).

- `scripts/` — helper scripts the skill runs instead of improvising.

- `tests/` — fixture generators (e.g. `make_fixtures.py` in `agent-insights`).

### SKILL.md frontmatter

YAML frontmatter carries `name`, `description` (the trigger text — the agent matches user requests against it), and `metadata.version`. Some skills add `blob_files:` listing binary assets shipped with the skill.

## Versioning invariant

Two places record every skill's version and must stay in sync:

1. `metadata.version` in the skill's `SKILL.md` frontmatter.

2. The skill's entry in [versions.json](versions.json) (the latest-version manifest).

When you change a skill's behavior, bump both. `versions.json` is how an installed copy checks whether it is current.

+ ## Plugin distribution

+ The repo doubles as a Claude Code plugin marketplace. Two manifests live in `.claude-plugin/` (see the [plugin-marketplaces guide](https://code.claude.com/docs/en/plugin-marketplaces)):

+ - `marketplace.json` — catalog `ai-sdlc` with one plugin entry, `ai-sdlc-skills`. It uses `source: "./"` plus an explicit `skills` array listing all 9 skill directories, rather than the default `skills/` scan.

+ - `plugin.json` — plugin metadata (author, homepage, license). It carries no `version` on purpose: the plugin is git-hosted and actively developed, so every commit counts as a new version (SHA-driven updates). Adding a pinned `version` means you must bump it on every release or installed copies never update — hence the validator's no-version warning is expected.

+ Because the entry uses an explicit `skills` list, **adding or removing a skill means editing the `skills` array in `marketplace.json`** — a new top-level skill directory won't ship through the plugin until it's listed there. This is a third sync point on top of the two in the versioning invariant, but only for add/remove, not version bumps.

+ Validate manifest changes with `claude plugin validate .` from the repo root. The no-version warning is expected; treat anything else as a real error.

## Scripts

Several skills carry real helper scripts — the repo is not script-free:

- **Python** — `agent-insights/scripts/agent_insights.py`, `declawed/scripts/scan.py`, `research-plan-implement/scripts/spec_metadata.sh` (git metadata for frontmatter), and the `architecture-diagram/scripts/` pair (`build_gallery.py` regenerates the style gallery, `html_to_png.py` renders a diagram to PNG via a headless browser).

Skills declare no dependency manifests (no root `requirements.txt` / `package.json`) — scripts rely on the interpreter's standard library.

## Repository conventions

- **`*-workspace/` directories** (e.g. `agent-insights-workspace/`, `gap-analysis-workspace/`) are gitignored skill-creator evaluation workspaces. They are not skills — don't document, ship, or edit them as such.

- **`*.zip`** files are packaged skills (gitignored) for drag-and-drop into the Claude desktop app.

- **`assets/`** holds shared repo assets (the README hero diagram + its HTML source).

## Key patterns across skills

- **Approval gates** — multi-stage skills (`spec-coding`, `research-plan-implement`) require human approval between phases; the agent must not run ahead.

- **Sub-agents** — `research-plan-implement` fans out six specialized agents (codebase-locator/-analyzer/-pattern-finder, thoughts-locator/-analyzer, web-search-researcher) for parallel investigation.

- **Frequent Intentional Compaction (FIC)** — `research-plan-implement` front-loads understanding into markdown artifacts that carry context across sessions instead of bloating the conversation.

- **Output artifacts** — skills produce structured markdown/HTML (specs, plans, gap registers, reports) as the durable handoff between phases and sessions.

- **Local-only data** — the Measure skill (`agent-insights`) reads local session logs and emits local output; it sends nothing anywhere.

## Editing Guidelines

- `SKILL.md` is the source of truth for behavior — edit it deliberately and bump the version in both places.

- Keep `references/` documents focused and structured; skills load them as context.

- When editing a skill, mirror its existing conventions rather than the repo average — skills vary intentionally (some fan out sub-agents, some run scripts, some are pure prose).