spoq 0.2.0__tar.gz

spoq-0.2.0/.gitignore

@@ -0,0 +1,80 @@
+# Dependencies
+node_modules/
+.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# Next.js
+.next/
+out/
+build/
+
+# Testing
+coverage/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+.Python
+*.so
+.venv/
+venv/
+ENV/
+
+# LaTeX build artifacts
+*.aux
+*.log
+*.out
+*.toc
+*.lof
+*.lot
+*.fls
+*.fdb_latexmk
+*.synctex.gz
+*.bbl
+*.blg
+*.nav
+*.snm
+*.vrb
+
+# Terraform
+.terraform/
+*.tfstate
+*.tfstate.*
+.terraform.lock.hcl
+*.tfvars
+!*.tfvars.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Env files
+.env
+.env.*
+!.env.example
+
+# Debug logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# TypeScript
+*.tsbuildinfo
+
+# Misc
+*.pem
+.vercel

spoq-0.2.0/PKG-INFO

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: spoq
+Version: 0.2.0
+Summary: SPOQ: Multi-agent AI orchestration with wave-based parallel execution and quality gates
+Project-URL: Homepage, https://spoqpaper.com
+Project-URL: Repository, https://gitlab.com/kenth56/spoq
+Project-URL: Documentation, https://spoqpaper.com/quickstart
+Author: Royce Carbowitz
+License-Expression: MIT
+Keywords: agents,ai,claude,mcp,orchestration,spoq
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: mcp>=1.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# SPOQ
+
+**Specialist Orchestrated Queuing** for multi-agent AI development.
+
+SPOQ coordinates AI coding agents through wave-based parallel execution with structured quality gates. It provides an MCP server with 23 tools, a CLI for project scaffolding, and template generators for epics and maps.
+
+## Install
+
+```bash
+pip install spoq
+```
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+spoq init --target /path/to/project --with-mcp
+```
+
+This creates the SPOQ directory structure, skill stubs for Claude Code, and configures `.mcp.json`.
+
+### 2. Use with Claude Code
+
+Once initialized, these slash commands are available in Claude Code:
+
+```
+/epic-planning          Plan an epic with atomic tasks and dependency DAG
+/epic-validation        Score epic quality (10 metrics, 95/90 threshold)
+/agent-execution        Execute tasks with parallel agent swarms
+/agent-validation       Score delivered code (10 metrics, 95/80 threshold)
+/team-execution         Persona-specialized agent teams
+/epic-planning --map    Coordinate multiple epics as a program
+```
+
+### 3. Run the MCP server directly
+
+```bash
+spoq mcp
+```
+
+Or configure in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "spoq": {
+      "command": "spoq",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `spoq mcp` | Run the MCP server (stdio transport) |
+| `spoq init` | Bootstrap SPOQ in a project directory |
+| `spoq init --full` | Include example epic and optional skills |
+| `spoq init --with-mcp` | Configure .mcp.json |
+| `spoq init --upgrade` | Upgrade existing installation |
+| `spoq template epic <name> <tasks>` | Generate an epic skeleton |
+| `spoq template map <name> <epics>` | Generate a map skeleton |
+| `spoq --version` | Show version |
+
+## MCP Tools (23)
+
+**Epic Management:** `spoq_parse_epic`, `spoq_validate_epic`, `spoq_compute_waves`, `spoq_get_wave_tasks`, `spoq_analyze_dag`, `spoq_estimate_effort`, `spoq_generate_execution_plan`, `spoq_generate_skeleton`
+
+**Map Management:** `spoq_parse_map`, `spoq_validate_map`, `spoq_compute_epic_waves`, `spoq_analyze_map_dag`, `spoq_estimate_map_effort`, `spoq_get_map_status`, `spoq_list_maps`, `spoq_generate_map_skeleton`
+
+**Task Management:** `spoq_get_task`, `spoq_update_task_status`, `spoq_list_task_statuses`
+
+**Team Execution:** `spoq_assign_personas`, `spoq_detect_conflicts`
+
+**Utilities:** `spoq_get_timestamp`, `spoq_ping`
+
+## Links
+
+- [Website](https://spoqpaper.com)
+- [Quickstart Guide](https://spoqpaper.com/quickstart)
+- [Methodology](https://spoqpaper.com/methodology)
+- [Source Code](https://gitlab.com/kenth56/spoq)
+
+## License
+
+MIT

spoq-0.2.0/README.md

@@ -0,0 +1,89 @@
+# SPOQ
+
+**Specialist Orchestrated Queuing** for multi-agent AI development.
+
+SPOQ coordinates AI coding agents through wave-based parallel execution with structured quality gates. It provides an MCP server with 23 tools, a CLI for project scaffolding, and template generators for epics and maps.
+
+## Install
+
+```bash
+pip install spoq
+```
+
+## Quick Start
+
+### 1. Initialize a project
+
+```bash
+spoq init --target /path/to/project --with-mcp
+```
+
+This creates the SPOQ directory structure, skill stubs for Claude Code, and configures `.mcp.json`.
+
+### 2. Use with Claude Code
+
+Once initialized, these slash commands are available in Claude Code:
+
+```
+/epic-planning          Plan an epic with atomic tasks and dependency DAG
+/epic-validation        Score epic quality (10 metrics, 95/90 threshold)
+/agent-execution        Execute tasks with parallel agent swarms
+/agent-validation       Score delivered code (10 metrics, 95/80 threshold)
+/team-execution         Persona-specialized agent teams
+/epic-planning --map    Coordinate multiple epics as a program
+```
+
+### 3. Run the MCP server directly
+
+```bash
+spoq mcp
+```
+
+Or configure in `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "spoq": {
+      "command": "spoq",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+## CLI Commands
+
+| Command | Description |
+|---------|-------------|
+| `spoq mcp` | Run the MCP server (stdio transport) |
+| `spoq init` | Bootstrap SPOQ in a project directory |
+| `spoq init --full` | Include example epic and optional skills |
+| `spoq init --with-mcp` | Configure .mcp.json |
+| `spoq init --upgrade` | Upgrade existing installation |
+| `spoq template epic <name> <tasks>` | Generate an epic skeleton |
+| `spoq template map <name> <epics>` | Generate a map skeleton |
+| `spoq --version` | Show version |
+
+## MCP Tools (23)
+
+**Epic Management:** `spoq_parse_epic`, `spoq_validate_epic`, `spoq_compute_waves`, `spoq_get_wave_tasks`, `spoq_analyze_dag`, `spoq_estimate_effort`, `spoq_generate_execution_plan`, `spoq_generate_skeleton`
+
+**Map Management:** `spoq_parse_map`, `spoq_validate_map`, `spoq_compute_epic_waves`, `spoq_analyze_map_dag`, `spoq_estimate_map_effort`, `spoq_get_map_status`, `spoq_list_maps`, `spoq_generate_map_skeleton`
+
+**Task Management:** `spoq_get_task`, `spoq_update_task_status`, `spoq_list_task_statuses`
+
+**Team Execution:** `spoq_assign_personas`, `spoq_detect_conflicts`
+
+**Utilities:** `spoq_get_timestamp`, `spoq_ping`
+
+## Links
+
+- [Website](https://spoqpaper.com)
+- [Quickstart Guide](https://spoqpaper.com/quickstart)
+- [Methodology](https://spoqpaper.com/methodology)
+- [Source Code](https://gitlab.com/kenth56/spoq)
+
+## License
+
+MIT

spoq-0.2.0/pyproject.toml

@@ -0,0 +1,51 @@
+[project]
+name = "spoq"
+version = "0.2.0"
+description = "SPOQ: Multi-agent AI orchestration with wave-based parallel execution and quality gates"
+requires-python = ">=3.12"
+license = "MIT"
+readme = "README.md"
+authors = [
+    { name = "Royce Carbowitz" },
+]
+keywords = ["ai", "agents", "orchestration", "mcp", "claude", "spoq"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "mcp>=1.0",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+spoq = "spoq_server.cli:main"
+spoq-mcp = "spoq_server.server:main"
+
+[project.urls]
+Homepage = "https://spoqpaper.com"
+Repository = "https://gitlab.com/kenth56/spoq"
+Documentation = "https://spoqpaper.com/quickstart"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/spoq_server"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[dependency-groups]
+dev = [
+    "anyio>=4.12.1",
+    "pytest>=8.0",
+    "pytest-anyio>=0.0.0",
+]

spoq-0.2.0/src/spoq_server/__init__.py

@@ -0,0 +1,9 @@
+"""SPOQ — Specialist Orchestrated Queuing for multi-agent AI development.
+
+Provides:
+  - MCP server with 23 tools for epic, map, and task management
+  - CLI for project initialization, template generation, and server operation
+  - Bundled epic_utils and map_utils for standalone use
+"""
+
+__version__ = "0.2.0"

spoq-0.2.0/src/spoq_server/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running with python -m spoq_server."""
+
+from spoq_server.cli import main
+
+main()

spoq-0.2.0/src/spoq_server/cli.py

@@ -0,0 +1,154 @@
+"""SPOQ CLI entry point.
+
+Provides subcommands:
+  spoq mcp       - Run the MCP server (stdio transport)
+  spoq init      - Bootstrap SPOQ in a project directory
+  spoq template  - Generate epic or map skeletons
+  spoq version   - Show version
+"""
+
+import argparse
+import sys
+
+from spoq_server import __version__
+
+
+def main():
+    """Main CLI entry point."""
+    parser = argparse.ArgumentParser(
+        prog="spoq",
+        description="SPOQ: Specialist Orchestrated Queuing for multi-agent AI development",
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"spoq {__version__}"
+    )
+
+    subparsers = parser.add_subparsers(dest="command", help="Available commands")
+
+    # --- spoq mcp ---
+    mcp_parser = subparsers.add_parser(
+        "mcp", help="Run the SPOQ MCP server (stdio transport)"
+    )
+    mcp_parser.add_argument(
+        "--transport", default="stdio", choices=["stdio"],
+        help="Transport protocol (default: stdio)",
+    )
+
+    # --- spoq init ---
+    init_parser = subparsers.add_parser(
+        "init", help="Bootstrap SPOQ in a project directory"
+    )
+    init_parser.add_argument(
+        "--target", default=".", help="Target directory (default: current directory)"
+    )
+    init_parser.add_argument(
+        "--full", action="store_true",
+        help="Include example epic and optional skills",
+    )
+    init_parser.add_argument(
+        "--with-mcp", action="store_true",
+        help="Configure .mcp.json to use the SPOQ MCP server",
+    )
+    init_parser.add_argument(
+        "--upgrade", action="store_true",
+        help="Upgrade an existing SPOQ installation",
+    )
+
+    # --- spoq template ---
+    template_parser = subparsers.add_parser(
+        "template", help="Generate epic or map skeletons"
+    )
+    template_sub = template_parser.add_subparsers(
+        dest="template_type", help="Template type"
+    )
+
+    # spoq template epic <name> <task_count>
+    epic_tmpl = template_sub.add_parser("epic", help="Generate an epic skeleton")
+    epic_tmpl.add_argument("name", help="Epic name (converted to slug)")
+    epic_tmpl.add_argument(
+        "task_count", type=int, help="Number of task files (minimum 3)"
+    )
+    epic_tmpl.add_argument(
+        "--path", default="", help="Base path (default: spoq/epics/active/)"
+    )
+
+    # spoq template map <name> <epic_count>
+    map_tmpl = template_sub.add_parser("map", help="Generate a map skeleton")
+    map_tmpl.add_argument("name", help="Map name (converted to slug)")
+    map_tmpl.add_argument(
+        "epic_count", type=int, help="Number of epic entries (minimum 2)"
+    )
+    map_tmpl.add_argument(
+        "--path", default="", help="Base path (default: spoq/maps/active/)"
+    )
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.command == "mcp":
+        _cmd_mcp(args)
+    elif args.command == "init":
+        _cmd_init(args)
+    elif args.command == "template":
+        _cmd_template(args)
+
+
+def _cmd_mcp(args):
+    """Run the MCP server."""
+    from spoq_server.server import main as mcp_main
+    mcp_main()
+
+
+def _cmd_init(args):
+    """Bootstrap SPOQ in a project directory."""
+    from spoq_server.init_cmd import run_init
+    run_init(
+        target=args.target,
+        full=args.full,
+        with_mcp=args.with_mcp,
+        upgrade=args.upgrade,
+    )
+
+
+def _cmd_template(args):
+    """Generate a template."""
+    import json
+
+    if args.template_type is None:
+        print("Usage: spoq template {epic,map} <name> <count>")
+        sys.exit(1)
+
+    if args.template_type == "epic":
+        from spoq_server.util_tools import spoq_generate_skeleton
+        result = json.loads(spoq_generate_skeleton(
+            name=args.name,
+            task_count=args.task_count,
+            path=args.path,
+        ))
+    elif args.template_type == "map":
+        from spoq_server.map_tools import spoq_generate_map_skeleton
+        result = json.loads(spoq_generate_map_skeleton(
+            name=args.name,
+            epic_count=args.epic_count,
+            path=args.path,
+        ))
+    else:
+        print(f"Unknown template type: {args.template_type}")
+        sys.exit(1)
+
+    if "error" in result:
+        print(f"Error: {result['error']}", file=sys.stderr)
+        sys.exit(1)
+
+    path_key = "epic_path" if args.template_type == "epic" else "map_path"
+    print(f"Created {args.template_type} at: {result[path_key]}")
+    if "wave_distribution" in result:
+        dist = result["wave_distribution"]
+        print(f"  Wave 0: {dist.get('wave_0', 0)}, Wave 1: {dist.get('wave_1', 0)}, Later: {dist.get('later', 0)}")
+
+
+if __name__ == "__main__":
+    main()