From fe9e2f15e048b95c425004c8476a555146323724 Mon Sep 17 00:00:00 2001 From: Hongming Wang Date: Wed, 6 May 2026 13:53:36 -0700 Subject: [PATCH] import from local vendored copy (2026-05-06) --- .github/workflows/ci.yml | 5 ++ .gitignore | 21 ++++++ .molecule-ci/scripts/requirements.txt | 1 + .molecule-ci/scripts/validate-plugin.py | 52 +++++++++++++ CLAUDE.md | 97 +++++++++++++++++++++++++ README.md | 36 +++++++++ adapters/__init__.py | 0 adapters/claude_code.py | 2 + known-issues.md | 57 +++++++++++++++ plugin.yaml | 12 +++ skills/update-docs/SKILL.md | 90 +++++++++++++++++++++++ 11 files changed, 373 insertions(+) create mode 100644 .github/workflows/ci.yml create mode 100644 .gitignore create mode 100644 .molecule-ci/scripts/requirements.txt create mode 100644 .molecule-ci/scripts/validate-plugin.py create mode 100644 CLAUDE.md create mode 100644 README.md create mode 100644 adapters/__init__.py create mode 100644 adapters/claude_code.py create mode 100644 known-issues.md create mode 100644 plugin.yaml create mode 100644 skills/update-docs/SKILL.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..c8fb9d3 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,5 @@ +name: CI +on: [push, pull_request] +jobs: + validate: + uses: Molecule-AI/molecule-ci/.github/workflows/validate-plugin.yml@main diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2af45b5 --- /dev/null +++ b/.gitignore @@ -0,0 +1,21 @@ +# Credentials — never commit. Use .env.example as the template. +.env +.env.local +.env.*.local +.env.* +!.env.example +!.env.sample + +# Private keys + certs +*.pem +*.key +*.crt +*.p12 +*.pfx + +# Secret directories +.secrets/ + +# Workspace auth tokens +.auth-token +.auth_token diff --git a/.molecule-ci/scripts/requirements.txt b/.molecule-ci/scripts/requirements.txt new file mode 100644 index 0000000..3aecde9 --- /dev/null +++ b/.molecule-ci/scripts/requirements.txt @@ -0,0 +1 @@ +pyyaml>=6.0 diff --git a/.molecule-ci/scripts/validate-plugin.py b/.molecule-ci/scripts/validate-plugin.py new file mode 100644 index 0000000..c42e916 --- /dev/null +++ b/.molecule-ci/scripts/validate-plugin.py @@ -0,0 +1,52 @@ +#!/usr/bin/env python3 +"""Validate a Molecule AI plugin repo.""" +import os, sys, yaml + +errors = [] + +# 1. plugin.yaml exists +if not os.path.isfile("plugin.yaml"): + print("::error::plugin.yaml not found at repo root") + sys.exit(1) + +with open("plugin.yaml") as f: + plugin = yaml.safe_load(f) + +# 2. Required fields +for field in ["name", "version", "description"]: + if not plugin.get(field): + errors.append(f"Missing required field: {field}") + +# 3. Version format +v = str(plugin.get("version", "")) +if v and not all(c in "0123456789." for c in v): + errors.append(f"Invalid version format: {v}") + +# 4. Runtimes type +runtimes = plugin.get("runtimes") +if runtimes is not None and not isinstance(runtimes, list): + errors.append(f"runtimes must be a list, got {type(runtimes).__name__}") + +# 5. Has content +content_paths = ["SKILL.md", "hooks", "skills", "rules"] +found = [p for p in content_paths if os.path.exists(p)] +if not found: + errors.append("Plugin must contain at least one of: SKILL.md, hooks/, skills/, rules/") + +# 6. SKILL.md formatting check +if os.path.isfile("SKILL.md"): + with open("SKILL.md") as f: + first_line = f.readline().strip() + if first_line and not first_line.startswith("#"): + print("::warning::SKILL.md should start with a markdown heading (e.g., # Plugin Name)") + +if errors: + for e in errors: + print(f"::error::{e}") + sys.exit(1) + +print(f"✓ plugin.yaml valid: {plugin['name']} v{plugin['version']}") +if found: + print(f" Content: {', '.join(found)}") +if runtimes: + print(f" Runtimes: {', '.join(runtimes)}") diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..bdb9242 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,97 @@ +# molecule-ai-plugin-molecule-skill-update-docs + +After any code change, review recent edits and update all documentation: +architecture docs, API specs, edit history, README mirrors, runbooks, and +`.env.example`. Creates missing documentation for new implementations. + +Run this skill after merging a PR that changes behavior, adds features, or +introduces new files. + +**Version:** 1.0.0 +**Runtime:** `claude_code`, `hermes` +**Skill:** `update-docs` + +--- + +## What It Does (12-step workflow) + +1. **Read today's edit history** — read `docs/edit-history/.md` to find what changed today. +2. **Analyze changes** — read modified files; categorize as new feature, bug fix, architecture change, API change, or config change. +3. **Update edit-history session file** — add a summary at the top grouped under headings. +4. **Update CLAUDE.md** — new commands/scripts, architecture changes, new env vars, new routes/endpoints, test counts. +5. **Update PLAN.md** — mark completed phases, add follow-ups, keep current status in sync. +6. **Update README.md** — new user-visible features, setup changes, tech stack changes, test count badges. +7. **Update README.zh-CN.md** — mirror user-visible changes from README.md; keep translations in sync. +8. **Update .env.example** — every new env var must be documented with a comment; remove deprecated vars. +9. **Update docs/README.md** — new features, setup instructions, project overview. +10. **Update docs/ files** — check each doc for outdated sections; update or create as needed. +11. **Create new docs** — if a feature has no documentation, create appropriate docs following existing style. +12. **Report summary** — list all updated and created files. + +--- + +## What Gets Updated + +| Doc type | When to update | +|---|---| +| `CLAUDE.md` | New commands, architecture changes, env vars, test counts | +| `PLAN.md` | Completed phases, architectural decisions, next steps | +| `README.md` | User-visible features, setup changes, tech stack, badges | +| `README.zh-CN.md` | Mirror README.md changes; keep translations in sync | +| `.env.example` | Every new env var; remove deprecated vars | +| `docs/README.md` | New features, setup, project overview | +| `docs/.md` | Architecture docs when features are added/removed/changed | +| `docs/edit-history/.md` | Always updated at end of session | + +--- + +## Repository Layout + +``` +molecule-skill-update-docs/ +├── skills/ +│ └── update-docs/ +│ └── SKILL.md # Full 12-step skill definition +├── adapters/ +│ ├── __init__.py +│ └── claude_code.py # AgentskillsAdaptor (wraps plugins_registry) +├── plugin.yaml # Plugin manifest +└── README.md +``` + +--- + +## Key Conventions + +| Topic | Convention | +|---|---| +| **When to run** | After merging a PR; explicitly triggered by `/update-docs` | +| **Edit history** | One session file per date: `docs/edit-history/YYYY-MM-DD.md` | +| **Env vars** | All vars read by code must be in `.env.example` with a comment | +| **README sync** | `README.zh-CN.md` must mirror `README.md` — never let them drift | +| **New docs** | Follow existing style and structure of the repo's docs | +| **Deprecations** | When removing features, mark as deprecated — do not silently delete docs | + +--- + +## Development + +```bash +# Verify docs/edit-history/ directory exists +ls docs/edit-history/ + +# Check for missing env var documentation +diff <(grep -h 'process.env' src/**/*.ts | sed 's/.*process.env.\([A-Z_]*\).*/\1/' | sort -u) \ + <(grep '^#\|^[A-Z]' .env.example | sed 's/ .*//' | sort -u) + +# Run the skill (if Hermes/cron context) +# After a PR merge, invoke via the update-docs skill or /update-docs command +``` + +--- + +## Relationship to Other Plugins + +- Used by `molecule-workflow-triage` — `/triage` workflow calls `update-docs` as a sub-step. +- Complements `molecule-audit-trail` — audit-trail records what changed; update-docs records the documentation impact. +- Pairs with `molecule-skill-cron-learnings` — learnings may flag docs that need updating. diff --git a/README.md b/README.md new file mode 100644 index 0000000..4234743 --- /dev/null +++ b/README.md @@ -0,0 +1,36 @@ +# molecule-skill-update-docs — Documentation Sync + +Plugin for Claude Code and Hermes. After any code change, review recent edits and +update all documentation: architecture docs, API specs, runbooks, edit history, and +README mirrors. Creates missing docs for new implementations. + +## When to use + +After merging a PR that changes behavior, adds features, or introduces new files. +Run the `update-docs` skill to audit what docs need updating. + +## What it updates + +| Doc type | What to check | +|----------|---------------| +| Architecture docs | New components, changed data flows, updated dependencies | +| API specs | New endpoints, changed request/response shapes, auth changes | +| Edit history | Session log entry with what changed and why | +| README mirrors | Updated descriptions of plugin capabilities | +| Runbooks | Updated operational procedures after incidents or changes | + +## Installation + +### In org template (org.yaml) +```yaml +plugins: + - molecule-skill-update-docs +``` + +### From URL +``` +github://Molecule-AI/molecule-ai-plugin-molecule-skill-update-docs +``` + +## License +Business Source License 1.1 — © Molecule AI. diff --git a/adapters/__init__.py b/adapters/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/adapters/claude_code.py b/adapters/claude_code.py new file mode 100644 index 0000000..cc58993 --- /dev/null +++ b/adapters/claude_code.py @@ -0,0 +1,2 @@ +"""Claude Code adaptor — uses the generic rule+skill+hooks installer.""" +from plugins_registry.builtins import AgentskillsAdaptor as Adaptor # noqa: F401 diff --git a/known-issues.md b/known-issues.md new file mode 100644 index 0000000..9b88743 --- /dev/null +++ b/known-issues.md @@ -0,0 +1,57 @@ +# Known Issues + +Active and recently resolved issues for `molecule-skill-update-docs`. + +--- + +## Active Issues + +*(None currently open. File an issue if you encounter a problem.)* + +--- + +## Known Gotchas + +### README.zh-CN.md sync can drift silently + +**Severity:** Medium +**Detail:** The skill updates README.zh-CN.md after README.md but does not independently verify that translations remain accurate — it mirrors the English text into Chinese sections, but does not re-translate. If a developer edits README.zh-CN.md directly (e.g., to correct a translation), subsequent `update-docs` runs may overwrite those corrections. + +**Workaround:** Keep corrections in a separate `docs/translation-notes.md` file that the skill is instructed to preserve. Alternatively, review README.zh-CN.md changes before committing. + +--- + +### `.env.example` detection is heuristic — false negatives possible + +**Severity:** Low +**Detail:** The skill uses `process.env` pattern matching to find env vars in source code. This approach can miss: +- Vars read via `os.environ["VAR"]` (Python) +- Vars accessed via `os.Getenv("VAR")` (Go) +- Vars injected at build time (Webpack, Vite) +- Vars accessed via a config struct that is populated from env at runtime + +**Workaround:** Manually audit `.env.example` after adding new configuration. Use `grep -r 'ENV\|env\|getenv\|environ' src/ | grep -v '.env.example'` to find additional vars the skill might miss. + +--- + +### No automatic invocation — must be triggered explicitly + +**Severity:** Informational +**Detail:** The skill does not auto-run. It must be explicitly invoked (via `/update-docs` command or skill call). In CI/CD workflows, this means docs can become stale between runs if developers forget to invoke the skill. + +**Workaround:** Add a CI step that warns (not fails) if `git diff --name-only` shows doc-relevant files were modified but `docs/edit-history/` was not updated in the same PR. + +--- + +### docs/edit-history/ date-based naming requires timezone awareness + +**Severity:** Low +**Detail:** The edit history file is named by date (`YYYY-MM-DD`). The date used is derived from the system clock at the time of the run. In distributed cron setups across timezones, the same work session may log to two different date files. + +**Workaround:** Use UTC consistently for `docs/edit-history/` file naming, regardless of local timezone. + +--- + +## Recently Resolved + +*(None yet.)* diff --git a/plugin.yaml b/plugin.yaml new file mode 100644 index 0000000..299b8f0 --- /dev/null +++ b/plugin.yaml @@ -0,0 +1,12 @@ +name: molecule-skill-update-docs +version: 1.0.0 +description: Review recent edits and update all documentation (architecture docs, API specs, edit history, README mirrors). Creates missing docs for new implementations. +author: Molecule AI +tags: [molecule, guardrails, documentation] + +runtimes: + - claude_code + - hermes + +skills: + - update-docs \ No newline at end of file diff --git a/skills/update-docs/SKILL.md b/skills/update-docs/SKILL.md new file mode 100644 index 0000000..87c3958 --- /dev/null +++ b/skills/update-docs/SKILL.md @@ -0,0 +1,90 @@ +--- +name: update-docs +description: "Review recent edits and update all documentation including architecture docs, API specs, and edit history. Creates missing docs for new implementations." +origin: molecule-skill-update-docs +--- + +# Update Documentation + +Review recent code changes and update ALL relevant documentation in the `/docs` folder. + +## Steps + +1. **Read today's edit history** + + - Check `docs/edit-history/` for the current date's session file + - Identify all files that were modified + +2. **Analyze changes** + + - Read the modified files to understand what changed + - Categorize changes: new features, bug fixes, architecture changes, API changes, config changes + +3. **Update edit-history session file** + + - Add a summary section at the top describing what was accomplished + - Group related changes under descriptive headings + - Add any missing context about why changes were made + +4. **Update CLAUDE.md if needed** + + - New commands or scripts added + - Architecture or key modules changed + - New environment variables required + - New routes or endpoints added + - Test counts when new test files were added + +5. **Update PLAN.md (repo root) if needed** + + - When a planned phase ships, mark it complete and add any follow-ups + - When new architectural decisions are made, update the relevant phase + - Keep the current status / next steps section in sync with reality + - If a feature was reverted, document the reversal and reasoning + +6. **Update README.md (repo root) if needed** + + - New features visible to users (canvas tabs, deploy flows, etc.) + - Changed setup or quickstart instructions + - Updated tech stack list (when adding/removing major dependencies) + - Updated test counts in the status badges + - License or branding changes + +7. **Update README.zh-CN.md (repo root) if README.md was updated** + + - Mirror any user-visible changes from README.md + - Keep the Chinese translation in sync — don't let it drift + - Update the same sections in both files (status, features, setup, license) + +8. **Update .env.example (repo root) if needed** + + - Every new env var read by code must be documented in `.env.example` + - Include a comment describing the var and its expected format + - When removing an env var from code, remove from `.env.example` + - Keep default values consistent with code defaults + +9. **Update docs/README.md if needed** + + - New features or capabilities + - Changed setup instructions + - Updated project overview + +10. **Update docs/ files** + Review and update all architecture documentation to match current implementation + + **For each doc:** + + - Check if documented features match actual code implementation + - Update outdated sections to reflect current code + - Add NEW sections for features that are implemented but not documented + - Remove or mark deprecated features that no longer exist + - Ensure code examples match actual implementation + +11. **Create new docs if needed** + + - If a significant new feature or module was added but has no documentation, create appropriate documentation + - Follow existing documentation style and structure + +12. **Report summary** + - List all documentation files updated + - Note any new documentation files created + - Summarize key changes documented