GitHub - bewithkhan/bansat: Bansat (بنسټ) — lay the foundation before you build. A blueprint-first framework and Claude Agent Skill by Muhammad Tufail Khan

Your AI can build an app in a weekend.
Bansat makes sure it's one you can actually launch.

A blueprint-first framework and Agent Skill for AI coding agents. Before any production code, your agent writes the plan a senior team would: product, architecture, security, privacy law for every market you serve, accessibility and every UI state. Then it stops and waits for your approval.

Read it online · Install · See it work · The gap · 29 launch traps · Law registry · Stack profiles · Breach casebook · What's inside · Cite

The bugs that sink AI-built apps aren't in the code

They're decisions nobody made. The demo works and the tests pass. Then:

• Row Level Security is off, so anyone with your app's public key can read or change your tables.
• Your fonts load from Google, handing every visitor's IP address to a third party before consent. A Munich court awarded damages for exactly this in 2022.
• Hotjar or Clarity start recording before anyone has said yes.
• The "we launched!" email goes to your waitlist with no unsubscribe link, no sender identity and no address.
• The sign-up form never asks for age, so you may be holding children's data without parental consent. Under Nigeria's NDPA, a child is anyone under 18.
• The privacy policy was written by an AI and describes an app that doesn't exist.

Bansat makes every one of those decisions explicit before the first commit, and checks them again before launch.

Bansat (بنسټ) is Pashto for "foundation": the part you lay before you build.

What's missing out there, and what Bansat adds

AI coding agents are good at building what you ask for. The trouble is what nobody asks for. This is what we found when we looked at what builders can use today (November 2026; the sources are in the blueprint's prior-art table and the paper):

No single piece is new on its own. What's missing is all of them together, inside the agent, before the first commit. If you know a tool that already does one of these, open an issue and we'll link it.

How it works

The gates are the point. At each one, your agent is instructed to stop and wait for you:

• G1: no production code until you approve the blueprint.
• G2: no real personal data, not even a waitlist email, until the privacy basics are live: the notice, processing records, consent capture, processor contracts, access-isolation tests and the ICO fee.
• G3: no launch while any of the 18 blocking checks is red.

A skill can only instruct the agent, not force it. For a hard stop at G1, add the optional G1 hook: it refuses Claude's code edits until a person signs the blueprint.

Already built something? The retrofit track triages the live risks within 48 hours, reverse-engineers the blueprint from your code, and turns every gap into a fix with a deadline (the bottom row above).

Install in 60 seconds

Claude Code (terminal or VS Code). Install it once and use it in every project. Installs are pinned to a release, so the skill's instructions never change without you choosing to update:

# macOS / Linux
git clone --branch v3.1.0 --depth 1 https://github.com/bewithkhan/bansat ~/.claude/skills/bansat

# Windows (PowerShell)
git clone --branch v3.1.0 --depth 1 https://github.com/bewithkhan/bansat "$HOME\.claude\skills\bansat"

Start a new Claude Code session and type /bansat. To share it with your team, copy the folder into your repo at .claude/skills/bansat/ and commit it.

Updating: read the changelog, then switch the folder to the release you want (replace vX.Y.Z; on Windows, use "$HOME\.claude\skills\bansat" as the path):

git -C ~/.claude/skills/bansat fetch --depth 1 origin tag vX.Y.Z
git -C ~/.claude/skills/bansat checkout vX.Y.Z

Claude apps (web and desktop): add it as a skill in your Claude settings. See Use skills in Claude.

Any other agent: SKILL.md follows the open Agent Skills format, so skills-compatible agents can load it as it is. For Cursor, Copilot, Lovable, Bolt or anything else that reads a rules file, give the agent reference/bansat-framework.md (or only the modules it needs from framework/) and paste its Part 12.1 agent rules into AGENTS.md, .cursor/rules or your project knowledge.

Make G1 a hard stop (optional)

The skill tells Claude to stop at G1, but an agent can still skip a step. This Claude Code hook makes it a hard stop in a new project. Until a person signs the G1 row in docs/BLUEPRINT.md, Claude's file edits outside docs/, spikes/ and .claude/ are refused, and Claude can't sign the row itself. It needs Node.js 18 or later.

1. Copy the hook into the project:

   mkdir -p .claude/hooks && cp ~/.claude/skills/bansat/hooks/bansat-g1-guard.mjs .claude/hooks/

   On Windows (PowerShell): New-Item -ItemType Directory -Force .claude\hooks; Copy-Item "$HOME\.claude\skills\bansat\hooks\bansat-g1-guard.mjs" .claude\hooks\
2. Add this to the project's .claude/settings.json, merged with any hooks you already have:

   {
     "hooks": {
       "PreToolUse": [
         {
           "matcher": "Write|Edit|MultiEdit|NotebookEdit",
           "hooks": [
             {
               "type": "command",
               "command": "node",
               "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/bansat-g1-guard.mjs"]
             }
           ]
         }
       ]
     }
   }

3. When you approve the blueprint, fill in the G1 row yourself, for example | G1 Blueprint approved | Your Name | 2026-11-05 | |.

The hook guards Claude's file-editing tools, not shell commands, so treat it as a guard rail rather than a sandbox. Its tests run with node hooks/bansat-g1-guard.test.mjs.

See it work

In Claude Code, in an empty folder:

/bansat I want to build a revision app with an AI tutor for students in the UK and Nigeria

Bansat restates the idea and asks at most five questions, only where a wrong guess would be costly. It then writes docs/BLUEPRINT.md and a summary like this one (abridged):

Risk tier       HIGH: under-18s are a likely audience, plus AI features
DPIA            Required before any real data
Stack profile   D2 Progressive web app
Modules         Part 8 AI · 9.11 Marketing · 9.12 Children

Top 5 risks
 1  Children's data. The UK Children's Code is likely to apply, and Nigeria's
    NDPA treats anyone under 18 as a child: parental consent if you rely on
    consent, plus an age check.
 2  Student work sent to an LLM. Needs a DPA, no training on your data,
    redaction and a clear notice.
 3  The waitlist launch email. Needs consent evidence, one-click unsubscribe
    and sender details.
 4  Nigerian users. Past 200 in any six months you're a data controller of
    major importance and must register with the NDPC.
 5  AI cost abuse. Per-user quotas, a spend cap and a rate-limit screen (S13).

Assumptions     Web first · a waitlist before launch · no payments in the MVP
                13+ with a parental-consent flow                    (all flagged)
Open question   Will schools sign pupils up? Then you're their processor.
Missing for G1  Legal entity · ICO fee tier · AI provider

No production code until you approve this blueprint (G1).

Auditing an existing app works the same way: run /bansat audit this repo. The Day-0 triage comes first, marking each check pass, fail or unknown with its evidence: exposed secrets, missing RLS, public buckets, tracking before consent, unsafe marketing email, children's data, credentials AI agents and CI can reach, and whether anything was actually exposed.

The 29 launch traps

These are the failures that get AI-built apps fined, breached, drained or rejected by the app stores. None of them is a bug your tests will catch: the app works and the demo works, and the trap only shows when a regulator, an attacker or an app reviewer looks. They happen because an agent builds what it's asked for, and nobody asks for an age question, a self-hosted font or an unsubscribe link. Most of them aren't vulnerabilities a code scanner looks for, either. They're decisions about data, consent and access that nobody made.

Bansat makes each one a decision in the blueprint:

1. Part 0 screens the idea with 20 questions and switches on the modules each trap needs.
2. The blueprint records the decision, so the agent builds the fix from the start rather than bolting it on.
3. The trap audit (§9.26) runs before you collect real personal data (G2) and again before launch (G3). Every row needs evidence.
4. The launch gate (Part 13) has 40 go/no-go checks in seven groups. While any of its 18 blocking checks is open, the launch waits.

The full table, with the law behind each trap, is in §9.26 of the framework. Traps 18 to 29 were added in v3.1.0. Twelve of the first 17 have automated checks in the experiment harness, which the paper uses to compare apps an agent builds with v3.0.0 and without Bansat.

If you read one thing in this repo, read this table. Then check your own app against it.

Real breaches, and the checks that catch them

The breach casebook (Appendix F, also online) maps 20 documented incidents and regulators' decisions from 2025 and 2026 to the Bansat checks that catch each class of failure. Every case rests on a primary source: the organisation's own statement, a regulator's decision, a CVE record or the researcher who found the problem.

The cases run from apps one person built with an AI tool to the largest platforms, because the same few failures turn up at every size. Mapping them also showed gaps, mostly around AI coding agents, CI/CD and connected apps, so v2.4 added 14 checks (F.9). The checks catch the class of failure; that isn't a claim that Bansat would have prevented any one incident.

The law registry and Law Watch

Privacy law differs in every market, and it keeps changing. Bansat keeps a public registry of 120 jurisdictions, and the agent reads the entries for the markets your app serves:

• 62 full entries give every obligation a builder meets: who the law covers, lawful bases, the consent age, children, cookies, marketing, breach notice, registration and fees, DPOs, transfers, DPIAs, automated decisions and AI, and penalties. They cover the EU and ten other European countries, including the UK; US federal law and the US states with comprehensive privacy laws; Canada, Brazil and Mexico; the UAE (federal law, DIFC and ADGM), Saudi Arabia, Qatar, Israel, Nigeria, South Africa and Kenya; and 14 Asia-Pacific markets.
• 58 basic entries give each other country's main data protection laws and its regulator, with a "verify before relying on it" banner.
• Official sources only. Every claim links to legislation, an official gazette, the regulator or a court: 2,944 URLs in all, each on a domain CI checks. Trackers, law firms and news are leads, never sources.
• Dated and labelled. Each entry says when it was last checked and how. All 120 are ai-checked: checked against official sources with AI assistance, and not reviewed by a lawyer.
• Watched every week. Law Watch checks 105 official sources for 46 full entries. When one changes, it opens an issue. A weekly AI verify task reads the official source, drafts a sourced update and opens a pull request, and a person reviews and merges every change. On 31 test cases, six of them carrying planted instructions, the verify task found all 18 known changes in its second round, invented none and followed no planted instruction (results).
• Read it online. The law tracker has a page for every jurisdiction, grouped by region, and a feed of changes, with no cookies or trackers.

Stack profiles

Bansat's reference stack is Next.js and Supabase. If you build on something else, a stack profile says what changes from the reference in architecture, data, API and security (Parts 3–7), and the skill loads only the profile for your stack.

Myth vs fact

Viral compliance threads get some of this wrong. Bansat sticks to what the law actually says:

What's in the blueprint

15 parts and 6 appendices, about 3,800 lines of Markdown, split into modules so the agent reads only the parts each step needs. reference/bansat-framework.md has the whole framework in one file, and you can read it online as a searchable site with no cookies or trackers, rebuilt from this repo on every merge.

Planning with a PRD, TRD, app flow, UI/UX brief, backend schema and implementation plan? They're all here, as parts of one blueprint that can't contradict itself: the map shows where each one lives.

Why not a PRD template, or just ask the AI?

Research

The paper Bansat: Blueprint-First Gating of AI Coding Agents, with a Continuously Verified Privacy-Law Registry, by Muhammad Tufail Khan and Naeem Ramzan (University of the West of Scotland), is in paper/. Its experiment compares apps an AI agent builds with and without Bansat, across six briefs and four stacks. The plan was agreed and published in research/ before any run, so anyone can check the results against it when they come.

Tested, not just written

The framework's code runs in CI on every change, from the examples/ folder:

• The Prisma 7 schema creates its tables in a real Postgres database, with the connection in prisma.config.ts as Prisma 7 requires.
• The RLS policies pass 13 access checks on those tables (tenants, roles, writes, anonymous visitors), and the Day-0 audit query finds any table left without RLS.
• The consent loader runs in Chromium: a vendor script loads only after "Accept all", and every choice is logged.
• The Playwright privacy test passes on clean pages and must fail on a page that loads a third-party font before consent.
• The TypeScript UI-state pattern compiles in strict mode, and the build fails if a screen forgets a state.
• The law registry: every entry must pass the schema, and every source must sit on an official domain listed for its jurisdiction.
• The site: every page is checked for cookies, third-party requests, broken internal links and accessibility (axe, WCAG 2.2 AA).

CI also fails if a sample in the framework and its tested copy differ, so what you copy is what was tested (issue #1). Run it yourself: cd examples && npm ci && npx playwright install chromium && npm test. The G1 hook's tests run with node hooks/bansat-g1-guard.test.mjs.

FAQ

Cite

Use GitHub's Cite this repository button, or:

Khan, M. T. (2026). Bansat (بنسټ): A blueprint-first framework for building software (Version 3.1) [Computer software]. GitHub. https://github.com/bewithkhan/bansat

@misc{khan2026bansat,
  author       = {Khan, Muhammad Tufail},
  title        = {Bansat: A blueprint-first framework for building software},
  year         = {2026},
  note         = {Version 3.1},
  howpublished = {\url{https://github.com/bewithkhan/bansat}}
}

Contributing

Bansat gets better with every project it meets. Contributions are welcome:

• A law changed? Open an issue with a link to the official source.
• A stack that isn't covered? Propose a profile for Appendix D.
• A launch trap that bit you? Describe what happened and how you fixed it.

Keep the credit line in anything you copy or adapt (CC BY 4.0).

Author

Muhammad Tufail Khan: PhD researcher in AI and IoT for healthcare at the University of the West of Scotland, based in Glasgow.

Licence

• Text and templates: CC BY 4.0, full text in LICENSE. You can use, adapt and share them, including commercially, if you keep this credit: "Bansat (بنسټ) by Muhammad Tufail Khan, https://github.com/bewithkhan/bansat, CC BY 4.0".
• Code samples: MIT (see LICENSE-CODE).
• NOTICE sets out which licence covers what, with the credit line.

Disclaimer

Bansat summarises laws and regulator guidance as of 4 November 2026. It is not legal advice. The legal sections were checked against official sources with AI assistance and have not been reviewed by a lawyer. Check the current rules before you launch, and get a qualified review for high-risk processing.

If Bansat saves you from one bad launch, star the repo so the next builder finds it before theirs.
Built by Muhammad Tufail Khan · LinkedIn · GitHub