docs(readme): rewrite to reflect current dev surface#108
Merged
Conversation
The previous README claimed the site was "static HTML + CSS, no build step" and described scorecards plus a live-scoring form at incorrect routes. None of that has been accurate since the build pipeline, Cloudflare Worker, scorecard renderer, live-scoring loop, and skill bundle endpoint landed. The rewrite replaces the four stale sections with: a what-it-serves route table, a stack summary (Worker over Static Assets, build pipeline, DO + R2 + KV + Turnstile for live scoring), a local-development recipe matching package.json scripts, the full seven-stage pre-push hook list, the branch plus release model pointing at RELEASES.md, a documentation map covering AGENTS / CONTRIBUTING / DESIGN / BRAND / PRODUCT / RELEASES / docs/runbooks, a related-repositories list, and a Contributing section mirroring the anc CLI README (three-tier shape, local setup recipe, cross-repo routing). Verified: bash scripts/prose-check.sh reports 0 blocking; unslop scores 0 (clean) after the route list was restructured from em-dashed bullets into a real table.
Stale carry-over from the v0 spec which had seven principles. The site copy
in content/_intro.md ("Eight principles, each expressing a requirement",
"/p1 through /p8") and the agentnative-cli README ("## The 8 Principles")
both reflect eight; only the freshly-rewritten README on this branch still
said seven.
The v0.4.0 CLI README documents the scoring formula (pass / (pass + warn + fail), skips and errors excluded), the MUST/SHOULD/ MAY tier mapping to fail/warn statuses, and the 80% badge eligibility floor. None of that surfaced in the site README even though the site is the public scoring display. Add a tight Scoring section between What it serves and Stack: formula one-liner, tier mapping, badge floor, and pointers to the three pages that hold the full detail (/methodology, /scorecard-schema, /badge), plus a pointer to the scoring engine repo. The site README stays scoped to the site; depth lives on the content pages.
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
Rewrite
README.mdto match the actual state ofdev. The old README claimed the site was "static HTML + CSS, no build step" and described the live-scoring loop at routes that never existed. The new README documents the full surface (route table, stack summary, local development, pre-push gate set, release model, doc map, related repos) and adds a Contributing section mirroring the anc CLI README's three-tier shape.Changelog
Documentation
README.mdto reflect current site surface: route table, Cloudflare Worker plus build pipeline plus live-scoring stack, local development recipe, seven-stage pre-push gate list, branch and release model, documentation map, related repositories, and a three-tier Contributing section.Type of Change
feat: New feature (non-breaking change which adds functionality)fix: Bug fix (non-breaking change which fixes an issue)refactor: Code refactoring (no functional changes)perf: Performance improvementdocs: Documentation updatetest: Adding or updating testschore: Maintenance tasks (dependencies, config, etc.)ci: CI/CD configuration changesstyle: Code style/formatting changesbuild: Build system changesBREAKING CHANGE: Breaking API change (requires major version bump)Related Issues/Stories
Testing
Test Summary:
bash scripts/prose-check.shreports 0 blocking, warnings unchanged from baseline.~/.claude/skills/unslop/scripts/score.py README.mdreports score 0 (clean). The original eight em-dashes lived inside a label-then-description route list; restructuring the list into a table removed every flagged occurrence without substitution.markdownlint-cli2clean on the file (PostToolUse hook each edit).Files Modified
Modified:
README.md(94 insertions, 16 deletions)Created:
Renamed:
Deleted:
Breaking Changes
Deployment Notes
Additional Context
The new Contributing section mirrors the
agentnative-cliREADME contributing section ondev: three-tier shape (Signal / Proposal / Code), local setup recipe, and cross-repo routing that points spec-tier discussion tobrettdavies/agentnative, scoring-engine and registry work tobrettdavies/agentnative-cli, and skill bundle changes tobrettdavies/agentnative-skill. Detailed tier breakdown remains inCONTRIBUTING.md.