[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-11353":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":15,"subscribersCount":15,"size":15,"stars1d":15,"stars7d":16,"stars30d":17,"stars90d":15,"forks30d":15,"starsTrendScore":15,"compositeScore":18,"rankGlobal":10,"rankLanguage":10,"license":10,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":33,"readmeContent":34,"aiSummary":35,"trendingCount":15,"starSnapshotCount":15,"syncStatus":36,"lastSyncTime":37,"discoverSource":38},11353,"facts","av\u002Ffacts","av","Antidote for fluffy specs, a toolkit for fact-driven development with AI agents","",null,"Rust",182,7,1,0,4,71,2.71,false,"main",true,[23,24,25,26,27,28,29,30,31,32],"agents","claude-code","codex","copilot","gemini","llm","skills","spec-driven-development","specification","vibe-coding","2026-06-12 02:02:31","\u003Cdiv align=\"center\">\n\n\u003Cimg src=\"assets\u002Freadme\u002Fhero.png\" alt=\"facts\" width=\"800\" \u002F>\n\n\n\nhttps:\u002F\u002Fgithub.com\u002Fuser-attachments\u002Fassets\u002F80981efb-8bab-47ee-a567-3eb6071321ad\n\n\n\nRead your entire project spec in 30 seconds. Verify it in one command.\n\n[![MIT License](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002Flicense-MIT-blue.svg)](LICENSE)\n[![Release](https:\u002F\u002Fimg.shields.io\u002Fgithub\u002Fv\u002Frelease\u002Fav\u002Ffacts)](https:\u002F\u002Fgithub.com\u002Fav\u002Ffacts\u002Freleases)\n\n\u003C\u002Fdiv>\n\nYour project has 48 facts, 31 of them implemented: code-backed, verified by command. 12 are specs your agent is working through. 5 are rough drafts you'll refine later. You know all of this because you ran `facts check`.\n\n```\n# auth\n- users authenticate via OAuth2 @implemented\n- sessions expire after 24 hours @implemented\n- failed logins rate-limited to 5 per minute @spec\n- label: bcrypt password hashing with cost factor 12\n  command: grep -q 'bcrypt.*12' src\u002Fauth.ts\n\n# data\n- all timestamps stored in UTC @implemented\n- soft deletes only, no rows dropped @spec\n- PII encrypted at rest @draft\n\n# api\n- REST with versioned endpoints @implemented\n- rate limiting on all public routes @spec\n- structured error responses with error codes @spec\n```\n\nThat's a `.facts` file, where each line is one atomic claim about your project. Tags track where each fact is in its lifecycle: `@draft` (rough idea), `@spec` (precise, ready to build), `@implemented` (true, code-backed). Your agent manages the transitions. The format is a flat list of claims: short enough to read in full, structured enough to manage, and when a fact has a shell command, the machine verifies it so the agent doesn't have to.\n\n## Install\n\nGive your agent the facts skill:\n\n```sh\nnpx skills add av\u002Ffacts\n```\n\nThen ask it to **Init facts**. It detects your stack, creates a `.facts` file with initial project truths, and sets up the full workflow.\n\n\u003Cdetails>\n\u003Csummary>Manual install\u003C\u002Fsummary>\n\n```sh\ncurl -fsSL https:\u002F\u002Fav.codes\u002Ffacts.sh | sh\n```\n\n```sh\nnpm install -g @avcodes\u002Ffacts        # or npm\npipx install facts-cli               # or pipx\n```\n\nIt's a single Rust binary with two dependencies, running on Linux, macOS, and Windows.\n\nThen scaffold your project:\n\n```sh\ncd your-project\nfacts init\nfacts check\n```\n\n\u003C\u002Fdetails>\n\n## Agent skills\n\nFour skills ship with every install. Your agent uses them to manage the full lifecycle without you directing every step.\n\n| Skill | What it does |\n|-------|-------------|\n| **facts** | Core operations: read the spec, check it, add and edit facts |\n| **facts-discover** | Scan the codebase, classify every fact by lifecycle stage, add missing truths |\n| **facts-refine** | Pick up `@draft` facts, sharpen them into precise `@spec` facts with you |\n| **facts-implement** | Pick up `@spec` facts, build them in code, verify, tag `@implemented` |\n\nThe workflow is a loop: you write rough ideas as `@draft`. The agent refines them into specs. Then it implements them, runs `facts check`, and tags what it built. You see the progress in the fact sheet, right there in the spec itself.\n\n```\n@draft → @spec → @implemented\n```\n\nEvery fact moves through this pipeline. At any point you can run `facts check` and know exactly where your project stands: what's done, what's in progress, and what's still just an idea.\n\n---\n\n## How it works\n\n\u003Cimg src=\"assets\u002Freadme\u002Fhowto-1.png\" alt=\"1. Describe\" width=\"700\" \u002F>\n\n**Describe** what should be true by writing claims as plain strings, one fact per line. Use `#` headings to organize by domain, tag each fact with its lifecycle stage, and for facts the machine can verify, add a `command` that exits 0 when the claim holds.\n\n\u003Cimg src=\"assets\u002Freadme\u002Fhowto-2.png\" alt=\"2. Verify\" width=\"700\" \u002F>\n\n**Verify** your facts with `facts check`, which lints all files, runs every command, and groups results by status: green pass, red fail, yellow manual. Facts without commands are verified by the agent against the codebase. It exits 0 when everything passes, non-zero when anything fails. Plug it into CI or let your agent run it after every change.\n\n\u003Cimg src=\"assets\u002Freadme\u002Fhowto-3.png\" alt=\"3. Implement\" width=\"700\" \u002F>\n\n**Implement** against the spec: your agent reads the fact sheet to understand the project, picks up `@spec` facts, builds them, and runs `facts check` to verify its own work. When a fact passes, it tags `@implemented`, and the spec updates itself as the project evolves.\n\n---\n\n## The format\n\nA `.facts` file is valid Markdown *and* valid YAML per section.\n\n```\n# section\n- a plain string fact @tag\n- label: a fact with a check command\n  command: test -f src\u002Fmain.rs\n  tags: [core, mvp]\n```\n\n| Key | Required | Purpose |\n|-----|----------|---------|\n| `label` | yes | The claim |\n| `command` | no | Shell command, exit 0 = true |\n| `tags` | no | Freeform tokens for filtering |\n| `id` | no | Override the auto-generated ID |\n\n**Tags** filter with boolean expressions: `--tags \"core and not blocked\"`. Three well-known tags (`@draft`, `@spec`, `@implemented`) drive the lifecycle, but any tag works.\n\n**Sections** use Markdown headings. Nesting creates hierarchy addressable by path (`api\u002Fauth`). Created when you add to them, removed when empty.\n\n**IDs** are short hashes of the label, stable as long as the label doesn't change.\n\n---\n\n## Commands\n\nCommon short aliases (all extra args are passed through to the real command):\n\n- `ll` = `list --light`  `ls` = `list`\n- `rm` = `remove`\n- `at \u003Cid> \u003Ctag>` = `edit \u003Cid> --add-tag \u003Ctag>`  `rt \u003Cid> \u003Ctag>` = `edit \u003Cid> --remove-tag \u003Ctag>`\n\n```\nfacts                                    # list all facts (default)\nfacts ll                                 # list in markdown-like skim format\nfacts ll --tags \"draft\"                  # combine alias + filter\nfacts check                              # verify everything\nfacts check --tags \"mvp and not blocked\" # filter by tag expression\nfacts add \"claim\" --section api          # add a fact\nfacts at \u003Cid> spec                       # quick tag add (or use the full edit form)\nfacts rt \u003Cid> draft                      # quick tag remove\nfacts remove \u003Cid>                        # remove a fact\nfacts get \u003Cid>                           # look up a single fact\nfacts move \u003Cid> --section new\u002Fpath       # relocate a fact\nfacts list --section api\u002Fauth            # filter by section\nfacts lint                               # validate structure\nfacts fmt                                # normalize all files\nfacts init                               # scaffold + install skills\nfacts uninit                             # remove facts from project\n```\n\n---\n\n## Dogfooding\n\nThis repo uses a `.facts` file to describe itself: 224 facts, 154 verified by command, none failing.\n\n```\n$ facts check\n...\n154 passed, 0 failed, 70 manual\n```\n\nClone the repo, install facts, and run `facts check` to see it work on itself.\n\n---\n\n## License\n\nMIT\n","av\u002Ffacts 是一个用于项目规格管理和验证的工具。它通过`.facts`文件来定义项目的原子性声明，每个声明都带有生命周期标签（如@draft, @spec, @implemented），帮助开发者清晰地了解项目的当前状态和发展方向。该工具使用Rust编写，支持Linux、macOS和Windows平台，并且可以通过简单的命令行操作进行安装与使用。特别适用于需要高效管理项目需求和自动化验证代码实现是否符合设计规范的开发场景中，能够显著提高团队协作效率及代码质量。",2,"2026-06-11 03:31:42","CREATED_QUERY"]