AI Workflow Kit

English · Tiếng Việt

Version: v1.4 (2026-07-30). When copying the kit into a new project, add > Initialized from ai-workflow-kit v1.4 — <date> at the end of the project's CLAUDE.md (step 5 in specs/INIT.md), so you always know which kit version an older project runs.

A reusable set of files that bootstraps a "spec-driven, AI implements, human reviews once per batch" workflow for any new project. Extracted from a real production project and generalized.

Why this exists: AI coding tools ship features fast, and generated-then-never-reviewed code is where the real security bugs live. This kit came out of an actual audit finding — an RBAC permission decorator with no guard behind it, leaving admin routes public in a production marketplace. Everything here is aimed at keeping AI speed without losing the one human checkpoint that catches bugs like that.

What makes v1.4 different from a pile of markdown: the checkpoint is now enforced by a hook, not requested in prose. Until v1.3 "do not implement before approval" was a sentence the model was asked to honour. Now a PreToolUse hook blocks writes to source files until a task in TASKS.md is In progress. Docs and specs stay writable, so planning is never blocked — only implementation is.

What's inside

Path	Role	Goes where in a new project
claude-skeleton/	The enforcement layer — approval-gate hook, secret-handling hook, six workflow commands	Copy to .claude/ at the root
CLAUDE.template.md	Project memory — read first every session: stack, conventions, DO-NOT list, audit cadence	Copy as CLAUDE.md at the root (must be at root to auto-load)
TASKS.template.md	Living backlog with a dependency column; the gate reads its status column	Copy as TASKS.md at the root
specs-skeleton/INIT.template.md	Self-contained init procedure — no access to the kit folder needed	Copy to specs/INIT.md, delete after init
specs-skeleton/00_Intake_Template.md	One-time project brief + per-feature brief	Copy to specs/
specs-skeleton/01-08_*.template.md	Spec skeletons: Tech Stack, DB Schema, API Contract, Frontend Architecture, Business Logic Flows, AI Tooling Rules, Testing Strategy, Deployment Guide	Copy all into specs/, drop .template, fill in gradually
specs-skeleton/09_Audit_Report_Template.md	Audit report structure (Critical / Should fix / Already good / could-not-confirm + priority table)	Copy to specs/09_Audit_Report_<date>.md per audit
specs-skeleton/10_AI_Workflow.template.md	The full loop: Intake → Spec → Tasks → One approval → Self-verifying implement loop → Release → Post-release	Copy to specs/10_AI_Workflow.md
specs-skeleton/11_Rollback_Runbook.template.md	Rollback triggers and procedure, written before you need it	Copy to specs/11_Rollback_Runbook.md
specs-skeleton/CHANGELOG.template.md	Per-release changelog, including an incidents section	Copy to specs/CHANGELOG.md
reference/security-baseline.md	Default security DO-NOTs, split into permanent invariants and replaceable generics	Copy to reference/ at the root
reference/intake-example.md	A fully filled Intake A+B + data-prep checklist + single-blob brief format	Copy to reference/
reference/industry-presets.md	Industry → suggested design style → compliance questions to ask	Copy to reference/
reference/ui-design-standards.md	UI/code-quality standards against "AI slop"	Copy to reference/
reference/ai-tooling-options.md	Evaluation notes on AI ecosystem add-ons (context compressors, memory plugins, skill meta-tools, third-party inference proxies) — what's safe to add, what risks your Claude Code subscription	Copy to reference/
i18n/vi/	Full Vietnamese mirror of every template and reference file	Copy from here instead if you work in Vietnamese

Quick start

cp -R claude-skeleton/. <project>/.claude/
chmod +x <project>/.claude/hooks/*.sh
cp CLAUDE.template.md <project>/CLAUDE.md
cp TASKS.template.md <project>/TASKS.md
cp -R specs-skeleton <project>/specs
cp -R reference <project>/reference
cd <project>/specs && for f in *.template.md; do mv "$f" "${f%.template.md}.md"; done

Then open a session in that project and say: "Initialize from ai-workflow-kit — here's the project description: […]". The whole procedure lives in the copied specs/INIT.md.

Working in Vietnamese? Use i18n/vi/ as the source for the last four copies above; the layout is identical, so every relative path still resolves.

The loop

Intake ──▶ Spec ──▶ Tasks ──▶ APPROVE ──▶ Implement + self-verify ──▶ Release ──▶ Post-release
  A         B         C          D                  E, F                  G            H
                                 ▲                                                     │
                                 └───────────── next feature ──────────────────────────┘

Command	Stage	What it does
/aiwk:intake	A–C	Brief → specs → task list, all Awaiting approval
/aiwk:approve	D	Present architecture + tasks; flip approved IDs to In progress
/aiwk:audit	—	Read-only security/RBAC audit → dated report → tasks
/aiwk:verify	F	Adversarial review of a Critical diff before Done
/aiwk:release	G–H	Release checklist, real-production verification, changelog
/aiwk:rollback	—	Execute the rollback runbook when a release goes bad

Core principles

• One mandatory checkpoint, and it is enforced. Architecture and task list are reviewed once per batch before code is written. Never fully automated, because generate-and-never-review is exactly where the RBAC bug came from.
• DO-NOT lists must be specific, never generic. After its first audit a project gets DO-NOTs named after its own real bugs. Exception: the Group A invariants in security-baseline.md (concurrency, migrations, secrets, deploy) are permanent — a static audit rarely proves a race condition absent, so that group must never be "replaced away".
• Small, self-verifiable tasks. Each one small enough for the model to run its own checklist — guards, secrets, four UI states, safe migrations — before reporting Done.
• Done means a machine proved it. For Critical features every acceptance criterion becomes a passing automated test, and a clean-context subagent reviews the diff. An author shares the blind spot that produced the bug.
• Every incident feeds back into the rules, as a DO-NOT entry if it is a judgement call and as a CI guardrail if a machine can catch it. That is what makes the list get better rather than just longer.

What changed in v1.4

• Enforcement layer (claude-skeleton/): the approval gate and the secret-handling guard are now hooks, plus six slash commands covering the workflow. This closes the gap between this kit and executable ones like GitHub Spec Kit.
• Audit reports now have a depth bar and an honesty section: every finding must name file:line, the concrete exploit and the fix, and each report states what it could not confirm rather than letting silence imply safety.
• English is now the primary language; the complete Vietnamese set moved to i18n/vi/.
• Post-release is no longer one line: a rollback runbook with pre-agreed triggers (11_Rollback_Runbook.md), a scheduled audit cadence in CLAUDE.md, and an explicit feed-lessons-back-into-the-rules step.
• TASKS.md gained a dependency column; 03_API_Contract gained an ownership-check column; 05_Business_Logic_Flows gained a concurrency section.
• 06_AI_Tooling_Rules no longer duplicates CLAUDE.md — it points at it via AGENTS.md, because a hand-copied rule is a rule that will drift.
• Model and session guidance added to 10_AI_Workflow.md section 5.

Backlog for v1.5: the staging/seed-data and observability slots in 08_Deployment_Guide and the hard guardrails in 01_Tech_Stack_Rules are placeholders on purpose — fill them from real pilot results, never design them in a vacuum.

How this compares

Same family as GitHub Spec Kit (constitution + specify/plan/tasks/implement), Amazon Kiro spec mode, Agent OS, and BMAD-Method. The shape of the loop is not novel and does not try to be. What is different is the security spine: a baseline whose concurrency and deploy invariants come from production incidents, an audit report that feeds findings back into the project's own DO-NOT list, and a checkpoint the harness enforces instead of requests.

---

Built and maintained by Thinh Le — freelance full-stack dev specializing in payment integrations and rescuing AI-built apps. Open for work: levietquocthinh@gmail.com