feat: add plugboard ai init CLI command (#237)

# Summary

Adds a new `plugboard ai init` CLI command that creates an `AGENTS.md`
file in the current working directory (or a specified directory). The
file provides AI coding agents with instructions for building Plugboard
models, following the convention used by tools like Claude Code, Codex,
and Gemini CLI.

The `AGENTS.md` template is kept in sync with `examples/AGENTS.md` via a
symlink in the package.

# Changes

- **`plugboard/cli/ai/__init__.py`** — New CLI module with `init`
command using Typer, following existing CLI patterns (rich output,
stderr for errors).
- **`plugboard/cli/ai/AGENTS.md`** — Symlink to `examples/AGENTS.md` so
the distributed template stays in sync with the examples.
- **`plugboard/cli/__init__.py`** — Register `ai` subcommand in the main
CLI app.
- **`tests/unit/test_cli.py`** — 3 new tests: successful creation,
already-exists error, and default directory behavior.
- **`docs/usage/ai.md`** — Documentation page for the new command.
- **`mkdocs.yaml`** — Added "AI-Assisted Development" nav entry under
Usage.
- **`examples/AGENTS.md`** — Fixed two typos (`componen` → `component`,
duplicate `SQLReader` → `SQLWriter`).

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: toby-coleman <13170610+toby-coleman@users.noreply.github.com>
Co-authored-by: Toby Coleman <toby@tobycoleman.com>

Author: Copilot

README.md

@@ -65,6 +65,22 @@ Optional integrations for different cloud providers can be installed using `plug
 
 Support for parallelisation can be installed using `plugboard[ray]`.
 
+## ⚡ Quickstart with AI
+
+The fastest way to get started is to let your AI coding assistant build your first model. Run the following command in your project directory:
+
+```shell
+plugboard ai init
+```
+
+This copies a context file (`AGENTS.md`) into your project that gives your AI tool everything it needs to know about Plugboard: how components work, how to wire them together, library components that are already available, and best practices for building models.
+
+Once initialised, simply open your AI tool of choice (GitHub Copilot, Cursor, Claude, etc.) and describe the model you want to build. For example:
+
+> *"I want to simulate a production line with three machines in series. Each machine has a processing time drawn from a normal distribution and a 5% chance of failure. Model the throughput over 1000 time steps and save the results to a CSV."*
+
+Your AI assistant will use the `AGENTS.md` context to generate working Plugboard code — components, connectors, and a runnable process — tailored to your description.
+
 ## 🚀 Usage
 
 <a href="https://colab.research.google.com/github/plugboard-dev/plugboard/blob/main/"><img src="https://colab.research.google.com/assets/colab-badge.svg"></a>

docs/usage/ai.md

@@ -0,0 +1,42 @@
+# AI-Assisted Development
+
+Plugboard ships with tooling to help AI coding agents understand how to build models using the framework. The `plugboard ai` command group provides utilities for setting up AI-assisted development workflows.
+
+## Initialising a project
+
+The `plugboard ai init` command creates an `AGENTS.md` file in your project directory. This file gives AI coding agents the context they need to help you build Plugboard models — covering how to create components, assemble processes, use events, and follow best practices.
+
+`AGENTS.md` is a convention used by AI coding tools (such as [Claude Code](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/overview), [Codex](https://openai.com/index/codex/), and [Gemini CLI](https://github.com/google-gemini/gemini-cli)) to discover project-specific instructions automatically.
+
+### Usage
+
+To create an `AGENTS.md` file in the current working directory:
+
+```bash
+plugboard ai init
+```
+
+To create the file in a specific directory:
+
+```bash
+plugboard ai init /path/to/project
+```
+
+!!! note
+    The command will not overwrite an existing `AGENTS.md` file. If one already exists in the target directory, the command exits with an error.
+
+### What's in the file?
+
+The generated `AGENTS.md` covers:
+
+- **Planning a model** — how to break a problem down into components, inputs, outputs, and data flows.
+- **Implementing components** — using built-in library components and creating custom ones by subclassing [`Component`][plugboard.component.Component].
+- **Assembling a process** — connecting components together and running a [`LocalProcess`][plugboard.process.LocalProcess].
+- **Event-driven models** — defining custom [`Event`][plugboard.events.Event] types, emitting events, and writing event handlers.
+- **Exporting models** — saving process definitions to YAML and running them via the CLI.
+
+The file is intended to be committed to version control alongside your project code so that any AI agent working in the repository has immediate access to Plugboard conventions.
+
+### Customising
+
+After generating the file you can edit it freely to add project-specific instructions — for example, domain context, coding standards, or pointers to your own components and data sources.

examples/AGENTS.md

@@ -20,7 +20,7 @@ Ask questions if anything is not clear about the business logic or you require a
 
 Always check whether the functionality you need is already available in the library components in `plugboard.library`. For example, try to use:
 - `FileReader` and `FileWriter` for reading/writing data from CSV or parquet files.
-- `SQLReader` and `SQLReader` for reading/writing data from SQL databases.
+- `SQLReader` and `SQLWriter` for reading/writing data from SQL databases.
 - `LLMChat` for interacting with standard LLMs, e.g. OpenAI, Gemini, etc.
 
 **Using Built-in Components**
@@ -33,7 +33,7 @@ data_loader = FileReader(name="input_data", path="input.csv", field_names=["x",
 
 **Creating Custom Components**
 
-New components should inherit from `plugboard.componen.Component`. Add logging messages where it would be helpful by using the bound logger `self._logger`.
+New components should inherit from `plugboard.component.Component`. Add logging messages where it would be helpful by using the bound logger `self._logger`.
 
 ```python
 import typing as _t

mkdocs.yaml

@@ -129,6 +129,7 @@ nav:
     - Event-driven models: examples/tutorials/event-driven-models.md
     - Tuning a process: examples/tutorials/tuning-a-process.md
   - Configuration: usage/configuration.md
+  - AI-Assisted Development: usage/ai.md
   - Topics: usage/topics.md
 - Demos:
   - Fundamentals:

plugboard/cli/__init__.py

@@ -3,6 +3,7 @@
 import typer
 
 from plugboard import __version__
+from plugboard.cli.ai import app as ai_app
 from plugboard.cli.process import app as process_app
 from plugboard.cli.server import app as server_app
 from plugboard.cli.version import app as version_app
@@ -14,6 +15,7 @@
     help=f"[bold]Plugboard CLI[/bold]\n\nVersion {__version__}",
     pretty_exceptions_show_locals=False,
 )
+app.add_typer(ai_app, name="ai")
 app.add_typer(process_app, name="process")
 app.add_typer(server_app, name="server")
 app.add_typer(version_app, name="version")

plugboard/cli/ai/AGENTS.md

@@ -0,0 +1 @@
+../../../examples/AGENTS.md

plugboard/cli/ai/__init__.py

@@ -0,0 +1,41 @@
+"""Plugboard AI CLI."""
+
+from pathlib import Path
+import shutil
+
+from rich import print
+from rich.console import Console
+import typer
+
+
+app = typer.Typer(
+    rich_markup_mode="rich", no_args_is_help=True, pretty_exceptions_show_locals=False
+)
+stderr = Console(stderr=True)
+
+_AGENTS_MD = Path(__file__).parent / "AGENTS.md"
+
+
+@app.command()
+def init(
+    directory: Path = typer.Argument(
+        default=None,
+        help="Target directory for the AGENTS.md file. Defaults to the current working directory.",
+        exists=True,
+        file_okay=False,
+        dir_okay=True,
+        resolve_path=True,
+    ),
+) -> None:
+    """Initialise a project with an AGENTS.md file for AI-assisted development."""
+    if directory is None:
+        directory = Path.cwd()
+
+    target = directory / "AGENTS.md"
+
+    if target.exists():
+        stderr.print("[red]AGENTS.md already exists[/red] in the target directory.")
+        raise typer.Exit(1)
+
+    shutil.copy2(_AGENTS_MD, target)
+    print(f"[green]Created[/green] {target}")

plugboard/tune/tune.py

@@ -1,13 +1,13 @@
 """Provides `Tuner` class for optimising Plugboard processes."""
 
+from __future__ import annotations
+
 from functools import partial
 from inspect import isfunction, signature
 import math
 from pydoc import locate
 import typing as _t
 
-import ray.tune.search.optuna
-
 from plugboard.component.component import Component, ComponentRegistry
 from plugboard.exceptions import ConstraintError
 from plugboard.process import Process, ProcessBuilder
@@ -27,6 +27,7 @@
     import optuna.storages
     import ray.tune
     import ray.tune.search
+    import ray.tune.search.optuna
 except ImportError:  # pragma: no cover
     pass
 

tests/unit/test_cli.py

@@ -87,6 +87,42 @@ def test_cli_process_diagram() -> None:
     assert "flowchart" in result.stdout
 
 
+def test_cli_ai_init(tmp_path: Path) -> None:
+    """Tests the ai init command creates AGENTS.md."""
+    result = runner.invoke(app, ["ai", "init", str(tmp_path)])
+    assert result.exit_code == 0
+    assert "Created" in result.stdout
+    # File must exist with expected content
+    agents_md = tmp_path / "AGENTS.md"
+    assert agents_md.exists()
+    content = agents_md.read_text()
+    assert "Plugboard" in content
+
+
+def test_cli_ai_init_already_exists(tmp_path: Path) -> None:
+    """Tests the ai init command fails when AGENTS.md already exists."""
+    (tmp_path / "AGENTS.md").write_text("existing content")
+    result = runner.invoke(app, ["ai", "init", str(tmp_path)])
+    assert result.exit_code == 1
+    # Error is printed to stderr which typer captures in output
+    assert "already exists" in result.output
+
+
+def test_cli_ai_init_default_directory() -> None:
+    """Tests the ai init command uses current directory by default."""
+    with tempfile.TemporaryDirectory() as tmpdir:
+        original_cwd = Path.cwd()
+        try:
+            import os
+
+            os.chdir(tmpdir)
+            result = runner.invoke(app, ["ai", "init"])
+            assert result.exit_code == 0
+            assert (Path(tmpdir) / "AGENTS.md").exists()
+        finally:
+            os.chdir(original_cwd)
+
+
 def test_cli_server_discover(test_project_dir: Path) -> None:
     """Tests the server discover command."""
     with respx.mock: