# CLAUDE.md — the-ai-machine

## Purpose

This repo is a **Claude Code marketplace** that hosts one or more plugins. Each plugin lives in its own folder under `plugins/<plugin-name>/` with its own `.claude-plugin/plugin.json` and component directories (`skills/`, `commands/`, `agents/`, `hooks/`).

Today the only plugin is [`plugins/machine-work/`](plugins/machine-work/), which implements the [AI Development Framework V2](https://github.com/el-frontend/software-engineering-skills/blob/main/docs/framework.md) as a set of composable skills following Anthropic's [agent-skills format](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/overview).

## Repo layout

```
the-ai-machine/
├── .claude-plugin/
│   └── marketplace.json          Catalog — lists every plugin with its git-subdir source.
├── plugins/
│   └── <plugin-name>/
│       ├── .claude-plugin/
│       │   └── plugin.json       Plugin manifest.
│       ├── skills/
│       ├── commands/
│       └── ...
├── docs/                          Marketplace-level docs (framework.md).
├── scripts/release.sh             Shared-tag release tool.
├── CLAUDE.md, README.md, RELEASING.md, CHANGELOG.md, LICENSE
```

The marketplace and the plugins use **shared tags** (`vX.Y.Z`): every release bumps every plugin to the same version and tags a single commit. See [`RELEASING.md`](RELEASING.md).

## Skill authoring conventions

When you add or edit a skill inside any plugin, mirror the structure of [`plugins/machine-work/skills/ai-driven-prd/`](plugins/machine-work/skills/ai-driven-prd/) — it is the reference implementation.

### Folder layout

```
plugins/<plugin-name>/skills/<skill-name>/
├── SKILL.md          (required — entry point)
├── prompts/          (optional — per-phase instructions)
├── templates/        (optional — scaffolds the skill fills in)
└── references/       (optional — checklists, anti-patterns, examples)
```

### SKILL.md frontmatter

Exactly two keys: `name` and `description`. The description MUST start with "Use when…" and MUST list the trigger phrases the user is likely to say.

```yaml
---
name: my-skill
description: Use when the user wants to do X. Triggers on "do X", "phrase Y", "/x Z".
---
```

### Hard rules for content

- **RFC 2119 keywords** (MUST / MUST NOT / SHOULD / MAY) in every normative statement.
- **Numbered IDs** for every requirement, AC, user story, and task. Cross-reference FR-N ↔ AC-N ↔ test name.
- **No vague adjectives.** *Fast, easy, intuitive, robust, modern, seamless* → rewrite to a quantified threshold.
- **DO NOT lists** — concrete prohibited actions, not vibes.
- **Every phase ends in a human gate.** Do not chain phases without explicit user approval.
- **Ambiguity → ASK.** Mark unfilled sections as `⚠️ NEEDS INPUT:` with the specific question. Never invent.
- **Anti-patterns file** for every skill that has hard rules.
- **Checklist file** when there is a quality gate (e.g. `references/checklist.md` with a threshold like ≥13/15).

### Tone

Prescriptive, engineering-grade. Write for an LLM with short memory and outdated training data — explicit > clever, structure > prose.

## Slash command convention

Every primary skill SHOULD have a slash command wrapper in `plugins/<plugin-name>/commands/`:

```markdown
---
description: <one line>
argument-hint: <argument hint>
---

Invoke the `<skill-name>` skill to ...

$ARGUMENTS
```

Keep command names aligned with the skill's trigger phrases (e.g. `/prd` → `ai-driven-prd`, `/plan` → `generate-dev-plan`).

## Adding a new plugin

1. Create `plugins/<new-plugin>/.claude-plugin/plugin.json` with `name`, `version` matching the current shared version, and `description`.
2. Add the plugin's component folders (`skills/`, `commands/`, etc.) under `plugins/<new-plugin>/`.
3. Add a `plugins[]` entry to `.claude-plugin/marketplace.json` with a `git-subdir` source pointing at `plugins/<new-plugin>` and the current `ref`.
4. The next `scripts/release.sh` run will pick it up automatically.

## Commit conventions

Conventional Commits. Examples:

- `feat(machine-work): add tdd-loop skill`
- `feat(plugins): scaffold new <plugin-name> plugin`
- `fix(machine-work/ai-driven-prd): correct phase 6 checklist threshold`
- `docs(readme): document new plugin`
- `chore(release): v0.2.0`

## Versioning

SemVer, shared across the whole marketplace. The same version lives in:

- `.claude-plugin/marketplace.json` (`metadata.version` and every `plugins[].version`).
- Every `plugins/*/.claude-plugin/plugin.json` (`version`).

- **patch** — bugfix in any plugin's skill or command.
- **minor** — new skill, new command, new plugin, or backwards-compatible improvement.
- **major** — breaking change to any plugin's interface.

## Source of truth

@docs/framework.md (when synced from the upstream repo).