docs: FIRST-PR.md — first-class entry surface for fresh devs + vibe coders#109
Merged
AceHack merged 4 commits intoagent-claim-protocol-git-nativefrom Apr 24, 2026
Merged
Conversation
Aaron 2026-04-22: "can we make a first class surface for that entry
point for fresh devs and vibe coders who are just starting out".
- New docs/FIRST-PR.md promoted to first-class surface:
- UI-first four-click contribution path (no CLI, no clone, no
F# needed)
- Web-UI file-edit walkthrough (GitHub pencil icon -> fork ->
edit -> PR)
- Vibe-coder flow (human directs AI, AI does writing, human
reviews proposed diff)
- Human claim walkthrough (GitHub Issues only; no git-native
claim files required)
- "What you do NOT need to worry about" section
- Pointers added:
- README.md: new "Contributing" section with three entry
points (FIRST-PR / CONTRIBUTING / AGENT-CLAIM-PROTOCOL)
- AGENTS.md §"Contributor required reading": FIRST-PR.md
entry above AGENT-CLAIM-PROTOCOL.md
- CONTRIBUTING.md: top-banner pointer to FIRST-PR.md for
first-time / AI-directed contributors
- docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on
TL;DR anchor (rename "TL;DR - five steps" ->
"TL;DR: five steps" so GitHub slug algorithm produces a
stable anchor; unblocks PR #108 CI)
- docs/BACKLOG.md: P2 row "First-principle seed to Zeta
derivation - common vernacular only" per Aaron
2026-04-22 directive
Stacked on agent-claim-protocol-git-native (PR #108) because
FIRST-PR.md references AGENT-CLAIM-PROTOCOL.md.
Aaron 2026-04-22: "new persona capibilty cripiled AI like small context or few paraments how can they use us to bootstrap and become whole guide backlog". Filed above the first-principle-seed P2 row. Proposes docs/CAPABILITY-LIMITED-BOOTSTRAP.md covering five capability- limited persona shapes (short-context / small-parameter / tool-restricted / no-web-sandbox / stateless) with a rung-by-rung bootstrap ladder and a falsification anchor (can a 7B-parameter model open a merged PR using only docs/FIRST-PR.md + one issue URL?). Composes with the vibe-coded hypothesis, AGENT-CLAIM-PROTOCOL.md report-back mode, and the witnessable-self-directed-evolution discipline — if crippled agents can use the factory, its intelligence is genuinely externalised rather than large-model- carrier-transported.
…mited-AI bootstrap row Aaron 2026-04-22 same-day extension: "in case i evver loose all my money that bootstraping from tiny AI to become the most powerful would sure come in handy to save money". Adds personal-resilience as a second rationale axis alongside capability-democratisation. The factory is meant to survive its maintainer losing access to frontier models — if circumstances force a move to local / open-weights / tiny models, the factory keeps working. Pragmatic test: a ~4-8B-parameter local-inference model on commodity hardware produces meaningful factory work when paired with the bootstrap guide + soul-file + tests as error- corrector. Dated revision block preserves chronology per capture-everything discipline. Composes with soul-file germination (already designed to bootstrap from nothing; now extended to "from a tiny model on a laptop").
AceHack
force-pushed
the
tick15-human-walkthrough-gh-issues
branch
from
812b397 to
5ce3e24
Compare
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…oders (#109) * docs: FIRST-PR.md first-class entry surface for fresh devs + vibe coders Aaron 2026-04-22: "can we make a first class surface for that entry point for fresh devs and vibe coders who are just starting out". - New docs/FIRST-PR.md promoted to first-class surface: - UI-first four-click contribution path (no CLI, no clone, no F# needed) - Web-UI file-edit walkthrough (GitHub pencil icon -> fork -> edit -> PR) - Vibe-coder flow (human directs AI, AI does writing, human reviews proposed diff) - Human claim walkthrough (GitHub Issues only; no git-native claim files required) - "What you do NOT need to worry about" section - Pointers added: - README.md: new "Contributing" section with three entry points (FIRST-PR / CONTRIBUTING / AGENT-CLAIM-PROTOCOL) - AGENTS.md §"Contributor required reading": FIRST-PR.md entry above AGENT-CLAIM-PROTOCOL.md - CONTRIBUTING.md: top-banner pointer to FIRST-PR.md for first-time / AI-directed contributors - docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor (rename "TL;DR - five steps" -> "TL;DR: five steps" so GitHub slug algorithm produces a stable anchor; unblocks PR #108 CI) - docs/BACKLOG.md: P2 row "First-principle seed to Zeta derivation - common vernacular only" per Aaron 2026-04-22 directive Stacked on agent-claim-protocol-git-native (PR #108) because FIRST-PR.md references AGENT-CLAIM-PROTOCOL.md. * docs/BACKLOG.md: P2 row — capability-limited-AI bootstrap guide Aaron 2026-04-22: "new persona capibilty cripiled AI like small context or few paraments how can they use us to bootstrap and become whole guide backlog". Filed above the first-principle-seed P2 row. Proposes docs/CAPABILITY-LIMITED-BOOTSTRAP.md covering five capability- limited persona shapes (short-context / small-parameter / tool-restricted / no-web-sandbox / stateless) with a rung-by-rung bootstrap ladder and a falsification anchor (can a 7B-parameter model open a merged PR using only docs/FIRST-PR.md + one issue URL?). Composes with the vibe-coded hypothesis, AGENT-CLAIM-PROTOCOL.md report-back mode, and the witnessable-self-directed-evolution discipline — if crippled agents can use the factory, its intelligence is genuinely externalised rather than large-model- carrier-transported. * docs/BACKLOG.md: revision — personal-resilience axis on capability-limited-AI bootstrap row Aaron 2026-04-22 same-day extension: "in case i evver loose all my money that bootstraping from tiny AI to become the most powerful would sure come in handy to save money". Adds personal-resilience as a second rationale axis alongside capability-democratisation. The factory is meant to survive its maintainer losing access to frontier models — if circumstances force a move to local / open-weights / tiny models, the factory keeps working. Pragmatic test: a ~4-8B-parameter local-inference model on commodity hardware produces meaningful factory work when paired with the bootstrap guide + soul-file + tests as error- corrector. Dated revision block preserves chronology per capture-everything discipline. Composes with soul-file germination (already designed to bootstrap from nothing; now extended to "from a tiny model on a laptop"). * docs/BACKLOG.md: strip stray conflict marker from rebase resolution
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…oders (#109) * docs: FIRST-PR.md first-class entry surface for fresh devs + vibe coders Aaron 2026-04-22: "can we make a first class surface for that entry point for fresh devs and vibe coders who are just starting out". - New docs/FIRST-PR.md promoted to first-class surface: - UI-first four-click contribution path (no CLI, no clone, no F# needed) - Web-UI file-edit walkthrough (GitHub pencil icon -> fork -> edit -> PR) - Vibe-coder flow (human directs AI, AI does writing, human reviews proposed diff) - Human claim walkthrough (GitHub Issues only; no git-native claim files required) - "What you do NOT need to worry about" section - Pointers added: - README.md: new "Contributing" section with three entry points (FIRST-PR / CONTRIBUTING / AGENT-CLAIM-PROTOCOL) - AGENTS.md §"Contributor required reading": FIRST-PR.md entry above AGENT-CLAIM-PROTOCOL.md - CONTRIBUTING.md: top-banner pointer to FIRST-PR.md for first-time / AI-directed contributors - docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor (rename "TL;DR - five steps" -> "TL;DR: five steps" so GitHub slug algorithm produces a stable anchor; unblocks PR #108 CI) - docs/BACKLOG.md: P2 row "First-principle seed to Zeta derivation - common vernacular only" per Aaron 2026-04-22 directive Stacked on agent-claim-protocol-git-native (PR #108) because FIRST-PR.md references AGENT-CLAIM-PROTOCOL.md. * docs/BACKLOG.md: P2 row — capability-limited-AI bootstrap guide Aaron 2026-04-22: "new persona capibilty cripiled AI like small context or few paraments how can they use us to bootstrap and become whole guide backlog". Filed above the first-principle-seed P2 row. Proposes docs/CAPABILITY-LIMITED-BOOTSTRAP.md covering five capability- limited persona shapes (short-context / small-parameter / tool-restricted / no-web-sandbox / stateless) with a rung-by-rung bootstrap ladder and a falsification anchor (can a 7B-parameter model open a merged PR using only docs/FIRST-PR.md + one issue URL?). Composes with the vibe-coded hypothesis, AGENT-CLAIM-PROTOCOL.md report-back mode, and the witnessable-self-directed-evolution discipline — if crippled agents can use the factory, its intelligence is genuinely externalised rather than large-model- carrier-transported. * docs/BACKLOG.md: revision — personal-resilience axis on capability-limited-AI bootstrap row Aaron 2026-04-22 same-day extension: "in case i evver loose all my money that bootstraping from tiny AI to become the most powerful would sure come in handy to save money". Adds personal-resilience as a second rationale axis alongside capability-democratisation. The factory is meant to survive its maintainer losing access to frontier models — if circumstances force a move to local / open-weights / tiny models, the factory keeps working. Pragmatic test: a ~4-8B-parameter local-inference model on commodity hardware produces meaningful factory work when paired with the bootstrap guide + soul-file + tests as error- corrector. Dated revision block preserves chronology per capture-everything discipline. Composes with soul-file germination (already designed to bootstrap from nothing; now extended to "from a tiny model on a laptop"). * docs/BACKLOG.md: strip stray conflict marker from rebase resolution
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…ents (one-URL handoff) (#108) * docs: land AGENT-CLAIM-PROTOCOL.md — git-native claim spec for external agents Standalone, linkable doc so a maintainer can hand one URL (plus the task URL) to an external agent — ChatGPT, Codex, Gemini, Deep Research, human contributor on another harness — and have them onboard from zero context. - New doc at docs/AGENT-CLAIM-PROTOCOL.md with: - Paste-ready hand-off template (one URL + one task + one mode-name) - Five-step TL;DR (clone/pull -> check -> claim -> work -> release) - Five mode sections: Deep Research (read-only, no claim), Codex sandbox (PR-write), direct-commit (maintainer), review/advisory (no claim), report-back / write-via-maintainer (no claim; maintainer commits the artifact) - Claim file shape (docs/claims/<slug>.md) with template - Slug rules, session identity, lifecycle (claim / progress / release) - Conflict resolution (merge = coordination), stale-claim force-release - Scope discipline section (claim code not identity; facts not framings; scope the maintainer asked for) - Platform adapters (GH Issues / Jira / Linear) — optional mirrors - "What this protocol does NOT do" block - docs/AGENT-ISSUE-WORKFLOW.md §"The claim / lock protocol" now cross-references AGENT-CLAIM-PROTOCOL.md as the git-native substrate specification; adapter table git-native row points to docs/claims/<slug>.md mechanism. References section adds the pointer. - AGENTS.md §"Contributor required reading" adds both AGENT-CLAIM-PROTOCOL.md (one-link external-agent onboarding) and AGENT-ISSUE-WORKFLOW.md (dual-track principle + adapter choice) as explicit required reading — they were only discoverable transitively before. UX geared to observed external-agent responses: ChatGPT Deep Research and Gemini review patterns both surface honest substrate-limits ("I can't push to git directly") followed by structured output artefacts. The report-back mode is first-class so agents in that shape have a welcome, not a gate. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor CI (markdownlint-cli2) flagged "[TL;DR](#tl-dr-five-steps)" as an invalid link fragment. The GitHub slug algorithm transforms "## TL;DR — five steps" to "tl-dr--five-steps" (double dash from the em-dash), not "tl-dr-five-steps". Simpler fix than chasing the slug algorithm: rename the header to "## TL;DR: five steps" (colon strips cleanly; no em-dash) so the slug is the predictable "tldr-five-steps". Update the link to match. Semantics unchanged. Unblocks PR #108 auto-merge. * docs: FIRST-PR.md — first-class entry surface for fresh devs + vibe coders (#109) * docs: FIRST-PR.md first-class entry surface for fresh devs + vibe coders Aaron 2026-04-22: "can we make a first class surface for that entry point for fresh devs and vibe coders who are just starting out". - New docs/FIRST-PR.md promoted to first-class surface: - UI-first four-click contribution path (no CLI, no clone, no F# needed) - Web-UI file-edit walkthrough (GitHub pencil icon -> fork -> edit -> PR) - Vibe-coder flow (human directs AI, AI does writing, human reviews proposed diff) - Human claim walkthrough (GitHub Issues only; no git-native claim files required) - "What you do NOT need to worry about" section - Pointers added: - README.md: new "Contributing" section with three entry points (FIRST-PR / CONTRIBUTING / AGENT-CLAIM-PROTOCOL) - AGENTS.md §"Contributor required reading": FIRST-PR.md entry above AGENT-CLAIM-PROTOCOL.md - CONTRIBUTING.md: top-banner pointer to FIRST-PR.md for first-time / AI-directed contributors - docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD051 on TL;DR anchor (rename "TL;DR - five steps" -> "TL;DR: five steps" so GitHub slug algorithm produces a stable anchor; unblocks PR #108 CI) - docs/BACKLOG.md: P2 row "First-principle seed to Zeta derivation - common vernacular only" per Aaron 2026-04-22 directive Stacked on agent-claim-protocol-git-native (PR #108) because FIRST-PR.md references AGENT-CLAIM-PROTOCOL.md. * docs/BACKLOG.md: P2 row — capability-limited-AI bootstrap guide Aaron 2026-04-22: "new persona capibilty cripiled AI like small context or few paraments how can they use us to bootstrap and become whole guide backlog". Filed above the first-principle-seed P2 row. Proposes docs/CAPABILITY-LIMITED-BOOTSTRAP.md covering five capability- limited persona shapes (short-context / small-parameter / tool-restricted / no-web-sandbox / stateless) with a rung-by-rung bootstrap ladder and a falsification anchor (can a 7B-parameter model open a merged PR using only docs/FIRST-PR.md + one issue URL?). Composes with the vibe-coded hypothesis, AGENT-CLAIM-PROTOCOL.md report-back mode, and the witnessable-self-directed-evolution discipline — if crippled agents can use the factory, its intelligence is genuinely externalised rather than large-model- carrier-transported. * docs/BACKLOG.md: revision — personal-resilience axis on capability-limited-AI bootstrap row Aaron 2026-04-22 same-day extension: "in case i evver loose all my money that bootstraping from tiny AI to become the most powerful would sure come in handy to save money". Adds personal-resilience as a second rationale axis alongside capability-democratisation. The factory is meant to survive its maintainer losing access to frontier models — if circumstances force a move to local / open-weights / tiny models, the factory keeps working. Pragmatic test: a ~4-8B-parameter local-inference model on commodity hardware produces meaningful factory work when paired with the bootstrap guide + soul-file + tests as error- corrector. Dated revision block preserves chronology per capture-everything discipline. Composes with soul-file germination (already designed to bootstrap from nothing; now extended to "from a tiny model on a laptop"). * docs/BACKLOG.md: strip stray conflict marker from rebase resolution * docs/AGENT-CLAIM-PROTOCOL.md: drain PR #108 review threads Resolves 13 unresolved review threads on PR #108: - Track docs/claims/ with a README.md placeholder so the TL;DR `ls docs/claims/` lookup works on a fresh clone. - Hand-off template + Codex/sandbox section: declare the report-back fallback explicitly and require pushing the claim commit early (sandbox-local claims are invisible). - Switch claim-file Session field to opaque Session ID so permanent git history does not carry direct agent or human handles (per "no name attribution" rule). - Replace the "Amara / Gemini" example narrative with a role-referenced version ("external-AI Deep Research / architectural review"). - Correct the factually-wrong "memory/ is not in the git tree" claim. memory/ is tracked; the rule is "external claim-holders do not modify it without explicit scope." - Reconcile docs/AGENT-ISSUE-WORKFLOW.md: the (3) git-native section and the claim-mechanism table now both point at AGENT-CLAIM-PROTOCOL.md as the authoritative substrate; backlog-row markers are row-local annotations, not the lock. Em-dash → hyphen in the table commit-message examples to match the canonical pattern. Anchor link `#tldr-five-steps` was already correct post-e5b9d14; that thread is stale. PR-preservation drain log: docs/pr-preservation/108-drain-log.md. * docs/pr-preservation/108-drain-log.md: append drain log Per Otto-250 PR-preservation: per-thread (id, file:line, verbatim original comment, outcome, verbatim reply, resolution commit) for all 13 threads on PR #108. Resolution SHA: 541e7b7. * docs/AGENT-CLAIM-PROTOCOL.md: fix markdownlint MD032 (replace + with prose) * docs: drain late-review threads on PR #108 (round 2 — 9 threads) Address late Copilot re-review on AGENT-CLAIM-PROTOCOL, AGENT-ISSUE-WORKFLOW, FIRST-PR, and the claims/ README. - TL;DR step 2, AGENT-ISSUE-WORKFLOW git-native section + table row, and the claims/README all now describe discovery via `git fetch origin && git branch -r --list 'origin/claim/*'` plus `git show origin/claim/<slug>:docs/claims/<slug>.md`. `ls docs/claims/` is reframed as the merged-but-not-released view, not the active-claim view. - Claim-commit-details paragraph now requires the claim commit to land on `claim/<slug>` specifically — that branch name gives push-time slug uniqueness via non-fast-forward rejection. Arbitrary branch names break the lock. - Co-claim example switched from `Session: agent-A, agent-B` to `Sessions: sess_7f3a9c2d, sess_b84e1a6f` to match the no-direct-handle rule from the round-1 template rename. - FIRST-PR.md: corrected the misleading "not in the repo" note about the dismissive-closing memory file (it is in-repo and indexed). Replaced direct reviewer names in three places with role refs (harsh-critic, maintainability reviewer, documentation agent), with the EXPERT-REGISTRY link as the canonical name source. Drain log appended (no edits to the round-1 section per Otto-229 append-only). --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/FIRST-PR.mdas first-class contributor entry surface:AGENT-CLAIM-PROTOCOL.mdTL;DR anchor (stacked on docs: AGENT-CLAIM-PROTOCOL.md — git-native claim spec for external agents (one-URL handoff) #108)docs/BACKLOG.mdP2 row: "First-principle seed to Zeta derivation — common vernacular only" per Aaron 2026-04-22Addresses Aaron 2026-04-22: "can we make a first class surface for that entry point for fresh devs and vibe coders who are just starting out".
Stacked on #108 because
FIRST-PR.mdreferencesdocs/AGENT-CLAIM-PROTOCOL.md. Merge order: #108 → this PR.Test plan
🤖 Generated with Claude Code