Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
108 lines (77 loc) · 6.23 KB

CONTRIBUTING.md

File metadata and controls

108 lines (77 loc) · 6.23 KB

Contributing to the AIDD Framework

The source of truth for AIDD skills, agents, rules, and templates. Authored in Claude Code syntax; at release time the CLI generates archives adapted to each supported tool.

Wider AIDD community, roles, and the training programme live at ai-driven-dev.fr. This file covers contributing to this repository.

Who does what (by profile)

---
title: Contribution by profile
---
flowchart TD
    Start["Anyone: open an issue, idea or question"]
    Who{"Your profile?"}
    Pub["Public - discuss, react, upvote"]
    Core["Core Team - vote on roadmap priority"]
    Cert["Certifie AIDD - branch, commit, open PR"]
    Rev["Habilite AIDD - review (CODEOWNERS)"]
    Merge["Habilite AIDD - merge, release-please ships"]

    Start --> Who
    Who -->|Public| Pub
    Who -->|Core Team| Core
    Who -->|Certifie| Cert
    Cert --> Rev
    Rev --> Merge
Loading

Pull-request rights are held by Certifié and Habilité only (Certifié via certification, Habilité by promotion). Full role ladder, voting weights, and promotion: GOVERNANCE.md. The rest of this guide is the how for those opening PRs.

1. Set up

Needs Node 20+, pnpm, jq, python3, and pipx (gh and the Claude/Codex CLI optional). Then:

make setup
  • installs deps + git hooks
  • registers this checkout as a local marketplace
  • installs the plugins into Claude + Codex (y/N confirm, since it writes your global config; YES=1 skips)

make lists every target; make doctor / make check verify the environment and run the pre-commit checks.

Test your changes locally

Exercise the skills you touched before opening a PR. Neither tool hot-reloads the checkout (both serve a copied cache), so after editing:

make reload                        # all plugins; or PLUGIN="aidd-refine aidd-pm" for a subset
  • reinstalls each plugin from the checkout (current versions, no bump - nothing to revert)
  • Claude installs straight from the raw repo (already native Claude format); Codex installs from a tree the aidd CLI builds (Claude syntax -> Codex, e.g. agents -> TOML)
  • refreshes the cache in Claude + Codex; Codex agents are copied to ~/.codex/agents/ (Codex does not load plugin-bundled agents yet)
  • restart the session to load it (/reload-plugins covers a Claude-only edit to an existing skill)

2. Commit

Format: <type>(<scope>): description.

git commit -m "feat(aidd-dev): add for-sure skill"

One scope per commit (split cross-plugin changes). The types, the scopes, and the rules live in aidd_docs/memory/vcs.md - it mirrors commitlint.config.cjs, the source of truth. Type drives the release; see RELEASE.md for what each type produces.

3. Open a pull request

  • Branch off next and target next (the integration branch); hotfix/* branches off main for urgent production fixes. See RELEASE.md.

  • Fill the PR template (applied automatically): explain what changed and how you resolved it technically - that narrative is the point of the PR. The conventional title and pre-commit hooks are already enforced by CI, so don't spend the description re-asserting them.

  • Label the PR so reviewers and the Roadmap board triage at a glance:

    Label When to use
    bug A fix for broken behaviour.
    enhancement A new skill, agent, rule, or feature.
    documentation A docs-only change (README, CONTRIBUTING, skill docs).
    security A security-sensitive change or fix.

  • The PR title follows the same conventional format (the Commitlint CI job enforces it); PRs are squash-merged using that title.

  • A Habilité review gates every merge (CODEOWNERS); Certifié contributors cannot self-merge.

  • Decision rules (lazy consensus, explicit consensus for cross-plugin/contract changes, the quality veto) live in GOVERNANCE.md.

Releases

How releases flow (the main/next model, weekly cadence, hotfix, auto-merge) is in RELEASE.md; the release tooling is in aidd_docs/memory/vcs.md. What a release produces, for contributors:

  • 7 independently-versioned packages (root aidd-framework + the 6 plugins).
  • On release, CI attaches the bundles:
    • aidd-framework-marketplace-X.Y.Z.zip - the Claude Code marketplace (.claude-plugin/ + plugins/); kept as the legacy Claude alias of aidd-framework-claude-marketplace-X.Y.Z.zip.
    • <plugin>-vX.Y.Z.zip - per released plugin.
    • aidd-framework-<tool>-<mode>-X.Y.Z.zip - per-tool distributions built by aidd-cli (framework build) on the root release: 4 marketplace (claude/cursor/copilot/codex) + 5 flat (+opencode, flat-only) = 9 archives. Produced by the build-per-tool matrix job in .github/workflows/ci.yml, pinned to a specific @ai-driven-dev/cli version.

Reporting issues

Open an issue (🐛 Bug or ✨ Feature). New issues are auto-added to the AIDD Roadmap board. For usage questions, use Discussions, not issues (see SUPPORT.md).

Reference

  • Build a plugin - docs/CREATE_PLUGIN.md
  • Architecture & terms - docs/ARCHITECTURE.md, docs/GLOSSARY.md
  • Patterns to follow: a minimal plugin aidd-refine, a router skill 00-onboard, agents aidd-dev/agents.
  • Syntax & per-tool builds: source files use Claude Code syntax; at release time the aidd-cli generates an archive per supported tool, mapping each surface to that tool's equivalent. In frontmatter, name / description / argument-hint are universal; other keys (model, color, paths, …) are tool-specific and ignored where unsupported.

■ Back to framework