@moon791017/neo-skills 1.1.11 → 1.1.12

package/README.md

@@ -59,6 +59,7 @@
 | TypeScript | `neo-typescript` | 處理 TypeScript、tsconfig、strict mode、泛型、conditional/mapped/template literal types、ESM/CJS 與 runtime boundaries。 |
 | Vue | `neo-vue` | 建置、除錯、重構或審查 Vue 3、SFC、Composition API、Pinia、Vue Router、Vite 與 Vue+TypeScript。 |
 | Agent 架構 | `neo-sub-agent` | 設計、建立、審查或轉換 sub-agent、custom agent、worker/reviewer/planner agent 或 multi-agent workflow。 |
+| Agent 架構 | `neo-agentic-design` | 設計、評估或實作 Agent 工作流、提示詞鏈、路由、規劃、反思、多 Agent 協作與記憶體管理等框架無關模式。 |
 | 文字潤飾 | `neo-stop-slop` | 去除繁中或英文中的 AI 腔、贅詞、公式化句式，支援文件、註解、commit message 與 PR 說明。 |
 
 ## 安裝
@@ -153,6 +154,7 @@ npx -p @moon791017/neo-skills install-system-instructions \
 | 建 Vue 3 元件 | `neo-vue` | `幫我重構這個 SFC，避免響應式踩坑` |
 | 改善 AI 開發流程 | `neo-agent-harness` | `評估這個專案讓 coding agent 協作的可靠度` |
 | 建立 sub-agent | `neo-sub-agent` | `幫我新增一個 Codex code-reviewer sub agent` |
+| 設計 Agent 編排架構 | `neo-agentic-design` | `幫我設計一個多 Agent 客服系統的拓撲結構與重試機制` |
 | 去掉 AI 腔 | `neo-stop-slop` | `把這段 PR 說明改得自然、直接一點` |
 
 ## 開發

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moon791017/neo-skills",
-  "version": "1.1.11",
+  "version": "1.1.12",
   "type": "module",
   "description": "Neo Skills: A Universal AI Agent Skills Extension",
   "homepage": "https://neo-blog-iota.vercel.app/",

package/skills/neo-agentic-design/SKILL.md

@@ -0,0 +1,89 @@
+---
+name: neo-agentic-design
+description: >
+  Use this skill when designing, evaluating, or implementing Agent workflows, prompt chains, routing, planning, reflection, multi-agent collaboration, memory management, or other framework-agnostic LLM orchestration patterns.
+license: MIT
+compatibility: No specific language runtime required; conceptual-only patterns.
+metadata:
+  version: "1.0.0"
+  type: "conceptual-design"
+---
+
+# Neo Agentic Design
+
+This skill provides architectural concepts and orchestration patterns for building LLM Agent systems. It covers 21 core design patterns categorized into four themes. The orchestration logic remains abstract and independent of specific programming languages or frameworks.
+
+## Gotchas
+* **Over-engineering**: Prioritize simple prompt chains (Chapter 1) or routing (Chapter 2). Use complex multi-agent collaboration (Chapter 7) or hierarchical networks only when necessary to reduce token overhead.
+* **Reflection Infinite Loops**: When implementing reflection (Chapter 4) or self-correction (Chapter 12), enforce a maximum iteration limit (e.g., 3-5 iterations) to prevent the LLM from getting stuck in an infinite loop.
+* **Blocking Operations**: High-risk operations (such as direct database deletions or large fund transfers) must include a Human-in-the-Loop review gate (Chapter 13).
+* **Context Pruning State Loss**: When compressing context, protect critical agent instructions from being pruned to prevent behavioral degradation.
+
+## Workflow Checklist
+Progress:
+- [ ] Step 1: Analyze Requirements (define objectives, inputs, constraints, and complexity levels).
+- [ ] Step 2: Select Orchestration Patterns (load corresponding reference documents based on requirements).
+- [ ] Step 3: Plan System Components (determine memory, learning mechanisms, and protocol specifications).
+- [ ] Step 4: Define Resilience and Safety (establish exception handling, human review gates, and input/output guardrails).
+- [ ] Step 5: Draft Design Proposal (create system topology diagrams and describe the architecture).
+
+## Detailed Guidelines
+
+### Step 1 — Analyze Requirements
+Evaluate problem complexity (Level 1, 2, or 3) and confirm:
+1. **Latency Sensitivity**: For low-latency requirements, prioritize parallelization (Chapter 3) and routing (Chapter 2).
+2. **Task Fragility**: For strict sequential tasks or error-prone processes, use chaining (Chapter 1) or planning (Chapter 6).
+
+### Step 2 — Load Design Patterns (Progressive Loading)
+Load specific reference files as needed to avoid loading all concepts at once:
+* Base workflows (Prompt Chaining, Routing, Parallelization, Reflection, Tool Use, Planning, Multi-Agent Collaboration):
+  👉 **Load [base-workflows](references/base-workflows.md)**
+* System infrastructure (Memory Management, Learning and Adaptation, MCP, Goal Setting and Monitoring):
+  👉 **Load [system-components](references/system-components.md)**
+* Exception handling, HITL, RAG fact-grounding:
+  👉 **Load [resilience-hitl](references/resilience-hitl.md)**
+* Advanced safety, evaluation, prioritization, A2A communication, exploration and discovery:
+  👉 **Load [advanced-safety](references/advanced-safety.md)**
+
+### Step 3 — System Architecture Planning
+The design document must clearly document:
+1. **State Space**: Context window management method and division of short-term and long-term memory (cognitive/procedural memory).
+2. **Tool Boundaries**: Tool call schema protocols and sandbox rules.
+3. **Safety Boundaries**: Specific conditions for triggering human approval (HITL) or falling back to backup models.
+
+---
+
+## Output Template (Agentic Architecture Design Proposal)
+
+When presenting agent designs to users, use this template format:
+
+```markdown
+# Agentic System Design Proposal: [System Name]
+
+## 1. Executive Summary
+* **Complexity Level**: [Level 1 / Level 2 / Level 3]
+* **Target Objective**: [System Goal]
+* **Key Constraints**: [Constraints such as latency, cost, security, etc.]
+
+## 2. Core Orchestration Architecture
+* **Selected Patterns**: [e.g., Router -> Parallel Agents -> Synthesizer]
+* **Workflow Description**: [System data flow and control flow description]
+
+### Topology Diagram (Mermaid)
+```mermaid
+[Mermaid diagram representing the Agent Loop / Topology]
+```
+
+## 3. Reference Patterns Applied
+* **[Pattern Name] (Chapter X)**: [Specific application and rationale in the system]
+* **[Pattern Name] (Chapter Y)**: [Specific application and rationale in the system]
+
+## 4. Resilience, Safety & HITL Rules
+* **Exception Recovery**: [Handling flow for API timeouts, rate limits, and JSON formatting errors]
+* **Human-in-the-Loop Gates**: [Conditions triggering human review]
+* **Guardrails**: [Input filtering and output validation mechanisms]
+
+## 5. Next Steps / Implementation Roadmap
+1. [Step 1]
+2. [Step 2]
+```

package/skills/neo-agentic-design/evals/eval_queries.json

@@ -0,0 +1,58 @@
+[
+  {
+    "query": "I need to design a system that routes incoming user queries to specialized LLM prompts depending on their category.",
+    "should_trigger": true
+  },
+  {
+    "query": "How do I implement reflection and self-correction in a multi-agent system to make it write better code?",
+    "should_trigger": true
+  },
+  {
+    "query": "Can you review my LLM orchestration workflow? It currently uses prompt chaining but has high latency.",
+    "should_trigger": true
+  },
+  {
+    "query": "I want to set up a Model Context Protocol (MCP) server for my agent so it can read local files.",
+    "should_trigger": true
+  },
+  {
+    "query": "What is the best way to handle long-term semantic memory and episodic memory in an autonomous agent?",
+    "should_trigger": true
+  },
+  {
+    "query": "Please design a pipeline workflow for generating technical reports, with a human-in-the-loop validation step.",
+    "should_trigger": true
+  },
+  {
+    "query": "How does dynamic re-prioritization work when an agent has conflicting goals?",
+    "should_trigger": true
+  },
+  {
+    "query": "Review the exception handling and recovery mechanism in my LLM agent loop.",
+    "should_trigger": true
+  },
+  {
+    "query": "I need to write a Python script that calculates the Fibonacci sequence using recursion.",
+    "should_trigger": false
+  },
+  {
+    "query": "What is the difference between supervised learning and reinforcement learning in traditional machine learning?",
+    "should_trigger": false
+  },
+  {
+    "query": "How do I configure my local PostgreSQL database on macOS?",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a CSS stylesheet for a dark mode website.",
+    "should_trigger": false
+  },
+  {
+    "query": "I want to build a simple web scraper in Python using beautifulsoup4.",
+    "should_trigger": false
+  },
+  {
+    "query": "How do I write a prompt to make ChatGPT act like a professional English translator?",
+    "should_trigger": false
+  }
+]

package/skills/neo-agentic-design/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "skill_name": "neo-agentic-design",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Design an agentic system that generates monthly financial reports. It must parse transaction raw data, categorize expenses, draft a report, let a human reviewer approve/edit the draft, and then output a final PDF. Minimize latency and ensure high accuracy.",
+      "expected_output": "An Agentic System Design Proposal containing Routing, Chaining, and Human-in-the-Loop patterns, structured with the standard output template.",
+      "assertions": [
+        "The output starts with 'Agentic System Design Proposal' or matches the template format",
+        "The proposal mentions Routing, Chaining, and Human-in-the-Loop patterns",
+        "The proposal contains a Mermaid sequence or flowchart diagram representing the topology",
+        "The proposal lists specific Gotchas or risks like latency and cost control"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "I need to design a system that reviews incoming code commits for potential security vulnerabilities and performance bottlenecks. It needs to check thousands of commits daily and must fail-safely if any analysis tool crashes.",
+      "expected_output": "An Agentic System Design Proposal containing Parallelization, Routing, Guardrails, and Exception Recovery patterns, structured with the standard output template.",
+      "assertions": [
+        "The proposal includes Parallelization and Exception Recovery patterns",
+        "The proposal provides a Mermaid topology diagram showing parallel evaluation and a merge point",
+        "The proposal includes specific Exception Handling rules for crashed analysis tools",
+        "The proposal includes Guardrails policies for input/output sanitization"
+      ]
+    }
+  ]
+}

package/skills/neo-agentic-design/references/advanced-safety.md

@@ -0,0 +1,158 @@
+# Advanced Execution, Guardrails & Safety
+
+This document provides conceptual designs for advanced execution, guardrails, and safety patterns, covering agent-to-agent (A2A) communication, resource-aware optimization, reasoning techniques, guardrails, evaluation and monitoring, prioritization, and scientific exploration.
+
+---
+
+## Chapter 15: Inter-Agent Communication (A2A)
+
+### 1. Definition
+An open agent communication protocol across frameworks and technology stacks. Uses standard HTTP and JSON-RPC formats to enable agent declaration, task delegation, and data exchange across different networks.
+
+### 2. Core Components
+* **Agent Card**: A JSON declaration containing the agent name, version, endpoint URL, multimodal capabilities, and skills.
+* **Task Mechanism**: Defines collaboration as a "Task" with a lifecycle state (Submitted, Working, Completed, Failed), tracked using a `contextId` for multi-turn conversation context.
+* **Communication Modes**:
+  * **Synchronous**: Direct invocation with immediate response.
+  * **Asynchronous Polling**: Submit a task to obtain a Task ID and periodically query status.
+  * **Streaming (SSE)**: Receive partial outputs in real time via Server-Sent Events.
+  * **Webhook**: Actively push notifications to a specified URL upon task completion.
+
+### 3. Problems Addressed
+* Heterogeneous framework silos: Solves communication barriers between different agent frameworks.
+* Distributed collaboration barriers: Enables agents on different servers to safely delegate tasks.
+
+---
+
+## Chapter 16: Resource-Aware Optimization
+
+### 1. Definition
+Monitors computation, latency, and financial costs (tokens/API calls) in real time during agent execution. Dynamically switches between models with different capabilities or prunes context based on budget and latency constraints.
+
+### 2. Problems Addressed
+* API cost overruns: Avoids using expensive reasoning models for simple queries.
+* Rate limits and overload: Executes fallbacks and backup plans when the primary model is limited or overloaded.
+
+### 3. Workflow
+```mermaid
+graph TD
+    Query[User Query] --> Router{Router LLM}
+    Router -->|1. Simple Query| CheapModel[Lightweight Model]
+    Router -->|2. Complex Reasoning| ExpensiveModel[High-tier Reasoning Model]
+    Router -->|3. Real-time Info| SearchTool[Real-time Search Tool]
+    CheapModel --> Checker[Critique Agent: Quality Eval]
+    ExpensiveModel --> Checker
+    Checker -->|Fail| Fallback[Fallback Plan]
+    Checker -->|Pass| Output[Final Output]
+```
+
+---
+
+## Chapter 17: Reasoning Techniques
+
+### 1. Definition
+Architectural techniques that allocate more computational resources at inference time to explicitly expand the agent's thought process. Covers step-by-step decomposition, tree-search path planning, code-assisted execution, and ReAct loops.
+
+### 2. Six Core Reasoning Patterns
+* **Chain of Thought (CoT)**: Guides the model to reason step-by-step to decompose complex problems.
+* **Tree of Thoughts (ToT)**: Represents the reasoning space as a tree, supporting backtracking and multi-path parallel evaluation.
+* **Reasoning and Action (ReAct)**: Interleaves tool execution with reasoning steps (Thought -> Action -> Observation -> Thought ... -> Finish).
+* **Program-Aided Language Models (PALMs)**: Offloads precise mathematical calculations to a secure code sandbox and interprets the results to eliminate calculation hallucinations.
+* **Multi-Agent Debate (Chain/Graph of Debates)**: Employs multiple agents to debate a problem across several turns, using consensus or strong logical conclusions as the final answer.
+* **Scaling Inference Law**: Uses multi-path generation, self-correction, or extended thinking paths during the inference stage, allowing smaller models to achieve performance comparable to a single generation of a larger model.
+
+---
+
+## Chapter 18: Guardrails & Safety Patterns
+
+### 1. Definition
+Deploys multiple layers of filtering and defense at the input, tool execution, and output stages to ensure system compliance, safety, and protection against jailbreak attacks, prompt injection, and tool privilege escalation.
+
+### 2. Multi-Layer Defense Flow
+```mermaid
+graph TD
+    Input[User Input] --> InputGuard[1. Input Guardrails: Jailbreak/Injection Detection]
+    InputGuard -->|Violation| Block[Access Denied]
+    InputGuard -->|Safe| LLM_Core[2. Core Agent Reasoning]
+    LLM_Core -->|Call Tool| ToolCallback[3. Pre-execution Tool Validation]
+    ToolCallback -->|Reject| LLM_Core
+    ToolCallback -->|Approve| ToolExec[Tool Execution]
+    ToolExec --> OutputGen[Output Generation]
+    OutputGen --> OutputGuard[4. Output Guardrails: PII/Toxicity Filter]
+    OutputGuard -->|Safe| User[Deliver to User]
+    OutputGuard -->|Violation| Redaction[Redaction/Block/Self-Correction]
+```
+
+### 3. Problems Addressed
+* Prompt jailbreaks: Prevents users from guiding the agent to perform unauthorized or harmful actions.
+* Privilege escalation: Follows the principle of least privilege to prevent agents from unauthorized data modification or account deletion.
+
+---
+
+## Chapter 19: Evaluation and Monitoring
+
+### 1. Definition
+Systematically measures and audits agent execution quality, trajectories, resource consumption, and drift. Evaluates the execution trajectory rather than just the final answer for non-deterministic systems.
+
+### 2. Three Core Evaluation Aspects
+* **Objective Metrics Monitoring**: Logs latency, token consumption, and API success rates.
+* **Trajectory Evaluation**: Compares action sequences with standard SOPs using exact matching, ordered matching, or unordered matching.
+* **LLM-as-a-Judge**: Uses an independent LLM to score answers based on specific rubrics and outputs structured feedback.
+
+### 3. Advanced Pattern: AI Contractor / Contract Pattern
+Resolves prompt drift and responsibility ambiguity:
+```mermaid
+graph TD
+    User[User] -->|1. Initiate Draft Contract| Contractor[Contractor Agent]
+    Contractor -->|2. Self-Analysis & Evaluation| Analyze[Analyze clauses, scope, cost, dependencies]
+    Analyze -->|3. Negotiate Feedback| User
+    User -->|4. Approve & Sign| Execute[5. Execution: Self-test & verify]
+    Execute -->|6. Decompose Tasks| SubContracts[Sub-contracts]
+    SubContracts --> SubAgents[Sub-agents]
+    Execute -->|7. Deliver Deliverables| User
+```
+
+---
+
+## Chapter 20: Prioritization
+
+### 1. Definition
+Sorts and dynamically schedules the execution order of multiple goals and tasks when the agent is faced with resource constraints or limited budgets.
+
+### 2. Problems Addressed
+* Deadlocks and lack of focus: Prevents delays in critical tasks caused by prioritizing minor ones.
+* Inadequate crisis response: Ensures the agent can dynamically switch task context when high-priority events (e.g., safety alerts) occur.
+
+### 3. Prioritization Metrics
+* **Urgency**: Time sensitivity (closeness to deadline).
+* **Importance**: Impact on accomplishing the ultimate goal.
+* **Dependencies**: Whether the task is a prerequisite for other tasks.
+* **Cost-Benefit Ratio**: Expected payoff relative to consumed resources.
+
+### 4. Mechanism
+Tasks are scored and entered into a Priority Queue, executed sequentially by the planner. The system recalculates weights and re-orders the queue (Dynamic Re-prioritization) or interrupts the current task when the environmental state changes.
+
+---
+
+## Chapter 21: Exploration and Discovery
+
+### 1. Definition
+Enables the agent to proactively explore unknown domains (Unknown Unknowns), generate new knowledge, design experiments, and prove hypotheses.
+
+### 2. Multi-Agent Scientific Discovery Flow
+```mermaid
+graph TD
+    Goal[Exploration Goal] --> GenAgent[1. Generation Agent]
+    GenAgent -->|Propose Hypothesis| RefAgent[2. Reflection Agent]
+    RefAgent -->|Peer Review / Correction Suggestions| GenAgent
+    RefAgent -->|Accepted Draft| RankAgent[3. Ranking Agent]
+    RankAgent -->|Elo Tournament Debate| BestHypotheses[Select Best Hypotheses]
+    BestHypotheses --> EvoAgent[4. Evolution Agent]
+    EvoAgent -->|Concept Merging & Non-linear Exploration| AdvancedHypo[Advanced Hypotheses]
+    AdvancedHypo --> LabAgent[5. Lab Agent]
+    LabAgent -->|Execute Code/Simulation/Analysis| FinalReport[6. Final LaTeX Report]
+```
+
+### 3. Trade-offs
+* **Pros**: Explores unknown topics autonomously, discovering insights that exceed human experience.
+* **Cons**: High uncertainty and heavy token consumption; requires strict safety guardrails to prevent generating hazardous protocols.

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

@@ -0,0 +1,219 @@
+# 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

@@ -0,0 +1,105 @@
+# 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

@@ -0,0 +1,93 @@
+# 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.