Tài liệu Bakit.

Bakit v2.1.0 — Command split, per-flow wireframes, test/BPMN/prototype/preview lanes

Standardize the BA-kit output surface into unified artifact shapes. Command surface 21→29: split monolithic srs into discrete steps (use-case, userflow, wireframe, render-html, test-checklist, test-cases, bpmn, prototype, preview, impact-cook), replace per-screen ascii-screen canon with per-flow ascii-wireframe (5-column table, 6-layer Description), remove ba-do/ba-next/ba-notion, add ba-review skill, backfill new content shapes into requirement templates, extend guardrails with L1/L2 change notification. Ships migrate-ascii-per-flow.py for existing projects.

Solo Basic v1.3.0 — Public CLI-distributed release

Publish the first Solo Basic release package for BA-kit CLI distribution. Ships exactly five skills plus core and templates, supports Claude Code, Codex, and Antigravity, and installs without GitHub authentication.

Bakit v1.5.1 — Add ASCII anchors to Figma Make prompts

Embed each approved ASCII wireframe verbatim in its Figma Make paste block so the external chat surface receives the intended layout. Correct the paste order to shared rules first, then the shared prompt skeleton.

Solo Pro v1.3.1 — Release layout and stale reference cleanup

Fix release layout drift for skills, templates, rules, hooks, and core workflows. Remove dangling ba-collab references and stale source-installer references before packaging for CLI installation.

Bakit v1.5.0 — Rework ba-figma-sync into Figma Make paste-ready prompt lane

Rework ba-figma-sync to generate paste-ready Figma Make prompts instead of touching Pencil (.pen) or MCP tools. Wire outputs to screen_field_contract and figma-make artifact paths. Drop obsolete figma-sync/mismatch report templates. Add step-by-step ba-figma-sync usage guide. 22 files changed.

Bakit v1.4.0 — package-frd command, remove ba-collab, install layout fix

Add package-frd command for FRD-only packaging before stories/SRS exist. Remove ba-collab skill, workflow, and templates entirely. Fix install-claude-code-ba-kit.sh directory layout drift vs release build (agents/, rules/, hooks, core/ now land at correct ~/.claude/ paths).

Solo Pro v1.3.0 — Port package-frd and compiled-doc badge fix from Bakit

Port package-frd command (FRD-only packaging) and compiled-frd/compiled-srs badge detection fix from Bakit v1.3.0/v1.4.0. Add CHANGELOG.md. Sync guardrail scripts, contract, and write-scope rules with upstream.

Bakit v1.2.1 — Remove ba-kit-update and ba-qc-export skills

Remove ba-kit-update (superseded by CLI ba-kit update) and ba-qc-export (unused QC bridge). Drops both skill dirs, codex mirror, install-script copy step, routing entries, docs mentions, and check-write-scope qc-export rules. 16 files, -1,636 lines.

Bakit v1.2.0 — SRS compilation enrichments, VN-aware HTML slugs

Enrich SRS compilation with multi-source UC data, index ordering, VN-aware heading slugs with dedup. Compile-srs draws UC summary from heading bodies + index table, orders files by index table row order, strips empty OQs, omits Flows/ERD when no source content. md-to-html strips frontmatter, deduplicates module H1 in compiled HTML.

Solo Pro v1.2.1 — Remove ba-kit-update, clean up qc-export references

Remove ba-kit-update skill (CLI handles self-update). Strip dead qc-export wiring from ba-kit CLI (qc_export_command, dispatch case, usage line) and write-scope rules left over from prior removal, plus routing/doc references.

Solo Pro v1.2.0 — Port SRS compilation enrichments from Bakit

Port SRS compilation enrichments from Bakit v1.2.0: multi-source UC data, index ordering, VN-diacritic-aware HTML heading slugs, strip empty OQs, omit Flows/ERD when no source content, deduplicate shared refs in compiled HTML.

Bakit v1.1.1 — BSD sed compatibility, npm metadata, dev-sync

Fix release workflow to generate targeted notes per tag instead of all PRs. Fix BSD-compatible sed -i (fail hard on guardrail install failure). Preserve npm CLI metadata in ~/.claude/ba-kit/. Replace install.sh with dev-sync.sh for streamlined local development.

ClaudeKit-style distribution — Polar.sh + npm + GitHub Releases

Switch to ClaudeKit-style distribution: npm package @bakit-org/cli (805 LOC, install/update/doctor/version/uninstall). Polar.sh purchase → GitHub OAuth invite → npm install → download release.tar.gz from GitHub Releases → merge to ~/.claude/. New docs: pricing, update, uninstall, troubleshooting guides. CI auto-publish via GitHub Actions with OIDC.

Resolve python3 cross-platform fallback for Windows

Resolve Python at startup instead of hardcoding python3. Try order: python (Windows-native) → python3 (macOS/Linux) → py (Windows launcher). Prevents Microsoft Store popup when python3 is broken stub on Windows. 21 ba-kit call sites, 9 install hooks, and guardrail scripts use resolved PYTHON variable.

Solo Pro: Resolve python cross-platform, try python before python3 for Windows

Solo Pro: all entry points resolve Python at startup with try order python → python3 → py. Prevents Microsoft Store popup on Windows Git Bash. Port from bakit PR #67.

Solo Pro: Remove license management, dead code, and native Python 3.10+ union types

Solo Pro no longer requires license. Delete 7 license files (2,439 lines): register, reauth, heartbeat, gate, event-emit, cache, schema. Remove license sections from all 7 SKILL.md files. Backport dead code removal and Optional[X] → X | None from bakit PR #62.

Cross-platform license robustness: python3 fallback, cache revalidate, device auth

Fix license enforcement gaps. Background revalidate on fresh and stale cache (writes block file on server denial). Cross-platform python3 resolution (py/python3/python fallback). GitHub device auth without mktemp (not available in Git Bash). User confirmation prompt between browser open and polling. Fix read -r capturing only first line.

Solo Pro: Cross-platform python, cache revalidate, date-based grace, Windows wrappers

Solo Pro: add cross-platform python3 resolution, license cache with TTL (24h) + date-based grace (7d) with fcntl/msvcrt locking, license gate hooks (UserPromptSubmit parsing for /ba-* commands), Windows ba-kit.cmd + install.cmd wrappers, ensure_path() for ~/.local/bin. Aligns with bakit PR #65 and #66.

Windows .cmd wrapper and device auth polling resilience

Add ba-kit.cmd wrapper for Windows Git Bash/WSL invocation. Fix device auth polling: set +e for transient failures, curl --connect-timeout 10 -m 15, progress dots, JSON validation guard before parsing, bootstrap_python3 PATH fix (~/bin wrapper added to PATH on Windows Git Bash).

Move license hard block from UserPromptSubmit to PreToolUse Skill gate

Move license enforcement from prompt-level blocking to tool-level blocking. Heartbeat hook runs tracking-only (always exit 0). New license-skill-gate.sh PreToolUse hook blocks BA-kit skill invocation when BLOCK_FILE exists. Non-BA-kit skills and normal chat always pass through regardless of license status.

Add ba-kit reauth and enterprise init commands, fix PATH

Add ba-kit reauth (re-authenticate when token expires) and ba-kit enterprise init (deploy tracking worker to Cloudflare) CLI commands. Add ensure_path() to auto-append ~/.local/bin to shell PATH config. Fix local variable used outside function in enterprise-init.sh.

Solo Pro: Sync stitch-sync from upstream + license management

Solo Pro initial release. License management with GitHub Device Flow OAuth, periodic heartbeat (120s debounce, 23h token re-verify, max 7d offline), re-authentication flow, localhost dashboard (port 9898). Sync ba-stitch-sync files to exact duplicates of BA-kit Course upstream with CRITICAL guardrail before next screen.

Remove dead code and use native Python 3.10+ union types

Delete unreachable duplicate code. Replace typing.Union[X, Y] and Optional[X] with Python 3.10+ native X | Y and X | None syntax. No behavior change.

Decouple contract.yaml path and add module list to backbone

Fix validate-shared-rule-message-registry resolving to BAkit install dir instead of project dir. Decouple ba_source (contract.yaml) from --repo (artifact paths). Add Danh sách module section to backbone template and PROJECT-HOME with MOD-* IDs.

Harden state variant generation and anti-hallucination bans in ba-stitch-sync

Replace generate_screen_from_text with generate_variants (REFINE + TEXT_CONTENT) for state variants. Add 8 anti-hallucination bans (brand, logo, buttons, links, styling, pre-filled values, fields, translation). Remove state descriptions from base prompts to prevent figaro_agent shortcut. Fix generate_variants response parsing path.

Add cross-platform python3 bootstrap for Windows

Fix BA-kit stop hooks on Windows Git Bash where python3 resolves to non-functional Microsoft Store stub. Three-layer defense: install.sh bootstrap_python3() creates ~/bin/python3 wrapper, install scripts detect real python3, hooks resolve Python via python3/python fallback.

Bump vitest to 4.1.8 and playwright to 1.55.1 (CVE fixes)

Fix CVE-2026-47429 (CRITICAL 9.8) in vitest 3.1.4 → 4.1.8, CVE-2025-59288 (HIGH) in playwright 1.52.0 → 1.55.1. SkillSpector re-scan: DO NOT INSTALL→SAFE. 49/49 unit tests pass.

Fix pre-tool-use hook in Claude Code and CodeX installers

Update pre-tool-use hook in both install-claude-code-ba-kit.sh and install-codex-ba-kit.sh. Fix guardrail hook behavior for tool-use events.

Prevent context thrashing in ba-content-audit with output-limiting, on-disk indexing, and module batching

Three-level context fix: L1 output-limiting reads (frontmatter offset=0 limit=40, TOC-first 80 lines), L2 incremental writes per file, L3 on-disk indexing via Bash for cross-reference queries. Module batching: ≤60 files single-agent, larger multi-agent. Context reduction ~97% (3.2MB → ~200K for 4 modules).

Add screen state variant generation to ba-stitch-sync

Extract all documented screen states (error, empty, loading, success) with ASCII wireframes from message list backbone. Generate state variants with state-specific prompts. New state prompt sanitizer gate. Cross-state consistency check. stitch-screen-map.json extended schema with {default, states: {state_name: {...}}}. Use generate_variants for structural identity between state variants and base screen.

Harden stitch-sync prompt building against Stitch hallucination

Per-zone negative space markers for all 6 shell zones. Field table priority rule: field table defines widget STRUCTURE, wireframe defines LAYOUT POSITIONS. Zone coverage gate (Check 5) verifies all 6 zones declared. Exact placeholder data directive with 'do NOT invent' instruction. Per-zone ban table: 7 zones × explicit ban lists + 7 common Stitch invention patterns.

Add ba-content-audit: cross-artifact content audit skill

New read-only skill for cross-artifact format and cross-reference consistency audit. Scans all BA-kit lifecycle artifacts (intake → backbone → modules → compiled). Reports frontmatter compliance, mandatory section presence, cross-reference integrity. Supports first-audit and re-audit with finding tracking (NEW/persistent/resolved). Content-hash finding IDs for re-audit comparison.

Add ba-stitch-sync: Stitch MCP design sync command

New skill for downstream BA-kit screen canon → Stitch MCP design sync. Full workflow: preflight gates → design system bootstrap → screen generation → cross-screen audit. Step 0.3a resolves Stitch projectId (list_projects/create_project). Device type respects --device flag instead of hardcoded DESKTOP. New behavior shard at core/behavior/stitch-sync.md.

Add UI library gate enforcement + interactive prompt + DESIGN.md Section 10

Hard enforcement for gate 5.1a: DESIGN.md template now includes Section 10 with TBD defaults, init-control-library CLI parses and blocks if unset, backbone supports dual-path (single-run interactive AskUserQuestion or two-run defer).

Add UI library selection gate between DESIGN.md and control-type-library

Split backbone Step 5: DESIGN.md now created first (Step 5.1), then backbone stops for user to pick UI library (Gate 5.1a). control-type-library deferred to Step 5.2 on next backbone run only after library confirmed. Prevents wrong baseline from premature generation.

Backbone index validator coverage and path resolution

Fix validator hard fail on Source IDs Not Indexed. Add format-sibling detection (FR-1 vs FR-01). Per-section ID extraction replaces global ID list. Separate source-repo and project-repo path resolution across all CLI commands.

Control Type Library + behaviour guardrails

Add Control Type Library to backbone with baseline pruning flow (library-aware). 6 new guardrail scripts: control-type compliance, message placement, CR coverage, terminology consistency, freshness, and postwrite hooks. Wire guardrails into all installers.

Update README layout

Refine README visual hierarchy: move BA-kit description below badges, remove star/fork counters, fix badge formatting for consistent rendering.

Update README badges and description

Add GitHub badge for bakit-org/bakit. Move BA-kit description below centered badge header. Restructure README for cleaner first impression.

Resolve partial SRS compile receipt source paths

Fix check-partial-srs-compile-receipt.py: resolve included file paths relative to module root. Preserve all existing receipt validation checks.

Add check-screen-behaviour.py to Codex installer

Add check-screen-behaviour.py to CodeX installer GUARDRAIL_SCRIPTS array. Fix script count 10 → 14. Ensures parity across all 3 runtimes.

Screen behaviour rules — business language guardrail + QC profiles

Enforce business-language Behaviour Rules in screen canon with 4-layer guard: template patterns, step gate, 230-line guardrail validator detecting API paths/HTTP methods/framework calls, and QC KA #5.5 scoring. Block technical language like POST /api/auth — require 'mở SCR-LRN-12 (Dashboard)'.

install.sh Antigravity deployment + CWD-aware CLI paths

Auto-detect Antigravity via ~/.gemini/antigravity/, ~/.gemini/, or agy CLI. Copy skills/rules/agents/templates/core to ~/.gemini/antigravity/. Call install-antigravity-ba-kit.sh for guardrails + Knowledge Item. Add CWD-aware path resolution: walk CWD for plans/ before falling back to registered repo.

Compile hardening + CLI CWD awareness + index-disk verification

Hardening compile-srs.py: strip YAML frontmatter, auto-fill template placeholders, detect remaining unfilled patterns, hard-block if index references non-existent files. Fix validate-index-quality.py double-dir bug. Extend guardrail_common.py to load contracts from ~/.claude/core/. Add placeholder detection to qc-export.py.

Hard index validation mandate + DESIGN.md system-level ownership + collab subdir cleanup

Add 3-layer index validation enforcement (step-file inline, PostToolUse hook, downstream guardrail). Move DESIGN.md and shared-shell-contract from SRS outputs to backbone outputs. Two-tier change authority: L1 Portal (Lead BA only), L2 Nav Item (Module BA with confirmation). Clean up ba-collab subdir pre-creation.

Global-first paths in SKILL.md + collab incremental module gating

All SKILL.md and step files reference ~/.claude/ paths as primary, repo root as fallback. ba-collab now creates only COLLAB-HOME.md on setup — module directories created incrementally on 'tôi nhận module X'. Add missing ba-qc-export-bridge-note.md to install docs.

Core symlink for SKILL.md relative path resolution

Add symlink ~/.claude/core → ba-kit during install so repo-relative paths in SKILL.md resolve correctly after installation. Add cleanup_previous_install to remove stale symlink on reinstall.

Compile script HTML + token budget recalibration

Recalibrate all token budget baselines across machine contract, behavior shards, bundles, and runtime policy entries. Realign compile receipt fixture with current SRS output schema including cross_function counters and template_compliance fields.

Context budget bootstrap tool, Glob guard, and CodeX hooks

Add context-budget-bootstrap.py for legacy project index generation, extend PreToolUse/PostToolUse matchers to Glob, add CodeX context guard hooks, session budget tracking, fix cached_token_waste calculation to use violation sequence distance, and add index preflight advisory to collab/do workflows.

Context guard token spending fix

Fix has_safe_flags: offset alone no longer considered safe for large files (>=10kB). Fix re-read detection to track after check (avoid self-match on first read). Remove unused SAFE_FLAGS constant.

Context budget enforcement hooks for Claude Code

Add 3-layer context budget enforcement: PreToolUse blocks Reads >10kB without offset+limit, PostToolUse warns on outputs >5kB, Stop audits total context waste. Add CLAUDE.md hard rules for tool selection, output limiting, and re-read prevention.

QC export output grouped by module with flattened UC structure

Restructure qc-export output: UC files now under {module}/UC-{slug}.md instead of UC-{slug}/UC-{slug}.md, screens in UC-{slug}-screens/, usecase-list.md inside module folder. Add stale UC file cleanup between exports.

Write-scope guard hardening for qc-export

Add _guard_path() helper to validate all qc-export output paths (UC markdown, PNGs, common-rules, message-list, usecase-list, summary JSON) through write-scope guard individually, not just top-level output_root.

Node precheck added to CodeX installer

Add command -v node guard to CodeX installer before running inline Node.js scripts, matching the python3 check pattern already in Claude Code installer. Prevents cryptic failures on systems without Node.

Guardrail scripts wired into production across all runtimes

Add guardrail, check-token-budget, and validate-index subcommands to ba-kit CLI. Wire guardrail dispatch into frd, stories, srs, and package steps. Add Claude Code installer with 7 guardrail scripts + 3 hook generators. Migrate raw python3 calls to ba-kit CLI across all step files.

BA-to-QC export bridge command

New ba-kit qc-export CLI command for one-way BA-to-QC artifact handoff: reads UC canon, screens, stories, and registries, then writes QC-kit-compatible per-UC markdown under 04_compiled/qc-kit/ with write-scope guardrails and 20/20 tests.

Cross-function impact declarations across BA-kit

Add Cross-Function Impact section to UC template with within-module and across-module dependency tables, update QC UC Review KA #8 scoring, inline cross-function data into SRS assembly, give ba-impact full propagation awareness, and wire cross-function data into the QC export bridge.

BA-facing output speaks more naturally in Vietnamese

Humanize BA-kit output with a Vietnamese wording layer: friendlier labels, stakeholder-ready SRS summaries, localized status/package wording, docs updates, and refreshed golden strings.

Figma Make per-UC incremental prompt and change-log artifacts

Add per-UC Figma Make paste-ready prompt files and versioned change logs under tool-lanes/figma-make/usecases/, with shared baseline reuse, validator guardrails, and lane docs. BA canon untouched.

BA-start adopts modular artifact source sets

Move BA-start/SRS authoring from legacy index and canon files to explicit module source sets: userstories/, usecases/, ascii-screen/, srs/, compile receipts, source-set validators, doctor-srs checks, and greenfield fixtures.

ASCII wireframes mandatory in screen canon

Require current ASCII wireframe sections in every UI-backed screen canon file. Missing ASCII becomes blocking schema error. Remove legacy wireframe-input, wireframe-map, and wireframe-state templates. Compile ASCII through srs path. Wireframes command becomes read-only compatibility validation.

QC review now runs after SRS, inside each module

Move QC review to the point where a module SRS is already done, read the module's own canon files first, save the report right inside that module, and lock the new timing with parity fixtures.

Shared rule/message guardrails and artifact folder layout

Reorganize BA artifacts into dedicated SRS, wireframe, Figma Make and Figma sync folders; add Common Rules, Message List, Shared Rule Message Index and validator guardrails for CR/MSG references.

SRS canon-first, ASCII wireframes, and Figma sync guardrails

Refactor SRS sang canon-first: screen/use case canon, SRS index, compile receipt, shared shell contracts, hard guardrail scripts, ba-figma-sync downstream-only và guide từng bước cho người dùng Paid.

Figma Make wireframe guardrails

Thêm Step 9 tool-lane artifacts cho Figma Make: screen field contracts machine-facing, shared prompt/rules/component templates, tool-lane state, prototype conformance checklist/report, validator scripts và token-budget/context updates để wireframe handoff có guardrails rõ hơn.

Reverse-web — Playwright crawl engine + synthesis skill + 57 tests

Thêm skill reverse-web: Playwright BFS crawl engine với 7 code-enforced guardrails (G1–G7), passive network capture, DOM extraction, incremental sitemap, --continue mode, evidence-index.md agent-facing index. SKILL.md hướng dẫn Claude điền intake-form-template.md 8 phần tiếng Việt. 57 tests (49 unit + 8 integration).

QC UC Review — platform-parameterized quality gate engine

Thêm skill /qc-review: 38 validation checks trên UC artifacts với 3 platform profiles (mobile/web/API), 3 quality gates tự động (pre_srs, pre_wireframe, pre_package) và auto-remediation loop max 2 retries.

Brainstorm skill — pre-intake idea clarification

Thêm skill /brainstorm như pre-intake feeder: 7-section deep interview để mở rộng ý tưởng thô thành tài liệu có cấu trúc trước khi vào lifecycle. Kèm NLP routing trong ba-do và hint trong ba-next.

Reverse-to-document mode

Thêm lifecycle code-first để BA extract requirements ngược từ source artifact có sẵn, bỏ qua forward design/wireframe gate. Kèm 6 guardrail modules, parity fixtures f21–f26 và Antigravity certifications.

Runtime guardrails và index validation

Thêm guardrail preflight/audit, output modes thấp-token và producer-side validator để index-first execution fail closed khi index stale hoặc mâu thuẫn.

Runtime token shards

Tách behavior runtime thành command-scoped shards, thêm Python token-budget checker đa nền tảng.

Navigation schema guardrails

Thêm validator và workflow gate để Screen Contract Plus không tự suy luận hoặc đổi active menu ngoài Navigation Schema đã duyệt trong DESIGN.md.

Token optimization và compact internal artifacts

Thêm source chunk index, backbone/stories/SRS indexes, artifact profiles và context-budget để agent đọc targeted thay vì nạp toàn bộ artifact lớn.

Community-first site and split public docs

Reposition site sang Community-first, tách public docs thành Community và Paid, đồng thời giữ Terms như boundary page cho private Paid repo.

Pre-backbone options flow

Thêm bước options trước backbone, option pack + comparison và quyết định explicit select/skip khi intake cần nhiều hướng solution.

PlantUML swimlanes và diagram rendering update

Đổi chuẩn swimlane sang PlantUML, giữ Mermaid cho sequence/DFD/ERD và cập nhật HTML packaging để render đúng.

BA-friendly collaboration workflow

Thêm ba-collab, COLLAB-HOME.md, MODULE-HOME.md, review packet và approval gate cho GitHub handoff.

Adaptive memory, activation parity và runtime verification

Thêm project-memory compact/shard, activation contract và parity harness giữa Claude Code, Codex và Antigravity.