zhongwei/gh-epieczko-betty
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-29 18:26:08 +08:00
commit 8f22ddf339
295 changed files with 59710 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

490
skills/docs.sync.readme/SKILL.md Normal file
View File

@@ -0,0 +1,490 @@
---
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