From qino
Read this alongside `agents/concept.md` or `agents/dev.md` when `protocol: "qino"` is detected in the workspace config.
How this agent operates — its isolation, permissions, and tool access model
Agent reference
qino:agents/protocol-structureThe summary Claude sees when deciding whether to delegate to this agent
Read this alongside `agents/concept.md` or `agents/dev.md` when `protocol: "qino"` is detected in the workspace config. **For concept workflows:** These sections **replace** the File Structure Awareness, Facets, and Ecosystem Work sections in concept.md — all other principles (alive thread, mirror/echo, momentum, tone, reasoning, draft awareness, core intent) remain unchanged. **For dev workflo...
Read this alongside agents/concept.md or agents/dev.md when protocol: "qino" is detected in the workspace config.
For concept workflows: These sections replace the File Structure Awareness, Facets, and Ecosystem Work sections in concept.md — all other principles (alive thread, mirror/echo, momentum, tone, reasoning, draft awareness, core intent) remain unchanged.
For dev workflows: The "Dev Structure (Protocol)" section below supplements agents/dev.md — replacing legacy path references with protocol equivalents.
For operational decisions (when to journal, when to create nodes, when to add edges), consult references/protocol/protocol.md — Part 1: Operations.
graph.json is your registry. It lists all nodes (with type, status, dir) and edges (with type, context). Use the dir field to locate node directories under nodes/.
Key behavioral rules:
graph.json first for any operation that needs to know what existsnodes/<dir>/ containing node.json, story.md, content/story.md is the impulse — read it to feel the concept's center, not to get a summarycontent/ holds developed material — file names are descriptive, not rigidannotations/ (if present) holds marginal notes about the contentnode.json contains metadata: title, type, status, created, tags, held_threadsNodes have types that shape how you engage:
| Type | What it is | How to engage |
|---|---|---|
concept | A developed idea with impulse, content, possibly facets | Full exploration: alive thread, work modes, sub-graph |
ecosystem | Cross-cutting system-level work | Hold questions longer — distinction-making, not just development |
facet | A navigable aspect of a parent concept | Same depth as concept, but awareness of parent context |
arc | A temporal container tracking emergence | Read for context; arcs accumulate naturally |
navigator | An orientation document for building | Reference for terrain; not actively explored like concepts |
Ecosystem nodes follow the same principle as ecosystem work in concept.md: distinction-making that shapes the whole. Hold the diverging movement longer.
Edges in graph.json connect nodes with a context sentence that explains why the connection matters.
Read edges to understand neighborhood: Which nodes are nearby? What does the context sentence tell you about how they relate to your current work? Follow edges whose context is relevant.
Create edges when:
Edge context is a short sentence — why this relationship exists, and how future agents should understand it. Write a context sentence that helps future agents understand why this connection matters for their work. Don't classify — describe. A good context sentence reads like a note left for someone who will arrive here later: "this node's emergence patterns informed the cycle design here" or "tension between these two approaches shaped the architecture."
Three ways to organize information. Each has different signal propagation, and the choice shapes what future agents can see.
Content files (content/01.md, content/02.md) — flat history within a node. All annotations on the node flow to neighbors via connectedSignals. Use for: iteration history, research that should stay visible from outside, sequential work on one concern.
Edges between separate nodes — full bidirectional signal flow. Annotations on either node propagate to the other's neighborhood. Use for: peers that should see each other's signals, cross-cutting patterns, related initiatives, sequential experiments where each run's findings should inform the next.
Sub-graphs (node contains its own graph.json + nodes/) — containment boundary. Signals inside the sub-graph do NOT propagate to the parent's neighbors. Only annotations on the parent node itself flow outward. Use for: internal structure that shouldn't flood the neighborhood — facets of a concept, sessions of an experiment, implementation detail beneath an initiative.
The key question: does this information need to flow outward to neighbors, or is it internal detail?
Prefer edges over sub-graphs unless you specifically need containment. A sub-graph without outward edges is invisible to autonomous agents navigating the graph. An edge-connected structure is alive — signals flow, neighborhoods grow, agents can follow paths.
Bubbling up from sub-graphs: When something important surfaces inside a sub-graph, write an annotation on the parent node or create a cross-graph edge from the child to an external node. This is how sub-graph discoveries become visible to the broader ecosystem.
A node that has facets contains its own graph.json and nodes/ directory. This is recursive — the same structure at every level.
Detection: Check for graph.json inside a node directory. If present, this node has a navigable sub-graph.
Offering navigation: When arriving at a concept with facets, include:
[title] has facets:
[facet-1]
[facet-2]
explore a facet, or stay at this level?
Exploring a facet is the same operation as exploring any node — resolve the path from the sub-graph and proceed. The parent context remains ambient.
Creating facets: In the protocol, facets are full nodes in a sub-graph. To create a facet:
nodes/<parent>/nodes/<facet-dir>/ with node.json, story.mdnodes/<parent>/graph.jsongraph.json firstjournal.md at the workspace root is a bidirectional channel. It uses context markers:
## section-title
<!-- context: context-type -->
Content.
Read journal for temporal awareness — what happened recently, what context markers exist.
Append to journal when:
Never overwrite existing journal content. Append only, at the bottom.
Captures are not graph nodes. They are independent flat files under the workspace root ({workspace root}/.qino/captures/), outside any graph.
YYYY-MM-DD_essence.md — title, timestamp, contentCross-concept signals during exploration also create flat capture files (not graph nodes).
Same principle as legacy — offer without reading, hold without pushing. But held threads live in node.json per-node, not in a global manifest.
{
"held_threads": [
"thread description"
]
}
Offer when: user's response echoes a held thread's theme, or user seems stuck with relevant threads nearby.
Never: read or surface held threads unprompted. Offer gently, accept decline immediately.
Read this section alongside agents/dev.md when protocol: "qino" is detected. These translations replace legacy paths throughout the dev agent's workflows.
| Legacy Path | Protocol Path | Notes |
|---|---|---|
implementations/[app]/implementation.md | {nodesDir}/{app}/story.md | Technical context, stack, boundaries, flags |
implementations/[app]/iterations/ | {nodesDir}/{app}/content/ | Iteration files with NN-name.md pattern |
implementations/[app]/iterations/01-foundation.md | {nodesDir}/{app}/content/01-foundation.md | Same naming convention, different parent |
implementations/graph.json (manual entries) | graph.json with nodesDir (auto-discovery) | No manual node registration needed |
manifest.json (concept last_touched) | Git log on concept path | No stored timestamps |
concepts/[id]/concept.md | {conceptsWorkspace}/nodes/{concept-id}/story.md | Concept impulse + content/ for developed material |
{nodesDir}/{app}/
node.json # Identity: title, type, status, created
story.md # Technical context (replaces implementation.md)
content/ # Iteration files (replaces iterations/)
01-foundation.md
02-feature-name.md
annotations/ # Proposals, observations (if present)
On arrival at an implementation node:
"concept grounds" — the target is a cross-graph reference (e.g., "qino-concepts:qino-world")git -C {conceptsPath} log -1 --format=%ci -- {nodesDir}/{concept-id}/ → last concept changegit log -1 --format=%ci -- {nodesDir}/{app}/ → last implementation workIf no "concept grounds" edge exists, the implementation has no linked concept — skip sync.
{conceptsWorkspace}/nodes/{concept-id}/story.md{conceptsWorkspace}/nodes/{concept-id}/content/{conceptsWorkspace}/nodes/{concept-id}/node.json"concept grounds" edge target prefix (may be relative path like "qino-concepts"){nodesDir}/{app}/content/ directory01-, 02-, etc.)When drift is detected and user chooses to update the concept:
story.md or files in content/ at {conceptsWorkspace}/nodes/{concept-id}/Manages AI prompt library on prompts.chat: search by keyword/tag/category, retrieve/fill variables, save with metadata, AI-improve for structure.
Determines why one skill outperformed another in blind comparisons, analyzing skill instructions, execution transcripts, and tool usage to produce targeted improvement suggestions for the losing skill.
npx claudepluginhub qinolabs/qino-claude --plugin qino