Skip to content

Latest commit

 

History

History
94 lines (70 loc) · 3.55 KB

CONTRIBUTING.md

File metadata and controls

94 lines (70 loc) · 3.55 KB

Contributing

Thank you for contributing to Codebase Knowledge Builder. This repository ships one canonical, content-only Agent Skill plus package and plugin metadata. Keep behavior in skills/codebase-knowledge-builder/; do not create platform-specific copies of the skill.

By participating, you agree to follow the Code of Conduct.

Reporting bugs

Open an issue using the Bug report template. Include:

  • What you expected to happen
  • What actually happened
  • The agent or host you are using
  • The installation method and skill revision or package version
  • Any error messages or unexpected output

Issues are public. Never post secrets, tokens, private repository URLs, proprietary code, personal data, or unredacted knowledge artifacts. Use a minimal synthetic reproduction or redact sensitive details. Report security vulnerabilities through the private process in SECURITY.md.

Suggesting improvements

Open an issue using the Feature request template. Describe the problem you're solving, not just the solution you want. Context helps.

Pull requests

  1. Fork the repository and create a branch from master.
  2. Make one focused change.
  3. Update the canonical skill, its bundled resources, and affected metadata together when their contract changes.
  4. Run the validation below.
  5. Open a pull request and describe the change, evidence, and any validation you could not run.

Repository layout

  • skills/codebase-knowledge-builder/SKILL.md: canonical skill instructions
  • skills/codebase-knowledge-builder/references/: material loaded when needed
  • skills/codebase-knowledge-builder/templates/: reusable artifact templates
  • .codex-plugin/, .claude-plugin/, and .agents/plugins/: distribution metadata
  • package.json: npm package metadata and the package file allowlist

Do not duplicate the canonical skill for individual agents. Compatibility changes should improve the shared instructions or metadata unless a platform requires a narrowly scoped manifest.

Validation

Run these commands from the repository root. They work in PowerShell, Command Prompt, and POSIX-compatible shells when Git, Node.js, and npm are available.

npx --yes markdownlint-cli2@0.23.2 "**/*.md" "!**/.planning/**" "llms.txt"
npx --yes skills@1.5.23 add "." --list
npm pack --dry-run --json --ignore-scripts
git diff --check

The discovery command must find codebase-knowledge-builder. Inspect the npm dry-run file list and confirm it contains the canonical skill and intended metadata, but excludes planning files, caches, dependencies, and generated ClawHub staging files.

When behavior changes, also run the skill against a public or synthetic fixture. Check that the output is source-cited, bounded to the requested scope, and free of secrets or unsupported claims. Do not use a private codebase as public test evidence.

What makes a good PR

  • One concern per PR. Don't bundle unrelated changes.
  • Keep SKILL.md focused. Move detailed, selectively loaded guidance to references/ and link it from the canonical skill.
  • Preserve the read-only default, scope boundaries, redaction rules, and evidence labels when changing behavior.
  • Keep package manifests and their version fields consistent when they change.
  • Test behavior changes with at least one public or synthetic codebase before submitting.

Style

  • Use direct, platform-neutral instructions.
  • Make claims proportional to the available evidence.
  • Write human-facing documentation in plain language.

Code of conduct

See CODE_OF_CONDUCT.md.