# the-ai-machine

> Claude Code marketplace hosting plugins that cover the full AI-assisted development workflow — from raw stakeholder request to a shipped, tested, maintainable feature.

This repo is a marketplace. It ships workflow plugins as folders under `plugins/`. [`machine-work`](plugins/machine-work/) implements the [AI Development Framework V2](https://github.com/el-frontend/software-engineering-skills/blob/main/docs/framework.md) as composable skills; business and discovery plugins add upstream product workflow stages.

## Plugins

| Plugin | Folder | Purpose |
|---|---|---|
| [`machine-work`](plugins/machine-work/) | `plugins/machine-work/` | 5-phase AI development pipeline (PRD → setup → plan → design → execute). |
| [`machine-business`](plugins/machine-business/) | `plugins/machine-business/` | Shared project input processing plus business proposal generation. |
| [`machine-discovery`](plugins/machine-discovery/) | `plugins/machine-discovery/` | F1 Discovery workflow: proposal intake, RF/RNF, HLA, planning, draft PRDs, project document, and commercial offer. |

## `machine-work` pipeline

```
1. PRD          →  docs/prd/prd-<slug>.md
2. Setup        →  CLAUDE.md + docs/{designs,prd,plans}/
3. Plan         →  docs/plans/<FR-N>.md
4. Design       →  docs/designs/<FR-N>-<slug>-<state>.{html,png}
5. Execute      →  shipped PR (one commit per task, conventional commits)
```

Each phase has a human gate and produces a machine-verifiable artifact.

### Skills included

| Skill | Phase | Trigger | Slash command |
|---|---|---|---|
| [`init-claude-project`](plugins/machine-work/skills/init-claude-project/SKILL.md) | Setup | "init Claude in this repo", "bootstrap docs folder" | `/init-project` |
| [`ai-driven-prd`](plugins/machine-work/skills/ai-driven-prd/SKILL.md) | PRD | "write a PRD", "spec this feature", "audit my PRD" | `/prd` |
| [`generate-dev-plan`](plugins/machine-work/skills/generate-dev-plan/SKILL.md) | Plan | "make a plan for FR-001", "break this PRD into tasks" | `/plan` |
| [`declarative-design`](plugins/machine-work/skills/declarative-design/SKILL.md) | Design | "import these designs", "add screens for FR-001" | `/designs` |
| [`execute-plan`](plugins/machine-work/skills/execute-plan/SKILL.md) | Execute | "execute the plan", "ship FR-001" | `/execute` |

## Installation

```
/plugin marketplace add git@gitlab.yareytech.com:the-ai-machine/the-ai-machine.git
/plugin install machine-work@the-ai-machine
```

The marketplace's `marketplace.json` on `main` declares which tag installs (`source.ref`). Commits to `main` that do not move that ref are invisible to consumers — only the release script advances it.

To update when a new version ships:

```
/plugin marketplace update the-ai-machine
/plugin update machine-work
```

### Local development

If you are iterating on a plugin without going through a release:

```bash
git clone git@gitlab.yareytech.com:the-ai-machine/the-ai-machine.git
cd the-ai-machine
# In marketplace.json, replace the git-subdir source with "./plugins/machine-work"
# to point at the local checkout.
```

```
/plugin marketplace add /absolute/path/to/the-ai-machine
/plugin install machine-work@the-ai-machine
```

### Verify the install

```
/plugin list
```

You should see the installed plugin active under the `the-ai-machine` marketplace with its skills and slash commands available.

### Publish a new version

See [`RELEASING.md`](RELEASING.md). The process in short:

```bash
scripts/release.sh patch          # or: minor | major | 0.3.0
git push origin main
git push origin vX.Y.Z
```

## Usage (recommended `machine-work` flow)

```bash
# 1. Bootstrap the target project
/init-project

# 2. Turn an idea into an AI-ready PRD
/prd "we need an email notifications system"

# 3. Turn FR-001 from the PRD into an executable plan
/plan FR-001

# 4. (Optional) Import or generate UI designs for FR-001
/designs FR-001

# 5. Execute the plan → PR
/execute FR-001
```

Each step stops at its human gate. There is no auto-chaining: you decide when to advance.

## Structure

```
the-ai-machine/                          (repo = marketplace)
├── .claude-plugin/
│   └── marketplace.json                 Catalog — git-subdir source per plugin, pinned to a tag.
├── plugins/
│   ├── machine-work/                    Plugin: AI development workflow.
│   ├── machine-business/                Plugin: business proposal workflow.
│   └── machine-discovery/               Plugin: F1 Discovery workflow.
├── docs/
│   └── framework.md                     AI Development Framework V2 — marketplace-level context.
├── scripts/
│   └── release.sh                       Shared-tag release tool.
├── CLAUDE.md                            Conventions for adding skills and plugins.
├── README.md
├── RELEASING.md
├── CHANGELOG.md
└── LICENSE
```

## Adding a new plugin

See [`CLAUDE.md`](CLAUDE.md) → "Adding a new plugin". Short version: create `plugins/<new-plugin>/.claude-plugin/plugin.json`, drop your skills/commands inside `plugins/<new-plugin>/`, add a `git-subdir` entry in `marketplace.json`, run `scripts/release.sh`.

## Philosophy (applies to every plugin)

Three principles the skills enforce:

1. **The spec is the bottleneck.** The PRD must be explicit, atomic, machine-verifiable, and self-contained. Omission = permission. Vague adjectives = hallucinations.
2. **You control the process.** Skills are small, decomposable, and model-agnostic. No framework lock-in. You can run one in isolation, swap it, fork it, or chain it.
3. **Engineering discipline.** RFC 2119 keywords, numbered IDs (FR-N ↔ AC-N ↔ test), TDD, vertical slices, conventional commits. The fundamentals matter more in the AI era, not less.

## Attribution

The 5 initial skills inside `machine-work` are the work of [el-frontend/software-engineering-skills](https://github.com/el-frontend/software-engineering-skills) (commit `b0184fa`), a work colleague. Vendored here to package them as a Claude Code plugin and to be able to evolve them independently. Structure and philosophy in turn inspired by [mattpocock/skills](https://github.com/mattpocock/skills).

## License

MIT — see [LICENSE](LICENSE).