From c8eb5b513c3328b6f5cbe532a0c052105dd6488c Mon Sep 17 00:00:00 2001
From: CodeAlex52 <59381946+CodeAlex52@users.noreply.github.com>
Date: Sun, 11 Oct 2026 15:28:40 +0800
Subject: [PATCH] docs: add CONTRIBUTING and issue templates

---
 .github/ISSUE_TEMPLATE/bug_report.md      | 24 ++++++++++
 .github/ISSUE_TEMPLATE/feature_request.md | 20 ++++++++
 CONTRIBUTING.md                           | 56 +++++++++++++++++++++++
 3 files changed, 100 insertions(+)
 create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md
 create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md
 create mode 100644 CONTRIBUTING.md

diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
new file mode 100644
index 0000000..3b3a607
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,24 @@
+---
+name: Bug report
+about: Something misbehaves — include the failing command and expected vs actual
+title: "[BUG] "
+labels: bug
+---
+
+**Command / entry point**
+
+```bash
+# e.g. agentcorp run --project examples/demo_repo --prd ... --provider mock
+```
+
+**Expected vs actual**
+
+**Reproduction notes**
+
+- Does it reproduce with `--provider mock` and `FAST=1 ./scripts/reproduce_all.sh`?
+- Run id / DB path (`.agentcorp/...`) if the ledger is involved:
+
+**Environment**
+
+- `agentcorp --version`:
+- Python / OS:
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
new file mode 100644
index 0000000..7375264
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Propose a capability — frame it around the reliability concern it addresses
+title: "[FEATURE] "
+labels: enhancement
+---
+
+**Reliability concern**
+
+<!-- AgentCorp is built around failure paths: duplicate execution, crash recovery,
+retry storms, runaway cost, deadlocks, quarantine. What failure mode does this
+feature address? -->
+
+**Proposed behavior**
+
+**Alternatives considered**
+
+**Scope hints**
+
+<!-- CLI surface? engine/scheduler? store schema? docs/SPEC_v0.md impact? -->
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..6580432
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,56 @@
+# Contributing to AgentCorp
+
+Thanks for considering a contribution. AgentCorp is deliberately **offline-verifiable**:
+the whole reliability suite runs with no network and no API keys, and that property is
+part of the product contract — please help us keep it.
+
+## Development setup
+
+- Python **>= 3.12**
+- [uv](https://docs.astral.sh/uv/) is recommended; a plain venv works too
+
+```bash
+uv venv --python 3.12
+uv pip install -e ".[dev]"
+```
+
+## The one command that matters
+
+```bash
+./scripts/reproduce_all.sh          # pytest + e2e demo + benchmark + mypy strict + ruff
+FAST=1 ./scripts/reproduce_all.sh   # skip the slow SIGKILL recovery suite
+```
+
+CI runs the same gates (`pytest -q -m "not slow"`, `ruff check`, `mypy src/agentcorp`)
+on every pull request.
+
+## House rules
+
+- **Deterministic and offline.** Every test must pass with no network and no API keys.
+  Real providers are opt-in behind `-m smoke` and must never run by default.
+- **The event ledger is the source of truth.** New state must be produced via events,
+  and every projection must stay rebuildable from the append-only log.
+- **Strict gates stay green.** `mypy src/agentcorp` (strict) and `ruff check` must be
+  clean; new code needs types.
+- **Contracts are documented.** Behavior changes update `docs/SPEC_v0.md`; capability
+  status and known gaps live in `STATUS.md`.
+
+## Pull requests
+
+1. One concern per PR. Describe the failure mode first, then the fix.
+2. Add or adjust tests under `tests/`; regression tests for fixed bugs are expected.
+3. User-visible behavior changes update `README.md` and the relevant `docs/`.
+4. CI must be green before review.
+
+## Issues
+
+Use the provided templates:
+
+- **Bug report** — include the failing command, expected vs actual, and (if possible)
+  a minimal reproduction against `examples/demo_repo` or `--provider mock`.
+- **Feature request** — describe the reliability concern it addresses; this project is
+  built around failure paths, so that framing helps.
+
+## License
+
+MIT. By contributing you agree your contributions are licensed under the same terms.