AI Pair Programming

phpspec includes an interactive pair programming mode and AI-powered refactoring. Combine the BDD workflow with LLM assistance to write specs, features, and source code conversationally.

The `pair` command

Start an interactive REPL session:

$ bin/phpspec pair

Or send a single prompt without entering the REPL:

$ bin/phpspec pair --prompt "write a spec for a Calculator that adds two numbers"

Built-in commands

These work without AI configuration:

Command	Description
`describe <Class>`	Generate a spec file and optionally create the class
`exemplify <Class> <method>`	Add a method example to an existing spec
`run [path]`	Run specs and offer code generation for failures
`clear`	Clear the terminal
`/help`	Show available commands and AI status
`/quit`, `/exit`	Exit pair mode

AI configuration

Add an ai section to your config file:

# phpspec.yaml
ai:
  provider: anthropic
  api_key: YOUR_API_KEY

Provider	Default Model
`google`	`gemini-2.5-pro`
`anthropic`	`claude-sonnet-4-20250514`
`openai`	`gpt-4o`

You can override the model: model: gpt-4o-mini

What you can ask

> write a spec for a UserRepository that finds users by email
> create a feature scenario for user registration
> add a greet method example to the Greeter spec
> run my specs and tell me what's failing
> explain how the Loader class works
> read src/App/Calculator.php and suggest improvements

AI tools

The assistant has access to these tools during a pair session:

Tool	Description
`generate_spec`	Write a `.spec.php` file
`generate_feature`	Write a Gherkin `.feature` file
`generate_steps`	Write a `.steps.php` file
`write_file`	Create a new file (class, interface, etc.)
`update_file`	Modify an existing file
`run_specs`	Run specs and return output
`read_file`	Read a project file for context
`list_files`	List directory contents

Smart routing

phpspec detects whether input is a command or an AI request:

> describe App/Calculator             # runs describe command
> describe what the Loader class does # routes to AI
> run spec/App                        # runs specs
> run my specs and explain failures   # routes to AI

Conversation history

The AI maintains context within a session. You can build on previous exchanges:

> write a spec for a Calculator
  (AI generates spec)

> now add a divide method that throws on division by zero
  (AI updates the spec, remembering Calculator context)

> run the spec
  (AI runs specs and reports results)

The `next` command

When you’re not sure what to work on next:

$ bin/phpspec next

Scans your project’s source files, specs, and features, then suggests the most impactful next step. Follows the scenario-first workflow — recommends a feature before a spec, and a spec before an implementation.

phpspec next

Analysing project...

Write a feature scenario for user registration.

Your project has a UserRepository class with a spec, but no
feature scenario covering the registration flow. Adding a
scenario first will drive the step definitions and any
missing specs.

The `refactor` command

AI-powered, behaviour-preserving refactoring:

$ bin/phpspec refactor "App\Calculator"
$ bin/phpspec refactor "App\Calculator::sum"
$ bin/phpspec refactor "spec/App/Calculator.spec.php"

How it works

Baseline check — Runs specs first. If they fail, refactoring is refused.
AI analysis — The LLM reads source and spec files, identifies a refactoring.
Apply — Writes the refactored code.
Verify — Runs specs again. If they fail, the original is restored.
Report — Shows technique name, description, and a unified diff.

Target resolution

Input	Source file	Spec file
`App\Calculator`	`src/App/Calculator.php`	`spec/App/Calculator.spec.php`
`App\Calculator::sum`	`src/App/Calculator.php` (focused)	`spec/App/Calculator.spec.php`
`spec/App/Calculator.spec.php`	`src/App/Calculator.php` (inferred)	`spec/App/Calculator.spec.php`

Refactoring techniques

The AI chooses from standard techniques:

Extract Method
Inline Variable / Inline Temp
Rename (variable, method, class)
Extract Class / Move Method
Replace Conditional with Polymorphism
Introduce Parameter Object
Replace Magic Number with Constant
Simplify Conditional
Remove Dead Code

If the code is already clean, the AI reports that no refactoring is needed.

Requirements

AI must be configured in phpspec.yaml (same ai: section)
Requires one of: papi-ai/papi-core with a provider package
Suggested providers: papi-ai/google, papi-ai/anthropic, papi-ai/openai

← Extensions