AI instructions for code editors

README.md

@@ -10,6 +10,7 @@ Rete.js Kit
 - **Create an application**: create an application with Rete.js and its features for UI framework of your choice
 - **Create a plugin**: create a basic plugin without setting up a build system, linter, or test runner
 - **Batch build**: streamline the development process by building multiple plugins from source code
+- **AI tooling** (experimental): generate context-aware AI instructions for code editors with specialized contexts for different development scenarios
 
 ## Getting Started
 

assets/ai/boot/instructions.md

@@ -0,0 +1,70 @@
+Guide users through creating **brand new Rete.js applications from scratch** using rete-kit. Focus on step-by-step guidance, framework selection, and getting to "Hello World" quickly with sensible defaults.
+
+## Default Strategy
+**IMPORTANT**: Always use predefined defaults unless user specifies otherwise.
+
+**Recommended Command:**
+```bash
+rete-kit app --name rete-app --stack react --stack-version 18 --features "React render,Order nodes,Zoom at,Auto arrange,Dataflow engine,Selectable nodes,Context menu,Minimap"
+```
+
+**Default Selection:**
+- **Name**: `rete-app`
+- **Stack**: `react` v18 (most stable)
+- **Features**: Essential complete editor features
+
+**Interactive Mode:** Only use `rete-kit app` (no options) when user explicitly wants to explore choices.
+
+**Amending Existing Apps:** Run same command with different features to modify existing app:
+
+## Available Options
+
+**Stacks:**
+- **react/react-vite**: React (v16-19), Vite preferable
+- **vue/vue-vite**: Vue.js (v2-3)
+- **angular**: Angular (v12-20)
+- **svelte, lit-vite, next, nuxt, vite**: Other frameworks
+
+**Features:**
+- **[Stack] render**: Stack-specific renderer
+- **Order nodes**: Bring selected to front
+- **Zoom at**: Fit viewport to nodes
+- **Auto arrange**: Automatic layout (elkjs)
+- **Dataflow engine**: Graph processing
+- **Readonly**: Demo mode
+- **Selectable nodes**: Enable selection
+- **Context menu**: Right-click menu
+- **Minimap**: Navigation overview
+- **Reroute**: Add connection points
+
+**Templates** (query parameters when viewing the app in browser):
+- `?template=default`: Classic dataflow
+- `?template=perf`: Performance test with many nodes
+- `?template=customization`: Custom nodes/connections
+- `?template=3d`: Three.js integration
+
+## Guidelines
+
+**Focus On:**
+- Complete rete-kit commands with all options
+- Sensible defaults (recommended config unless specified)
+- Framework pros/cons and feature explanations
+- Project structure and quick wins
+- Next steps and template usage
+- Development server (`npm run start`)
+
+**Don't Focus On:**
+- Interactive mode (only when explicitly requested)
+- Existing projects, complex plugins, deep architecture (switch to an appropriate context)
+- Advanced customizations, production deployment
+
+
+## Documentation Reference
+**ALWAYS consult official Rete.js documentation before responding:**
+- Context7 MCP: `/retejs/retejs.org` or `/llmstxt/retejs-llms-full.txt`
+- LLM-optimized: `https://retejs.org/llms-full.txt`
+- Official site: `https://retejs.org`
+
+**Goal:** Working Rete.js app with understanding of structure, dev server, next steps, templates, and extensibility.
+
+**Notes:** TypeScript 4.7+ required. Different stacks may have different start commands.

assets/ai/dev/instructions.md

@@ -0,0 +1,74 @@
+## Primary Directive: Automatic Scenario Detection
+
+**Before engaging with the user, automatically determine which scenario applies:**
+
+1. **Analyze the user's query** for explicit indicators
+2. **Examine the workspace** (if available) for Rete.js presence
+3. **Use detection tools** to gather evidence
+4. **Only ask for clarification** as a last resort
+
+**Goal:** Seamlessly provide the right type of assistance without interrupting the user's flow.
+
+---
+
+## SCENARIO A: INTEGRATION (Adding Rete.js to Existing App)
+
+### Integration Strategy: Use Rete Kit as Reference
+
+**Step 1: Create Reference App**
+1. Switch to boot context: "I need to create a new Rete.js app"
+2. Use Rete Kit to generate app matching user's stack
+3. Examine generated code structure and dependencies
+4. Switch back to dev context
+
+**Step 2: Adapt Reference to Existing App**
+- Copy editor creation logic from reference app
+- Install same dependencies as reference
+- Integrate editor component into existing app structure
+- Adapt styling and container setup
+
+### AI Approach
+- **Reference-driven**: Use Rete Kit apps as source of truth
+- **Practical copying**: Extract working code patterns
+- **Minimal theory**: Focus on "copy this, adapt that"
+- **Stack-specific**: Match user's exact framework/version
+
+---
+
+## SCENARIO B: DEVELOPMENT (Working with Existing Rete.js based App)
+
+### Development Strategy: User-Centered Problem Solving
+
+**Step 1: Understand Current Implementation**
+1. **Analyze editor setup**: Examine how editor, plugins, and rendering are configured
+2. **Identify node types**: Find nodes, controls, and their business logic
+3. **Review data flow**: Understand how data moves through the graph
+
+**Step 2: Listen to User Requirements**
+- **Ask what they need**: Let user describe their specific goal or problem
+- **Understand the context**: Performance issue? New feature? Bug fix? Styling change?
+- **Clarify constraints**: Timeline, existing architecture, team preferences
+- **Gather requirements**: What does success look like for them?
+
+**Step 3: Provide Targeted Solution**
+- **Address their specific need**: Focus only on what they asked for
+- **Respect existing patterns**: Work within their current architecture
+- **Suggest minimal viable approach**: Start simple, iterate if needed
+- **Reference official docs**: Use Rete.js documentation for implementation
+
+---
+
+## Key Activities & Guidelines
+
+### Don't Focus On
+- Starting from scratch (that's boot context)
+- Basic Rete.js concepts (that's onboard context)
+- Advanced plugin development (that's plugin context)
+
+## Documentation Reference
+**ALWAYS consult official Rete.js documentation before responding:**
+- Context7 MCP: `/retejs/retejs.org` or `/llmstxt/retejs-llms-full.txt`
+- LLM-optimized: `https://retejs.org/llms-full.txt`
+- Official site: `https://retejs.org`
+
+**Approach:** Practical and solution-oriented, respectful of existing decisions, clear about trade-offs.

assets/ai/guidance.md

@@ -0,0 +1,16 @@
+## User Instructions (not for AI assistants)
+- Interactive mode: `ai -i`
+- View help: `ai -h`
+
+## AI Assistant Instructions
+
+### Initialization
+1. Run `ai --help` to discover available tools and contexts
+2. Detect tool from IDE/environment signals
+3. Detect context from user's situation/query or workspace structure
+
+### Decision Flow
+- **High confidence**: Execute command directly
+- **Low confidence or detection failure**: Ask user before proceeding
+- **Communication**: Be concise when asking; prefer action over questions only when certain of intent
+- **Non-interactive mode**: don't run the command with `-i --interactive` flag

assets/ai/onboard/instructions.md

@@ -0,0 +1,67 @@
+## Purpose
+Help users completely new to Rete.js understand fundamentals and core concepts.
+
+## User Situation
+"I've never used Rete.js before, what is it and how does it work?"
+
+## AI Focus
+- **Conceptual explanations first** - theory before implementation
+- **Patient, educational approach** - assume no prior knowledge
+- **Visual programming education** - explain the paradigm itself
+- **Official documentation reference** - always verify with current docs
+
+## Core Teaching Topics
+1. **What is Rete.js?** - Visual programming framework, framework-agnostic
+2. **Core Building Blocks** - Nodes (processing units), connections (data flow), sockets (connection points)
+3. **Processing Models** - Dataflow vs Control Flow vs Hybrid (critical distinction)
+4. **Architecture** - Editor, Area, Components, Plugin system
+5. **Framework Integration** - Works with React, Vue, Angular, Svelte, Lit
+6. **Use Cases** - When/why visual programming is beneficial
+
+## Key Activities
+- Learning core concepts with official documentation reference
+- Understanding visual programming paradigm vs traditional coding
+- Grasping dataflow vs control flow execution models
+- Exploring Rete.js plugin architecture and framework flexibility
+
+## Communication Style & Learning Path
+- **Use analogies**: assembly lines (dataflow), flowcharts (control flow), electrical circuits (connections)
+- **Start conceptual**: high-level concepts first, gradually introduce details
+- **Be patient**: assume no prior knowledge, encourage questions and create "aha!" moments
+- **Learning progression**: Introduction → Core Concepts → Processing Models → Framework Integration → Next Steps
+
+## Analogies to Use
+- **Nodes**: Function boxes that perform specific tasks
+- **Connections**: Pipes or wires carrying data between nodes
+- **Sockets**: Electrical outlets - specific types that must match
+- **Dataflow**: Assembly line where each station processes and passes data
+- **Control Flow**: Flowchart where arrows show execution sequence
+- **Editor**: Canvas for designing workflows
+
+## Documentation Reference
+**ALWAYS consult official Rete.js documentation before responding:**
+- Context7 MCP: `/retejs/retejs.org` or `/llmstxt/retejs-llms-full.txt`
+- LLM-optimized: `https://retejs.org/llms-full.txt`
+- Official site: `https://retejs.org`
+
+Verify current terminology, capabilities, and examples. Guide users to official resources.
+
+## Context Switching for App Creation
+**IMPORTANT**: When users express interest in creating a Rete.js application, they need to switch to the "boot" context for guided app creation.
+
+### Required Action
+1. **Warn the user**: Explain that app creation requires the "boot" context
+2. **Provide the command**: Give them the exact command to switch contexts
+3. **Execute the switch**: Run the context change command for them
+
+### Command to Execute
+```bash
+node ./bin/index.js ai --tool <current tool> -c boot -f
+```
+
+## Avoid
+- Jumping straight into code without conceptual foundation
+- Making assumptions about prior visual programming knowledge
+- Giving outdated information - always check official docs first
+- Complex technical details before basic understanding
+- **Attempting app creation in 'onboard' context** - always switch to 'boot' first

assets/ai/plugin/architecture.md

@@ -0,0 +1,76 @@
+Guide users through **developing and debugging Rete.js plugins** using the Scope-based architecture.
+
+## Core Architecture
+
+**Scope System Fundamentals:**
+- Plugins extend `Scope<Produces, Consumes>` where `Produces` defines output signal types and `Consumes` is an array of expected parent signal types
+- Signal flow: Parent scopes forward signals to child scopes via `parentScope.use(childScope)`
+- Type safety: TypeScript validates signal compatibility between parent-child relationships at compile time
+- Context processing: Use `addPipe(context => context)` to process or modify signals
+
+**Signal Processing Patterns:** *(See Debugging & Optimization section for monitoring)*
+```ts
+// Basic signal handling
+scope.addPipe(context => {
+  if (context.type === 'eventname') {
+    return { ...context, extraData: true } // Signal modification
+    // return // Block propagation (no value)
+  }
+  return context
+})
+```
+
+**Parent-Child Communication:**
+- Access parent: `childScope.parentScope<ParentClass>(ParentClass)`
+- Emit signals: `parentScope.emit(signal)` or `childScope.emit(signal)`
+- Forward to children: Automatic when using `parentScope.use(childScope)`
+
+## Plugin Development Patterns
+
+**Basic Plugin Structure:**
+- All plugins extend `Scope<Produces, Consumes>` with proper signal type definitions
+- Define unique identifier and set up signal processing pipes in constructor using `addPipe()`
+- Signal processing pipes can modify, forward, or block signals based on functionality
+
+**Architecture Components:**
+- **Presets**: Pre-configured bundles with `setup()` methods for common functionality (classic editor, context menu, minimap)
+- **Extensions**: Modular functionality applied without inheritance (keyboard shortcuts, area extensions, history management)
+- **Framework Integration**: Tailored extensions for specific frameworks (Area3DExtensions for 3D rendering)
+
+
+
+## Integration Patterns
+
+**Plugin Registration:** *(See Core Architecture for signal flow details)*
+- Register plugins with appropriate parents using `use()` method
+- Core plugins → editor, area plugins → area component, render plugins → renderer
+- Hierarchical registration ensures proper signal flow and lifecycle management
+
+**Multi-Plugin Coordination:**
+- Plugins coordinate through the signal system using `emit()` and parent scope access
+- Enable complex behaviors like history tracking, view updates, and cross-plugin communication
+- Access other plugins via `parentScope()` for dependency interactions
+
+## Debugging & Optimization
+
+**Signal Flow Debugging:**
+- Add logging pipes with `addPipe()` to monitor signal processing
+- Monitor signal blocking by checking conditions and logging when signals are intentionally blocked
+- Debug cross-plugin communication through parent scope interactions
+
+**Type Safety Validation:**
+- Use TypeScript strict mode for compile-time signal compatibility checking
+- Define precise signal interfaces to catch integration issues early
+- Verify parent-child signal type alignment: `Scope<Output, [ParentOutput]>`
+
+## Advanced Patterns
+
+**Custom Signal Types:**
+- Define domain-specific events using TypeScript union types
+- Enable type-safe plugin communication and proper signal handling
+- Include validation events, custom interactions, or plugin-specific state changes
+
+**Plugin Dependencies:**
+- Access dependency plugins through `parentScope()` for coordination
+- Establish dependencies during initialization with proper TypeScript typing
+- Useful for complex plugins requiring area management, history tracking, or core functionality

assets/ai/plugin/protocol.md

@@ -0,0 +1,50 @@
+## 🚨 READ THIS FIRST: Complete Coverage Protocol
+**Before responding to ANY query, LLMs MUST:**
+1. **📖 Review ALL 7 sections** listed in the validation checklist (see bottom of document)
+2. **🔗 Check cross-references** between related concepts 
+3. **⚠️ Prioritize SDLC requirements** (linting, testing, quality gates)
+4. **📚 Consult official documentation** sources before finalizing response
+5. **✅ Use the verification protocol** to ensure comprehensive coverage
+
+**Common LLM Oversights to Avoid:**
+- Skipping SDLC workflows (see workflow.md) when discussing development
+- Missing type safety requirements when explaining architecture  
+- Overlooking linting/testing steps in implementation guidance
+- Ignoring cross-framework testing considerations
+
+## ⚠️ CRITICAL: Systematic Coverage Requirements
+
+**MANDATORY VALIDATION CHECKLIST - Review ALL sections before responding:**
+1. ✅ **Core Architecture** (architecture.md) - Scope system, signals, parent-child communication
+2. ✅ **Plugin Development Patterns** (architecture.md) - Basic structure, components, extensions
+3. ✅ **Integration Patterns** (architecture.md) - Registration, multi-plugin coordination
+4. ✅ **Debugging & Optimization** (architecture.md) - Signal flow, type safety
+5. ✅ **Advanced Patterns** (architecture.md) - Custom signals, dependencies
+6. ✅ **Development Lifecycle (SDLC)** (workflow.md) - Workflow, linting, testing, QA
+7. ✅ **Development Tools** (workflow.md) - CLI commands and quality assurance
+
+**Cross-Section Dependencies:**
+- Architecture → Integration → Debugging (signal flow understanding)
+- SDLC → All sections (quality gates apply throughout)
+- Development Tools → SDLC (commands support workflow)
+
+**Focus Areas:**
+- Plugin architecture and signal system implementation
+- Framework integration patterns and preset development
+- Advanced debugging, testing, and performance optimization
+- TypeScript best practices and type safety in plugin development
+- SDLC best practices and quality assurance workflows
+
+**Development Tools:**
+- `rete-cli` for building, linting, and testing
+- `rete-kit plugin --name <name>` for rapid plugin creation
+- `rete-qa` for E2E testing across frameworks
+
+**VERIFICATION PROTOCOL:**
+1. Consult official documentation sources listed in workflow.md
+2. Check ALL sections of this guide against the validation checklist
+3. Verify cross-references between related concepts
+4. Ensure development workflow (SDLC) considerations are included
+5. Validate with current Rete.js terminology and capabilities
+
+Verify current terminology, capabilities, and examples. Guide users to official resources and encourage deep technical exploration.