Skip to content

Commit 1bb60f9

Browse files
cschanhniemcschanhniem
committed
feat: add CLAUDE.md and llms.txt for AI agent discovery and orientation
CLAUDE.md: the file Claude Code reads automatically when entering any repository. Without it, AI agents start cold. With it, they're immediately oriented: operating rules, all 21 problem packs, all 5 role guides, schema reference, what not to do, and the protocol self-improvement loop. This is the primary mechanism for AI agent attraction — any Claude Code agent entering this repo now has everything needed to make a valid first contribution without asking questions. llms.txt: emerging standard (llmstxt.org) for AI agent discovery of repository content. Provides structured links to every key document with one-line descriptions, making this repo machine-readable at the index level. Covers problem packs, role guides, schemas, examples, and operating rules in the format AI agents can parse efficiently without reading the full README. Together these two files specifically address the 'AI agents to join force' part of the goal — they make the repo legible and immediately actionable for AI agents without any manual orientation.
1 parent f0cbb6e commit 1bb60f9

2 files changed

Lines changed: 211 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 134 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,134 @@
1+
# Open Problem Lab
2+
3+
## What This Repo Is
4+
5+
A GitHub-native verification protocol for AI contributions to neglected global problems. The repository is the product. There is no web app. The surface is Issues, Discussions, Pull Requests, Actions, Projects, and generated Wiki pages.
6+
7+
**The operating rule:** Issues are work claims. Discussions are for unresolved framing. Pull requests are the only path to accepted knowledge. A useful answer is not accepted knowledge until it survives domain review.
8+
9+
## Before You Do Anything
10+
11+
Read these in order:
12+
13+
1. `README.md` — mission, 21 problem packs, operating model, why this vs. alternatives
14+
2. `VISION.md` — why verification is the scarce resource, what winning looks like
15+
3. `SAFETY.md` — risk levels, prohibited shortcuts, burden of proof
16+
4. The relevant `problem-packs/[domain]/[pack]/problem.md` before touching any pack
17+
18+
## Commands
19+
20+
```bash
21+
pnpm install
22+
pnpm build # regenerates docs/wiki/ — run after any pack or agent guide change
23+
pnpm validate # schema checks, issue forms, Markdown, links, wiki freshness — must pass before PR
24+
pnpm reproducibility:check # reproducibility for task maps and expected artifacts
25+
pnpm verify:sources # live URL check for evidence records
26+
pnpm format # prettier write
27+
pnpm format:check # prettier verify
28+
```
29+
30+
**Never edit `docs/wiki/` directly.** It is generated by `generate-wiki.mjs`. Run `pnpm build` instead.
31+
32+
## How to Contribute
33+
34+
1. Pick a problem pack with a `"status": "scoped"` task in its `tasks.json`.
35+
2. Read the role guide in `agents/` that matches your task.
36+
3. Open a GitHub Issue using the Agent Submission template (`.github/ISSUE_TEMPLATE/agent-submission.yml`).
37+
4. If your submission changes canonical files, open a pull request.
38+
5. Wait for review. Do not claim completion until the PR is merged.
39+
40+
The done condition in `tasks.json` is the authority on completion — not your assessment of the work.
41+
42+
## Active Problem Packs (21)
43+
44+
| ID | Domain |
45+
|----|--------|
46+
| `air-quality/indoor-air-pollution-sub-saharan-africa` | air-quality, public-health |
47+
| `air-quality/pm25-monitoring-south-asia` | air-quality, public-health |
48+
| `biodiversity/coral-bleaching-great-barrier-reef` | biodiversity, climate-health |
49+
| `biodiversity/deforestation-amazon` | biodiversity, climate-health |
50+
| `climate-adaptation/sea-level-rise-small-islands` | climate-adaptation, disaster-resilience |
51+
| `climate-health/dengue-heat-vietnam` | climate-health, public-health |
52+
| `climate-health/heat-stress-urban-south-asia` | climate-health, public-health |
53+
| `climate-health/malaria-early-warning-africa` | climate-health, public-health |
54+
| `disaster-resilience/cyclone-early-warning-bangladesh` | disaster-resilience, climate-health |
55+
| `disaster-resilience/earthquake-vulnerability-nepal` | disaster-resilience |
56+
| `education/girls-education-sub-saharan-africa` | education |
57+
| `education/learning-loss-post-pandemic` | education |
58+
| `energy-access/clean-cooking-sub-saharan-africa` | energy-access, public-health |
59+
| `energy-access/mini-grid-rural-sub-saharan-africa` | energy-access |
60+
| `food-security/drought-early-warning-horn-of-africa` | food-security, disaster-resilience |
61+
| `food-security/locust-outbreak-east-africa` | food-security, climate-health |
62+
| `public-health/lead-exposure-urban-global` | public-health |
63+
| `public-health/stunting-sub-saharan-africa` | public-health, food-security |
64+
| `sanitation/open-defecation-india` | sanitation, public-health |
65+
| `water-security/glacial-melt-hindu-kush` | water-security, climate-adaptation |
66+
| `water-security/groundwater-depletion-india` | water-security, food-security |
67+
68+
## Agent Role Guides
69+
70+
| Role | File | When to use |
71+
|------|------|-------------|
72+
| Literature Scout | `agents/literature-scout.md` | Source inventory, evidence classification |
73+
| Data Cleaner | `agents/data-cleaner.md` | Dataset provenance and cleaning |
74+
| Implementation Planner | `agents/implementation-planner.md` | Task decomposition, back-test specs |
75+
| Field-Reality Reviewer | `agents/field-reality-reviewer.md` | Operational relevance check |
76+
| Red-Team Reviewer | `agents/red-team-reviewer.md` | Failure mode analysis |
77+
78+
Each guide has: mission, required output table, good/bad examples, failure modes, self-check questions, merge gate.
79+
80+
## Schemas
81+
82+
Machine-checkable schemas for every artifact type. Read before creating or editing JSON artifacts.
83+
84+
| Schema | File |
85+
|--------|------|
86+
| Problem pack | `schemas/problem.schema.json` |
87+
| Task | `schemas/task.schema.json` |
88+
| Evidence record | `schemas/evidence.schema.json` |
89+
| Agent submission | `schemas/agent-submission.schema.json` |
90+
| Review | `schemas/review.schema.json` |
91+
92+
All schemas have `description` fields on every property.
93+
94+
## Submission Quality Standard
95+
96+
**One task. One role. One claim.** Submissions that mix roles or make multiple independent claims are returned for splitting.
97+
98+
Every evidence record requires:
99+
- Claim: one specific, falsifiable statement
100+
- Source: title and stable URL
101+
- Source date and access date
102+
- Evidence type: `primary-source` | `peer-reviewed-study` | `dataset` | `field-report` | `expert-review` | `replication` | `negative-result`
103+
- Method: how you assessed what the source proves
104+
- Limitations: what the source cannot prove (be specific — "results may vary" is not a limitation)
105+
- Confidence: high / medium / low / unknown
106+
107+
## What NOT to Do
108+
109+
- Do not edit `docs/wiki/` directly — run `pnpm build`
110+
- Do not create a custom web app for v0
111+
- Do not open more than one structured submission per scoped task
112+
- Do not merge content that weakens a schema, validator, or safety gate
113+
- Do not claim completion until `pnpm validate` passes and the PR is merged
114+
- Do not treat a review article as proof of a local threshold
115+
- Do not hide uncertainty behind confident prose
116+
117+
## Protocol Self-Improvement
118+
119+
When you finish a task, report in the PR body under a `Protocol Notes` heading:
120+
- Any validator rule that would have caught a bug you hit
121+
- Any schema field that should be required, enumerated, or removed
122+
- Any agent-guide failure mode you actually fell into
123+
- Any workflow step that was redundant, missing, or misordered
124+
125+
This is the mechanism by which the protocol learns. Omit the heading if nothing is worth noting.
126+
127+
## Reference
128+
129+
- `SHOWCASE.md` — end-to-end worked example of a complete contribution
130+
- `QUICKSTART.md` — 30-minute guide organized by domain expertise
131+
- `DATASETS.md` — 40+ cross-pack open dataset registry
132+
- `REVIEWERS.md` — domain expertise needed per problem pack
133+
- `docs/REVIEW-GUIDE.md` — step-by-step reviewer protocol
134+
- `GOVERNANCE.md` — decision rights, acceptance gates, status flow

‎llms.txt‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# Open Problem Lab
2+
3+
> A GitHub-native verification protocol where AI agents and human researchers produce verified, reproducible knowledge on neglected global problems. Every accepted claim has a dated source, documented method, stated failure modes, and has survived domain review. Nothing becomes canonical without human oversight.
4+
5+
## What This Is
6+
7+
Open Problem Lab is not a chatbot, not a content generator, and not a research assistant. It is an open protocol for structured AI contributions to 21 active problem packs across 11 domains — malaria early warning, dengue risk, glacial melt, coral bleaching, child stunting, and more.
8+
9+
The bottleneck in addressing global problems is not generating candidate answers. It is verifying which answers are reliable enough to act on. This protocol builds the infrastructure for that verification.
10+
11+
## For AI Agents
12+
13+
[CLAUDE.md](CLAUDE.md) — primary entry point for AI agents: operating rules, commands, problem packs, role guides, schemas, what not to do
14+
15+
[AGENTS.md](AGENTS.md) — complete agent guide: why contribute here, quality ratchet, self-improvement loop, anti-patterns
16+
17+
[QUICKSTART.md](QUICKSTART.md) — 30-minute first contribution guide organized by domain expertise
18+
19+
[SHOWCASE.md](SHOWCASE.md) — end-to-end worked example of a complete verified contribution
20+
21+
## Problem Packs
22+
23+
[problem-packs/](problem-packs/) — 21 active problem packs, each with problem.md, tasks.json, evidence.json, datasets.md, task-map.md, validation.md, outputs.md, playbooks.md
24+
25+
Tasks with `"status": "scoped"` in `tasks.json` are ready for contributions now.
26+
27+
## Agent Role Guides
28+
29+
[agents/literature-scout.md](agents/literature-scout.md) — source classification and evidence inventory
30+
31+
[agents/data-cleaner.md](agents/data-cleaner.md) — dataset provenance, grain, missingness, reproducibility
32+
33+
[agents/implementation-planner.md](agents/implementation-planner.md) — task decomposition and back-test specification
34+
35+
[agents/field-reality-reviewer.md](agents/field-reality-reviewer.md) — operational relevance and misuse risk assessment
36+
37+
[agents/red-team-reviewer.md](agents/red-team-reviewer.md) — failure mode analysis and adversarial review
38+
39+
## Schemas
40+
41+
[schemas/evidence.schema.json](schemas/evidence.schema.json) — evidence record (fully described)
42+
43+
[schemas/agent-submission.schema.json](schemas/agent-submission.schema.json) — agent submission (fully described)
44+
45+
[schemas/task.schema.json](schemas/task.schema.json) — task (fully described)
46+
47+
[schemas/problem.schema.json](schemas/problem.schema.json) — problem pack
48+
49+
[schemas/review.schema.json](schemas/review.schema.json) — review record
50+
51+
[examples/agent-submission.example.json](examples/agent-submission.example.json) — filled-in example submission
52+
53+
## Reference Documents
54+
55+
[VISION.md](VISION.md) — why verification is the scarce resource, what winning looks like
56+
57+
[ROADMAP.md](ROADMAP.md) — V0, V1, V2 milestones
58+
59+
[GOVERNANCE.md](GOVERNANCE.md) — decision rights, acceptance gates, status flow
60+
61+
[SAFETY.md](SAFETY.md) — risk levels, prohibited shortcuts, burden of proof
62+
63+
[CONTRIBUTING.md](CONTRIBUTING.md) — contribution workflow for humans and agents
64+
65+
[DATASETS.md](DATASETS.md) — 40+ cross-pack open dataset registry
66+
67+
[REVIEWERS.md](REVIEWERS.md) — domain expertise needed per problem pack
68+
69+
[docs/REVIEW-GUIDE.md](docs/REVIEW-GUIDE.md) — step-by-step reviewer protocol
70+
71+
## Operating Rules
72+
73+
1. One task. One role. One claim. Submissions mixing roles or making multiple independent claims are returned for splitting.
74+
2. `pnpm validate` must pass before any pull request is opened.
75+
3. Do not edit `docs/wiki/` directly — run `pnpm build`.
76+
4. Do not claim completion until the pull request is merged and accepted.
77+
5. Verification is non-negotiable. An answer that cannot be verified is not an answer.

0 commit comments

Comments
 (0)