491 lines
12 KiB
Markdown
491 lines
12 KiB
Markdown
---
|
||
name: Documentation README Sync
|
||
description: Automatically regenerate README.md from Betty Framework registries
|
||
---
|
||
|
||
# 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`
|
||
|
||
**Examples**:
|
||
- `api.define`, `api.validate`
|
||
- `api.generate-models`, `api.compatibility`
|
||
|
||
### Infrastructure Category
|
||
|
||
**Criteria**:
|
||
- Tags include: `agents`, `command`, `hook`, `policy`, `plugin`, `registry`
|
||
- Infrastructure and orchestration skills
|
||
|
||
**Examples**:
|
||
- `agent.define`, `agent.run`
|
||
- `hook.define`, `hook.register`
|
||
- `plugin.sync`, `plugin.build`
|
||
|
||
### Governance Category
|
||
|
||
**Criteria**:
|
||
- Tags include: `governance`, `policy`, `audit`
|
||
- Policy enforcement and audit trails
|
||
|
||
**Examples**:
|
||
- `policy.enforce`
|
||
- `audit.log`
|
||
|
||
## Filtering Rules
|
||
|
||
### ✅ Included
|
||
|
||
- Skills with `status: active`
|
||
- Agents with `status: active` or `status: draft`
|
||
- Skills with meaningful descriptions
|
||
|
||
### ❌ Excluded
|
||
|
||
- Skills with `status: draft`
|
||
- Skills starting with `test.`
|
||
- Skills without names or descriptions
|
||
|
||
## Common Errors
|
||
|
||
| Error | Cause | Solution |
|
||
|-------|-------|----------|
|
||
| "README.md not found" | Missing README file | Ensure README.md exists in repo root |
|
||
| "Registry file not found" | Missing registry | Run skill.define to populate registry |
|
||
| "Failed to parse JSON" | Invalid JSON | Fix JSON syntax in registry files |
|
||
|
||
## Files Read
|
||
|
||
- `README.md` – Current README content
|
||
- `registry/skills.json` – Skills registry
|
||
- `registry/agents.json` – Agents registry
|
||
|
||
## Files Modified
|
||
|
||
- `README.md` – Updated with current skills and agents
|
||
- `skills/docs.sync.readme/sync_report.json` – Sync statistics
|
||
|
||
## Exit Codes
|
||
|
||
- **0**: Success (README updated successfully)
|
||
- **1**: Failure (error during sync)
|
||
|
||
## Logging
|
||
|
||
Logs sync progress:
|
||
|
||
```
|
||
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: 9
|
||
INFO: - Governance skills: 1
|
||
INFO: - Total active skills: 19
|
||
INFO: - Agents: 2
|
||
```
|
||
|
||
## Best Practices
|
||
|
||
1. **Run After Registry Changes**: Sync README whenever skills or agents are added/updated
|
||
2. **Include in CI/CD**: Add README sync to deployment pipelines
|
||
3. **Review Before Commit**: Check updated README before committing changes
|
||
4. **Use Hooks**: Set up auto-sync hooks for convenience
|
||
5. **Combine with plugin.sync**: Keep both plugin.yaml and README in sync
|
||
6. **Version Control**: Always commit README changes with skill/agent changes
|
||
|
||
## Troubleshooting
|
||
|
||
### README Not Updating
|
||
|
||
**Problem**: Changes to registry don't appear in README
|
||
|
||
**Solutions**:
|
||
- Ensure skills have `status: active`
|
||
- Check that skill names and descriptions are present
|
||
- Verify registry files are valid JSON
|
||
- Run `/skill/define` before syncing README
|
||
|
||
### Skills in Wrong Category
|
||
|
||
**Problem**: Skill appears in unexpected category
|
||
|
||
**Solutions**:
|
||
- Check skill tags in skill.yaml
|
||
- Verify tag categorization rules above
|
||
- Add appropriate tags to skill.yaml
|
||
- Re-run skill.define to update registry
|
||
|
||
### Section Markers Not Found
|
||
|
||
**Problem**: "Section marker not found" warnings
|
||
|
||
**Solutions**:
|
||
- Ensure README has expected section headers
|
||
- Check for typos in section headers
|
||
- Restore original README structure if modified
|
||
- Update section_marker strings in code if intentionally changed
|
||
|
||
## Architecture
|
||
|
||
### Skill Categories
|
||
|
||
**Documentation** – docs.sync.readme maintains the README documentation layer by syncing registry state to the top-level README.
|
||
|
||
### Design Principles
|
||
|
||
- **Single Source of Truth**: Registries are the source of truth
|
||
- **Preserve Structure**: Only update specific sections
|
||
- **Maintain Style**: Keep original tone and formatting
|
||
- **Clear Categorization**: Logical grouping of skills by function
|
||
- **Idempotent**: Can be run multiple times safely
|
||
|
||
## See Also
|
||
|
||
- **plugin.sync** – Sync plugin.yaml with registries ([SKILL.md](../plugin.sync/SKILL.md))
|
||
- **skill.define** – Validate and register skills ([SKILL.md](../skill.define/SKILL.md))
|
||
- **agent.define** – Validate and register agents ([SKILL.md](../agent.define/SKILL.md))
|
||
- **registry.update** – Update registries ([SKILL.md](../registry.update/SKILL.md))
|
||
- **Betty Architecture** – Framework overview ([betty-architecture.md](../../docs/betty-architecture.md))
|
||
|
||
## Dependencies
|
||
|
||
- **registry.update**: Registry management
|
||
- **betty.config**: Configuration constants and paths
|
||
- **betty.logging_utils**: Logging infrastructure
|
||
|
||
## Status
|
||
|
||
**Active** – Production-ready documentation skill
|
||
|
||
## Version History
|
||
|
||
- **0.1.0** (Oct 2025) – Initial implementation with skills categorization and agents documentation
|