@georgeroberts/ai-workflows

Install reusable AI workflow Markdown files into any project to power developer agents (like Cursor, Codex, Copilot, Windsurf, or Claude Code).

Installation

You can install this package globally, as a dev dependency, or just run it via npx:

# Recommended: Run via npx
npx @georgeroberts/ai-workflows init

# Or install as a dev dependency
npm install -D @georgeroberts/ai-workflows

Usage

Once installed or run via npx, the following commands are available:

Initialize Workflows

Copy all bundled workflow files into your project.

npx @georgeroberts/ai-workflows init

By default, this copies files to .ai/workflows/. You can specify a different target:

npx @georgeroberts/ai-workflows init --target cursor

Supported targets: generic (default), cursor, codex, windsurf, docs.

Use --force to overwrite existing files:

npx @georgeroberts/ai-workflows init --force

Sync Workflows

Update your project with missing workflows from the package, preserving any files you have locally modified.

npx @georgeroberts/ai-workflows sync

Add a Specific Workflow

Add a single workflow file by name.

npx @georgeroberts/ai-workflows add pwa
npx @georgeroberts/ai-workflows add deployment --target cursor

List Workflows

View all the workflow templates currently bundled in the package.

npx @georgeroberts/ai-workflows list

Run Doctor

Check your current project to see which AI workflow targets are configured and what files exist.

npx @georgeroberts/ai-workflows doctor

Template Source and Distribution Model

The package currently distributes bundled Markdown templates from templates/. init copies workflow templates plus root agent instruction files into a target project. sync adds missing workflow files while preserving local modifications unless you explicitly force an overwrite.

The source methodology lives outside the package in the repository root files (AGENTS.md, AIDLC-WORKFLOW-README.md) and workflow/. Before publishing, mirror source changes into templates/root/ and templates/workflow/ so npm installs match the current methodology.

Git submodule distribution is a future design option, not current package behavior. A likely shape is for consuming projects to pin a shared workflow/ tree as a submodule, while root agent instruction files remain copied or generated by package commands. That needs a separate design and CLI update before it becomes supported behavior.

Before publishing, verify that templates/root/AIDLC-WORKFLOW-README.md matches the root AIDLC-WORKFLOW-README.md, and that any touched templates/workflow/** files mirror the corresponding workflow/** source files.

Development & Publishing

Local Testing

1. Clone the repository and run npm install.
2. Build the package: npm run build.
3. To test locally in another project, you can run npm link in this directory, and then run ai-workflows init in your target project.

Publishing to npm

When you are ready to publish:

1. Update the version in package.json.
2. Run npm run build.
3. Log in to npm (npm login).
4. Publish the package (npm publish).

License

MIT