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

Range	Layer	Purpose	Example
00-10	Management	Build ecosystem infrastructure	JARVIS-07 MCP-Manager
11+	Execution	Control external system	JARVIS-11 Cloudflare

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

Pattern	Meaning
Bash(npm:*)	Allow npm commands
Bash(git:*)	Allow git commands
mcp__server__*	Allow all tools from MCP server
mcp__server__tool	Allow specific MCP tool
Read(path/**)	Allow reading from path
Write(path/**)	Allow writing to path

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

Plugin	Action
orchestrator	Copy from shared source (identical)
dev	Copy from shared source (identical)
bigquery-[name]	Create from template, update table list
category-[name]	Create custom with domain agents/skills

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

Component	Check	Common Issues
CLAUDE.md	Exists? Up to date?	Missing MCP docs, outdated responsibilities
Primary Skill	Complete? References?	Missing triggers, no validation checklist
settings.json	Permissions correct?	Missing MCP tool permissions
4 Plugins	All present?	Missing plugin directories
mcp.json	Configured? (Execution)	Wrong server URLs

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

Issue	Diagnosis	Fix
Missing CLAUDE.md	ls JARVIS-XX/CLAUDE.md returns nothing	Create from template above
Wrong layer number	Category 15 doing management work	Renumber or reassign responsibilities
No Primary Skill	.claude/skills/ empty	Create following skills-manager
Missing plugins	ls plugins/ shows < 4 dirs	Create missing plugin directories
Outdated content	CLAUDE.md references old tools	Update with current MCP tools
No mcp.json	Execution category without MCP	Work with JARVIS-07 to create

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