@leclabs/agent-toolkit 1.0.0 → 1.2.0

package/README.md

@@ -1,129 +1,90 @@
 # Agent Toolkit
 
-[![npm version](https://img.shields.io/npm/v/@leclabs/agent-toolkit)](https://www.npmjs.com/package/@leclabs/agent-toolkit)
-[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
-[![GitHub stars](https://img.shields.io/github/stars/leclabs/agent-toolkit)](https://github.com/leclabs/agent-toolkit/stargazers)
-
-The essential Claude Code plugin marketplace for reliable Agent-led workflow orchestration.
-
-## What's Included
-
-| Component | Description |
-|-----------|-------------|
-| **[Flow Plugin](plugins/flow/)** | DAG-based workflow orchestration for Claude Code |
-| **[Navigator MCP](packages/agent-flow-navigator-mcp/)** | Workflow state machine that navigates agents through DAG-based workflows |
+A Claude Code plugin marketplace for AI agent tools. The flagship plugin is **Flow** -- DAG-based workflow orchestration that guides agents through structured, multi-step tasks.
 
 ## Installation
 
-Add the marketplace to Claude Code:
-
 ```bash
-claude plugin marketplace add https://github.com/leclabs/agent-toolkit
+# Add the toolkit to Claude Code
+claude plugin:add github:leclabs/agent-toolkit
 ```
 
-Install the Flow plugin:
+## Quick Start
 
 ```bash
-claude plugin install flow@agent-toolkit
-```
+# Load the orchestrator at session start
+/flow:prime
 
-## Quick Start
+# Create a task using any command
+/flow:feat "add user authentication"
+/flow:bug "fix login redirect loop"
+/flow:task "refactor the settings module"
 
-Use prefix commands to create and execute workflow-tracked tasks:
+# Execute all pending tasks
+/flow:go
+```
 
-| Prefix | Workflow | Description |
-|--------|----------|-------------|
-| `feat:` | feature-development | Full lifecycle: requirements, planning, implementation, testing |
-| `bug:` | bug-fix | Bug workflow: reproduce, investigate, fix, verify |
-| `fix:` | quick-task | Minimal: understand, execute, verify |
-| `test:` | test-coverage | Analyze coverage gaps and write tests |
-| `ctx:` | context-optimization | Optimize agent context and instructions |
+## Commands
 
-**Examples:**
+Commands are the primary human interface. Type a command to create a task with the right workflow:
 
-```
-feat: Add user authentication with OAuth2 support
-bug: Login button not responding on mobile devices
-fix: Update copyright year in footer
-test: Increase coverage for payment module
-```
+| Command       | Workflow             | Description                        |
+| ------------- | -------------------- | ---------------------------------- |
+| `/flow:feat`  | feature-development  | New feature with planning + review |
+| `/flow:bug`   | bug-fix              | Bug investigation and fix          |
+| `/flow:task`  | agile-task           | General development task           |
+| `/flow:fix`   | quick-task           | Quick fix, minimal ceremony        |
+| `/flow:spec`  | test-coverage        | Analyze and improve test coverage  |
+| `/flow:ctx`   | context-optimization | Optimize agent context and prompts |
+| `/flow:ui`    | ui-reconstruction    | Reconstruct UI from reference      |
+| `/flow:go`    | _(runs task queue)_  | Execute all pending tasks          |
+| `/flow:recon` | _(exploration)_      | Deep project reconnaissance        |
+
+## Workflows
 
-## How It Works
+10 workflow templates ship in the catalog:
 
-The Flow plugin provides DAG-based workflow orchestration. When you use a prefix command, it:
+| Workflow                  | Steps | Description                                            |
+| ------------------------- | ----- | ------------------------------------------------------ |
+| feature-development       | 15    | Full lifecycle: plan, implement, test, review, PR      |
+| bug-fix                   | 11    | Reproduce, investigate, fix, regression test           |
+| agile-task                | 9     | General task: analyze, implement, test, review         |
+| quick-task                | 8     | Minimal: understand, execute, verify                   |
+| test-coverage             | 10    | Analyze gaps, write tests, review                      |
+| context-optimization      | 9     | Map connections, identify pathologies, improve         |
+| ui-reconstruction         | 17    | Extract semantic IR, rebuild UI, blind review          |
+| refactor                  | 16    | Functional core / imperative shell restructuring       |
+| build-review-murder-board | 7     | Build-review loop, level 5 scrutiny, blind-shot review |
+| build-review-quick        | 7     | Build-review loop, basic sanity check                  |
 
-1. **Creates a task** with the appropriate workflow type
-2. **Navigates** through workflow steps using the Navigator MCP
-3. **Delegates** to specialized subagents (@flow:Planner, @flow:Developer, @flow:Tester)
-4. **Tracks progress** with retry logic and HITL escalation
+Customize workflows for your project with `/flow:init`.
 
-### Architecture
+## Architecture
 
 ```
-Orchestrator (Claude Code)
-    │
-    ├── /flow:task-create   Create tasks with workflow metadata
-    ├── /flow:run           Execute tasks through workflow steps
-    ├── /flow:task-list     View all tasks and their status
-    └── /flow:task-advance  Manually advance tasks
-            │
-            ▼
-    Navigator MCP Server
-    ├── Workflow Store      (Graph definitions)
-    ├── Edge Evaluator      (Conditional routing)
-    └── Retry Tracking      (Per-step retries with HITL escalation)
+/flow:feat "add dark mode"     ← human types a command
+         │
+         ▼
+┌──────────────────┐         ┌──────────────────┐
+│   Orchestrator   │ ◄─MCP─► │    Navigator     │
+│   (flow:prime)   │         │  (state machine) │
+└──────────────────┘         └──────────────────┘
+         │                            │
+         ▼                            ▼
+┌──────────────────┐         ┌──────────────────┐
+│    Subagents     │         │    Workflows     │
+│  @flow:Planner   │         │    (DAGs)        │
+│  @flow:Developer │         └──────────────────┘
+│  @flow:Tester    │
+│  @flow:Reviewer  │
+└──────────────────┘
 ```
 
-## Available Workflows
-
-| Workflow | Steps | Use Case |
-|----------|-------|----------|
-| **feature-development** | requirements → planning → implementation → testing → review | New features with full lifecycle |
-| **bug-fix** | reproduce → investigate → fix → verify | Bug fixes with root cause analysis |
-| **agile-task** | understand → implement → verify | Standard development tasks |
-| **quick-task** | understand → execute → verify | Fast, minimal overhead tasks |
-| **test-coverage** | analyze → write-tests → verify | Improving test coverage |
-| **context-optimization** | audit → optimize → validate | Improving agent context |
-| **ui-reconstruction** | analyze → reconstruct → verify | UI/component rebuilding |
-
-## Skills Reference
-
-| Skill | Description |
-|-------|-------------|
-| `/flow:prime` | Load orchestrator context (invoke at session start) |
-| `/flow:task-create` | Create a new workflow task |
-| `/flow:run` | Execute tasks autonomously with subagent delegation |
-| `/flow:task-list` | List all tasks with status |
-| `/flow:task-get` | Get task details with workflow diagram |
-| `/flow:task-advance` | Manually advance a task to next step |
-| `/flow:init` | Copy workflows to project `.flow/workflows/` |
-| `/flow:diagram` | Generate mermaid diagram for a workflow |
-
-## Feature Highlights
-
-- **DAG-Based Workflows**: Define complex workflows as directed acyclic graphs with conditional edges
-- **Subagent Delegation**: Specialized agents handle specific workflow steps (@flow:Planner, @flow:Developer, @flow:Tester)
-- **Retry Logic**: Per-step retry tracking with configurable limits
-- **HITL Escalation**: Automatic human-in-the-loop escalation when retries are exhausted
-- **Progress Tracking**: Visual progress through workflow stages
-- **Workflow Catalog**: Pre-built workflows for common development patterns
-
-## Documentation
-
-- [Flow Plugin Documentation](plugins/flow/) - Detailed plugin usage and customization
-- [Navigator MCP Reference](packages/agent-flow-navigator-mcp/) - MCP server API and workflow schema
-- [Workflow Schema](packages/agent-flow-navigator-mcp/README.md#workflow-definition-schema) - Node types, edge properties, task schema
-
-## Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feat/amazing-feature`)
-3. Make your changes
-4. Run tests (`npm test`)
-5. Commit with conventional commits (`git commit -m 'feat: add amazing feature'`)
-6. Push to your fork (`git push origin feat/amazing-feature`)
-7. Open a Pull Request
+## Links
+
+- [Flow Plugin](plugins/flow/README.md) -- commands, skills, workflows, and customization
+- [Navigator MCP Server](packages/agent-flow-navigator-mcp/README.md) -- workflow state machine
 
 ## License
 
-ISC License - see [LICENSE](LICENSE) for details.
+ISC

package/bin/setup-agent-toolkit.js

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
 
-import { execSync, spawnSync } from 'child_process';
-import fs from 'fs';
-import path from 'path';
-import readline from 'readline';
+import { execSync, spawnSync } from "child_process";
+import fs from "fs";
+import path from "path";
+import readline from "readline";
 
-const MARKETPLACE_SOURCE = 'github:leclabs/agent-toolkit';
-const PLUGIN_NAME = 'flow@agent-toolkit';
+const MARKETPLACE_SOURCE = "leclabs/agent-toolkit";
+const PLUGIN_NAME = "flow@agent-toolkit";
 
 const args = process.argv.slice(2);
 const flags = {
-  yes: args.includes('--yes') || args.includes('-y'),
-  help: args.includes('--help') || args.includes('-h'),
+  yes: args.includes("--yes") || args.includes("-y"),
+  help: args.includes("--help") || args.includes("-h"),
 };
 
 function printHelp() {
@@ -34,13 +34,15 @@ Steps performed:
 
 function run(cmd) {
   try {
-    return execSync(cmd, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
-  } catch { return null; }
+    return execSync(cmd, { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] }).trim();
+  } catch {
+    return null;
+  }
 }
 
 function runWithOutput(cmd) {
-  const result = spawnSync('sh', ['-c', cmd], { encoding: 'utf8' });
-  return { success: result.status === 0, stdout: (result.stdout || '').trim(), stderr: (result.stderr || '').trim() };
+  const result = spawnSync("sh", ["-c", cmd], { encoding: "utf8" });
+  return { success: result.status === 0, stdout: (result.stdout || "").trim(), stderr: (result.stderr || "").trim() };
 }
 
 async function prompt(question, defaultValue) {
@@ -56,31 +58,31 @@ async function prompt(question, defaultValue) {
 
 async function confirm(question, defaultYes = true) {
   if (flags.yes) return true;
-  const answer = await prompt(`${question} ${defaultYes ? '[Y/n]' : '[y/N]'}`, defaultYes ? 'y' : 'n');
-  return answer.toLowerCase().startsWith('y');
+  const answer = await prompt(`${question} ${defaultYes ? "[Y/n]" : "[y/N]"}`, defaultYes ? "y" : "n");
+  return answer.toLowerCase().startsWith("y");
 }
 
 function checkClaudeCode() {
-  console.log('\nChecking Claude Code CLI...');
-  const version = run('claude --version');
+  console.log("\nChecking Claude Code CLI...");
+  const version = run("claude --version");
   if (!version) {
-    console.error('  Error: Claude Code CLI not found.');
-    console.error('  Install from: https://claude.ai/code');
+    console.error("  Error: Claude Code CLI not found.");
+    console.error("  Install from: https://claude.ai/code");
     process.exit(1);
   }
   console.log(`  Found: ${version}`);
 }
 
 function addMarketplace() {
-  console.log('\nAdding agent-toolkit marketplace...');
-  const list = run('claude plugin marketplace list') || '';
-  if (list.includes('agent-toolkit')) {
-    console.log('  Already added.');
+  console.log("\nAdding agent-toolkit marketplace...");
+  const list = run("claude plugin marketplace list") || "";
+  if (list.includes("agent-toolkit")) {
+    console.log("  Already added.");
     return true;
   }
   const result = runWithOutput(`claude plugin marketplace add ${MARKETPLACE_SOURCE}`);
   if (result.success) {
-    console.log('  Added successfully.');
+    console.log("  Added successfully.");
     return true;
   }
   console.error(`  Failed: ${result.stderr || result.stdout}`);
@@ -89,15 +91,15 @@ function addMarketplace() {
 }
 
 function installPlugin() {
-  console.log('\nInstalling flow plugin...');
-  const list = run('claude plugin list') || '';
+  console.log("\nInstalling flow plugin...");
+  const list = run("claude plugin list") || "";
   if (list.includes(PLUGIN_NAME)) {
-    console.log('  Already installed.');
+    console.log("  Already installed.");
     return true;
   }
   const result = runWithOutput(`claude plugin install ${PLUGIN_NAME} --scope user`);
   if (result.success) {
-    console.log('  Installed successfully.');
+    console.log("  Installed successfully.");
     return true;
   }
   console.error(`  Failed: ${result.stderr || result.stdout}`);
@@ -106,25 +108,29 @@ function installPlugin() {
 }
 
 async function configureTaskListId() {
-  console.log('\nConfiguring project settings...');
+  console.log("\nConfiguring project settings...");
   const cwd = process.cwd();
   const defaultId = path.basename(cwd);
-  const taskListId = await prompt('  Task list ID', defaultId);
+  const taskListId = await prompt("  Task list ID", defaultId);
 
-  const claudeDir = path.join(cwd, '.claude');
-  const settingsPath = path.join(claudeDir, 'settings.local.json');
+  const claudeDir = path.join(cwd, ".claude");
+  const settingsPath = path.join(claudeDir, "settings.local.json");
 
   if (!fs.existsSync(claudeDir)) fs.mkdirSync(claudeDir, { recursive: true });
 
   let settings = {};
   if (fs.existsSync(settingsPath)) {
-    try { settings = JSON.parse(fs.readFileSync(settingsPath, 'utf8')); } catch {}
+    try {
+      settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    } catch {
+      // Ignore parse errors, start fresh
+    }
   }
 
   settings.env = settings.env || {};
   settings.env.CLAUDE_CODE_TASK_LIST_ID = taskListId;
 
-  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
   console.log(`  Created: ${settingsPath}`);
   console.log(`  CLAUDE_CODE_TASK_LIST_ID: ${taskListId}`);
   return true;
@@ -144,15 +150,18 @@ Quick prefixes: fix: | feat: | bug:
 }
 
 async function main() {
-  if (flags.help) { printHelp(); process.exit(0); }
+  if (flags.help) {
+    printHelp();
+    process.exit(0);
+  }
 
-  console.log('Agent Toolkit Setup');
-  console.log('===================');
+  console.log("Agent Toolkit Setup");
+  console.log("===================");
 
   checkClaudeCode();
 
-  if (!await confirm('\nProceed with setup?')) {
-    console.log('Setup cancelled.');
+  if (!(await confirm("\nProceed with setup?"))) {
+    console.log("Setup cancelled.");
     process.exit(0);
   }
 
@@ -163,9 +172,12 @@ async function main() {
   if (marketplaceOk && pluginOk && configOk) {
     showSuccess();
   } else {
-    console.log('\nSetup completed with errors. Review the messages above.');
+    console.log("\nSetup completed with errors. Review the messages above.");
     process.exit(1);
   }
 }
 
-main().catch((err) => { console.error('Unexpected error:', err.message); process.exit(1); });
+main().catch((err) => {
+  console.error("Unexpected error:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@leclabs/agent-toolkit",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "The essential Claude Code plugin marketplace for reliable Agent-led workflow orchestration",
   "main": "index.js",
   "bin": {
@@ -13,6 +13,9 @@
     "test": "npm test --prefix packages/agent-flow-navigator-mcp",
     "lint": "eslint .",
     "format": "prettier --write .",
+    "changeset": "changeset",
+    "version": "changeset version && node scripts/sync-versions.js",
+    "publish:all": "npm publish --access public && cd packages/agent-flow-navigator-mcp && npm publish --access public",
     "plugin:reinstall": "(claude plugin uninstall flow@agent-toolkit || true) && claude plugin marketplace update agent-toolkit && claude plugin install flow@agent-toolkit"
   },
   "repository": {
@@ -34,6 +37,7 @@
   },
   "homepage": "https://github.com/leclabs/agent-toolkit#readme",
   "devDependencies": {
+    "@changesets/cli": "^2.29.8",
     "@eslint/js": "^9.39.2",
     "eslint": "^9.39.2",
     "eslint-config-prettier": "^10.1.8",