workflow-agent-cli

A self-evolving workflow management system for AI-friendly development

Workflow Agent is a portable, framework-agnostic CLI tool that brings structure and consistency to your development workflow. It enforces branch naming conventions, validates commit messages, and includes a self-improvement system that learns from community feedback.

🎯 Perfect for:

• AI agent development with strict workflow requirements
• Teams maintaining multiple repositories
• Open source projects enforcing contribution guidelines
• Any project needing consistent branch/commit patterns

✨ Features

• 🎯 Scope-based workflow - Organize work with preset or custom scopes
• ✅ Branch validation - <type>/<scope>/<description> format enforcement
• 📝 Commit validation - Conventional commits: type(scope): description
• 🔍 Smart suggestions - Did-you-mean corrections for typos
• 🎨 Framework detection - Auto-detects Next.js, Vite, Remix, Astro, SvelteKit
• 📦 5 preset libraries - SaaS (17), Library (10), API (13), E-commerce (12), CMS (13)
• 🎨 Custom scope builder - Create domain-specific scope packages with scope:create
• 🔄 Scope migration - Convert inline scopes to reusable packages with scope:migrate
• 🚀 Interactive CLI - Beautiful prompts with @clack/prompts
• 🤖 Non-interactive mode - CI/CD friendly with --preset --name --yes

🚀 Installation

Global Installation

# npm
npm install -g workflow-agent-cli

# pnpm
pnpm add -g workflow-agent-cli

# yarn
yarn global add workflow-agent-cli

Local Installation (Per-Project)

# npm
npm install -D workflow-agent-cli

# pnpm
pnpm add -D workflow-agent-cli

# yarn
yarn add -D workflow-agent-cli

⚠️ pnpm users: pnpm blocks postinstall scripts by default. After installation, run the setup command to add workflow scripts to your package.json:

pnpm workflow-agent setup

On install (npm/yarn) or after running setup (pnpm), 31 workflow scripts are automatically added to your package.json:

{
  "scripts": {
    // Core Commands
    "workflow:init": "workflow-agent init",
    "workflow:validate": "workflow-agent validate",
    "workflow:config": "workflow-agent config",
    "workflow:suggest": "workflow-agent suggest",
    "workflow:setup": "workflow-agent setup",
    "workflow:doctor": "workflow-agent doctor",

    // Scope Commands
    "workflow:scope:create": "workflow-agent scope:create",
    "workflow:scope:migrate": "workflow-agent scope:migrate",

    // Verification
    "workflow:verify": "workflow-agent verify",
    "workflow:verify:fix": "workflow-agent verify --fix",
    "workflow:auto-setup": "workflow-agent auto-setup",

    // Learning System
    "workflow:learn": "workflow-agent learn:list",
    "workflow:learn:record": "workflow-agent learn:record",
    "workflow:learn:list": "workflow-agent learn:list",
    "workflow:learn:apply": "workflow-agent learn:apply",
    "workflow:learn:sync": "workflow-agent learn:sync",
    "workflow:learn:config": "workflow-agent learn:config",
    "workflow:learn:deprecate": "workflow-agent learn:deprecate",
    "workflow:learn:stats": "workflow-agent learn:stats",

    // Solution Patterns
    "workflow:solution": "workflow-agent solution:list",
    "workflow:solution:capture": "workflow-agent solution:capture",
    "workflow:solution:search": "workflow-agent solution:search",
    "workflow:solution:list": "workflow-agent solution:list",
    "workflow:solution:apply": "workflow-agent solution:apply",
    "workflow:solution:deprecate": "workflow-agent solution:deprecate",
    "workflow:solution:stats": "workflow-agent solution:stats",

    // Advisory Board
    "workflow:advisory": "workflow-agent advisory",
    "workflow:advisory:quick": "workflow-agent advisory --depth quick",
    "workflow:advisory:standard": "workflow-agent advisory --depth standard",
    "workflow:advisory:comprehensive": "workflow-agent advisory --depth comprehensive",
    "workflow:advisory:executive": "workflow-agent advisory --depth executive",
    "workflow:advisory:ci": "workflow-agent advisory --ci"
  }
}

Note: When you update the package, any new scripts from newer versions are automatically added.

📖 Quick Start

1. Initialize Your Project

Interactive Mode

# If installed globally:
workflow-agent init

# If installed locally:
pnpm workflow-agent init
# or
npx workflow-agent init
# or (after running setup):
pnpm run workflow:init

Prompts you to:

1. Enter project name
2. Choose a preset (SaaS, Library, API, E-commerce, CMS, Custom)
3. Generate guidelines (optional)

Non-Interactive Mode

# Perfect for CI/CD or automation

# Global:
workflow-agent init --preset library --name my-project --yes

# Local:
pnpm workflow-agent init --preset library --name my-project --yes

2. Validate Your Work

# Validate branch names
workflow-agent validate branch
workflow-agent validate branch "feature/auth/add-login"

# Validate commit messages
workflow-agent validate commit "feat(auth): add OAuth support"

Expected formats:

• Branch: <type>/<scope>/<description>

  • Types: feature, bugfix, hotfix, chore, refactor, docs, test
  • Example: feature/auth/implement-2fa

• Commit: <type>(<scope>): <description>

  • Types: feat, fix, refactor, chore, docs, test, perf, style, ci, build
  • Example: feat(auth): implement 2FA with TOTP

3. Create Custom Scopes

Build reusable scope packages for your domain:

workflow-agent scope:create

# Follow the interactive prompts to:
# 1. Name your scope package (e.g., "medical", "finance", "gaming")
# 2. Define scopes (e.g., "patient", "appointment", "billing")
# 3. Add descriptions for each scope
# 4. Choose package location

4. Migrate Inline Scopes

Convert inline scopes to reusable packages:

workflow-agent scope:migrate

# Extracts scopes from workflow.config.json
# Creates a new scope package
# Updates config to reference the package

🛠️ Commands

| Command | Description | | ------------------------------------------ | ------------------------------------------- | | workflow-agent init | Initialize project with interactive prompts | | workflow-agent validate branch [name] | Validate branch name format | | workflow-agent validate commit [message] | Validate commit message format | | workflow-agent config get [key] | View configuration values | | workflow-agent config set <key> <value> | Update configuration | | workflow-agent suggest <idea> | Submit improvement suggestion | | workflow-agent doctor | Run health checks and get optimization tips | | workflow-agent scope:create | Create a custom scope package | | workflow-agent scope:migrate | Migrate inline scopes to package | | workflow-agent learn:record | Record a new fix pattern or blueprint | | workflow-agent learn:list | List recorded patterns | | workflow-agent learn:apply <id> | Apply a pattern to current project | | workflow-agent learn:sync | Sync patterns with community registry | | workflow-agent learn:config | Configure learning settings | | workflow-agent learn:stats | View learning statistics |

Command Options

init

• --preset <name> - Skip preset selection (saas, library, api, ecommerce, cms, custom)
• --name <name> - Set project name without prompt
• --yes - Accept all defaults (non-interactive)

validate

• --fix - Apply automatic fixes (coming soon)
• --json - Output in JSON format

suggest

• --category <type> - Suggestion category (feature, bug, improvement, documentation)
• --author <name> - Your name or username

learn:record

• --type <type> - Pattern type: fix or blueprint
• --name <name> - Human-readable pattern name
• --description <desc> - What the pattern does
• --category <cat> - Fix category: lint, type-error, dependency, config, etc.
• --framework <fw> - Target framework: next, react, vue, etc.
• --version <ver> - Semver version range

learn:list

• --type <type> - Filter by pattern type
• --framework <fw> - Filter by framework
• --deprecated - Include deprecated patterns

learn:config

• --enable-telemetry - Enable anonymous usage telemetry
• --disable-telemetry - Disable telemetry
• --enable-sync - Enable community pattern sync
• --disable-sync - Disable sync

📦 Preset Scope Libraries

SaaS (17 scopes)

auth, billing, analytics, notifications, teams, admin, api, integration, subscription, dashboard, onboarding, settings, payments, reports, support, webhooks, search

Library (10 scopes)

core, utils, types, config, cli, api, docs, examples, test, build

API (13 scopes)

routes, middleware, controllers, models, services, auth, validation, errors, logging, cache, queue, websocket, graphql

E-commerce (12 scopes)

products, cart, checkout, orders, payments, shipping, inventory, customers, reviews, discounts, recommendations, analytics

CMS (13 scopes)

content, media, pages, posts, categories, tags, users, comments, seo, templates, widgets, api, admin

🎨 Custom Scopes

Create domain-specific scope packages:

workflow-agent scope:create

Example: Medical Scope Package

// packages/scopes-medical/src/index.ts
export default {
  scopes: [
    { name: "patient", description: "Patient records and profiles" },
    { name: "appointment", description: "Scheduling and appointments" },
    { name: "billing", description: "Medical billing and insurance" },
    { name: "prescription", description: "Prescriptions and medications" },
    { name: "lab", description: "Laboratory tests and results" },
  ],
};

Use in workflow.config.json:

{
  "name": "medical-app",
  "scopesSource": "packages/scopes-medical"
}

For detailed instructions, see the Custom Scopes Documentation.

🐛 Troubleshooting

Installation Issues

pnpm Installation with Postinstall

If you're using pnpm, postinstall scripts are blocked by default. Run setup manually:

pnpm add -D workflow-agent-cli
pnpm workflow-agent setup

Permission Errors (Global Install)

# Linux/macOS
sudo npm install -g workflow-agent-cli

# Or use nvm to avoid sudo
nvm use system
npm install -g workflow-agent-cli

Publishing Issues (For Contributors)

npm Token Errors

Error: "Access token expired or revoked" or "404 Not Found"

This typically means your npm token doesn't have the correct permissions. To fix:

1. Create a Granular Access Token on npm:

   • Go to https://www.npmjs.com/ → Profile → Access Tokens
   • Click "Generate New Token" → Select "Granular Access Token"
   • Configure:
     • Packages and scopes: Select "All packages" + "Read and write"
     • Organizations: Leave unchecked/empty (unless publishing under an org)
     • Token type: Should support automation/bypass 2FA
   • Copy the token immediately

2. Test the token locally:

   echo '//registry.npmjs.org/:_authToken=YOUR_TOKEN' > ~/.npmrc
   npm whoami  # Should show your npm username
   cd packages/core
   npm publish --access public --dry-run  # Should succeed

3. Update GitHub Secret:

   • Go to your repo → Settings → Secrets and variables → Actions
   • Update NPM_TOKEN with the exact token that works locally

Error: "This operation requires a one-time password (EOTP)"

Your npm account has 2FA enabled. Options:

1. Use an Automation token that bypasses 2FA (recommended)
2. Disable 2FA for publishing (keeps it for login):
   • Go to npm → Account Settings → Two-Factor Authentication
   • Change from "Authorization and Publishing" to "Authorization only"

Package Name Conflicts

Error: "must not have multiple workspaces with the same name"

If you have workspace packages with duplicate names:

1. Check all package.json files in packages/*/package.json
2. Rename conflicting packages:

   # Example: rename vscode-extension to avoid conflict
   # packages/vscode-extension/package.json
   { "name": "workflow-agent-vscode" }

3. Update imports in dependent packages
4. Run pnpm install to update lockfile

Lockfile Out of Sync

Error: "Cannot install with frozen-lockfile because pnpm-lock.yaml is not up to date"

After changing package dependencies:

pnpm install  # Update lockfile
git add pnpm-lock.yaml
git commit -m "chore: update lockfile"

Build Issues

TypeScript Compilation Errors

Error: "Cannot find module 'workflow-agent-cli/config'"

This means the core package wasn't built before dependent packages:

# Build core package first
pnpm --filter workflow-agent-cli run build

# Then build everything
pnpm build

Fix permanently by updating the root package.json:

{
  "scripts": {
    "build": "pnpm --filter workflow-agent-cli run build && pnpm -r run build"
  }
}

Template Issues

Error: Guidelines directory not created

If templates aren't bundled with the npm package:

1. Ensure templates are in the package:

   // packages/core/package.json
   {
     "files": ["dist", "templates"]
   }

2. Copy templates to package directory:

   cp -r templates packages/core/

3. Update template paths in code to use relative paths from the package

🤝 Contributing

Contributions are welcome! Please see our Contributing Guide.

Development Setup

# Clone the repository
git clone https://github.com/hawkinsideOut/workflow-agent.git
cd workflow-agent

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run the CLI locally
node packages/core/dist/cli/index.js --help

📄 License

MIT © Workflow Agent Team

See LICENSE for details.

🔗 Links

• GitHub Repository
• npm Package
• Documentation
• Custom Scopes Guide
• Issue Tracker
• Changelog

Made with ❤️ for developers who value consistency and automation