@poolzin/plcode 2.1.1 → 3.0.0

package/.plcode/context/system-builder-templates/orchestrator-template.md

@@ -0,0 +1,261 @@
+# Orchestrator Agent Template
+
+This template is used to generate main orchestrator agents for context-aware AI systems.
+
+## Template Structure
+
+```markdown
+---
+description: "{domain} orchestrator for {primary_purpose}"
+mode: primary
+temperature: 0.2
+tools:
+  read: true
+  write: true
+  edit: true
+  bash: { based_on_requirements }
+  task: true
+  glob: true
+  grep: true
+---
+
+# {Domain} Orchestrator
+
+<context>
+  <system_context>
+    {Description of the overall system this orchestrator manages}
+  </system_context>
+  <domain_context>
+    {Domain/industry specifics and user personas}
+  </domain_context>
+  <task_context>
+    {What types of tasks this orchestrator handles}
+  </task_context>
+  <execution_context>
+    {How this orchestrator coordinates work and manages workflows}
+  </execution_context>
+</context>
+
+<role>
+  {Domain} Orchestrator specializing in {key_capabilities} with expertise
+  in {specialized_areas}
+</role>
+
+<task>
+  Transform user requests into completed {outcomes} by intelligently routing work
+  to specialized agents and managing workflow execution
+</task>
+
+<workflow_execution>
+<stage id="1" name="AnalyzeRequest">
+<action>Assess request complexity and requirements</action>
+<prerequisites>User request received and parseable</prerequisites>
+<process> 1. Parse user request for intent and parameters 2. Identify use case category 3. Assess complexity level (simple/moderate/complex) 4. Determine required capabilities 5. Select appropriate workflow
+</process>
+<decision>
+<if test="simple_request">Handle directly or route to single specialist</if>
+<if test="moderate_request">Execute standard workflow</if>
+<if test="complex_request">Coordinate multi-agent workflow</if>
+</decision>
+<checkpoint>Request analyzed and workflow selected</checkpoint>
+</stage>
+
+  <stage id="2" name="AllocateContext">
+    <action>Determine what context is needed for execution</action>
+    <prerequisites>Workflow selected</prerequisites>
+    <process>
+      1. Identify required domain knowledge
+      2. Determine process documentation needs
+      3. Select relevant standards and templates
+      4. Choose context level (1/2/3)
+      5. Load only necessary context files
+    </process>
+    <context_allocation>
+      <level_1>
+        <when>Simple, well-defined operation</when>
+        <context>Task description only</context>
+      </level_1>
+      <level_2>
+        <when>Requires domain knowledge or validation</when>
+        <context>Filtered context files relevant to task</context>
+      </level_2>
+      <level_3>
+        <when>Complex coordination requiring full state</when>
+        <context>Complete system state and history</context>
+      </level_3>
+    </context_allocation>
+    <checkpoint>Context allocated and loaded</checkpoint>
+  </stage>
+
+  <stage id="3" name="ExecuteWorkflow">
+    <action>Execute selected workflow or route to specialists</action>
+    <prerequisites>Context allocated</prerequisites>
+    <routing>
+      {for each subagent:
+      <route to="@{subagent_name}" when="{trigger_condition}">
+        <context_level>{Level X}</context_level>
+        <pass_data>{specific_data_elements}</pass_data>
+        <expected_return>{what_agent_returns}</expected_return>
+        <integration>{how_to_use_result}</integration>
+      </route>
+      }
+    </routing>
+    <checkpoint>Workflow executed or routed successfully</checkpoint>
+  </stage>
+
+  <stage id="4" name="ValidateResults">
+    <action>Verify quality of outputs</action>
+    <prerequisites>Workflow execution complete</prerequisites>
+    <validation_criteria>
+      <completeness>All required outputs present</completeness>
+      <correctness>Outputs meet specifications</correctness>
+      <quality>Outputs meet quality standards</quality>
+    </validation_criteria>
+    <decision>
+      <if test="validation_passed">Proceed to finalize</if>
+      <if test="validation_failed">Identify issues and retry or escalate</if>
+    </decision>
+    <checkpoint>Results validated</checkpoint>
+  </stage>
+
+  <stage id="5" name="FinalizeAndDeliver">
+    <action>Package and deliver results to user</action>
+    <prerequisites>Validation passed</prerequisites>
+    <process>
+      1. Format results for user consumption
+      2. Save outputs to appropriate locations
+      3. Log execution metadata
+      4. Provide clear response with next steps
+    </process>
+    <checkpoint>Results delivered to user</checkpoint>
+  </stage>
+</workflow_execution>
+
+<routing_intelligence>
+<analyze_request>
+<step_1>Parse request for intent and parameters</step_1>
+<step_2>Identify use case category</step_2>
+<step_3>Assess complexity (simple/moderate/complex)</step_3>
+<step_4>Determine required capabilities</step_4>
+</analyze_request>
+
+<allocate_context>
+<level_1_triggers> - Single domain operation - Clear requirements - Standard workflow - No dependencies
+</level_1_triggers>
+
+    <level_2_triggers>
+      - Multi-step process
+      - Domain knowledge needed
+      - Quality validation required
+      - Integration points
+    </level_2_triggers>
+
+    <level_3_triggers>
+      - Complex multi-agent coordination
+      - Requires historical context
+      - High-stakes decisions
+      - Extensive state management
+    </level_3_triggers>
+
+</allocate_context>
+
+<execute_routing>
+{Subagent routing patterns based on domain}
+</execute_routing>
+</routing_intelligence>
+
+<context_engineering>
+<determine_context_level>
+function(task_type, complexity, subagent_target) {
+if (task_type === "simple" && no_dependencies) {
+return "Level 1"; // Complete isolation
+}
+if (task_type === "moderate" || requires_domain_knowledge) {
+return "Level 2"; // Filtered context
+}
+if (task_type === "complex" && multi_agent_coordination) {
+return "Level 3"; // Windowed context
+}
+return "Level 1"; // Default to isolation
+}
+</determine_context_level>
+
+<prepare_context>
+<level_1>
+Pass only task description and target output specification
+</level_1>
+<level_2>
+Pass task + relevant context files (domain knowledge, standards, templates)
+</level_2>
+<level_3>
+Pass task + full context + recent history + system state
+</level_3>
+</prepare_context>
+</context_engineering>
+
+<quality_standards>
+{Domain-specific quality criteria}
+</quality_standards>
+
+<validation>
+  <pre_flight>
+    - User request is clear and parseable
+    - Required context files are available
+    - Necessary subagents are accessible
+  </pre_flight>
+  
+  <post_flight>
+    - All outputs meet quality standards
+    - User receives clear, actionable results
+    - Execution metadata is logged
+  </post_flight>
+</validation>
+
+<performance_metrics>
+<efficiency> - 80% of tasks use Level 1 context (isolation) - 20% of tasks use Level 2 context (filtered) - Level 3 context (windowed) is rare
+</efficiency>
+
+  <quality>
+    - Routing accuracy: +20% with LLM-based decisions
+    - Consistency: +25% with XML structure
+    - Context efficiency: 80% reduction in overhead
+  </quality>
+</performance_metrics>
+
+<principles>
+  <intelligent_routing>
+    Route to specialists based on request analysis, not rigid rules
+  </intelligent_routing>
+  
+  <context_efficiency>
+    Use minimal context necessary for each task (prefer Level 1)
+  </context_efficiency>
+  
+  <validation_gates>
+    Validate at critical points to ensure quality
+  </validation_gates>
+  
+  <user_focused>
+    Deliver clear, actionable results with next steps
+  </user_focused>
+</principles>
+```
+
+## Customization Points
+
+1. **Domain Context**: Replace `{domain}`, `{primary_purpose}`, `{key_capabilities}`
+2. **Workflow Stages**: Customize stages based on domain workflows
+3. **Routing Logic**: Add domain-specific subagent routing patterns
+4. **Quality Standards**: Define domain-specific quality criteria
+5. **Context Files**: Reference actual context files from the domain
+
+## Validation Criteria
+
+Generated orchestrators must:
+
+- Follow optimal component ordering (context→role→task→instructions)
+- Include 5+ workflow stages with checkpoints
+- Implement routing_intelligence section
+- Define context_engineering functions
+- Include validation gates (pre_flight and post_flight)
+- Score 8+/10 on XML optimization criteria

package/.plcode/context/system-builder-templates/subagent-template.md

@@ -0,0 +1,213 @@
+# Subagent Template
+
+This template is used to generate specialized subagent files.
+
+## Template Structure
+
+````markdown
+---
+description: "{specific_task_description}"
+mode: subagent
+temperature: 0.1
+---
+
+# {Subagent Name}
+
+<context>
+  <specialist_domain>{area_of_expertise}</specialist_domain>
+  <task_scope>{specific_task_this_agent_completes}</task_scope>
+  <integration>{how_this_fits_in_larger_system}</integration>
+</context>
+
+<role>
+  {Specialist_Type} expert with deep knowledge of {specific_domain}
+</role>
+
+<task>
+  {Specific, measurable objective this agent accomplishes}
+</task>
+
+<inputs_required>
+<parameter name="{param1}" type="{type}">
+{Description of what this parameter is and acceptable values}
+</parameter>
+<parameter name="{param2}" type="{type}">
+{Description of what this parameter is and acceptable values}
+</parameter>
+{additional parameters as needed}
+</inputs_required>
+
+<inputs_forbidden>
+
+  <!-- Subagents should never receive these -->
+
+<forbidden>conversation_history</forbidden>
+<forbidden>full_system_state</forbidden>
+<forbidden>unstructured_context</forbidden>
+</inputs_forbidden>
+
+<process_flow>
+<step_1>
+<action>{First thing to do}</action>
+<process> 1. {Substep 1} 2. {Substep 2} 3. {Substep 3}
+</process>
+<validation>{How to verify this step succeeded}</validation>
+<output>{What this step produces}</output>
+</step_1>
+
+<step_2>
+<action>{Second thing to do}</action>
+<process> 1. {Substep 1} 2. {Substep 2}
+</process>
+<conditions>
+<if test="{condition_a}">{Do option A}</if>
+<else>{Do option B}</else>
+</conditions>
+<output>{What this step produces}</output>
+</step_2>
+
+<step_3>
+<action>{Final thing to do}</action>
+<process> 1. {Substep 1} 2. {Substep 2}
+</process>
+<output>{Final output to return}</output>
+</step_3>
+</process_flow>
+
+<constraints>
+  <must>{Always enforce requirement X}</must>
+  <must>{Always validate parameter Y}</must>
+  <must_not>{Never make assumptions about Z}</must_not>
+  <must_not>{Never proceed if critical data is missing}</must_not>
+</constraints>
+
+<output_specification>
+<format>
+`yaml
+    {Exact structure of output, preferably in YAML or JSON format}
+    status: "success" | "failure" | "partial"
+    result:
+      field1: value
+      field2: value
+    metadata:
+      execution_time: "X.Xs"
+      warnings: ["warning 1", "warning 2"]
+    `
+</format>
+
+  <example>
+    ```yaml
+    {Concrete example of successful output}
+    status: "success"
+    result:
+      example_field: "example value"
+      another_field: 42
+    metadata:
+      execution_time: "2.3s"
+      warnings: []
+    ```
+  </example>
+
+<error_handling>
+If something goes wrong, return:
+`yaml
+    status: "failure"
+    error:
+      code: "ERROR_CODE"
+      message: "Human-readable error message"
+      details: "Specific information about what went wrong"
+    `
+</error_handling>
+</output_specification>
+
+<validation_checks>
+<pre_execution> - Verify all required inputs are present - Validate input formats and types - Check that any referenced files exist - Ensure prerequisites are met
+</pre_execution>
+
+<post_execution> - Verify output meets specifications - Validate any files created or modified - Ensure no side effects occurred - Check quality standards are met
+</post_execution>
+</validation_checks>
+
+<{domain}\_principles>
+<principle_1>
+{Domain-specific principle or best practice}
+</principle_1>
+
+<principle_2>
+{Another domain-specific principle}
+</principle_2>
+
+<principle_3>
+{Another domain-specific principle}
+</principle_3>
+</{domain}\_principles>
+````
+
+## Customization Points
+
+1. **Specialist Domain**: Define the specific area of expertise
+2. **Task Scope**: Clearly articulate what this agent does
+3. **Input Parameters**: Define all required inputs with types and descriptions
+4. **Process Flow**: Break down the task into clear steps
+5. **Constraints**: Add domain-specific must/must_not rules
+6. **Output Format**: Define exact output structure (prefer YAML/JSON)
+7. **Validation**: Add domain-specific validation checks
+8. **Principles**: Include domain-specific best practices
+
+## Subagent Types
+
+### Research Agent
+
+- **Purpose**: Gather information from external sources
+- **Context Level**: Level 1 (isolation)
+- **Inputs**: Topic, scope, source constraints
+- **Outputs**: Research summary with citations
+
+### Validation Agent
+
+- **Purpose**: Validate outputs against standards
+- **Context Level**: Level 2 (standards + rules)
+- **Inputs**: Content to validate, validation criteria
+- **Outputs**: Validation score with prioritized feedback
+
+### Processing Agent
+
+- **Purpose**: Transform or process data
+- **Context Level**: Level 1 (task only)
+- **Inputs**: Data to process, transformation rules
+- **Outputs**: Processed data
+
+### Generation Agent
+
+- **Purpose**: Create content or artifacts
+- **Context Level**: Level 2 (templates + standards)
+- **Inputs**: Generation parameters, requirements
+- **Outputs**: Generated content
+
+### Integration Agent
+
+- **Purpose**: Handle external system integrations
+- **Context Level**: Level 1 (task only)
+- **Inputs**: Integration parameters, data to send
+- **Outputs**: Integration result
+
+## Validation Criteria
+
+Generated subagents must:
+
+- Define clear, explicit input parameters
+- Include step-by-step process flow
+- Specify exact output format (preferably YAML/JSON)
+- Include pre and post execution validation
+- Have clear constraints (must/must_not)
+- Be stateless (no conversation history)
+- Score 8+/10 on XML optimization criteria
+
+## Best Practices
+
+1. **Single Responsibility**: Each subagent should do ONE thing extremely well
+2. **Stateless**: Don't maintain state or assume context from previous interactions
+3. **Complete Instructions**: Every call must include ALL information needed
+4. **Explicit Output**: Define exact output format with examples
+5. **Validation**: Validate inputs before processing and outputs before returning
+6. **Error Handling**: Handle errors gracefully with clear messages

package/.plcode/context/ui/navigation.md

@@ -0,0 +1,83 @@
+# UI Context
+
+**Purpose**: User interface design patterns, standards, and best practices across all platforms
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Overview
+
+This category contains UI/UX patterns, design systems, and interface standards for building user-facing applications across different platforms.
+
+---
+
+## Directory Structure
+
+### 📁 Subcategories
+
+| Subcategory   | Description                                            | Path                                             |
+| ------------- | ------------------------------------------------------ | ------------------------------------------------ |
+| **web/**      | Web UI patterns, animations, styling, React components | [web/navigation.md](web/navigation.md)           |
+| **terminal/** | Terminal UI (TUI) patterns for CLI applications        | [terminal/navigation.md](terminal/navigation.md) |
+
+### Future Subcategories
+
+- **mobile/** - React Native, Flutter patterns (planned)
+- **desktop/** - Electron, Tauri patterns (planned)
+
+---
+
+## Quick Navigation
+
+### Web UI
+
+- Animation patterns and micro-interactions
+- CSS styling standards and design systems
+- React component patterns
+- Design assets and resources
+- Scroll-linked animations (scrollytelling)
+
+### Terminal UI
+
+- CLI/TUI patterns (planned)
+- Ink, Blessed component patterns (planned)
+- Terminal animations and progress indicators (planned)
+
+---
+
+## Usage
+
+**Web development**: Navigate to `web/` for browser-based UI patterns
+
+**CLI/TUI development**: Navigate to `terminal/` for terminal interface patterns
+
+**Cross-platform**: Consider patterns from multiple subcategories
+
+---
+
+## Scope
+
+This category covers:
+
+- ✅ Visual design patterns
+- ✅ Animation and transitions
+- ✅ Component architecture
+- ✅ Styling standards
+- ✅ Design systems
+- ✅ Accessibility patterns
+- ⏳ Platform-specific patterns (mobile, desktop)
+
+---
+
+## Related Categories
+
+- `development/` - General development patterns (backend, APIs, clean code)
+- `product/` - Product design and UX strategy
+- `content/` - Content design and copywriting
+
+---
+
+## Used By
+
+**Agents**: frontend-specialist, design-specialist, ui-developer, animation-expert

package/.plcode/context/ui/terminal/navigation.md

@@ -0,0 +1,99 @@
+# Terminal UI Context
+
+**Purpose**: Terminal UI (TUI) patterns, CLI animations, and command-line interface design
+
+**Last Updated**: 2026-01-07
+
+---
+
+## Overview
+
+This subcategory will contain patterns and best practices for building terminal user interfaces using libraries like Ink, Blessed, and native terminal capabilities.
+
+---
+
+## Planned Content
+
+### Core Files (Future)
+
+| File                  | Description                                  | Priority |
+| --------------------- | -------------------------------------------- | -------- |
+| `tui-patterns.md`     | Terminal UI component patterns and layouts   | high     |
+| `cli-animations.md`   | Terminal animations, spinners, progress bars | high     |
+| `ink-components.md`   | React Ink component patterns                 | medium   |
+| `blessed-patterns.md` | Blessed.js patterns and widgets              | medium   |
+| `terminal-styling.md` | ANSI colors, chalk, terminal theming         | medium   |
+
+### Planned Topics
+
+- **Layout patterns**: Boxes, borders, flexbox-like layouts
+- **Interactive components**: Menus, forms, selects, inputs
+- **Progress indicators**: Spinners, progress bars, loading states
+- **Terminal animations**: Frame-based animations, smooth transitions
+- **Color and styling**: ANSI escape codes, chalk, gradient text
+- **Keyboard handling**: Key bindings, shortcuts, navigation
+- **Terminal detection**: Capability detection, fallbacks
+
+---
+
+## Example Libraries
+
+### React-based TUI
+
+- **Ink** - React for CLIs
+- **Pastel** - React-like TUI framework
+
+### Traditional TUI
+
+- **Blessed** - High-level terminal interface library
+- **Blessed-contrib** - Widgets for blessed (charts, gauges)
+- **Terminal-kit** - Comprehensive terminal manipulation
+
+### Styling
+
+- **Chalk** - Terminal string styling
+- **Gradient-string** - Gradient colors in terminal
+- **Boxen** - Create boxes in terminal
+
+### Progress/Animation
+
+- **Ora** - Elegant terminal spinners
+- **CLI-progress** - Progress bars
+- **Listr** - Terminal task lists
+
+---
+
+## Usage
+
+**When this subcategory is populated**, use it for:
+
+- Building CLI tools with rich interfaces
+- Creating terminal-based dashboards
+- Implementing interactive command-line applications
+- Adding animations and progress indicators to CLI tools
+
+---
+
+## Related Categories
+
+- `ui/web/` - Web UI patterns
+- `development/` - General development patterns
+
+---
+
+## Status
+
+⏳ **Placeholder** - This subcategory is planned but not yet populated.
+
+To contribute content here, follow the MVI principles:
+
+1. Extract core concepts (1-3 sentences)
+2. List key points (3-5 bullets)
+3. Provide minimal example
+4. Link to full documentation
+
+---
+
+## Used By
+
+**Agents**: cli-developer, terminal-specialist, devops-specialist (future)