Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
116 lines (86 loc) · 3.65 KB

CONTRIBUTING.md

File metadata and controls

116 lines (86 loc) · 3.65 KB

Contributing to Charter Kit

Thanks for contributing. This repo is a PNPM workspace for offline governance tooling.

Development Setup

git clone https://github.com/stackbilt-dev/charter.git
cd charter
pnpm install
pnpm run build

Project Structure

packages/
  types/      Shared TypeScript contracts
  core/       Schemas, sanitization, shared errors
  adf/        ADF parser, formatter, patcher, bundler (AI context format)
  git/        Git trailer parsing and risk scoring
  classify/   Heuristic change classification
  validate/   Citation and governance validation
  drift/      Anti-pattern drift scanning
  cli/        CLI tool (`charter`)
  ci/         GitHub Actions integration helpers

Local Validation Before PR

Run these from the repo root:

pnpm run typecheck
pnpm run build
node packages/cli/dist/bin.js doctor --format json

If you changed CLI behavior, include at least one command sample in your PR body.

Commit and PR Standards

Use Conventional Commits:

  • feat(git): add support for custom trailer names
  • fix(drift): handle empty anti-pattern strings
  • docs: update CLI usage examples

PR checklist:

  1. Keep scope focused (single concern per PR)
  2. Describe what changed and why
  3. Link related issue(s)
  4. Include command output/screenshots for behavior changes
  5. Confirm pnpm run build passes
  6. If CLI UX or setup behavior changes, update README.md, packages/cli/README.md, and CHANGELOG.md in the same PR

Code Standards

  • TypeScript strict: true across all packages
  • No runtime dependency on cloud services
  • Pure functions preferred; side effects in CLI command handlers only
  • No LLM API calls in this kit (heuristic-only runtime)

What Belongs Here vs External Services

Belongs here (offline, local-first):

  • Heuristic classifiers and validators
  • Schema definitions and validation
  • Git integration logic
  • ADF context format parsing, formatting, and patching
  • CLI commands and local config parsing

Handled by external services (not in this repo):

  • LLM-powered analysis requiring cloud API calls
  • Database operations and multi-tenant runtime features
  • AuthN/AuthZ and hosted frontend concerns

Claude Code Setup

This repo ships with Claude Code skills and permissions config in .claude/.

Tracked (shared with all contributors):

  • .claude/skills/ — project workflows (/commit, /release, /issue, /test)
  • .claude/settings.json — stable Bash permissions and PostToolUse hooks
  • CLAUDE.md / AGENTS.md — thin pointers routing agents to .ai/ modules

Not tracked (create your own):

  • .claude/settings.local.json — personal overrides, MCP server config, WSL/machine-specific permissions

To add personal overrides, create .claude/settings.local.json:

{
  "permissions": {
    "allow": ["Bash(wslview:*)"]
  },
  "enabledMcpjsonServers": ["your-mcp-server"]
}

Reporting Issues

Use GitHub Issues for bugs/features. Include Node.js version, OS, and charter --version output. For security issues, follow SECURITY.md.

Papers Workflow

  • GitHub Issues/PRs are the canonical tracker for active engineering work.
  • papers/ is a curated narrative layer (feedback, research, release plans), not a full mirror of all links.
  • New AGENT_DX_FEEDBACK_*.md files must include frontmatter keys required by scripts/papers-lint.mjs: feedback-id, date, source, severity, bucket, status, tracked-issues, tracked-prs.
  • Release plans under papers/releases/*-plan.md must include the release-plan frontmatter schema validated by scripts/papers-lint.mjs.

License

By contributing, you agree that contributions are licensed under Apache License 2.0.