[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-92381":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":9,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":24,"discoverSource":25},92381,"ai-blueprint","bradtraversy\u002Fai-blueprint","bradtraversy","A repeatable process for coding with AI while being the architect of your project",null,"JavaScript",85,19,2,0,10,41.9,false,"main",true,[],"2026-07-22 04:02:06","# AI Coding Blueprint\n\nA starter and repeatable workflow for building real software with an AI assistant,\n**without vibe coding**.\n\nYou provide two short planning docs. The AI turns them into project context,\nfeature specs, and build steps. You build one feature at a time, review every\nspec before code exists, and review every diff before it lands.\n\n## What this is\n\nVibe coding is describing a vague thing and accepting whatever the AI returns.\nIt is fast until it is not: you end up with code nobody understands and a project\nthat cannot be changed safely.\n\nThis blueprint gives the AI a controlled loop:\n\n1. **Spec before code.** Planning skills write a spec and stop. You review it\n   before a single line of code is written.\n2. **Small, reviewable steps.** Each implementation step ends with something\n   observable, a diff you can read, and proof that the done-when was met.\n3. **One feature at a time.** `blueprint\u002Fcontext\u002Fcurrent-feature.md` holds exactly\n   one feature or fix. Finish it, archive it, then move on.\n\nThe point is not to type less. It is to stay in control of a codebase the AI is\nhelping you write.\n\n## At a glance\n\n| Principle | What it means |\n| ---- | ---- |\n| Spec first | The AI writes a feature or fix spec, then stops for review before code. |\n| Small diffs | Implementation happens one reviewed step at a time, with proof each step works. |\n| File-backed state | Plans, current work, and history live in markdown files, so context clears are survivable. |\n| Tool adapters | Codex uses `.agents\u002Fskills`; Claude Code uses `.claude\u002Fskills`. |\n| Optional visibility | Commit the workflow files for portability, or keep them local with `.gitignore`. |\n\n## Quick start\n\nScaffold the app first, then install the Blueprint.\n\n> [!IMPORTANT]\n> Scaffold your app first, then install the Blueprint. Do not run a framework\n> scaffolder inside a folder that already contains Blueprint files.\n\n**1. Scaffold your app** in a new, empty directory. Next.js is only an example\nhere; use any stack or scaffolder you want:\n\n```bash\nnpx create-next-app@latest my-app\ncd my-app\n```\n\nMake sure the app is a **git repo**. The build loop works on branches and\nsquash-merges. Some scaffolders run `git init` for you; if yours does not, run it\nyourself:\n\n```bash\ngit init\n```\n\n**2. Add the blueprint** from inside the app:\n\n```bash\nnpx create-ai-blueprint@latest\n```\n\nYou can also run `npm create ai-blueprint@latest`.\n\nThe installer asks which AI tool adapters you want and adds only the Blueprint\nworkflow files your app needs.\n\n> [!IMPORTANT]\n> After installing, run `\u002Fonboard` before filling in plans or running\n> `\u002Foverview`. This is the setup pass that makes the Blueprint match your actual\n> project. If Claude Code was already open when the Blueprint was installed,\n> restart Claude Code in that folder so the newly added project skills appear.\n\n**3. Run onboard before anything else.** This detects the stack and may edit the\nsetup files that ship with the overlay: `AGENTS.md` commands, the `CLAUDE.md`\nproject title when present, `blueprint\u002Fcontext\u002Fcoding-standards.md`,\n`blueprint\u002Fcontext\u002Fai-interaction.md`, `.gitignore`, adapter recommendations, and\nREADME placement. It also asks whether Blueprint workflow files should be\ncommitted or kept local-only through `.gitignore`:\n\n```text\n\u002Fonboard\n```\n\nIn Codex, invoke it as `$onboard`. In Claude Code, invoke it as `\u002Fonboard`.\n\n**4. Review the setup.** Skim\n[blueprint\u002Fcontext\u002Fcoding-standards.md](blueprint\u002Fcontext\u002Fcoding-standards.md) and\n[blueprint\u002Fcontext\u002Fai-interaction.md](blueprint\u002Fcontext\u002Fai-interaction.md). Adjust\nanything `\u002Fonboard` flagged or anything that does not match how you want to work.\nIf something feels off, run `\u002Fdoctor`; it is a read-only health check for the\nBlueprint setup.\n\n**5. Plan the app.** Fill in the two files you own:\n\n- [blueprint\u002Fproject-plan.md](blueprint\u002Fproject-plan.md)\n- [blueprint\u002Fbuild-plan.md](blueprint\u002Fbuild-plan.md)\n\nThe project plan can be rough notes. The build plan should become a numbered\ncheckbox list because the build loop uses checked and unchecked items to know\nwhat is next. If your first pass is just bullets, `\u002Foverview` will flag that and\ncan propose a cleaned-up checkbox version before generating context.\n\n**6. Generate the overview once.** This checks the two planning docs, helps shape\nthe build plan if needed, then turns them into\n`blueprint\u002Fcontext\u002Fproject-overview.md`, the AI-facing source of truth:\n\n```text\n\u002Foverview\n```\n\nRe-run `\u002Foverview` only when `project-plan.md` or `build-plan.md` changes.\n\n**7. Repeat the build loop.** Once the overview exists, build one feature or fix\nat a time:\n\n```text\n\u002Ffeature\n\u002Fimplement\n\u002Fcheck\n\u002Fcomplete\n```\n\nThat loop specs the next feature, builds it, proves it works, then archives and\nmerges it.\n\nIn Codex, invoke the same steps as skills (`$overview`, `$feature`, `$implement`,\n`$check`, `$complete`) or ask naturally, such as \"run the overview.\" In Claude\nCode, use the slash commands shown above.\n\n### Already have a codebase?\n\nIf the app already has meaningful shipped features, use `\u002Fadopt` instead of\n`\u002Fonboard`. Install the Blueprint, then run:\n\n```text\n\u002Fadopt\n```\n\n`\u002Fadopt` surveys the real repo, asks for the intent the code cannot reveal, then\ngenerates the planning docs and coding standards from what already exists. Then\nrun `\u002Foverview` and continue through the normal build loop.\n\n## The AI workflow\n\nAI loops are popular because the assistant can plan, act, check the result, and\niterate. This blueprint turns that idea into a project workflow with human review\ngates and a written history.\n\nThe core build loop is:\n\n```text\n\u002Ffeature -> review spec -> \u002Fimplement -> \u002Fcheck -> \u002Fcomplete\n```\n\nUse `\u002Ftry` when you want a manual review path, `\u002Faudit` when you want a read-only\ncode quality pass before closing the work, and `\u002Frelease` after a completed\nfeature or milestone when you want Render or Vercel deployment prep.\n\nFor unplanned bugs or small changes, use the fix loop:\n\n```text\n\u002Ffix \"what is wrong\" -> review spec -> \u002Fimplement -> \u002Fcheck -> \u002Fcomplete\n```\n\nIn this repo, **the build loop** means:\n\n- **`\u002Ffeature`** selects the next planned feature and writes a buildable spec.\n- **`\u002Ffix`** writes a smaller spec for an unplanned bug or change.\n- **`\u002Fimplement`** builds the current spec one reviewed step at a time.\n- **`\u002Fcheck`** runs the real app and proves the done-whens.\n- **`\u002Fcomplete`** archives the spec, commits the finished work, and merges with\n  your approval.\n\nThe loop is the control system. The AI can keep iterating, but only inside the\ncurrent spec, with observable checks and review gates.\n\nThe diagram shows the fresh-project workflow. `\u002Foverview` happens after planning\nand only re-runs when the plans change; the repeating loop starts at `\u002Ffeature`\nor `\u002Ffix`. For an existing codebase, use `\u002Fadopt` instead of `\u002Fonboard`; that\npath is described above.\n\n```mermaid\nflowchart TD\n    OB([\"\u002Fonboard\u003Cbr\u002F>fresh setup\"])\n\n    subgraph planning[\"planning files\"]\n        PP[\"project-plan.md\"]\n        BPL[\"build-plan.md\"]\n    end\n\n    OB -->|fill next| PP\n    OB -->|fill next| BPL\n    PP --> OV([\"\u002Foverview\"])\n    BPL --> OV\n    OV --> POV[\"project-overview.md\u003Cbr\u002F>source of truth\"]\n    POV -.->|optional| PT([\"\u002Fprototype\"])\n    PT -.-> PRO[\"prototypes\u002F\"]\n    POV -.->|understand, read-only| BR([\"\u002Fbrief\"])\n    BR -.-> FT\n\n    POV --> FT([\"\u002Ffeature\"])\n    POV --> FX([\"\u002Ffix\"])\n    FT --> CF[\"current-feature.md\"]\n    FX --> CF\n    CF --> IM([\"\u002Fimplement\u003Cbr\u002F>build + iterate, reviewed\"])\n    IM -.->|prove done-whens| CK([\"\u002Fcheck\"])\n    IM -.->|manual path| TRY([\"\u002Ftry\"])\n    IM -.->|quality pass| AU([\"\u002Faudit\"])\n    CK -.->|fails| IM\n    TRY -.->|issues| IM\n    AU -.->|findings| IM\n    CK -.->|passes| CP\n    TRY -.->|looks good| CP\n    AU -.->|clean| CP\n    IM --> CP([\"\u002Fcomplete\u003Cbr\u002F>commit + merge + log\"])\n    CP --> AR[\"blueprint\u002Fhistory\u002F\"]\n    AR -.->|next| FT\n\n    classDef skill fill:#2563eb,stroke:#1e40af,color:#ffffff;\n    class OB,OV,PT,BR,FT,FX,IM,CP,CK,TRY,AU skill;\n```\n\n## The two files you own\n\n| File | What it is |\n| ---- | ---------- |\n| [blueprint\u002Fproject-plan.md](blueprint\u002Fproject-plan.md) | The **what and why**: problem, users, features, data, tech, monetization, and UI\u002FUX. Answer each section in a line or two. |\n| [blueprint\u002Fbuild-plan.md](blueprint\u002Fbuild-plan.md) | The **ordered feature list**: one line per feature, in rough build order. No deep detail here. |\n\nThese two files are the inputs you maintain. Draft them yourself or with the AI.\nYour job is to decide and own what goes in them. The AI can help with wording,\nexpansion, and tradeoffs.\n\n> [!TIP]\n> Keep these files short and decisive. The overview step will turn them into more\n> concrete project context.\n\n## What gets generated\n\n| File | Generated by | What it is |\n| ---- | ------------ | ---------- |\n| [blueprint\u002Fcontext\u002Fproject-overview.md](blueprint\u002Fcontext\u002Fproject-overview.md) | `\u002Foverview` | The single source of truth the AI reads every session, generated from the two planning docs. |\n| [blueprint\u002Fcontext\u002Fcurrent-feature.md](blueprint\u002Fcontext\u002Fcurrent-feature.md) | `\u002Ffeature` or `\u002Ffix` | The spec for the one feature or fix being built right now, including build steps and done-whens. |\n| `blueprint\u002Fhistory\u002Ffeatures\u002FNN-name.md` | `\u002Fcomplete` | The archive of finished feature specs. |\n| `blueprint\u002Fhistory\u002Ffixes\u002FNN-name.md` | `\u002Fcomplete` | The archive of finished fix specs. |\n\nFix the planning docs, then regenerate. Do not hand-edit generated context unless\nthe skill tells you to.\n\n> [!WARNING]\n> Treat generated context as downstream output. When the plan changes, update the\n> planning docs and re-run the relevant skill instead of patching generated files\n> by hand.\n\n## Using the workflow\n\nAfter `\u002Fonboard` and after filling in the two planning docs, run `\u002Foverview`. It\nchecks that the plans are usable, proposes a normalized checkbox build plan if\nneeded, distills the docs into `blueprint\u002Fcontext\u002Fproject-overview.md`, and\nreports contradictions or gaps under **Open questions**. Answer those questions\nin the plans, then re-run `\u002Foverview`.\n\nIf you are unsure whether setup is complete, the plans are ready, or the overview\nis current, run `\u002Fdoctor`. If setup is healthy and you just need to know where\nthe build loop stands, run `\u002Fstatus`.\n\nThen repeat the build loop for each feature:\n\n1. Optionally run **`\u002Fbrief`** first to preview what the next feature involves -\n   scope, dependencies, size - without writing anything. Then run **`\u002Ffeature`**\n   to spec the next unchecked build-plan item. You can also pass a number or name,\n   such as `\u002Ffeature 3` or `\u002Ffeature \"login\"`.\n2. Review `blueprint\u002Fcontext\u002Fcurrent-feature.md` before code is written.\n3. Run **`\u002Fimplement`**. It branches, builds one step, shows the diff, proves the\n   done-when, and waits for approval before moving on.\n4. Run **`\u002Fcheck`** when you want an outside proof pass against the real app.\n5. Run **`\u002Ftry`** when you want the manual review path: where to go, what to\n   click or run, and what to expect.\n6. Run **`\u002Fcomplete`** when the feature is done. It archives the spec, checks off\n   the build plan, commits the finished work, and squash-merges with your\n   go-ahead. After the merge, it must ask separately before pushing main.\n7. Optionally run **`\u002Frelease render`** or **`\u002Frelease vercel`** when you want\n   local deployment config and a provider-specific readiness check.\n\n### Fixes\n\nUse `\u002Ffix` instead of `\u002Ffeature`:\n\n```text\n\u002Ffix \"password reset email never sends\"\n```\n\nIf you already described the problem in chat, `\u002Ffix` can use that context. It\nneeds an argument or clear problem statement; it does not scan the app and\nmagically know what to fix.\n\nThen continue with `\u002Fimplement`, `\u002Fcheck`, and `\u002Fcomplete`. Fixes are logged to\n`blueprint\u002Fhistory\u002Ffixes\u002F` and do not change `build-plan.md`.\n\n## Command reference\n\n| Skill | Run it | Does |\n| ----- | ------ | ---- |\n| **\u002Fonboard** | once, after installing into a fresh or early project | Detects the stack, updates commands and conventions, asks whether Blueprint workflow files should be committed or kept local-only, checks `.gitignore`, and tells you what to fill in before `\u002Foverview`. |\n| **\u002Fdoctor** | any time, especially after `\u002Fonboard` or when setup feels off | Runs a read-only health check for Blueprint files, adapters, commands, root README placement, ignore rules, planning readiness, overview freshness, workflow drift, and git state. |\n| **\u002Fadopt** | once, for an existing codebase | Surveys the repo, protects the project README, and generates the planning docs and coding standards from what already exists. |\n| **\u002Foverview** | after writing or editing the plans | Checks plan quality, normalizes rough build-plan bullets when approved, and generates `blueprint\u002Fcontext\u002Fproject-overview.md`. |\n| **\u002Fbrief** | before spec'ing, or when deciding what's next | Read-only briefing on an upcoming build-plan feature - scope, dependencies, what it touches, size, likely split - without writing anything. |\n| **\u002Ffeature** | for each planned feature | Specs the next unchecked feature, or a selected feature, into `current-feature.md`. |\n| **\u002Ffix** | for an unplanned bug or small change | Specs an ad-hoc fix into `current-feature.md`. |\n| **\u002Ftests** | when you want unit tests added | Adds or normalizes the stack-native unit test setup, adds one example test, updates `AGENTS.md`, and runs build plus tests. |\n| **\u002Fimplement** | after reviewing a spec | Builds the current spec one small, reviewed step at a time, then ends with a compact review packet. |\n| **\u002Fcheck** | before wrapping up, or any time you want proof | Runs the real app and reports pass\u002Ffail against the spec's done-whens. |\n| **\u002Ftry** | when you want to review manually | Gives a human walkthrough: what to start, where to go, what to click or run, what to expect, and what would count as wrong. |\n| **\u002Faudit** | before closing a feature, or any time quality feels suspect | Runs a read-only code quality audit for duplication, dead code, DRY issues, standards drift, missing tests, and maintainability risks. |\n| **\u002Fcomplete** | when work is built and reviewed | Runs a final safety pass, archives the spec, commits the finished work, and merges with your approval. Pushes main only after a separate yes. |\n| **\u002Frelease** | after a completed feature or milestone | Prepares Render or Vercel deployment readiness, local config, env var review, and smoke-test steps. Never deploys or changes remote services without a separate yes. |\n| **\u002Fprototype** | before the build loop | Creates throwaway static mockups to explore the look and feel. |\n| **\u002Fstatus** | any time | Shows build-plan progress, current work, overview freshness, git state, workflow drift warnings, and the suggested next action. |\n| **\u002Fautopilot** | experimental, explicit opt-in only | Runs one bounded spec\u002Fbuild\u002Fcheck pass without pausing after each passing implementation step, then stops with a review packet before `\u002Fcomplete`. |\n\nThese commands are the structured path, not a cage. You can describe a feature,\nfix, or change directly in chat at any time. Use the skills when you want the\nrepeatable loop, review gates, and history.\n\n### Experimental: Autopilot\n\n`\u002Fautopilot` or `$autopilot` is an experimental, explicit opt-in mode for one\nbounded pass. It can pick or resume a feature, write the spec when needed,\nimplement small steps, run build\u002Ftests\u002Fchecks, create checkpoint commits on the\nfeature branch after passing steps, self-review the diff, and stop with a review\npacket.\n\nAutopilot does not replace the normal workflow. `\u002Ffeature`, `\u002Fimplement`,\n`\u002Fcheck`, and `\u002Fcomplete` remain the conservative default.\n\nAutopilot always stops before `\u002Fcomplete`, merge, push, deploy, publish, send,\ndestructive actions, or any action that needs a product decision not covered by\nthe docs.\n\n## Testing\n\nTesting is opt-in. The blueprint installs no test runner because it does not know\nyour stack, but adding one is a normal workflow task.\n\n> [!NOTE]\n> Tests become a required gate only after you add a real `test` command to the\n> Commands section of `AGENTS.md`.\n\nTo add unit testing, run:\n\n```text\n\u002Ftests\n```\n\nThe agent should pick the stack-native runner, reuse an existing runner if one is\nalready present, wire the scripts or commands, add a small example test, and\nupdate the **Commands** section of `AGENTS.md`. For a TypeScript app that usually\nmeans Vitest; Python might use pytest, and Go already has `go test`.\n\n`\u002Ftests` is a setup command, not a product feature. It should not try to write a\nbroad test suite for existing code. It proves the runner works, documents the\ncommand, and turns on the testing gate for future logic-bearing work.\n\nOnce a runner is configured, tests become a gate for logic-bearing steps:\nparsers, validators, server actions, formatters, and similar work should include\na passing test in the same diff. UI and integration work can ride on screenshot,\nbrowser, build, or API evidence from `\u002Fimplement` and `\u002Fcheck`.\n\nFor browser-heavy work, Playwright is preferred when the project already has it\ninstalled or declares a Playwright command. The blueprint does not install it by\ndefault; adding browser automation is a normal setup task when a project wants\nthat level of verification.\n\n## Code quality audits\n\n`\u002Fcheck` proves the app does what the spec promised. `\u002Faudit` reviews the code\nitself.\n\nRun `\u002Faudit` when you want a read-only maintainability pass before closing a\nfeature, after an Autopilot run, or whenever the code feels like it may be\ndrifting. It looks for issues such as duplicated logic, dead code, unused exports,\novergrown modules, inconsistent patterns, missing tests for logic-bearing code,\nsecurity risks, performance risks, and drift from `coding-standards.md`.\n\n`\u002Faudit` reports findings with severity and file references. It does not edit\nfiles, install tools, commit, merge, or push. Fixes stay in `\u002Fimplement` or a\nseparate `\u002Ffix`.\n\n## Manual try guides\n\n`\u002Fcheck` is the agent proof pass. `\u002Ftry` is the human review path.\n\nRun `\u002Ftry` when you want to know what to start, where to go, what to click or\nrun, what to expect, and what would count as wrong. It reads the active feature\nspec when a feature is in progress, or the latest archived feature after\n`\u002Fcomplete`.\n\n`\u002Ftry` is read-only. It does not run the app unless you explicitly ask for that.\n\n## Deployment readiness\n\n`\u002Frelease` prepares a project for Render or Vercel without making deployment an\nautomatic part of the build loop.\n\nUse it after a feature or milestone is complete:\n\n```text\n\u002Frelease render\n\u002Frelease vercel\n```\n\nIt reads the project plans, app commands, package files, and existing provider\nconfig. It can create or update local files such as `render.yaml`, `vercel.json`,\nor `.env.example` when the target is clear. It also runs local build\u002Ftest\u002Fstart\nchecks where possible and ends with the env vars, smoke-test path, blockers, and\nnext provider step.\n\n`\u002Frelease` must stop before deploy, remote service creation, remote env changes,\npush, publish, or any external action unless you explicitly approve that action\nin the current chat.\n\n## Picking up where you left off\n\nYou do not need a separate save\u002Fload command. The blueprint keeps project state\nin files, not the conversation:\n\n- `blueprint\u002Fcontext\u002Fproject-overview.md` is the source of truth.\n- `blueprint\u002Fcontext\u002Fcurrent-feature.md` is the in-progress spec.\n- `blueprint\u002Fbuild-plan.md` says what is done and what is next.\n- `blueprint\u002Fhistory\u002F` plus git keeps the build history.\n\nYou can clear context any time. Between features, run `\u002Ffeature` for the next\nitem. Mid-feature, run `\u002Fimplement` again and it resumes from the first unchecked\nstep in `current-feature.md`.\n\n> [!TIP]\n> If you are unsure what to do next, run `\u002Fstatus`. To understand what a specific\n> upcoming feature involves before spec'ing it, run `\u002Fbrief`. If you are unsure\n> whether the Blueprint is set up correctly, run `\u002Fdoctor`. All three are read-only.\n\n## File map\n\n```text\n.                              (your app: src\u002F, package.json, README.md, ...)\n├── CLAUDE.md                  (Claude Code entry; imports AGENTS.md + context)\n├── AGENTS.md                  (agent instructions for Codex, Cursor, and others)\n├── .agents\u002F\n│   └── skills\u002F                (Codex repo skills)\n│       ├── adopt\u002F             ($adopt: bootstrap from an existing codebase)\n│       ├── doctor\u002F            ($doctor: read-only Blueprint health check)\n│       ├── onboard\u002F           ($onboard: finish fresh-project setup)\n│       ├── overview\u002F          ($overview: plans to project-overview.md)\n│       ├── brief\u002F             ($brief: preview a build-plan feature)\n│       ├── feature\u002F           ($feature: build-plan item to current-feature.md)\n│       ├── fix\u002F               ($fix: document an ad-hoc fix)\n│       ├── tests\u002F             ($tests: add unit testing)\n│       ├── implement\u002F         ($implement: build the current spec)\n│       ├── check\u002F             ($check: prove the done-whens)\n│       ├── try\u002F               ($try: manual review guide)\n│       ├── audit\u002F             ($audit: code quality review)\n│       ├── complete\u002F          ($complete: commit, merge, and log)\n│       ├── release\u002F           ($release: Render or Vercel readiness)\n│       ├── prototype\u002F         ($prototype: static mockups)\n│       ├── status\u002F            ($status: where things stand)\n│       └── autopilot\u002F         ($autopilot: experimental bounded pass)\n├── .claude\u002F\n│   └── skills\u002F                (Claude Code skills and slash commands)\n│       ├── adopt\u002F             (\u002Fadopt: bootstrap from an existing codebase)\n│       ├── doctor\u002F            (\u002Fdoctor: read-only Blueprint health check)\n│       ├── onboard\u002F           (\u002Fonboard: finish fresh-project setup)\n│       ├── overview\u002F          (\u002Foverview: plans to project-overview.md)\n│       ├── brief\u002F             (\u002Fbrief: preview a build-plan feature)\n│       ├── feature\u002F           (\u002Ffeature: build-plan item to current-feature.md)\n│       ├── fix\u002F               (\u002Ffix: document an ad-hoc fix)\n│       ├── tests\u002F             (\u002Ftests: add unit testing)\n│       ├── implement\u002F         (\u002Fimplement: build the current spec)\n│       ├── check\u002F             (\u002Fcheck: prove the done-whens)\n│       ├── try\u002F               (\u002Ftry: manual review guide)\n│       ├── audit\u002F             (\u002Faudit: code quality review)\n│       ├── complete\u002F          (\u002Fcomplete: commit, merge, and log)\n│       ├── release\u002F           (\u002Frelease: Render or Vercel readiness)\n│       ├── prototype\u002F         (\u002Fprototype: static mockups)\n│       ├── status\u002F            (\u002Fstatus: where things stand)\n│       └── autopilot\u002F         (\u002Fautopilot: experimental bounded pass)\n└── blueprint\u002F\n    ├── README.md             (workflow docs installed here)\n    ├── project-plan.md        (you write: what and why)\n    ├── build-plan.md          (you write: ordered feature list)\n    ├── context\u002F\n    │   ├── project-overview.md  (generated by \u002Foverview)\n    │   ├── coding-standards.md  (your conventions)\n    │   ├── ai-interaction.md    (how the AI works with you)\n    │   └── current-feature.md   (generated by \u002Ffeature or \u002Ffix)\n    └── history\u002F\n        ├── features\u002F          (completed feature specs)\n        └── fixes\u002F             (completed fix specs)\n```\n\n`AGENTS.md`, `CLAUDE.md`, `.agents\u002F`, and `.claude\u002F` stay at the repo root\nbecause the tools that read them look there. Everything else owned by the\nworkflow lives under `blueprint\u002F`, so it stays out of your app code.\n\nThis file map shows the portable, committed layout. During `\u002Fonboard`, you can\nchoose local-only mode instead. That keeps `AGENTS.md` public as a lightweight\nproject guide, but adds this to `.gitignore`:\n\n```gitignore\n# AI Blueprint local workflow files\n.agents\u002F\n.claude\u002F\nblueprint\u002F\nCLAUDE.md\n```\n\nIn local-only mode, `\u002Fonboard` should keep public `AGENTS.md` focused on project\ndescription, commands, testing status, and conventions, not the hidden workflow\ndocs or skill list.\n\nLocal-only mode keeps the workflow contents out of the repo, but it is not\nportable by itself. Another machine needs the Blueprint reinstalled or restored\nlocally. If those paths were already committed, `.gitignore` is not enough; you\nmust explicitly approve untracking them with `git rm --cached` while keeping the\nlocal files.\n\nWhen editing shared workflow behavior, keep the matching files in `.agents\u002Fskills`\nand `.claude\u002Fskills` aligned. Tool-specific invocation text is fine, but the\nactual build loop should stay the same across both adapters.\n\n## Notes\n\n### This is not an app skeleton\n\nThe installed Blueprint overlay does not add a project-level `package.json`.\nScaffold the app first with whatever stack you like, then install these files.\nThat keeps the workflow stack-agnostic: the same process can guide a Next.js\napp, a Vite SPA, a Python service, or something else.\n\nThe defaults in `coding-standards.md` assume Next.js, TypeScript, Tailwind, and\nPrisma. Change them to match your project. To keep the install low-conflict, the\nblueprint avoids root files a framework scaffold usually creates, like\n`.gitignore`, `package.json`, lockfiles, `tsconfig.json`, or `eslint.config.mjs`.\n\n### Prototyping is separate\n\nLocking the look with mockups, Figma, v0, or static HTML is exploratory work. Do\nit before the build loop and let the result inform the UI\u002FUX section of your\nproject plan. The `\u002Fprototype` helper can create throwaway static mockups in\n`prototypes\u002F`.\n\n### Works in other tools\n\nThe blueprint is not Claude-specific. `AGENTS.md` is the cross-tool entry point,\n`.agents\u002Fskills` exposes the workflow to Codex, and `.claude\u002Fskills` exposes it\nto Claude Code.\n\nYou do not have to keep both adapters. For Codex-only work, keep `AGENTS.md`,\n`.agents\u002F`, and `blueprint\u002F`. For Claude Code-only work, keep `AGENTS.md`,\n`CLAUDE.md`, `.claude\u002F`, and `blueprint\u002F`. Keep both adapters if you switch\nbetween tools.\n\nUse the native invocation style for your tool:\n\n- Codex: `$onboard`, `$doctor`, `$adopt`, `$overview`, `$brief`, `$feature`,\n  `$fix`, `$tests`, `$implement`, `$check`, `$try`, `$audit`, `$complete`,\n  `$release`, `$prototype`, `$status`, or plain language like \"run the overview.\"\n  Experimental: `$autopilot`.\n- Claude Code: `\u002Fonboard`, `\u002Fdoctor`, `\u002Fadopt`, `\u002Foverview`, `\u002Fbrief`,\n  `\u002Ffeature`, `\u002Ffix`, `\u002Ftests`, `\u002Fimplement`, `\u002Fcheck`, `\u002Ftry`, `\u002Faudit`,\n  `\u002Fcomplete`, `\u002Frelease`, `\u002Fprototype`, `\u002Fstatus`. Experimental: `\u002Fautopilot`.\n- Other tools: ask the agent to follow the matching `SKILL.md`.\n\n```text\nrun the overview by following .agents\u002Fskills\u002Foverview\u002FSKILL.md\n```\n","这是一个面向开发者的AI辅助编程工作流模板，旨在帮助工程师在使用AI编码时保持对项目架构和技术决策的主导权。核心特点是采用‘先规范后编码’的受控循环：用户通过编写简短规划文档定义上下文与需求，AI据此生成可评审的功能规格与分步实现计划，开发者逐项审查规格与代码变更后再合并。所有状态均以Markdown文件持久化，支持Next.js等主流框架，并提供Codex、Claude Code等AI工具的适配器。适用于希望提升AI协作质量、保障代码可维护性与团队可控性的中小型软件开发场景。","2026-07-08 04:30:13","CREATED_QUERY"]