skill-dag 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- skill_dag-0.1.0/LICENSE +21 -0
- skill_dag-0.1.0/PKG-INFO +209 -0
- skill_dag-0.1.0/README.md +186 -0
- skill_dag-0.1.0/pyproject.toml +36 -0
- skill_dag-0.1.0/setup.cfg +4 -0
- skill_dag-0.1.0/skill_dag.egg-info/PKG-INFO +209 -0
- skill_dag-0.1.0/skill_dag.egg-info/SOURCES.txt +21 -0
- skill_dag-0.1.0/skill_dag.egg-info/dependency_links.txt +1 -0
- skill_dag-0.1.0/skill_dag.egg-info/entry_points.txt +2 -0
- skill_dag-0.1.0/skill_dag.egg-info/requires.txt +3 -0
- skill_dag-0.1.0/skill_dag.egg-info/top_level.txt +1 -0
- skill_dag-0.1.0/skillflow/__init__.py +6 -0
- skill_dag-0.1.0/skillflow/__main__.py +4 -0
- skill_dag-0.1.0/skillflow/cli.py +129 -0
- skill_dag-0.1.0/skillflow/dag.py +224 -0
- skill_dag-0.1.0/skillflow/db.py +42 -0
- skill_dag-0.1.0/skillflow/mcp_server.py +204 -0
- skill_dag-0.1.0/tests/test_dag.py +106 -0
- skill_dag-0.1.0/tests/test_harness_skill_drift.py +100 -0
- skill_dag-0.1.0/tests/test_legacy_panel_runner.py +182 -0
- skill_dag-0.1.0/tests/test_panel_runner.py +193 -0
- skill_dag-0.1.0/tests/test_panel_stage.py +261 -0
- skill_dag-0.1.0/tests/test_ui_crawl_dag.py +67 -0
skill_dag-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Nate Roybal
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
skill_dag-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: skill-dag
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A minimal SQLite-backed DAG runner: nodes, edges, run, status.
|
|
5
|
+
Author: NatesVibeCode
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/NatesVibeCode/skillflow
|
|
8
|
+
Project-URL: Repository, https://github.com/NatesVibeCode/skillflow
|
|
9
|
+
Keywords: dag,mcp,agents,skills
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Provides-Extra: mcp
|
|
21
|
+
Requires-Dist: mcp<2,>=1.0; extra == "mcp"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Skillflow
|
|
25
|
+
|
|
26
|
+
A minimal SQLite-backed DAG runner. Define nodes (shell commands) and
|
|
27
|
+
dependency edges, then run the graph in topological order. Every run and
|
|
28
|
+
per-node result is recorded in a plain SQLite file — no servers, no
|
|
29
|
+
background services, no external dependencies beyond the Python standard
|
|
30
|
+
library.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
Requires Python 3.10+.
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
pip install skill-dag
|
|
37
|
+
# with the MCP server:
|
|
38
|
+
pip install "skill-dag[mcp]"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Or from a checkout (needed for the panel skills and `panel/run.sh`):
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
pip install .
|
|
45
|
+
pip install ".[mcp]"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Use
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
skillflow init
|
|
52
|
+
skillflow add-node fetch --cmd "curl -s https://example.com -o page.html"
|
|
53
|
+
skillflow add-node parse --cmd "python parse.py page.html"
|
|
54
|
+
skillflow add-edge fetch parse
|
|
55
|
+
skillflow run
|
|
56
|
+
skillflow status
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Options:
|
|
60
|
+
|
|
61
|
+
- `--db PATH` (before the subcommand, e.g. `skillflow --db demo.db run`)
|
|
62
|
+
or `SKILLFLOW_DB` selects the SQLite file. Defaults to `./skillflow.db`.
|
|
63
|
+
- `show` prints the DAG as JSON.
|
|
64
|
+
- `status [--run ID] [--json]` shows the latest run (or a given one).
|
|
65
|
+
- `run` exits nonzero if any node fails; downstream nodes do not execute
|
|
66
|
+
after a failure.
|
|
67
|
+
|
|
68
|
+
## How it works
|
|
69
|
+
|
|
70
|
+
Four tables: `nodes`, `edges`, `runs`, `node_results`. Execution order is
|
|
71
|
+
computed with Kahn's algorithm; cycles are rejected when an edge is added
|
|
72
|
+
(and re-checked at run time). Node output (stdout + stderr), exit codes,
|
|
73
|
+
and timestamps are stored per run.
|
|
74
|
+
|
|
75
|
+
## Panel skills
|
|
76
|
+
|
|
77
|
+
Debate, brainstorm, review, and reframe run in the active conversation. Their
|
|
78
|
+
prose methods do the intellectual work; a local skillflow DAG enforces the order
|
|
79
|
+
and makes the session pause before moving on. Nothing launches another model.
|
|
80
|
+
|
|
81
|
+
- **Debate:** ground → activate → crossfire → continue/finish → final.
|
|
82
|
+
- **Brainstorm:** ground → activate → divergent field → activate → develop field →
|
|
83
|
+
final.
|
|
84
|
+
- **Review:** ground → activate → intent → activate → evidence/deltas → final.
|
|
85
|
+
- **Reframe:** ground → activate → stronger-shape field → lineup → continue/finish
|
|
86
|
+
→ final. Generation and lineup have separate pauses.
|
|
87
|
+
|
|
88
|
+
The session selects and activates lenses from the roster, shows the prose in the
|
|
89
|
+
conversation, and authors every result. The DAG does not select the room, extract
|
|
90
|
+
semantic tensions, decide whether an argument is good, or synthesize the answer.
|
|
91
|
+
When prior decisions, corrections, rejections, or failures matter, the active
|
|
92
|
+
session uses bounded semantic work-history recall during grounding. The current
|
|
93
|
+
instruction and live sources govern. `rewind` archives affected artifacts and
|
|
94
|
+
invalidates their dependent checkpoints when later evidence changes an earlier
|
|
95
|
+
phase. A debate/reframe refusal still requires an honest final answer.
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
bash panel/run.sh debate "ship it friday" 3 /tmp/my-debate
|
|
99
|
+
# PAUSE ground: do the grounding in the current conversation; write ground.md.
|
|
100
|
+
bash panel/run.sh resume /tmp/my-debate
|
|
101
|
+
# PAUSE activate-1: perform that phase, save it, then resume again.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Each new checkpoint returns control before accepting its artifact, even if a file
|
|
105
|
+
was prefilled. Exit 1 with `PAUSE` means the current session should do the named
|
|
106
|
+
work and resume, not ask a human to fill a file or approve the next phase. Do not
|
|
107
|
+
batch-author future phases. `final.md` is session-authored, never a machine
|
|
108
|
+
concatenation. The receipts prove sequence, not quality. The final output is the
|
|
109
|
+
complete useful room, not a checklist of its conclusions.
|
|
110
|
+
|
|
111
|
+
Brainstorm/review have two mandatory phases. Debate/reframe accept a 1–8 round
|
|
112
|
+
ceiling (default 3); the session decides whether further rounds are worthwhile.
|
|
113
|
+
Full method and recovery instructions are in
|
|
114
|
+
[the shared protocol](skills/_shared/running-on-skillflow.md).
|
|
115
|
+
|
|
116
|
+
Install the four skills **with their shared prose and launcher**:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
python3 scripts/install_panel_skills.py --skills-dir ~/.codex/skills
|
|
120
|
+
# Another local skill root can be passed instead, or with another --skills-dir.
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The installed launcher resolves the checkout from a local location file, so it
|
|
124
|
+
works from any repo. Reinstall if the checkout moves. No harness settings, other
|
|
125
|
+
skills, or authentication are modified. Copying a lone SKILL.md is insufficient.
|
|
126
|
+
|
|
127
|
+
Existing session DBs retain their graphs and can still use `skillflow run` from
|
|
128
|
+
that session directory. `add-skill` remains a separate authoring workflow on its
|
|
129
|
+
legacy graph. The selector and seed tools remain available for explicit standalone
|
|
130
|
+
use and old sessions; the four conversational skills no longer depend on them.
|
|
131
|
+
|
|
132
|
+
## MCP server
|
|
133
|
+
|
|
134
|
+
Everything above is also an MCP server (stdio). Eight tools: `skillflow_init`,
|
|
135
|
+
`skillflow_add_node`, `skillflow_add_edge`, `skillflow_show`, `skillflow_run`,
|
|
136
|
+
`skillflow_status`, `panel_seed`, `panel_select_room`.
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
pip install "skill-dag[mcp]"
|
|
140
|
+
python -m skillflow.mcp_server
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Example client config (stdio):
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"mcpServers": {
|
|
148
|
+
"skillflow": {
|
|
149
|
+
"command": "python3",
|
|
150
|
+
"args": ["-m", "skillflow.mcp_server"],
|
|
151
|
+
"cwd": "/path/to/skillflow"
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Run the server from a repo checkout: the panel tools need `panel/` next to
|
|
158
|
+
the engine, and pip installs ship the engine only. (The six `skillflow_*`
|
|
159
|
+
tools work fine from an installed copy.)
|
|
160
|
+
|
|
161
|
+
Note: panel round nodes never prompt. A round with no response stops the run
|
|
162
|
+
at that stage boundary — a `run` containing an unwritten round stops there,
|
|
163
|
+
by design, and resumes when the response is written.
|
|
164
|
+
|
|
165
|
+
Trust boundary: this server executes arbitrary shell commands from the DAGs
|
|
166
|
+
you define (`skillflow_run` is annotated destructive for exactly that
|
|
167
|
+
reason). Run it locally, for your own agents only — do not expose it to
|
|
168
|
+
untrusted clients or networks.
|
|
169
|
+
|
|
170
|
+
### Client wiring: Codex + Muse
|
|
171
|
+
|
|
172
|
+
Codex (`~/.codex/config.toml`, TOML):
|
|
173
|
+
|
|
174
|
+
```toml
|
|
175
|
+
[mcp_servers.skillflow]
|
|
176
|
+
command = "python3"
|
|
177
|
+
args = ["-m", "skillflow.mcp_server"]
|
|
178
|
+
cwd = "/path/to/skillflow"
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Muse (`~/.config/muse/settings.json`, JSON under `mcpServers`):
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
{
|
|
185
|
+
"mcpServers": {
|
|
186
|
+
"skillflow": {
|
|
187
|
+
"command": "python3",
|
|
188
|
+
"args": ["-m", "skillflow.mcp_server"],
|
|
189
|
+
"cwd": "/path/to/skillflow"
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Point `cwd` at a repo checkout (panel tools need `panel/` beside the
|
|
196
|
+
engine), or `pip install` the package and drop `cwd` for engine-only use.
|
|
197
|
+
Muse documents streamable-HTTP entries; the stdio entry above is confirmed
|
|
198
|
+
working.
|
|
199
|
+
|
|
200
|
+
## Develop
|
|
201
|
+
|
|
202
|
+
```sh
|
|
203
|
+
python -m unittest discover -t . -s tests -v
|
|
204
|
+
cd panel && python -m unittest test_select -v
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# Skillflow
|
|
2
|
+
|
|
3
|
+
A minimal SQLite-backed DAG runner. Define nodes (shell commands) and
|
|
4
|
+
dependency edges, then run the graph in topological order. Every run and
|
|
5
|
+
per-node result is recorded in a plain SQLite file — no servers, no
|
|
6
|
+
background services, no external dependencies beyond the Python standard
|
|
7
|
+
library.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
Requires Python 3.10+.
|
|
11
|
+
|
|
12
|
+
```sh
|
|
13
|
+
pip install skill-dag
|
|
14
|
+
# with the MCP server:
|
|
15
|
+
pip install "skill-dag[mcp]"
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Or from a checkout (needed for the panel skills and `panel/run.sh`):
|
|
19
|
+
|
|
20
|
+
```sh
|
|
21
|
+
pip install .
|
|
22
|
+
pip install ".[mcp]"
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
## Use
|
|
26
|
+
|
|
27
|
+
```sh
|
|
28
|
+
skillflow init
|
|
29
|
+
skillflow add-node fetch --cmd "curl -s https://example.com -o page.html"
|
|
30
|
+
skillflow add-node parse --cmd "python parse.py page.html"
|
|
31
|
+
skillflow add-edge fetch parse
|
|
32
|
+
skillflow run
|
|
33
|
+
skillflow status
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Options:
|
|
37
|
+
|
|
38
|
+
- `--db PATH` (before the subcommand, e.g. `skillflow --db demo.db run`)
|
|
39
|
+
or `SKILLFLOW_DB` selects the SQLite file. Defaults to `./skillflow.db`.
|
|
40
|
+
- `show` prints the DAG as JSON.
|
|
41
|
+
- `status [--run ID] [--json]` shows the latest run (or a given one).
|
|
42
|
+
- `run` exits nonzero if any node fails; downstream nodes do not execute
|
|
43
|
+
after a failure.
|
|
44
|
+
|
|
45
|
+
## How it works
|
|
46
|
+
|
|
47
|
+
Four tables: `nodes`, `edges`, `runs`, `node_results`. Execution order is
|
|
48
|
+
computed with Kahn's algorithm; cycles are rejected when an edge is added
|
|
49
|
+
(and re-checked at run time). Node output (stdout + stderr), exit codes,
|
|
50
|
+
and timestamps are stored per run.
|
|
51
|
+
|
|
52
|
+
## Panel skills
|
|
53
|
+
|
|
54
|
+
Debate, brainstorm, review, and reframe run in the active conversation. Their
|
|
55
|
+
prose methods do the intellectual work; a local skillflow DAG enforces the order
|
|
56
|
+
and makes the session pause before moving on. Nothing launches another model.
|
|
57
|
+
|
|
58
|
+
- **Debate:** ground → activate → crossfire → continue/finish → final.
|
|
59
|
+
- **Brainstorm:** ground → activate → divergent field → activate → develop field →
|
|
60
|
+
final.
|
|
61
|
+
- **Review:** ground → activate → intent → activate → evidence/deltas → final.
|
|
62
|
+
- **Reframe:** ground → activate → stronger-shape field → lineup → continue/finish
|
|
63
|
+
→ final. Generation and lineup have separate pauses.
|
|
64
|
+
|
|
65
|
+
The session selects and activates lenses from the roster, shows the prose in the
|
|
66
|
+
conversation, and authors every result. The DAG does not select the room, extract
|
|
67
|
+
semantic tensions, decide whether an argument is good, or synthesize the answer.
|
|
68
|
+
When prior decisions, corrections, rejections, or failures matter, the active
|
|
69
|
+
session uses bounded semantic work-history recall during grounding. The current
|
|
70
|
+
instruction and live sources govern. `rewind` archives affected artifacts and
|
|
71
|
+
invalidates their dependent checkpoints when later evidence changes an earlier
|
|
72
|
+
phase. A debate/reframe refusal still requires an honest final answer.
|
|
73
|
+
|
|
74
|
+
```sh
|
|
75
|
+
bash panel/run.sh debate "ship it friday" 3 /tmp/my-debate
|
|
76
|
+
# PAUSE ground: do the grounding in the current conversation; write ground.md.
|
|
77
|
+
bash panel/run.sh resume /tmp/my-debate
|
|
78
|
+
# PAUSE activate-1: perform that phase, save it, then resume again.
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
Each new checkpoint returns control before accepting its artifact, even if a file
|
|
82
|
+
was prefilled. Exit 1 with `PAUSE` means the current session should do the named
|
|
83
|
+
work and resume, not ask a human to fill a file or approve the next phase. Do not
|
|
84
|
+
batch-author future phases. `final.md` is session-authored, never a machine
|
|
85
|
+
concatenation. The receipts prove sequence, not quality. The final output is the
|
|
86
|
+
complete useful room, not a checklist of its conclusions.
|
|
87
|
+
|
|
88
|
+
Brainstorm/review have two mandatory phases. Debate/reframe accept a 1–8 round
|
|
89
|
+
ceiling (default 3); the session decides whether further rounds are worthwhile.
|
|
90
|
+
Full method and recovery instructions are in
|
|
91
|
+
[the shared protocol](skills/_shared/running-on-skillflow.md).
|
|
92
|
+
|
|
93
|
+
Install the four skills **with their shared prose and launcher**:
|
|
94
|
+
|
|
95
|
+
```sh
|
|
96
|
+
python3 scripts/install_panel_skills.py --skills-dir ~/.codex/skills
|
|
97
|
+
# Another local skill root can be passed instead, or with another --skills-dir.
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
The installed launcher resolves the checkout from a local location file, so it
|
|
101
|
+
works from any repo. Reinstall if the checkout moves. No harness settings, other
|
|
102
|
+
skills, or authentication are modified. Copying a lone SKILL.md is insufficient.
|
|
103
|
+
|
|
104
|
+
Existing session DBs retain their graphs and can still use `skillflow run` from
|
|
105
|
+
that session directory. `add-skill` remains a separate authoring workflow on its
|
|
106
|
+
legacy graph. The selector and seed tools remain available for explicit standalone
|
|
107
|
+
use and old sessions; the four conversational skills no longer depend on them.
|
|
108
|
+
|
|
109
|
+
## MCP server
|
|
110
|
+
|
|
111
|
+
Everything above is also an MCP server (stdio). Eight tools: `skillflow_init`,
|
|
112
|
+
`skillflow_add_node`, `skillflow_add_edge`, `skillflow_show`, `skillflow_run`,
|
|
113
|
+
`skillflow_status`, `panel_seed`, `panel_select_room`.
|
|
114
|
+
|
|
115
|
+
```sh
|
|
116
|
+
pip install "skill-dag[mcp]"
|
|
117
|
+
python -m skillflow.mcp_server
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
Example client config (stdio):
|
|
121
|
+
|
|
122
|
+
```json
|
|
123
|
+
{
|
|
124
|
+
"mcpServers": {
|
|
125
|
+
"skillflow": {
|
|
126
|
+
"command": "python3",
|
|
127
|
+
"args": ["-m", "skillflow.mcp_server"],
|
|
128
|
+
"cwd": "/path/to/skillflow"
|
|
129
|
+
}
|
|
130
|
+
}
|
|
131
|
+
}
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
Run the server from a repo checkout: the panel tools need `panel/` next to
|
|
135
|
+
the engine, and pip installs ship the engine only. (The six `skillflow_*`
|
|
136
|
+
tools work fine from an installed copy.)
|
|
137
|
+
|
|
138
|
+
Note: panel round nodes never prompt. A round with no response stops the run
|
|
139
|
+
at that stage boundary — a `run` containing an unwritten round stops there,
|
|
140
|
+
by design, and resumes when the response is written.
|
|
141
|
+
|
|
142
|
+
Trust boundary: this server executes arbitrary shell commands from the DAGs
|
|
143
|
+
you define (`skillflow_run` is annotated destructive for exactly that
|
|
144
|
+
reason). Run it locally, for your own agents only — do not expose it to
|
|
145
|
+
untrusted clients or networks.
|
|
146
|
+
|
|
147
|
+
### Client wiring: Codex + Muse
|
|
148
|
+
|
|
149
|
+
Codex (`~/.codex/config.toml`, TOML):
|
|
150
|
+
|
|
151
|
+
```toml
|
|
152
|
+
[mcp_servers.skillflow]
|
|
153
|
+
command = "python3"
|
|
154
|
+
args = ["-m", "skillflow.mcp_server"]
|
|
155
|
+
cwd = "/path/to/skillflow"
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
Muse (`~/.config/muse/settings.json`, JSON under `mcpServers`):
|
|
159
|
+
|
|
160
|
+
```json
|
|
161
|
+
{
|
|
162
|
+
"mcpServers": {
|
|
163
|
+
"skillflow": {
|
|
164
|
+
"command": "python3",
|
|
165
|
+
"args": ["-m", "skillflow.mcp_server"],
|
|
166
|
+
"cwd": "/path/to/skillflow"
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
```
|
|
171
|
+
|
|
172
|
+
Point `cwd` at a repo checkout (panel tools need `panel/` beside the
|
|
173
|
+
engine), or `pip install` the package and drop `cwd` for engine-only use.
|
|
174
|
+
Muse documents streamable-HTTP entries; the stdio entry above is confirmed
|
|
175
|
+
working.
|
|
176
|
+
|
|
177
|
+
## Develop
|
|
178
|
+
|
|
179
|
+
```sh
|
|
180
|
+
python -m unittest discover -t . -s tests -v
|
|
181
|
+
cd panel && python -m unittest test_select -v
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
## License
|
|
185
|
+
|
|
186
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
[project]
|
|
2
|
+
name = "skill-dag"
|
|
3
|
+
version = "0.1.0"
|
|
4
|
+
description = "A minimal SQLite-backed DAG runner: nodes, edges, run, status."
|
|
5
|
+
readme = "README.md"
|
|
6
|
+
requires-python = ">=3.10"
|
|
7
|
+
license = { text = "MIT" }
|
|
8
|
+
authors = [{ name = "NatesVibeCode" }]
|
|
9
|
+
keywords = ["dag", "mcp", "agents", "skills"]
|
|
10
|
+
classifiers = [
|
|
11
|
+
"License :: OSI Approved :: MIT License",
|
|
12
|
+
"Operating System :: OS Independent",
|
|
13
|
+
"Programming Language :: Python :: 3",
|
|
14
|
+
"Programming Language :: Python :: 3.10",
|
|
15
|
+
"Programming Language :: Python :: 3.11",
|
|
16
|
+
"Programming Language :: Python :: 3.12",
|
|
17
|
+
"Programming Language :: Python :: 3.13",
|
|
18
|
+
]
|
|
19
|
+
|
|
20
|
+
[project.urls]
|
|
21
|
+
Homepage = "https://github.com/NatesVibeCode/skillflow"
|
|
22
|
+
Repository = "https://github.com/NatesVibeCode/skillflow"
|
|
23
|
+
|
|
24
|
+
[project.scripts]
|
|
25
|
+
skillflow = "skillflow.cli:main"
|
|
26
|
+
|
|
27
|
+
[project.optional-dependencies]
|
|
28
|
+
mcp = ["mcp>=1.0,<2"]
|
|
29
|
+
|
|
30
|
+
[build-system]
|
|
31
|
+
requires = ["setuptools>=61"]
|
|
32
|
+
build-backend = "setuptools.build_meta"
|
|
33
|
+
|
|
34
|
+
[tool.setuptools.packages.find]
|
|
35
|
+
where = ["."]
|
|
36
|
+
include = ["skillflow*"]
|
|
@@ -0,0 +1,209 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: skill-dag
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A minimal SQLite-backed DAG runner: nodes, edges, run, status.
|
|
5
|
+
Author: NatesVibeCode
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/NatesVibeCode/skillflow
|
|
8
|
+
Project-URL: Repository, https://github.com/NatesVibeCode/skillflow
|
|
9
|
+
Keywords: dag,mcp,agents,skills
|
|
10
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
11
|
+
Classifier: Operating System :: OS Independent
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.10
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
Provides-Extra: mcp
|
|
21
|
+
Requires-Dist: mcp<2,>=1.0; extra == "mcp"
|
|
22
|
+
Dynamic: license-file
|
|
23
|
+
|
|
24
|
+
# Skillflow
|
|
25
|
+
|
|
26
|
+
A minimal SQLite-backed DAG runner. Define nodes (shell commands) and
|
|
27
|
+
dependency edges, then run the graph in topological order. Every run and
|
|
28
|
+
per-node result is recorded in a plain SQLite file — no servers, no
|
|
29
|
+
background services, no external dependencies beyond the Python standard
|
|
30
|
+
library.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
Requires Python 3.10+.
|
|
34
|
+
|
|
35
|
+
```sh
|
|
36
|
+
pip install skill-dag
|
|
37
|
+
# with the MCP server:
|
|
38
|
+
pip install "skill-dag[mcp]"
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
Or from a checkout (needed for the panel skills and `panel/run.sh`):
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
pip install .
|
|
45
|
+
pip install ".[mcp]"
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Use
|
|
49
|
+
|
|
50
|
+
```sh
|
|
51
|
+
skillflow init
|
|
52
|
+
skillflow add-node fetch --cmd "curl -s https://example.com -o page.html"
|
|
53
|
+
skillflow add-node parse --cmd "python parse.py page.html"
|
|
54
|
+
skillflow add-edge fetch parse
|
|
55
|
+
skillflow run
|
|
56
|
+
skillflow status
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
Options:
|
|
60
|
+
|
|
61
|
+
- `--db PATH` (before the subcommand, e.g. `skillflow --db demo.db run`)
|
|
62
|
+
or `SKILLFLOW_DB` selects the SQLite file. Defaults to `./skillflow.db`.
|
|
63
|
+
- `show` prints the DAG as JSON.
|
|
64
|
+
- `status [--run ID] [--json]` shows the latest run (or a given one).
|
|
65
|
+
- `run` exits nonzero if any node fails; downstream nodes do not execute
|
|
66
|
+
after a failure.
|
|
67
|
+
|
|
68
|
+
## How it works
|
|
69
|
+
|
|
70
|
+
Four tables: `nodes`, `edges`, `runs`, `node_results`. Execution order is
|
|
71
|
+
computed with Kahn's algorithm; cycles are rejected when an edge is added
|
|
72
|
+
(and re-checked at run time). Node output (stdout + stderr), exit codes,
|
|
73
|
+
and timestamps are stored per run.
|
|
74
|
+
|
|
75
|
+
## Panel skills
|
|
76
|
+
|
|
77
|
+
Debate, brainstorm, review, and reframe run in the active conversation. Their
|
|
78
|
+
prose methods do the intellectual work; a local skillflow DAG enforces the order
|
|
79
|
+
and makes the session pause before moving on. Nothing launches another model.
|
|
80
|
+
|
|
81
|
+
- **Debate:** ground → activate → crossfire → continue/finish → final.
|
|
82
|
+
- **Brainstorm:** ground → activate → divergent field → activate → develop field →
|
|
83
|
+
final.
|
|
84
|
+
- **Review:** ground → activate → intent → activate → evidence/deltas → final.
|
|
85
|
+
- **Reframe:** ground → activate → stronger-shape field → lineup → continue/finish
|
|
86
|
+
→ final. Generation and lineup have separate pauses.
|
|
87
|
+
|
|
88
|
+
The session selects and activates lenses from the roster, shows the prose in the
|
|
89
|
+
conversation, and authors every result. The DAG does not select the room, extract
|
|
90
|
+
semantic tensions, decide whether an argument is good, or synthesize the answer.
|
|
91
|
+
When prior decisions, corrections, rejections, or failures matter, the active
|
|
92
|
+
session uses bounded semantic work-history recall during grounding. The current
|
|
93
|
+
instruction and live sources govern. `rewind` archives affected artifacts and
|
|
94
|
+
invalidates their dependent checkpoints when later evidence changes an earlier
|
|
95
|
+
phase. A debate/reframe refusal still requires an honest final answer.
|
|
96
|
+
|
|
97
|
+
```sh
|
|
98
|
+
bash panel/run.sh debate "ship it friday" 3 /tmp/my-debate
|
|
99
|
+
# PAUSE ground: do the grounding in the current conversation; write ground.md.
|
|
100
|
+
bash panel/run.sh resume /tmp/my-debate
|
|
101
|
+
# PAUSE activate-1: perform that phase, save it, then resume again.
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
Each new checkpoint returns control before accepting its artifact, even if a file
|
|
105
|
+
was prefilled. Exit 1 with `PAUSE` means the current session should do the named
|
|
106
|
+
work and resume, not ask a human to fill a file or approve the next phase. Do not
|
|
107
|
+
batch-author future phases. `final.md` is session-authored, never a machine
|
|
108
|
+
concatenation. The receipts prove sequence, not quality. The final output is the
|
|
109
|
+
complete useful room, not a checklist of its conclusions.
|
|
110
|
+
|
|
111
|
+
Brainstorm/review have two mandatory phases. Debate/reframe accept a 1–8 round
|
|
112
|
+
ceiling (default 3); the session decides whether further rounds are worthwhile.
|
|
113
|
+
Full method and recovery instructions are in
|
|
114
|
+
[the shared protocol](skills/_shared/running-on-skillflow.md).
|
|
115
|
+
|
|
116
|
+
Install the four skills **with their shared prose and launcher**:
|
|
117
|
+
|
|
118
|
+
```sh
|
|
119
|
+
python3 scripts/install_panel_skills.py --skills-dir ~/.codex/skills
|
|
120
|
+
# Another local skill root can be passed instead, or with another --skills-dir.
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The installed launcher resolves the checkout from a local location file, so it
|
|
124
|
+
works from any repo. Reinstall if the checkout moves. No harness settings, other
|
|
125
|
+
skills, or authentication are modified. Copying a lone SKILL.md is insufficient.
|
|
126
|
+
|
|
127
|
+
Existing session DBs retain their graphs and can still use `skillflow run` from
|
|
128
|
+
that session directory. `add-skill` remains a separate authoring workflow on its
|
|
129
|
+
legacy graph. The selector and seed tools remain available for explicit standalone
|
|
130
|
+
use and old sessions; the four conversational skills no longer depend on them.
|
|
131
|
+
|
|
132
|
+
## MCP server
|
|
133
|
+
|
|
134
|
+
Everything above is also an MCP server (stdio). Eight tools: `skillflow_init`,
|
|
135
|
+
`skillflow_add_node`, `skillflow_add_edge`, `skillflow_show`, `skillflow_run`,
|
|
136
|
+
`skillflow_status`, `panel_seed`, `panel_select_room`.
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
pip install "skill-dag[mcp]"
|
|
140
|
+
python -m skillflow.mcp_server
|
|
141
|
+
```
|
|
142
|
+
|
|
143
|
+
Example client config (stdio):
|
|
144
|
+
|
|
145
|
+
```json
|
|
146
|
+
{
|
|
147
|
+
"mcpServers": {
|
|
148
|
+
"skillflow": {
|
|
149
|
+
"command": "python3",
|
|
150
|
+
"args": ["-m", "skillflow.mcp_server"],
|
|
151
|
+
"cwd": "/path/to/skillflow"
|
|
152
|
+
}
|
|
153
|
+
}
|
|
154
|
+
}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
Run the server from a repo checkout: the panel tools need `panel/` next to
|
|
158
|
+
the engine, and pip installs ship the engine only. (The six `skillflow_*`
|
|
159
|
+
tools work fine from an installed copy.)
|
|
160
|
+
|
|
161
|
+
Note: panel round nodes never prompt. A round with no response stops the run
|
|
162
|
+
at that stage boundary — a `run` containing an unwritten round stops there,
|
|
163
|
+
by design, and resumes when the response is written.
|
|
164
|
+
|
|
165
|
+
Trust boundary: this server executes arbitrary shell commands from the DAGs
|
|
166
|
+
you define (`skillflow_run` is annotated destructive for exactly that
|
|
167
|
+
reason). Run it locally, for your own agents only — do not expose it to
|
|
168
|
+
untrusted clients or networks.
|
|
169
|
+
|
|
170
|
+
### Client wiring: Codex + Muse
|
|
171
|
+
|
|
172
|
+
Codex (`~/.codex/config.toml`, TOML):
|
|
173
|
+
|
|
174
|
+
```toml
|
|
175
|
+
[mcp_servers.skillflow]
|
|
176
|
+
command = "python3"
|
|
177
|
+
args = ["-m", "skillflow.mcp_server"]
|
|
178
|
+
cwd = "/path/to/skillflow"
|
|
179
|
+
```
|
|
180
|
+
|
|
181
|
+
Muse (`~/.config/muse/settings.json`, JSON under `mcpServers`):
|
|
182
|
+
|
|
183
|
+
```json
|
|
184
|
+
{
|
|
185
|
+
"mcpServers": {
|
|
186
|
+
"skillflow": {
|
|
187
|
+
"command": "python3",
|
|
188
|
+
"args": ["-m", "skillflow.mcp_server"],
|
|
189
|
+
"cwd": "/path/to/skillflow"
|
|
190
|
+
}
|
|
191
|
+
}
|
|
192
|
+
}
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Point `cwd` at a repo checkout (panel tools need `panel/` beside the
|
|
196
|
+
engine), or `pip install` the package and drop `cwd` for engine-only use.
|
|
197
|
+
Muse documents streamable-HTTP entries; the stdio entry above is confirmed
|
|
198
|
+
working.
|
|
199
|
+
|
|
200
|
+
## Develop
|
|
201
|
+
|
|
202
|
+
```sh
|
|
203
|
+
python -m unittest discover -t . -s tests -v
|
|
204
|
+
cd panel && python -m unittest test_select -v
|
|
205
|
+
```
|
|
206
|
+
|
|
207
|
+
## License
|
|
208
|
+
|
|
209
|
+
MIT. See [LICENSE](LICENSE).
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
LICENSE
|
|
2
|
+
README.md
|
|
3
|
+
pyproject.toml
|
|
4
|
+
skill_dag.egg-info/PKG-INFO
|
|
5
|
+
skill_dag.egg-info/SOURCES.txt
|
|
6
|
+
skill_dag.egg-info/dependency_links.txt
|
|
7
|
+
skill_dag.egg-info/entry_points.txt
|
|
8
|
+
skill_dag.egg-info/requires.txt
|
|
9
|
+
skill_dag.egg-info/top_level.txt
|
|
10
|
+
skillflow/__init__.py
|
|
11
|
+
skillflow/__main__.py
|
|
12
|
+
skillflow/cli.py
|
|
13
|
+
skillflow/dag.py
|
|
14
|
+
skillflow/db.py
|
|
15
|
+
skillflow/mcp_server.py
|
|
16
|
+
tests/test_dag.py
|
|
17
|
+
tests/test_harness_skill_drift.py
|
|
18
|
+
tests/test_legacy_panel_runner.py
|
|
19
|
+
tests/test_panel_runner.py
|
|
20
|
+
tests/test_panel_stage.py
|
|
21
|
+
tests/test_ui_crawl_dag.py
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|