skill-dag 0.1.0__py3-none-any.whl

skill_dag-0.1.0.dist-info/METADATA

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: skill-dag
+Version: 0.1.0
+Summary: A minimal SQLite-backed DAG runner: nodes, edges, run, status.
+Author: NatesVibeCode
+License: MIT
+Project-URL: Homepage, https://github.com/NatesVibeCode/skillflow
+Project-URL: Repository, https://github.com/NatesVibeCode/skillflow
+Keywords: dag,mcp,agents,skills
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.0; extra == "mcp"
+Dynamic: license-file
+
+# Skillflow
+
+A minimal SQLite-backed DAG runner. Define nodes (shell commands) and
+dependency edges, then run the graph in topological order. Every run and
+per-node result is recorded in a plain SQLite file — no servers, no
+background services, no external dependencies beyond the Python standard
+library.
+
+## Install
+Requires Python 3.10+.
+
+```sh
+pip install skill-dag
+# with the MCP server:
+pip install "skill-dag[mcp]"
+```
+
+Or from a checkout (needed for the panel skills and `panel/run.sh`):
+
+```sh
+pip install .
+pip install ".[mcp]"
+```
+
+## Use
+
+```sh
+skillflow init
+skillflow add-node fetch --cmd "curl -s https://example.com -o page.html"
+skillflow add-node parse --cmd "python parse.py page.html"
+skillflow add-edge fetch parse
+skillflow run
+skillflow status
+```
+
+Options:
+
+- `--db PATH` (before the subcommand, e.g. `skillflow --db demo.db run`)
+  or `SKILLFLOW_DB` selects the SQLite file. Defaults to `./skillflow.db`.
+- `show` prints the DAG as JSON.
+- `status [--run ID] [--json]` shows the latest run (or a given one).
+- `run` exits nonzero if any node fails; downstream nodes do not execute
+  after a failure.
+
+## How it works
+
+Four tables: `nodes`, `edges`, `runs`, `node_results`. Execution order is
+computed with Kahn's algorithm; cycles are rejected when an edge is added
+(and re-checked at run time). Node output (stdout + stderr), exit codes,
+and timestamps are stored per run.
+
+## Panel skills
+
+Debate, brainstorm, review, and reframe run in the active conversation. Their
+prose methods do the intellectual work; a local skillflow DAG enforces the order
+and makes the session pause before moving on. Nothing launches another model.
+
+- **Debate:** ground → activate → crossfire → continue/finish → final.
+- **Brainstorm:** ground → activate → divergent field → activate → develop field →
+  final.
+- **Review:** ground → activate → intent → activate → evidence/deltas → final.
+- **Reframe:** ground → activate → stronger-shape field → lineup → continue/finish
+  → final. Generation and lineup have separate pauses.
+
+The session selects and activates lenses from the roster, shows the prose in the
+conversation, and authors every result. The DAG does not select the room, extract
+semantic tensions, decide whether an argument is good, or synthesize the answer.
+When prior decisions, corrections, rejections, or failures matter, the active
+session uses bounded semantic work-history recall during grounding. The current
+instruction and live sources govern. `rewind` archives affected artifacts and
+invalidates their dependent checkpoints when later evidence changes an earlier
+phase. A debate/reframe refusal still requires an honest final answer.
+
+```sh
+bash panel/run.sh debate "ship it friday" 3 /tmp/my-debate
+# PAUSE ground: do the grounding in the current conversation; write ground.md.
+bash panel/run.sh resume /tmp/my-debate
+# PAUSE activate-1: perform that phase, save it, then resume again.
+```
+
+Each new checkpoint returns control before accepting its artifact, even if a file
+was prefilled. Exit 1 with `PAUSE` means the current session should do the named
+work and resume, not ask a human to fill a file or approve the next phase. Do not
+batch-author future phases. `final.md` is session-authored, never a machine
+concatenation. The receipts prove sequence, not quality. The final output is the
+complete useful room, not a checklist of its conclusions.
+
+Brainstorm/review have two mandatory phases. Debate/reframe accept a 1–8 round
+ceiling (default 3); the session decides whether further rounds are worthwhile.
+Full method and recovery instructions are in
+[the shared protocol](skills/_shared/running-on-skillflow.md).
+
+Install the four skills **with their shared prose and launcher**:
+
+```sh
+python3 scripts/install_panel_skills.py --skills-dir ~/.codex/skills
+# Another local skill root can be passed instead, or with another --skills-dir.
+```
+
+The installed launcher resolves the checkout from a local location file, so it
+works from any repo. Reinstall if the checkout moves. No harness settings, other
+skills, or authentication are modified. Copying a lone SKILL.md is insufficient.
+
+Existing session DBs retain their graphs and can still use `skillflow run` from
+that session directory. `add-skill` remains a separate authoring workflow on its
+legacy graph. The selector and seed tools remain available for explicit standalone
+use and old sessions; the four conversational skills no longer depend on them.
+
+## MCP server
+
+Everything above is also an MCP server (stdio). Eight tools: `skillflow_init`,
+`skillflow_add_node`, `skillflow_add_edge`, `skillflow_show`, `skillflow_run`,
+`skillflow_status`, `panel_seed`, `panel_select_room`.
+
+```sh
+pip install "skill-dag[mcp]"
+python -m skillflow.mcp_server
+```
+
+Example client config (stdio):
+
+```json
+{
+  "mcpServers": {
+    "skillflow": {
+      "command": "python3",
+      "args": ["-m", "skillflow.mcp_server"],
+      "cwd": "/path/to/skillflow"
+    }
+  }
+}
+```
+
+Run the server from a repo checkout: the panel tools need `panel/` next to
+the engine, and pip installs ship the engine only. (The six `skillflow_*`
+tools work fine from an installed copy.)
+
+Note: panel round nodes never prompt. A round with no response stops the run
+at that stage boundary — a `run` containing an unwritten round stops there,
+by design, and resumes when the response is written.
+
+Trust boundary: this server executes arbitrary shell commands from the DAGs
+you define (`skillflow_run` is annotated destructive for exactly that
+reason). Run it locally, for your own agents only — do not expose it to
+untrusted clients or networks.
+
+### Client wiring: Codex + Muse
+
+Codex (`~/.codex/config.toml`, TOML):
+
+```toml
+[mcp_servers.skillflow]
+command = "python3"
+args = ["-m", "skillflow.mcp_server"]
+cwd = "/path/to/skillflow"
+```
+
+Muse (`~/.config/muse/settings.json`, JSON under `mcpServers`):
+
+```json
+{
+  "mcpServers": {
+    "skillflow": {
+      "command": "python3",
+      "args": ["-m", "skillflow.mcp_server"],
+      "cwd": "/path/to/skillflow"
+    }
+  }
+}
+```
+
+Point `cwd` at a repo checkout (panel tools need `panel/` beside the
+engine), or `pip install` the package and drop `cwd` for engine-only use.
+Muse documents streamable-HTTP entries; the stdio entry above is confirmed
+working.
+
+## Develop
+
+```sh
+python -m unittest discover -t . -s tests -v
+cd panel && python -m unittest test_select -v
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

skill_dag-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+skill_dag-0.1.0.dist-info/licenses/LICENSE,sha256=5EAEQA9a09Et9BXQiotsIqJDXp8FJpaEmbzy31RniUY,1068
+skillflow/__init__.py,sha256=1k7rY5W22u-oLk6GISDsmR0eu10RoKxk-jrUi9aeL6k,142
+skillflow/__main__.py,sha256=MHKZ_ae3fSLGTLUUMOx15fWdeOnJSHhq-zslRP5F5Lc,79
+skillflow/cli.py,sha256=paQtmSwExkJb7TuOF4sjbjD6jA-73etiPll8lN99_Nw,3517
+skillflow/dag.py,sha256=zzCKMZ1IkNjtp0l7ab693YjoeKudbTIR-2ZNHhXDams,7691
+skillflow/db.py,sha256=_M8i6J3SvpKvsLIUbwMi6CRoqA9Sxo_XhSCPjVbzuGo,1306
+skillflow/mcp_server.py,sha256=xt9tsLiI3coy-kqN9ll3xhnI2SIqeqG10uLi_DpFUV4,7209
+skill_dag-0.1.0.dist-info/METADATA,sha256=pi_H5ZJvpoi6eu7y8mWJDvciHfLyCYCh2yypLhXtVQ8,7306
+skill_dag-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+skill_dag-0.1.0.dist-info/entry_points.txt,sha256=OJO2E9p4Yj8b7x6lwMv8QF-Dk1ZK1xaQkXAUvAQXS0s,49
+skill_dag-0.1.0.dist-info/top_level.txt,sha256=xAVJwLQPLxsYwbCijOtzqRQRX4GmjLb_B5if8k5_0QA,10
+skill_dag-0.1.0.dist-info/RECORD,,

skill_dag-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

skill_dag-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+skillflow = skillflow.cli:main

skill_dag-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nate Roybal
+
+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.

skill_dag-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+skillflow

skillflow/__init__.py

@@ -0,0 +1,6 @@
+"""Skillflow: a minimal SQLite-backed DAG runner."""
+
+from .dag import Flow, FlowError
+
+__all__ = ["Flow", "FlowError"]
+__version__ = "0.1.0"

skillflow/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skillflow/cli.py

@@ -0,0 +1,129 @@
+"""Command line interface for skillflow."""
+
+import argparse
+import json
+import os
+import sys
+
+from .dag import Flow, FlowError
+
+DEFAULT_DB = os.environ.get("SKILLFLOW_DB", "skillflow.db")
+
+
+def _flow(args) -> Flow:
+    return Flow(args.db)
+
+
+def cmd_init(args) -> int:
+    try:
+        with _flow(args):
+            pass
+    except FlowError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(f"initialized {args.db}")
+    return 0
+
+
+def cmd_add_node(args) -> int:
+    try:
+        with _flow(args) as flow:
+            flow.add_node(args.name, args.cmd)
+    except FlowError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(f"added node {args.name!r}")
+    return 0
+
+
+def cmd_add_edge(args) -> int:
+    try:
+        with _flow(args) as flow:
+            flow.add_edge(args.from_node, args.to_node)
+    except FlowError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(f"added edge {args.from_node!r} -> {args.to_node!r}")
+    return 0
+
+
+def cmd_show(args) -> int:
+    try:
+        with _flow(args) as flow:
+            print(json.dumps({"nodes": flow.nodes(), "edges": flow.edges()}, indent=2))
+    except FlowError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+def cmd_run(args) -> int:
+    try:
+        with _flow(args) as flow:
+            run_id = flow.run()
+            result = flow.status(run_id)
+    except FlowError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    print(json.dumps(result, indent=2, default=str))
+    return 0 if result["run"]["status"] == "ok" else 1
+
+
+def cmd_status(args) -> int:
+    try:
+        with _flow(args) as flow:
+            result = flow.status(args.run)
+    except FlowError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    if args.json:
+        print(json.dumps(result, indent=2, default=str))
+    else:
+        run = result["run"]
+        print(f"run {run['id']}: {run['status']}")
+        for node in result["nodes"]:
+            print(f"  {node['name']}: {node['status']}")
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="skillflow", description="A minimal SQLite-backed DAG runner."
+    )
+    parser.add_argument("--db", default=DEFAULT_DB, help="path to the SQLite file")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p = sub.add_parser("init", help="create the database")
+    p.set_defaults(func=cmd_init)
+
+    p = sub.add_parser("add-node", help="add a node")
+    p.add_argument("name")
+    p.add_argument("--cmd", default="", help="shell command to run for this node")
+    p.set_defaults(func=cmd_add_node)
+
+    p = sub.add_parser("add-edge", help="add a dependency edge (from -> to)")
+    p.add_argument("from_node")
+    p.add_argument("to_node")
+    p.set_defaults(func=cmd_add_edge)
+
+    p = sub.add_parser("show", help="print the DAG as JSON")
+    p.set_defaults(func=cmd_show)
+
+    p = sub.add_parser("run", help="execute the DAG in topological order")
+    p.set_defaults(func=cmd_run)
+
+    p = sub.add_parser("status", help="show the latest (or given) run")
+    p.add_argument("--run", type=int, default=None)
+    p.add_argument("--json", action="store_true")
+    p.set_defaults(func=cmd_status)
+
+    return parser
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

skillflow/dag.py

@@ -0,0 +1,224 @@
+"""Core DAG operations: nodes, edges, topological run, status."""
+
+import sqlite3
+import subprocess
+from datetime import datetime, timezone
+
+from . import db as _db
+
+
+class FlowError(Exception):
+    pass
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+class Flow:
+    def __init__(self, path: str):
+        self.path = path
+        try:
+            self.conn = _db.connect(path)
+        except (sqlite3.Error, OSError) as exc:
+            raise FlowError(f"cannot open database {path!r}: {exc}") from exc
+
+    def close(self):
+        self.conn.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        self.close()
+
+    # -- definition --------------------------------------------------------
+
+    def add_node(self, name: str, cmd: str = "") -> int:
+        if not name:
+            raise FlowError("node name must not be empty")
+        try:
+            cur = self.conn.execute(
+                "INSERT INTO nodes (name, cmd) VALUES (?, ?)", (name, cmd)
+            )
+        except Exception as exc:
+            raise FlowError(f"cannot add node {name!r}: {exc}") from exc
+        self.conn.commit()
+        return cur.lastrowid
+
+    def _node_id(self, name: str) -> int:
+        row = self.conn.execute(
+            "SELECT id FROM nodes WHERE name = ?", (name,)
+        ).fetchone()
+        if row is None:
+            raise FlowError(f"unknown node {name!r}")
+        return row["id"]
+
+    def _reachable(self, start_id: int, goal_id: int) -> bool:
+        seen = {start_id}
+        stack = [start_id]
+        while stack:
+            current = stack.pop()
+            if current == goal_id:
+                return True
+            for row in self.conn.execute(
+                "SELECT to_id FROM edges WHERE from_id = ?", (current,)
+            ):
+                if row["to_id"] not in seen:
+                    seen.add(row["to_id"])
+                    stack.append(row["to_id"])
+        return False
+
+    def add_edge(self, from_name: str, to_name: str) -> None:
+        from_id = self._node_id(from_name)
+        to_id = self._node_id(to_name)
+        if from_id == to_id:
+            raise FlowError("a node cannot depend on itself")
+        if self._reachable(to_id, from_id):
+            raise FlowError(
+                f"edge {from_name!r} -> {to_name!r} would create a cycle"
+            )
+        try:
+            self.conn.execute(
+                "INSERT INTO edges (from_id, to_id) VALUES (?, ?)",
+                (from_id, to_id),
+            )
+        except Exception as exc:
+            raise FlowError(f"cannot add edge: {exc}") from exc
+        self.conn.commit()
+
+    def nodes(self) -> list:
+        return [
+            dict(row)
+            for row in self.conn.execute("SELECT id, name, cmd FROM nodes ORDER BY name")
+        ]
+
+    def edges(self) -> list:
+        return [
+            dict(row)
+            for row in self.conn.execute(
+                """SELECT f.name AS from_name, t.name AS to_name
+                   FROM edges e
+                   JOIN nodes f ON f.id = e.from_id
+                   JOIN nodes t ON t.id = e.to_id
+                   ORDER BY from_name, to_name"""
+            )
+        ]
+
+    # -- execution ----------------------------------------------------------
+
+    def order(self) -> list:
+        nodes = {row["id"]: row for row in self.conn.execute("SELECT * FROM nodes")}
+        indegree = {nid: 0 for nid in nodes}
+        outgoing: dict = {nid: [] for nid in nodes}
+        for row in self.conn.execute("SELECT from_id, to_id FROM edges"):
+            outgoing[row["from_id"]].append(row["to_id"])
+            indegree[row["to_id"]] += 1
+        queue = sorted(n for n, d in indegree.items() if d == 0)
+        result = []
+        while queue:
+            nid = queue.pop(0)
+            result.append(nodes[nid])
+            for nxt in sorted(outgoing[nid]):
+                indegree[nxt] -= 1
+                if indegree[nxt] == 0:
+                    queue.append(nxt)
+        if len(result) != len(nodes):
+            raise FlowError("graph contains a cycle")
+        return [dict(r) for r in result]
+
+    def run(self) -> int:
+        ordered = self.order()
+        try:
+            return self._run_ordered(ordered)
+        except sqlite3.Error as exc:
+            raise FlowError(f"database is busy or locked: {exc}") from exc
+
+    def _run_ordered(self, ordered: list) -> int:
+        started = _now()
+        # Runs left behind by a killed process never finish on their own;
+        # mark them interrupted so they stop masquerading as the latest run.
+        self.conn.execute(
+            "UPDATE runs SET status = 'interrupted', finished_at = ? "
+            "WHERE status = 'running'",
+            (started,),
+        )
+        self.conn.execute(
+            """UPDATE node_results SET status = 'interrupted', finished_at = ?
+               WHERE status = 'running'""",
+            (started,),
+        )
+        self.conn.commit()
+        cur = self.conn.execute(
+            "INSERT INTO runs (started_at, status) VALUES (?, 'running')", (started,)
+        )
+        run_id = cur.lastrowid
+        self.conn.commit()
+        overall = "ok"
+        for node in ordered:
+            node_started = _now()
+            self.conn.execute(
+                """INSERT INTO node_results
+                   (run_id, node_id, status, started_at)
+                   VALUES (?, ?, 'running', ?)""",
+                (run_id, node["id"], node_started),
+            )
+            self.conn.commit()
+            try:
+                proc = subprocess.run(
+                    node["cmd"],
+                    shell=True,
+                    capture_output=True,
+                    text=True,
+                    timeout=3600,
+                )
+                status = "ok" if proc.returncode == 0 else "failed"
+                output = (proc.stdout or "") + (proc.stderr or "")
+                exit_code = proc.returncode
+            except Exception as exc:
+                status = "failed"
+                output = str(exc)
+                exit_code = None
+            self.conn.execute(
+                """UPDATE node_results
+                   SET status = ?, exit_code = ?, output = ?, finished_at = ?
+                   WHERE run_id = ? AND node_id = ?""",
+                (status, exit_code, output, _now(), run_id, node["id"]),
+            )
+            self.conn.commit()
+            if status != "ok":
+                overall = "failed"
+                break
+        self.conn.execute(
+            "UPDATE runs SET status = ?, finished_at = ? WHERE id = ?",
+            (overall, _now(), run_id),
+        )
+        self.conn.commit()
+        return run_id
+
+    def status(self, run_id: int | None = None) -> dict:
+        if run_id is None:
+            row = self.conn.execute(
+                "SELECT id FROM runs ORDER BY id DESC LIMIT 1"
+            ).fetchone()
+            if row is None:
+                raise FlowError("no runs yet")
+            run_id = row["id"]
+        run = self.conn.execute(
+            "SELECT * FROM runs WHERE id = ?", (run_id,)
+        ).fetchone()
+        if run is None:
+            raise FlowError(f"unknown run {run_id}")
+        results = [
+            dict(r)
+            for r in self.conn.execute(
+                """SELECT n.name, r.status, r.exit_code, r.output,
+                          r.started_at, r.finished_at
+                   FROM node_results r
+                   JOIN nodes n ON n.id = r.node_id
+                   WHERE r.run_id = ?
+                   ORDER BY r.rowid""",
+                (run_id,),
+            )
+        ]
+        return {"run": dict(run), "nodes": results}

skillflow/db.py

@@ -0,0 +1,42 @@
+"""SQLite schema and connection handling for skillflow."""
+
+import sqlite3
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS nodes (
+    id   INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL UNIQUE,
+    cmd  TEXT NOT NULL DEFAULT ''
+);
+CREATE TABLE IF NOT EXISTS edges (
+    id      INTEGER PRIMARY KEY AUTOINCREMENT,
+    from_id INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+    to_id   INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+    UNIQUE (from_id, to_id),
+    CHECK (from_id != to_id)
+);
+CREATE TABLE IF NOT EXISTS runs (
+    id          INTEGER PRIMARY KEY AUTOINCREMENT,
+    started_at  TEXT NOT NULL,
+    finished_at TEXT,
+    status      TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS node_results (
+    run_id      INTEGER NOT NULL REFERENCES runs(id) ON DELETE CASCADE,
+    node_id     INTEGER NOT NULL REFERENCES nodes(id) ON DELETE CASCADE,
+    status      TEXT NOT NULL,
+    exit_code   INTEGER,
+    output      TEXT NOT NULL DEFAULT '',
+    started_at  TEXT,
+    finished_at TEXT,
+    PRIMARY KEY (run_id, node_id)
+);
+"""
+
+
+def connect(path: str, timeout: float = 30.0) -> sqlite3.Connection:
+    conn = sqlite3.connect(path, timeout=timeout)
+    conn.row_factory = sqlite3.Row
+    conn.execute("PRAGMA foreign_keys = ON")
+    conn.executescript(SCHEMA)
+    return conn

skillflow/mcp_server.py

@@ -0,0 +1,204 @@
+"""Skillflow MCP server: DAG runner + panel room selection as MCP tools.
+
+Run with:  python -m skillflow.mcp_server
+ exposure: stdio transport.
+"""
+
+import os
+import sys
+
+REPO_ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
+PANEL_DIR = os.path.join(REPO_ROOT, "panel")
+sys.path.insert(0, PANEL_DIR)
+
+try:
+    from mcp.server.fastmcp import FastMCP  # noqa: E402
+    from mcp.types import ToolAnnotations  # noqa: E402
+except ImportError:
+    print("error: the 'mcp' package is not installed.",
+          "Install the server extra: pip install 'skill-dag[mcp]',",
+          file=sys.stderr)
+    raise SystemExit(2)
+
+from .dag import Flow, FlowError  # noqa: E402
+
+READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False,
+                            idempotentHint=True, openWorldHint=False)
+WRITE_SAFE = ToolAnnotations(readOnlyHint=False, destructiveHint=False,
+                             idempotentHint=False, openWorldHint=False)
+WRITE_IDEMPOTENT = ToolAnnotations(readOnlyHint=False, destructiveHint=False,
+                                   idempotentHint=True, openWorldHint=False)
+EXECUTES_SHELL = ToolAnnotations(readOnlyHint=False, destructiveHint=True,
+                                 idempotentHint=False, openWorldHint=False)
+
+
+def _panel_file(name: str) -> str:
+    path = os.path.join(PANEL_DIR, name)
+    if not os.path.isfile(path):
+        raise FileNotFoundError(
+            f"panel data missing at {path}; the panel tools need a repo "
+            f"checkout (pip installs ship the engine only)")
+    return path
+
+mcp = FastMCP("skillflow")
+
+
+OUTPUT_LIMIT = 2000
+
+HINTS = [
+    ("would create a cycle", "Use skillflow_show to see the current edges."),
+    ("unknown node", "Use skillflow_show to list node names."),
+    ("unknown run", "Call skillflow_status without a run id for the latest."),
+    ("no runs yet", "Call skillflow_run first."),
+    ("cannot open database", "Check the db path; use skillflow_init to create it."),
+]
+
+
+def _err(exc: Exception) -> dict:
+    message = str(exc)
+    for needle, hint in HINTS:
+        if needle in message:
+            return {"ok": False, "error": message, "hint": hint}
+    return {"ok": False, "error": message}
+
+
+def _trim_run(result: dict) -> dict:
+    for node in result.get("nodes", []):
+        output = node.get("output") or ""
+        if len(output) > OUTPUT_LIMIT:
+            node["output"] = output[:OUTPUT_LIMIT]
+            node["truncated"] = True
+    return result
+
+
+@mcp.tool(annotations=WRITE_IDEMPOTENT)
+def skillflow_init(db: str = "skillflow.db") -> dict:
+    """Create a skillflow SQLite database (idempotent)."""
+    try:
+        with Flow(db):
+            pass
+    except FlowError as exc:
+        return _err(exc)
+    return {"ok": True, "db": db}
+
+
+@mcp.tool(annotations=WRITE_SAFE)
+def skillflow_add_node(db: str = "skillflow.db", name: str = "",
+                       cmd: str = "") -> dict:
+    """Add a node (a shell command) to the DAG."""
+    try:
+        with Flow(db) as flow:
+            node_id = flow.add_node(name, cmd)
+    except FlowError as exc:
+        return _err(exc)
+    return {"ok": True, "id": node_id, "name": name}
+
+
+@mcp.tool(annotations=WRITE_SAFE)
+def skillflow_add_edge(db: str = "skillflow.db", from_node: str = "",
+                       to_node: str = "") -> dict:
+    """Add a dependency edge (from_node runs before to_node). Rejects cycles."""
+    try:
+        with Flow(db) as flow:
+            flow.add_edge(from_node, to_node)
+    except FlowError as exc:
+        return _err(exc)
+    return {"ok": True, "from": from_node, "to": to_node}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def skillflow_show(db: str = "skillflow.db") -> dict:
+    """Show the DAG's nodes and edges."""
+    with Flow(db) as flow:
+        return {"ok": True, "nodes": flow.nodes(), "edges": flow.edges()}
+
+
+def _run_common(db: str, run: int | None, execute: bool) -> dict:
+    try:
+        with Flow(db) as flow:
+            run_id = flow.run() if execute else run
+            result = flow.status(run_id)
+    except FlowError as exc:
+        return _err(exc)
+    result["ok"] = True
+    return _trim_run(result)
+
+
+@mcp.tool(annotations=EXECUTES_SHELL)
+def skillflow_run(db: str = "skillflow.db") -> dict:
+    """Execute the DAG in topological order and return the run record.
+
+    Use after defining nodes and edges with skillflow_add_node /
+    skillflow_add_edge. The first failing node stops downstream nodes;
+    the returned record shows per-node status, exit codes, and output
+    (trimmed to 2000 chars per node). Gate nodes that prompt on a
+    terminal fail closed without one — a run containing an unanswered
+    gate stops there, which is the correct outcome, not an error.
+    """
+    return _run_common(db, None, execute=True)
+
+
+@mcp.tool(annotations=READ_ONLY)
+def skillflow_status(db: str = "skillflow.db", run: int | None = None) -> dict:
+    """Show the latest run, or the given run id, with per-node results.
+
+    Use to inspect a previous run without executing anything. Omit `run`
+    for the latest. Returns run status plus each executed node's status,
+    exit code, and trimmed output.
+    """
+    return _run_common(db, run, execute=False)
+
+
+@mcp.tool(annotations=WRITE_IDEMPOTENT)
+def panel_seed(db: str = "skillflow.db") -> dict:
+    """Seed the panelists table in a session DB. Run once before selecting."""
+    try:
+        source = _panel_file("panelists.json")
+        _panel_file("seed.py")
+        import seed as seed_mod
+        count = seed_mod.seed(db, source)
+    except Exception as exc:  # noqa: BLE001 - surfaced as tool error
+        return _err(exc)
+    return {"ok": True, "panelists": count, "db": db}
+
+
+@mcp.tool(annotations=READ_ONLY)
+def panel_select_room(db: str = "skillflow.db", tensions: str = "",
+                      size: int = 4, exclude_ids: list[str] | None = None) -> dict:
+    """Seat a panel room from the 128-person roster in the session DB.
+
+    `tensions` is comma-separated situation topics (e.g.
+    "risk,measurement"); panelists are ranked by token overlap with their
+    tags, lens, and attributes, then diversity is enforced: one per family,
+    3-5 seats, near-duplicate tag sets skipped. Pass `exclude_ids` with
+    earlier rooms' member ids to keep later rounds fresh. Requires
+    panel_seed to have run once on this DB.
+    """
+    if not 3 <= size <= 5:
+        return {"ok": False, "error": "--size must be 3-5"}
+    try:
+        _panel_file("select_room.py")
+        import select_room as selector
+        panelists = selector.load_panelists(db)
+    except Exception as exc:  # noqa: BLE001 - surfaced as tool error
+        return {"ok": False,
+                "error": f"cannot load panelists (run panel_seed?): {exc}"}
+    parsed = [t.strip() for t in tensions.split(",") if t.strip()]
+    room = selector.select(panelists, parsed, size, set(exclude_ids or ()))
+    return {
+        "ok": True,
+        "tensions": parsed,
+        "room": [
+            {"name": p["name"], "id": p["id"], "family": p["family"],
+             "lens": p["lens"], "score": selector.score(parsed, p)}
+            for p in room
+        ],
+    }
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()