Why This Exists
AI coding agents in 2026 can be highly productive, but they still need structure. Without a framework, speed can come at the cost of quality and security.
66%
of developers report AI solutions that are "almost right, but not quite"
Source: Stack Overflow Developer Survey 202545%
of AI-generated code in one benchmark study contained security flaws
Source: Veracode GenAI Code Security Report 2025Hallucinated APIs
AI training data is frozen. External APIs change. Code written from memory against outdated endpoints breaks at runtime — silently.
Addressed by: context-hub-integration skillContext
degradation is a recurring failure mode — agents forget instructions mid-session
This framework doesn't replace developer judgment. It adds quality gates, persistent memory, and a feedback loop for improving the workflow over time.
Ad-hoc Prompting vs This Framework
The difference is not whether you use AI — it is whether you use it with discipline.
| Dimension | Ad-hoc AI Prompting | With This Framework |
|---|---|---|
| Planning | Jump straight to code | Spec first: user stories, data model, acceptance criteria |
| Context | Forgotten between sessions | Memory bank reloaded at the start of every session |
| Security | Checked if you remember to ask | Mandatory OWASP checklist before every feature ships |
| Testing | Optional, often skipped under pressure | RED → GREEN → REFACTOR enforced as part of DoD |
| External APIs | From training data — may be outdated or hallucinated | Fresh docs fetched via context-hub before every integration |
| Code review | None, or manual if you remember | Independent subagent review on every STANDARD+ task |
| Quality gates | Manual and inconsistent | Husky hooks: secrets scan, lint, type-check, tests, dep audit |
| Stack guidance | Generic, one-size-fits-all | 7 stack presets with conventions, gotchas, and templates |
| Improvement | Same mistakes repeat across sessions | Reflect phase captures lessons and evolves the rules |
Who Is This For?
This framework is aimed at builders who want speed without chaos.
Solo Developers
Add more structure and review discipline to solo AI-assisted development. Useful for indie hackers and small personal projects.
Startups
Move faster on MVP delivery while keeping planning, verification, and documentation visible from the start.
Teams
Standardize code quality with a shared ruleset and stack presets. Onboard new members faster with a structured reading order and project-specific context in cline_docs/onboarding.md.
Maturity Model
This framework scales with your project. Tools and processes activate when real-world triggers justify them, not before.
Level 1 · Foundation
Solo · MVP · Pre-launch
.clinerules, Husky hook templates, memory bank, conventional commits, and pre-commit quality gates
Level 2 · Growth
Team ≥2 · First users · Post-launch
Structured logging, Sentry, Renovate Bot, staging environment, API versioning, preview environments
Level 3 · Scale
Team ≥5 · SLAs · 100+ RPS
Load testing, distributed tracing, SLOs, feature flags, canary deployments, on-call rotation
Level 4 · Enterprise
Compliance · Multi-region · Team ≥20
Audit logging, SBOM generation, IaC, data retention policy, annual penetration testing
Advancing requires trigger criteria — real users, team growth, or operational incidents. Not calendar dates. Run Maturity check to assess readiness and get an ordered upgrade checklist.
Supported Stacks
Seven preset configurations. Choose one or define your own in cline_docs/stackConfig.md. All skills and rules adapt automatically.
| Preset | Stack | Best for |
|---|---|---|
nestjs-nextjs | NestJS + Next.js (TypeScript) | SaaS, dashboards, public or mobile API |
trpc-nextjs | tRPC + Next.js + Prisma (TypeScript) | SaaS, internal tools, TypeScript-only consumers (T3 Stack) |
django-react | Django + React (Python + TypeScript) | Data-heavy apps, admin tools |
laravel-vue | Laravel + Vue (PHP) | Content platforms, e-commerce |
go-htmx | Go + htmx (server-rendered) | Internal tools, low-JS apps |
fastapi-nextjs-rag | FastAPI + Next.js + pgvector (Python AI) | RAG, document Q&A, AI search |
nextjs-ai | Next.js + Vercel AI SDK (TypeScript AI) | Chatbots, copilots, AI-enhanced SaaS |
TypeScript
TypeScript-only consumers → trpc-nextjs
Public API / mobile → nestjs-nextjs
AI is core product → nextjs-ai
Python
Data / admin → django-react
RAG / AI search → fastapi-nextjs-rag
Other
Content / e-commerce → laravel-vue
Low-JS / internal → go-htmx
Core Commands & Workflow
The framework operates on a structured daily workflow.
Declare the task size before every task — it determines which steps are required. At L1, MICRO is the default. STANDARD and MAJOR are opt-in.
NANO
Single file · <30 min · No logic change
Edit → Verify → Commit
MICRO
1-2 files · <1 day · Contained change · L1 default
Plan → Act → Verify → Commit
STANDARD
Feature / bug with scope · L2 default · Reflect required
Resume → Plan → Act → Verify → Reflect
MAJOR
Architecture / cross-cutting · L3+ default · Reflect required
Resume → Plan+ADR → Act → Verify → Load test → Reflect
| Command / Skill | When / What |
|---|---|
Initialize project | First time — stack + memory bank setup |
Resume | Start of every session — reload memory & context |
This is a NANO / MICRO / STANDARD / MAJOR task | Declare lifecycle size before every task |
spec-writing skill | Complex feature → spec + acceptance criteria (STANDARD+) |
Quality check | Code quality scan before marking done |
Security audit | Full security verification (OWASP, STRIDE) |
UX review | Error messages, email, exports, onboarding, UI/a11y (ux-heuristics skill) |
Review this | AI-on-AI code review (code-reviewer subagent) |
Debug this | Structured 8-step root cause investigation (debugger subagent) |
Maturity check | Assess current level + generate ordered upgrade checklist |
Reflect | Update memory files, propose rule improvements (STANDARD+) |
End session | Save context, update activeContext.md & progress.md |
Hotfix | Production emergency — minimal fix, rollback plan, post-mortem |
Fresh start | Clear context, begin new unrelated task |
8-Step Verification Process
No code ships without passing these gates.
1
chub fetch
Fresh API docs (external APIs only)
2
Tests
Coverage ≥70%
3
Quality
Quality scan
4
Security
OWASP, STRIDE
5
UX/a11y
Errors always · UI, email, exports conditionally
6
AI Review
Subagent
7
Commit
Lint · Format · Type check
8
Push
Full tests · Dep audit
Steps 7 and 8 can run automatically once hooks are configured in your project.
The sample .husky/ hooks are designed to enforce quality with minimal manual discipline:
pre-commit can run secretlint + lint + format + type-check,
commit-msg can enforce conventional commit format,
pre-push can run the full test suite with coverage checks and a dependency security audit.
Hook scripts are included as ready-to-customise templates — update the commands to match your stackConfig.md before relying on them as enforcement.
File Structure
Getting Started
# 1. Clone
git clone https://github.com/YOUR_ORG/ai-driven-dev-framework my-project
cd my-project
# 2. Install Husky and activate the hooks
npm install --save-dev husky
chmod +x .husky/*
# 3. Copy quality templates to project root (TypeScript example)
cp docs/templates/eslint.config.mjs .
cp docs/templates/prettier.config.js . # Prettier (format command)
cp docs/templates/vitest.config.ts . # or jest.config.ts
cp docs/templates/commitlint.config.js .
cp docs/templates/.secretlintrc.json .
cp docs/templates/playwright.config.ts . # E2E tests
cp -r docs/templates/e2e/ e2e/
# 4. Set up release automation (optional)
cp docs/templates/release-please-config.json .
cp docs/templates/.release-please-manifest.json .
touch CHANGELOG.md
# GitHub workflows are already in .github/workflows/ — customize them:
# deploy.yml → fill in your deploy command and environment names
# ci-node.yml → adjust test/build commands for your stack
# 5. Configure (minimum 4 files)
# cline_docs/stackConfig.md ← pick a preset from .cline/stacks/
# cline_docs/projectBrief.md ← vision + scope
# cline_docs/activeContext.md ← current task
# cline_docs/progress.md ← status + milestones
# 6. Start — type this in your AI assistant:
# "Initialize project"
#
# Works with: Cline (VS Code), Claude Code (CLI), Cursor, Windsurf, or
# any AI assistant that can read files from the project directory.