Category Manager

Category Manager - Branch of JARVIS-01

Build and improve categories following the category-management policy.

Policy Source

Primary policy: JARVIS-01 → .claude/skills/category-management/SKILL.md

This branch executes the policy defined by JARVIS-01. Always sync with Primary before major operations.

Quick Decision Tree

Task Received
    │
    ├── Create new category? ────────────> Workflow 1: Build
    │
    ├── Fix existing category? ──────────> Workflow 2: Improve
    │
    ├── Validate category? ──────────────> Validation Checklist
    │
    ├── Migrate to new standard? ────────> Workflow 3: Migrate
    │
    └── Self-improvement cycle? ─────────> Self-Improvement Process

Category Overview

Each JARVIS category maintains effective configuration through:

• CLAUDE.md - Main Agent instructions at category root
• .claude/settings.json - Tool permissions and MCP configurations
• .claude/mcp.json - MCP server definitions (Execution layer)
• .claude/skills/ - Primary Skill defining category policy
• plugins/ - 4-Plugin Architecture

Workflow 1: Build New Category

Step 1: Determine Layer

Decision criteria:

• Does it build tools for OTHER categories? → Management
• Does it control ONE external API/system? → Execution

Step 2: Assign Number

# Check existing categories
ls -d JARVIS-* | sort -t'-' -k2 -n

• Management: Limited to 00-10, must be approved
• Execution: Start from 11, take next available

Step 3: Create Full Structure

# Create all directories at once
mkdir -p JARVIS-XX-Name/{.claude/skills/[name]-management/references,plugins/{orchestrator,dev,bigquery-[name],category-[name]},TASKS}

Expected structure:

JARVIS-XX-Category-Name/
├── CLAUDE.md                        <- Category identity (REQUIRED)
├── .claude/
│   ├── settings.json                <- Tool permissions
│   ├── mcp.json                     <- MCP config (Execution layer)
│   └── skills/
│       └── [name]-management/       <- Primary Skill
│           ├── SKILL.md             <- REQUIRED
│           └── references/          <- Optional details
├── plugins/                         <- 4 Plugins (REQUIRED)
│   ├── orchestrator/                <- Shared - task routing
│   ├── dev/                         <- Shared - self-improvement
│   ├── bigquery-[name]/             <- Template - data access
│   └── category-[name]/             <- Unique - domain logic
└── TASKS/                           <- Task tracking
    └── TASK-XX-[name]/
        └── README.md

Step 4: Write CLAUDE.md

CLAUDE.md Structure

Minimal Template (for new categories):

# JARVIS-XX-CategoryName

## Role
[One sentence describing primary function]

## Responsibilities
- [Key responsibility 1]
- [Key responsibility 2]
- [Key responsibility 3]

## MCP Servers
| Server | Location | Purpose |
|--------|----------|---------|
| vault | VPS | Secrets management |
| supabase-common | CloudRun | Database access |

## Quick Reference
[Most common commands or patterns]

Full Template (for mature categories):

# JARVIS-XX-CategoryName

## Role
[Category's primary function and domain expertise]

## Responsibilities
- [Responsibility 1]
- [Responsibility 2]
- [Responsibility 3]

## MCP Servers
| Server | Location | Purpose |
|--------|----------|---------|
| server1 | VPS/CloudRun/Local | Description |

## Schemas (if database access)
| Schema | Purpose |
|--------|---------|
| schema1 | Description |

## Common Tasks

### Task Type 1
[Step-by-step instructions]

### Task Type 2
[Step-by-step instructions]

## Best Practices
- [Practice 1]
- [Practice 2]

## Integration Points
- **Category XX**: [How they interact]
- **Category YY**: [How they interact]

## Learnings
- [Learning 1 from previous conversations]
- [Learning 2]

## Changelog
- YYYY-MM-DD: [Change description]

CLAUDE.md Best Practices

• Keep concise (500-2000 words ideal)
• Use tables for structured data
• Include practical examples
• Update changelog on changes
• Focus on actionable instructions

Management Layer Template:

# JARVIS-XX-CategoryName

## Role
[Category function] for the JARVIS AI Ecosystem.

## Responsibilities
- Define [domain] policy for all categories
- Maintain [domain] standards
- Support categories in [domain] tasks

## Integration
- **Plugin-dev branch**: [branch-name]
- **Primary Skill**: [skill-name]-management

## Quick Reference
[Most common operations for this category]

Execution Layer Template:

# JARVIS-XX-CategoryName

## Role
Control [External System] via MCP with full coverage.

## Responsibilities
- Manage [System] resources
- Automate [System] operations
- Monitor [System] status

## MCP Servers
| Server | Location | Coverage | Purpose |
|--------|----------|----------|---------|
| [name] | CloudRun | 90%+ | [Description] |

## Schemas (BigQuery)
| Schema | Purpose |
|--------|---------|
| jarvis_XX_[name] | [Data stored] |

## Quick Reference
[Most common MCP operations]

Step 5: Configure settings.json

Settings.json Location

.claude/settings.json in category root

Basic Structure

{
  "permissions": {
    "allow": [],
    "deny": []
  }
}

With MCP Servers

{
  "permissions": {
    "allow": [
      "Bash(npm:*)",
      "Bash(git:*)",
      "mcp__vault__*"
    ],
    "deny": [
      "Bash(rm -rf:*)"
    ]
  },
  "mcpServers": {
    "vault": {
      "command": "npx",
      "args": ["-y", "@anthropic/mcp-vault"],
      "env": {
        "VAULT_ADDR": "${VAULT_ADDR}"
      }
    }
  }
}

Permission Patterns

Settings.json Best Practices

• Follow least privilege principle
• Document why permissions exist
• Test after changes
• Use environment variables for secrets
• Keep MCP configs minimal

Step 6: Create Primary Skill

Follow skills-manager for full details. Minimum:

---
name: [category]-management
description: "This skill [function]. Use when [conditions]. Triggers: '[trigger1]', '[trigger2]'."
---

# [Category] Management - JARVIS-XX

[Core concept in 2-3 sentences]

## When to Use This Skill
- [Condition 1]
- [Condition 2]

## Core Workflows
### Workflow 1: [Name]
1. [Step]
2. [Step]

## Validation Checklist
- [ ] [Check 1]
- [ ] [Check 2]

## Reference Files
- [references/detail.md](references/detail.md) - [Description]

Step 7: Set Up 4 Plugins

Use plugins-manager for detailed plugin creation.

Step 8: Configure MCP (Execution Layer Only)

Work with JARVIS-07 to:

1. Build or adapt MCP server
2. Document all tools in Primary Skill
3. Configure .claude/mcp.json
4. Test tool coverage

Step 9: Validate

Run full validation checklist (see below).

Self-Improvement Cycle

Categories should run self-improvement periodically to maintain effectiveness.

When to Run

• Every ~6 conversations
• After completing major tasks
• When issues or inefficiencies noticed
• On explicit request

Self-Improvement Process

1. Analyze Current State
   ├── Read CLAUDE.md
   ├── Read settings.json
   └── Review recent patterns

2. Identify Improvements
   ├── Missing instructions
   ├── Outdated information
   ├── Permission gaps
   └── New learnings

3. Apply Changes
   ├── Update CLAUDE.md
   ├── Update settings.json
   └── Document changes

4. Validate
   ├── Test configurations
   └── Verify no breakage

What to Improve

CLAUDE.md:

• Add instructions for recurring tasks
• Remove outdated information
• Improve clarity and organization
• Add learnings from conversations
• Update MCP server documentation

Settings.json:

• Add permissions for frequently used tools
• Remove unnecessary permissions
• Update MCP configurations
• Fix broken server configs

Self-Improvement Best Practices

• Make incremental changes
• Preserve working configurations
• Document all changes
• Test after modifications
• Review periodically

Workflow 2: Improve Existing Category

Step 1: Analyze Current State

# Run category audit
ls -la JARVIS-XX-Name/
cat JARVIS-XX-Name/CLAUDE.md
cat JARVIS-XX-Name/.claude/skills/*/SKILL.md
ls JARVIS-XX-Name/plugins/

Step 2: Gap Analysis

Step 3: Apply Fixes

Priority order:

1. Critical: Missing CLAUDE.md or Primary Skill
2. High: Missing plugins
3. Medium: Outdated content
4. Low: Formatting, clarity

Step 4: Document Changes

Create task record:

# TASK-XX-Category-Improvement

## Date: YYYY-MM-DD

## Changes Made
- [ ] Updated CLAUDE.md with [changes]
- [ ] Added missing [component]
- [ ] Fixed [issue]

## Validation
- [ ] All checks pass
- [ ] Tested functionality

Workflow 3: Migrate Category to New Standard

When category structure policy changes:

1. Backup current state
2. Compare with new standard (read Primary Skill)
3. Create migration plan
4. Apply changes incrementally
5. Validate each step
6. Document migration

Validation Checklist

Structure Checks

• Directory named JARVIS-XX-Name (XX = 2-digit number)
• Number matches layer (00-10 Management, 11+ Execution)
• CLAUDE.md exists at root
• CLAUDE.md has Role section
• CLAUDE.md has Responsibilities section

Configuration Checks

• .claude/settings.json exists and valid JSON
• .claude/mcp.json exists (if Execution layer)
• MCP servers documented in CLAUDE.md

Skill Checks

• Primary Skill at .claude/skills/[name]-management/SKILL.md
• SKILL.md has valid frontmatter (name, description)
• Description has "Triggers:" section
• references/ exists if SKILL.md > 1500 words

Plugin Checks

• plugins/orchestrator/ exists
• plugins/dev/ exists
• plugins/bigquery-[name]/ exists
• plugins/category-[name]/ exists
• Each plugin has .claude-plugin/plugin.json

Integration Checks

• If Management 01-06: branch exists in plugin-dev
• If Execution: MCP configured and tested
• TASKS/ directory exists

Common Issues & Fixes

BigQuery Integration (Optional)

Categories can track metrics in BigQuery for analytics and improvement:

bigquery.jarvis_analytics.
├── jarvis_XX_conversations    # Conversation logs
├── jarvis_XX_improvements     # Improvement history
└── jarvis_XX_metrics          # Performance metrics

Tracked Metrics

• Conversation count
• Task types and frequency
• Error patterns
• Improvement effectiveness

Use bigquery-[name] plugin for data access.

When to Use This Skill

• User asks to create a new JARVIS category
• User asks to validate category compliance
• User asks to fix category structure issues
• User asks about CLAUDE.md structure or settings.json format
• User asks about self-improvement cycle
• DEV-Manager detects category problems during improvement cycle
• Migrating categories to updated standard
• Regular improvement cycle (~6 sessions)

Sync Protocol

Before executing any workflow:

1. Read JARVIS-01's category-management SKILL.md
2. Check for policy updates
3. Apply current policy, not cached knowledge