molecule-ai-plugin-ecc/rules/plugin-ecc-conventions.md

plugin-ecc Conventions

Plugin-specific rules for plugin-ecc. These complement the ECC ecosystem rules and are specific to how this plugin is packaged, released, and maintained.

Error Handling

• Parse errors in rules/skills: Log to stderr with a [PluginName] prefix and exit 0. Never block tool execution due to a malformed doc.
• Adapter errors: The adapters/ layer is a thin wrapper — any runtime errors from plugins_registry should propagate, not be swallowed.
• Markdown parse failures: If a markdown file fails to parse (missing frontmatter, broken sections), report in the agent response but do not abort the session.

Logging Patterns

• In hooks (via run-with-flags.js): Use console.error for diagnostic output — stdout is reserved for the JSON response.
• Prefix all log lines: [ECC] <component>: <message> — e.g., [ECC] guardrails: rule loaded, [ECC] adapter: init.
• No token/secret logging: Never log API keys, tokens, or user credentials, even at DEBUG level.
• Structured fields: Prefer console.error('[ECC] key=value key2=value2') over freeform strings for parseable output.

Config / Environment Variables

Variable	Purpose	Required
ECC_HOOK_PROFILE	Gate which hooks fire at runtime	No
ECC_DISABLED_HOOKS	Colon-separated list of hooks to skip	No
PLUGINS_REGISTRY_URL	Override registry base URL	No

• Validate required env vars at adapter init time. Fail fast with a clear message.
• No hardcoded defaults for credentials — require them to be set or inherited from the harness.

Release Process

Version Bump

1. Update version in plugin.yaml (semver: MAJOR.MINOR.PATCH).
2. Update version number in AGENTS.md (**Version:** X.Y.Z) if agents list changed.
3. Update **Version:** in CLAUDE.md if conventions changed.

Pre-Release Checklist

• All markdown files pass npx markdownlint '**/*.md' --ignore node_modules
• plugin.yaml is valid YAML and references all existing files
• No .pyc or __pycache__ files committed (gitignore covers this — verify)
• Changelog section in release notes covers: new rules, removed rules, breaking changes

Tag & Push

git tag -a vX.Y.Z -m "chore: release vX.Y.Z"
git push origin main
git push origin --tags

Post-Release

Create a GitHub Release with:

• Tag version and SHA
• ## Changelog section listing all changes since last release
• Any migration notes if rules/ or skills/ were reorganized

File Integrity

• All .md files committed to the plugin must be valid Markdown — test with npx markdownlint.
• No binary files in rules/, skills/, agents/, or commands/.
• The .gitignore must cover: __pycache__/, *.pyc, .DS_Store, editor backups.

Adapter Layer

• The adapters/claude_code.py file wraps the ECC ecosystem via plugins_registry.builtins.AgentskillsAdaptor.
• Do not add business logic to the adapter — keep it as a thin import shim.
• If the adapter needs configuration, add it to plugin.yaml under an adapter: section, not as code constants.