import from local vendored copy (2026-05-06)

.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

.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

.molecule-ci/scripts/requirements.txt

@@ -0,0 +1 @@
+pyyaml>=6.0

.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)}")

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/<date>.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/<file>.md` | Architecture docs when features are added/removed/changed |
+| `docs/edit-history/<date>.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.

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.

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

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.)*

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

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