swarm-orchestrator 7.0.0-alpha.0

package/templates/README.md

@@ -0,0 +1,35 @@
+# Plan Templates
+
+Ready-made plan files for common project types. Copy a template and customize it
+for your project, or use them as-is with `swarm swarm <template>.json`.
+
+| Template | Steps | Agents Used | Estimated Time |
+|----------|-------|-------------|----------------|
+| [rest-api](rest-api.json) | 4 | worker, reviewer | 8-12 min |
+| [react-app](react-app.json) | 5 | worker, reviewer | 10-15 min |
+| [cli-tool](cli-tool.json) | 3 | worker, reviewer | 6-10 min |
+| [fullstack](fullstack.json) | 6 | worker, reviewer | 15-20 min |
+| [library](library.json) | 4 | worker, reviewer | 8-12 min |
+
+## Usage
+
+```bash
+# Copy a template to your plans directory
+cp templates/rest-api.json plans/my-api.json
+
+# Edit the goal and tasks to fit your project
+# Then execute:
+swarm swarm plans/my-api.json
+
+# Or run directly (uses the template as-is):
+swarm swarm templates/rest-api.json
+```
+
+## Customization
+
+Each template is a standard plan JSON file. You can:
+- Change the `goal` field to describe your specific project
+- Edit step `task` descriptions to match your requirements
+- Add or remove steps
+- Change agent assignments
+- Adjust dependencies between steps

package/templates/cli-tool.json

@@ -0,0 +1,31 @@
+{
+  "goal": "Build a CLI tool with argument parsing, commands, and tests",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Create a Node.js CLI tool: (1) Use commander or yargs for argument parsing, (2) At least 2 subcommands with options, (3) Colored output using chalk, (4) Error handling with helpful messages, (5) Add bin entry in package.json, (6) TypeScript with strict mode.",
+      "dependencies": [],
+      "expectedOutputs": ["CLI entry point", "command handlers", "package.json with bin entry"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Write tests for the CLI tool: (1) Unit tests for each command handler, (2) Integration tests that spawn the CLI process and check stdout, (3) Test error cases (missing args, invalid input), (4) Ensure all tests pass.",
+      "dependencies": [1],
+      "expectedOutputs": ["test files", "test results"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "reviewer",
+      "task": "Finalize the CLI tool: (1) Verify --help output is clear and complete, (2) Write README with installation and usage examples, (3) Add CHANGELOG.md, (4) Ensure npm link works for local testing, (5) All tests pass.",
+      "dependencies": [2],
+      "expectedOutputs": ["README.md", "CHANGELOG.md", "Working CLI"]
+    }
+  ],
+  "metadata": {
+    "totalSteps": 3,
+    "estimatedDuration": "6-10 minutes"
+  }
+}

package/templates/fullstack.json

@@ -0,0 +1,52 @@
+{
+  "goal": "Build a full-stack web application with frontend, backend, auth, security review, CI/CD, and integration",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Create backend API: (1) Express + TypeScript server, (2) JWT authentication with register/login/logout, (3) CRUD endpoints for the main resource, (4) Input validation and sanitization, (5) CORS configured for frontend origin, (6) Clear API documentation in code comments.",
+      "dependencies": [],
+      "expectedOutputs": ["server.ts", "routes", "auth middleware", "package.json"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Build frontend: (1) React + TypeScript with Vite, (2) Auth pages (login/register), (3) Main CRUD interface, (4) API integration via fetch (not local-only state), (5) Loading and error states, (6) Vite proxy for /api routes.",
+      "dependencies": [1],
+      "expectedOutputs": ["React components", "vite.config.ts", "API hooks"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Write comprehensive tests: (1) Backend unit + integration tests, (2) Frontend component tests, (3) Auth flow integration test, (4) All tests pass.",
+      "dependencies": [1, 2],
+      "expectedOutputs": ["test files", "test results"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "reviewer",
+      "task": "Security review: (1) Check for injection vulnerabilities, (2) Review JWT implementation, (3) Check dependency vulnerabilities with npm audit, (4) Review CORS configuration, (5) Document findings and fixes.",
+      "dependencies": [1, 2],
+      "expectedOutputs": ["security report", "security fixes committed"]
+    },
+    {
+      "stepNumber": 5,
+      "agentName": "worker",
+      "task": "CI/CD and deployment: (1) GitHub Actions workflow for lint + test + build, (2) Dockerfile for production, (3) docker-compose.yml for local development, (4) Environment variable documentation.",
+      "dependencies": [1],
+      "expectedOutputs": ["CI workflow", "Dockerfile", "docker-compose.yml", ".env.example"]
+    },
+    {
+      "stepNumber": 6,
+      "agentName": "reviewer",
+      "task": "Final integration: (1) Verify full end-to-end flow (register, login, CRUD), (2) Fix any field name mismatches, (3) Ensure all tests pass after security fixes, (4) Write comprehensive README, (5) Add Troubleshooting section.",
+      "dependencies": [3, 4, 5],
+      "expectedOutputs": ["README.md", "Working full-stack app", "Clean git history"]
+    }
+  ],
+  "metadata": {
+    "totalSteps": 6,
+    "estimatedDuration": "15-20 minutes"
+  }
+}

package/templates/library.json

@@ -0,0 +1,38 @@
+{
+  "goal": "Build a reusable library with TypeScript, comprehensive tests, and npm publishing configuration",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Create library core: (1) TypeScript with strict mode, (2) Dual CJS/ESM output configuration, (3) At least 3 exported functions/classes implementing the core functionality, (4) JSDoc comments on all exports, (5) types.d.ts generation, (6) package.json with proper main/module/types fields.",
+      "dependencies": [],
+      "expectedOutputs": ["src/ with library code", "tsconfig.json", "package.json"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Write comprehensive tests: (1) Unit tests for every exported function/class, (2) Edge case tests (null input, empty arrays, boundary values), (3) Type safety tests if applicable, (4) Code coverage setup and reporting, (5) All tests pass with good coverage.",
+      "dependencies": [1],
+      "expectedOutputs": ["test files", "coverage report", "test results"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Publishing and CI setup: (1) GitHub Actions for CI (lint, test, build on PR), (2) GitHub Actions for npm publish on release tag, (3) .npmignore or files field in package.json, (4) Semantic versioning setup, (5) Do not modify library code.",
+      "dependencies": [1],
+      "expectedOutputs": ["CI workflows", ".npmignore or files config"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "reviewer",
+      "task": "Finalize: (1) README with installation, API reference, and usage examples, (2) CHANGELOG.md, (3) Verify CJS and ESM imports both work, (4) All tests pass, (5) npm pack succeeds and includes only intended files.",
+      "dependencies": [2, 3],
+      "expectedOutputs": ["README.md", "CHANGELOG.md", "Working library package"]
+    }
+  ],
+  "metadata": {
+    "totalSteps": 4,
+    "estimatedDuration": "8-12 minutes"
+  }
+}

package/templates/react-app.json

@@ -0,0 +1,45 @@
+{
+  "goal": "Build a React application with component library, state management, and tests",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Create a backend API server for the React app: (1) Express server with REST endpoints for the main data model, (2) In-memory or file-based storage, (3) CORS enabled for localhost:5173, (4) Input validation. Document API field names clearly for frontend consistency.",
+      "dependencies": [],
+      "expectedOutputs": ["server.ts or server.js", "API endpoints", "package.json"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Build the React frontend: (1) Create Vite + React + TypeScript project if not exists, (2) Component hierarchy with at least 3 components, (3) State management (useState/useReducer or Zustand), (4) API integration using fetch to call backend endpoints, (5) Loading states and error handling, (6) Configure Vite proxy for /api routes.",
+      "dependencies": [1],
+      "expectedOutputs": ["React components", "vite.config.ts", "API integration code"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Write tests: (1) Unit tests for React components using Vitest + React Testing Library, (2) At least one integration test that verifies frontend calls backend API, (3) Test error states and loading states. Use the same field names as the backend API.",
+      "dependencies": [1, 2],
+      "expectedOutputs": ["test files", "test results"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "worker",
+      "task": "Set up build and deployment: (1) GitHub Actions CI workflow, (2) Production build configuration, (3) Add scripts to package.json for dev, build, test, and start. Do not modify application logic.",
+      "dependencies": [1, 2],
+      "expectedOutputs": [".github/workflows/ci.yml", "build scripts"]
+    },
+    {
+      "stepNumber": 5,
+      "agentName": "reviewer",
+      "task": "Final integration: (1) Verify frontend actually calls backend API (not just local state), (2) Fix any field name mismatches between frontend and backend, (3) Ensure all tests pass, (4) Write README with setup instructions, (5) Add Troubleshooting section to README.",
+      "dependencies": [3, 4],
+      "expectedOutputs": ["README.md", "All tests passing", "Working full-stack app"]
+    }
+  ],
+  "metadata": {
+    "totalSteps": 5,
+    "estimatedDuration": "10-15 minutes"
+  }
+}

package/templates/recipes/add-api-docs.json

@@ -0,0 +1,35 @@
+{
+  "name": "add-api-docs",
+  "description": "Generate OpenAPI spec and API documentation",
+  "category": "documentation",
+  "parameters": {
+    "format": {
+      "description": "Documentation output format",
+      "default": "openapi",
+      "options": ["openapi", "markdown"]
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Analyze all API routes and generate an OpenAPI 3.0 specification (openapi.yaml). Include: all endpoints with methods, request/response schemas, authentication requirements, and example values. If format is 'markdown', also produce a Markdown version.",
+      "dependencies": [],
+      "expectedOutputs": ["openapi.yaml"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Add JSDoc or inline documentation comments to all route handlers and middleware. Each handler should document its purpose, parameters, request body shape, and response codes.",
+      "dependencies": [],
+      "expectedOutputs": ["documented route handlers"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "reviewer",
+      "task": "Validate the OpenAPI spec is syntactically correct. Cross-check that every route in the codebase has a corresponding spec entry. Update README with a link to the API docs and instructions for viewing them.",
+      "dependencies": [1, 2],
+      "expectedOutputs": ["validated openapi.yaml", "updated README"]
+    }
+  ]
+}

package/templates/recipes/add-auth.json

@@ -0,0 +1,47 @@
+{
+  "name": "add-auth",
+  "description": "Add authentication (JWT or session-based) to an existing app",
+  "category": "feature",
+  "parameters": {
+    "auth-type": {
+      "description": "Authentication strategy",
+      "default": "jwt",
+      "options": ["jwt", "session"]
+    },
+    "provider": {
+      "description": "OAuth provider to integrate (or none for local-only auth)",
+      "default": "none",
+      "options": ["none", "github", "google"]
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Add user registration and login endpoints using {{auth-type}} authentication. Create user model/schema, password hashing with bcrypt, and token generation. If provider is not 'none', add OAuth flow for {{provider}}.",
+      "dependencies": [],
+      "expectedOutputs": ["auth routes", "user model", "auth middleware"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Add auth middleware that protects existing routes. Add role-based access control if the app has admin functionality. Ensure unauthenticated requests return 401.",
+      "dependencies": [1],
+      "expectedOutputs": ["auth middleware applied to routes", "401 responses for unauthenticated requests"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Write tests for authentication: registration, login, token validation, protected route access (valid token, expired token, no token), and logout if applicable. All tests must pass.",
+      "dependencies": [2],
+      "expectedOutputs": ["auth test files", "all tests passing"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "reviewer",
+      "task": "Verify end-to-end auth flow works. Create .env.example with required auth environment variables. Update README with authentication setup instructions and API endpoint documentation.",
+      "dependencies": [3],
+      "expectedOutputs": [".env.example", "updated README"]
+    }
+  ]
+}

package/templates/recipes/add-ci.json

@@ -0,0 +1,39 @@
+{
+  "name": "add-ci",
+  "description": "Add GitHub Actions CI pipeline with lint, test, and build",
+  "category": "devops",
+  "parameters": {
+    "node-version": {
+      "description": "Node.js version for the CI runner",
+      "default": "20"
+    },
+    "package-manager": {
+      "description": "Package manager used by the project",
+      "default": "npm",
+      "options": ["npm", "yarn", "pnpm"]
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Create a GitHub Actions CI workflow at .github/workflows/ci.yml. It should: (1) trigger on push to main and pull requests, (2) use Node.js {{node-version}}, (3) install dependencies with {{package-manager}}, (4) run lint if a lint script exists, (5) run tests, (6) run build if a build script exists. Include caching for node_modules.",
+      "dependencies": [],
+      "expectedOutputs": [".github/workflows/ci.yml"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Add a Dockerfile for containerized deployment. Include a .dockerignore file. Ensure the container runs the built application. Add health check if the project is a server.",
+      "dependencies": [],
+      "expectedOutputs": ["Dockerfile", ".dockerignore"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "reviewer",
+      "task": "Validate the CI workflow YAML is syntactically correct. Verify the Dockerfile builds successfully (dry run). Update README with CI badge and deployment instructions.",
+      "dependencies": [1, 2],
+      "expectedOutputs": ["updated README with CI badge"]
+    }
+  ]
+}

package/templates/recipes/add-tests.json

@@ -0,0 +1,39 @@
+{
+  "name": "add-tests",
+  "description": "Add unit tests for untested modules",
+  "category": "testing",
+  "parameters": {
+    "framework": {
+      "description": "Test framework to use",
+      "default": "mocha",
+      "options": ["mocha", "jest", "vitest"]
+    },
+    "coverage-target": {
+      "description": "Minimum coverage percentage to target",
+      "default": "80"
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Analyze the project to identify all modules without test coverage. List each untested file and its exported functions. Determine the test framework ({{framework}}) and write a test plan. Do not write tests yet.",
+      "dependencies": [],
+      "expectedOutputs": ["test plan or analysis output"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Write unit tests for the untested modules identified in step 1 using {{framework}}. Target {{coverage-target}}% coverage. Each test file should cover: happy path, edge cases, and error conditions. Ensure all tests pass.",
+      "dependencies": [1],
+      "expectedOutputs": ["test files", "passing test results"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "reviewer",
+      "task": "Run the full test suite and verify all new and existing tests pass. Fix any integration issues. Update README if test running instructions are missing or outdated.",
+      "dependencies": [2],
+      "expectedOutputs": ["all tests passing", "updated README if needed"]
+    }
+  ]
+}

package/templates/recipes/migrate-to-ts.json

@@ -0,0 +1,42 @@
+{
+  "name": "migrate-to-ts",
+  "description": "Migrate a JavaScript project to TypeScript",
+  "category": "migration",
+  "parameters": {
+    "strictness": {
+      "description": "TypeScript strictness level",
+      "default": "strict",
+      "options": ["strict", "moderate", "loose"]
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Initialize TypeScript: install typescript and @types packages, create tsconfig.json with {{strictness}} settings (strict: all strict flags on, moderate: strict but no exactOptionalPropertyTypes, loose: noImplicitAny only). Configure paths, outDir, and include/exclude patterns.",
+      "dependencies": [],
+      "expectedOutputs": ["tsconfig.json", "package.json updated with typescript dependency"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Rename .js files to .ts (or .jsx to .tsx). Add type annotations to function parameters and return types. Fix any 'any' types with proper interfaces. Do not change runtime behavior.",
+      "dependencies": [1],
+      "expectedOutputs": ["renamed .ts files", "type annotations added"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Update test configuration for TypeScript (ts-node, ts-jest, or vitest). Rename test files to .test.ts. Fix type errors in tests. Verify all tests still pass after migration.",
+      "dependencies": [2],
+      "expectedOutputs": ["renamed test files", "all tests passing"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "reviewer",
+      "task": "Run tsc with zero errors. Update build scripts in package.json. Update CI configuration if present. Remove any leftover .js source files that have .ts equivalents. Update README with TypeScript build instructions.",
+      "dependencies": [3],
+      "expectedOutputs": ["clean tsc compilation", "updated package.json scripts", "updated README"]
+    }
+  ]
+}

package/templates/recipes/refactor-modularize.json

@@ -0,0 +1,44 @@
+{
+  "name": "refactor-modularize",
+  "description": "Break monolithic code into smaller, focused modules",
+  "category": "refactoring",
+  "parameters": {
+    "target": {
+      "description": "File or directory to refactor (default: largest file)"
+    },
+    "max-lines": {
+      "description": "Maximum lines per module after refactoring",
+      "default": "300"
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Analyze {{target}} and identify logical boundaries for extraction. Group related functions, classes, and types. Produce a refactoring plan listing each new module, what it will contain, and which imports change. Target {{max-lines}} lines per module.",
+      "dependencies": [],
+      "expectedOutputs": ["refactoring plan"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Execute the refactoring plan from step 1: extract modules, move code, update imports and exports. Each new module should have a single clear responsibility. Preserve all existing public API surface (re-export from the original file if needed).",
+      "dependencies": [1],
+      "expectedOutputs": ["new module files", "updated imports"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Run the full test suite and verify no regressions. If tests reference internal functions that moved, update the imports. Add tests for any newly exposed module boundaries.",
+      "dependencies": [2],
+      "expectedOutputs": ["all tests passing"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "reviewer",
+      "task": "Verify the build compiles cleanly with no errors or warnings. Check that no circular dependencies were introduced. Update documentation to reflect the new module structure.",
+      "dependencies": [3],
+      "expectedOutputs": ["clean build", "updated documentation"]
+    }
+  ]
+}

package/templates/recipes/security-audit.json

@@ -0,0 +1,35 @@
+{
+  "name": "security-audit",
+  "description": "Run security audit and fix findings",
+  "category": "security",
+  "parameters": {
+    "severity": {
+      "description": "Minimum severity level to fix",
+      "default": "high",
+      "options": ["critical", "high", "moderate"]
+    }
+  },
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Run npm audit (or equivalent) and review all dependencies for known vulnerabilities. Identify all findings at {{severity}} level or above. List each vulnerability, affected package, and recommended fix.",
+      "dependencies": [],
+      "expectedOutputs": ["security audit report"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Fix the vulnerabilities found in step 1: update affected packages, apply patches, or replace insecure dependencies. For code-level issues (SQL injection, XSS, path traversal), fix the vulnerable code patterns. Do not introduce breaking changes.",
+      "dependencies": [1],
+      "expectedOutputs": ["updated package.json", "fixed source files"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "reviewer",
+      "task": "Re-run the security audit and verify all findings at {{severity}} level or above are resolved. Run the test suite to confirm no regressions. Document the fixes in a SECURITY-FIXES.md file.",
+      "dependencies": [2],
+      "expectedOutputs": ["clean audit result", "all tests passing", "SECURITY-FIXES.md"]
+    }
+  ]
+}

package/templates/rest-api.json

@@ -0,0 +1,38 @@
+{
+  "goal": "Build a REST API with authentication, CRUD endpoints, and tests",
+  "createdAt": "2025-01-01T00:00:00.000Z",
+  "steps": [
+    {
+      "stepNumber": 1,
+      "agentName": "worker",
+      "task": "Create a Node.js/Express REST API with: (1) User authentication endpoints (register, login, logout) using JWT, (2) CRUD endpoints for the main resource, (3) Input validation and error handling, (4) CORS configuration. Use TypeScript if the project supports it.",
+      "dependencies": [],
+      "expectedOutputs": ["server.ts or server.js", "route files", "auth middleware", "package.json with dependencies"]
+    },
+    {
+      "stepNumber": 2,
+      "agentName": "worker",
+      "task": "Write comprehensive tests for the REST API: (1) Unit tests for auth middleware, (2) Integration tests for all endpoints using supertest, (3) Edge case tests (invalid input, unauthorized access, missing fields). Ensure all tests pass.",
+      "dependencies": [1],
+      "expectedOutputs": ["test files", "test results showing all passing"]
+    },
+    {
+      "stepNumber": 3,
+      "agentName": "worker",
+      "task": "Set up CI/CD and deployment config: (1) GitHub Actions workflow for lint + test on PR, (2) Dockerfile for containerized deployment, (3) Environment variable configuration (.env.example). Do not modify application code.",
+      "dependencies": [1],
+      "expectedOutputs": [".github/workflows/ci.yml", "Dockerfile", ".env.example"]
+    },
+    {
+      "stepNumber": 4,
+      "agentName": "reviewer",
+      "task": "Final integration: (1) Verify all endpoints work end-to-end, (2) Ensure README documents all API endpoints with example requests, (3) Verify CI workflow syntax is valid, (4) Fix any integration issues between components.",
+      "dependencies": [2, 3],
+      "expectedOutputs": ["Updated README.md", "All tests passing", "Clean git history"]
+    }
+  ],
+  "metadata": {
+    "totalSteps": 4,
+    "estimatedDuration": "8-12 minutes"
+  }
+}