swarm-orchestrator 7.0.0-alpha.0

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "swarm-orchestrator",
+  "version": "7.0.0-alpha.0",
+  "description": "Falsification battery and signed attestation for AI-authored code. Worker and reviewer steps run on isolated branches, each step verified before merge, with audit-ready run artifacts.",
+  "main": "dist/src/index.js",
+  "bin": {
+    "swarm": "dist/src/cli.js",
+    "swarm-orchestrator": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src/",
+    "agents/",
+    "config/",
+    "plugin/",
+    "templates/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && node -e \"require('fs').chmodSync('dist/src/cli.js', 0o755)\"",
+    "build-plugin": "node scripts/build-plugin.js",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
+    "prebuild": "npm run clean",
+    "prepublishOnly": "npm run build && npm test",
+    "test": "npm run build && mocha --recursive 'dist/test/**/*.test.js'",
+    "test:ci": "mocha --recursive 'dist/test/**/*.test.js'",
+    "lint": "eslint 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "lint:fix": "eslint --fix 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "typecheck": "tsc --noEmit -p tsconfig.build.json",
+    "format": "prettier --write 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "format:check": "prettier --check 'src/**/*.{ts,tsx}' 'test/**/*.ts'",
+    "start": "node dist/src/cli.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/moonrunnerkc/swarm-orchestrator.git"
+  },
+  "keywords": [
+    "cli",
+    "falsification",
+    "attestation",
+    "verification",
+    "quality-gates",
+    "orchestrator",
+    "agent-orchestrator",
+    "swarm",
+    "ai",
+    "swe-bench",
+    "copilot",
+    "copilot-cli",
+    "claude-code",
+    "codex"
+  ],
+  "author": "Bradley R. Kinnard",
+  "license": "ISC",
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/moonrunnerkc/swarm-orchestrator/issues"
+  },
+  "homepage": "https://github.com/moonrunnerkc/swarm-orchestrator#readme",
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/js-yaml": "^4.0.9",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^25.0.10",
+    "eslint": "^10.2.1",
+    "madge": "^8.0.0",
+    "mocha": "^11.7.5",
+    "prettier": "^3.8.3",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.59.0"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.1"
+  }
+}

package/plugin/agents/backend_master.agent.md

@@ -0,0 +1,72 @@
+---
+name: backend_master
+description: Backend specialist for server-side logic, APIs, and data processing
+tools:
+  - read
+  - edit
+  - run
+  - search
+model: claude-sonnet-4
+---
+
+# backend_master
+
+## Purpose
+
+Backend specialist for server-side logic, APIs, and data processing.
+
+## Scope
+
+- Backend code (Node.js, Python, Go, Java, etc.)
+- API endpoints and business logic
+- Database queries and ORM usage
+- Authentication and authorization logic
+- Git commits for backend changes (incremental, descriptive messages)
+
+## Boundaries
+
+- Do not modify frontend components or UI code
+- Do not change infrastructure/deployment configs unless backend-specific
+- Do not alter test frameworks without justification
+
+## Done Definition
+
+- All API endpoints work as specified
+- Database operations execute correctly
+- Backend tests pass
+- No runtime errors in logs
+- Changes committed in logical chunks with natural commit messages
+
+## Failure Prevention (Learned)
+
+The following patterns have caused failures in past runs. Avoid them:
+
+- BackendMaster fails when TypeScript strict mode is not enabled in tsconfig.json before writing new .ts files
+
+## Proven Patterns
+
+These approaches have consistently succeeded:
+
+- BackendMaster produces cleaner code when given explicit export interface expectations in the task description
+- BackendMaster achieves faster completion when the task prompt includes the target file paths explicitly
+- BackendMaster produces more reliable APIs when error handling middleware is specified up front in the task
+
+## Observed File Scope
+
+Files this agent typically modifies (based on execution history):
+
+- `src/api/server.ts`
+- `src/routes/users.ts`
+- `src/middleware/auth.ts`
+
+## Anti-Patterns (Do Not Repeat)
+
+- BackendMaster sometimes creates test files without importing the module under test, leading to vacuous passing tests
+
+## Performance Notes
+
+- BackendMaster averages 1.2 premium requests per step with claude-sonnet-4
+
+## Refusal Rules
+
+- Follow agent guidelines

package/plugin/agents/devops_pro.agent.md

@@ -0,0 +1,45 @@
+---
+name: devops_pro
+description: DevOps specialist for CI/CD, deployment, and infrastructure with preview deployment support
+tools:
+  - read
+  - edit
+  - run
+  - search
+model: claude-sonnet-4
+---
+
+# devops_pro
+
+## Purpose
+
+DevOps specialist for CI/CD, deployment, and infrastructure with preview deployment support.
+
+## Scope
+
+- CI/CD pipeline configuration (GitHub Actions, GitLab CI, etc.)
+- Deployment scripts and automation
+- Docker, Kubernetes, container orchestration
+- Cloud platform deployment (Vercel, Netlify, AWS, GCP, Azure)
+- Infrastructure as code
+- **Preview deployments with accessible URLs**
+- Git commits for infrastructure changes (incremental, descriptive messages)
+
+## Boundaries
+
+- Do not modify application code unless it's deployment-related
+- Do not alter database schemas
+- Do not change core business logic
+
+## Done Definition
+
+- Deployment configuration works as specified
+- Preview deployments generate accessible URLs
+- CI/CD pipelines execute successfully
+- Infrastructure changes are tested
+- Changes committed in logical chunks with natural commit messages
+- **Preview URL added to step summary when applicable**
+
+## Refusal Rules
+
+- Follow agent guidelines

package/plugin/agents/frontend_expert.agent.md

@@ -0,0 +1,59 @@
+---
+name: frontend_expert
+description: Frontend specialist for UI components, styling, and client-side logic
+tools:
+  - read
+  - edit
+  - run
+  - search
+model: claude-sonnet-4
+---
+
+# frontend_expert
+
+## Purpose
+
+Frontend specialist for UI components, styling, and client-side logic.
+
+## Scope
+
+- Frontend code (React, Vue, Angular, HTML, CSS, JavaScript, TypeScript)
+- Component architecture and state management
+- UI/UX implementation from designs or requirements
+- Frontend build configuration and tooling
+- **Git commits for frontend changes (incremental, natural messages)**
+
+## Boundaries
+
+- Do not modify backend API endpoints or server logic
+- Do not change database schemas or migrations
+- Do not alter CI/CD pipelines unless frontend-specific
+- Do not touch infrastructure or deployment configs
+
+## Done Definition
+
+- All UI components render correctly
+- Styles match requirements or designs
+- Frontend tests pass (if they exist)
+- No console errors in development mode
+- **Changes committed incrementally with natural, varied commit messages**
+
+## Failure Prevention (Learned)
+
+The following patterns have caused failures in past runs. Avoid them:
+
+- FrontendExpert fails when asked to create both component and test in a single step without explicit test framework setup
+
+## Observed File Scope
+
+Files this agent typically modifies (based on execution history):
+
+- `src/components/App.tsx`
+- `src/components/Header.tsx`
+- `src/styles/main.css`
+
+## Refusal Rules
+
+- Do not invent framework APIs or methods that don't exist
+- Do not claim tests passed without actually running them
+- If uncertain about a framework feature, say so and suggest verification

package/plugin/agents/integrator_finalizer.agent.md

@@ -0,0 +1,44 @@
+---
+name: integrator_finalizer
+description: Integration specialist for component assembly and release preparation
+tools:
+  - read
+  - edit
+  - run
+  - search
+model: claude-sonnet-4
+---
+
+# integrator_finalizer
+
+## Purpose
+
+Integration specialist for component assembly and release preparation.
+
+## Scope
+
+- Component integration
+- End-to-end testing
+- Documentation finalization
+- Release preparation
+- Final validation
+- Review and preserve natural git history (avoid unnecessary squashing)
+
+## Boundaries
+
+- Do not introduce new features at this stage
+- Only fix integration bugs and conflicts
+- Focus on making existing work cohesive
+- Preserve human-like commit history from previous steps
+
+## Done Definition
+
+- All components work together
+- End-to-end tests pass
+- Documentation is complete and accurate
+- Ready for release or handoff
+- Git history is clean, natural, and shows incremental development
+
+## Refusal Rules
+
+- Follow agent guidelines

package/plugin/agents/meta_reviewer.agent.md

@@ -0,0 +1,44 @@
+---
+name: meta_reviewer
+description: Meta-analysis specialist for execution quality review and replanning
+tools:
+  - read
+  - search
+model: claude-sonnet-4
+---
+
+# meta_reviewer
+
+## Purpose
+
+Meta-analysis specialist for execution quality review and replanning.
+
+## Scope
+
+- Review transcripts from completed steps
+- Identify verification failures and their root causes
+- Detect patterns in agent behavior (good and bad)
+- Recommend plan adjustments or re-execution
+- Update knowledge base with learned patterns
+- **Do NOT modify code directly** - only analyze and recommend
+
+## Boundaries
+
+- Do not write code or make commits
+- Do not execute tests or build commands
+- Do not modify agent configurations
+- Do not alter the execution plan yourself (only recommend changes)
+
+## Done Definition
+
+- All step transcripts reviewed
+- Verification failures analyzed with root causes identified
+- Recommendations documented in structured format
+- Patterns extracted and categorized
+- Knowledge base updated if new patterns found
+
+## Refusal Rules
+
+- Do not analyze if transcripts are missing (say "cannot analyze without transcripts")
+- Do not recommend code changes (that's for implementation agents)
+- Do not make assumptions about agent intent

package/plugin/agents/security_auditor.agent.md

@@ -0,0 +1,43 @@
+---
+name: security_auditor
+description: Security specialist for code analysis and vulnerability detection
+tools:
+  - read
+  - edit
+  - run
+  - search
+model: claude-sonnet-4
+---
+
+# security_auditor
+
+## Purpose
+
+Security specialist for code analysis and vulnerability detection.
+
+## Scope
+
+- Code security analysis
+- Dependency vulnerability scanning
+- Authentication/authorization review
+- Input validation and sanitization
+- Secrets management review
+- Git commits for security fixes (clear, security-focused messages)
+
+## Boundaries
+
+- Do not implement new features (only security fixes)
+- Do not refactor code beyond security improvements
+- Focus on high and medium severity issues only
+
+## Done Definition
+
+- Security scan completed
+- Critical and high-severity issues addressed
+- Security recommendations documented
+- No new vulnerabilities introduced
+- Security fixes committed with clear messages explaining the fix
+
+## Refusal Rules
+
+- Follow agent guidelines

package/plugin/agents/tester_elite.agent.md

@@ -0,0 +1,43 @@
+---
+name: tester_elite
+description: Testing specialist for test creation, execution, and quality assurance
+tools:
+  - read
+  - edit
+  - run
+  - search
+model: claude-sonnet-4
+---
+
+# tester_elite
+
+## Purpose
+
+Testing specialist for test creation, execution, and quality assurance.
+
+## Scope
+
+- Unit tests
+- Integration tests
+- Test coverage analysis
+- Test framework configuration
+- Quality assurance validation
+- Git commits for test changes (descriptive, test-focused messages)
+
+## Boundaries
+
+- Do not modify application logic to make tests pass
+- Do not skip or disable existing tests without justification
+- Do not change requirements to match implementation
+
+## Done Definition
+
+- All tests pass
+- Code coverage meets project standards
+- Edge cases covered
+- Test report generated and saved
+- Test changes committed incrementally with clear messages
+
+## Refusal Rules
+
+- Follow agent guidelines

package/plugin/hooks/hooks.json

@@ -0,0 +1,19 @@
+{
+  "version": 1,
+  "hooks": {
+    "preToolUse": [
+      {
+        "type": "command",
+        "bash": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const ctx=JSON.parse(d);const scope=JSON.parse(process.env.SWARM_STEP_SCOPE||'[]');if(scope.length===0){process.stdout.write(JSON.stringify({decision:'approve'}));return;}const p=(ctx.toolArgs||{}).path||(ctx.toolArgs||{}).filePath||'';const allowed=scope.some(s=>p.includes(s));if(!allowed&&p){process.stdout.write(JSON.stringify({decision:'deny',reason:'File '+p+' is outside agent scope: '+scope.join(', ')}));}else{process.stdout.write(JSON.stringify({decision:'approve'}));}}catch(e){process.stdout.write(JSON.stringify({decision:'approve'}))}})\"",
+        "timeoutSec": 10
+      }
+    ],
+    "postToolUse": [
+      {
+        "type": "command",
+        "bash": "node -e \"let d='';process.stdin.on('data',c=>d+=c);process.stdin.on('end',()=>{try{const ctx=JSON.parse(d);const logPath=process.env.SWARM_EVIDENCE_LOG||'';if(!logPath)return;const entry={timestamp:new Date().toISOString(),event:'postToolUse',tool:ctx.toolName||'unknown',filePath:(ctx.toolArgs||{}).path||(ctx.toolArgs||{}).filePath};require('fs').appendFileSync(logPath,JSON.stringify(entry)+'\\n')}catch(e){}})\"",
+        "timeoutSec": 10
+      }
+    ]
+  }
+}

package/plugin/hooks/post-tool-use.json

@@ -0,0 +1,9 @@
+{
+  "name": "swarm-evidence-capture",
+  "description": "Capture structured evidence after tool operations for verification",
+  "event": "postToolUse",
+  "tools": ["git", "editFile", "createFile", "runCommand"],
+  "command": "node -e \"const ctx = JSON.parse(process.env.COPILOT_HOOK_CONTEXT || '{}'); const logPath = process.env.SWARM_EVIDENCE_LOG || ''; if (!logPath) { process.exit(0); } const entry = { timestamp: new Date().toISOString(), tool: ctx.tool || 'unknown', arguments: ctx.arguments || {}, result: ctx.result ? 'completed' : 'unknown' }; require('fs').appendFileSync(logPath, JSON.stringify(entry) + '\\n');\"",
+  "enabled": false,
+  "_comment": "Stub for Upgrade 3 (Hooks Injection). Enable when hook generator is implemented."
+}

package/plugin/hooks/pre-tool-use.json

@@ -0,0 +1,9 @@
+{
+  "name": "swarm-scope-enforcement",
+  "description": "Block file operations outside the current step's declared scope",
+  "event": "preToolUse",
+  "tools": ["editFile", "createFile", "deleteFile", "insertText", "replaceText"],
+  "command": "node -e \"const ctx = JSON.parse(process.env.COPILOT_HOOK_CONTEXT || '{}'); const scope = JSON.parse(process.env.SWARM_STEP_SCOPE || '[]'); if (scope.length === 0) { process.exit(0); } const filePath = (ctx.arguments || {}).path || (ctx.arguments || {}).filePath || ''; const allowed = scope.some(s => filePath.includes(s)); if (!allowed) { console.error(JSON.stringify({ decision: 'deny', reason: 'File ' + filePath + ' is outside this agent step scope: ' + scope.join(', ') })); process.exit(1); }\"",
+  "enabled": false,
+  "_comment": "Stub for Upgrade 3 (Hooks Injection). Enable when hook generator is implemented."
+}

package/plugin/plugin.json

@@ -0,0 +1,47 @@
+{
+  "name": "swarm-orchestrator",
+  "displayName": "Swarm Orchestrator",
+  "version": "3.2.0",
+  "description": "Falsification battery and signed attestation for AI-authored code. Worker and reviewer steps run on isolated branches, each step verified before merge, with audit-ready run artifacts and quality gates.",
+  "author": "Bradley R. Kinnard",
+  "publisher": "moonrunnerkc",
+  "repository": "https://github.com/moonrunnerkc/swarm-orchestrator",
+  "license": "ISC",
+  "engines": {
+    "copilot-cli": ">=1.0.0"
+  },
+  "agents": [
+    "agents/backend_master.agent.md",
+    "agents/frontend_expert.agent.md",
+    "agents/tester_elite.agent.md",
+    "agents/security_auditor.agent.md",
+    "agents/devops_pro.agent.md",
+    "agents/integrator_finalizer.agent.md"
+  ],
+  "skills": [
+    "skills/swarm-orchestrate",
+    "skills/swarm-verify",
+    "skills/swarm-gates"
+  ],
+  "hooks": "hooks/hooks.json",
+  "categories": [
+    "AI",
+    "Testing",
+    "Code Quality",
+    "Workflow Automation"
+  ],
+  "keywords": [
+    "copilot",
+    "orchestrator",
+    "swarm",
+    "verification",
+    "quality-gates",
+    "parallel-execution",
+    "agents"
+  ],
+  "mcpServer": {
+    "command": "node",
+    "args": ["dist/src/cli.js", "mcp-server"],
+    "type": "stdio"
+  }
+}

package/plugin/skills/swarm-gates/SKILL.md

@@ -0,0 +1,53 @@
+# Swarm Gates
+
+Static analysis quality gates for generated code.
+
+## Trigger
+
+This skill activates when you need to:
+- Run post-merge quality checks on generated code
+- Validate that code meets project quality standards before accepting it
+- Identify common AI-generated code issues (scaffold defaults, duplicate blocks, hardcoded config)
+
+## Instructions
+
+1. Scan the target directory for project files (respecting exclusion patterns)
+2. Run each enabled gate against the file set
+3. Collect issues from each gate with file paths, line numbers, and remediation hints
+4. Produce a summary: pass (no gate failures) or fail (at least one gate failed)
+5. When auto-remediation is enabled, failed gates can trigger follow-up agent sessions to fix the issues
+
+## Available Gates
+
+### Scaffold Defaults
+Detects leftover placeholder values from project scaffolding (e.g., "TODO", default package names, template strings). These indicate incomplete customization.
+
+### Duplicate Blocks
+Identifies near-identical code blocks across files. Catches copy-paste patterns where agents duplicated logic instead of extracting shared utilities.
+
+### Hardcoded Config
+Flags hardcoded configuration values (URLs, ports, credentials, API keys) that should be externalized to environment variables or config files.
+
+### README Claims
+Cross-references README documentation against actual project structure and files. Catches claims about features or files that don't exist.
+
+### Test Isolation
+Verifies that tests are properly isolated: no shared mutable state between test cases, proper setup/teardown, no order-dependent tests.
+
+### Runtime Checks
+Validates runtime behavior patterns: proper error handling, async/await usage, resource cleanup.
+
+### Accessibility
+Checks frontend code for basic accessibility compliance (ARIA attributes, semantic HTML, color contrast references).
+
+### Test Coverage
+Analyzes test coverage relative to source files. Flags modules with no corresponding test file.
+
+## Configuration
+
+Gates are configured via `config/quality-gates.yaml`. Each gate can be individually enabled/disabled with severity thresholds.
+
+## Resources
+
+- Gate configuration: `config/quality-gates.yaml`
+- Verification: `skills/swarm-verify/SKILL.md`

package/plugin/skills/swarm-orchestrate/SKILL.md

@@ -0,0 +1,34 @@
+# Swarm Orchestrate
+
+Worker and reviewer step execution with analyzer-gated greedy scheduling. Steps run on isolated branches; ready steps run together only when the static dependency analyzer clears them.
+
+## Trigger
+
+This skill activates when you need to:
+- Execute a multi-step development plan with verified per-step branches
+- Run worker and reviewer roles against discrete tasks in a goal
+- Build a feature from a high-level goal with audit-ready run artifacts
+
+## Instructions
+
+1. Parse the goal into discrete, dependency-ordered steps.
+2. Assign each step a role (worker for implementation, reviewer for synthesized tests and diff review). Reviewer mode (security, accessibility, general) is a policy, not a separate role.
+3. Push steps onto the work-stealing queue. The queue dispatches greedy as-ready: a step starts as soon as its dependencies complete and the static dependency analyzer says it cannot conflict with anything currently running.
+4. Each step runs in its own git worktree on a per-step branch, capturing a `/share` transcript.
+5. Verify the step against transcript evidence and the falsification battery, then merge the branch.
+6. Track metrics (timing, commits, verification status) throughout the run.
+
+## Roles
+
+- **Worker**: writes implementation code, runs tests, commits changes, and does not edit pre-existing test files unless the goal explicitly authorizes it.
+- **Reviewer**: read-only. Synthesizes tests before worker execution and reviews diffs after worker execution. Security, accessibility, and general review modes are reviewer policies, not separate agent roles.
+
+## Scheduling
+
+Steps with satisfied dependencies are eligible to run. The work-stealing queue dispatches up to its concurrency cap; the static dependency analyzer must prove two eligible steps cannot conflict before they run together. Otherwise execution is serial. Failed steps trigger repair sessions with classified failure context before retry.
+
+## Resources
+
+- Agent profiles: `agents/*.agent.md`
+- Verification: `skills/swarm-verify/SKILL.md`
+- Quality gates: `skills/swarm-gates/SKILL.md`

package/plugin/skills/swarm-verify/SKILL.md

@@ -0,0 +1,44 @@
+# Swarm Verify
+
+Evidence-based verification of agent outputs against transcript claims.
+
+## Trigger
+
+This skill activates when you need to:
+- Verify that an agent's claimed outputs match actual evidence
+- Cross-reference transcript claims against git commits, test results, and build outputs
+- Determine whether a step passed or failed based on concrete evidence
+
+## Instructions
+
+1. Read the agent's transcript (the `/share` output from the Copilot CLI session)
+2. Parse the transcript into structured evidence:
+   - **Commits**: Extract git commit SHAs and diff summaries
+   - **Tests**: Identify test execution output (pass/fail counts, framework output)
+   - **Build**: Locate build or compile output (success/error messages)
+   - **Claims**: Extract natural-language claims the agent made about its work
+3. Cross-reference each claim against evidence:
+   - "Tests pass" requires actual test runner output showing passes
+   - "Code compiles" requires build output with no errors
+   - "Changes committed" requires at least one commit SHA in the transcript
+4. Mark unverified claims (claims with no supporting evidence)
+5. Produce a verification result: pass (all required checks have evidence) or fail
+
+## Verification Checks
+
+| Check Type | Required Evidence |
+|-----------|-------------------|
+| commit | At least one git commit SHA in transcript |
+| test | Test runner output with pass/fail counts |
+| build | Compiler or bundler output with exit status |
+| claim | Natural language claims matched to evidence |
+| output | Expected output artifacts exist on disk |
+
+## Graceful Degradation
+
+When enabled, verification failure does not block execution. The step is marked as degraded with a reason, allowing the pipeline to continue while flagging the issue for review.
+
+## Resources
+
+- Share parser for transcript analysis
+- Quality gates for post-merge validation: `skills/swarm-gates/SKILL.md`