Documentation README Sync

What this skill does

# docs.sync.readme

## Overview

**docs.sync.readme** is the documentation synchronization tool that regenerates the top-level `README.md` to reflect all current registered skills and agents. It ensures that the README stays in sync with the actual state of the Betty Framework by pulling from registry files.

## Purpose

Automates the maintenance of `README.md` to keep documentation accurate and up-to-date with:
- **Skill Registry** (`registry/skills.json`) – All registered skills
- **Agent Registry** (`registry/agents.json`) – All registered agents

This eliminates manual editing of the README and prevents documentation drift as skills and agents are added, modified, or removed.

## What It Does

1. **Reads Registries**: Loads `skills.json` and `agents.json`
2. **Categorizes Skills**: Groups skills by tag/category:
   - Foundation (skill.*, registry.*, workflow.*)
   - API Development (api.*)
   - Infrastructure (agents, commands, hooks, policy)
   - Governance (policy, audit)
3. **Updates Sections**:
   - Current Core Skills table with categorized skills
   - Agents documentation links
   - Skills documentation references
4. **Maintains Style**: Preserves README tone, formatting, and structure
5. **Generates Report**: Creates sync report with statistics

## Usage

### Basic Usage

```bash
python skills/docs.sync.readme/readme_sync.py
```

No arguments required - reads from standard registry locations.

### Via Betty CLI

```bash
/docs/sync/readme
```

### Expected Registry Structure

```
betty/
├── registry/
│   ├── skills.json      # Skills registry
│   └── agents.json      # Agents registry
└── README.md            # File to update
```

## Behavior

### 1. Registry Loading

Reads JSON files from:
- `registry/skills.json` – Skills registry
- `registry/agents.json` – Agents registry

If a registry file is missing, logs a warning and continues with empty data.

### 2. Skill Categorization

**Foundation Skills**:
- Matches: `skill.*`, `registry.*`, `workflow.*`
- Examples: `skill.create`, `workflow.compose`

**API Development Skills**:
- Matches: `api.*` or tags: `api`, `openapi`, `asyncapi`
- Examples: `api.define`, `api.validate`

**Infrastructure Skills**:
- Matches tags: `agents`, `command`, `hook`, `policy`, `plugin`
- Examples: `agent.define`, `hook.register`, `plugin.sync`

**Governance Skills**:
- Matches tags: `governance`, `policy`, `audit`
- Examples: `policy.enforce`, `audit.log`

Only **active** skills are included. Test skills (starting with `test.`) are filtered out.

### 3. Skills Section Update

Replaces the "## 🧩 Current Core Skills" section with:

```markdown
## 🧩 Current Core Skills

Betty's self-referential "kernel" of skills bootstraps the rest of the system:

### Foundation Skills

| Skill | Purpose |
|--------|----------|
| **skill.create** | Generates a new Betty Framework Skill directory and manifest. |
| **skill.define** | Validates and registers skill manifests (.skill.yaml) for the Betty Framework. |
| **registry.update** | Updates the Betty Framework Skill Registry by adding or modifying entries. |

### API Development Skills

| Skill | Purpose |
|--------|----------|
| **api.define** | Create OpenAPI and AsyncAPI specifications from templates |
| **api.validate** | Validate OpenAPI and AsyncAPI specifications against enterprise guidelines |

### Infrastructure Skills

| Skill | Purpose |
|--------|----------|
| **agent.define** | Validates and registers agent manifests for the Betty Framework. |
| **hook.define** | Create and register validation hooks for Claude Code |

These skills form the baseline for an **AI-native SDLC** where creation, validation, registration, and orchestration are themselves skills.
```

### 4. Agents Section Update

Updates the "### Agents Documentation" subsection with current agents:

```markdown
### Agents Documentation

Each agent has a `README.md` in its directory:
* [api.designer](agents/api.designer/README.md) — Design RESTful APIs following enterprise guidelines with iterative refinement
* [api.analyzer](agents/api.analyzer/README.md) — Analyze API specifications for backward compatibility and breaking changes
```

Includes both `active` and `draft` agents.

### 5. Report Generation

Creates `sync_report.json` with statistics:

```json
{
  "skills_by_category": {
    "foundation": 5,
    "api": 4,
    "infrastructure": 9,
    "governance": 1
  },
  "total_skills": 19,
  "agents_count": 2,
  "timestamp": "2025-10-23T20:30:00.123456+00:00"
}
```

## Outputs

### Success Response

```json
{
  "ok": true,
  "status": "success",
  "readme_path": "/home/user/betty/README.md",
  "report": {
    "skills_by_category": {
      "foundation": 5,
      "api": 4,
      "infrastructure": 9,
      "governance": 1
    },
    "total_skills": 19,
    "agents_count": 2,
    "timestamp": "2025-10-23T20:30:00.123456+00:00"
  }
}
```

### Failure Response

```json
{
  "ok": false,
  "status": "failed",
  "error": "README.md not found at /home/user/betty/README.md"
}
```

## What Gets Updated

### ✅ Updated Sections

- **Current Core Skills** (categorized tables)
- **Agents Documentation** (agent links list)
- Skills documentation references

### ❌ Not Modified

- Mission and inspiration
- Purpose and scope
- Repository structure
- Design principles
- Roadmap
- Contributing guidelines
- Requirements

The skill only updates specific documentation sections while preserving all other README content.

## Examples

### Example 1: Sync After Adding New Skills

**Scenario**: You've added several new skills and want to update the README

```bash
# Create and register new skills
/skill/create data.transform "Transform data between formats"
/skill/define skills/data.transform/skill.yaml

/skill/create telemetry.report "Generate telemetry reports"
/skill/define skills/telemetry.report/skill.yaml

# Sync README to include new skills
/docs/sync/readme
```

**Output**:
```
INFO: Starting README.md sync from registries...
INFO: Loading registry files...
INFO: Generating updated README content...
INFO: ✅ Updated README.md
INFO:    - Foundation skills: 5
INFO:    - API skills: 4
INFO:    - Infrastructure skills: 11
INFO:    - Governance skills: 1
INFO:    - Total active skills: 21
INFO:    - Agents: 2
```

### Example 2: Sync After Adding New Agent

**Scenario**: A new agent has been registered and needs to appear in README

```bash
# Define new agent
/agent/define agents/workflow.optimizer/agent.yaml

# Sync README
/docs/sync/readme
```

The new agent will appear in the "### Agents Documentation" section.

### Example 3: Automated Sync in Workflow

**Scenario**: Include README sync as a workflow step after registering skills

```yaml
# workflows/skill_release.yaml
steps:
  - skill: skill.define
    args: ["skills/new.skill/skill.yaml"]

  - skill: plugin.sync
    args: []

  - skill: docs.sync.readme
    args: []
```

This ensures README, plugin.yaml, and registries stay in sync.

## Integration

### With skill.define

After defining skills, sync the README:

```bash
/skill/define skills/my.skill/skill.yaml
/docs/sync/readme
```

### With agent.define

After defining agents, sync the README:

```bash
/agent/define agents/my.agent/agent.yaml
/docs/sync/readme
```

### With Hooks

Auto-sync README when registries change:

```yaml
# .claude/hooks.yaml
- event: on_file_save
  pattern: "registry/*.json"
  command: python skills/docs.sync.readme/readme_sync.py
  blocking: false
  description: Auto-sync README when registries change
```

### With plugin.sync

Chain both sync operations:

```bash
/plugin/sync && /docs/sync/readme
```

## Categorization Rules

### Foundation Category

**Criteria**:
- Skill name starts with: `skill.`, `registry.`, `workflow.`
- Core Betty framework functionality

**Examples**:
- `skill.create`, `skill.define`
- `registry.update`, `registry.query`
- `workflow.compose`, `workflow.validate`

### API Category

**Criteria**:
- Skill name starts with: `api.`
- Tags include: `api`, `openapi`, `asyncapi`