@moon791017/neo-skills 1.1.21 → 1.1.23

package/skills/neo-agentic-design/references/base-workflows.md

@@ -1,219 +0,0 @@
-# Base Patterns & Workflows
-
-This document provides conceptual designs for basic agentic orchestration patterns, covering prompt chaining, routing, parallelization, reflection, tool use, planning, and multi-agent collaboration.
-
----
-
-## Chapter 1: Prompt Chaining
-
-### 1. Definition
-Decomposes a complex task into multiple **sequentially dependent subtasks**. The structured output of the previous step serves as the input for the next step. Each step focuses on a single, clear objective.
-
-### 2. Problems Addressed
-* Context dilution: Prevents the LLM from losing focus when processing large, complex tasks.
-* Instruction drift: Avoids failures in a single prompt that contains too many rules.
-
-### 3. Workflow
-```mermaid
-graph LR
-    Input[Raw Input] --> Step1[LLM Step A]
-    Step1 -->|Structured Output A| Step2[LLM Step B]
-    Step2 -->|Structured Output B| Step3[LLM Step C]
-    Step3 --> Output[Final Answer]
-```
-
-### 4. Trade-offs
-* **Pros**: High predictability; easy to optimize prompts and perform unit testing for individual steps.
-* **Cons**: High total latency due to sequential execution; errors in earlier steps propagate downstream (Error Cascade).
-
-### 5. Use Cases
-* Multi-step article generation (Outline -> Draft -> Polish -> Format).
-* Data extraction and compliance analysis.
-
----
-
-## Chapter 2: Routing
-
-### 1. Definition
-Dynamically redirects tasks to the most suitable execution path, specialized tool, or sub-agent based on input characteristics. Routing decisions are made by rule engines, semantic similarity, or LLM classifiers.
-
-### 2. Problems Addressed
-* Resource waste: Avoids using expensive, slow high-tier models for simple queries.
-* Tool clutter: Avoids crowding too many unrelated tools into a single agent's context window.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Input[User Input] --> Router[Routing Classifier / LLM]
-    Router -->|Path A| AgentA[Specialized Agent A / Tool A]
-    Router -->|Path B| AgentB[Specialized Agent B / Tool B]
-    Router -->|Path C| AgentC[Specialized Agent C / Tool C]
-```
-
-### 4. Trade-offs
-* **Pros**: High modularity; reduces average system latency and token consumption.
-* **Cons**: Routing errors directly cause downstream task failures; an extra routing decision layer adds minor latency.
-
-### 5. Use Cases
-* Customer support dispatching (e.g., routing to billing, tech support, or returns agents).
-* Pre-filtering for tool calls.
-
----
-
-## Chapter 3: Parallelization
-
-### 1. Definition
-Splits a large task into multiple **independent subtasks** executed in parallel (Fork) and aggregates the results at a single point (Join).
-
-### 2. Problems Addressed
-* Cumulative linear latency: Solves the high time cost associated with sequential multi-step execution.
-* Single-perspective limitation: Collects diverse solutions to the same problem simultaneously for synthesis.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Input[Raw Query] --> Splitter[Splitter]
-    Splitter --> TaskA[Parallel Task A]
-    Splitter --> TaskB[Parallel Task B]
-    Splitter --> TaskC[Parallel Task C]
-    TaskA --> Syn[Synthesis / Aggregator]
-    TaskB --> Syn
-    TaskC --> Syn
-    Syn --> Output[Aggregated Output]
-```
-
-### 4. Trade-offs
-* **Pros**: Significantly reduces elapsed time; suitable for large-scale parallel filtering.
-* **Cons**: High spikes in token usage, easily triggering API rate limits; reconciling inconsistent results requires additional algorithms or LLM overhead.
-
-### 5. Use Cases
-* Static code analysis (checking security, performance, and style simultaneously).
-* Large-scale information retrieval and cross-document comparison.
-
----
-
-## Chapter 4: Reflection (Self-Correction)
-
-### 1. Definition
-Introduces a dual-entity feedback mechanism: a Generator and a Critic. The Generator produces an initial draft, the Critic evaluates it for quality and provides feedback, and the Generator iteratively refines the output until termination conditions are met.
-
-### 2. Problems Addressed
-* Unstable output quality: Prevents logical gaps, factual errors, or formatting anomalies.
-* Overconfidence: Breaks cognitive blind spots of a single-turn generation via an independent critique mechanism.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Input[Task Goal] --> Gen[Generator]
-    Gen --> Draft[Initial Draft]
-    Draft --> Critic[Critic / Evaluator]
-    Critic --> Decision{Is Acceptable?}
-    Decision -->|No| Feedback[Feedback/Suggestions]
-    Feedback -->|Guide Correction| Gen
-    Decision -->|Yes| Output[Final Accepted Output]
-```
-
-### 4. Trade-offs
-* **Pros**: Highly stable output quality, significantly reducing logical and formatting errors.
-* **Cons**: Higher token consumption; extended execution time; potential for infinite loops if termination conditions are poorly defined.
-
-### 5. Use Cases
-* Automated code generation and testing (write code -> run tests -> fix based on errors -> re-test).
-* Strict compliance document drafting.
-
----
-
-## Chapter 5: Tool Use / Function Calling
-
-### 1. Definition
-The LLM reads the description format (schema) of external tools, autonomously decides when to call a tool and generates the parameters. The agent executes the tool in a sandbox or external system, and feeds the results back to the LLM for interpretation.
-
-### 2. Problems Addressed
-* Information lag: Connects the model to real-time data.
-* Lack of computation: Solves difficulties in mathematics and precise logical operations.
-* Inability to affect external systems: Allows agents to send emails, write databases, or call APIs.
-
-### 3. Workflow
-```mermaid
-sequenceDiagram
-    participant U as User
-    participant L as LLM (Core Reasoning)
-    participant A as Agent Execution Sandbox
-    participant T as External Tool / API
-    U->>L: Query
-    L->>L: Identify context, decide to use clock tool
-    L-->>A: Return tool name & structured parameters
-    A->>T: Call external API
-    T-->>A: Return real-time data
-    A-->>L: Send execution result back as context
-    L->>L: Synthesize and reason
-    L->>U: Respond to user
-```
-
-### 4. Trade-offs
-* **Pros**: Greatly expands the action capabilities and data retrieval scope of the agent.
-* **Cons**: Risk of parameter generation errors; security risks with external tools (requires strict sandboxing); vulnerability to external API instability.
-
-### 5. Use Cases
-* Real-time data queries (weather, stock market, ERP systems).
-* Data entry and control (sending notifications, database updates).
-
----
-
-## Chapter 6: Planning
-
-### 1. Definition
-Decomposes a high-level goal into an ordered set of dependent execution steps. The planner dynamically rewrites the remaining steps (replanning) based on environmental feedback and new information to ensure the goal is reached.
-
-### 2. Problems Addressed
-* Goal drift: Prevents the agent from losing sight of the ultimate goal during multi-step execution.
-* Dynamic environment changes: Automatically searches for alternative solutions if a step fails.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Goal[Ultimate Goal] --> Planner[Planner: Task Decomposition]
-    Planner --> Plan[Generate Step List 1, 2, 3...]
-    Plan --> Executor[Executor: Call tools / sub-steps sequentially]
-    Executor --> EnvFeedback[Environmental Feedback]
-    EnvFeedback --> Checker{Encounter obstacles/failure?}
-    Checker -->|Yes| Replanner[Dynamic Replanner: Update plan]
-    Replanner --> Plan
-    Checker -->|No| Next{All steps completed?}
-    Next -->|No| Executor
-    Next -->|Yes| Output[Goal Accomplished]
-```
-
-### 4. Trade-offs
-* **Pros**: Highly adaptable; capable of autonomously handling complex, unstructured tasks.
-* **Cons**: Very high cost in LLM calls for planning and replanning; plan errors propagate, drifting downstream actions away from the target.
-
-### 5. Use Cases
-* Autonomous research assistants (Deep Research: dynamically selecting keywords, assessing information quality, diving deep into unknown domains).
-* Automated software development (architecture design -> module division -> sequential development).
-
----
-
-## Chapter 7: Multi-Agent Collaboration
-
-### 1. Definition
-Distributes a large task among multiple **specialized agents with distinct personas and skills**. These agents coordinate task handoffs, discussions, and integration through a predefined collaboration topology.
-
-### 2. Problems Addressed
-* Cognitive limits of a single core: Avoids overloading a single system prompt with too many instructions and roles.
-* Unclear division of labor: Emulates human teams by dedicating specialists to specific tasks.
-
-### 3. Workflow
-Four main collaboration topologies:
-* **Handoffs (Network)**: Agent A finishes its task and hands over the context and control to Agent B.
-* **Supervisor**: A central Supervisor agent coordinates, assigns tasks to specialists, and aggregates results.
-* **Hierarchy**: Supervisors oversee sub-supervisors, delegating and aggregating tasks hierarchically.
-* **Blackboard**: Agents read and write to a shared state space (blackboard), intervening autonomously as the state changes.
-
-### 4. Trade-offs
-* **Pros**: Modular and scalable; allows mixing different model sizes/strengths to optimize costs.
-* **Cons**: High communication overhead (multi-turn dialogues between agents); complex state management; risk of infinite discussion loops or unclear ownership.
-
-### 5. Use Cases
-* Simulated software development teams (Product Manager -> Architect -> Engineer -> QA).
-* Creative content generation and peer review.

package/skills/neo-agentic-design/references/resilience-hitl.md

@@ -1,105 +0,0 @@
-# Resilience, Exceptions & HITL
-
-This document provides conceptual designs for system resilience, human interaction, and knowledge grounding, covering exception handling, Human-in-the-Loop (HITL) gates, and Retrieval-Augmented Generation (RAG).
-
----
-
-## Chapter 12: Exception Handling and Recovery
-
-### 1. Definition
-Designs automatic detection, retry, fallback, and state rollback mechanisms for exceptions that may occur during agent execution (such as API timeouts, network disconnections, LLM format errors, and invalid tool parameters).
-
-### 2. Problems Addressed
-* System fragility: Prevents long-cycle workflows from breaking due to transient network or API issues.
-* Format pollution: Guides the LLM to self-heal when its output does not conform to the expected JSON schema.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Step[Execute Tool / Call LLM] --> Success{Successful?}
-    Success -->|Yes| Next[Proceed to Next Step]
-    Success -->|No: Exception| Detector[Exception Detector]
-    Detector --> RuleCheck{Evaluate Exception Type}
-    RuleCheck -->|Network/Timeout| Retry[Auto Retry with Backoff]
-    RuleCheck -->|Format Error| Refine[Guide LLM to Self-Correct]
-    RuleCheck -->|Tool Failure| Fallback[Route to Fallback/Alternative Tool]
-    RuleCheck -->|Critical Error| Rollback[Rollback State to Checkpoint]
-    Retry --> Step
-    Refine --> Step
-    Fallback --> Step
-    Rollback --> UserEscalation[Human Intervention]
-```
-
-### 4. Trade-offs
-* **Pros**: Improves system robustness and reduces manual maintenance costs.
-* **Cons**: Excessive retries or fallbacks can mask underlying bugs or quietly degrade output quality.
-
----
-
-## Chapter 13: Human-in-the-Loop (HITL)
-
-### 1. Definition
-Strategically embeds human review, intervention, and authorization mechanisms into the agent's autonomous decision-making workflow, combining human common sense, ethics, and legal judgment with AI automation.
-
-### 2. Problems Addressed
-* High-risk operations: Prevents agent errors when performing large financial transactions, deleting sensitive data, or executing legally sensitive actions.
-* Automation boundaries: Requests human guidance when decision confidence falls below a set threshold.
-
-### 3. Three Core Interaction Modes
-````carousel
-### 1. Human-in-the-Loop (HITL)
-* **Mechanism**: The agent pauses when reaching a high-risk step (e.g., large bank transfer), suspends the task, and sends it to a pending review queue.
-* **Workflow**: Agent pauses -> Human reviews (Approve/Reject/Modify) -> Agent receives input and resumes execution.
-* **Key Characteristic**: Human approval is a mandatory gate.
-<!-- slide -->
-### 2. Human-on-the-Loop (HOTL)
-* **Mechanism**: The agent executes tasks autonomously while a human supervisor monitors and adjusts strategies.
-* **Workflow**: Human sets macro rules (e.g., transaction limits) -> Agent trades automatically -> Human monitors metrics -> Human intervenes via a Kill Switch if necessary.
-* **Key Characteristic**: Human does not intervene in individual decisions but maintains macro-level oversight.
-<!-- slide -->
-### 3. Decision Augmentation
-* **Mechanism**: The agent acts as an analytical assistant, gathering data and presenting candidates. Decision-making and execution are performed entirely by a human.
-* **Workflow**: Human asks query -> Agent collects and analyzes data -> Agent proposes options A, B, and C with pros/cons -> Human selects and executes.
-* **Key Characteristic**: Agent provides cognitive augmentation without execution authority.
-````
-
-### 4. Trade-offs
-* **Pros**: Provides a safety net and compliance guarantee for high-risk decisions; collects human feedback to optimize agent alignment.
-* **Cons**: Human intervention limits system scalability and speed; designing human-in-the-loop review queues increases development costs.
-
----
-
-## Chapter 14: Knowledge Retrieval / RAG
-
-### 1. Definition
-Retrieves relevant information from a knowledge base before the LLM generates a response, injecting the retrieved text chunks into the prompt context to guide the LLM toward producing factually grounded answers.
-
-### 2. Advanced Agentic RAG Variants
-```mermaid
-graph TD
-    subgraph Traditional RAG
-        Query[User Query] --> VectorSearch[Vector Similarity Search]
-        VectorSearch --> Context[Concatenate Context Chunks]
-        Context --> LLMGen[LLM Generates Response]
-    end
-    subgraph Graph RAG
-        GQuery[User Query] --> GraphSearch[Navigate Knowledge Graph Nodes & Edges]
-        GraphSearch --> UnifiedContext[Cross-document Context Linkage]
-    end
-    subgraph Agentic RAG
-        AQuery[User Query] --> AgentLayer[Agent Decision Layer]
-        AgentLayer -->|1. Decompose Task| SubQueries[Multi-step Sub-retrieval Tasks]
-        AgentLayer -->|2. Self-Reflection| SourceVal[Source Timeliness & Quality Check]
-        AgentLayer -->|3. Resolve Conflicts| ConflictRecon[Active Conflict Reconciliation]
-        AgentLayer -->|4. Tool Call| WebSearch[Web Search for Knowledge Gaps]
-    end
-```
-
-### 3. Problems Addressed
-* Outdated knowledge: Bypasses the temporal limits of static training data.
-* Hallucination: Restricts the model within factual boundaries using verified document contexts.
-* Fragmented information: Resolves vector search limitations that struggle to answer comprehensive questions spanning multiple documents.
-
-### 4. Trade-offs
-* **Pros**: Minimizes factual errors; supports precise citations; imports private knowledge without retraining models.
-* **Cons**: Highly sensitive to the quality of text chunking and embeddings; multi-step reasoning in Agentic RAG increases response latency.

package/skills/neo-agentic-design/references/system-components.md

@@ -1,93 +0,0 @@
-# System Components & Protocols
-
-This document provides conceptual designs for system architecture components, resources, and protocols, covering memory management, learning and adaptation, Model Context Protocol (MCP), and goal setting and monitoring.
-
----
-
-## Chapter 8: Memory Management
-
-### 1. Definition
-Provides agents with the ability to store and retrieve information across sessions and tasks through persistence mechanisms. The memory system is generally divided into short-term and long-term memory, managed by a unified Memory Service.
-
-### 2. Memory Classification
-| Memory Type | Medium | Function | Eviction & Retrieval Mechanism |
-| :--- | :--- | :--- | :--- |
-| **Short-term** | Current Context Window | Stores current conversation context and task execution trajectory | Sliding window, context pruning, and summarization |
-| **Long-term Semantic** | Vector Database / Knowledge Base | Retains factual knowledge, concepts, and external rules | Vector semantic retrieval based on user input |
-| **Long-term Episodic** | Structured Database / Log Store | Records past task execution experiences and outcomes | Used for few-shot learning or similar scenario matching |
-| **Long-term Procedural**| Codebase / Tool Definitions / Prompt Templates | Records Standard Operating Procedures (SOPs) and toolbox definitions for specific tasks | Dynamically loaded based on task type |
-
-### 3. Problems Addressed
-* Amnesia (Context limits): Prevents long conversations from causing the LLM to lose critical history.
-* Repeated errors: Ensures the agent learns from past executions to improve decision success rates.
-
----
-
-## Chapter 9: Learning and Adaptation
-
-### 1. Definition
-Enables the agent to autonomously modify prompts or self-modify execution code in a code sandbox (SICA - Self-Improving Coding Agent) by collecting behavioral feedback and rewards from interactions with the environment, users, or other agents.
-
-### 2. Problems Addressed
-* Static configuration lag: Solves the issue of agents failing to adjust when environmental rules change.
-* High development cost: Eliminates the manual process of fine-tuning prompts.
-
-### 3. Workflow
-```mermaid
-graph TD
-    Interaction[Agent-Environment Interaction] --> Result[Execution Results & Metrics]
-    Result --> evaluator[Evaluator / Scoring System]
-    evaluator -->|Feedback/Score| Learner[Learning Engine]
-    Learner -->|Self-Optimize Prompts or Refactor Code| AgentUpgrade[Upgraded Agent]
-    AgentUpgrade -->|Next Task Turn| Interaction
-```
-
-### 4. Trade-offs
-* **Pros**: High potential for long-term self-evolution; can discover high-quality logic not designed by humans in specific vertical disciplines (e.g., mathematical proofs, code generation).
-* **Cons**: Unpredictable evolution paths, which may generate harmful mutations; self-modifying prompts can lead to privilege escalation or security vulnerabilities; extremely high overhead for training and testing iterations.
-
----
-
-## Chapter 10: Model Context Protocol (MCP)
-
-### 1. Definition
-A standardized **Client-Server communication protocol** that establishes a plug-and-play integration standard between LLMs/Agents (Clients) and external data sources, development tools, and API services (Servers). MCP standardizes three core types of context exchange: **Resources**, **Prompts**, and **Tools**.
-
-```mermaid
-graph LR
-    subgraph Agentic Client
-        Agent[AI Agent / LLM]
-    end
-    subgraph MCP Server
-        Res[Resources: Files/Databases]
-        Pmt[Prompts: Templates]
-        Tls[Tools: APIs/Sandboxes]
-    end
-    Agent <-->|Standard JSON-RPC 2.0| MCP_Link[MCP Protocol Layer]
-    MCP_Link <--> Res
-    MCP_Link <--> Pmt
-    MCP_Link <--> Tls
-```
-
-### 2. Problems Addressed
-* Tedious integration: Avoids repeatedly writing custom wrapper code when developing new agents or integrating new tools.
-* Fragmented context acquisition: Provides external data and actions to the model in a unified interface format.
-
-### 3. Trade-offs
-* **Pros**: Reduces integration costs for multiple tools and data sources; decouples data sources from reasoning entities; supports dynamic discovery.
-* **Cons**: Protocol serialization and JSON-RPC wrapping introduce minor performance overhead; requires tool providers to actively adopt the protocol.
-
----
-
-## Chapter 11: Goal Setting and Monitoring
-
-### 1. Definition
-Sets structured and quantifiable goals (SMART principles) before agent initialization, and introduces an independent monitor during the execution phase to observe progress in real time (Progress Checkpoints), detect blocks, and trigger human-agent collaboration escalation when necessary.
-
-### 2. Problems Addressed
-* Blind execution: Prevents agents from entering infinite retry loops when encountering logical obstacles, wasting budget.
-* Lack of observability: Solves the black-box execution problem, providing a clear progress path.
-
-### 3. Use Cases
-* Automated marketing campaign execution.
-* Long-cycle autonomous codebase refactoring.