AI Engineering Starter Kit

Shape the work. Ship the PRs.

Practical AI-assisted engineering workflows: clarify rough work, choose the safest delivery path, and execute focused tasks with proof before PR.

Shape → Ship

The starter kit includes:

Shape (/shape) — a shaping workflow that turns rough work into clear, testable PR-sized tasks
Ship (/ship) — a coordination workflow that chooses the safest execution path across PPP, PPP Cloud, or parallel delivery
Plan. Patch. Prove. (/ppp) — an interactive execution workflow for one focused task in your IDE
Plan. Patch. Prove - Cloud (/ppp-cloud) — a non-interactive execution workflow for one bounded autonomous task
repo templates for agent guidance, Copilot instructions, PR templates, and Cursor rules
practical docs and examples for adoption

Quick start

npx ai-engineering-starter-kit install

Or via the skills.sh ecosystem:

npx skills add bransbury/ai-engineering-starter-kit

If slash commands are supported in your tool, run one of:

/shape <prompt>
/ship <prompt>
/ppp <prompt>
/ppp-cloud <prompt>

If a slash-command skill does not work

These skills work only where your agent tool loads skills as slash commands.

Fallback invocation:

Use the Plan. Patch. Prove workflow on this prompt:
<paste prompt>

Not sure which setup to use? See IDE setup.

Prefer shell scripts instead of npx?

git clone https://github.com/bransbury/ai-engineering-starter-kit
cd ai-engineering-starter-kit
./install.sh

Which setup should I use?

I am...	Do this
Trying the workflows personally	Run `npx ai-engineering-starter-kit install`
Rolling out to a repo	Copy `templates/AGENTS.md` and `templates/copilot-instructions.md`
Using Cursor	Copy `templates/cursor-ppp-rule.mdc`
Shaping rough work first	Run `npx ai-engineering-starter-kit install` and use `/shape`
Coordinating multi-step delivery	Run `npx ai-engineering-starter-kit install` and use `/ship`
Assigning cloud-agent tasks	Run `npx ai-engineering-starter-kit install --repo-local`, add `AGENTS.md`, and use `/ppp-cloud`

Which skill should I use?

I want to...	Use
Give the system a task and let it choose the safest delivery path	`/ship`
Clarify or split rough work before coding	`/shape`
Complete one focused task interactively in an IDE	`/ppp`
Delegate one clear bounded task to an autonomous coding agent	`/ppp-cloud`

Examples:

/ship Roll out the saved-reports feature safely across UI, validation, and docs.
/shape Add role-based approvals to expense reports.
/ppp Add an empty state to the experiment results table.
/ppp-cloud Add regression tests for report-name validation.

The core workflow

The starter kit is built around a simple top-level workflow:

Shape → Ship

Shape turns vague work into clear, scoped, PR-sized tasks.
Ship chooses the safest delivery path: local PPP, autonomous PPP Cloud, parallel worktrees, or stop for a human decision.

In practice, Ship is the router:

Task
  ↓
Ship
  ├─ Shape first if unclear
  ├─ /ppp for one local task
  ├─ /ppp-cloud for one autonomous task
  ├─ parallel worktrees when safe
  └─ stop for a human decision

Execution engine: PPP

PPP stands for:

Plan the smallest safe complete change.
Patch the code in small, controlled steps.
Prove it works before PR.

When work is ready, Ship uses the PPP execution loop:

Inspect → Clarify → Plan → Prove → Patch → Review → PR

Prove starts before Patch: the agent defines the proof first, then patches in small loops and runs the proof as it goes.

IDE flow

Ticket
  ↓
/ppp
  ↓
Inspect → Clarify → Plan → Prove → Patch → Review → PR
  ↓
PR handoff

Cloud flow

Issue
  ↓
/ppp-cloud
  ↓
Draft PR or blocker

What gets installed?

The installers copy all four skills to common personal skill locations:

~/.agents/skills/<skill-name>/SKILL.md
~/.claude/skills/<skill-name>/SKILL.md
~/.copilot/skills/<skill-name>/SKILL.md

Where <skill-name> is one of ppp, ppp-cloud, shape, or ship.

If a .cursor/ directory is detected in the current directory, it also installs the Cursor rule:

.cursor/rules/ppp.mdc

Run npx ai-engineering-starter-kit install or ./install.sh from each project where you want the Cursor rule active.

Repo-local install

GitHub supports project skills in .github/skills, .claude/skills, or .agents/skills. If you want the workflows to live with a specific repo instead of your personal environment, copy the skills into one of those project-local locations.

For GitHub project skills:

npx ai-engineering-starter-kit install --repo-local

For most teams, the most reliable repo rollout is:

repo-local skills for /shape, /ship, /ppp, and /ppp-cloud
AGENTS.md at the repo root
.github/copilot-instructions.md for VS Code + Copilot
.cursor/rules/ppp.mdc for Cursor projects

The new default behaviour

For most engineers, the simplest guidance is:

use /ship for normal work;
use /shape when you only want to clarify or split the work;
use /ppp when you already know it is one focused IDE task;
use /ppp-cloud when you already know it is one bounded autonomous task.

When to use `/ppp`

Use /ppp for normal engineering work that should fit in one focused PR:

bug fixes
small features
tests
UI tweaks
small refactors

Good examples:

/ppp Fix whitespace-only report names being accepted.
/ppp Add an empty state to the experiment results table when there are no rows.

When not to use `/ppp`

Do not use /ppp to implement a whole large feature in one go.

Examples that are too large:

/ppp Build a new analytics dashboard.
/ppp Implement the new permissions system.

For large work, ask /ppp to identify the smallest first task, or use a feature-slicing workflow.

For vague or multi-PR work, prefer /ship first or /shape if you only want clarification.

What good looks like

A good PPP run should:

inspect relevant code before editing
ask only important questions
define how the change will be verified before editing
add or update tests/checks where appropriate
stop after two focused failed fix attempts
review production readiness
prepare a PR title/body using repo conventions

See a full example run.

Cloud agent usage

	`/ppp`	`/ppp-cloud`
Who drives it	Engineer in IDE	Autonomous cloud agent
Interaction	Interactive menus	Non-interactive, runs to completion
Output	Guided session → PR handoff	Draft PR or blocker report
Best for	Any normal ticket with a human in the loop	Clear, bounded tasks you can assign and review

Use /ppp-cloud for autonomous coding agents. It is designed for clear, bounded, verifiable tasks where the agent should either:

create one focused draft PR; or
stop with a clear blocker explaining why it could not proceed safely.

See Cloud agent usage.

How is this different?

Some skills are broad libraries of composable expert workflows.
Some tools are opinionated operating systems for full-stack or product development.
Shape and Ship provide the top-level operating model for the kit.
Ship is the coordination layer that picks the safest path for delivery.
PPP is the execution loop Ship uses when work is ready and focused.
/ppp-cloud is the autonomous variant for one bounded task that should end in a draft PR or blocker.

Docs and templates

Docs

Templates

If you don't already have them, copy these into your repos to give AI agents consistent guidance:

Template	Copy to	Purpose
`templates/AGENTS.md`	`AGENTS.md` (repo root)	Tells agents which workflow to use and what requires human approval
`templates/copilot-instructions.md`	`.github/copilot-instructions.md`	Repo-level Copilot instructions picked up automatically in VS Code
`templates/PULL_REQUEST_TEMPLATE.md`	`.github/PULL_REQUEST_TEMPLATE.md`	Consistent PR descriptions across human and AI-authored PRs
`templates/cursor-ppp-rule.mdc`	`.cursor/rules/ppp.mdc`	Cursor project rule — automatically installed by `npx ai-engineering-starter-kit install` or `./install.sh` if `.cursor/` exists

Each template is intentionally minimal. Add repo-specific conventions (architecture rules, test commands, forbidden areas) directly in AGENTS.md and copilot-instructions.md.

Security note

Skills are operational instructions that can influence AI agent behaviour. Review changes to SKILL.md files carefully.

Do not add secrets, credentials, internal-only URLs, or sensitive customer data to skills or examples.

Name		Name	Last commit message	Last commit date
.github		.github
bin		bin
docs		docs
evals		evals
examples		examples
scripts		scripts
skills		skills
templates		templates
.gitignore		.gitignore
.markdownlint-cli2.jsonc		.markdownlint-cli2.jsonc
.markdownlint.json		.markdownlint.json
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE.md		LICENSE.md
README.md		README.md
SECURITY.md		SECURITY.md
install.sh		install.sh
package.json		package.json
uninstall.sh		uninstall.sh

Navigation Menu

Repository files navigation

AI Engineering Starter Kit

Quick start

If a slash-command skill does not work

Which setup should I use?

Which skill should I use?

The core workflow

Execution engine: PPP

IDE flow

Cloud flow

What gets installed?

Repo-local install

The new default behaviour

When to use `/ppp`

When not to use `/ppp`

What good looks like

Cloud agent usage

How is this different?

Docs and templates

Docs

Templates

Security note

License

About

Releases

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

AI Engineering Starter Kit

Quick start

If a slash-command skill does not work

Which setup should I use?

Which skill should I use?

The core workflow

Execution engine: PPP

IDE flow

Cloud flow

What gets installed?

Repo-local install

The new default behaviour

When to use /ppp

When not to use /ppp

What good looks like

Cloud agent usage

How is this different?

Docs and templates

Docs

Templates

Security note

License

About

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Contributors

Languages

When to use `/ppp`

When not to use `/ppp`