# VC-SYS CLI User Guide
## Complete AI Development Environment with Integrated Backend Provisioning

### 🚀 What is VC-SYS CLI?

VC-SYS CLI is a **complete AI development environment** that transforms software development through specialized AI expertise, intelligent workflow orchestration, and integrated backend provisioning. Built for founders, developers, and teams who want AI-powered development environments that understand context, maintain memory, and coordinate complex workflows.

**Core Features:**
- **14 Specialized AI Agents** - Expert agents with persistent memory and context awareness
- **32+ Executable Task Workflows** - Automated development processes and project management
- **21+ Professional Templates** - Document and code generation with structured outputs
- **Intelligent Memory System** - Persistent context across sessions for personalized experience
- **Multi-Agent Orchestration** - Coordinated workflows between specialized agents
- **Integrated Supabase Backend** - Direct authentication, project provisioning, and schema deployment
- **Claude Code Integration** - Native slash command system for immediate productivity
- **Cross-Platform Architecture** - Windows, macOS, and Linux compatibility

---

## 📁 System Architecture

### **Two-Layer Architecture**
```
.claude/                    # Claude Code Integration Layer
└── commands/              # User-accessible slash commands
    ├── test-vcsys-working.md      # Working system test
    ├── test-vcsys.md              # Basic system test  
    └── vcsys/                     # VC-SYS command namespace
        ├── agents/               # 14 agent command files
        └── tasks/                # 29 task command files

.vcsys/                     # VC-SYS Resource Repository
├── agents/                 # Agent definitions (14 agents)
├── agent-teams/            # Team configurations (3 teams)
├── artifacts/              # Generated outputs and reports
├── checklists/             # Quality gates and validation
├── data/                   # Knowledge bases and reference materials
├── tasks/                  # Executable task workflows (32 tasks)
├── templates/              # Document templates (21 templates)  
├── utils/                  # Utility functions
├── workflows/              # Multi-step processes
├── core-config.yaml        # System configuration
├── install-manifest.yaml   # Installation tracking
└── user-guide.md          # This guide
```

**How It Works:**
- Users execute commands in `.claude/commands/vcsys/` using Claude Code slash commands
- Commands reference resources in `.vcsys/` for actual functionality
- All paths are relative for cross-platform installation compatibility

---

## 🤖 Available Agents (14 Total)

### **Architecture & Development**
- **`architect`** - Legacy system architect (simple version)  
- **`technical-architect`** - Modern system architecture and technical design
- **`developer`** - Code implementation and programming
- **`integration-specialist`** - System integration and API coordination

### **Quality & Testing**  
- **`qa`** - Quality assurance, testing strategy, and validation
- **`accessibility-specialist`** - WCAG compliance and inclusive design

### **Product & Management**
- **`product-owner`** - Product management and requirements  
- **`scrum-master`** - Agile project management and coordination
- **`orchestrator`** - System coordination and workflow management
- **`mentor`** - Personalized guidance, knowledge transfer, and adaptive development coaching

### **User Experience & Research**
- **`ux-expert`** - User experience design and interface optimization  
- **`market-research-specialist`** - Market analysis and competitive intelligence

### **Specialized Agents**
- **`gauntlet`** - Idea validation, challenge, and concept testing
- **`laboratory`** - Creative experimentation and structured brainstorming

---

## ⚡ Quick Start Guide

### **1. Test Your Installation**
```bash
# Test the VC-SYS system (verified working)
/test-vcsys-working
```

### **2. Start with AI Agent Coordination**
```bash
# Launch the Orchestrator (Master Coordinator)
/vcsys/agents/orchestrator

# Or start with creative work
/vcsys/agents/laboratory

# Technical architecture and system design
/vcsys/agents/technical-architect
```

### **3. Execute Automated Workflows**
```bash  
# Creative and ideation workflows
/vcsys/tasks/creative-exploration
/vcsys/tasks/concept-prototyping

# Project planning workflows
/vcsys/tasks/create-roadmap
/vcsys/tasks/create-story
/vcsys/tasks/create-epic

# Technical development workflows
/vcsys/tasks/technical-architecture
/vcsys/tasks/database-design

# Documentation workflows
/vcsys/tasks/create-doc
/vcsys/tasks/create-prd
```

### **4. Set Up Integrated Backend (Optional)**
```bash
# Using the TypeScript CLI for Supabase integration
cd vcsys-cli

# Authenticate with Supabase
npm start -- supabase auth login

# Create new project with database
npm start -- supabase provision my-backend --interactive

# Complete backend workflow with AI assistance  
npm start -- database-wizard
```

---

## 🎯 Agent Team Configurations

### **1. Full-Stack Development Team** 
**File**: `team-fullstack.yaml`  
**Use For**: Complete application development with comprehensive coverage
**Focus**: Full-stack development, security, accessibility, market intelligence

### **2. Market Intelligence Team**
**File**: `team-market-intelligence.yaml`  
**Use For**: Market research, competitive analysis, business case development  
**Focus**: Business intelligence, market validation, strategic planning

### **3. Security-Focused Team**
**File**: `team-security-focused.yaml`  
**Use For**: Security-first development, compliance projects, threat modeling
**Focus**: Security architecture, compliance validation, risk assessment

---

## 📋 Available Tasks (32 Total)

### **Creative & Ideation** (7 tasks)
- `advanced-elicitation` - Structured requirement gathering and analysis
- `concept-prototyping` - Rapid concept development and validation  
- `concept-testing` - Systematic concept validation and testing
- `convergent-thinking` - Idea refinement and prioritization
- `creative-exploration` - Deep creative problem exploration  
- `divergent-thinking` - Maximum idea variety generation
- `facilitate-brainstorming-session` - Interactive brainstorming workflows
- `idea-experimentation` - Structured creative idea testing
- `idea-synthesis` - Combine ideas into innovative hybrid solutions

### **Development & Architecture** (4 tasks)  
- `database-design` - Data architecture and database planning
- `generate-ai-frontend-prompt` - Frontend specification generation
- `technical-architecture` - System architecture design and documentation
- `tech-stack-selection` - Technology selection and evaluation

### **Project Management** (8 tasks)
- `create-doc` - Structured document creation using templates
- `create-epic` - Epic breakdown and planning  
- `create-next-story` - Sequential story planning and creation
- `create-story` - User story creation and documentation
- `execute-checklist` - Quality gate validation and verification
- `review-story` - Story validation and review processes  
- `task-breakdown` - Feature decomposition into actionable tasks
- `validate-next-story` - Story prioritization and validation

### **Legacy & Brownfield** (3 tasks)
- `brownfield-create-epic` - Legacy system epic planning
- `brownfield-create-story` - Legacy system story creation  
- `create-brownfield-story` - Legacy enhancement and modernization

### **Research & Analysis** (2 tasks)
- `create-deep-research-prompt` - Research planning and strategy
- `correct-course` - Project correction and realignment

### **Utility & Management** (8 tasks)
- `index-docs` - Documentation organization and indexing
- `kb-mode-interaction` - Knowledge base interaction workflows
- `manage-user-context` - Create and manage persistent user context profiles for Laboratory
- `manage-orchestrator-context` - Create and manage coordination preferences for Orchestrator  
- `manage-mentor-context` - Create and manage learning profiles for Mentor
- `shard-doc` - Document segmentation and organization

---

## 📄 Available Templates (21 Total)

### **Architecture Templates**
- `api-spec-tmpl.yaml` - API specification and documentation
- `architecture-tmpl.yaml` - General system architecture
- `brownfield-architecture-tmpl.yaml` - Legacy system architecture  
- `front-end-architecture-tmpl.yaml` - Frontend system architecture
- `fullstack-architecture-tmpl.yaml` - Complete full-stack architecture
- `implementation-roadmap-tmpl.yaml` - Development roadmap and planning

### **Business & Research Templates**  
- `competitor-analysis-tmpl.yaml` - Competitive analysis framework
- `market-research-tmpl.yaml` - Market analysis and research
- `project-brief-tmpl.yaml` - Project overview and brief

### **Development Templates**
- `front-end-spec-tmpl.yaml` - Frontend specifications  
- `prd-tmpl.yaml` - Product requirements document
- `story-tmpl.yaml` - User story template

### **Creative & Innovation Templates**
- `concept-prototype-tmpl.yaml` - Concept prototyping documentation  
- `creative-session-tmpl.yaml` - Creative session results
- `experiment-results-tmpl.yaml` - Creative experimentation documentation
- `idea-synthesis-tmpl.yaml` - Idea synthesis and hybrid concepts
- `innovation-report-tmpl.yaml` - Comprehensive innovation reporting
- `mentor-handoff-tmpl.yaml` - Task handoff and knowledge transfer

### **User Memory & Context Templates**
- `user-context-tmpl.yaml` - Laboratory agent creative and business context
- `orchestrator-context-tmpl.yaml` - Orchestrator agent coordination and project intelligence
- `mentor-context-tmpl.yaml` - Mentor agent learning and development context

---

## 🔄 Available Workflows (6 Enhanced Workflows)

### **Greenfield Development**
- `vcsys-greenfield-fullstack.yaml` - Complete new project development
- `vcsys-greenfield-ui.yaml` - Accessibility-first UI development
- `vcsys-greenfield-service.yaml` - Security-first backend services

### **Brownfield Enhancement**  
- `vcsys-brownfield-fullstack.yaml` - Legacy system modernization
- `vcsys-brownfield-ui.yaml` - UI accessibility retrofit
- `vcsys-brownfield-service.yaml` - Backend security hardening

---

## ⚙️ Command Reference

### **Correct Command Syntax**
All VC-SYS commands use the namespace pattern:

```bash
# Agent commands  
/vcsys/agents/agent-name

# Task commands
/vcsys/tasks/task-name

# Test commands
/test-vcsys-working  # Verified functional test
```

### **Agent Command Examples**
```bash
# Creative and brainstorming
/vcsys/agents/laboratory

# Technical architecture  
/vcsys/agents/technical-architect
/vcsys/agents/architect

# Development and implementation
/vcsys/agents/developer  
/vcsys/agents/integration-specialist

# Quality and testing
/vcsys/agents/qa
/vcsys/agents/accessibility-specialist  

# Business and research
/vcsys/agents/market-research-specialist
/vcsys/agents/product-owner

# Project management  
/vcsys/agents/scrum-master
/vcsys/agents/orchestrator

# User experience
/vcsys/agents/ux-expert

# Validation and guidance
/vcsys/agents/gauntlet  
/vcsys/agents/mentor
```

### **Task Command Examples**  
```bash
# Start creative exploration
/vcsys/tasks/creative-exploration

# Design system architecture
/vcsys/tasks/technical-architecture  

# Create user stories
/vcsys/tasks/create-story

# Validate concepts
/vcsys/tasks/concept-testing

# Plan development roadmap
/vcsys/tasks/task-breakdown
```

---

## 🚀 Agent Capabilities

### **Laboratory Agent** (Creative Powerhouse + User Memory)
- **Creative Commands**: `*help`, `*experiment`, `*explore`, `*prototype`, `*connect`, `*diverge`, `*converge`, `*test`, `*document`, `*handoff`
- **Memory Commands**: `*remember`, `*context`, `*update-context`
- **Specializes In**: Creative ideation, concept experimentation, breakthrough thinking, personalized user experience
- **Dependencies**: 10 tasks, 7 templates, 2 data files
- **Architecture**: Modular (94 lines) with intelligent user context integration
- **Unique Feature**: **Persistent User Memory** - Learns your interests, constraints, and goals to eliminate repetitive questioning and provide personalized exploration sessions

### **Technical Architect** (System Design Expert)  
- **Specializes In**: System architecture, technical specifications, scalability planning
- **Creates**: PRDs, technical architecture, database designs, implementation roadmaps
- **Dependencies**: 4 tasks, 6 templates for comprehensive system design

### **Market Research Specialist** (Business Intelligence)
- **Specializes In**: Market analysis, competitive intelligence, business validation  
- **Capabilities**: Market research, competitor analysis, business case development

### **Orchestrator** (System Coordinator + Project Intelligence)
- **Coordination Commands**: `*help`, `*workflow`, `*personas`, `*route`, `*status`
- **Memory Commands**: `*remember`, `*context`, `*update-context`
- **Role**: Master coordinator with intelligent project portfolio management
- **Specializes In**: Agent routing, workflow optimization, strategic alignment, multi-project coordination
- **Unique Feature**: **Project Intelligence Memory** - Learns your coordination style, successful patterns, and strategic objectives to optimize agent routing and workflow management

---

## 🧠 Intelligent User Memory System

### **Revolutionary Persistent Context**
Three core agents (Laboratory, Orchestrator, Mentor) feature advanced user memory systems that learn and remember your preferences, eliminating repetitive setup and providing truly personalized AI interactions tailored to each agent's role.

### **How It Works**
1. **First Session**: Answer comprehensive context questions once
2. **Automatic Learning**: System captures your interests, constraints, goals, and preferences  
3. **Persistent Storage**: Context saved in `.vcsys/artifacts/user-contexts/`
4. **Smart Integration**: Future sessions automatically reference your profile
5. **Continuous Evolution**: Context updates as your preferences and goals change

### **Memory Management Commands**
```bash
# Laboratory Agent - Creative context and interests
/vcsys/agents/laboratory
> *remember    # Create/update creative profile
> *context     # View creative context
> *update-context  # Modify creative preferences

# Orchestrator Agent - Project coordination preferences  
/vcsys/agents/orchestrator
> *remember    # Create/update coordination profile
> *context     # View coordination preferences
> *update-context  # Modify workflow preferences

# Mentor Agent - Learning and development context
/vcsys/agents/mentor
> *remember    # Create/update learning profile
> *context     # View development history
> *update-context  # Modify learning goals
```

### **What Gets Remembered Per Agent**

**Laboratory Agent Context:**
- **Creative Interests**: Technical skills, passion areas, problem sensitivity
- **Business Goals**: Revenue targets, model preferences, market focus
- **Development Constraints**: Time, complexity tolerance, resource budgets
- **Innovation Patterns**: Learning style, creative preferences, breakthrough moments

**Orchestrator Agent Context:**
- **Project Portfolio**: Active initiatives, complexity preferences, coordination style
- **Agent Usage History**: Successful routing patterns, workflow preferences, team configurations
- **Strategic Objectives**: Business goals, resource allocation, growth trajectory
- **Coordination Intelligence**: Decision patterns, quality standards, optimization insights

**Mentor Agent Context:**
- **Learning Profile**: Skill levels, learning preferences, knowledge gaps, development goals
- **Mentoring History**: Previous guidance experiences, communication preferences, trust patterns
- **Career Context**: Professional aspirations, current situation, strategic direction
- **Growth Patterns**: Development pace, challenge tolerance, success factors

### **Personalization Benefits**
- **No Repetitive Questions**: Skip questions already answered in previous sessions
- **Tailored Recommendations**: Suggestions based on your specific interests and constraints  
- **Smart Defaults**: Use known preferences as starting points for exploration
- **Goal Tracking**: Monitor progress toward stated objectives across sessions
- **Context Evolution**: Learn from your feedback and changing circumstances

### **Example User Experience**

**First Session:**
```
User: "I want to explore app ideas for extra $5k/month"
Laboratory: [Asks comprehensive context questions about interests, constraints, goals]
> *remember command captures all responses in persistent profile
```

**Future Sessions:**  
```
# Laboratory Session
User: "Let's brainstorm some new concepts" 
Laboratory: "Welcome back! I know you're targeting $5k/month revenue to accelerate 
your larger projects, with your background in [technical areas]..."

# Orchestrator Session  
User: "What should I work on next?"
Orchestrator: "Based on your portfolio and preference for [coordination style], 
I recommend routing to [specific agent] for your [project phase]..."

# Mentor Session
User: "I need guidance on this challenge"
Mentor: "Given your [learning style] and development goals in [area], 
let me provide guidance that builds on our previous work on [topic]..."

> No repetitive setup - immediate personalized assistance
```

### **Privacy & Control**
- **Local Storage**: All context stored locally in your project directory
- **Full Control**: View, modify, or delete your profile at any time
- **Transparent**: Clear visibility into what information is stored
- **Secure**: No external data transmission - your context stays with you

---

## 🚀 Supabase Backend Integration

### **Direct Backend Provisioning**

VC-SYS CLI includes integrated Supabase backend provisioning for complete full-stack development workflows. Deploy production-ready backends directly from the CLI with AI-assisted schema design.

### **Authentication & Setup**
```bash
# Authenticate with Supabase (requires personal access token)
npm start -- supabase auth login

# Check authentication status  
npm start -- supabase auth status

# Logout and clear stored tokens
npm start -- supabase auth logout
```

**Getting Supabase Access Token:**
1. Visit [Supabase Dashboard → Account → Access Tokens](https://supabase.com/dashboard/account/tokens)
2. Create a new personal access token
3. Run `npm start -- supabase auth login` and enter token when prompted
4. Tokens are stored securely with encrypted file storage

### **Project Management**
```bash
# List your organizations
npm start -- supabase orgs

# List all projects (or filter by organization)
npm start -- supabase list
npm start -- supabase list --org <org-id>

# Get project details and status
npm start -- supabase status <project-ref>
```

### **Project Provisioning**
```bash
# Interactive provisioning (recommended)
npm start -- supabase provision my-project --interactive

# Direct provisioning with parameters
npm start -- supabase provision my-project --org <org-id> --region us-east-1 --password <db-password>
```

### **Database Schema Management**
```bash
# Deploy schema from SQL file
npm start -- supabase deploy-schema schema.sql --project <project-ref>

# Generate environment configuration
npm start -- supabase env <project-ref>
npm start -- supabase env <project-ref> --output .env.production
```

### **Database Wizard - Complete Backend Workflow**

The Database Wizard combines AI-assisted schema design with live Supabase deployment:

```bash
# Launch Database Wizard
npm start -- database-wizard
```

**Complete Workflow Options:**
1. **"Complete workflow: Schema + Supabase deployment"** (Recommended)
   - Schema design from requirements
   - Comprehensive documentation generation
   - Supabase project provisioning
   - Schema deployment to live database
   - Environment setup with connection details

2. **"Draft a new database schema from requirements"**
   - AI-assisted schema design only
   - PostgreSQL with RLS policies
   - Comprehensive documentation

3. **"Provision Supabase backend with existing schema"** 
   - Deploy existing schema file
   - Project provisioning and setup

4. **"Generate schema documentation only"**
   - Document existing database schemas

**Generated Artifacts:**
- `schema-[timestamp].sql` - Complete PostgreSQL schema with RLS policies
- `schema-documentation-[timestamp].md` - Comprehensive database documentation
- `.env.local` - Environment variables for Supabase connection
- **Live Supabase Project** - Deployed and ready for development

**Security Features:**
- Row Level Security (RLS) policies automatically generated
- Supabase Auth integration built-in
- Secure token storage with encryption
- User-scoped data access patterns

### **Integration with AI Agents**

Supabase backend provisioning integrates seamlessly with VC-SYS AI agents:

```bash
# Technical Architect + Database Design
/vcsys/agents/technical-architect
> Design system architecture including database requirements
> Export requirements to Database Wizard for implementation

# Developer + Backend Implementation
/vcsys/agents/developer  
> Use provisioned Supabase backend for implementation
> Reference generated environment variables and schema documentation

# QA + Security Validation
/vcsys/agents/qa
> Validate RLS policies and security implementation
> Test backend integration and data access patterns
```

---

## 🔧 Installation & Setup

### **Prerequisites**
- **Node.js** v20+ required for TypeScript CLI and Supabase integration
- **Claude Code** for AI agent slash command integration
- **Git** for version control and repository management

### **Installation Steps**
```bash
# Clone the repository
git clone https://github.com/yourusername/vcsys-cli.git
cd vcsys-cli

# Install dependencies
npm install

# Build the TypeScript CLI
npm run build

# Verify installation
npm start -- --help
```

### **Initial Setup & Validation**
```bash
# Test VC-SYS AI agent system (verified working)
/test-vcsys-working

# Initialize new VC-SYS project environment
npm start -- init my-saas-project

# Check system status
npm start -- status

# Validate CLI resources
npm start -- validate-resources
```

### **Optional: Supabase Backend Setup**
```bash
# Set up Supabase integration (if needed)
npm start -- supabase auth login

# Test backend connectivity
npm start -- supabase orgs
```

---

## 💡 Getting Help & Troubleshooting

### **System Validation**
```bash  
# Test basic functionality (verified working)
/test-vcsys-working

# Test system integration 
/test-vcsys
```

### **Agent Help**
- Each agent includes built-in help commands (e.g., `*help` in Laboratory)
- Agent files contain complete capability descriptions  
- Task files include success criteria and usage guidelines

### **Common Issues**
- **Command not found**: Ensure using correct syntax `/vcsys/agents/name` not `/name`
- **Missing dependencies**: Check that `.vcsys/` directory contains required resources
- **Template errors**: Verify template exists in `.vcsys/templates/` before use

---

## 📊 System Metrics & Performance

### **Architecture Efficiency**  
- **Agent Files**: 94-line modular agents vs 400+ line monolithic
- **Token Efficiency**: Dynamic dependency loading reduces context usage
- **Installability**: Relative paths ensure cross-platform compatibility
- **Mirror Architecture**: Perfect synchronization between `.claude/` and `.vcsys/`

### **Capability Coverage**
- ✅ **14 Specialized Agents** covering all development roles
- ✅ **32 Executable Tasks** for comprehensive workflow automation  
- ✅ **21 Professional Templates** for documentation and planning
- ✅ **Claude Code Integration** with native slash command support
- ✅ **Quality Gates** built into all workflows and processes

---

## 🎯 Success Metrics

**System Status**: ✅ **Fully Functional**
- All agent commands verified and working
- Template dependencies resolved and complete
- Command syntax corrected for proper usage  
- Mirror architecture maintained and synchronized
- Installable structure with relative paths

**User Experience**: ✅ **Production Ready**
- Clear command syntax with predictable patterns
- Comprehensive help and documentation  
- Systematic task workflows with quality gates
- Professional template library for all common needs

---

*VC-SYS CLI: Professional AI development environments through intelligent agent orchestration, systematic task automation, and structured template generation.*