# VC-SYS CLI Structural Reference Guide

## Critical Directive for All Future Claude Code Operations

This guide is the DEFINITIVE REFERENCE for the vcsys-cli system structure and MUST be consulted before creating, modifying, or referencing any commands, agents, or tasks within this system.

---

## Core System Architecture

### Primary Directory Structure

```
/mnt/c/Users/Chris/vc-sys-app/vcsys-cli/
├── .claude/                    # Claude Code Integration Layer
│   └── commands/              # User-accessible slash commands
│       ├── test-*.md         # System test commands
│       └── vcsys/            # VC-SYS command namespace
│           ├── agents/       # Agent command files
│           └── tasks/        # Task command files
│
└── .vcsys/                    # VC-SYS Resource Repository
    ├── agents/               # Agent definitions and configurations
    ├── agent-teams/          # Team configurations
    ├── artifacts/            # Generated artifacts and outputs
    ├── checklists/          # Quality gates and validation checklists
    ├── data/                # Reference data and knowledge bases
    ├── tasks/               # Task workflow definitions
    ├── templates/           # Document and code templates
    ├── utils/               # Utility functions and helpers
    ├── workflows/           # Complete workflow orchestrations
    ├── core-config.yaml     # System configuration
    ├── project.yaml         # Project metadata
    ├── user-guide.md        # User documentation
    └── install-manifest.yaml # Installation tracking
```

## Critical Reference Resolution Rules

### Rule 1: Two-Layer Architecture
- **Layer 1 (.claude/)**: User-facing commands that Claude Code users execute directly
- **Layer 2 (.vcsys/)**: Resource repository that Layer 1 commands reference

### Rule 2: File Reference Protocol
**MANDATORY PATH RESOLUTION:**
- All commands in `.claude/commands/vcsys/` MUST reference resources using EXACT paths to `.vcsys/`
- Never reference `.vcsys-core/` (does not exist)
- Never reference relative paths without full directory structure

**Correct Reference Patterns:**
```markdown
# In Claude command files (.claude/commands/vcsys/*)
# Use relative paths that work for any installation
- Task reference: `.vcsys/tasks/task-name.md`
- Template reference: `.vcsys/templates/template-name.yaml`
- Data reference: `.vcsys/data/data-name.md`
- Agent reference: `.vcsys/agents/agent-name.md`
```

**INCORRECT Reference Patterns (NEVER USE):**
```markdown
# These will FAIL - DO NOT USE
- .vcsys-core/ (directory doesn't exist)
- ../tasks/ (relative paths without full context)
- tasks/task-name.md (missing full path)
- Any reference to non-existent directories or files
```

### Rule 3: Dependency Mapping System
When commands reference dependencies, they map as follows:

```yaml
# Dependency Type Mapping
dependencies:
  tasks: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/tasks/{task-name}
  templates: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/templates/{template-name}
  agents: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/agents/{agent-name}
  data: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/data/{data-name}
  checklists: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/checklists/{checklist-name}
  utils: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/utils/{util-name}
  workflows: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/workflows/{workflow-name}
```

## Claude Command Structure Standards

### Agent Command Files (.claude/commands/vcsys/agents/)
**REQUIRED STRUCTURE:**
```markdown
# /agent-name Command

When this command is used, adopt the following agent persona:

# agent-name

ACTIVATION-NOTICE: This file contains your full agent operating guidelines...

## COMPLETE AGENT DEFINITION FOLLOWS - NO EXTERNAL FILES NEEDED

```yaml
# Complete YAML configuration with proper path references
dependencies:
  tasks:
    - /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/tasks/task-name.md
  templates:
    - /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/templates/template-name.yaml
  # etc...
```
```

### Task Command Files (.claude/commands/vcsys/tasks/)
**REQUIRED STRUCTURE:**
```markdown
# /task-name Command

When this command is used, execute the following task:

Load and execute: `/mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/tasks/task-name.md`

## Task Overview
[Brief description of what this task does]

## Dependencies Required
- Template: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/templates/related-template.yaml
- Data: /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/data/reference-data.md

[Execute the task workflow exactly as defined in the referenced file]
```

## Resource File Standards (.vcsys/)

### Task Files (.vcsys/tasks/)
**REQUIRED YAML HEADER:**
```yaml
# At top of every task file
task_type: "interactive-workflow|automated|analysis"
complexity: "simple|moderate|complex"
estimated_time: "X-Y minutes"
elicit: true|false
prerequisites: ["requirement1", "requirement2"]
outputs:
  - output-type-1
  - output-type-2
```

### Template Files (.vcsys/templates/)
**NAMING CONVENTION:**
- End with `-tmpl.yaml`
- Clear, descriptive names
- Use YAML format with variable substitution syntax

### Data Files (.vcsys/data/)
**CONTENT STANDARDS:**
- Reference data, methodologies, frameworks
- Structured as Markdown with clear sections
- Contain reusable knowledge elements

## Quality Assurance Protocol

### Pre-Command Creation Checklist
1. **Verify Resource Existence**: Confirm all referenced files exist in `.vcsys/`
2. **Path Accuracy**: Use complete absolute paths to all resources
3. **Dependency Chain**: Ensure all dependencies are available and functional
4. **Test Execution**: Verify command can execute without errors

### Post-Creation Validation
1. **File Reference Test**: Attempt to read all referenced files
2. **Command Execution Test**: Run the command to ensure it functions
3. **User Experience Test**: Verify the command produces expected outputs
4. **Documentation Update**: Update user-guide.md if needed

## Error Prevention Guidelines

### Common Mistakes to Avoid
1. **Directory References**: Never reference `.vcsys-core/` or other non-existent directories
2. **Relative Paths**: Always use complete absolute paths
3. **Missing Dependencies**: Don't reference files that don't exist
4. **Broken Chains**: Ensure all dependency files are functional
5. **Outdated References**: Update references when files are moved or renamed

### Validation Commands for Testing
Before completing any work, use these validation patterns:

```bash
# Test file existence
ls -la /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.vcsys/tasks/task-name.md

# Test command references
grep -r "task-name" /mnt/c/Users/Chris/vc-sys-app/vcsys-cli/.claude/commands/

# Verify dependency chain
# Read referenced files to ensure they exist and are functional
```

## Mirror Architecture Requirements

### Perfect Mirror Principle
Following the BMad model, maintain perfect mirroring between:
- `.vcsys/agents/` ↔ `.claude/commands/vcsys/agents/`
- `.vcsys/tasks/` ↔ `.claude/commands/vcsys/tasks/`

**Current Agent Count Requirement**: 14 agents in both directories

### Mirror Validation Process
1. **Count Verification**: `ls .vcsys/agents/ | wc -l` should equal `ls .claude/commands/vcsys/agents/ | wc -l`
2. **Name Matching**: Every agent in `.vcsys/agents/` should have corresponding command in `.claude/commands/vcsys/agents/`
3. **Functionality Parity**: Each Claude command should properly reference its `.vcsys/` counterpart

## Current System State

### Existing Resources (.vcsys/)
**Verified Directories:**
- agents/ (14 agent definitions)
- agent-teams/ (team configurations)
- artifacts/ (generated outputs)
- checklists/ (quality gates)
- data/ (reference materials)
- tasks/ (workflow definitions)
- templates/ (document templates)
- utils/ (utility functions)
- workflows/ (complete orchestrations)

**Key Configuration Files:**
- `core-config.yaml` - System configuration
- `user-guide.md` - User documentation
- `install-manifest.yaml` - Installation tracking
- `project.yaml` - Project metadata

### Claude Commands (.claude/commands/)
**Test Commands:**
- `test-vcsys-enhanced.md` (BROKEN - references non-existent .vcsys-core/)
- `test-vcsys-working.md` (FUNCTIONAL)
- `test-vcsys.md` (status unknown)

**Agent Commands:** 14 files in `.claude/commands/vcsys/agents/`
**Task Commands:** Multiple files in `.claude/commands/vcsys/tasks/`

## Implementation Protocol

### When Creating New Commands
1. **Read This Guide First**: Always consult this document before starting
2. **Verify Resource Availability**: Check that all referenced resources exist
3. **Use Absolute Paths**: Never use relative or incorrect paths
4. **Test Before Completion**: Validate that the command actually works
5. **Update Documentation**: Ensure user-guide.md reflects new capabilities

### When Modifying Existing Commands
1. **Audit Current State**: Check all file references for accuracy
2. **Preserve Functionality**: Don't break existing working features
3. **Maintain Mirror Architecture**: Keep agent/task mirrors synchronized
4. **Validate After Changes**: Test that modifications work correctly

### When Troubleshooting Errors
1. **Check File Paths First**: Most errors are incorrect path references
2. **Verify File Existence**: Ensure referenced files actually exist
3. **Read Error Messages**: Look for specific clues about what's missing
4. **Use This Guide**: Cross-reference against the standards defined here

---

## CRITICAL SUCCESS PATTERN

**The Only Acceptable Workflow:**
1. Read this guide completely
2. Verify all file paths and dependencies exist before creating commands
3. Use absolute paths to all resources in `.vcsys/`
4. Test commands after creation to ensure they function
5. Update this guide if structural changes are needed

**This Guide Prevents:**
- Broken command references
- Non-existent directory references  
- Relative path failures
- Missing dependency chains
- User frustration from non-functional commands

**This Guide Ensures:**
- All commands function correctly when used
- Users can reliably access all system capabilities
- Resource references are accurate and complete
- System maintains professional reliability standards

---

*Last Updated: [Current Date] - This guide is the authoritative reference for all vcsys-cli structural decisions.*