README: drop § section sign, replace wrapping Unicode dividers#1
Merged
Conversation
- Section headers now read "## 1 — Links" instead of "## §1 — Links". The § is the typographic section sign — accurate but unfamiliar. - The long horizontal dividers between sections were Unicode box-drawing characters (─ × 74) which wrapped to two lines at GitHub's narrower render width. Replaced with markdown --- horizontal rules, which render as a proper full-width <hr> at any viewport. - Box-drawing characters inside fenced code blocks are unchanged — they need a consistent width and code blocks scroll horizontally rather than wrap.
JayantChopra
force-pushed
the
readme/cleanup-dividers
branch
from
a394461 to
8ccbdaa
Compare
- Section 1 (Links): code block → bulleted list with <URL> markdown, so every link is clickable when rendered. - Section 3 (Repo map): trim two lines that overflowed the column (line wrap at ~80 chars on GitHub's render width); drop inline spec previews that duplicate section 5; keep only the two callouts (hello-world as smoke, refund-aud-only as canonical reference). - Section 4 (Agent catalog): ASCII pseudo-table → real markdown table with clickable agent slugs that link to each AGENT.md. - Section 5 (Spec catalog): same conversion. Each row now has clickable spec name + clickable agent name. Removes the longest-overflowing block in the old README. - Section 6 (Agent × spec map): code block → bulleted list with links on both sides of the arrow. - Section 9 (Embedding media): expand with image sizing example and a "want me to embed something?" handoff section so future asks are unambiguous (which file, where, caption).
Each of the 8 generic agent folders now contains an AGENT.md that's optimized for an AI coder to read and implement. New structure per AGENT.md: - Scaffold banner at top, status: scaffold - 'What this agent must do' — testable behaviors - 'Inputs at runtime' — files, env vars, services - 'Outputs the agent must produce' — file paths + side effects - 'Acceptance criteria' — link to the spec yaml that gates 'done' - 'How to build this agent' — package + upload steps - 'Paste this to your AI coder' — copy-pasteable prompt - 'System prompt (starting point)' — preserved from old version stripe-refund-aud is unchanged content-wise but now marked status: implemented with a 'reference implementation' banner. Updates: - agents/_template.md mirrors the new scaffold shape - agents/README.md explains the scaffold-to-runnable flow - planning/AGENTS.md adds rationale for scaffold approach - top README §4 splits the catalog into scaffold (8) vs implemented (1) with a new Status column
What we proved runs end-to-end on Keystone (Grok-4 via xAI): - hello-world (cli baseline) - summarize-changelog (type: python, embedded code, all invariants pass) - security-review (type: python, embedded code, all invariants pass) - refund-aud-only (type: snapshot, uploaded agent, full flow proven) Plus research-summarizer proved as a snapshot agent. Six undocumented Keystone behaviors discovered and worked around: 1. Snapshot bundles extract to /agent/, not /workspace 2. Nomad alloc has a ~1MB practical cap on bundle size 3. setup.files do NOT propagate to snapshot agents 4. type: python agents can't reach declared services 5. Bare-name secret YAML syntax is documented but rejected 6. ks env push fails silently against the dashboard Changes: - LEARNINGS.md: full field report, intended as Polarity feedback too - agents/research-summarizer/agent.py: stdlib-only working snapshot agent - agents/stripe-refund-aud/agent.py: rewritten stdlib-only (was anthropic SDK) - agents/stripe-refund-aud/README.md: updated upload + size-cap notes - AGENT.md status updates: research-summarizer + stripe-refund-aud both marked 'implemented' (proven working) with grok-4 default model - 4 spec yamls updated to the working pattern (embedded type: python or uploaded type: snapshot) - README: added LEARNINGS.md callout + Run column on spec catalog showing which specs are verified vs scaffold
…back The 8 generic agents are scaffolds — design docs that describe what an implementation should do, paired with the spec yaml as acceptance. Per repo policy (set 2026-05-13), test implementations built from a scaffold are throwaway and not committed. Changes: - Delete agents/research-summarizer/agent.py (was a one-off test). AGENT.md status flipped to 'scaffold-verified' — scaffold proven realizable via a throwaway snapshot that ran clean, but no impl in the repo. - Revert specs/general/summarize-changelog.yaml back to scaffold form (agent: type: snapshot, snapshot: research-summarizer). No embedded agent code; relies on a pre-uploaded snapshot. - Revert specs/security-agents/security-review.yaml the same way. - agents/stripe-refund-aud/ remains: it's the one canonical reference implementation showing the Pattern B (snapshot, stdlib-only) shape that other agents should mirror. - LEARNINGS.md: rewritten to be purely user-facing. Documents the two working patterns, decision tree, six Keystone gotchas, and how to validate a scaffold without committing the test agent. The 'For Polarity:' recommendations were pulled out into ~/keystone-polarity-feedback.md (private, outside the repo). - README: status line clarifies the scaffold model; spec catalog Run column gets a legend distinguishing 'verified', 'scaffold-verified', 'scaffold', and 'flow-proven'.
Test runs were throwaway type:python implementations following each scaffold's instructions, run once against the spec's invariants, then deleted. Per repo policy the test agents are NOT committed. Results (2026-05-13): - bug-fixer / bugfix-linked-list: PASS composite 1.0 (27s) - general-coder / refactor-god-class: PASS gates, FAIL style line-cap (composite 0.75) - general-coder / language-matrix-csv: PASS composite 1.0 (4s) Python-only scenario - web-builder / rest-api-todo: PASS composite 1.0 (29s) - web-builder / webhook-receiver-hmac: PASS composite 1.0 (79s) - (security-auditor / security-review was already scaffold-verified) All AGENT.md files updated with status + run notes. README spec catalog Run column updated. Three scaffolds deferred — each documented in its AGENT.md: - db-architect needs Postgres service from snapshot agent - devops-shell needs Docker installable in sandbox - data-pipeline complex showcase, multi-service Total session cost on xAI: under $0.20 (grok-4-fast at $0.20/$0.50 per Mtok).
- Replaced the plain-markdown opener with a centered header block: banner image (placeholder), title, tagline, six shields.io badges (license, status, ks version, spec count, scaffold verified count, github issues), and an anchor nav row. - Reorganized sections to match the standard Polarity OSS shape: What is this, Links, Getting started (boxes preserved), Repo structure, Agent catalog, Spec catalog, Agent x spec map, Workflow, Validation, Embedding media, Documentation, Status, Community, Contributing, License (with copyright). - Added LICENSE (Apache 2.0) at the repo root. - Copyright line at the bottom of README points to polarity.so. Banner image at assets/banner.png is a placeholder; falls back silently if the file doesn't exist.
…m dashes Counts: - agents: 5 scaffold-verified + 1 implemented = 6/9 (was wrong: said 7/9) - specs: 1 baseline + 7 scaffold-verified + 1 reference flow-proven = 9/12 (was wrong: said 8/12 with 6 scaffold-verified) Updated: - badge: scaffolds_verified-6/9 (was 7/9) - top callout: 6 of 9 + 9 of 12 (was 7 of 9 + 8 of 12) - Status section: same correction with breakdown Em dashes: removed all 31. Replaced with colons (for label-then-description patterns), periods (when ending a clause), commas (mid-sentence continuations), or parentheses (for asides). No em dashes remain in README.
Three asks landed:
1. Outdated AI-coder prompts in 8 scaffolds + the reference impl
said 'wrap your LLM client with polarity_keystone.Keystone().wrap()'.
That's the path that fails on the snapshot bundle size cap
(LEARNINGS.md section 2). Updated all to point at the working
stdlib-only urllib pattern that mirrors stripe-refund-aud/agent.py.
Tailored each per-scaffold note (psql, docker, services, matrix,
etc.).
2. Added 'Run your first real eval' section to the README right
after Getting started. Four step-boxes covering: install
polarity-keystone SDK locally, add XAI_API_KEY, upload the
stripe-refund-aud snapshot via ks.agents.upload(), run
refund-aud-only.yaml.
3. Added five standard OSS files:
- CONTRIBUTING.md dev setup, scaffold + spec workflows,
repo policy on test-agent throwaway
- SECURITY.md vuln-disclosure path, scope notes
- CODE_OF_CONDUCT.md Contributor Covenant 2.1
- NOTICE Apache 2.0 attribution + third-party
(Polarity skills, ks-setup-written content)
- CHANGELOG.md Unreleased entry + initial 0.1.0 entry
summarizing the six-discovery session
Updated README repo-structure tree and Contributing section to
reference the new files.
…ecs/README Asset embeds (the user added these to assets/): - assets/keystone-trailer.mp4 (25 MB) → header, under H1 - assets/screenshot_tweet2_spec_creation.png (847 KB) + assets/yaml-customization.mp4 (12 MB) → new section 'Creating specs from natural language' between 'Run your first real eval' and 'Repo structure' Reorganization: - Moved CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md into .github/ (GitHub auto-detects them in either location). Cleaner repo root. - Updated README's repo-structure tree + every internal link to point at the new .github/ paths. - Added specs/README.md: 12-spec layout, template pointer, validate command, lint rules, run-spec instructions, link to top-level catalog. - Removed the 'scaffolds_verified 6/9' badge per request. Cleanup: - Renamed assets with spaces in filenames (URL-safe). - Removed assets/.DS_Store. Note: ~38 MB of media now committed. If this becomes a concern, Git LFS is a one-command migration.
…paths)
GitHub's markdown renderer only honors <video> tags whose src points
at user-attachments.githubusercontent.com (drag-and-drop URLs).
Repo-relative MP4 paths get stripped, so the previous embeds rendered
as nothing.
Switched to the clickable-cover-image pattern that does work with
relative paths:
<a href='assets/keystone-trailer.mp4'>
<img src='assets/keystone-trailer-cover.jpg' />
</a>
Generated assets/yaml-customization-cover.jpg via ffmpeg (frame at
2s of yaml-customization.mp4). Both videos now show their poster
inline; clicking takes you to the MP4 file (browser plays it or
downloads it depending on the browser).
Added a note under the spec-creation video explaining how to get
true inline playback if needed (drag-and-drop into PR #1 to get
the CDN URL).
Adapted from Polarityinc/zenith conventions, scoped to this repo:
.github/PULL_REQUEST_TEMPLATE.md
- PR types reflect this repo (scaffold / spec / validation /
fix / docs / tooling / chore) rather than Zenith's Rust-flavored
feat/perf/refactor.
- Test checklist references bash scripts/validate.sh and the
/tmp/build throwaway-agent flow we documented.
- Bottom checklist enforces: no secrets, no AI attribution,
template shape, validate.sh pass, LEARNINGS.md updated when
discovering new behavior.
.github/ISSUE_TEMPLATE/bug_report.yml
- YAML form (matches Zenith's style). Required: summary, repro,
expected, actual. Optional: ks version, OS, notes.
.github/ISSUE_TEMPLATE/spec_or_scaffold_proposal.yml
- YAML form for proposing a new scaffold + spec pair.
Asks: purpose, acceptance criteria, external services,
likely agent type. Tells proposers to read LEARNINGS.md
first.
.github/ISSUE_TEMPLATE/config.yml
- Disables blank issues, points users at upstream Polarity docs
for Keystone questions, security policy for vulns,
support@polarity.so for commercial.
.github/CODEOWNERS
- Default reviewer @JayantChopra; explicit ownership for the
reference impl, validation scripts, .github/, and LEARNINGS.md.
.github/workflows/validate.yml
- GitHub Actions: runs bash scripts/validate.sh on every push
to main and every PR targeting main. Catches yaml syntax,
missing fields, weight=0, missing agent slugs before merge.
README repo-structure tree updated to show the .github/ contents.
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
2 participants
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
## 1 — Linksinstead of## §1 — Links. The § was the typographic section sign — accurate but unfamiliar to most readers.─× 74) which wrapped to two lines at GitHub's narrower render width. Replaced with markdown---horizontal rules, which render as a proper full-width<hr>at any viewport.Test plan
§anywhere, all section dividers render as a single horizontal rule (not two stacked lines).