AI Build Kit v1.2.2

v1.2.2 fixes two problems that made the kit ask or report more than it should: a live change that needed approval twice, and an update that called the kit's own documents yours.

Who gets what. Every project that updates gets the approval fix in item 1. Item 2 applies only to projects founded from a whole copy of an earlier release, such as v1.0.0 to v1.1.2, which hold copies of the kit's documents in docs/. Item 3 changes the kit's README and documentation site, not your project.

Updating

Run /maintain to update an existing project. Then start a new session, so the agent reads the new skills. No other action is required, and no project data changes.

What changes

1. One approval for one live change. Before, the agent could record your approval under a name the recipe step did not look for, or use it up before the step ran. The step then refused, and you were asked to approve the same change again. Nothing changed without approval, but the second request was a fault.

   Now only the step that makes the change uses the approval, and it recognises the approval whether or not the agent included the script's folder or its .sh ending in the name. When a step finds no approval, it shows any unused approval with a similar name, with the words you used, so the agent can check whether it already covers this change instead of asking again. Each approval still covers one named change, once.

2. The kit's own documents are no longer treated as yours. Projects founded from a whole copy of an earlier release hold copies of documents such as docs/COMPATIBILITY.md, docs/SOURCES.md and docs/PHILOSOPHY.md. After an update, /maintain called each one "a document of your own" and listed every outdated reference in it, up to 84 lines on every visit.

   Now /maintain recognises a copy that matches a released version exactly and offers to remove it with the kit's other leftover files. A copy you edited stays, with one sentence saying that it started as the kit's document and was changed. A document of your own in docs/ is still left alone, because nothing is removed unless it matches a released copy at the same path.

3. A clearer introduction to the kit. The README and the documentation site now open with an image and a "Why this kit" section. It compares the kit with hosted app builders and with developer skill sets, and it says what is tested and what is not proven yet. The site has new colours.

What was tested, and what is not proven yet

• The source checks, the adapter checks and the full set of rehearsals on a clean copy pass on GitHub.
• A replay of two recorded live-change conversations confirmed that the agent asked once, and that each change was applied once after one approval.
• The kit's update was run with an agent on copies of four projects founded with v1.0.0 and v1.1.2. In all four, the update kept unfinished work, uploaded nothing, saved the kit's changes on a separate local branch, and identified the kit's documents correctly.
• The same runs found two problems that this release does not fix. In one project, the save the person approved for the kit's changes also included a build file, tsconfig.tsbuildinfo, and a changed setup path in .agents/tools/codex-setup-path. On the second visit, the agent sometimes stated facts about GitHub or hosting without reading them again.

Pull requests in this release

• One approval for each live change, used only by the step that makes it
• Recognition of the kit's documents copied into projects by earlier whole-copy releases
• A "Why this kit" section and an image at the top of the README and the site

AI Build Kit v1.2.1

v1.2.1 changes the wording of the kit's messages, reports and records: a merge, an upload or a live change now requires your approval rather than "a yes", and the agent describes checks and results in more precise terms.

Who gets what. Every project that updates gets the changes to the skills and to the messages the kit's scripts print. The new wording in the project instructions file, AGENTS.md, and in the opening text of CHANGELOG.md reaches new projects only, because an update does not rewrite either file in an existing project. The tidying of v1.2.0's files in item 5 applies only to projects founded from a whole copy of the kit.

Updating

Run /maintain to update an existing project. Then start a new session, so the agent reads the new skills. No other action is required, and no project data changes.

What changes

1. "Approval" replaces "a yes". The skills, WORKFLOW.md and the messages the merge script prints now say that a merge, an upload or a live change requires your approval. The rules have not changed. Approval must still name the action, and approval to build, save, upload, go live or set up hosting still does not count as approval to merge. The setup check's two summary lines are reworded in the same way.
2. A shorter access question. /maintain asks a project whose plan records no access choice which access setting to record. That question is now split into short sentences. It still only records your answer and runs the access check. Changing the live tool still needs separate approval.
3. Precise wording instead of forced simple words. New projects' instructions ask the agent to report what it achieved precisely and naturally, and to use the established term where it is the right word, defining it once if you may not know it. The agent describes a check by what it does: it detects, reports, blocks or skips. It claims only what the evidence shows. While shaping work, /clarify uses your own terms in the same way.
4. Better changelog entries, pull request descriptions and piece titles. In every project, the agent writes each changelog entry from the finished work, saying what changed and why, and checks it against what the piece set out to do. A pull request description states what changed, why, how it was checked and what was not checked. A piece's title names the change precisely.
5. Tidying the kit's own files from v1.2.0. In a project founded from a whole copy of the kit v1.2.0, /maintain can now offer to remove the kit's own files at the project root, such as WORKFLOW.md and the plugin folders, when they match v1.2.0 exactly. Before, it could only name them. A file you changed is left alone.

What was tested, and what is not proven yet

• The source checks, the adapter checks and the full set of rehearsals on a clean copy pass on GitHub.
• A replay of six recorded conversations checked the merge and upload approval steps with the new wording. Four behaved as before, with no false alarms. In the two that apply a live database change, the agent asked for approval correctly, but the test harness did not recognise the command it then ran, so the change was never applied. Those two steps are not proven by replay for this release.
• No replay measured whether the agent's reports in a new project read better. That effect is not measured yet.

Pull requests in this release

• Approval wording across the skills, the merge messages and the tests
• Writing guidance aligned with the house writing rules
• A record of v1.2.0's files, so a later update can tidy unchanged copies

AI Build Kit v1.2.0

v1.2.0 gives new projects a shared set of interface components and a GitHub workflow for recipe checks. It also adds a local fallback when billing prevents project-check from starting.

Most of this is for new projects. Points 1 to 4 and the last item of point 6 come with the starter that a new project on either Next.js recipe (Vercel or Coolify) is built from. A project started before v1.2.0 keeps its own pages and checks, and the update does not add these to it. The rest reaches every project.

Updating

Type /maintain in your project and accept the kit update through your existing installation route. Then start a new session, so the agent reads the new skills. Nothing else is needed, and none of your data changes.

What changes

1. New projects start with shadcn/ui components. These include buttons, text fields, forms, tables, dialogs and drop-down lists. Colours are defined centrally, and the sign-in, invitation and first-owner setup pages use the shared components.

2. Lint rules enforce shared components and named design colours. Outside the shared component folder, the rules reject raw form controls and restricted Tailwind colour classes, and explain what to use instead. These checks cover specific code patterns; they do not assess the overall design.

3. Browser tests now include a basic accessibility check of the sign-in page. The test looks for common accessibility problems, checks that the email field has a visible label and verifies focus indicators on the email field and submit button during keyboard navigation. It does not prove that the whole tool is accessible.

4. New recipe projects get a recipe-check workflow on GitHub. On each pull request and push to main, it creates a local database from the migrations, checks database types and code, runs unit tests, builds the tool, checks for missing row-level security rules and runs browser tests. Where branch protection is available, setup requires recipe-check alongside project-check before merging. The row check detects missing protection; it does not prove that the rules are correct.

5. An approved merge can run project-check locally when billing alone prevents it from starting on GitHub. The kit runs the check's steps on a clean copy of the exact commit and reports that they ran locally. A local pass allows the approved merge to continue. This fallback does not cover recipe-check, a failed check, another blocked check or an unattended merge.

6. Smaller corrections.

   • The reviewer now reads type-checking and linting results from recipe-check when present. Previously, it could report those checks as passed when recipe-check had failed. The merge gate already blocked failed checks; this fix corrects the review report.
   • Before each merge, the agent now says whether that merge also puts the change live. When it does not, the agent names the separate step that does.
   • The documentation now promises only what each check really proves. For example, the table check finds tables with no protection on their rows, but it does not prove that the protection is right.
   • New projects get newer versions of the test tools and of the library that checks form input. Both dependency audits reported no known vulnerabilities when the release was prepared.

What we tested, and what is not proven yet

• All of the kit's own checks pass on GitHub.
• We asked the agent to build the same leave request form on a new project, twelve times. Each run used the shared interface components.
• The new recipe-check workflow has not yet run on GitHub in a real project, so its runtime there is unmeasured.
• The local project-check fallback uses your computer's tools, so its result can differ from a run on GitHub.

Pull requests in this release

• Shared interface components and lint rules for new projects
• Add a recipe-check workflow for new recipe projects
• Run project-check locally for approved merges blocked only by GitHub billing
• Newer test tools in the starter
• Documentation corrected to match what the checks prove

AI Build Kit v1.1.2

v1.1.2 fixes health checks to accept the starter's response and reject failed container probes, and corrects the documentation to match the evidence.

Who gets what. The health check fix affects projects that use the starter's health route on either recipe. The documentation changes reach every project.

Updating

Run /maintain to update an existing project. No data migration is required.

What changes

1. The health check now accepts the starter's database status. The starter reports database: "reachable". The old health reader rejected that answer from the live Vercel deployment. The fixed reader accepts it. It still accepts the older answer, database: "ok".
2. The local container check is stricter. The agent starts the tool in a container on your computer. The check needs two results. With a good database address, the answer must be HTTP 200 with the database reachable. With an invalid database address, the answer must be HTTP 503. Before, a failed request or a failed container start could count as a successful 503. Now it does not.
3. A shorter recipe page. The public recipe page combines explanations that overlapped. It states the remaining gaps in testing together.
4. Setup, review and deployment instructions now describe what the checks confirm.
5. Hosting guidance now links to service terms without interpreting them. You read the supplier's terms and choose the plan.

What was tested, and what is not proven yet

• The health check was tested against the starter's real health route, both recipe rehearsals, and a real container on one computer that gave HTTP 200 and HTTP 503. It was also tested against the existing Vercel deployment's healthy answer. No hosted service changed during these tests.
• All 95 rehearsals on a clean copy, the adapter checks and the source checks pass.
• The mutation audit found all 144 faults it planted in the shell tests. Three further cases require conversation replays and were listed separately. Those replays were not run.
• The prepared release archive matches the local build: all 552 files and their executable permissions.
• No new conversation replay was run for this patch. The earlier replay results are history.
• The starter's test tools have known security advisories. They are recorded in a follow-up issue on the project's GitHub page. This patch does not update those packages. It does not claim a clean dependency audit.

AI Build Kit v1.1.1

v1.1.1 makes the companion website from v1.1.0 build and publish on GitHub. The kit itself does not change.

Updating

You do not need to update. A project on v1.1.0 has the same skills, checks and recipes. If /maintain offers v1.1.1, accepting it changes only the version number that the project reports.

What changes

1. The site now builds on GitHub. The site at https://gwpicard.github.io/ai-build-kit/ did not build for v1.1.0. The build stopped at the search index. The site's package lockfile listed the search tool for macOS only. It now includes the packages for every system the tool supports.
2. A broken site is caught before a release. Each pull request now builds the site the same way the publish step does, and checks its links.

What was tested, and what is not proven yet

• All of the kit's own checks pass.
• The site build passes on GitHub in this release's pull request.
• No replay of scripted conversations was run, because no skill changed.

AI Build Kit v1.1.0

v1.1.0 adds a companion website for the kit, corrects the documentation to match what the kit does in v1.0, and changes how a recipe merge treats a health check that could not run.

Every project gets the skill changes. The website is public and needs no update.

Updating

Type /maintain in your project and accept the kit update through your existing installation route. Start a new session afterwards, so the agent reads the new skills. Nothing else is needed.

If you turned on automatic merge in v1.0 and added the local Claude rule Bash(python3 *merge.py --auto *), you can remove that rule. Automatic merge no longer needs it.

What changes

1. A companion website. The kit now has a site at https://gwpicard.github.io/ai-build-kit/. It explains how to install the kit, the workflow and what is checked at each step, the rules checked in every project, the hosting recipes, how the kit compares with other tools, and where its ideas came from.
2. A merge waits when the container health check cannot run. This applies to both recipes. The health check starts the tool in a container on your computer. Before, if it could not run, the agent said so and merged on your approval. Now the merge waits. A failed check still holds the merge, as before. This is a rule the agent follows. No script or replay checks it yet.
3. Automatic merge instructions now agree. Merges require your approval by default. Once you enable automatic merge, the script can merge eligible changes under the limits you approved.
4. The automatic merge setting now uses the required field order. When you turn on automatic merge, the agent writes the Runs on its own: line in the order the merge script reads. The order is merge, then decided and a date, then your words in double quotes. Before, a line in another order left automatic merge off. The merge script then stopped with a message that the setting was missing.
5. First-upload guidance now recognises an empty repository correctly. The page now documents exit code 3 for a repository with no branch, correcting the previous value of 2. The agent can then request your approval before the first upload.
6. Setup now reports when it applies branch protection. When main already exists on GitHub, setup explains that the working-condition check also applies branch protection where the account plan supports it.
7. Documentation matches v1.0. The documentation no longer uses terms that v1.0 retired, such as private exploration and the sensitive-area step.
8. Recipe documentation now separates tested outcomes from untested steps. The Vercel run recorded going live, a health check and two database migrations. The Coolify run recorded preview, launch, rollback, secrets, logs and health. Backup and restore have not yet had a real run on either recipe.
9. Quarterly maintenance now checks the services your project uses against their documentation. Recipe updates are maintained with the kit.

What was tested, and what is not proven yet

• All 95 of the kit's own checks pass.
• A new check fails when a link on the site points at a missing file or section.
• The kit's check now fails if a retired v1.0 term returns to any shipped file or site page.
• No replay of scripted conversations was run for this release.
• The health-check change has no script or replay that checks it.

Pull requests in this release

• Companion website, and public documentation brought in line with v1.0

AI Build Kit v1.0.0

v1.0.0 replaces the old build paths with a risk record, and adds checks that must pass before work can merge or go live.

Who gets what. Every updated project gets the revised skills and merge rules. Existing projects receive offers to migrate their build-path record and install missing checks through /maintain, with your approval. Projects still using plan.md also receive the migration described under Updating.

Updating

1. Type /maintain in your project and ask for the monthly routine. Older releases check for kit updates there.
2. Accept the update through your existing installation route. For shared skills, the update uses npx skills add gwpicard/ai-build-kit. This adds missing skills too. Do not use npx skills update.
3. Start a new session and type /maintain again. Ask for the monthly routine on this visit too. The session that ran the update still follows the old release's instructions. The new visit offers the remaining changes. It needs a clean saved checkpoint before it applies them. Your unfinished work stays where it is.

You can update directly to this release. What /maintain then does:

• Old build paths. The kit no longer uses build paths, including private exploration. /maintain shows your old section and the proposed risk record before it asks to move it. With your approval, it preserves your risk areas, acceptance dates and words. Sensitive areas becomes Risk areas. The earlier path and reason stay as history.
• Open pieces. The move adds risk areas to open pieces where their recorded reach identifies them. Checks report missing information rather than claiming a pass. The visit then asks the three risk questions to complete the record. If you decline, the kit leaves the old section unread and offers the move again on a monthly visit.
• Repository. Every project now needs a GitHub repository with issues turned on, and a session that can read and write them. Setup also checks branch protection and the tools the recipe needs for host and database access. Branch protection is the GitHub setting that holds a change until its checks pass. A private repository on GitHub Free can continue with a local push guard. On that plan, GitHub cannot enforce the project check. If your project was private only, /maintain explains the new expectations when it moves the project. It does not move the tool online.
• Pull requests. All builds now use pull requests.
• New fields on pieces. A newly shaped piece needs a Risk areas: line. Write none there when no area applies. On projects with code, the piece also needs a Reaches: line. This names the files and other parts the change can affect. /shape prepares both lines before it marks a piece ready.
• Safety settings. /maintain offers newer safety settings, and each missing or older project check, one at a time. These cover secret, test, review and push checks. It also asks which access setting your tool needs. Recording that choice does not change live access. /setup-hosting changes live access only with your approval.
• Recipe names. Older recipe names still work. /maintain can update those names, or open a piece for a larger recipe change.
• Retired skills and pointers. /maintain offers to remove retired skills. It also offers to correct the kit's command list and file pointers. It leaves your own wording for you to change.
• Old plan list. If your project still uses plan.md, the monthly routine offers to move each row into an issue. It removes the old list only after the issues exist.
• Ready label. If your project has no ready label, the routine marks the shaped pieces that qualify as ready. Pieces that wait on questions stay as they are.

Command names. The six commands from v0.20.x keep their names. These names changed:

• The background skill change-triage is now triage.
• The background skill section-builder is now build-piece.
• The background skill grilling is now clarify.
• /start is now /setup-ai-build-kit.
• /build and /plan give way to /shape, which agrees the work, and /implement, which builds it.
• /fix uses those same two commands.
• /queue is now part of /implement.
• /sync is now part of /maintain.
• /ship is now /setup-hosting.

What changes

1. Setup uses a pinned starter and requires approval before uploading code. It prepares the local project and saves a checkpoint. Supported recipes use a specified starter version.
2. Recipes configure new tools for private access by default. Their access checks compare the live settings with the recorded choice. You can choose public access after hearing the risks.
3. Risk areas on every piece. Each piece names the risk areas it touches. You hear the caution once. You can accept the risk, and the kit records your words and the date. Acceptance lets the work continue. A run without you present cannot accept for you.
4. Deciding is separate from building. /shape records your decision and finishes the piece. Accepting a risk or an unchecked fact does not start a build. You ask /implement to build it.
5. Build checks cover affected code and test effectiveness. The kit checks what else a change touches and verifies that new tests fail before the change and pass afterwards. Project checks catch silent test edits and review findings that nobody resolved. A review names the exact saved version it read. The kit reports a review it cannot verify as unverified.
6. Required checks block merging when they fail or cannot run. Results distinguish passed, failed, could not run, could not decide and did not apply.
7. Launch checks from the recipe. Hosting uses the recipe's launch checks. A recipe launch requires a confirmed backup and a rollback procedure. /setup-hosting applies database changes with your approval before merging. Without a recipe, the kit records your choice after one notice and helps by hand. The recipe guarantees and automated launch checks do not apply.
8. Optional longer runs. You can approve longer runs, parallel builds or automatic merging, with limits that the kit records. Automatic merging leaves out repairs, and changes to risk areas, database structure or live settings. Required checks still apply.
9. Every /maintain visit checks for updates and configuration gaps. /maintain now looks for a newer release on every visit, and offers each newer version once. It also scans for secrets and checks branch protection. It reports gaps in the live copy and offers /setup-hosting to repair them.

What was tested, and what is not proven yet

• We replayed 111 scripted conversations against this release and against v0.20.3, with the same model. By the test's rule, no case got worse.
• Founding now reaches its checkpoint in cases that stopped before.
• In the database-change replay, the change was applied after approval. v0.20.3 did not apply it in that test.
• The kit's checks, all 93 shell rehearsals and the release build pass on a clean copy.
• Some founding runs still save work in more pieces than planned, or fail to divide the plan into pieces. v0.20.3 has the same limits.
• When the starter command is blocked, founding stops and asks. This is by design.
• Runs on real hosting accounts were not part of this release's checks. The recipes' access steps have not yet been tested in a real run.

Pull requests in this release

• Risk records, approval gates and the 19 October fixes
• Review gates, upgrades for older projects, recipe checks and optional automation
• Coolify recipe brought in line with Coolify guide version 0.8.2
• Hosting recipes, a pinned starter and two optional parts
• Automated checks for secrets, merging, affected code and tests
• Shorter commands with shared background skills and agents
• Private by default: an access check on every recipe

AI Build Kit v0.20.3

v0.20.3 fixes seven problems found while building a project with the kit.

This reaches every project. One exception: a project founded before this release keeps GitHub's squash and rebase merges switched on in its repository settings. The kit no longer uses them either way.

Updating

Type /maintain in your project and accept the kit update. Start a new session afterwards, so it reads the new skills. Nothing else is needed.

If you are still on v0.19.3 or older, follow the v0.20.0 update steps to finish the move to six commands.

What changes

1. GitHub checks that never start are no longer reported as failed. For example, an account billing limit may prevent the project check from starting. The kit runs the checks locally and reports that once. On Explore privately, passing local checks is enough to merge. On Build and run it and Build with care, merging still requires the GitHub check. Disabling the workflow requires your explicit request; the kit records how to restore it, and /maintain reminds you while it is disabled.

2. A merge keeps every commit of the piece. Founding also turns off GitHub's squash and rebase merges on a new repository.

3. Piece labels now follow the build through to merge. ready becomes building when the build starts. Both labels are gone once the piece closes.

4. Setup records the project commit checked against the masterplan. Later builds update that record after reconciling the changes. If the record is missing or unusable, /what-now points you to /maintain to check the whole masterplan against the code.

5. /shape never starts a build because you picked one of its answers. A build starts only when you ask for it.

6. The kit asks where extra requests go. Suppose you ask for more while a piece is being built. The kit first asks whether the request belongs in this piece or in a new one. It asks to merge only after you have tried the result.

7. Builds now use one preview address and a separate browser tab. A build gives you one address to try the work on. It stops any older preview first. It checks pages in a browser tab of its own, not in yours. It stops its previews when you are done.

What was tested, and what is not proven yet

• Each change has a source check that fails when its rule is removed. All 93 rehearsals pass.
• Before release, two throwaway projects were founded and built with Claude Code from a preview. Every change above held there, except two that the run did not reach.
• Not reached: a private exploration that merges on the local checks alone, and /what-now pointing to /maintain.
• That run also found four older faults. They are written up for the next release.

AI Build Kit v0.20.2

v0.20.2 fixes GitHub access during founding and the first code upload, including Codex sessions on macOS.

The GitHub permission checks apply to every project. The launcher changes apply to Codex, and the shell configuration offer appears only during setup on macOS.

Updating

Type /maintain in your project and accept the kit update. Start a new session afterwards, so it reads the new skills.

In Codex, run /maintain again if you want it to offer the new GitHub check at session start. Adding that check requires your approval.

If you are still on v0.19.3 or older, follow the v0.20.0 update steps to finish the move to six commands.

What changes

1. Codex can use your existing GitHub login. The kit gives Codex a session launcher that does this. When the session cannot read the login, the kit gives you the exact restart command. On a Mac, founding can also offer to make typing codex use that launcher in kit projects. It asks for your approval before it changes your shell settings.

2. Setup warns when your GitHub login lacks permission to upload workflows. Founding carries on. /implement checks again before it asks for the first upload. To fix the login, run this in your own terminal: gh auth refresh -h github.com -s workflow. It opens the browser once. In Codex, quit and restart through the launcher that the kit shows. Then the session uses the updated login. If you use SSH, or the kit cannot read your permissions, the kit shows the result as unknown.

What was tested, and what is not proven yet

• Source checks and rehearsals cover the launcher, the install routes, the reading of permissions and the recovery messages.
• A real Codex run on macOS completed founding and the first upload. Local tests, type checking and linting passed.
• GitHub could not start the remote check of that test project, because of a billing or spending limit on the account.
• The browser permission refresh was not tried against a real account.

Pull requests in this release

• Warn when GitHub workflow upload permission is missing
• Fix GitHub access in Codex sessions on macOS

AI Build Kit v0.20.1

v0.20.1 completes the migration to six commands in projects where v0.20.0 left it unfinished, and shortens the README.

This reaches every project that is on v0.20.0 or older. The shorter README is the same for everyone.

Updating

Type /maintain in your project. It reads these notes and asks before it updates the kit. Say yes.

• If you are still on v0.19.3 or older, follow the steps in the v0.20.0 notes. Update, start a new session, and type /maintain again.
• If you are already on v0.20.0, one /maintain visit is enough. It checks your project again and offers to fix what v0.20.0 missed.

What changes

1. Your AGENTS.md no longer keeps the old commands. In some older projects, AGENTS.md lists the commands in a sentence, not in a list. v0.20.0 could not rewrite that sentence. It told you to change it by hand, and then it said the update was finished. Every later session then read about /ship, /fix, /queue and /sync, which no longer exist. /maintain now shows the old sentence and its proposed replacement, and applies it with your approval. Until you approve the correction or decline it, /what-now and /implement report that the update is unfinished.

2. No false warning about .ai-build-kit-version. A project that started from a whole copy of an older kit has this file. /maintain now recognises it as an unchanged kit file and offers to remove it without incorrectly warning that it may contain your changes.

3. Recipe dates pass in every time zone. A recipe date written just after midnight, east of UTC, no longer fails the kit's own checks.

4. A shorter README. It is about a third of its old length. The details moved to WORKFLOW.md and docs/COMPATIBILITY.md. Nothing about how the kit works changed.

What was tested, and what is not proven yet

• The first real update of a real project, from v0.19.3 to v0.20.0, found the command-list problem. The fix was then tried on that project.

If the update fails, open an issue on the AI Build Kit GitHub page and include your installation route.