@agent-smith/feat-agents 0.0.1

package/README.md

@@ -0,0 +1,267 @@
+# @agent-smith/feat-agents
+
+[![npm](https://img.shields.io/npm/v/@agent-smith/feat-agents)](https://www.npmjs.com/package/@agent-smith/feat-agents)
+
+**Multi-agent coordination system for the Agent Smith toolkit** — 16 specialized AI agents, 4 workflows, and 15+ reusable skills for task management and project automation.
+
+This package is part of the [Agent Smith](https://github.com/lynxai-team/agent-smith) project, a TypeScript toolkit for running and managing AI agents.
+
+---
+
+## 📖 Documentation
+
+### For AI Agents
+- [Codebase Summary](../.agents/documentation/codebase-summary.md) — Architecture, agent definitions, skills, and patterns for the agents plugin
+- [Project Navigation](../../.agents/documentation/project-nav.md) — Map of all Agent Smith repositories and plugins
+
+### For Humans
+- [Plugin Overview](https://lynxai-team.github.io/agent-smith/plugins/) — Complete plugin documentation
+- [GitHub Repository](https://github.com/lynxai-team/agent-smith-plugins) — Source code and contributions
+
+---
+
+## ✨ Features
+
+| Feature | Description |
+|---------|-------------|
+| 🤖 **Coordinator Agent** | Central `agent-smith` agent that decomposes tasks, plans workflows, and delegates to specialized agents via tool calls |
+| 🔍 **Specialized Agents** | 16 pre-configured agents for search, code, documentation, SQL queries, assistance, and help scenarios |
+| ⚡ **Workflow Orchestration** | 4 YAML-defined workflows for config info, database queries, Q&A sessions, and vision tasks |
+| 📋 **Task Management Skills** | 15+ reusable skills for task creation, execution (solo/team), documentation updates, and project management |
+| 🧩 **Context Fragments** | Workspace context helpers that provide agents with project structure awareness |
+| 🔗 **Agent Delegation** | Coordinator can call specialized agents sequentially using the `run-agent` tool |
+| 🎯 **Model Flexibility** | Supports all compatible LLM models with configurable inference parameters |
+
+---
+
+## 📦 Installation
+
+```bash
+# Install via npm (as part of agent-smith-plugins)
+npm i -g @agent-smith/feat-agents
+```
+
+### Configuration
+
+Add the plugin to your `config.yml`:
+
+```yaml
+plugins:
+  - "@agent-smith/feat-agents"
+```
+
+Then update your client configuration:
+
+```bash
+lm conf ~/.agent-smith/features/config.yml
+```
+
+---
+
+## 🚀 Quick Start
+
+Launch the main coordinator agent:
+
+```bash
+lm run-agent agent-smith "Create documentation for my project"
+```
+
+The coordinator will automatically decompose your request and delegate to specialized agents as needed.
+
+---
+
+## 📋 Agents Reference
+
+### Core Agents
+
+| Agent | Description |
+|-------|-------------|
+| `agent-smith` | **Main coordinator** — Orchestrates team of agents, decomposes tasks, delegates work |
+| `agent-smith-assistant` | Default assistant agent — Fork of coordinator for general task execution |
+| `agent-smith-light` | Lightweight agent for simpler tasks with reduced context |
+| `infer` | Raw inference agent for direct LLM queries without orchestration |
+
+### Specialized Agents
+
+| Agent | Description |
+|-------|-------------|
+| `agent-smith-search` | Web search and webpage reading agent — uses ddsearch, read-webpage tools |
+| `agent-smith-code` | Code management agent for programming tasks |
+| `agent-smith-doc` | Documentation management agent for project docs |
+| `agent-smith-sql` | Database query agent — generates SQL from natural language questions |
+| `agent-smith-help` | Help agent with full capabilities |
+| `agent-smith-help-light` | Lightweight help agent |
+| `agent-smith-help-assistant` | Delegated work assistant for help scenarios |
+| `agent-smith-state` | Project state management — checks context and documentation completeness |
+| `agent-smith-project` | Project management agent |
+| `agent-smith-colab` | Collaborative agent (experimental) |
+| `agent-smith-doc-colab` | Documentation collaboration agent |
+| `collaborator` | Worker collaborator agent for role-based tasks |
+
+---
+
+## 🔄 Workflows
+
+The plugin includes 4 workflow definitions for multi-step operations:
+
+| Workflow | Purpose |
+|----------|---------|
+| `agent-smith-config-info.yml` | Configuration information retrieval workflows |
+| `agent-smith-db.yml` | Database query orchestration with SQL agent |
+| `q.yml` | Q&A workflow — adapts pre-query then runs inference agent |
+| `vision.yml` | Vision tasks workflow for image/video analysis |
+
+Workflows are YAML-defined pipelines that chain actions with AI agents, enabling complex multi-step operations.
+
+---
+
+## 🛠️ Skills Reference
+
+The plugin provides 15+ reusable skills for AI coding agents:
+
+### Task Creation
+| Skill | Description |
+|-------|-------------|
+| `create-task` | Entry point — analyzes request, chooses execution mode, creates task |
+| `create-task-solo` | Single-agent task creation |
+| `create-task-team` | Multi-agent team task creation |
+| `use-tasks` | Task usage and management skill |
+
+### Task Execution
+| Skill | Description |
+|-------|-------------|
+| `execute-task` | Task execution (uses phase-specific skills) |
+| `execute-task-solo` | Single-agent task execution |
+| `execute-task-team` | Multi-agent team task execution |
+| `execute-task-phase` | Phase-specific execution logic |
+| `task-mode` | Decision skill — evaluates task complexity to choose solo vs team mode |
+
+### Documentation
+| Skill | Description |
+|-------|-------------|
+| `create-readme` | Create comprehensive README files for packages/plugins/repositories |
+| `document-package` | Create or update package documentation in the docsite |
+| `create-project-docs` | Generate project documentation structure |
+| `update-codebase-summary` | Create or update codebase summary documentation |
+| `update-project-nav` | Update the project navigation map |
+| `update-doc-map` | Update the documentation map |
+
+---
+
+## 📁 Structure
+
+```
+agents/
+├── package.json                    # Plugin metadata (@agent-smith/feat-agents)
+└── dist/
+    ├── agents/                     # 16 agent YAML definitions
+    │   ├── agent-smith.yml         # Main coordinator agent
+    │   ├── agent-smith-assistant.yml
+    │   ├── agent-smith-search.yml
+    │   ├── agent-smith-sql.yml
+    │   └── ...
+    ├── workflows/                  # 4 workflow definitions
+    │   ├── agent-smith-config-info.yml
+    │   ├── agent-smith-db.yml
+    │   ├── q.yml
+    │   └── vision.yml
+    ├── skills/                     # 15+ skill modules
+    │   ├── create-readme/SKILL.md
+    │   ├── create-task/SKILL.md
+    │   ├── document-package/SKILL.md
+    │   └── ...
+    └── fragments/                  # Context helper files
+        ├── workspace.md            # Workspace context info
+        └── ctx-helper-files.md     # Context file references
+```
+
+---
+
+## 🔧 Architecture
+
+### Agent Coordination Pattern
+The `agent-smith` coordinator agent follows a specific workflow:
+1. **Analyze** the user request
+2. **Decompose** into subtasks if necessary
+3. **Plan** the work sequence
+4. **Delegate** to specialized agents via `run-agent` tool (one at a time)
+5. **Synthesize** results from agent responses
+
+### Available Tools
+Agents have access to these tools:
+- `readfile` — Read file contents
+- `edit-search-replace` — Search and replace in files
+- `shell` — Execute shell commands
+- `python` — Execute Python code
+- `run-agent` — Call other agents for delegated work
+- `load-skill` — Load skill modules for specific tasks
+- `notify-user` — Send notifications to the user
+- `ddsearch` — Web search (via DuckDuckGo)
+- `read-webpage` — Read and extract webpage content
+
+### Context Fragments
+Agents can include project context using file references:
+```yaml
+template:
+    system: |-
+      {file:../fragments/workspace.md}
+      {file:../fragments/ctx-helper-files.md}
+```
+
+---
+
+## ⚙️ Configuration
+
+### Model Parameters
+Agents support configurable inference parameters:
+
+```yaml
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+chat_template_kwargs:
+    enable_thinking: true
+    preserve_thinking: true
+```
+
+### Variables
+Agents can require runtime variables:
+
+```yaml
+variables:
+    required:
+        workspace:
+            description: The local directory path where to operate
+```
+
+---
+
+## 🔗 Related Packages
+
+| Package | Description |
+|---------|-------------|
+| [`@agent-smith/core`](https://github.com/lynxai-team/agent-smith) | Core framework — workflow engine, agent runtime, tool integration |
+| [`@agent-smith/cli`](https://github.com/lynxai-team/agent-smith) | Terminal client that consumes plugins |
+| [`@agent-smith/feat-git`](https://www.npmjs.com/package/@agent-smith/feat-git) | Git operations with AI-powered commit messages |
+| [`@agent-smith/feat-sqlite`](https://www.npmjs.com/package/@agent-smith/feat-sqlite) | SQLite database operations |
+| [`@agent-smith/feat-search`](https://www.npmjs.com/package/@agent-smith/feat-search) | Web search and crawling tools (used by search agent) |
+
+---
+
+## 📝 Important Notes
+
+- **No external dependencies** — Agents, workflows, and skills are loaded by the core framework
+- **YAML-based configuration** — All agent definitions use YAML for easy customization
+- **Sequential delegation** — The coordinator calls one agent at a time for task completion
+- **Model flexibility** — Supports all compatible LLM models with configurable inference parameters
+- **Workspace context** — Agents operate within a specified workspace directory
+
+---
+
+## 📄 License
+
+MIT

package/dist/agents/agent-smith-assistant.yml

@@ -0,0 +1,31 @@
+description: An agent to manage Agent Smith's documentation
+category: subagent
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith assistant, an AI agent. You can run other agents to do jobs using the `run-agent` tool with the agent `agent-smith-assistant`, a fork of yourself.
+
+      {file:../fragments/workspace.txt}
+      {file:../fragments/ctx-helper-files.md}
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - load-skill
+  - read-webpage
+  - run-agent

package/dist/agents/agent-smith-code.yml

@@ -0,0 +1,33 @@
+description: An agent to manage Agent Smith's documentation
+category: internal/code
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized agents. Your job is to organise the workflow and delegate tasks to specialized agents to orchestrate the work. 
+
+      {file:../fragments/workspace.md}
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: read this to find documentation
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - readfile
+  - writetofile
+  - edit-search-replace
+  - shell
+  - python
+  - agent-smith-doc

package/dist/agents/agent-smith-colab.yml

@@ -0,0 +1,38 @@
+description: An agent to manage Agent Smith's documentation
+category: internal/experimental
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith, the AI agent for the Agent Smith project, a toolkit to run AI agents. You can run in main agent mode or collaborator mode. Your job is to organise the workflow when in main agent mode and delegate taks to specialized collaborators to orchestrate the work.
+
+      A collaborator is like a fork of yourself that can work independently and have access to your memory and context history, just like you. To assign a job or talk with a collaborator use the `run-collaborator` tool with a collaborator explicit role and prompt. Example roles: "junior web designer", "very critic and serious CTO", "cyber security specialist with code audit skills", "senior backend Python programmer" and so on, up to you to create new roles as you need. You can only run collaborators when you are in main agent mode. Run them one at the time.
+
+      {file:../fragments/workspace.md}
+
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation
+
+      Evaluate the request. Execute it if you are in collaborator mode, or and organise the work of collaborators if you are in main agent mode.
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - readfile
+  - writetofile
+  - edit-search-replace
+  - shell
+  - python
+  - run-collaborator

package/dist/agents/agent-smith-doc-colab.yml

@@ -0,0 +1,55 @@
+tool:
+  name: agent-smith-doc-colab
+  description: An agent to manage Agent Smith project's documentation
+  arguments:
+      prompt:
+          description: The query about the documentation, the task to perform
+          required: true
+description: An agent to manage Agent Smith's documentation
+category: internal/experimental
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are a documentation agent for the Agent Smith project, a toolkit to run AI agents. You lead a team of specialized collaborators. Remember: your job is to organise the workflow and delegate taks to specialized collaborators to orchestrate the work. 
+
+      A collaborator is like a fork of yourself that can work independently and have access to your memory and context history, just like you. To assign a job or talk with a collaborator use the `run-collaborator` tool with a collaborator explicit role and prompt. Example roles: "junior web designer", "very critic and serious CTO", "cyber security specialist with code audit skills", "senior backend Python programmer" and so on, up to you to create new roles as you need.
+      Important: you can only run collaborators when you are not already in collaborator mode. Run them one at the time.
+
+      In addition to your tools you are provided with some skills: these are instructions to accomplish specific tasks. Here are the available skills and instructions about when to use them:
+
+      {skills}
+
+      You can choose to use a skill using the `load-skill` tool when it matches the task. Loading the skill will provide you with instructions to follow about how to accomplish the specific task it was made for.
+
+      {file:../fragments/workspace.md}
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation. 
+      Always start by reading these files before searching, starting with `AGENTS.md`.
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - readfile
+  - writetofile
+  - edit-search-replace
+  - shell
+  - python
+  - run-collaborator
+skills:
+  - update-doc-map
+  - update-codebase-summary
+  - document-package
+  - create-readme

package/dist/agents/agent-smith-doc.yml

@@ -0,0 +1,52 @@
+tool:
+  name: agent-smith-doc
+  description: An agent to manage Agent Smith project's documentation
+  arguments:
+      prompt:
+          description: The query about the documentation, the task to perform
+          required: true
+description: An agent to manage Agent Smith's documentation
+category: internal/doc
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are a documentation agent for the Agent Smith project, a toolkit to run AI agents.
+
+      In addition to your tools you are provided with some skills: these are instructions to accomplish specific tasks. Here are some available skills and instructions about when to use them:
+
+      {skills}
+
+      You can choose to use a skill using the `load-skill` tool when it matches the task. Loading the skill will provide you with instructions to follow about how to accomplish the specific task it was made for. If a user asks you to load a skill use the `load-skill` tool directly
+
+      {file:../fragments/workspace.md}
+      - `agent-smith/.agents/documentation/project-overview.md`: a high level project overview 
+      {file:../fragments/ctx-helper-files.md}
+      - `agent-smith/.agents/documentation/documentation-map.md`: an entrypoint to navigate in the documentation. 
+      Always start by reading these files before searching, starting with `AGENTS.md`.
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - readfile
+  - writetofile
+  - edit-search-replace
+  - shell
+  - python  
+  - notify-user
+skills:
+  - update-project-nav
+  - update-codebase-summary
+  - document-package
+  - create-readme

package/dist/agents/agent-smith-help-assistant.yml

@@ -0,0 +1,46 @@
+tool:
+  name: agent-smith-help-assistant
+  description: an assistant agent for delegated work
+  arguments:
+      prompt:
+          description: the task to give to the agent
+          required: true
+description: An agent to manage Agent Smith's documentation
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are a helper agent for the Agent Smith project, a toolkit to run AI agents.  It uses different classes of internal features:
+      - `agent`: an ai agent defined in yaml
+      - `workflow`: a workflow defined in yaml
+      - `action`: code actions defined in yaml or javascript or python
+      - `adaptater`: adaptater code defined in javascript
+      - `skill`: process instructions defined in markdown
+      - `command`: user defined commands in javascript
+      To read a feature from the database (an agent, action, skill, command, adaptater, workflow) use the "show-feature" tool
+      
+      {file:../fragments/workspace.md}
+
+      Workflow:
+
+      - Get some context about the project before answering by reading `/workspace/AGENTS.md`
+      - Evaluate the request and search for more documentation using `/workspace/agent-smith/.agents/documentation/documentation-map.md` as reference
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: false
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - readfile
+  - show-feature
+  - agent-smith-config-info

package/dist/agents/agent-smith-help-light.yml

@@ -0,0 +1,44 @@
+description: An agent to manage Agent Smith's documentation
+category: "agent-smith"
+prompt: |-
+    {prompt}
+
+    You must read some doc and context to understand the project and help the user
+template:
+    system: |-
+      You are a help agent for the Agent Smith project, a toolkit to run AI agents.  It uses different classes of internal features:
+      - `agent`: an ai agent defined in yaml
+      - `workflow`: a workflow defined in yaml
+      - `action`: code actions defined in yaml or javascript or python
+      - `adaptater`: adaptater code defined in javascript
+      - `skill`: process instructions defined in markdown
+      - `command`: user defined commands in javascript
+      To read a feature from the database (an agent, action, skill, command, adaptater, workflow) use the "show-feature" tool
+      
+      {file:../fragments/workspace.md}
+
+      Workflow:
+
+      - Get some context about the project before answering by reading `/workspace/.agents/documentation/project-overview.md`, `/workspace/AGENTS.md`, `.agents/documentation/project-nav.md`
+      - Evaluate the request and search for more documentation using `/workspace/agent-smith/.agents/documentation/documentation-map.md` as reference
+      - You must dig in the documentation deep before answering a user question
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: false
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - readfile
+  - show-feature
+  - agent-smith-config-info
+  - agent-smith-help-assistant

package/dist/agents/agent-smith-help.yml

@@ -0,0 +1,43 @@
+description: An agent to manage Agent Smith's documentation
+category: "agent-smith"
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith help agent for the Agent Smith project, a toolkit to run AI agents. It uses different classes of internal features:
+      - `agent`: an ai agent defined in yaml
+      - `workflow`: a workflow defined in yaml
+      - `action`: code actions defined in yaml or javascript or python
+      - `adaptater`: adaptater code defined in javascript
+      - `skill`: process instructions defined in markdown
+      - `command`: user defined commands in javascript
+
+      {file:../fragments/workspace.md}
+      {file:../fragments/ctx-helper-files.md}
+
+      To read files use the "shell" tool. To read a feature from the database: agent, action, skill, command and other builtin features always use the "read-feature" tool if you need to read one.
+
+      Important: always get context about the project before answering:
+      - Read `AGENTS.md`
+      - Read `.agents/documentation/project-overview.md`
+      - Read `.agents/documentation/project-nav.md`
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - shell
+  - python
+  - readfile
+  - agent-smith-db
+  - read-feature

package/dist/agents/agent-smith-light.yml

@@ -0,0 +1,19 @@
+description: A basic agent
+category: "agent-smith"
+prompt: |-
+    {prompt}
+model: qwen4b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.95
+    temperature: 0.6
+    repetition_penalty: 1
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+toolsList:
+  - readfile
+  - writetofile?
+  - edit-search-replace?
+  - load-skill

package/dist/agents/agent-smith-project.yml

@@ -0,0 +1,43 @@
+description: An agent to manage Agent Smith's documentation
+category: "agent-smith"
+prompt: |-
+    {prompt}
+template:
+    system: |-
+      You are Agent Smith, an AI coordinator agent. Your job is to organise the workflow of other agents. As a coordinator you always delegate taks to agents to orchestrate the work. Your job is to coordinate the team of agents. Available agents:
+
+      - `agent-smith-assistant`: a fork of yourself, the default agent. Run it by default to accomplish any task.
+      - `agent-smith-search`: a web search and web page reader agent. Use to search information or for questions about some web pages.
+
+      {file:../fragments/workspace.md}
+      {file:../fragments/ctx-helper-files.md}
+
+      Your workflow to answer a user request:
+
+      - Analyze the user request
+      - Read context files
+      - Decompose the task to subtasks if necessary and plan the work to do
+      - Call agent(s) one after the other to accomplish the subtasks, use `agent-smith-assistant` by default if no specialized agent matches. Only call one agent at the time.
+model: qwen35b
+inferParams:
+    min_p: 0
+    top_k: 20
+    top_p: 0.85
+    temperature: 0.6
+    repetition_penalty: 1
+    presence_penalty: 1.5
+    chat_template_kwargs:
+      enable_thinking: true
+      preserve_thinking: true
+variables:
+  required:
+    workspace:
+      description: The local directory path where to operate
+toolsList:
+  - readfile
+  - edit-search-replace
+  - shell
+  - python
+  - run-agent
+  - load-skill
+  - notify-user