tasq/node_modules/agentic-flow/docs/architecture/PACKAGE_STRUCTURE.md

agentic-flow Package Structure

Overview

The agentic-flow npm package includes all necessary files for agent execution, including 76 pre-built agent definitions in the .claude/agents/ directory.

Package Contents

When you install agentic-flow via npm, you get:

agentic-flow/
├── dist/                    # Compiled JavaScript
│   ├── cli-proxy.js         # Main CLI entry point
│   ├── agents/              # Agent implementations
│   ├── router/              # Multi-provider router
│   └── utils/               # Utilities
├── .claude/                 # Agent definitions (76 files)
│   └── agents/
│       ├── core/            # Core agents (coder, planner, reviewer, etc.)
│       ├── consensus/       # Distributed consensus agents
│       ├── github/          # GitHub integration agents
│       ├── flow-nexus/      # Flow Nexus cloud agents
│       ├── sparc/           # SPARC methodology agents
│       └── ...              # More specialized categories
├── docs/                    # Documentation
├── README.md
└── LICENSE

Agent Loading System

Package Agents (Bundled)

All 76 agent definitions are included in the npm package at:

node_modules/agentic-flow/.claude/agents/

These are automatically loaded when you run npx agentic-flow.

Local Agents (User Custom)

You can create custom agents in your project:

your-project/
└── .claude/
    └── agents/
        └── custom/
            └── my-agent.md

Local agents override package agents with the same relative path.

Agent Discovery Order

1. Package agents: Load from node_modules/agentic-flow/.claude/agents/
2. Local agents: Load from ./claude/agents/ (overrides package agents if same path)
3. Custom directory: Use --agents-dir flag to specify alternative location

Verification

To verify your installation includes all agents:

# List all available agents
npx agentic-flow --list

# Should show 73 agents (76 files, some without proper frontmatter)

Custom Agent Creation

Create custom agents that augment or replace package agents:

# Interactive creation
npx agentic-flow agent create

# Manual creation
mkdir -p .claude/agents/custom
cat > .claude/agents/custom/my-agent.md << 'EOF'
---
name: my-agent
description: My custom agent
---

You are a specialized agent for [purpose].
Follow these guidelines:
- [guideline 1]
- [guideline 2]
EOF

Package Maintenance

Building

npm run build

Verifying Package Structure

./scripts/verify-package.sh

Creating Package

npm pack

Testing Installation

# Install in test directory
mkdir -p /tmp/test-install
cd /tmp/test-install
npm install /path/to/agentic-flow-1.1.2.tgz

# Verify agents loaded
./node_modules/.bin/agentic-flow --list

Environment Configuration

The package automatically loads .env files from:

1. Current directory
2. Parent directories (recursively up to root)

This ensures API keys work from any directory:

# Works from project root
cd /workspaces/myproject
npx agentic-flow --agent coder --task "test" --provider gemini

# Also works from subdirectory (finds parent .env)
cd /workspaces/myproject/src
npx agentic-flow --agent coder --task "test" --provider gemini

Files Included in Package

See package.json:

{
  "files": [
    "dist",
    "docs",
    ".claude",
    "README.md",
    "LICENSE"
  ]
}

Files Excluded (.npmignore)

• Source files (src/, *.ts)
• Tests (tests/, validation/)
• Development files (.env, tsconfig.json)
• Runtime state directories (.claude-flow/, .swarm/, memory/)
• ONNX models (*.onnx, models/)

Agent Categories

The 76 included agents span:

• Core (5): coder, planner, researcher, reviewer, tester
• Consensus (7): Byzantine, CRDT, Gossip, Raft, Quorum, etc.
• GitHub (14): PR management, issue tracking, release automation
• Flow Nexus (9): Cloud sandboxes, neural networks, workflows
• SPARC (4): Specification, Pseudocode, Architecture, Refinement
• Optimization (5): Resource allocation, load balancing, benchmarks
• Goal Planning (2): GOAP, sublinear algorithms
• Swarm (3): Hierarchical, mesh, adaptive coordination
• Payments (1): Agentic payment authorization
• Templates (10): Automation, orchestration, migration
• Testing (2): TDD, production validation
• Specialized (varies): Analysis, architecture, data, development, DevOps, documentation

Total Agent Count

• 76 agent files in .claude/agents/
• 73 valid agents (3 files missing required frontmatter)
• All core agents (coder, planner, researcher, reviewer, tester) working

Summary

✅ All 76 agent definitions are packaged and distributed via npm ✅ Agent loading works automatically from node_modules/ ✅ Local .claude/agents/ can override package agents ✅ Environment variable loading works recursively ✅ Package structure verified and tested

The .claude/ directory is a first-class part of the npm package, ensuring all users have immediate access to the complete agent library upon installation.