@leclabs/agent-toolkit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lance Caraccioli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,129 @@
+# 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 |
+
+## Installation
+
+Add the marketplace to Claude Code:
+
+```bash
+claude plugin marketplace add https://github.com/leclabs/agent-toolkit
+```
+
+Install the Flow plugin:
+
+```bash
+claude plugin install flow@agent-toolkit
+```
+
+## Quick Start
+
+Use prefix commands to create and execute workflow-tracked tasks:
+
+| 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 |
+
+**Examples:**
+
+```
+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
+```
+
+## How It Works
+
+The Flow plugin provides DAG-based workflow orchestration. When you use a prefix command, it:
+
+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
+
+### 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)
+```
+
+## 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
+
+## License
+
+ISC License - see [LICENSE](LICENSE) for details.

package/bin/setup-agent-toolkit.js

@@ -0,0 +1,171 @@
+#!/usr/bin/env node
+
+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 args = process.argv.slice(2);
+const flags = {
+  yes: args.includes('--yes') || args.includes('-y'),
+  help: args.includes('--help') || args.includes('-h'),
+};
+
+function printHelp() {
+  console.log(`
+Usage: setup-agent-toolkit [options]
+
+Set up the agent-toolkit marketplace and flow plugin for Claude Code.
+
+Options:
+  -y, --yes   Accept all defaults, skip prompts
+  -h, --help  Show this help message
+
+Steps performed:
+  1. Check Claude Code CLI is installed
+  2. Add agent-toolkit marketplace
+  3. Install flow plugin (user scope)
+  4. Configure project task list ID
+`);
+}
+
+function run(cmd) {
+  try {
+    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() };
+}
+
+async function prompt(question, defaultValue) {
+  if (flags.yes) return defaultValue;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(`${question} (${defaultValue}): `, (answer) => {
+      rl.close();
+      resolve(answer.trim() || 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');
+}
+
+function checkClaudeCode() {
+  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');
+    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.');
+    return true;
+  }
+  const result = runWithOutput(`claude plugin marketplace add ${MARKETPLACE_SOURCE}`);
+  if (result.success) {
+    console.log('  Added successfully.');
+    return true;
+  }
+  console.error(`  Failed: ${result.stderr || result.stdout}`);
+  console.error(`  Try manually: claude plugin marketplace add ${MARKETPLACE_SOURCE}`);
+  return false;
+}
+
+function installPlugin() {
+  console.log('\nInstalling flow plugin...');
+  const list = run('claude plugin list') || '';
+  if (list.includes(PLUGIN_NAME)) {
+    console.log('  Already installed.');
+    return true;
+  }
+  const result = runWithOutput(`claude plugin install ${PLUGIN_NAME} --scope user`);
+  if (result.success) {
+    console.log('  Installed successfully.');
+    return true;
+  }
+  console.error(`  Failed: ${result.stderr || result.stdout}`);
+  console.error(`  Try manually: claude plugin install ${PLUGIN_NAME} --scope user`);
+  return false;
+}
+
+async function configureTaskListId() {
+  console.log('\nConfiguring project settings...');
+  const cwd = process.cwd();
+  const defaultId = path.basename(cwd);
+  const taskListId = await prompt('  Task list ID', defaultId);
+
+  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 {}
+  }
+
+  settings.env = settings.env || {};
+  settings.env.CLAUDE_CODE_TASK_LIST_ID = taskListId;
+
+  fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + '\n');
+  console.log(`  Created: ${settingsPath}`);
+  console.log(`  CLAUDE_CODE_TASK_LIST_ID: ${taskListId}`);
+  return true;
+}
+
+function showSuccess() {
+  console.log(`
+Setup complete!
+
+Next steps:
+  1. Start Claude Code:  claude
+  2. Prime the plugin:   /flow:prime
+  3. Create a task:      feat: "Add user authentication"
+
+Quick prefixes: fix: | feat: | bug:
+`);
+}
+
+async function main() {
+  if (flags.help) { printHelp(); process.exit(0); }
+
+  console.log('Agent Toolkit Setup');
+  console.log('===================');
+
+  checkClaudeCode();
+
+  if (!await confirm('\nProceed with setup?')) {
+    console.log('Setup cancelled.');
+    process.exit(0);
+  }
+
+  const marketplaceOk = addMarketplace();
+  const pluginOk = marketplaceOk && installPlugin();
+  const configOk = await configureTaskListId();
+
+  if (marketplaceOk && pluginOk && configOk) {
+    showSuccess();
+  } else {
+    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); });

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@leclabs/agent-toolkit",
+  "version": "1.0.0",
+  "description": "The essential Claude Code plugin marketplace for reliable Agent-led workflow orchestration",
+  "main": "index.js",
+  "bin": {
+    "setup-agent-toolkit": "./bin/setup-agent-toolkit.js"
+  },
+  "files": [
+    "bin/"
+  ],
+  "scripts": {
+    "test": "npm test --prefix packages/agent-flow-navigator-mcp",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "plugin:reinstall": "(claude plugin uninstall flow@agent-toolkit || true) && claude plugin marketplace update agent-toolkit && claude plugin install flow@agent-toolkit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/leclabs/agent-toolkit.git"
+  },
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "workflow",
+    "agents",
+    "orchestration"
+  ],
+  "author": "Lance Caraccioli",
+  "license": "MIT",
+  "type": "module",
+  "bugs": {
+    "url": "https://github.com/leclabs/agent-toolkit/issues"
+  },
+  "homepage": "https://github.com/leclabs/agent-toolkit#readme",
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "globals": "^17.1.0",
+    "prettier": "^3.8.1"
+  }
+}