qino Skill

Ecology for developing ideas. Natural language activation — users describe intent, Claude routes to the appropriate workflow.

Execution Mode

Workflows execute in one of two modes based on their nature:

Inject Mode (Dialogue Workflows)

For: home, explore, capture, test, attune, compare, arc, orientation, lab, navigate, bug

These workflows involve multi-turn dialogue with the user. They execute in the main conversation — no Task tool, no subagent.

When a dialogue workflow is triggered:

1. Read the workflow file (e.g., workflows/explore.md)
2. Read the agent file, extract content between <!-- INJECT-START --> and <!-- INJECT-END --> markers
3. Follow the persona principles and workflow instructions directly
4. Continue the conversation as that persona — first visible output is dialogue, not process

The persona is invisible. Do not announce "PERSONA ACTIVE" or show any process. Just follow the principles and workflow naturally.

Example (inject mode):

User: "explore qinolabs-homepage"

Claude: [Reads workflows/explore.md and agents/concept.md]
        [Follows concept persona principles]
        [Responds directly as the concept agent would]

"What part of qinolabs-homepage still feels alive when you think about it?"

Spawn Mode (Synthesis Workflows)

For: import, dev-work, dev-init, dev-setup, workspace-init, research-init, research-setup, concept-init, concept-setup

These workflows involve heavy file reading, code changes, or scaffolding. They execute in an isolated subagent via the Task tool.

When a synthesis workflow is triggered:

1. Spawn the agent using Task tool with appropriate subagent_type:

   • qino:concept — for import, concept-init, concept-setup
   • qino:dev — for dev-init, dev-setup, workspace-init, dev-work
   • qino:research — for research-init, research-setup

2. Pass context in the Task prompt:

   • The detected workspace context
   • The user's intent/request
   • The workflow to execute
   • Momentum context if present

3. Let the agent work — agent returns results; main conversation stays clean

Example (spawn mode):

User: "bring in /path/to/notes.md"

Claude: [Uses Task tool]
  subagent_type: "qino:concept"
  prompt: "Read and follow the workflow at plugins/qino/skills/qino/workflows/import.md

           Context:
           - Workspace: concepts at /path/to/concepts-repo
           - Source file: /path/to/notes.md

           User wants to import this material into concepts."

Why Two Modes?

Inject mode preserves full conversation context — essential for dialogue where user's words and energy matter.

Spawn mode provides context isolation — prevents heavy file reading and synthesis from filling the main context window.

Context Detection (First Step)

Before routing, detect workspace context:

1. Check for .claude/qino-config.json in current directory
2. Read repoType field to determine context and apply structure conventions (see references/dev/repo-conventions.md for patterns)

3. Extract relevant paths:

   • conceptsRepo — path to concepts repository (for implementation projects)
   • researchRepo — path to research repository
   • linkedConcept — primary linked concept ID
   • linkedConcepts — map of concept IDs to paths

4. Detect protocol: Check for protocol field in qino-config.json. When protocol: "qino" is present, set context.protocol = "qino". This activates protocol-aware workflow routing — graph-based structure instead of manifest-based.

   When protocol is detected:

   • Read agents/protocol-structure.md alongside agents/concept.md for inject workflows
   • Route concept work (home, capture, explore) to workflows/protocol/ versions
   • Route dev work (dev-work, dev-init) to workflows/protocol/ versions
   • Read agents/protocol-structure.md alongside agents/dev.md for spawn workflows
   • Reference references/protocol/protocol-spec.md for data model details

5. Detect ecosystem concepts: When the target concept lives in ecosystem/ (check manifest.json path field) or has type "ecosystem" in graph.json, recognize this as ecosystem work — distinct from app concept work.

   Pass this awareness to the agent:

   "This is ecosystem work — distinctions forming, not just ideas developing. Hold questions longer."

6. If no qino-config.json exists:

   • Route to orientation workflow (first-time arrival)
   • See workflows/orientation.md

Momentum Detection (Second Step)

Before executing a workflow (inject or spawn), assess whether the conversation already carries momentum.

Momentum exists when the user has:

• Shared specific ideas, direction, or vision in recent messages
• Articulated what feels alive or important to them
• Described concrete details (not just "I want to work on X")
• Built up context through back-and-forth dialogue

When momentum exists:

1. Summarize what's already surfaced:

   • The specific direction or vision they expressed
   • Key details or qualities they mentioned
   • What seems to have energy for them

2. Pass this to the agent as "already surfaced" context (see example below)

3. Tell the agent to skip exploratory questioning and go directly to working with what's been expressed

Example with momentum (inject mode — explore workflow):

User has been discussing their vision for a tools page - an interactive terminal
playground with guided steps, split layout, demonstrating fluidity between
concept/research/implementation work.

Claude: [Reads workflows/explore.md and agents/concept.md persona]
        [Recognizes momentum — user has already surfaced what's alive]
        [Skips the alive-thread question, goes directly to working]

"The terminal playground idea — guidance alongside experience, process becoming
artifact. Let me see how this lands in the concept."

[Reads concept, proposes integration]

Example with momentum (spawn mode — import workflow):

User has been discussing specific notes they want to bring in, with context
about which concept they connect to.

Claude: [Uses Task tool]
  subagent_type: "qino:concept"
  prompt: "Read and follow the workflow at plugins/qino/skills/qino/workflows/import.md

           MOMENTUM: User has already indicated:
           - Source file: /path/to/notes.md
           - Target concept: qinolabs-homepage
           - Connection: these notes relate to the tools page vision

           Skip exploratory questions. Go directly to reading and proposing integration."

Example with decision context (inject mode — test workflow):

User is deciding between embedding approaches for the qino-journey concept.
The conversation contains specific options being evaluated.

Claude: [Reads workflows/test.md and agents/concept.md persona]
        [Recognizes decision context — user has specific options to evaluate]

"You're weighing six approaches to embedding. Let me find a principle in
qino-journey that can test these..."

[Reads concept, finds relevant ecology principle, applies it to each option]

When NO momentum exists:

Let the workflow's natural dialogue unfold:

User: "explore qinolabs-homepage"

Claude: [Reads workflows/explore.md and agents/concept.md persona]
        [No momentum — follows workflow naturally]

"What part of qinolabs-homepage still feels alive when you think about it?"

The alive-thread question is valuable when arriving cold. Skip it when the user has already warmed up.

Routing

Match user intent to workflow. Spawn the specified agent to execute the workflow.

Quick Route (Agent Selection)

CRITICAL: Select agent FIRST based on user language, THEN find the workflow.

Implementation signals (→ qino:dev):

• Any app name mentioned with action intent: "qino-world", "qino-journey", "qino-frame"
• Building/coding language: "add feature", "fix bug", "implement", "create component"
• Progress language: "what's next", "continue", "move forward", "next iteration"
• Planning language: "plan", "scope", "break down", "what needs to be done"

Navigator signals (→ direct, graph tools):

• Activation language: "use the active navigator", "activate navigator for [territory]", "navigate [territory]"
• Mapping language: "map this concept", "create a navigator for [territory]", "show me the terrain"
• Update language: "update the navigator", "log this session", "record what we found"
• All navigator operations use qino-lab MCP tools — navigators are graph nodes

Concept signals (→ qino:concept):

• Exploration language: "explore", "deepen", "what is", "understand"
• Arrival language: "where am I", "what's here", "show me"
• Capture language: "hold this", "note", "capture"
• Testing language: "test through ecology", "notice", "inform the decision"

Research signals (→ qino:research):

• Investigation language: "research", "investigate", "study", "inquiry"
• Question framing: "how does X work", "what are the approaches to"

Lab mode signals (→ direct, no agent):

• Activation language: "use the lab", "lab mode", "work through the lab"
• Protocol context: "work through qino-lab", "use qino-lab for this"
• Requires: protocol workspace with qino-lab-mcp available
• Priority rule: "lab" as prefix takes priority over other routing. "lab create X" = lab mode, then action.

Bug signals (→ direct, graph tools):

• Filing language: "file a bug", "log this bug", "create a bug ticket", "bug ticket for [app]"
• Explicit command: "/qino bug"
• Discovery language: "this is a bug", "bug in [app]", "found a bug"
• Requires: implementation workspace with graph.json
• Bug operations use qino-lab MCP tools — bugs are finding nodes in the implementation graph

Concept Work → qino:concept

Protocol routing: When context.protocol === "qino", home/capture/explore route to protocol versions. The agent reads agents/protocol-structure.md alongside agents/concept.md.

Arc Work → qino:concept

Arc behavior notes:

• Arc opening, linking, and closing are explicit commands
• Arc detection on arrival is automatic but non-intrusive (see agent inject sections)
• Retrospective capture (arc.md) works standalone or as the final phase of arc-close

Research Work → qino:research

Navigator Work → direct (graph tools)

Navigator behavior notes:

• Navigators are graph nodes with type: "navigator" in the root graph — they appear in qino-lab
• Activation loads terrain, reading order, and open questions via read_node
• Creation uses create_node + content files; deep reading can be delegated to an Explore agent
• Session log updates edit content/terrain.md and write journal entries
• Navigator operations implicitly use graph tools (qino-lab MCP) — no need to say "lab" first

Bug Work → direct (graph tools)

Bug behavior notes:

• Bugs are finding type nodes in the implementation graph with sparked-by edges to the affected app
• The workflow gathers context from the conversation (if debugging was happening) and fills gaps through dialogue
• Resolution updates the node status to composted and captures root cause + fix + generalizable pattern
• Bug nodes are visible in qino-lab and connected to their app's implementation node
• Works from any workspace that can resolve the implementation graph path

Implementation Work → qino:dev

The agent reads agents/protocol-structure.md alongside agents/dev.md.

Orientation (no agent needed — lightweight)

Lab Mode (no agent needed — direct mode)

Lab mode behavior notes:

• Requires protocol-compliant workspace (protocol: "qino" in qino-config.json)
• Uses qino-lab-mcp tools for real-time UI communication
• Signal types: reading, connection, tension, proposal
• The graph becomes the medium of dialogue — annotations surface in the UI

Lab mode persistence (compaction resilience):

• Lab mode is a long-running behavioral overlay that persists across the session
• If the conversation has been compacted and lab mode was previously active, re-read workflows/lab.md to restore full behavioral instructions
• The graph carries continuity — annotations, nodes, and journal entries persist across compaction boundaries
• Detection: if the conversation summary mentions "lab mode active" or recent MCP tool calls include qino-lab tools (write_annotation, read_graph, etc.), treat "use the lab" as a re-injection refresh
• Operational details (deeplinks, views, node creation) live in references/lab/lab-operations.md — read on demand, not at activation

Implementation Context

When context.type === "implementation", additional routing applies:

Key behavior: In implementation repos, the concept agent gains bidirectional visibility with iterations. When exploring a linked concept, it:

• Surfaces current iteration status ("iteration 05 — figures-center-stage")
• Offers translation prompts after concept changes
• Shows iteration context when capturing discoveries from building

Multi-app scoping: Users can work across multiple apps conversationally:

• "work on world and journey" → dev agent sees both apps
• "the encounter panel in world needs to talk to journey's substrate" → dev agent holds both contexts

Check execution mode. Dialogue workflows (explore, capture) inject into main conversation. Synthesis workflows (dev-work) spawn subagents.

Context Object

Pass to workflows:

interface Context {
  type: "concepts" | "research" | "implementation" | "tool";
  root: string;                              // Workspace root path
  protocol?: "qino";                         // Protocol mode — graph-based structure
  conceptsRepo?: string;                     // Path to concepts repo
  researchRepo?: string;                     // Path to research repo
  linkedConcept?: string;                    // Primary linked concept ID
  linkedConcepts?: Record<string, string>;   // Map of concept IDs to paths
}

Non-Linear Ecology

This is not a lifecycle. Users move fluidly between modalities:

• Capture during explore
• Explore from research
• Research informing implementation
• Implementation sparking new concepts
• Arcs emerging across any activity

The skill routes based on current intent. Each workflow knows how to handle cross-context flow.

Agent and Execution Reference

Workflows specify both an agent persona and an execution mode.

Execution Mode by Workflow

Subagent Types (for spawn mode only)

Agent definitions live in agents/ directory. Each agent file has:

• <!-- INJECT-START --> ... <!-- INJECT-END --> — persona/principles for inject mode
• Task-specific instructions — for spawn mode

Error States

Cross-repo resolution failure:

"Can't find concepts-repo at [path]." Check your .claude/qino-config.json

Ambiguous intent (could be concept, dev, or research):

Use AskUserQuestion to disambiguate:

Route based on selection.

Unknown intent (no signal at all):

Route to workflows/home.md — arrival handles orientation naturally.