greatminds 0.1.0__py3-none-any.whl

greatminds/__init__.py

@@ -0,0 +1,8 @@
+"""greatminds — file-based multi-agent coordination protocol.
+
+See https://github.com/veryviolet/greatminds for full docs.
+"""
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

greatminds/cli/__init__.py

@@ -0,0 +1,6 @@
+"""greatminds CLI entry-points.
+
+Each module here exposes a ``main()`` function wired up as a ``project.scripts``
+entry-point in ``pyproject.toml``. Modules are added incrementally as the
+original ``/opt/coordination/bin/*`` scripts are ported.
+"""

greatminds/cli/coord_init.py

@@ -0,0 +1,324 @@
+#!/usr/bin/env python3
+"""coord-init — bootstrap coordination into a fresh project.
+
+Usage:
+  coord-init [--project-dir <dir>] [--force]
+
+Creates under <project-dir>:
+  bin/                   symlinks (or copies) to canon scripts
+  coord.yaml             from canon/coord.example.yaml (edit before launch)
+  coordination/
+    PROJECT.md           from canon/templates/PROJECT.md.template
+    schema.yaml          copy of canon/schema.yaml
+    .gitignore           journal.ndjson, intent/, .agent_registry/, .locks/, .id_counter
+    feature_inbox/_TEMPLATE.yaml  (and other queues)
+    feature_plan/, feature_dev/, feature_ui_dev/, feature_docs/,
+    feature_test/, feature_docs_review/, feature_review/,
+    feature_blocked/, verified/, archive/, user_feedback/,
+    review_sessions/, stand_requests/, stand_wip/, stand_done/,
+    intent/, inbox/<role>/
+
+Idempotent: re-running on an initialised project copies missing pieces
+only, never overwrites coordination/PROJECT.md or coord.yaml unless
+--force is given.
+
+After init:
+  1. edit <project>/coord.yaml — set project_dir, tweak window list
+  2. edit <project>/coordination/PROJECT.md — fill in tokens
+  3. run bin/coord-tmux to spin up the tmux session
+"""
+
+from __future__ import annotations
+
+import argparse
+import os
+import shutil
+import sys
+from pathlib import Path
+
+from greatminds.core.util import die as _die_canonical
+
+
+QUEUES = [
+    "feature_inbox", "feature_plan", "feature_dev", "feature_ui_dev",
+    "feature_docs", "feature_test", "feature_docs_review",
+    "feature_review", "feature_blocked", "verified", "archive",
+    "user_feedback", "review_sessions",
+    "stand_requests", "stand_wip", "stand_done",
+    "bot_inbox", "bot_wip", "bot_done", "bot_verified", "bot_archive",
+]
+
+ROLES_LOWER = [
+    "architect-planner", "architect-reviewer", "developer", "ui-developer",
+    "technical-writer", "tester", "reader", "explorer", "stand-keeper",
+    "user", "maintainer", "bot-user", "bot-developer",
+]
+
+
+def die(msg: str) -> None:
+    """Historical (msg-only) die signature preserved as a thin adapter."""
+    _die_canonical(1, msg)
+
+
+def info(msg: str) -> None:
+    print(f"  {msg}")
+
+
+def ensure_dir(p: Path) -> str:
+    if p.is_dir():
+        return "exists"
+    p.mkdir(parents=True)
+    return "created"
+
+
+def copy_if_missing(src: Path, dst: Path, force: bool = False) -> str:
+    if not src.is_file():
+        return "(canon source missing)"
+    if dst.is_file() and not force:
+        return "exists"
+    shutil.copyfile(src, dst)
+    if src.stat().st_mode & 0o111:
+        os.chmod(dst, dst.stat().st_mode | 0o755)
+    return "copied" if not dst.is_file() else "overwritten" if force else "copied"
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point — wired up as ``greatminds-coord-init`` in pyproject.toml.
+
+    Bootstraps a project directory to use the coordination protocol:
+    creates the runtime queue tree, copies the schema / command / role
+    docs from the packaged ``greatminds.data`` directory, and seeds the
+    inbox + plugin overlay layout.
+
+    No ``bin/*`` symlinks are created. With pip/pipx-installed
+    ``greatminds``, the launcher and CLI tools (``greatminds-task``,
+    ``greatminds-coordd``, …) live in the venv's ``bin/`` and are on
+    PATH; per-project shims are unnecessary.
+    """
+    from greatminds.core.paths import find_canon_dir
+
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("--project-dir", type=Path, default=Path.cwd())
+    ap.add_argument("--force", action="store_true",
+                    help="overwrite coord.yaml and PROJECT.md if present")
+    args = ap.parse_args(argv)
+
+    canon = find_canon_dir()
+    proj = args.project_dir.resolve()
+    proj.mkdir(parents=True, exist_ok=True)
+    print(f"coord-init: bootstrapping {proj} from canon {canon}")
+
+    # project-root config (schema, command_START, role docs — canon-data,
+    # kept locally so humans can `cat <project>/DEVELOPER.md` without
+    # importing the package).
+    print("\nproject-root config:")
+    coord_example = canon / "coord.example.yaml"
+    if coord_example.is_file():
+        info(f"coord.yaml: {copy_if_missing(coord_example, proj / 'coord.yaml', args.force)}")
+    info(f"schema.yaml: {copy_if_missing(canon / 'schema.yaml', proj / 'schema.yaml', force=True)}")
+    info(f"command_START.yaml: {copy_if_missing(canon / 'command_START.yaml', proj / 'command_START.yaml', force=True)}")
+    info(f"COORDINATE.md: {copy_if_missing(canon / 'COORDINATE.md', proj / 'COORDINATE.md', force=True)}")
+    # role docs at project root (sourced from packaged greatminds.data/roles/)
+    for role_md in ("ARCHITECT-PLANNER.md", "ARCHITECT-REVIEWER.md", "DEVELOPER.md",
+                    "UI-DEVELOPER.md", "TECHNICAL-WRITER.md", "TESTER.md", "READER.md",
+                    "EXPLORER.md", "STAND-KEEPER.md", "MAINTAINER.md", "USER.md",
+                    "BOT-USER.md", "BOT-DEVELOPER.md"):
+        src = canon / "roles" / role_md
+        if src.is_file():
+            copy_if_missing(src, proj / role_md, force=True)
+
+    # coordination/ — runtime state (queues, journal, intent, inbox)
+    coord = proj / "coordination"
+    print(f"\ncoordination/ (runtime state):")
+    info(f"dir: {ensure_dir(coord)}")
+    info(f"PROJECT.md: {copy_if_missing(canon / 'templates' / 'PROJECT.md.template', coord / 'PROJECT.md', args.force)}")
+    # .gitignore
+    gi = coord / ".gitignore"
+    if not gi.is_file() or args.force:
+        gi.write_text(
+            "# Runtime churn — NOT version-controlled. Everything else\n"
+            "# under coordination/ (PROJECT.md, queue task files,\n"
+            "# verified/archive history, templates) IS tracked.\n"
+            "journal.ndjson\n"
+            ".notify_state.json\n"
+            "intent/\n"
+            ".agent_registry/\n"
+            ".locks/\n"
+            ".id_counter\n"
+            "heartbeat.*\n"
+            "inbox/*/*\n"
+            "!inbox/*/.gitkeep\n"
+            "*.legacy\n"
+            "PROJECT.env\n",
+            encoding="utf-8",
+        )
+        info(".gitignore: written")
+    else:
+        info(".gitignore: exists")
+
+    # queue dirs + gitkeep
+    print("\nqueues:")
+    for q in QUEUES:
+        st = ensure_dir(coord / q)
+        gk = coord / q / ".gitkeep"
+        if not gk.is_file():
+            gk.touch()
+        info(f"{q}: {st}")
+    ensure_dir(coord / "intent")
+    info("intent: created/exists")
+
+    # inbox per role
+    inbox = coord / "inbox"
+    ensure_dir(inbox)
+    print("\ninbox per role:")
+    for r in ROLES_LOWER:
+        d = inbox / r
+        ensure_dir(d)
+        gk = d / ".gitkeep"
+        if not gk.is_file():
+            gk.touch()
+        info(f"{r}: created/exists")
+
+    # locks + agent_registry dirs (gitignored)
+    ensure_dir(coord / ".locks")
+    ensure_dir(coord / ".agent_registry")
+
+    # Project-side plugin overlay. Canon plugins live in
+    # /opt/coordination/plugins/ and are loaded directly via --plugin-dir;
+    # this overlay is the project's per-install override layer.
+    print("\nplugin overlay (project-overrides):")
+    overlay = coord / "plugins.local" / "project-overrides"
+    overlay_meta = overlay / ".claude-plugin"
+    overlay_skills = overlay / "skills"
+    ensure_dir(overlay)
+    ensure_dir(overlay_meta)
+    ensure_dir(overlay_skills)
+    pj = overlay_meta / "plugin.json"
+    if not pj.is_file():
+        pj.write_text(
+            '{\n'
+            '  "name": "project-overrides",\n'
+            '  "version": "0.1.0",\n'
+            '  "description": "Project-side overlay for canon coordination plugins. Add SKILL.md under skills/<name>/ to override (same name) or extend (new name) canon skills. To disable a canon skill instead, use skillOverrides in <project>/.claude/settings.local.json.",\n'
+            '  "author": { "name": "project-local" }\n'
+            '}\n',
+            encoding="utf-8",
+        )
+        info("plugin.json: written")
+    else:
+        info("plugin.json: exists")
+    sg = overlay_skills / ".gitkeep"
+    if not sg.is_file():
+        sg.touch()
+    rdme = overlay / "README.md"
+    if not rdme.is_file():
+        rdme.write_text(
+            "# project-overrides\n\n"
+            "Project-side overlay for canon coordination plugins. Loaded LAST\n"
+            "by `bin/start_agent --plugin-dir` so last-wins precedence applies.\n\n"
+            "## Three usage patterns\n\n"
+            "**Replace a canon skill (override by name).** Create\n"
+            "`skills/<same-name>/SKILL.md` with the same `name:` in its\n"
+            "frontmatter as the canon skill — your project skill shadows\n"
+            "the canon one.\n\n"
+            "**Disable a canon skill.** Edit\n"
+            "`<project>/.claude/settings.local.json` and add a `skillOverrides`\n"
+            "field: `{\"<canon-skill-name>\": \"off\"}`.\n\n"
+            "**Add a project-only skill.** Create `skills/<new-name>/SKILL.md`\n"
+            "with a unique `name:`. It joins the loaded skill pool for this\n"
+            "project; no canon counterpart needed.\n",
+            encoding="utf-8",
+        )
+        info("README.md: written")
+    else:
+        info("README.md: exists")
+
+    # mcp.local.json — empty stub; projects add per-project MCP servers
+    # here. Canon MCPs come from /opt/coordination/mcp/canon.json.
+    mcpl = coord / "mcp.local.json"
+    if not mcpl.is_file():
+        mcpl.write_text('{\n  "mcpServers": {}\n}\n', encoding="utf-8")
+        info("mcp.local.json: written")
+    else:
+        info("mcp.local.json: exists")
+
+    # PROJECT.env.example — committed template; real PROJECT.env (gitignored)
+    # is copied from this and filled in per-environment with secrets.
+    pe_ex = coord / "PROJECT.env.example"
+    if not pe_ex.is_file():
+        pe_ex.write_text(
+            "# coordination/PROJECT.env.example — TEMPLATE for the real PROJECT.env.\n"
+            "#\n"
+            "# Copy this file to PROJECT.env (gitignored) and fill in real values.\n"
+            "# bin/start_agent sources PROJECT.env before launching Claude/codex/cursor\n"
+            "# so MCP servers and skill Bash blocks resolve ${VAR} via the env.\n"
+            "#\n"
+            "# Canon token-contract (full list + semantics in\n"
+            "# <canon>/templates/PROJECT.md.template):\n"
+            "\n"
+            "# Project root (usually exported automatically by start_agent; set\n"
+            "# explicitly only if you need a different value than $COORD_PROJECT_DIR).\n"
+            "#PROJECT_ROOT=/opt/your_project\n"
+            "\n"
+            "# Postgres DSN with credentials (used by postgres MCP server).\n"
+            "# Example: postgresql://user:password@host:5432/dbname\n"
+            "COORD_POSTGRES_DSN=\n"
+            "\n"
+            "# Stand hostnames (if your project has a stand).\n"
+            "STAND_HOST_A=\n"
+            "STAND_HOST_B=\n"
+            "\n"
+            "# Stand REST API base URLs.\n"
+            "STAND_URL_A=\n"
+            "STAND_URL_B=\n",
+            encoding="utf-8",
+        )
+        info("PROJECT.env.example: written")
+    else:
+        info("PROJECT.env.example: exists")
+
+    # <project>/.claude/settings.local.json — Claude Code picks this up
+    # from cwd automatically. Create with standard coordination hooks
+    # only if absent; existing files are left alone.
+    #
+    # Hook commands reference the installed entry-points by name; they
+    # must be on PATH (which pip/pipx install puts them on for the env
+    # the user runs Claude Code from).
+    cclaude = proj / ".claude"
+    ensure_dir(cclaude)
+    sl = cclaude / "settings.local.json"
+    if not sl.is_file():
+        # .format() template: {{...}} → literal {...}, single braces are subs.
+        # The Stop hook command contains a shell expansion ${COORD_ROLE:-UNKNOWN}
+        # which must reach the final file as $X; we wrap each side as {{ }}.
+        settings_tpl = (
+            "{{\n"
+            '  "permissions": {{ "allow": [] }},\n'
+            '  "autoMode": {{ "allow": ["$defaults"] }},\n'
+            '  "hooks": {{\n'
+            '    "Stop": [{{\n'
+            '      "matcher": "",\n'
+            '      "hooks": [{{\n'
+            '        "type": "command",\n'
+            '        "command": "greatminds-stop-decide \\"${{COORD_ROLE:-UNKNOWN}}\\" --host claude --project-dir {proj}"\n'
+            '      }}]\n'
+            '    }}]\n'
+            '  }}\n'
+            "}}\n"
+        )
+        sl.write_text(settings_tpl.format(proj=str(proj)), encoding="utf-8")
+        info(".claude/settings.local.json: written")
+    else:
+        info(".claude/settings.local.json: exists")
+
+    print("\ndone.")
+    print()
+    print("Next:")
+    print(f"  1. edit {proj}/coord.yaml — confirm project_dir, window list")
+    print(f"  2. edit {proj}/coordination/PROJECT.md — fill in tokens")
+    print(f"  3. run: cd {proj} && greatminds-coord-tmux")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

greatminds/cli/coord_launch.py

@@ -0,0 +1,258 @@
+"""coord-launch — multi-frontend launcher for the coordination fleet.
+
+Currently supports:
+
+  ``tmux``           Same as ``greatminds-coord-tmux`` — build a tmux session,
+                     one window per role, agent launcher pre-typed. Use that
+                     binary directly if you only need the tmux target.
+
+  ``vscode``         Generate ``.vscode/tasks.json`` and a workspace file at
+                     the project root. One task per agent role, each agent
+                     runs in its own dedicated terminal panel. User opens
+                     the project with ``code .`` then launches tasks via
+                     ``Cmd+Shift+P → Tasks: Run Task → agent: <role>``.
+
+  ``cursor-ide``     Same generated files as ``vscode`` (Cursor IDE is a
+                     VS Code fork and reads the same ``.vscode/`` config).
+                     Prints ``cursor .`` as the open command instead.
+
+The IDE targets are written as a foundation — terminals work, env vars
+propagate, but advanced features like auto-attach to existing sessions or
+panel grouping are best-effort. PRs welcome.
+
+Usage::
+
+    greatminds-coord-launch --target {tmux,vscode,cursor-ide} [--config <coord.yaml>] [--project-dir <dir>]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+import yaml
+
+from greatminds.core.util import die
+
+
+# Status colour for the agent terminals in VS Code (cycled per agent so they
+# stand out side-by-side). Names from VS Code's standard theme colour set.
+VSCODE_PANEL_COLOURS = [
+    "terminal.ansiBlue",
+    "terminal.ansiGreen",
+    "terminal.ansiYellow",
+    "terminal.ansiMagenta",
+    "terminal.ansiCyan",
+    "terminal.ansiRed",
+]
+
+
+def load_coord_yaml(cfg_path: Path) -> dict:
+    """Parse a coord.yaml file or die with a clear error."""
+    if not cfg_path.is_file():
+        die(1, f"coord.yaml not found at {cfg_path} "
+               "(pass --config or run from the project root)")
+    try:
+        data = yaml.safe_load(cfg_path.read_text(encoding="utf-8"))
+    except yaml.YAMLError as exc:
+        die(1, f"coord.yaml parse error: {exc}")
+        raise SystemExit
+    if not isinstance(data, dict):
+        die(1, "coord.yaml root must be a mapping")
+        raise SystemExit
+    return data
+
+
+def resolve_launcher() -> str:
+    """Return the absolute path to ``greatminds-start-agent`` or die.
+
+    IDE-target tasks reference this command verbatim, so it must be on PATH
+    at coord-launch time too (we resolve it now to give a clear error rather
+    than letting VS Code's task runner fail opaquely later).
+    """
+    p = shutil.which("greatminds-start-agent")
+    if p is None:
+        die(1, "greatminds-start-agent not on PATH. "
+               "Install greatminds (pip/pipx) first.")
+        raise SystemExit
+    return p
+
+
+def emit_vscode(project_dir: Path, cfg: dict, *, ide_label: str) -> None:
+    """Write ``.vscode/tasks.json`` (and a workspace file) for VS Code / Cursor IDE."""
+    launcher = resolve_launcher()
+
+    windows = cfg.get("windows") or []
+    if not isinstance(windows, list) or not windows:
+        die(1, "coord.yaml: windows must be a non-empty list")
+
+    vscode_dir = project_dir / ".vscode"
+    vscode_dir.mkdir(exist_ok=True)
+
+    tasks: list[dict] = []
+    colour_idx = 0
+    for w in windows:
+        name = w.get("name") or ""
+        role = (w.get("role") or "").upper()
+        tool = w.get("tool") or "bash"
+        mode = w.get("mode") or ""
+        if not name:
+            die(1, f"window without name: {w}")
+
+        # Bash / no-role windows: just open a project shell, no agent launch.
+        if tool == "bash" or not role:
+            task = {
+                "label": f"shell: {name}",
+                "type": "shell",
+                "command": "${env:SHELL}",
+                "presentation": {
+                    "echo": True,
+                    "reveal": "always",
+                    "panel": "dedicated",
+                    "group": "agents",
+                    "showReuseMessage": False,
+                    "clear": False,
+                },
+                "options": {
+                    "cwd": "${workspaceFolder}",
+                    "env": {
+                        "COORD_PROJECT_DIR": "${workspaceFolder}",
+                    },
+                },
+                "problemMatcher": [],
+                "runOptions": {"runOn": "default"},
+            }
+            tasks.append(task)
+            continue
+
+        cmd_args = [role, tool]
+        if mode:
+            cmd_args += ["--mode", mode]
+        cmd_line = launcher + " " + " ".join(cmd_args)
+
+        colour = VSCODE_PANEL_COLOURS[colour_idx % len(VSCODE_PANEL_COLOURS)]
+        colour_idx += 1
+
+        task = {
+            "label": f"agent: {name}",
+            "detail": f"{role} via {tool}" + (f" ({mode})" if mode else ""),
+            "type": "shell",
+            "command": cmd_line,
+            "presentation": {
+                "echo": True,
+                "reveal": "always",
+                "panel": "dedicated",
+                "group": "agents",
+                "showReuseMessage": False,
+                "clear": False,
+            },
+            "options": {
+                "cwd": "${workspaceFolder}",
+                "env": {
+                    "COORD_PROJECT_DIR": "${workspaceFolder}",
+                    "COORD_ROLE": role,
+                },
+            },
+            "problemMatcher": [],
+            "runOptions": {"runOn": "default"},
+            # VS Code allows colorising the terminal status bar per task.
+            "icon": {"id": "terminal", "color": colour},
+        }
+        tasks.append(task)
+
+    tasks_doc = {
+        "version": "2.0.0",
+        "tasks": tasks,
+    }
+    tasks_file = vscode_dir / "tasks.json"
+    tasks_file.write_text(json.dumps(tasks_doc, indent=2) + "\n", encoding="utf-8")
+
+    # Workspace file — opens VS Code with the project root and an attractive title.
+    session_name = cfg.get("session") or "agents"
+    workspace = {
+        "folders": [{"path": "."}],
+        "settings": {
+            "window.title": f"{session_name} — greatminds fleet",
+        },
+    }
+    ws_file = project_dir / f"{session_name}.code-workspace"
+    ws_file.write_text(json.dumps(workspace, indent=2) + "\n", encoding="utf-8")
+
+    print(f"wrote {tasks_file.relative_to(project_dir)} "
+          f"({len(tasks)} tasks)")
+    print(f"wrote {ws_file.relative_to(project_dir)}")
+    print()
+    print(f"open in {ide_label}:")
+    open_cmd = "code" if ide_label == "VS Code" else "cursor"
+    print(f"    {open_cmd} {ws_file.name}")
+    print()
+    print("then launch each agent terminal via:")
+    print("    Cmd/Ctrl+Shift+P → Tasks: Run Task → agent: <name>")
+    print()
+    print("each task opens a dedicated terminal panel with COORD_ROLE and "
+          "COORD_PROJECT_DIR pre-exported.")
+
+
+def emit_tmux_via_existing(args: argparse.Namespace) -> int:
+    """Delegate to greatminds-coord-tmux (the existing tmux target)."""
+    from greatminds.cli.coord_tmux import main as tmux_main
+
+    fwd: list[str] = []
+    if args.config is not None:
+        fwd += ["--config", str(args.config)]
+    if args.project_dir is not None:
+        fwd += ["--project-dir", str(args.project_dir)]
+    if args.recreate:
+        fwd.append("--recreate")
+    return tmux_main(fwd)
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point — wired up as ``greatminds-coord-launch`` in pyproject.toml."""
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0] if __doc__ else "")
+    ap.add_argument("--target", choices=["tmux", "vscode", "cursor-ide"],
+                    default="tmux",
+                    help="frontend to launch the fleet in (default: tmux)")
+    ap.add_argument("--config", type=Path,
+                    help="path to coord.yaml (default: <project>/coord.yaml)")
+    ap.add_argument("--project-dir", type=Path,
+                    help="override config.project_dir / cwd")
+    ap.add_argument("--recreate", action="store_true",
+                    help="(tmux target only) kill existing session and rebuild")
+    args = ap.parse_args(argv)
+
+    if args.target == "tmux":
+        return emit_tmux_via_existing(args)
+
+    # vscode / cursor-ide: locate coord.yaml.
+    cfg_path = args.config
+    if cfg_path is None:
+        for p in (Path.cwd() / "coord.yaml",
+                  Path.cwd() / "coordination" / "coord.yaml"):
+            if p.is_file():
+                cfg_path = p
+                break
+    if cfg_path is None or not cfg_path.is_file():
+        die(1, "coord.yaml not found (pass --config or run from project root)")
+        return 1
+
+    cfg = load_coord_yaml(cfg_path)
+    project_dir = (args.project_dir or Path(cfg.get("project_dir") or ".")).resolve()
+    if not project_dir.is_dir():
+        die(1, f"project_dir {project_dir} not found")
+        return 1
+    if not (project_dir / "coordination").is_dir():
+        die(1, f"{project_dir}/coordination/ not found "
+               "(run greatminds-coord-init first)")
+        return 1
+
+    ide_label = "VS Code" if args.target == "vscode" else "Cursor IDE"
+    emit_vscode(project_dir, cfg, ide_label=ide_label)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())