# Plan: Restructure Claude Code Components

## Summary
Reclassify misplaced skill files as commands, standardize workflow format to YAML, and add cross-references between components.

---

## Decisions Made

| Decision | Choice |
|----------|--------|
| Handle misclassified skills | Move to commands as thin wrappers |
| Workflow format | Keep YAML, convert Markdown to YAML |
| Cross-references | Add inline links in command files |

---

## Task 1: Move Misclassified Skills to Commands

These files use `/command` syntax and should be commands, not skills.

### 1.1 Create `/cluster-status` command

**Delete:** `~/.claude/skills/cluster-status.md`
**Create:** `~/.claude/commands/k8s/cluster-status.md`

```yaml
---
name: cluster-status
description: Get quick cluster health overview
aliases: [status, cs]
---
```

Content: Thin wrapper referencing `cluster-health-check` workflow.

### 1.2 Create `/deploy` command

**Delete:** `~/.claude/skills/deploy.md`
**Create:** `~/.claude/commands/k8s/deploy.md`

```yaml
---
name: deploy
description: Deploy application to K8s cluster
aliases: [d]
---
```

Content: Thin wrapper referencing `deploy-app` workflow.

### 1.3 Create `/diagnose` command

**Delete:** `~/.claude/skills/diagnose.md`
**Create:** `~/.claude/commands/k8s/diagnose.md`

```yaml
---
name: diagnose
description: Investigate cluster issues
aliases: [diag]
---
```

Content: Thin wrapper referencing incident workflows.

---

## Task 2: Convert Workflow to YAML

**File:** `~/.claude/workflows/deploy/deploy-app.md`
**Convert to:** `~/.claude/workflows/deploy/deploy-app.yaml`

Restructure as proper YAML workflow matching other workflow files.

---

## Task 3: Add Cross-References to Existing Commands

Update existing commands to explicitly reference what they invoke:

### 3.1 Update `/health` command

**File:** `~/.claude/commands/sysadmin/health.md`

Add: `invokes: skill:sysadmin-health`

### 3.2 Update `/update` command

**File:** `~/.claude/commands/sysadmin/update.md`

Add: `invokes: workflow:sysadmin/system-update`

### 3.3 Update `/autonomy` command

**File:** `~/.claude/commands/sysadmin/autonomy.md`

Add: `modifies: state:sysadmin/session-autonomy`

---

## Task 4: Update CLAUDE.md with Component Conventions

**File:** `~/.claude/CLAUDE.md`

Add section documenting:
- Format conventions (when to use JSON vs YAML vs Markdown)
- Component relationships (commands → skills → workflows)
- Naming patterns

---

## Files to Create

| File | Purpose |
|------|---------|
| `~/.claude/commands/k8s/cluster-status.md` | Cluster status command |
| `~/.claude/commands/k8s/deploy.md` | Deploy command |
| `~/.claude/commands/k8s/diagnose.md` | Diagnose command |
| `~/.claude/workflows/deploy/deploy-app.yaml` | Converted workflow |

## Files to Delete

| File | Reason |
|------|--------|
| `~/.claude/skills/cluster-status.md` | Moved to commands |
| `~/.claude/skills/deploy.md` | Moved to commands |
| `~/.claude/skills/diagnose.md` | Moved to commands |
| `~/.claude/workflows/deploy/deploy-app.md` | Converted to YAML |

## Files to Modify

| File | Change |
|------|--------|
| `~/.claude/commands/sysadmin/health.md` | Add invokes reference |
| `~/.claude/commands/sysadmin/update.md` | Add invokes reference |
| `~/.claude/commands/sysadmin/autonomy.md` | Add modifies reference |
| `~/.claude/CLAUDE.md` | Add component conventions |

---

## Execution Order

1. Create `~/.claude/commands/k8s/` directory
2. Create 3 new command files
3. Delete 3 misclassified skill files
4. Convert deploy-app.md to deploy-app.yaml
5. Update existing command files with cross-references
6. Update CLAUDE.md with conventions