Agentic Development Framework

A methodology framework for AI-assisted software development. Structure your AI coding workflow with checkpoints, escalation rules, and human oversight to ship quality code faster.

---

What Problem This Solves

AI coding assistants can generate code fast, but without structure:

• Developers spend too much time validating AI output
• Quality is inconsistent across sessions
• Security issues slip through
• No clear process for when to trust vs. verify

This framework provides guardrails that make AI-assisted development predictable, secure, and scalable.

---

What This Framework Provides

Component	Purpose
Checkpoints (C0→C3)	Structured workflow: Scope → Plan → Implement → PR
Escalation Rules	When AI must stop and ask the human
Quality Gates	Automated + human verification at each stage
Security Module	DevSecOps for AI-generated code
Factory Model	Scale to multiple agents and batch processing

---

Start Here

Your Goal	Start With
Apply to your project	Bootstrap Guide
Learn the workflow	Agent Quickstart
Understand checkpoints	Checkpoints Spec
See real examples	Case Studies
Scale to teams	Factory Model
Secure AI code	Security Module

---

The Core Workflow

┌─────────────────────────────────────────────────────────────┐
│                    BEFORE ANY WORK                          │
│   Check Escalation Triggers → If any apply → STOP → Ask     │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ C0: SCOPE                                                    │
│ • Understand the task                                       │
│ • Define what's in/out of scope                             │
│ • Identify affected files                                   │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ C1: PLAN (for non-trivial tasks)                            │
│ • Document approach                                         │
│ • Identify risks                                            │
│ • Get human validation if needed                            │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ C2: IMPLEMENT                                                │
│ • Write code following plan                                 │
│ • Run tests                                                 │
│ • Pass automated gates                                      │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
┌─────────────────────────────────────────────────────────────┐
│ C3: PR & PROOFS                                              │
│ • Document what was done                                    │
│ • Provide evidence (tests, screenshots)                     │
│ • Human reviews and approves                                │
└─────────────────────────────────────────────────────────────┘

---

Escalation Rules — The Highest Value Component

AI agents must stop and ask when:

Trigger	Example
Architecture decisions	New service, schema change, new dependency
Security concerns	Auth changes, crypto, access control
Data handling	PII, migrations, retention policies
Breaking changes	API changes, deprecations
Uncertainty	Multiple valid approaches, unclear requirements

See ESCALATION_RULES.md

---

Task Size → Workflow

Not every task needs the full workflow:

Size	Lines	Workflow
Trivial	< 10	Fast Path (C0 + C3 only)
Small	10-50	Lite (C0 + C2 + C3)
Medium	50-200	Full (C0 → C1 → C2 → C3)
Large	> 200	Full + Extra Review

---

Repository Structure

├── core/
│   ├── agent-operating-model/   Roles, escalation, golden rules
│   ├── spec/                    Checkpoints, templates
│   ├── security/                DevSecOps for AI code
│   └── factory-model/           Scale: multi-agent, batch, metrics
│
├── runtime/
│   ├── golden-path/             Quickstarts, bootstrap
│   ├── prompts/                 System prompts for agents
│   └── quality-gates/           Definition of done
│
├── case-studies/                Real workflow examples
├── bench/                       Benchmark tasks
├── examples/php-symfony-k8s/    Complete reference implementation
└── tools/                       Validation utilities

---

Security Module — Your Competitive Edge

AI-generated code needs additional security controls:

Component	Purpose
Secure Code Generation	Security-aware prompts, OWASP rules
Security Gates	SAST, secrets detection, dependency scanning
Supply Chain Security	Dependencies, AI model trust
Audit Trail	Traceability for all AI-generated code

---

Factory Model — Scale to Teams

When you need more than 1 developer + 1 AI:

Component	Purpose
Multi-Agent Orchestration	Coordinate N agents on M tasks
Batch Pipeline	Overnight code generation
Automated Gates	Pre-review quality checks
Metrics Dashboard	Track and optimize

---

Adoption Levels

Level	Files	Time to Start
Micro	2 files	10 minutes
Minimal	6 files	30 minutes
Full	Complete framework	2 hours
Factory	+ Scale modules	1 week

See Bootstrap Guide

---

Key Principles

Human at the Checkpoints

AI executes autonomously within bounds. Humans approve at defined gates.

Escalation Over Assumption

When in doubt, the AI asks. It's faster to clarify than to fix bad code.

Proportional Process

Trivial tasks get fast path. Complex tasks get full workflow.

Security by Default

Every line of AI-generated code goes through security gates.

---

Contributing

See CONTRIBUTING.md for guidelines.

License

MIT License — See LICENSE for details.

Author

Laurent Giovannoni

---

A methodology framework for AI-assisted software development — ship quality code faster with human oversight.