Skip to content

Commit 9d390e2

Browse files
az9713claude
az9713
and
claude
committed
Add comprehensive documentation suite for Open Brain
Documentation-enhanced clone of NateBJones-Projects/OB1 with: - HOW_OPEN_BRAIN_WORKS.md: Technical deep dive with source file references - ARCHITECTURE.md: System design with 9 ASCII diagrams - DEVELOPER_GUIDE.md: 2,490-line guide for C/Java devs new to web dev - API_REFERENCE.md: All 35+ MCP tools, full database schema reference - STUDY_PLAN.md: 13-phase zero-to-hero learning plan - USER_GUIDE.md: 10 educational use cases for new users - QUICKSTART.md: 10-step guided tutorial - Article synthesized from video transcript, substack, and prompt kit - README.md: Attribution to upstream NateBJones-Projects/OB1 - CLAUDE.md: Updated with documentation index Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
0 parents  commit 9d390e2

119 files changed

Lines changed: 23123 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.claude/skills/review-pr.md‎

Lines changed: 121 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,121 @@
1+
---
2+
name: review-pr
3+
description: Run admin review on an OB1 pull request. Covers what CI can't — security deep scan, mission fit, naming consistency, and generates admin summary, Discord draft, and post-merge task list. Takes PR number as argument (e.g., "review PR 21").
4+
---
5+
6+
# OB1 PR Review — Admin Skill
7+
8+
Run the human-judgment layer of PR review on OB1. CI handles the mechanical checks (11 rules, scope, links, post-merge reminders). This skill handles everything CI can't automate.
9+
10+
## Input
11+
12+
PR number from the user. Fetch details with `gh pr view <number>` and `gh pr diff <number>`. Checkout the branch with `gh pr checkout <number>` to inspect files. Return to the original branch when done.
13+
14+
## Step 1: CI Status
15+
16+
Run `gh pr checks <number>` to see automated review results. Report:
17+
- Passed: move on to admin checks
18+
- Failed: note which rules failed — contributor must fix before admin review matters
19+
- Pending: note it, proceed with admin checks anyway
20+
21+
Also check if the CI bot posted a "Post-Merge Tasks" section — those are the doc coverage gaps CI detected. Pull them into Section F below.
22+
23+
## Step 2: Security Deep Scan
24+
25+
CI only does basic credential pattern matching. Scan deeper:
26+
27+
- **Secrets beyond CI's patterns** — tokens in comments, base64-encoded values, connection strings, private keys
28+
- **External URLs** — anything besides github.com, discord.gg, or relative doc links. Where does this code phone home?
29+
- **Dangerous operations** — `rm -rf`, `chmod`, `sudo`, `eval()`, `exec()`, `system()`, `subprocess`, `os.system`
30+
- **Prompt injection** in skill/prompt files — `ignore previous`, `disregard`, `you are now`, `jailbreak`, `bypass`
31+
- **Personal data** — email addresses, phone numbers, real names that aren't the author's
32+
- **Data exfiltration** — `webhook`, `ngrok`, `requestbin`, `pipedream`, `discord.com/api/webhooks`
33+
- **Supply chain** — does it install packages? from where? pinned versions?
34+
35+
## Step 3: Mission Fit
36+
37+
Assess against OB1's core: "One brain, all your AI tools."
38+
39+
- Does this add a capture, retrieval, or processing capability for Open Brain?
40+
- Does it complement existing contributions? Check `recipes/`, `schemas/`, etc. for overlap.
41+
- Does it respect the upstream boundary (no core `thoughts` table or MCP server modifications)?
42+
- Does it require paid services with no free-tier alternative?
43+
- Is the difficulty rating accurate?
44+
- If in a curated category (`extensions/`, `primitives/`), flag that maintainer approval is required regardless.
45+
46+
## Step 4: Naming & Consistency
47+
48+
- Folder name vs `metadata.json` name — do they match?
49+
- Filenames referenced in README vs actual files — any mismatches? (This is the #1 bug CI can't catch reliably.)
50+
- Consistent naming throughout — no mixed references like "brain-dump-processor" in README but "panning-for-gold" on disk.
51+
52+
## Step 5: PR Description Quality
53+
54+
Per CONTRIBUTING.md, must include: what it does, what it requires, confirmation of testing. CI can check if sections exist but not if they're meaningful. Assess quality.
55+
56+
## Output
57+
58+
### A: Review Checklist
59+
60+
| Check | Status | Notes |
61+
|-------|--------|-------|
62+
| CI status | | |
63+
| Security | | |
64+
| Mission fit | | |
65+
| Naming consistency | | |
66+
| PR description | | |
67+
68+
### B: Verdict
69+
70+
- **Approve** — all clear
71+
- **Approve with required changes** — minor fixes needed, list them
72+
- **Request changes** — significant issues, list with explanations
73+
- **Reject** — doesn't fit OB1, duplicates work, or security concerns
74+
75+
### C: Admin Summary (Shareable)
76+
77+
Formatted for copy-pasting to other admins in Discord or DMs:
78+
79+
```
80+
PR #<number>: <title>
81+
Author: @<github> (first-time / returning contributor)
82+
Category: <recipes/schemas/etc.>
83+
What it does: <one sentence>
84+
CI: <passed/failed>
85+
Admin review: <verdict>
86+
Changes needed: <list or "none">
87+
Post-merge: <task count> items
88+
Link: <PR URL>
89+
```
90+
91+
### D: Discord Draft
92+
93+
For `#show-and-tell` after merge. Welcoming tone, specific about the contribution, encouraging. Include PR link and contributor's GitHub handle.
94+
95+
### E: Post-Merge Task List
96+
97+
Assemble from CI's "Post-Merge Tasks" section plus anything else identified:
98+
99+
```
100+
- [ ] Update <category>/README.md index
101+
- [ ] Update root README.md (if needed)
102+
- [ ] Add contributor to CONTRIBUTORS.md (if first contribution)
103+
- [ ] Post Discord message
104+
- [ ] <other follow-ups>
105+
```
106+
107+
### F: PR Comment Draft
108+
109+
Compose the review to post on the PR:
110+
- Reference CI status (don't repeat — just "CI passed" or "CI flagged X")
111+
- Security scan result
112+
- Admin findings (required changes, suggestions)
113+
- Welcoming close linking to Discord: https://discord.gg/Cgh9WJEkeG
114+
115+
**Ask the user before posting:** "Ready to post this review?" Then run `gh pr review <number> --comment --body "..."`.
116+
117+
## Notes
118+
119+
- This skill does NOT re-run CI checks. It reads CI results and adds the judgment layer.
120+
- Any admin using Claude Code in the OB1 repo has this skill. The outputs (admin summary, PR comment) are designed to be shared with admins who don't use Claude Code.
121+
- Return to original branch after review: `git checkout <branch>`

‎.github/.markdownlint.jsonc‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
{
2+
// Permissive config: catch real problems, don't block on style nits
3+
"default": true,
4+
5+
// Allow any line length — READMEs with tables and URLs get long
6+
"MD013": false,
7+
8+
// Allow duplicate headings (common in contribution READMEs)
9+
"MD024": false,
10+
11+
// Allow inline HTML (badges, images, comments)
12+
"MD033": false,
13+
14+
// Allow bare URLs
15+
"MD034": false,
16+
17+
// Allow trailing punctuation in headings
18+
"MD026": false,
19+
20+
// Allow multiple top-level headings (some files have them)
21+
"MD025": false,
22+
23+
// Allow non-blank lines before/after lists (common in quick docs)
24+
"MD032": false,
25+
26+
// Allow files to start without a top-level heading (PR templates start with ##)
27+
"MD041": false,
28+
29+
// Allow bold text as pseudo-headings (used in troubleshooting sections)
30+
"MD036": false,
31+
32+
// Allow fenced code blocks without language specifier (common in templates)
33+
"MD040": false,
34+
35+
// Allow flexible table column spacing
36+
"MD060": false
37+
}

‎.github/ISSUE_TEMPLATE/blank.yml‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
name: Blank Issue
2+
description: Open a blank issue — use this if nothing else fits
3+
labels: []
4+
body:
5+
- type: textarea
6+
id: content
7+
attributes:
8+
label: What's on your mind?
9+
validations:
10+
required: true

‎.github/ISSUE_TEMPLATE/bug-report.yml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
name: Bug Report
2+
description: Something isn't working as documented
3+
labels: ["bug"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Thanks for reporting a bug! Please fill out the details below so we can help.
9+
10+
- type: input
11+
id: contribution
12+
attributes:
13+
label: Which contribution?
14+
description: The name and category (e.g., "recipes/email-history-import")
15+
placeholder: recipes/email-history-import
16+
validations:
17+
required: true
18+
19+
- type: textarea
20+
id: what-happened
21+
attributes:
22+
label: What happened?
23+
description: Describe what went wrong. Include any error messages you saw.
24+
placeholder: "I followed step 3 but got an error saying..."
25+
validations:
26+
required: true
27+
28+
- type: textarea
29+
id: expected
30+
attributes:
31+
label: What did you expect?
32+
description: What should have happened instead?
33+
validations:
34+
required: true
35+
36+
- type: textarea
37+
id: steps
38+
attributes:
39+
label: Steps to reproduce
40+
description: How can we see the same problem?
41+
placeholder: |
42+
1. Go to '...'
43+
2. Run '...'
44+
3. See error
45+
validations:
46+
required: true
47+
48+
- type: textarea
49+
id: environment
50+
attributes:
51+
label: Environment
52+
description: Any relevant details about your setup.
53+
placeholder: |
54+
- Supabase plan: Free
55+
- OS: macOS 15
56+
- Node version: 22
57+
validations:
58+
required: false

‎.github/ISSUE_TEMPLATE/config.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
blank_issues_enabled: false
2+
contact_links: []

‎.github/ISSUE_TEMPLATE/extension-submission.yml‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
name: Extension Proposal
2+
description: Propose a new extension for the learning path
3+
labels: ["extension-proposal"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Extensions are curated, practical builds that form a progressive learning path. Each extension teaches new concepts through real use cases.
9+
10+
**Important:** Extensions are curated by maintainers. Please discuss your idea here before submitting a PR. We want to make sure it fits the learning path and doesn't duplicate existing extensions.
11+
12+
- type: input
13+
id: name
14+
attributes:
15+
label: Extension Name
16+
description: A short, descriptive name
17+
placeholder: "Pet Care Tracker"
18+
validations:
19+
required: true
20+
21+
- type: textarea
22+
id: pain_point
23+
attributes:
24+
label: Why does this matter?
25+
description: What real-life pain point does this solve? Lead with the human scenario, not the tech spec.
26+
placeholder: "You can never remember when the dog's last vet visit was, what vaccines are due, or what brand of food the cat is on..."
27+
validations:
28+
required: true
29+
30+
- type: textarea
31+
id: what_it_does
32+
attributes:
33+
label: What does it do?
34+
description: 1-3 sentences on the practical capability.
35+
validations:
36+
required: true
37+
38+
- type: textarea
39+
id: what_it_teaches
40+
attributes:
41+
label: What new concepts does it teach?
42+
description: What will users learn that they haven't encountered in existing extensions?
43+
placeholder: |
44+
- Recurring event scheduling
45+
- Multi-pet data models
46+
- Vet visit history logging
47+
validations:
48+
required: true
49+
50+
- type: textarea
51+
id: tables
52+
attributes:
53+
label: Proposed tables
54+
description: What database tables would this extension create?
55+
placeholder: |
56+
- pets (name, species, breed, birth_date, vet, notes)
57+
- vet_visits (pet_id, date, type, notes, next_due)
58+
validations:
59+
required: false
60+
61+
- type: textarea
62+
id: primitives
63+
attributes:
64+
label: Required primitives
65+
description: Does this extension need any primitives (e.g., RLS, Shared MCP)? List existing ones or propose new ones.
66+
validations:
67+
required: false
68+
69+
- type: dropdown
70+
id: difficulty
71+
attributes:
72+
label: Estimated difficulty
73+
options:
74+
- Beginner
75+
- Intermediate
76+
- Advanced
77+
validations:
78+
required: true
79+
80+
- type: dropdown
81+
id: status
82+
attributes:
83+
label: Do you have this working?
84+
options:
85+
- "Yes — I've built it and can submit a PR after discussion"
86+
- "Partially — I have a working prototype"
87+
- "No — this is an idea I'd like to see built"
88+
validations:
89+
required: true

‎.github/ISSUE_TEMPLATE/feature-request.yml‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
name: Feature Request
2+
description: Suggest an improvement to an existing contribution or to the repo itself
3+
labels: ["enhancement"]
4+
body:
5+
- type: markdown
6+
attributes:
7+
value: |
8+
Have an idea to make something better? We'd love to hear it.
9+
10+
- type: dropdown
11+
id: area
12+
attributes:
13+
label: What area does this relate to?
14+
options:
15+
- An existing contribution (recipe, schema, dashboard, integration)
16+
- Repo structure or templates
17+
- CI/CD or automation
18+
- Documentation
19+
- Other
20+
validations:
21+
required: true
22+
23+
- type: textarea
24+
id: description
25+
attributes:
26+
label: What would you like to see?
27+
description: Describe the improvement. What problem does it solve?
28+
validations:
29+
required: true
30+
31+
- type: textarea
32+
id: alternatives
33+
attributes:
34+
label: Alternatives considered
35+
description: Have you tried any workarounds or considered other approaches?
36+
validations:
37+
required: false

0 commit comments

Comments
 (0)