npm package: @jcmrs/claude-agent-os
Description: AI-powered product development assistant with conversational design and spec-driven workflows
Author: Claude-Agent-OS Contributors
Latest version: 0.1.0

# Claude-Agent-OS

**AI-powered product development assistant with conversational planning and spec-driven workflows**

Version 0.1.0 (Development) | [Installation](#installation) | [Features](#features) | [GitHub](https://github.com/jcmrs/claude-agent-os)

---

## What is Claude-Agent-OS?

Claude-Agent-OS combines two powerful systems for AI-assisted software development:

1. **PDA (Product Design Assistant)**: Conversational interface for brainstorming product ideas, refining concepts, and generating comprehensive product documentation through natural dialogue
2. **Agent-OS Workflows**: Spec-driven development system with structured workflows for planning, specification, and implementation

### Key Features

- **Conversational Product Design**: Natural dialogue with specialist AI agents (strategy, research, design, technical)
- **Knowledge Accumulation**: Builds understanding of your product across conversation turns
- **Document Generation**: Automatically creates PRDs, user stories, research reports, design specs
- **Spec-Driven Workflows**: Structured `plan-product`, `new-spec`, `create-spec`, `implement-spec` workflows
- **Multi-Agent Orchestration**: Coordinate specialized agents for complex tasks
- **100% Test Coverage**: 602 passing tests across all systems
- **Production-Ready**: CLI, Claude API integration, configuration management

---

## Installation

### Development Installation

```bash
# Clone the repository
git clone https://github.com/jcmrs/claude-agent-os.git
cd claude-agent-os

# Install dependencies
npm install

# Build the project
npm run build

# Set up environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY
```

### Configuration

Create a `.env` file in the project root:

```env
# Required: Your Anthropic API key
ANTHROPIC_API_KEY=your_api_key_here

# Optional: Override default model (default: claude-sonnet-4)
# ANTHROPIC_MODEL=claude-sonnet-4
```

Get your API key from [Anthropic Console](https://console.anthropic.com/)

---

## Usage

### CLI Commands

```bash
# View available commands
node dist/cli/index.cjs --help

# Initialize project structure
node dist/cli/index.cjs init

# Check system health
node dist/cli/index.cjs doctor

# View project status
node dist/cli/index.cjs status

# List available workflows
node dist/cli/index.cjs list
```

### Workflow Commands

```bash
# Plan a product (creates mission, roadmap, tech stack)
node dist/cli/index.cjs plan-product

# Initialize new feature spec
node dist/cli/index.cjs new-spec "user authentication"

# Create detailed specification
node dist/cli/index.cjs create-spec agent-os/specs/2025-01-10-auth

# Implement specification
node dist/cli/index.cjs implement-spec agent-os/specs/2025-01-10-auth
```

### PDA (Product Design Assistant)

The PDA provides conversational product design through specialized AI agents:

```typescript
import { Orchestrator, SessionManager, KnowledgeBase, /* ... */ } from '@claude/agent-os';

// Create PDA session
const sessionManager = new SessionManager('./sessions');
const session = await sessionManager.createSession('My Product Idea');

// Have conversation with specialist agents
const response = await orchestrator.processTurn(
  session.id,
  "I want to build a task management app for remote teams"
);

// Generate documents from accumulated knowledge
const prd = await orchestrator.generateDocument(session.id, 'PRD');
const userStories = await orchestrator.generateDocument(session.id, 'UserStories');
```

---

---

## Architecture

### Dual System Design

Claude-Agent-OS integrates two complementary systems:

**PDA (Product Design Assistant)**
- Conversational interface for product ideation and refinement
- Specialist AI agents: Strategy, Research, Design, Technical
- Knowledge accumulation across conversation turns
- Document generation: PRDs, user stories, research reports, design specs
- Session management for persistent conversations

**Agent-OS Workflows**
- Spec-driven development methodology
- Structured workflows: plan-product, new-spec, create-spec, implement-spec
- Multi-agent orchestration for complex tasks
- Integration with Claude API via @anthropic-ai/claude-agent-sdk

### Project Structure

```
claude-agent-os/
├── src/
│   ├── cli/                    # CLI commands and utilities
│   ├── pda/                    # Product Design Assistant
│   │   ├── core/              # Session, Knowledge Base, Orchestrator
│   │   ├── agents/            # Specialist agents (Strategy, Research, etc.)
│   │   ├── documents/         # Document generators (PRD, UserStories, etc.)
│   │   └── prompts/           # AI prompts and templates
│   ├── agent-os/              # Spec-driven workflow system
│   │   ├── commands/          # Workflow commands (plan-product, etc.)
│   │   ├── planning/          # Product planning workflows
│   │   ├── spec/              # Specification workflows
│   │   └── workflows/         # Core workflow engine
│   ├── orchestration/         # Multi-agent orchestration layer
│   ├── types/                 # TypeScript type definitions
│   └── utils/                 # Shared utilities
├── dist/                      # Built output (CommonJS)
├── package.json
└── .env                       # Configuration (ANTHROPIC_API_KEY)
```

### Testing

**100% Test Coverage** - 602 passing tests across 27 test files:
- Unit tests for all core components
- Integration tests for PDA and workflows
- End-to-end workflow tests
- Template and configuration validation

Run tests: `npm test`

---

## Requirements

- **Node.js**: 20.0.0+ required
- **Anthropic API Key**: Required for Claude integration ([Get API key](https://console.anthropic.com/))
- **npm**: Required for dependency management
- **Git**: Optional, for version control operations

---

## Development

### Build Commands

```bash
npm run build         # Build TypeScript to dist/
npm run dev           # Watch mode for development
npm run typecheck     # TypeScript type checking
npm run lint          # ESLint checks
npm run format        # Prettier formatting
```

### Testing

```bash
npm test                    # Run all 602 tests
npm run test:coverage       # Run tests with coverage report
```

**Current Status**: 602/602 tests passing (100% coverage)
- 27 test files covering all core systems
- Unit tests for PDA, Agent-OS, orchestration
- Integration tests for workflows
- End-to-end workflow validation

---

## Version History

### v0.1.0 (Current - Development)

**Development Release** - Not yet published to npm

**Implemented Features**:
- ✅ **PDA System**: Complete conversational product design assistant
  - Session management with persistent conversations
  - Specialist AI agents (Strategy, Research, Design, Technical)
  - Knowledge accumulation across conversation turns
  - Document generators (PRD, User Stories, Research Reports, Design Specs)
  - Intent extraction and agent selection
- ✅ **Agent-OS Workflows**: Spec-driven development system
  - Product planning workflows (mission, roadmap, tech stack)
  - Specification workflows (new-spec, create-spec, implement-spec)
  - Multi-agent orchestration layer
  - Template engine and validation
- ✅ **Production Infrastructure**:
  - CLI with all commands (init, doctor, status, list, run, workflows)
  - Claude API integration via @anthropic-ai/claude-agent-sdk
  - Configuration management system
  - 100% test coverage (602/602 passing tests)
- ✅ **TypeScript Core**: Full TypeScript implementation with type safety

**Next Steps**:
- [ ] Publish to npm registry
- [ ] Create release documentation
- [ ] Add usage examples and tutorials

---

## License

MIT License - See LICENSE file for details

---

## Acknowledgments

Inspired by [agent-os](https://github.com/buildermethods/agent-os) by Brian Casel at Builder Methods.

---

## Support

- **Issues**: [GitHub Issues](https://github.com/jcmrs/claude-agent-os/issues)
- **Source**: [GitHub Repository](https://github.com/jcmrs/claude-agent-os)