@agent-smith/feat-agents 0.0.1

package/dist/skills/create-task-team/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: create-task-team
+description: use this to create a new task with proper structure for multi-agent (team) execution with coordinator-executor delegation
+---
+
+# Create Task Instructions (Coordinator Agent)
+
+## Task Directory Structure
+
+Tasks are located in `.agents/tasks/[task-name]/`. Structure:
+
+```
+[task-name]/
+├── goals.md                      # Goals and success criteria
+├── plan.md                       # Full execution plan (reference)
+├── state.md                      # Progress tracking
+├── coordinator-instructions.md   # Your orchestration instructions
+└── phases/
+    ├── phase-1.md
+    └── phase-2.md
+```
+
+## Creating Task Files
+
+### 1. `goals.md` — Goals & Success Criteria
+```md
+# Goals and Success Criteria: [task-name]
+
+## Primary Goal
+[Clear statement of what the task achieves]
+
+## Success Criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+
+## Files Modified
+- `path/to/file` — description of changes
+
+## Exclusions
+[What is NOT included in this task]
+```
+
+### 2. `plan.md` — Full Execution Plan
+Contains the complete plan with all phases and steps. Used as reference only.
+
+### 3. `phases/phase-X.md` — Individual Phase Files
+
+Each phase file must contain **context** (so executor can work independently) and **step-by-step instructions**:
+
+```md
+# Phase X: [Phase Name]
+
+## Context
+- **Task ID:** [task-name]
+- **Current state:** [metrics/status]
+- **Target:** [what we're aiming for]
+
+### Files to Modify
+| File | Purpose |
+|------|---------|
+| `path/to/file` | What changes here |
+
+---
+
+## Phase Goal
+[What this phase achieves]
+
+---
+
+### Step X.1: [Step Name]
+**File:** `path/to/file`
+**Execution Plan:** [Detailed instructions]
+**Success Criteria:**
+- [ ] Criterion 1 (verifiable)
+```
+
+**Phase file rules:**
+- Include full context — executor agents should NOT read other files
+- Each step has explicit execution plan AND success criteria
+- Success criteria must be verifiable (e.g., "test passes", "file contains X")
+
+### 4. `coordinator-instructions.md` — Your Orchestration Guide
+```md
+# Coordinator Instructions: [task-name]
+
+## Phase Files
+| Phase | File | Steps |
+|-------|------|-------|
+| 1: [name] | phases/phase-1.md | N |
+
+## Execution Workflow
+1. Read `state.md` to identify next phase
+2. Delegate phase to executor agent
+3. Wait for completion, verify success criteria
+4. Update `state.md` to mark phase completed
+5. Repeat until all phases done
+```
+
+The coordinator must instruct subagents that they can use the `.agents/tasks/[task-name]/documents` directory to create markdown file that other agents will be able to read. Each agent must report what documents it created if it did, so that the next agent can be informed to read these documents if necessary
+
+### 5. `state.md` — Progress Tracking
+```md
+# Task State: [task-name]
+
+## Status: [planned | in-progress | completed]
+
+## Phase Files
+| Phase | File | Steps |
+|-------|------|-------|
+| 1: [name] | phases/phase-1.md | N |
+
+## Progress
+### Phase X: [name]
+- [ ] Step X.1: [description]
+- [x] Step X.2: [description] ✓
+
+## Notes
+- Next phase to execute: Phase X
+```

package/dist/skills/document-package/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: document-package
+description: use when asked to create or update package documentation in the docsite
+---
+
+This skill describes the workflow to document a package for the Agent Smith CLI.
+
+## Workflow
+
+Execute this one step after the other:
+
+1. **Locate the package** — Read `.agents/documentation/codebase-summary.md` to find the package path
+
+2. **Read codebase summary** — Read `[package-path].agents/documentation/codebase-summary.md` (e.g., `agent-smith-plugins/system/shell/.agents/documentation/codebase-summary.md`). This provides a quick overview of tools, agents, dependencies, and architecture.
+
+3. **Read source code** — Inspect `src/actions/`, `dist/agents/*.yml`, `dist/tasks/*.yml` to identify tools, agents, and capabilities.
+
+4. **Find next number** — List existing docs in `agent-smith/docsite/public/doc/plugins/`. Use the next available number (e.g., if 1-8 exist, use 9).
+
+5. **Write the doc** at `agent-smith/docsite/public/doc/plugins/<N>.<name>.md` using this exact structure:
+
+```markdown
+# <PackageName>
+
+![pub package](https://img.shields.io/npm/v/@agent-smith/feat-<name>)
+
+One-line description of what the package does.
+
+## Install
+
+```bash
+npm i -g @agent-smith/feat-<name>
+```
+
+Add the package to your `config.yml` file and run the `conf` command:
+
+```yml
+plugins:
+  - "@agent-smith/feat-<name>"
+```
+
+```bash
+lm conf
+```
+
+## Actions and tools
+
+### <category>
+
+Available tools:
+
+- <kbd>tool-name</kbd> one-line description of what it does (include container image if applicable)
+
+## Agents
+
+Available agents:
+
+- <kbd>agent-name</kbd> one-line description. Lists tools used:
+    - `tool-a` — purpose
+    - `tool-b` — purpose
+
+## Example agent
+
+```yaml
+description: A brief description
+model: qwen4b
+toolsList:
+  - agent-name # this tool is a subagent
+```
+
+## Links
+
+Add a next page link. All internal links must be of this form:
+
+<a href="javascript:openLink('/plugins/overview')">Back: Overview</a>
+```
+
+## Rules
+
+- Keep it short and information-dense — match the style of `6.filesystem.md` and `8.search.md`
+- Use `<kbd>tool-name</kbd>` for all tools/agents
+- Use backticks `for tool names in prose
+- End with navigation link to overview (or next package if known)

package/dist/skills/execute-task-phase/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: execute-task-phase
+description: behavioral contract for executor agents in team tasks
+---
+
+# Executor Agent Contract
+
+## Your Role
+You are an **Executor Agent**. Execute your assigned phase independently.
+
+## Core Rules
+
+1. **Read ONLY your assigned phase file** — Do NOT read other phase files, `plan.md`, or `goals.md`
+2. **Execute steps sequentially** — Complete each step before moving to the next
+3. **Verify success criteria** — Each step must pass its criteria before proceeding
+4. **No regressions** — Run existing tests to ensure nothing breaks
+5. **Share context via documents** — Use `.agents/tasks/[task-name]/documents/` to create markdown files for subsequent agents
+
+## Reporting
+
+After completing your phase, report:
+- Summary of changes made
+- Steps completed successfully
+- Any issues encountered
+- Documents created (if any) in the `documents/` directory

package/dist/skills/execute-task-solo/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: execute-task-solo
+description: use this to execute a solo task (single agent executes all phases)
+---
+
+# Execute Task (Solo Mode)
+
+This skill describes how to execute a task created with `create-task-solo`. A single agent executes all phases sequentially.
+
+## Task Location
+
+Tasks are located in `.agents/tasks/[task-name]/` directory.
+
+## Task Structure
+
+```
+[task-name]/
+├── goals.md              # Goals and success criteria
+├── plan.md               # Full execution plan with all phases
+├── state.md              # Progress tracking
+└── notes.md              # Optional: additional context/notes
+```
+
+## Execution Workflow
+
+### 1. Start/Resume Task
+1. Read `state.md` to determine current progress
+2. Identify the next step to execute
+3. If status is `completed`, notify user and exit
+
+### 2. Execute Steps
+For each step:
+1. Read the step instructions from `plan.md`
+2. Perform the action (edit files, run commands, etc.)
+3. Verify success criteria
+4. If verification fails, fix issues and re-verify
+5. Once verified, mark step as complete in `state.md`
+
+### 3. Update State
+After completing each phase:
+1. Mark all steps in that phase as `[x]` with `✓`
+2. Mark the phase as `[x]`
+3. Update "Next" note to point to the next phase/step
+4. If all phases complete, set status to `completed`
+
+### 4. Completion
+1. When all phases are done, notify user
+2. Ask user to verify the results
+3. Only delete the task directory if user confirms everything is correct
+
+## State Management
+
+If the task is interrupted before completion, update `state.md` to indicate:
+- What was done
+- What remains to do
+- Current status (`in-progress`)
+
+## Important Rules
+
+- Always execute steps one by one — never skip ahead
+- Verify success criteria after each step before proceeding
+- Update `state.md` after each completed step
+- Do not verify previously completed steps (check `state.md` first)
+- Ask user for confirmation before deleting task directory

package/dist/skills/execute-task-team/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: execute-task-team
+description: use this to execute a team task (coordinator delegates phases to executor agents)
+---
+
+# Coordinator Agent Instructions (Task Execution)
+
+## Your Role
+You are the **Coordinator Agent**. Delegate phases to executor agents.
+
+Instruct subagents that they can use the `.agents/tasks/[task-name]/documents` directory to create markdown file that other agents will be able to read. Each agent must report what documents it created if it did, so that the next agent can be informed to read these documents if necessary
+
+## Execution Workflow
+
+1. Read `state.md` to identify next phase
+2. Delegate phase to an executor agent using the prompt template below
+3. Wait for completion, verify success criteria met
+4. Update `state.md` to mark phase completed
+5. Repeat until all phases done
+
+## Delegating to Executor Agents
+
+Use this prompt template:
+```
+You are an executor agent for the "[task-name]" task.
+
+Your assignment: Execute Phase X — [Phase Name]
+
+Instructions:
+1. Load the `execute-task-phase` skill for behavioral rules
+2. Read your phase file at: .agents/tasks/[task-name]/phases/phase-X.md
+3. Execute steps as specified in the phase file
+4. Report completion with summary and any documents created
+
+Important: Follow the executor contract — do NOT read other phase files.
+```
+
+## State Management
+After each phase: update `state.md` with progress, issues, and next phase.
+
+## Verification Rules
+- Each step must pass success criteria before moving on
+- All existing tests must continue passing (no regressions)
+- Final phase should verify overall targets are met
+
+## After Task Completion
+1. Ask user if everything is satisfactory
+2. Only delete task directory if user confirms
+3. If incomplete: update `state.md` with what was done and what remains

package/dist/skills/task-mode/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: task-mode
+description: use this to decide between solo (create-task-solo) or team (create-task-team) task execution mode
+---
+
+# Task Mode Selection
+
+This skill helps you choose the right execution mode before creating a task. Use it to determine whether to use `create-task-solo` (single agent) or `create-task-team` (coordinator-executor with multiple agents).
+
+## Quick Decision Checklist
+
+Evaluate the task against these criteria:
+
+### Solo Mode (`create-task-solo`) Indicators
+Check each that applies:
+- [ ] Task involves reading/analyzing lots of data to produce output
+- [ ] Phases are tightly coupled with shared state
+- [ ] Task complexity fits in one agent's context window
+- [ ] Quick iteration/refinement is needed
+- [ ] Same expertise required throughout all phases
+
+### Team Mode (`create-task-team`) Indicators
+Check each that applies:
+- [ ] Different phases require different expertise/domains
+- [ ] Phases are independent or parallelizable
+- [ ] Context isolation would improve output quality
+- [ ] Task is too large/complex for one agent's context
+- [ ] Long-running task that benefits from checkpointing between phases
+
+## Decision Rule
+
+| Score | Decision |
+|-------|----------|
+| 3+ solo indicators | Use **`create-task-solo`** (single agent) |
+| 3+ team indicators | Use **`create-task-team`** (multi-agent) |
+| Tie | Default to **`create-task-solo`** (simpler, less overhead) |
+
+## Key Principle: Context Isolation vs Unified Context
+
+### When Unified Context Wins (`create-task-solo`)
+> "Read all docs and create a summary" — The agent needs to hold all the data in context to produce coherent output. Splitting this across agents would lose the unified view.
+
+**Use `create-task-solo` when:** The task benefits from having all information available in one context window. Reading → Processing → Output flows work best with a single agent.
+
+### When Context Isolation Wins (`create-task-team`)
+> "Create module with tests, docs, and integration" — Each phase needs focused expertise. Isolating context prevents interference between phases and lets each agent specialize.
+
+**Use `create-task-team` when:** Different phases benefit from separate, focused contexts. Multi-agent execution prevents context pollution and allows specialization.
+
+## Decision Flow
+
+```
+Task Analysis
+ │
+ ├─→ Need to read/analyze lots of data → produce output?
+ │    └─ YES → create-task-solo (unified context)
+ │
+ ├─→ Phases tightly coupled with shared state?
+ │    └─ YES → create-task-solo (keep context together)
+ │
+ ├─→ Different phases need different expertise?
+ │    └─ YES → create-task-team (context isolation helps)
+ │
+ ├─→ Task too complex for one context window?
+ │    └─ YES → create-task-team (split across agents)
+ │
+ ├─→ Phases independent/parallelizable?
+ │    └─ YES → create-task-team (leverage isolation)
+ │
+ └─→ Default → create-task-solo (simpler, less overhead)
+```
+
+## Examples
+
+### Use `create-task-solo` (Single Agent):
+- "Read all documentation files and create a summary"
+- "Analyze codebase metrics and generate a report"
+- "Refactor function X across the project"
+- "Add feature Y to existing module"
+- "Update configuration based on new requirements"
+- "Generate documentation from code comments"
+
+### Use `create-task-team` (Multi-Agent):
+- "Create new module with tests, docs, and integration"
+- "Migrate database schema, update queries, update API"
+- "Implement feature requiring frontend + backend + tests"
+- "Large refactoring across multiple unrelated modules"
+- "Build new service with API, CLI, and documentation"
+- "Add authentication: update backend, frontend, and tests"
+
+## Output Format
+
+When using this skill, output your decision as:
+
+```
+Task Mode Decision: [create-task-solo | create-task-team]
+Reasoning: [Brief explanation based on checklist]
+Next Step: Use the `create-task-solo` or `create-task-team` skill to create the task
+```

package/dist/skills/update-codebase-summary/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: update-codebase-summary
+description: use when asked to create or update the codebase summary documentation
+---
+
+This skill describes the workflow to create or update a codebase documentation file (`[project-path].agents/documentation/codebase-summary.md`).
+
+## Workflow
+
+1. **Explore the project** — Walk the directory tree, identify package/module boundaries, read manifest files (e.g., `package.json`), locate entry points, and understand inter-module dependencies.
+
+2. **Check for existing file** — Look for `[project-path].agents/documentation/codebase-summary.md` in the project directory. If it exists, update it. If not, create it.
+
+3. **Write the file** using exactly these 7 sections in this order:
+
+### Section Format
+
+# <module-name>
+
+## Summary
+One sentence: what the module does and why it exists.
+
+## Dependencies
+- `<dep-module>` — key types, functions, or services used
+- External: `<library>` (<purpose>)
+
+## Used By
+- `<consumer-module>` — why it uses this module
+
+## Entry Point
+- `<path>` — one-line description of what it exports or provides
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| `<src/path>` | One-line: what the file does conceptually |
+
+## Architecture
+- 2–4 bullet points on main design patterns and data flow.
+
+## Related
+- See `<related-module>` — how they work together
+
+Keep the file as short and condensed as possible

package/dist/skills/update-doc-map/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: update-doc-map
+description: read this only when instructed to update the documentation map
+---
+
+Run the `agent-smith-plugins/agents/dist/skills/update-doc-map/scripts/generate-doc-map.mjs` Nodejs script.
+
+Report only the end result: if the script has run ok or not.

package/dist/skills/update-doc-map/scripts/generate-doc-map.mjs

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+/**
+ * generate-doc-map.mjs
+ * 
+ * Scans the project for all documentation files and generates a doc-map.md
+ * file that helps AI agents navigate the codebase documentation.
+ */
+
+import { readdir, stat, writeFile } from 'node:fs/promises';
+import { join, relative, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// The script is in .agents/, so the project root is one level up
+// Accept PROJECT_ROOT from command line argument or environment variable, otherwise calculate
+const PROJECT_ROOT = process.argv[2] || process.env.PROJECT_ROOT || join(__dirname, '../../../../..');
+
+// Packages that have their own .agents/documentation
+const PACKAGES = [
+  'core', 'agent', 'cli', 'wscli', 'types', 'smem', 'tmem', 'server'
+];
+
+/**
+ * Recursively find all markdown files in a directory
+ */
+async function findMarkdownFiles(dir, baseDir) {
+  const files = [];
+  try {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(dir, entry.name);
+      if (entry.isDirectory()) {
+        // Skip node_modules and other non-doc directories
+        if (!['node_modules', '.git', 'dist', 'build', '__pycache__'].includes(entry.name)) {
+          files.push(...await findMarkdownFiles(fullPath, baseDir));
+        }
+      } else if (entry.isFile() && entry.name.endsWith('.md')) {
+        const relPath = relative(baseDir, fullPath);
+        files.push({ path: fullPath, relative: relPath });
+      }
+    }
+  } catch (err) {
+    // Skip directories we can't read
+  }
+  return files;
+}
+
+/**
+ * Extract a human-readable title from the filename
+ */
+function extractTitle(fileRelative) {
+  const parts = fileRelative.split('/');
+  const filename = basename(fileRelative, '.md');
+
+  // Try to get a better name from the path segments
+  if (parts.length > 1) {
+    return parts.slice(0, -1).join('/') + '/' + filename;
+  }
+  return filename;
+}
+
+/**
+ * Format a file path for display and linking using full workspace-relative path
+ */
+function formatLink(fileRelative, basePath) {
+  // Return full path from workspace root with .md extension preserved
+  return `${basePath}/${fileRelative}`;
+}
+
+/**
+ * Generate the documentation map markdown content
+ */
+async function generateDocMap() {
+  const docSections = [];
+
+  // Scan public documentation (docsite/public/doc)
+  const publicDocPath = join(PROJECT_ROOT, 'docsite/public/doc');
+  try {
+    await stat(publicDocPath);
+    const files = await findMarkdownFiles(publicDocPath, publicDocPath);
+
+    if (files.length > 0) {
+      // Group by top-level category
+      const grouped = {};
+      for (const file of files) {
+        const parts = file.relative.split('/');
+        const category = parts[0] || 'root';
+        if (!grouped[category]) grouped[category] = [];
+        grouped[category].push(file);
+      }
+
+      docSections.push({
+        title: '📚 Public Documentation',
+        description: 'Main project documentation hosted in the docsite.',
+        files: grouped,
+        basePath: 'docsite/public/doc'
+      });
+    }
+  } catch (err) {
+    // Skip if directory doesn't exist
+  }
+
+  // Scan root .agents/documentation
+  const rootAgentsPath = join(PROJECT_ROOT, '.agents/documentation');
+  try {
+    await stat(rootAgentsPath);
+    const files = await findMarkdownFiles(rootAgentsPath, rootAgentsPath);
+
+    if (files.length > 0) {
+      docSections.push({
+        title: '🤖 Root Agent Documentation',
+        description: 'Documentation for the agent system itself.',
+        files: { '': files },
+        basePath: '.agents'
+      });
+    }
+  } catch (err) {
+    // Skip if directory doesn't exist
+  }
+
+  // Scan each package's .agents/documentation
+  for (const pkg of PACKAGES) {
+    const pkgAgentsPath = join(PROJECT_ROOT, `packages/${pkg}/.agents/documentation`);
+    try {
+      await stat(pkgAgentsPath);
+      const files = await findMarkdownFiles(pkgAgentsPath, pkgAgentsPath);
+
+      if (files.length > 0) {
+        docSections.push({
+          title: `📦 Package: @agent-smith/${pkg}`,
+          description: `Documentation for the ${pkg} package.`,
+          files: { '': files },
+          basePath: `packages/${pkg}/.agents`
+        });
+      }
+    } catch (err) {
+      // Skip if directory doesn't exist or has no docs
+    }
+  }
+
+  // Generate the markdown content - compact format for AI agents
+  const lines = [
+    '# 🗺️ Documentation Map',
+    '',
+  ];
+
+  // Detailed sections only (no summary table, no horizontal rules)
+  for (const section of docSections) {
+    lines.push(`## ${section.title}`);
+    lines.push('');
+
+    for (const [category, files] of Object.entries(section.files)) {
+      if (files.length === 0) continue;
+
+      if (category) {
+        lines.push(`### ${category}`);
+        lines.push('');
+      }
+
+      // Sort files: files starting with numbers come first, then alphabetical
+      const sortedFiles = [...files].sort((a, b) => {
+        const aName = basename(a.relative, '.md');
+        const bName = basename(b.relative, '.md');
+        return aName.localeCompare(bName, undefined, { numeric: true });
+      });
+
+      for (const file of sortedFiles) {
+        const fullPath = formatLink(file.relative, section.basePath);
+        const workspacePath = `agent-smith/${fullPath}`;
+        lines.push(`- [\`${workspacePath}\`](${workspacePath})`);
+      }
+
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// Main execution
+async function main() {
+  console.log('🔍 Scanning for documentation files...');
+
+  const content = await generateDocMap();
+  const outputPath = join(PROJECT_ROOT, '.agents/documentation/documentation-map.md');
+
+  // Write the file
+  await writeFile(outputPath, content, 'utf-8');
+
+  console.log(`✅ Documentation map generated: ${outputPath}`);
+}
+
+main().catch(err => {
+  console.error('❌ Error generating doc-map:', err);
+  process.exit(1);
+});