Agentic System

A multi-agent orchestration system for planning, speccing, and building software using Claude Code agents.

Overview

The Agentic System provides a structured workflow for software development through specialized AI agents:

Planning Stage: PM → OpenSpec Specialist → Efficiency Engineer → Task Manager → Database Setup
Development Stage: Junior Dev → Senior Dev → QA Dev → Doc Agent (with smart parallelization)

Features

11 Specialized Agents for different aspects of development
SQLite Database for task tracking and documentation
OpenSpec Integration for structured planning
Smart Parallelization of independent tasks
Backend-First Enforcement to prevent architectural issues
Hierarchical Task System with human-readable numbering (1, 1.1, 1.2.3)
Interactive Setup Scripts for easy initialization

Prerequisites

Before using the Agentic System, ensure you have:

SQLite3 - Database engine

# Check if installed
sqlite3 --version

# Install on Ubuntu/Debian
sudo apt-get install sqlite3

# Install on macOS
brew install sqlite3

Node.js and npm - For OpenSpec integration (optional but recommended)
```
node --version  # Should be v18 or higher
npm --version
```
OpenSpec - For structured planning (optional)
```
npm install -g @fission-ai/openspec
```
Claude Code - The AI-powered CLI tool
- Must be installed and configured

Installation

One-Liner Install (Recommended)

Linux/Mac:

bash <(curl -fsSL https://raw.githubusercontent.com/Xananthium/Claude-Code-Agents-OSS/master/setup.sh)

Windows (PowerShell):

iwr -useb https://raw.githubusercontent.com/Xananthium/Claude-Code-Agents-OSS/master/setup.bat | iex

Manual Install

Clone the repository:

git clone https://github.com/Xananthium/Claude-Code-Agents-OSS.git
cd Claude-Code-Agents-OSS

Run the setup script:

Linux/Mac:
```
chmod +x setup.sh
./setup.sh
```
Windows:
```
setup.bat
```
The setup script will:
- Prompt you to create a new project or use an existing one
- Create the .claude/agents/ directory structure
- Copy all agent definitions
- Initialize the SQLite database
- Set up the agentic/ directory structure
- Initialize OpenSpec (if installed)

Project Structure

After setup, your project will have this structure:

my-project/
├── .claude/
│   └── agents/              # Agent definitions
│       ├── orchestrator.md
│       ├── project-manager.md
│       ├── openspec-specialist.md
│       ├── karla-fant.md
│       ├── task-manager.md
│       ├── database-manager.md
│       ├── junior-dev.md
│       ├── senior-dev.md
│       ├── qa-dev.md
│       ├── doc-agent.md
│       └── database-agent.md
├── agentic/
│   ├── planning/            # Temporary, cleaned after iteration
│   │   ├── openspec/        # OpenSpec artifacts
│   │   ├── pmdraft.md       # PM's draft plan
│   │   ├── ossplan.md       # OpenSpec Specialist's plan
│   │   └── tasks.md         # Final task breakdown
│   ├── db/
│   │   └── agentic.db       # SQLite database
│   ├── archive/             # Completed iterations
│   └── requirements.md      # Project requirements
└── [your project files]

Usage

Starting a New Project

Navigate to your project directory:
```
cd my-project
```
Start the Orchestrator agent:
```
claude-code --agent orchestrator
```
Provide your project idea:
- The Orchestrator will coordinate with other agents
- PM will ask clarifying questions
- OpenSpec Specialist will validate the plan
- Efficiency Engineer will review for performance
- Task Manager will break down into implementable tasks
Development begins automatically:
- Tasks are executed in dependency order
- Independent tasks run in parallel
- Progress is tracked in the database

Checking Progress

Query the database directly:

sqlite3 agentic/db/agentic.db "SELECT task_number, description, status FROM tasks ORDER BY id;"

Or view the task hierarchy:

sqlite3 agentic/db/agentic.db << EOF
WITH RECURSIVE task_tree AS (
  SELECT id, parent_id, task_number, description, status, 0 as level
  FROM tasks
  WHERE parent_id IS NULL

  UNION ALL

  SELECT t.id, t.parent_id, t.task_number, t.description, t.status, tt.level + 1
  FROM tasks t
  JOIN task_tree tt ON t.parent_id = tt.id
)
SELECT
  printf('%s%s %s (%s)',
    substr('    ', 1, level * 2),
    task_number,
    description,
    status
  ) as task
FROM task_tree
ORDER BY task_number;
EOF

Agent Roles

Planning Stage

Orchestrator - Main coordinator, never touches code
Project Manager (PM) - Asks questions, presents framework options, writes pmdraft.md
OpenSpec Specialist - Reviews for clarity, identifies blockers (API keys, credentials)
Karla Fant (Efficiency Engineer) - Reviews for performance (caching, incremental fetching)
Task Manager - Breaks down into <100k token tasks, maintains related functions together
Database Manager - Sets up SQLite database from tasks.md, enforces backend-first rule

Development Stage

Junior Dev - Pulls task dependencies from database, formats context for Senior Dev
Senior Dev - Implements production-ready code (no stubs, full error handling)
QA Dev - Tests implementation, validates against specs, catches vulnerabilities
Doc Agent - Extracts function signatures and summaries
Database Agent - ONLY agent touching database during development (queries, updates, commits)

Key Principles

Backend-First Development

The system enforces backend completion before frontend work:

All frontend tasks automatically depend on backend completion
Database Manager validates this rule during setup
Prevents architectural issues and wasted effort

Smart Parallelization

The Database Agent analyzes task dependencies to:

Execute independent tasks concurrently
Avoid file conflicts
Optimize development speed

Production-Ready Code Only

Following CLAUDE.md principles:

No stub functions or placeholders
Complete error handling
Full validation at boundaries
No TODO comments for "implement later"

No Assumptions

When multiple approaches exist:

PM presents options with pros/cons
User makes informed decisions
Clear communication of trade-offs

Database Schema

TASKS Table

Tracks all tasks with hierarchical relationships:

id - Integer primary key
parent_id - Foreign key to parent task
task_number - Display format (1, 1.1, 1.2.3)
description - Detailed task description
status - pending | in_progress | completed | blocked
assigned_to - Current agent working on task
order_index - Sibling ordering

DOCS Table

Stores function documentation:

declaration - Function signature
summary - Returns, expects, DB transformations
file_path - Implementation location
task_id - Associated task

Task Dependencies

Enables smart parallelization:

Tracks which tasks depend on others
Prevents circular dependencies
Enables dependency graph analysis

OpenSpec Integration

The system uses a hybrid approach:

Planning Phase: OpenSpec for structured proposals and specs
Execution Phase: SQLite database for real-time tracking
Synchronization: Bi-directional updates between OpenSpec and database

OpenSpec artifacts are stored in agentic/planning/openspec/ and cleaned up after iteration completion.

Archiving Iterations

After completing an iteration:

# The Orchestrator will prompt for archiving
# Creates: agentic/archive/YYYY-MM-DD-iteration-name/
# - Exports tasks to JSON
# - Exports docs to JSON
# - Copies planning/ directory
# - Cleans up temporary files

This ensures:

No duplicate artifacts between iterations
Full history preserved
Clean slate for next iteration

Troubleshooting

SQLite Database Issues

Database locked:

# Close any open connections
lsof agentic/db/agentic.db
kill <PID>

Corrupted database:

# Backup first
cp agentic/db/agentic.db agentic/db/agentic.db.backup

# Rebuild from archive
sqlite3 agentic/db/agentic.db < templates/schema.sql
# Then manually import from archive JSON

Agent Communication Issues

Agent not responding:

Check .claude/agents/ directory exists
Verify agent file has correct YAML frontmatter
Check Claude Code is properly installed

Planning artifacts not created:

Ensure agentic/planning/ directory exists
Check write permissions
Verify OpenSpec is installed (if using)

Task Execution Issues

Tasks stuck in pending:

# Check for circular dependencies
sqlite3 agentic/db/agentic.db "
SELECT t1.task_number, t2.task_number
FROM task_dependencies td
JOIN tasks t1 ON td.task_id = t1.id
JOIN tasks t2 ON td.depends_on_task_id = t2.id;
"

Backend-first violation:

Database Manager will reject invalid task breakdowns
Ensure all frontend tasks depend on backend completion

Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch
Follow the coding principles in CLAUDE.md
Test your changes thoroughly
Submit a pull request

License

[Choose appropriate license - MIT, Apache 2.0, etc.]

Acknowledgments

Karla Fant - Efficiency engineer role inspired by LANL computer scientist
OpenSpec - Structured planning framework by Fission AI
Claude Code - AI-powered development assistant by Anthropic

Support

For issues, questions, or suggestions:

GitHub Issues: [repository URL]/issues
Documentation: [repository URL]/wiki

Version: 1.0.0 Last Updated: January 2025

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
agents		agents
templates		templates
.gitignore		.gitignore
LICENSE		LICENSE
ORCHESTRATOR.md		ORCHESTRATOR.md
QUICKSTART.md		QUICKSTART.md
README.md		README.md
package.json		package.json
setup.bat		setup.bat
setup.sh		setup.sh

Folders and files

Latest commit

History

Repository files navigation