Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
6 changes: 1 addition & 5 deletions .github/ISSUE_TEMPLATE/config.yml
Original file line number Diff line number Diff line change
@@ -1,5 +1 @@
blank_issues_enabled: false
contact_links:
- name: Discussion / Question
url: https://github.com/mmilanez/lead-protocol/discussions
about: For questions, ideas, or general discussion — not bugs or features.
blank_issues_enabled: false
230 changes: 115 additions & 115 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,115 +1,115 @@
# Contributing to Lead Protocol

Thank you for your interest in contributing to the Lead Protocol. This document explains how to get involved.

---

## How to contribute

### Reporting bugs

Open an [issue](https://github.com/mmilanez/lead-protocol/issues/new) with:

- A clear title describing the problem
- Steps to reproduce
- Expected vs. actual behavior
- Your environment (OS, tool versions)

### Suggesting features

Open an issue with the `enhancement` label. Describe:

- The problem you're trying to solve
- Your proposed solution
- Why this belongs in the protocol (vs. a project-specific customization)

### Submitting code

1. **Fork** this repository
2. **Create a branch** from `main`:
- `feat/<description>` for new features
- `fix/<description>` for bug fixes
- `docs/<description>` for documentation changes
3. **Make your changes** — keep commits focused and atomic
4. **Test** your changes locally
5. **Open a Pull Request** against `main` with a clear description of what and why

### Commit messages

For human contributors, use clear conventional commit messages:

```
feat: add JSON Schema validation for handoff.md
fix: correct takeover rule timestamp comparison
docs: clarify recovery mode procedure
```

AI agents working on this repo follow the `[Agent] <type>: <summary>` convention defined in `.agents/PROTOCOL_RULES.md`.

---

## What makes a good contribution

### We welcome

- Bug fixes and improvements to the CLI, schemas, or MCP server
- New `PROJECT_RULES.md` templates for different industries/use cases
- Documentation improvements (typos, clarity, examples)
- Test coverage for existing functionality
- Integrations with new AI coding agents or IDEs

### Please avoid

- Changes to `PROTOCOL_RULES.md` without discussion — this is the framework layer and follows a controlled upgrade path
- Adding vendor-specific dependencies — the protocol must remain LLM-agnostic
- Over-engineering simple features — the protocol's value is in its simplicity
- Marketing language in documentation — be technical and direct

---

## Code style

- Keep code simple and readable
- Write tests for new functionality
- Follow existing patterns in the codebase
- No unnecessary abstractions — three similar lines are better than a premature abstraction

---

## Protocol files

If your contribution touches the `.agents/` directory:

- **`PROTOCOL_RULES.md`** — do not modify directly. Propose changes via an issue first.
- **`PROJECT_RULES.md`** — bump version (`X.Y`) on structural changes.
- **`handoff.md`** — follows an immutable schema. Do not add new fields.
- **`decisions.json`** — append-only. Never edit past entries.

---

## Review process

1. A maintainer will review your PR within a few days
2. Feedback may be requested — this is normal and collaborative
3. Once approved, a maintainer will merge your PR
4. Your contribution will be credited in the git history

---

## Dogfooding workflow

The Lead Protocol is developed using itself. Maintainers may keep a private development workspace that runs the protocol on every session — each architectural decision is recorded in `decisions.jsonl`, significant deliveries are promoted to `JOURNAL.md`, and agent state is tracked per-pair in `local/<actor>/<agent>/handoff.md`.

Finished artifacts (schemas, scripts, module files, documentation) are then published to this public repository as releases. This means:

- The `.agents/` directory in this repo is the **distributable scaffold** — pristine, consumer-ready.
- The private workspace carries the real operational history.
- Contributors never see private operational state; they see only the polished product.

This is the recommended pattern for any team that wants to use Lead Protocol to develop Lead Protocol — or any other protocol-governed project where operational history is private.

---

## Questions?

Open a [Discussion](https://github.com/mmilanez/lead-protocol/discussions) or an issue. We're happy to help you get started.
# Contributing to Lead Protocol
Thank you for your interest in contributing to the Lead Protocol. This document explains how to get involved.
---
## How to contribute
### Reporting bugs
Open an [issue](https://github.com/mmilanez/lead-protocol/issues/new) with:
- A clear title describing the problem
- Steps to reproduce
- Expected vs. actual behavior
- Your environment (OS, tool versions)
### Suggesting features
Open an issue with the `enhancement` label. Describe:
- The problem you're trying to solve
- Your proposed solution
- Why this belongs in the protocol (vs. a project-specific customization)
### Submitting code
1. **Fork** this repository
2. **Create a branch** from `main`:
- `feat/<description>` for new features
- `fix/<description>` for bug fixes
- `docs/<description>` for documentation changes
3. **Make your changes** — keep commits focused and atomic
4. **Test** your changes locally
5. **Open a Pull Request** against `main` with a clear description of what and why
### Commit messages
For human contributors, use clear conventional commit messages:
```
feat: add JSON Schema validation for handoff.md
fix: correct takeover rule timestamp comparison
docs: clarify recovery mode procedure
```
AI agents working on this repo follow the `[Agent] <type>: <summary>` convention defined in `.agents/PROTOCOL_RULES.md`.
---
## What makes a good contribution
### We welcome
- Bug fixes and improvements to the CLI, schemas, or MCP server
- New `PROJECT_RULES.md` templates for different industries/use cases
- Documentation improvements (typos, clarity, examples)
- Test coverage for existing functionality
- Integrations with new AI coding agents or IDEs
### Please avoid
- Changes to `PROTOCOL_RULES.md` without discussion — this is the framework layer and follows a controlled upgrade path
- Adding vendor-specific dependencies — the protocol must remain LLM-agnostic
- Over-engineering simple features — the protocol's value is in its simplicity
- Marketing language in documentation — be technical and direct
---
## Code style
- Keep code simple and readable
- Write tests for new functionality
- Follow existing patterns in the codebase
- No unnecessary abstractions — three similar lines are better than a premature abstraction
---
## Protocol files
If your contribution touches the `.agents/` directory:
- **`PROTOCOL_RULES.md`** — do not modify directly. Propose changes via an issue first.
- **`PROJECT_RULES.md`** — bump version (`X.Y`) on structural changes.
- **`handoff.md`** — follows an immutable schema. Do not add new fields.
- **`decisions.json`** — append-only. Never edit past entries.
---
## Review process
1. A maintainer will review your PR within a few days
2. Feedback may be requested — this is normal and collaborative
3. Once approved, a maintainer will merge your PR
4. Your contribution will be credited in the git history
---
## Dogfooding workflow
The Lead Protocol is developed using itself. Maintainers may keep a private development workspace that runs the protocol on every session — each architectural decision is recorded in `decisions.jsonl`, significant deliveries are promoted to `JOURNAL.md`, and agent state is tracked per-pair in `local/<actor>/<agent>/handoff.md`.
Finished artifacts (schemas, scripts, module files, documentation) are then published to this public repository as releases. This means:
- The `.agents/` directory in this repo is the **distributable scaffold** — pristine, consumer-ready.
- The private workspace carries the real operational history.
- Contributors never see private operational state; they see only the polished product.
This is the recommended pattern for any team that wants to use Lead Protocol to develop Lead Protocol — or any other protocol-governed project where operational history is private.
---
## Questions?
Open an [issue](https://github.com/mmilanez/lead-protocol/issues). We're happy to help you get started.
Loading