70 lines
3.1 KiB
Markdown
70 lines
3.1 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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.
|