Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
129 lines (85 loc) · 4.43 KB

CONTRIBUTING.md

File metadata and controls

129 lines (85 loc) · 4.43 KB

Contributing to Project Workflow Protocol

Thank you for your interest in contributing. We welcome community input, but we are extremely strict about what gets merged.

This protocol exists to enforce a high quality bar. Any contribution that dilutes that bar will be rejected.

Core Principle: This protocol optimizes for long-term quality over short-term speed.

Repository Structure

Before contributing, understand where things live:

Directory Contains Extension Convention
protocol/ Core process modules (00-09) .md
protocol/ai-agents/ AI-specific constraint modules (00-10) .md
templates/ Copy-paste-ready templates .md
skills/ Drop-in AI agent skill files .skill.md
examples/ Real-world adoption scenarios .md

What We Accept

We welcome PRs that:

  • Clarify intent — If a rule is ambiguous, help us make it precise.
  • Add examples — Real-world scenarios that show the protocol in action.
  • Handle edge cases — "What if X happens?" scenarios we missed.
  • Adapt tooling — Scripts or configs that enforce the protocol automatically.
  • Share learnings — "This failed for us because..." reports with concrete evidence.
  • Improve cross-references — Links between related modules that we missed.
  • Add task-specific skills — New .skill.md files for common engineering tasks (must follow existing format).

What We Reject

We will close PRs that:

  • Dilute standards — e.g., "Make pre-merge verification optional."
  • Add shortcuts — "Just let us merge to main for small fixes."
  • Promote unproven opinions — "We should use X instead" without production evidence.
  • Add clutter — Framework-specific files that belong in examples/, not protocol/.
  • Break traceability — Changes that remove plan IDs, cross-references, or audit trails.

Contribution Types

Protocol Module Changes

Changes to protocol/*.md or protocol/ai-agents/*.md:

  1. Must preserve or add the **Related:** cross-reference footer at the bottom of each file.
  2. Must not break existing cross-references in other modules.
  3. Must follow the existing numbering convention (e.g., 07-testing.md, 08-deployment.md).

New Skill Files

New files in skills/:

  1. Filename: {skill-name}.skill.md (kebab-case).
  2. YAML Frontmatter (required): 
    ---
name: {skill-name}
version: 0.3.0
description: One-line description of what the skill covers.
extends: Project Workflow Protocol
---
  3. Must include concrete rules, not vague guidelines.
  4. Must include verification steps or checklists.

Template Changes

Changes to templates/*.md:

  1. Templates must remain copy-paste ready — no project-specific content.
  2. Placeholder values should use {curly braces} for fields to fill in.

Example Additions

Changes to examples/*.md:

  1. Must represent a real or realistic adoption scenario.
  2. Must reference specific protocol modules and templates by filename.

The Process

  1. Check Issues — See if the discussion is already happening.
  2. Open an Issue — Propose your change before writing code. Use the appropriate issue template.
  3. Draft PR — Link to your issue. Use the PR template (.github/pull_request_template.md).
  4. Review — Expect strict feedback on tone, precision, and alignment with protocol standards.

PR Checklist

Before submitting, ensure:

  • All modified protocol modules retain their **Related:** footer
  • New skill files include correct YAML frontmatter with version field
  • No broken cross-references (links to other protocol files)
  • Changes documented in CHANGELOG format (Added / Changed / Removed)
  • No trailing whitespace, consistent formatting

Versioning

This project follows Semantic Versioning. The current version is v0.3.0 (Professional Edition).

  • Patch (0.3.x): Typo fixes, clarifications, new examples
  • Minor (0.x.0): New modules, new templates, new skills
  • Major (x.0.0): Breaking changes to core protocol structure

Reporting Vulnerabilities

If you find a security concern in the protocol itself (e.g., a rule that could enable unsafe practices), please follow the process in SECURITY.md.

License

By contributing, you agree that your contributions will be licensed under the MIT License.