ai-engineering-starter-kit 0.4.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcus Bransbury
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,243 @@
+# AI Engineering Starter Kit
+
+[![CI](https://github.com/bransbury/ai-engineering-starter-kit/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/bransbury/ai-engineering-starter-kit/actions/workflows/ci.yml)
+[![License](https://img.shields.io/github/license/bransbury/ai-engineering-starter-kit)](LICENSE.md)
+[![Release](https://img.shields.io/github/v/release/bransbury/ai-engineering-starter-kit)](https://github.com/bransbury/ai-engineering-starter-kit/releases)
+
+AI coding agents are now part of everyday engineering work, but the process is often inconsistent. Engineers can prompt normally, yet the quality of the outcome still depends on whether the agent inspects the right code, asks only the necessary questions, plans a safe change, and proves it before PR.
+
+**Plan. Patch. Prove.**
+
+The practical AI coding loop: inspect first, change safely, verify before PR.
+
+![Plan. Patch. Prove workflow overview](docs/images/plan-prove-patch-header.png)
+
+```text
+Inspect → Clarify → Plan → Prove → Patch → Review → PR
+```
+
+PPP is a simple, practical workflow for everyday tasks and tickets. It gives AI coding agents a fast, reliable, consistent, and token-efficient loop: inspect first, plan the smallest safe complete change, patch in small validated steps, and prove the result before handoff.
+
+The starter kit includes:
+
+- **Plan. Patch. Prove. (`/ppp`)** — an interactive workflow for engineers using an IDE agent
+- **Plan. Patch. Prove. Cloud (`ppp-cloud`)** — a non-interactive workflow for autonomous cloud coding agents
+- repo templates for agent guidance, Copilot instructions, PR templates, and Cursor rules
+- practical docs and examples for adoption
+
+## Quick start
+
+```bash
+npx ai-engineering-starter-kit install
+```
+
+If slash commands are supported in your tool, run:
+
+```text
+/ppp <prompt>
+```
+
+## If `/ppp` does not work
+
+`/ppp` works only where your agent tool loads skills as slash commands.
+
+Fallback invocation:
+
+```text
+Use the Plan. Patch. Prove workflow on this prompt:
+<paste prompt>
+```
+
+Not sure which setup to use? See [IDE setup](docs/ide-setup.md).
+
+Prefer shell scripts instead of `npx`?
+
+```bash
+git clone https://github.com/bransbury/ai-engineering-starter-kit
+cd ai-engineering-starter-kit
+./install.sh
+```
+
+## How PPP works
+
+PPP stands for:
+
+- **Plan** the smallest safe complete change.
+- **Patch** the code in small, controlled steps.
+- **Prove** it works before PR.
+
+The actual workflow is deliberately proof-first:
+
+```text
+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
+
+```text
+Ticket
+  ↓
+/ppp
+  ↓
+Inspect → Clarify → Plan → Prove → Patch → Review → PR
+  ↓
+PR handoff
+```
+
+### Cloud flow
+
+```text
+Issue
+  ↓
+ppp-cloud
+  ↓
+Draft PR or blocker
+```
+
+## Which setup should I use?
+
+| I am... | Do this |
+| --- | --- |
+| Trying PPP 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` |
+| Assigning cloud-agent tasks | Use `ppp-cloud` and repo instructions |
+
+## What gets installed?
+
+The installers copy the skills to both common personal skill locations:
+
+```text
+~/.agents/skills/ppp/SKILL.md
+~/.agents/skills/ppp-cloud/SKILL.md
+~/.copilot/skills/ppp/SKILL.md
+~/.copilot/skills/ppp-cloud/SKILL.md
+```
+
+If a `.cursor/` directory is detected in the current directory, it also installs the Cursor rule:
+
+```text
+.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 PPP 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:
+
+```bash
+npx ai-engineering-starter-kit install --repo-local
+```
+
+For most teams, the most reliable repo rollout is:
+
+- repo-local skills for `/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
+
+## 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:
+
+```text
+/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:
+
+```text
+/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.
+
+## 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](examples/prompts/ppp-examples.md#what-good-output-looks-like).
+
+## 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](docs/cloud-agent-usage.md).
+
+## 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.
+- PPP is a narrow, practical workflow for everyday engineering tasks.
+- It focuses on a simple loop: inspect first, plan the smallest safe change, prove it before patching broadly, and hand off a reviewable PR.
+
+## Docs and templates
+
+### Docs
+
+- [How to use PPP](docs/how-to-use-ppp.md)
+- [IDE setup](docs/ide-setup.md)
+- [Cloud agent usage](docs/cloud-agent-usage.md)
+- [Adoption rollout](docs/adoption-rollout.md)
+- [Release automation spec](docs/release-automation-spec.md)
+- [Troubleshooting](docs/troubleshooting.md)
+
+### 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.
+
+## License
+
+[MIT](LICENSE.md) © 2026 Marcus Bransbury

package/bin/ai-engineering-starter-kit.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const readline = require("readline");
+
+const root = path.resolve(__dirname, "..");
+const home = os.homedir();
+const skills = ["ppp", "ppp-cloud"];
+const personalTargets = [
+  path.join(home, ".agents", "skills"),
+  path.join(home, ".copilot", "skills"),
+];
+const repoLocalTargets = [path.join(process.cwd(), ".github", "skills")];
+
+function parseArgs(argv) {
+  const positional = [];
+  const flags = new Set();
+
+  for (const arg of argv) {
+    if (arg.startsWith("-")) {
+      flags.add(arg);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  return {
+    command: positional[0] || null,
+    dryRun: flags.has("--dry-run"),
+    force: flags.has("--force"),
+    yes: flags.has("--yes") || flags.has("-y"),
+    repoLocal: flags.has("--repo-local"),
+    help: flags.has("--help") || flags.has("-h"),
+  };
+}
+
+function usage() {
+  console.log(`AI Engineering Starter Kit
+
+Usage:
+  ai-engineering-starter-kit install [--yes] [--dry-run] [--force] [--repo-local]
+  ai-engineering-starter-kit uninstall [--yes] [--dry-run] [--repo-local]
+  ai-engineering-starter-kit help
+
+Examples:
+  npx ai-engineering-starter-kit install --yes
+  npx ai-engineering-starter-kit install --dry-run
+  npx ai-engineering-starter-kit install --repo-local
+`);
+}
+
+function log(message = "") {
+  console.log(message);
+}
+
+function skillVersion(skillName) {
+  const src = path.join(root, "skills", skillName, "SKILL.md");
+  const content = fs.readFileSync(src, "utf8");
+  const match = content.match(/^version:\s*(.+)$/m);
+  return match ? match[1].trim() : "unknown";
+}
+
+function timestamp() {
+  const now = new Date();
+  const pad = (value) => String(value).padStart(2, "0");
+  return [
+    now.getFullYear(),
+    pad(now.getMonth() + 1),
+    pad(now.getDate()),
+    pad(now.getHours()),
+    pad(now.getMinutes()),
+    pad(now.getSeconds()),
+  ].join("");
+}
+
+function actionWord(dryRun, verb) {
+  return dryRun ? `Would ${verb}` : verb[0].toUpperCase() + verb.slice(1);
+}
+
+function runMkdir(destDir, dryRun) {
+  if (dryRun) {
+    log(`[dry-run] mkdir -p ${destDir}`);
+    return;
+  }
+  fs.mkdirSync(destDir, { recursive: true });
+}
+
+function runCopy(src, dest, dryRun) {
+  if (dryRun) {
+    log(`[dry-run] copy ${src} -> ${dest}`);
+    return;
+  }
+  fs.copyFileSync(src, dest);
+}
+
+function runRemove(target, dryRun) {
+  if (dryRun) {
+    log(`[dry-run] remove ${target}`);
+    return;
+  }
+  fs.rmSync(target, { recursive: true, force: true });
+}
+
+function backupFile(filePath, dryRun) {
+  const backupPath = `${filePath}.bak.${timestamp()}`;
+  runCopy(filePath, backupPath, dryRun);
+  log(`${actionWord(dryRun, "back up existing file")} to ${backupPath}`);
+}
+
+async function confirmOverwrite(targetFile) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stderr,
+  });
+
+  const reply = await new Promise((resolve) => {
+    rl.question(`Overwrite ${targetFile}? [y/N] `, resolve);
+  });
+  rl.close();
+
+  return /^(y|yes)$/i.test(reply.trim());
+}
+
+async function shouldOverwrite(targetFile, options) {
+  if (!fs.existsSync(targetFile)) {
+    return true;
+  }
+
+  if (options.force) {
+    return true;
+  }
+
+  if (options.yes || !process.stdin.isTTY) {
+    log(`Exists at ${targetFile} - skipping (use --force to overwrite)`);
+    return false;
+  }
+
+  const confirmed = await confirmOverwrite(targetFile);
+  if (!confirmed) {
+    log(`Skipping ${targetFile}`);
+    return false;
+  }
+  return true;
+}
+
+async function installSkill(skillName, targetRoot, options) {
+  const src = path.join(root, "skills", skillName, "SKILL.md");
+  const destDir = path.join(targetRoot, skillName);
+  const destFile = path.join(destDir, "SKILL.md");
+
+  if (!fs.existsSync(src)) {
+    throw new Error(`Missing skill source: ${src}`);
+  }
+
+  runMkdir(destDir, options.dryRun);
+
+  if (!(await shouldOverwrite(destFile, options))) {
+    return;
+  }
+
+  if (fs.existsSync(destFile)) {
+    backupFile(destFile, options.dryRun);
+  }
+
+  runCopy(src, destFile, options.dryRun);
+  log(`${actionWord(options.dryRun, "install")} ${skillName} ${skillVersion(skillName)} to ${destFile}`);
+}
+
+async function installCursorRule(options) {
+  const src = path.join(root, "templates", "cursor-ppp-rule.mdc");
+  const destDir = path.join(process.cwd(), ".cursor", "rules");
+  const destFile = path.join(destDir, "ppp.mdc");
+
+  if (!fs.existsSync(src)) {
+    throw new Error(`Missing Cursor rule template: ${src}`);
+  }
+
+  if (!fs.existsSync(path.join(process.cwd(), ".cursor"))) {
+    log("Cursor not detected in current directory - skipping Cursor rule install.");
+    log("To install manually: copy templates/cursor-ppp-rule.mdc to .cursor/rules/ppp.mdc");
+    return;
+  }
+
+  runMkdir(destDir, options.dryRun);
+
+  if (!(await shouldOverwrite(destFile, options))) {
+    return;
+  }
+
+  if (fs.existsSync(destFile)) {
+    backupFile(destFile, options.dryRun);
+  }
+
+  runCopy(src, destFile, options.dryRun);
+  log(`${actionWord(options.dryRun, "install")} Cursor rule to ${destFile}`);
+}
+
+async function install(options) {
+  const targetRoots = options.repoLocal ? repoLocalTargets : personalTargets;
+
+  log("PPP installer");
+  log(`Version: ${skillVersion("ppp")}`);
+  if (options.repoLocal) {
+    log("Mode: repo-local");
+  }
+  if (options.dryRun) {
+    log("Mode: dry-run");
+  }
+  if (options.force) {
+    log("Overwrite mode: force");
+  }
+  log();
+
+  for (const skill of skills) {
+    for (const targetRoot of targetRoots) {
+      await installSkill(skill, targetRoot, options);
+    }
+  }
+
+  log();
+  if (!options.repoLocal) {
+    await installCursorRule(options);
+  }
+
+  log();
+  log("Done.");
+  log("Important: /ppp works only where your tool loads skills as slash commands.");
+  log("Fallback: Use the Plan. Patch. Prove workflow on this prompt:");
+  log("<paste prompt>");
+}
+
+function removeSkillDirs(targetRoots, options) {
+  for (const skill of skills) {
+    for (const targetRoot of targetRoots) {
+      const targetDir = path.join(targetRoot, skill);
+      if (fs.existsSync(targetDir)) {
+        runRemove(targetDir, options.dryRun);
+        log(`${actionWord(options.dryRun, "remove")} ${targetDir}`);
+      } else {
+        log(`Not found, skipping: ${targetDir}`);
+      }
+    }
+  }
+}
+
+function removeCursorRule(options) {
+  const cursorRule = path.join(process.cwd(), ".cursor", "rules", "ppp.mdc");
+  if (fs.existsSync(cursorRule)) {
+    runRemove(cursorRule, options.dryRun);
+    log(`${actionWord(options.dryRun, "remove")} ${cursorRule}`);
+  } else {
+    log(`Not found, skipping: ${cursorRule}`);
+  }
+}
+
+function uninstall(options) {
+  const targetRoots = options.repoLocal ? repoLocalTargets : personalTargets;
+
+  removeSkillDirs(targetRoots, options);
+  if (!options.repoLocal) {
+    removeCursorRule(options);
+  }
+
+  log("Done.");
+}
+
+async function main() {
+  const options = parseArgs(process.argv.slice(2));
+
+  if (!options.command || options.help || options.command === "help") {
+    usage();
+    process.exit(0);
+  }
+
+  if (options.command === "install") {
+    await install(options);
+    return;
+  }
+
+  if (options.command === "uninstall") {
+    uninstall(options);
+    return;
+  }
+
+  console.error(`Unknown command: ${options.command}`);
+  usage();
+  process.exit(1);
+}
+
+main().catch((error) => {
+  console.error(error.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "ai-engineering-starter-kit",
+  "version": "0.4.0",
+  "description": "Plan. Patch. Prove. Practical AI-assisted engineering workflows for IDE and cloud coding agents.",
+  "license": "MIT",
+  "private": false,
+  "type": "commonjs",
+  "bin": {
+    "ai-engineering-starter-kit": "bin/ai-engineering-starter-kit.js",
+    "aesk": "bin/ai-engineering-starter-kit.js"
+  },
+  "files": [
+    "bin",
+    "skills",
+    "templates",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  }
+}