npm package: @kartick.ns/claude-agents
Description: Enterprise AI development fleet for Claude Code. Build autonomous teams with specialized agents, skills, hooks, and workflows.
Author: kartick.ns
Latest version: 2.0.0

# Claude Code: Enterprise AI Development Fleet

[![npm version](https://badge.fury.io/js/@kartick.ns%2Fclaude-agents.svg)](https://www.npmjs.com/package/@kartick.ns/claude-agents)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> Build autonomous AI development teams with specialized agents, skills, and workflows.

Inspired by:
- [AgentField](https://github.com/Agent-Field/agentfield) - "Kubernetes for AI Agents" architecture
- [Shotgun](https://github.com/shotgun-sh/shotgun) - Spec-driven development (5-phase pipeline)
- [Claude Code Skill Factory](https://github.com/alirezarezvani/claude-code-skill-factory) - Factory patterns for generating skills/agents

## Quick Start

```bash
# Basic installation (agents only)
npx @kartick.ns/claude-agents init

# Full installation (agents + skills + hooks + rules + memory)
npx @kartick.ns/claude-agents init --full

# Enterprise installation (everything + enterprise settings)
npx @kartick.ns/claude-agents init --enterprise
```

## What's Included

### Agents (12 Specialized Subagents)

| Agent | Model | Purpose |
|-------|-------|---------|
| `code-reviewer` | sonnet | Proactive code quality review |
| `security-auditor` | opus | Vulnerability detection (proactive) |
| `debugger` | opus | Bug investigation and fixes |
| `test-engineer` | sonnet | Test creation and coverage |
| `architect` | opus | System design and planning |
| `feature-builder` | sonnet | Feature implementation |
| `api-developer` | sonnet | REST/GraphQL API development |
| `refactorer` | sonnet | Code improvement |
| `performance-analyst` | sonnet | Performance optimization |
| `codebase-explorer` | haiku | Code understanding |
| `doc-writer` | sonnet | Technical documentation |
| `git-operator` | haiku | Version control operations |

### Skills (16 Workflow Commands)

| Skill | Purpose |
|-------|---------|
| `/specify` | Create codebase-aware specs (5-phase: Research→Specify→Plan→Tasks→Export) |
| `/plan` | Design implementation plans |
| `/implement` | Execute plans task by task |
| `/validate` | Verify against specifications |
| `/review` | Comprehensive code review |
| `/debug` | Systematic debugging |
| `/orchestrate` | Multi-agent coordination |
| `/ralph-loop` | Autonomous iteration pattern |
| `/tdd` | Test-driven development |
| `/explore` | Deep codebase exploration |
| `/manual-qa` | Manual QA testing (Playwright MCP for web, Mobile MCP for mobile) |
| `/automation-qa` | E2E automation testing (Playwright/Detox/Maestro) |
| `/skill-factory` | Generate new skills through guided Q&A |
| `/agent-factory` | Generate new agents through guided Q&A |
| `/hook-factory` | Generate new hooks through guided Q&A |
| `/export` | Export specs to AGENTS.md, Cursor rules, or other formats |

### Hooks (9 Automation Scripts)

| Hook | Event | Purpose |
|------|-------|---------|
| `detect-secrets` | PreToolUse | Block credential exposure |
| `validate-command` | PreToolUse | Prevent dangerous commands |
| `validate-file-path` | PreToolUse | Block path traversal |
| `auto-format` | PostToolUse | Auto-format after edits |
| `run-lint` | PostToolUse | Run linter on changes |
| `update-progress` | Stop | Track progress |
| `log-agent-completion` | SubagentStop | Log agent work |
| `load-env` | SessionStart | Load environment |
| `save-session-summary` | SessionEnd | Create session summary |

### Rules (5 Path-Specific Standards)

| Rule | Applies To |
|------|------------|
| `api` | `src/api/**/*`, `src/routes/**/*` |
| `tests` | `**/*.test.ts`, `test/**/*` |
| `components` | `src/components/**/*` |
| `database` | `src/db/**/*`, `prisma/**/*` |
| `security` | `src/auth/**/*`, `**/*password*` |

### Memory Bank

Persistent context across sessions:
- `progress.md` - Task tracking
- `decisions.md` - Architectural decisions
- `patterns.md` - Code patterns
- `issues.md` - Known issues
- `glossary.md` - Project terminology

## Installation Options

```bash
# Install everything
npx @kartick.ns/claude-agents init --enterprise

# Install specific components
npx @kartick.ns/claude-agents init --with-skills --with-hooks

# Install specific team
npx @kartick.ns/claude-agents team full-stack

# Add specific agents
npx @kartick.ns/claude-agents add code-reviewer security-auditor
```

### CLI Commands

| Command | Description |
|---------|-------------|
| `init` | Initialize agents (+ optional components) |
| `add <agents...>` | Add specific agents |
| `team <name>` | Install pre-configured team |
| `list` | List available agents/teams |
| `update` | Update to latest version |
| `validate` | Validate installed files |

### Init Options

| Option | Description |
|--------|-------------|
| `--full` | Install agents, skills, hooks, rules, memory |
| `--enterprise` | Full + enterprise settings and MCP |
| `--with-skills` | Install workflow skills |
| `--with-hooks` | Install hook scripts |
| `--with-rules` | Install path-specific rules |
| `--with-memory` | Install memory bank templates |
| `--with-mcp` | Install MCP configuration |
| `--with-settings` | Install settings.json |

## Pre-Built Teams

### Essential (3 agents)
For solo developers and quick prototypes.
```bash
npx @kartick.ns/claude-agents team essential
```

### Full-Stack (7 agents)
For web application development.
```bash
npx @kartick.ns/claude-agents team full-stack
```

### Security (6 agents)
For security-sensitive applications.
```bash
npx @kartick.ns/claude-agents team security
```

### Enterprise (12 agents)
Complete coverage for enterprise development.
```bash
npx @kartick.ns/claude-agents team enterprise
```

## Workflow: Spec-Driven Development

```
/specify → /plan → /implement → /validate
```

1. **Specify**: Create requirements specification
2. **Plan**: Design implementation approach
3. **Implement**: Execute the plan
4. **Validate**: Verify against acceptance criteria

## Workflow: Ralph Loop (Autonomous Iteration)

For complex tasks requiring multiple iterations:

```bash
# Start the loop
/ralph-loop "Migrate all API endpoints to Hono"
```

Progress tracked in git history and `.claude/memory/ralph-progress.md`.

## Project Structure After Installation

```
your-project/
├── .claude/
│   ├── agents/           # Agent definitions
│   │   ├── code-reviewer.md
│   │   ├── debugger.md
│   │   └── ...
│   ├── skills/           # Workflow skills
│   │   ├── specify/SKILL.md
│   │   ├── plan/SKILL.md
│   │   └── ...
│   ├── rules/            # Path-specific rules
│   │   ├── api.md
│   │   ├── tests.md
│   │   └── ...
│   ├── memory/           # Persistent context
│   │   ├── progress.md
│   │   ├── decisions.md
│   │   └── ...
│   └── settings.json     # Hooks and permissions
├── hooks/                # Hook scripts
│   ├── auto-format.sh
│   ├── detect-secrets.sh
│   └── ...
└── .mcp.json             # MCP server configuration
```

## Configuration

### Settings (.claude/settings.json)

```json
{
  "permissions": {
    "allow": ["Bash(npm:*)", "Read(*)", "Glob(*)"],
    "deny": ["Bash(rm -rf:*)"]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {"type": "command", "command": "$CLAUDE_PROJECT_DIR/hooks/detect-secrets.sh"}
        ]
      }
    ]
  }
}
```

### MCP Servers (.mcp.json)

```json
{
  "mcpServers": {
    "github": {
      "type": "http",
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": {"Authorization": "Bearer ${GITHUB_TOKEN}"}
    },
    "postgres": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"POSTGRES_URL": "${DATABASE_URL}"}
    }
  }
}
```

## Agent File Format

```markdown
---
name: agent-name
description: |
  When to use this agent. Claude reads this for delegation.
tools: Read, Grep, Glob, Bash
model: sonnet
---

# System prompt content

## When Invoked
1. Step 1
2. Step 2

## Output Format
...
```

## Skill File Format

```markdown
---
name: skill-name
description: What this skill does
allowed-tools: Read, Grep, Glob
context: fork
model: sonnet
---

# Instructions for the skill
```

## Resources

- [Claude Code Documentation](https://code.claude.com/docs/)
- [Multi-Agent Orchestration Guide](./MULTI_AGENT_ORCHESTRATION.md)

## License

MIT