Skip to content

Commit 6b38a76

Browse files
laugiovlaugiov
committed
feat: add Security module and Factory Model for scale
Major additions to the framework: Security Module (core/security/): - Secure code generation with OWASP-aware prompts - Security gates (SAST, secrets, dependencies) - Supply chain security for AI pipelines - Audit trail for AI-generated code Factory Model (core/factory-model/): - Multi-agent orchestration - Batch pipeline for overnight generation - Automated pre-review gates - Metrics dashboard
1 parent 3a6e6eb commit 6b38a76

12 files changed

Lines changed: 3192 additions & 135 deletions

‎README.md‎

Lines changed: 141 additions & 71 deletions
Original file line numberDiff line numberDiff line change
@@ -1,125 +1,195 @@
1-
# AI-Driven Development Framework
1+
# Agentic Development Framework
22

33
[![Documentation](https://img.shields.io/badge/docs-99%20files-blue)](./DOCUMENTATION_INDEX.md)
44
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
55

6-
> A **technology-agnostic framework** for autonomous AI-driven software delivery — from Issue to PR with human oversight at defined checkpoints.
6+
> **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.
77
88
---
99

10-
## What This Repo Is
10+
## What Problem This Solves
1111

12-
1. **An agentic development framework** for autonomous Issue→PR workflows where AI agents plan, implement, test, and deliver with human oversight at defined checkpoints.
12+
AI coding assistants can generate code fast, but without structure:
13+
- Developers spend too much time validating AI output
14+
- Quality is inconsistent across sessions
15+
- Security issues slip through
16+
- No clear process for when to trust vs. verify
1317

14-
2. **A methodology** for writing unambiguous, security-by-design documentation that enables AI coding assistants to implement systems without drifting from standards.
18+
This framework provides **guardrails** that make AI-assisted development predictable, secure, and scalable.
1519

16-
3. **A complete example** demonstrating the methodology applied to a real-world platform (PHP/Symfony/Kubernetes).
20+
---
1721

18-
## What This Repo Is NOT
22+
## What This Framework Provides
1923

20-
- Not tied to any specific technology stack
21-
- Not a prompt library or "magic" AI coding tricks
22-
- Not autonomous execution without human supervision
24+
| Component | Purpose |
25+
|-----------|---------|
26+
| **Checkpoints** (C0→C3) | Structured workflow: Scope → Plan → Implement → PR |
27+
| **Escalation Rules** | When AI must stop and ask the human |
28+
| **Quality Gates** | Automated + human verification at each stage |
29+
| **Security Module** | DevSecOps for AI-generated code |
30+
| **Factory Model** | Scale to multiple agents and batch processing |
2331

2432
---
2533

2634
## Start Here
2735

2836
| Your Goal | Start With |
2937
|-----------|------------|
30-
| **Apply to your own project** | [BOOTSTRAP_NEW_PROJECT.md](runtime/golden-path/BOOTSTRAP_NEW_PROJECT.md) |
31-
| Explore agentic workflows | [core/README.md](core/README.md) |
32-
| Understand the methodology | [METHODOLOGY.md](METHODOLOGY.md) |
33-
| See a complete example | [examples/php-symfony-k8s/](examples/php-symfony-k8s/) |
34-
| Find your path by profile | [REPO_MAP.md](REPO_MAP.md) |
38+
| **Apply to your project** | [Bootstrap Guide](runtime/golden-path/BOOTSTRAP_NEW_PROJECT.md) |
39+
| Learn the workflow | [Agent Quickstart](runtime/golden-path/QUICKSTART_AGENT.md) |
40+
| Understand checkpoints | [Checkpoints Spec](core/spec/CHECKPOINTS.md) |
41+
| See real examples | [Case Studies](case-studies/) |
42+
| Scale to teams | [Factory Model](core/factory-model/) |
43+
| Secure AI code | [Security Module](core/security/) |
3544

3645
---
3746

38-
## Repository Structure
47+
## The Core Workflow
3948

4049
```
41-
├── [Framework]
42-
│ ├── core/ Agent operating model, checkpoints, templates
43-
│ ├── runtime/ Quickstarts, prompts, quality gates
44-
│ ├── bench/ 10 benchmark tasks, scoring, runner
45-
│ └── tools/ Validation utilities
46-
│
47-
├── [Examples]
48-
│ └── php-symfony-k8s/ Complete reference implementation
49-
│
50-
├── [Methodology] README, METHODOLOGY, GLOSSARY
51-
├── [Case Studies] case-studies/
52-
└── [Supporting] LICENSE, CONTRIBUTING, .github/
50+
┌─────────────────────────────────────────────────────────────┐
51+
│ BEFORE ANY WORK │
52+
│ Check Escalation Triggers → If any apply → STOP → Ask │
53+
└─────────────────────────────────────────────────────────────┘
54+
│
55+
▼
56+
┌─────────────────────────────────────────────────────────────┐
57+
│ C0: SCOPE │
58+
│ • Understand the task │
59+
│ • Define what's in/out of scope │
60+
│ • Identify affected files │
61+
└─────────────────────────────────────────────────────────────┘
62+
│
63+
▼
64+
┌─────────────────────────────────────────────────────────────┐
65+
│ C1: PLAN (for non-trivial tasks) │
66+
│ • Document approach │
67+
│ • Identify risks │
68+
│ • Get human validation if needed │
69+
└─────────────────────────────────────────────────────────────┘
70+
│
71+
▼
72+
┌─────────────────────────────────────────────────────────────┐
73+
│ C2: IMPLEMENT │
74+
│ • Write code following plan │
75+
│ • Run tests │
76+
│ • Pass automated gates │
77+
└─────────────────────────────────────────────────────────────┘
78+
│
79+
▼
80+
┌─────────────────────────────────────────────────────────────┐
81+
│ C3: PR & PROOFS │
82+
│ • Document what was done │
83+
│ • Provide evidence (tests, screenshots) │
84+
│ • Human reviews and approves │
85+
└─────────────────────────────────────────────────────────────┘
5386
```
5487

55-
Full index: [DOCUMENTATION_INDEX.md](DOCUMENTATION_INDEX.md)
56-
5788
---
5889

59-
## The Framework
90+
## Escalation Rules — The Highest Value Component
91+
92+
AI agents must **stop and ask** when:
6093

61-
### Agent Operating Model
94+
| Trigger | Example |
95+
|---------|---------|
96+
| Architecture decisions | New service, schema change, new dependency |
97+
| Security concerns | Auth changes, crypto, access control |
98+
| Data handling | PII, migrations, retention policies |
99+
| Breaking changes | API changes, deprecations |
100+
| Uncertainty | Multiple valid approaches, unclear requirements |
62101

63-
Defines how AI agents work autonomously within boundaries:
64-
- **5 Roles**: Manager, Planner, Implementer, Tester, Reviewer
65-
- **Workflow**: Plan → Act → Observe → Fix
66-
- **Checkpoints**: C0 (scope) → C1 (plan) → C2 (implement) → C3 (PR)
102+
See [ESCALATION_RULES.md](core/agent-operating-model/ESCALATION_RULES.md)
67103

68-
See [core/agent-operating-model/](core/agent-operating-model/)
104+
---
69105

70-
### Escalation Rules
106+
## Task Size → Workflow
71107

72-
When agents must pause and request human input:
73-
- Architecture decisions
74-
- Security concerns
75-
- Multiple valid approaches
76-
- Iteration limits reached
108+
Not every task needs the full workflow:
77109

78-
See [core/agent-operating-model/ESCALATION_RULES.md](core/agent-operating-model/ESCALATION_RULES.md)
110+
| Size | Lines | Workflow |
111+
|------|-------|----------|
112+
| **Trivial** | < 10 | Fast Path (C0 + C3 only) |
113+
| **Small** | 10-50 | Lite (C0 + C2 + C3) |
114+
| **Medium** | 50-200 | Full (C0 → C1 → C2 → C3) |
115+
| **Large** | > 200 | Full + Extra Review |
79116

80-
### Quality Gates
117+
---
81118

82-
Definition of Done by change type:
83-
- Documentation, code, configuration, schema changes
84-
- Machine-checkable and human-judgment criteria
119+
## Repository Structure
85120

86-
See [runtime/quality-gates/](runtime/quality-gates/)
121+
```
122+
├── core/
123+
│ ├── agent-operating-model/ Roles, escalation, golden rules
124+
│ ├── spec/ Checkpoints, templates
125+
│ ├── security/ DevSecOps for AI code
126+
│ └── factory-model/ Scale: multi-agent, batch, metrics
127+
│
128+
├── runtime/
129+
│ ├── golden-path/ Quickstarts, bootstrap
130+
│ ├── prompts/ System prompts for agents
131+
│ └── quality-gates/ Definition of done
132+
│
133+
├── case-studies/ Real workflow examples
134+
├── bench/ Benchmark tasks
135+
├── examples/php-symfony-k8s/ Complete reference implementation
136+
└── tools/ Validation utilities
137+
```
87138

88139
---
89140

90-
## Key Principles
141+
## Security Module — Your Competitive Edge
91142

92-
### Explicit Over Implicit
93-
Every decision includes justification. AI agents follow documented reasoning, not guesses.
143+
AI-generated code needs additional security controls:
94144

95-
### Validation Checkpoints
96-
Every workflow stage includes verification criteria for self-validation.
145+
| Component | Purpose |
146+
|-----------|---------|
147+
| [Secure Code Generation](core/security/SECURE_CODE_GENERATION.md) | Security-aware prompts, OWASP rules |
148+
| [Security Gates](core/security/SECURITY_GATES.md) | SAST, secrets detection, dependency scanning |
149+
| [Supply Chain Security](core/security/SUPPLY_CHAIN_SECURITY.md) | Dependencies, AI model trust |
150+
| [Audit Trail](core/security/AUDIT_TRAIL.md) | Traceability for all AI-generated code |
97151

98-
### Human at the Checkpoints
99-
Autonomous execution within bounds; escalation and approval at defined gates.
152+
---
153+
154+
## Factory Model — Scale to Teams
155+
156+
When you need more than 1 developer + 1 AI:
100157

101-
### Technology Agnostic
102-
The framework applies to any stack. Adapt checkpoints and prompts to your tools.
158+
| Component | Purpose |
159+
|-----------|---------|
160+
| [Multi-Agent Orchestration](core/factory-model/MULTI_AGENT_ORCHESTRATION.md) | Coordinate N agents on M tasks |
161+
| [Batch Pipeline](core/factory-model/BATCH_PIPELINE.md) | Overnight code generation |
162+
| [Automated Gates](core/factory-model/AUTOMATED_GATES.md) | Pre-review quality checks |
163+
| [Metrics Dashboard](core/factory-model/METRICS_DASHBOARD.md) | Track and optimize |
103164

104165
---
105166

106-
## Examples
167+
## Adoption Levels
107168

108-
### PHP/Symfony/Kubernetes
169+
| Level | Files | Time to Start |
170+
|-------|-------|---------------|
171+
| **Micro** | 2 files | 10 minutes |
172+
| **Minimal** | 6 files | 30 minutes |
173+
| **Full** | Complete framework | 2 hours |
174+
| **Factory** | + Scale modules | 1 week |
109175

110-
A complete reference implementation with documentation files:
176+
See [Bootstrap Guide](runtime/golden-path/BOOTSTRAP_NEW_PROJECT.md)
177+
178+
---
179+
180+
## Key Principles
181+
182+
### Human at the Checkpoints
183+
AI executes autonomously within bounds. Humans approve at defined gates.
111184

112-
| Area | Content |
113-
|------|---------|
114-
| Architecture | Hexagonal, DDD, microservices |
115-
| Security | Zero Trust, OAuth2, Vault |
116-
| Infrastructure | Kubernetes, Istio, observability |
117-
| Development | Coding standards, testing, APIs |
118-
| Operations | Monitoring, incident response, DR |
185+
### Escalation Over Assumption
186+
When in doubt, the AI asks. It's faster to clarify than to fix bad code.
119187

120-
See [examples/php-symfony-k8s/](examples/php-symfony-k8s/)
188+
### Proportional Process
189+
Trivial tasks get fast path. Complex tasks get full workflow.
121190

122-
*More examples welcome via contributions.*
191+
### Security by Default
192+
Every line of AI-generated code goes through security gates.
123193

124194
---
125195

@@ -137,4 +207,4 @@ MIT License — See [LICENSE](LICENSE) for details.
137207

138208
---
139209

140-
*A technology-agnostic framework for AI-driven software delivery.*
210+
*A methodology framework for AI-assisted software development — ship quality code faster with human oversight.*

0 commit comments

Comments
 (0)