@paradigma-inc/flywheel 0.1.10 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paradigma-inc/flywheel",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "One-command setup for Flywheel MCP hosts",
   "type": "module",
   "files": [

package/skills/flywheel/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: flywheel
-description: Use for Flywheel experiment design, MCP-assisted execution, and platform setup/troubleshooting across supported hosts.
+description: Use for Flywheel experiment design, turning source material into Flywheel graphs, staged frontier planning with `/lookahead`, budgeted autonomous research with `/fsd`, MCP-assisted execution, and platform setup/troubleshooting across supported hosts.
 ---
 
 # Flywheel Skill
@@ -12,6 +12,9 @@ Use this skill to structure research work and to route setup/support questions t
 Use this skill when the conversation is about any of the following:
 
 - planning experiments, hypotheses, comparisons, or next-branch decisions
+- turning source material into a Flywheel graph
+- using command-like Flywheel workflows such as `/to-graph`, `/reproduce`,
+  `/lookahead`, or `/fsd`
 - running or interpreting empirical work in Flywheel
 - choosing between `insight` and `empirical` nodes
 - setting up, updating, authenticating, or troubleshooting Flywheel MCP
@@ -23,17 +26,23 @@ If the request is ambiguous, default to experiment-design guidance before platfo
 
 1. Classify the request as research guidance, platform support, or mixed.
 2. Load only the minimum files needed for the current task.
-3. For research requests, run a short design pass before execution:
+3. If the user is using command-like language such as `/to-graph`,
+   `/reproduce`, `/lookahead`, or `/fsd`, load
+   `reference/command-presets.md` first.
+4. For research requests, run a short design pass before execution:
    ask 1-2 questions to clarify objective, assumptions, and decision criteria.
-4. If design is solid and the user wants to proceed, shift to execution support.
-5. Use Flywheel MCP tools for live behavior/contract checks when available.
-6. Summarize evidence and propose the most likely next branch.
+5. If design is solid and the user wants to proceed, shift to execution support.
+6. Use Flywheel MCP tools for live behavior/contract checks when available.
+7. Summarize evidence and propose the most likely next branch.
 
 ## Routing Map
 
 Choose one primary file first, then add at most one supporting file only if needed:
 
 - `reference/experiment-design-protocol.md` for structured experiment design and readiness checks
+- `reference/command-presets.md` for `/to-graph`, `/reproduce`, `/lookahead`,
+  and `/fsd`
+- `reference/wiki-porting.md` when the user asks to port a markdown/wiki corpus
 - `reference/flywheel-mcp-tool-map.md` for exact tool surface and contract behavior
 - `getting-started/flywheel-tutorial-overview.md` for orientation and learning path
 - `getting-started/flywheel-quickstart.md` for fastest first-use setup and auth recovery
@@ -50,3 +59,12 @@ Choose one primary file first, then add at most one supporting file only if need
 - Prefer concrete steps and decision points over long narrative explanations.
 - Do not run broad document reads; load only what is required by the current request.
 - Do not start compute-heavy execution before design intent is clear.
+- Keep `/reproduce` narrow: validate existing knowledge claims rather than
+  expanding an open-ended research frontier.
+- Treat `/lookahead` as planning only and `/fsd` as budgeted autonomous
+  frontier advancement.
+
+## Wiki Porting
+
+When asked to port a markdown wiki, load `reference/wiki-porting.md` before
+acting.

package/skills/flywheel/agents/openai.yaml

@@ -1,7 +1,7 @@
 interface:
   display_name: "Flywheel"
-  short_description: "Guide Flywheel experiment design, setup, tools, and workflows"
-  default_prompt: "Use $flywheel to answer Flywheel experiment, setup, MCP tool, compute, campaign, or Web UI questions."
+  short_description: "Guide Flywheel graph planning, research, and setup"
+  default_prompt: "Use $flywheel to answer Flywheel experiment, graph, setup, MCP tool, compute, campaign, or Web UI questions. Treat /to-graph as graph construction only, /reproduce as budgeted validation of existing knowledge, /lookahead as staged frontier planning, and /fsd as budgeted autonomous frontier advancement that stays n steps ahead."
 
 dependencies:
   tools:

package/skills/flywheel/reference/command-presets.md

@@ -0,0 +1,230 @@
+# Command Presets
+
+Use this guide when the user frames the request as `/to-graph`,
+`/reproduce`, `/lookahead`, `/fsd`, or equivalent command-like language.
+
+These are workflow presets inside the Flywheel skill. They are not separate
+product surfaces.
+
+## `/to-graph`
+
+Use `/to-graph` when the user's main goal is to convert unstructured source
+material into a Flywheel graph.
+
+Typical inputs:
+
+- paper
+- blogpost
+- README
+- markdown wiki
+- research notes
+
+Output contract:
+
+- create or update a root node or subtree
+- put the primary narrative in node `content`
+- attach supporting files as artifacts
+- add only durable graph edges
+
+Execution policy:
+
+- do not acquire compute by default
+- do not spend budget implicitly
+- execution only happens if the user explicitly asks to run branches
+
+Default mapping:
+
+- stable page or concept -> one node
+- main markdown/text -> `content`
+- short synopsis -> `summary`
+- figures, PDFs, datasets, notebooks, code, tables -> artifacts
+- durable semantic relationships -> edges
+- ordinary hyperlinks or citations -> remain in markdown unless they deserve an
+  actual graph relationship
+
+## `/reproduce`
+
+Use `/reproduce` when the source is claim-bearing and the user wants Flywheel
+to both structure the source and run empirical validation.
+
+`/reproduce` is conceptually:
+
+```text
+/to-graph --mode reproduce --execute
+```
+
+That means:
+
+1. graphify the source first
+2. split it into explicit validation branches
+3. execute those branches within a hard maximum budget
+
+Typical sources:
+
+- research papers
+- benchmark claims
+- blogposts with strong empirical claims
+- replication requests on an existing Flywheel graph
+
+Budget semantics:
+
+- a max budget is a hard ceiling, not a soft preference
+- if no max budget is given, ask for one before any compute acquisition
+- until the budget is explicit, planning and graph construction may proceed, but
+  empirical execution should not start
+- prefer the highest-information, lowest-cost branches first
+- stop when the claim is resolved or the budget limit is reached
+
+Default branch types:
+
+- baseline sanity check
+- mechanism or intermediate-signal check
+- ablation
+- efficiency or overhead check
+- robustness or failure-mode check
+- follow-up analysis branch after results land
+
+## `/lookahead`
+
+Use `/lookahead` when the user wants Flywheel to plan the next frontier of work
+from an existing set of nodes without executing it yet.
+
+`/lookahead` is conceptually:
+
+```text
+/plan-frontier --execute=false
+```
+
+That means:
+
+1. resolve a starting set of Flywheel nodes
+2. resolve a measurable objective for those nodes
+3. expand the frontier into staged next-step nodes
+
+Starting-node policy:
+
+- prefer explicit node ids, slugs, or directly named nodes
+- otherwise use the focused or recently referenced graph context
+- if no stable starting set can be recovered, ask
+
+Objective policy:
+
+- if the objective is missing, ask for one
+- if the user insists on not specifying it, infer the objective from the graph
+  context and state it explicitly before planning
+- the objective must be measurable enough to rank frontier branches
+
+Lookahead policy:
+
+- depth `n` means plan `n` hops ahead from the currently resolved frontier
+- default `n=1`
+- width `k` means expand up to `k` non-redundant frontier directions
+- avoid redundant siblings that only restate the same branch with different
+  wording
+
+Node-typing policy:
+
+- if a planned node is expected to produce evidence or artifacts, type it
+  `empirical`
+- otherwise type it `insight`
+- leave planned nodes staged until the underlying work has a resolution
+
+Output contract:
+
+- create or update a graph-local planning contract
+- write the objective, depth `n`, width `k`, and terminal condition into the
+  graph
+- stage the next frontier of nodes without hidden execution
+
+## `/fsd`
+
+Use `/fsd` ("full self-driving") when the user wants Flywheel to keep
+advancing a research frontier autonomously under a specified budget.
+
+`/fsd` is conceptually:
+
+```text
+/lookahead --execute --replan-after-each-resolution
+```
+
+That means:
+
+1. resolve starting nodes
+2. resolve a measurable objective
+3. resolve a hard budget
+4. expand the frontier up to depth `n` and width `k`
+5. execute up to `k` frontier branches in parallel
+6. refresh the lookahead after each resolved node so the graph stays `n` hops
+   ahead
+
+Budget semantics:
+
+- credits are the default budget unit unless the user specifies another
+  measurable budget semantic
+- the budget is a hard ceiling, not a soft preference
+- if no budget is given, ask before execution starts
+- if the user supplies a non-credit budget unit, persist that exact unit in the
+  graph-local control contract
+
+Objective policy:
+
+- if the objective is missing, ask for one
+- if the user refuses to specify it, infer it from the existing graph context
+  and state it explicitly before execution
+- the objective must be precise enough that the model can decide whether a
+  branch is advancing or stalling it
+
+Width and worker policy:
+
+- `k` always means maximum distinct frontier directions
+- in `/fsd`, that same `k` also caps concurrent workers
+- if more than `k` worthwhile branches exist, route the extra branches in
+  sequence via the parent model
+
+Termination policy:
+
+- do not rely on new user feedback to decide whether to continue
+- before execution, persist a graph-local terminal condition that later steps
+  can read directly from node state
+- stop when the persisted condition is met, for example:
+  - objective reached
+  - hard budget exhausted
+  - no non-redundant frontier branch with positive expected value remains
+
+Graph-maintenance policy:
+
+- keep unresolved planned nodes staged
+- commit nodes only when their work has a resolution
+- empirical nodes should accumulate the expected evidence or artifact before
+  completion
+- insight nodes should only be committed once the synthesis is actually known
+
+## Choosing Between Them
+
+Use `/to-graph` when the user wants structure from source material.
+
+Use `/reproduce` when the user wants structure plus budgeted validation of
+existing knowledge.
+
+Use `/lookahead` when the user wants staged next-step planning from existing
+nodes.
+
+Use `/fsd` when the user wants budgeted autonomous frontier advancement.
+
+If a graph starts as `/lookahead`, `/fsd` should resume from the same graph and
+keep it `n` steps ahead rather than planning from scratch each time.
+
+## Guardrails
+
+- Do not hide spend behind `/to-graph`.
+- Do not treat `/reproduce` as a magical bulk importer.
+- Do not blur `/reproduce` and `/fsd`.
+- `/reproduce` validates existing knowledge claims.
+- `/fsd` expands the frontier to create new knowledge under budget.
+- Build the graph explicitly with nodes, artifacts, and selected edges.
+- Keep the source material legible in `content`; do not dump everything into
+  artifacts.
+- Keep `/reproduce` scoped by cost and decision value, not by exhaustively
+  trying every possible branch.
+- Keep `/fsd` graph-local: future continuation and stopping decisions should be
+  derivable from the persisted node state rather than from fresh chat context.

package/skills/flywheel/reference/wiki-porting.md

@@ -0,0 +1,92 @@
+# Wiki Porting
+
+Use this guide when the source material is a markdown wiki, README corpus, or a
+Karpathy-style LLM wiki that should become Flywheel nodes.
+
+## Default Mapping
+
+- One wiki page or stable concept -> one Flywheel node.
+- The main page markdown -> the node body/readme field (`content`).
+- A short synopsis of the page -> `summary`.
+- Images, PDFs, datasets, notebooks, code snippets, and other supporting files
+  -> node artifacts.
+- Durable structural relationships -> graph edges.
+- Ordinary wiki hyperlinks -> remain markdown links inside the node body.
+
+Do not try to preserve the source wiki as a file-first mirror inside Flywheel.
+Flywheel is node-first.
+
+## What The Model Should Do
+
+Assume the model is expected to perform the port directly unless the user
+explicitly asks to build a dedicated importer.
+
+That means:
+
+1. Read the source pages and supporting files.
+2. Create/update nodes explicitly.
+3. Write the page body into node `content`.
+4. Publish supporting files as artifacts.
+5. Add only the graph edges that materially help reasoning or navigation.
+
+Do not wait for a magical "import this wiki" product surface if the available
+Flywheel primitives are already enough.
+
+## `flywheel_import_subgraph`
+
+Use `flywheel_import_subgraph` only when the input is already normalized into
+Flywheel node JSON with DAG-safe edges.
+
+Do not use it for raw markdown repositories because those are usually:
+
+- file-centric rather than node-centric
+- heavily cross-linked
+- cyclic in ways that are natural for a wiki but not a clean Flywheel graph
+
+Treat raw wiki content as authoring input, not as a direct subgraph payload.
+
+## Edge Policy
+
+Promote a relation to a graph edge only when it carries durable meaning such as:
+
+- hierarchy or decomposition
+- prerequisite/dependency
+- derived-from or result-of
+- canonical comparison target
+
+Do not create edges for every incidental mention, backlink, or navigational
+cross-reference. Keep those inside the markdown body instead.
+
+## Inline Artifact Embeds
+
+When the node body supports inline artifact rendering, keep references on their
+own lines so the renderer can replace them with the matching artifact preview.
+
+Examples:
+
+```md
+![Loss curve](loss-curve.png)
+
+[Evaluation metrics](metrics.json)
+```
+
+Guidelines:
+
+- Upload the artifact first, then reference it from the body.
+- Keep filenames stable enough for the renderer to match them.
+- Use inline embeds for supporting visuals/data, but keep the main explanation
+  in the node body itself.
+- If a reference does not match an artifact, it should remain valid markdown
+  rather than break the page.
+
+## Recommended Node Authoring Sequence
+
+1. Create the node with `flywheel_stage_node_create` if it does not exist.
+2. Read the latest node with `flywheel_get_node` before writes that need fresh
+   `expected_revision`.
+3. Stage node fields with `flywheel_stage_node_update`, putting the primary
+   markdown in `content`.
+4. Publish each supporting file with `flywheel_prepare_artifact_publish`.
+5. Add selected graph structure through the relevant graph tools when that
+   relationship matters.
+6. Commit once the node snapshot is coherent.