RFC: Advanced Workflow Extensions for Greenfield and Brownfield AI-DLC Projects

[aymanyaq]

RFC: Advanced Workflow Extensions for Greenfield and Brownfield AI-DLC Projects

1. Background & Motivation

The AI-DLC methodology provides an incredibly robust, structured framework for guiding AI agents through the software development lifecycle. However, as organizations attempt to scale AI-DLC into massive, complex enterprise environments (both greenfield and brownfield applications), several gaps emerge:

1. Sequential Bottlenecks: Agent execution is inherently sequential. In projects with dozens of independent modules, waiting for sequential code generation drastically increases the end-to-end completion time.
2. Verification Gaps: The current Build & Test phase generates instructional Markdown for humans to execute, which breaks the autonomous verification loop.
3. Brownfield Data Blindspots: Reverse Engineering currently relies heavily on schema discovery. In data-driven brownfield apps, the AI often guesses or hallucinates categorical values because it never profiles the actual data.
4. Enterprise Code Safety: Standard code generation can produce silent, hard-to-detect failures in complex environments (e.g., pagination loops, middleware tracing loss, mock lifecycle pollution).
5. Missing Estimation Bridge: Units of work are decomposed effectively but there is no translation layer for human project managers who need sprint-level sizing.
6. Domain-Specific NFR Gaps: A global NFR pass covers system-wide concerns (database choice, caching layer, retry framework), but it cannot anticipate unit-specific performance characteristics — how a particular unit handles slow dependencies, what its latency budget is, or what happens at its specific system boundaries.

To address these challenges, I am proposing 6 new opt-in extensions.

Note: While I am presenting these 6 extensions together here to show the cohesive vision for Advanced/Enterprise scaling, I have opened them as 6 completely independent Pull Requests. This allows the community to debate, accept, or reject each extension on its own individual merit.

---

2. Proposed Extensions

2.1 Parallel Execution — 19 Rules (See PR #209)

Problem: Sequential generation of independent units of work is highly inefficient for large projects.
Solution: A comprehensive, coordinator-driven, adaptive parallel execution model built on the principle "Accuracy First — parallelism is a speed optimization, accuracy is non-negotiable."

Key capabilities across 19 rules (PARALLEL-EXEC-001 through PARALLEL-EXEC-019):

• Wave Dependency Planning with formal accuracy safety assessments per wave group
• Pre-Flight Accuracy Gate that re-validates conditions at execution time
• Sub-Task Parallelism within units (backend ∥ frontend, data pipeline ∥ visualization, ML training ∥ serving, IaC ∥ application code) with mandatory convergence gates
• Anticipatory Test Planning — starts test plans as soon as Functional Design is approved
• Cross-Unit Knowledge Sharing via shared-patterns.md
• Coordinator Dispatch Model — full dispatch lifecycle with prompt templates, context discipline, result collection, and fallback-to-sequential
• Runtime Convergence Validation — catches hardcoded values that don't match actual data
• Critical Path Marking and Priority within waves
• Session Resume with context loading discipline for parallel dispatch
• Impact: Massively reduces overall execution time while maintaining deterministic, accuracy-first state tracking.

2.2 Build & Test Execution — 5 Rules (See PR #210)

Problem: The default AI-DLC Build & Test phase generates test instruction documentation for humans to run.
Solution: Upgrades the phase to enforce actual test execution with self-healing iteration.

Key capabilities across 5 rules (BUILD-TEST-EXEC-001 through BUILD-TEST-EXEC-005):

• Environment Validation Pre-flight — validates dependencies, test runner config, zero-warnings policy, setup file execution, and environment isolation
• Contract Verification — static pre-execution validation of import paths, identifiers, selectors, mock paths, pagination contracts, error serialization contracts, and mock lifecycle alignment
• Test Execution and Iteration — runs suites, categorizes failures, fixes code, iterates until green
• Inline Test Execution During Code Generation — runs tests immediately after each code gen step, not deferred to end
• Results Presentation — completion messages reflect actual test runner output, not estimates
• Impact: Closes the loop on autonomous verification and increases confidence in generated code.

2.3 Estimation Guidance — 2 Rules (See PR #211)

Problem: The Units Generation phase successfully breaks down work but provides no translation layer for human project managers (e.g., sprint planning).
Solution: Introduces structured estimation with two complementary rules:

• ESTIMATION-001 (Structured Estimation): Adds relative complexity sizing (story points or T-shirt sizes) as a mandatory measure, plus an optional conventional team estimate (developer-weeks) labeled clearly as "Reference Only"
• ESTIMATION-002 (Anti-Confusion Guard): Prevents presenting conventional estimates as AI-DLC execution predictions. AI-DLC elapsed time depends on approval gate throughput, not generation speed
• Impact: Bridges the gap between autonomous execution and agile project management tools.

2.4 Code Safety — 6 Rules (See PR #212)

Problem: AI code generation frequently misses complex, framework-level safety constraints that compile successfully but fail silently at runtime.
Solution: Injects strict rules during the Code Generation phase to prevent common silent failure classes, each derived from real production incidents:

• CODE-SAFETY-001 (Middleware/Request-Context Safety): Traces every request-scoped property to the middleware that populates it; verifies route-level vs global application
• CODE-SAFETY-002 (Configuration/Environment Isolation): Prevents config loaders from loading env files in test mode
• CODE-SAFETY-003 (Test Mock Lifecycle): Handles module reset invalidation, clearing vs resetting distinction, auto-mock limitations with instanceof, and mock scope leakage
• CODE-SAFETY-004 (Pagination/Bounded-Query Safety): Ensures all pages are consumed, continuation tokens are acted on, and tests include multi-page scenarios
• CODE-SAFETY-005 (Error Serialization Consistency): Ensures all semantic error fields are serialized and tests assert the full response shape
• CODE-SAFETY-006 (Post-Refactor Test Alignment): Greps test files after any source refactor, updates stale mocks, and runs affected tests immediately
• Impact: Dramatically reduces hard-to-debug architectural bugs in the generated codebase.

2.5 NFR Compensation — 2 Rules (See PR #213)

Problem: A global NFR pass covers system-wide concerns (database choice, caching layer, retry framework), but it cannot anticipate unit-specific performance characteristics — how a particular unit handles slow dependencies, what its latency budget is, or what happens at its specific system boundaries. When units skip their dedicated NFR stages (e.g., because NFR was handled globally by a foundation unit), these domain-specific concerns are lost entirely.
Solution: Adds two complementary rules to the Functional Design phase:

• NFR-COMP-001 (Mandatory Performance Section): When a unit's NFR stages are skipped, its Functional Design must include a "Performance & Behavioral Considerations" section covering latency budgets, timeout strategies, resource constraints, edge-case behavior at system boundaries, and testable acceptance criteria specific to that unit.
• NFR-COMP-002 (Cross-Reference with Global NFR): Requires the unit to explicitly reference inherited global NFR decisions, identify gaps where global NFR doesn't cover this unit's specific needs, and flag conflicts for resolution before Code Generation.
• Impact: Ensures domain-specific performance concerns are captured where they are best understood — during the functional design of each domain unit — without requiring a full NFR stage re-run.

2.6 Data Profile — 4 Rules (See PR #214)

Problem: During Reverse Engineering, agents understand the database schema but remain blind to the actual values, leading to hallucinations when handling enums, categories, or edge-case nulls. Additionally, shared data dependencies have fragilities (CWD-relative paths, deprecated APIs) that aren't surfaced.
Solution: A comprehensive data profiling system that spans the full construction lifecycle:

• DATA-PROFILE-001 (Data Source Profiling): During Reverse Engineering, profiles every data source — extracts exact categorical values, key patterns (for NoSQL), numeric ranges, storage type variance (mixed-type detection for schema-less stores), and audits shared data dependencies (signatures, fragilities, safe usage patterns). Uses a 3-tier accessibility model (local → code-inferable → user-reported)
• DATA-PROFILE-002 (Functional Design Alignment): Requires Functional Design to read the profile and use exact values for filters, selectors, and business rules
• DATA-PROFILE-003 (Code Generation Accuracy): Enforces exact value matching for all hardcoded strings in generated code; mandates cross-referencing every filter value against the profile
• DATA-PROFILE-004 (Build & Test Validation): Validates that mixed-type attributes are handled defensively in source code
• Impact: Eliminates "empty result set" errors and runtime KeyErrors by ensuring the AI writes code based on reality, not schema assumptions.

---

3. Implementation Status

To demonstrate the viability of these extensions, I have drafted all 6 in accordance with the CONTRIBUTING.md standards.

• Fully Agnostic: They do not assume specific IDEs or platforms.
• Linting: All Markdown files strictly adhere to the project's markdownlint-cli2 rules (0 errors).
• Format: They utilize the established extension.md and extension.opt-in.md structure.

4. Request for Comments

I would love to hear feedback from the maintainers and the community on the following topics across all 6 extensions:

Parallel Execution

1. Does the wave-based Coordinator model align with the long-term vision for AI-DLC multi-agent scaling, or is the project considering alternative parallelism approaches (e.g., DAG-based continuous dispatch)?
2. Should the wave tracking state live in aidlc-state.md or in a dedicated file to prevent context window bloat on very large projects?
3. The extension contains 19 rules — is this granularity appropriate, or should some rules be consolidated?

Build & Test Execution

4. Is there a concern about agents running arbitrary test commands in user environments? Should there be a sandboxing or confirmation step before execution?
5. How does the self-healing retry loop interact with the existing overconfidence-prevention rules? Should there be a maximum retry cap defined at the extension level?
6. The contract verification step (BUILD-TEST-EXEC-002) includes checks for pagination, error serialization, and mock lifecycle — is there overlap concern with the Code Safety extension, or is the redundancy desirable as defense-in-depth?

Estimation Guidance

7. Is the dual-estimate model (AI-DLC time vs. conventional developer-weeks) useful for the broader community, or would a single unified estimate be preferred?
8. Should estimation outputs be integrated into aidlc-state.md or kept as standalone artifacts?

Code Safety

9. Are the 6 safety categories (middleware context, config isolation, mock lifecycle, pagination, error serialization, post-refactor alignment) comprehensive enough, or should additional categories be considered?
10. How does this extension interact with the existing property-based-testing extension? Should there be a formal recommendation to use them together?

NFR Compensation

11. Is the two-rule approach (mandatory performance section + cross-reference with global NFR) the right granularity, or should this be a single combined rule?
12. Should the extension trigger only when NFR stages are fully skipped, or should it also apply when NFR stages are executed but at reduced depth (e.g., a "lite" NFR pass)?
13. How should conflicts between a unit's domain-specific NFR needs and global NFR decisions be escalated — should they block Code Generation or just be flagged as warnings?

Data Profile

14. Are there privacy or security concerns with agents profiling real production data (e.g., PII exposure)? Should the extension include data masking guidance?
15. Should the profiling depth (number of rows sampled, categorical value limits) be configurable via the opt-in prompt?
16. The 3-tier accessibility model (local → code-inferable → user-reported) — is this sufficient, or should there be a tier for API-accessible data sources?

General

17. Are there any concerns regarding the cumulative prompt token overhead when multiple extensions are enabled simultaneously?
18. Would the maintainers prefer these to be merged gradually or evaluated as a consolidated batch?

Thank you for your time and guidance!

[leandrodamascena]

Hey @aymanyaq, thanks for putting this together. The project is still evolving and we really appreciate people thinking about where it could go.

We love seeing the community engaged and proposing ideas. At the same time, we want to make sure everything that goes into the project is well aligned with its direction and foundations. We'd rather take fewer things that fit well than merge ideas just because they exist.

Those are my feedback on each item you proposed:

2.1 Parallel Execution - 19 Rules
Sequential generation of independent units of work is highly inefficient for large projects.

I can see why this looks like a bottleneck from the outside, but the sequential model is intentional. The core workflow explicitly states that each unit is completed fully before moving to the next. It's a design decision we're happy with. 19 rules to change this would be more of a core rewrite than an extension, and it doesn't align with where the project is today.

2.2 Build & Test Execution - 5 Rules
The default AI-DLC Build & Test phase generates test instruction documentation for humans to run.

I understand the appeal of closing the loop on test execution. Today the project generates instructions rather than executing code, and that's by design. But this is a topic worth exploring. If you're interested, it could be a good candidate for its own issue so we can discuss the safety and scope implications separately.

2.3 Estimation Guidance - 2 Rules
Introduces structured estimation with story points or T-shirt sizes as a mandatory measure.

This is an interesting space, but AI-DLC focuses on guiding agents through development workflows. IMO sprint estimation, story points, and developer-week projections are project management concerns that fall outside what this project does. It's just not the right space for it.

2.4 Code Safety - 6 Rules
Injects strict rules during the Code Generation phase to prevent common silent failure classes.

This is the one with the most potential. The underlying concepts (pagination safety, error serialization, mock lifecycle) are real problems that show up across stacks. The rules are mostly written in an agnostic way, which is great. This could be another good candidate (like 2.2) for a standalone issue and a more focused discussion on how it fits as an extension.

2.5 NFR Compensation - 2 Rules
When units skip their dedicated NFR stages, these domain-specific concerns are lost entirely.

I appreciate the thinking here, but the workflow already has NFR Requirements and NFR Design as conditional stages with intelligent skip logic. The mechanism for when to run and when to skip is already there. From what we've seen, this gap doesn't really show up in practice.

2.6 Data Profile - 4 Rules
During Reverse Engineering, agents understand the database schema but remain blind to the actual values.

The idea of not guessing values is solid. The tiered approach (local files, code-inferable, runtime-only) is thoughtful. Our concern is that Tier 1 and Tier 3 assume agents can access or request real data, which opens up security and privacy questions (PII, credentials). It's also quite specific to data-heavy applications and may not generalize well.

---

Overall: the project currently has 2 extension categories (security and testing). This RFC proposes 38 new rules across 6 extensions, which is larger than everything the project has today. Even if individual ideas had merit, the scale alone makes this hard to absorb.

None of this is meant to discourage you from contributing. We genuinely love having the community involved, and we want your ideas to land. We just hold the project to a high bar and want to make sure contributions are aligned before they go in. If something here resonates with you, pick one idea, open an issue, and let's talk it through together.

@scottschreckengaust and @harmjeff I'd love to hear your thoughts on this too and agree with the next steps.

[aymanyaq]

Thank you for the incredibly thoughtful and detailed review — I genuinely appreciate the time you took to evaluate each extension individually and the transparency about the project's direction.

Before responding point by point, I want to address the overall scale concern directly, because it frames everything else.

On Scale: Extensions as an Ecosystem — and a Differentiator

You noted that this RFC proposes 38 new rules across 6 extensions, larger than everything the project has today. I understand why that feels like a lot. But I'd argue this is actually a strength of the extension architecture, not a risk.

Every organization customizes their SDLC differently. One company needs parallel execution for multi-unit projects; another needs data profiling for brownfield migrations; another needs both. The extension model exists precisely so the core stays lean while organizations tailor the methodology to their reality. An extension library that grows beyond the core framework isn't bloat — it's an ecosystem.

This is also what sets AI-DLC apart from other AI-assisted SDLC approaches. Frameworks like BMAD and Squad propose fixed models — BMAD uses predefined AI personas (Product Manager, Architect, Developer, QA) in a role-driven pipeline; Squad assigns a team of named specialists (frontend, backend, tester, lead) that each run in their own context. Both are valuable, but both essentially digitize the traditional org chart — they map conventional roles onto AI personas and keep the same human team structure underneath.

AI-DLC does something fundamentally different at two levels. First, the white paper reimagines how humans themselves interact — mob elaboration, mob construction, where the whole team converges around AI-generated artifacts rather than splitting into siloed roles. Second, the extension architecture lets organizations customize methodology behavior across the entire lifecycle without forking the core or being locked into a persona model. No other AI-driven SDLC framework offers both: a new model for human collaboration and an extensible system for adapting the process. A rich extension ecosystem is what makes that vision real. I see these extensions as the beginning of that ecosystem, where the community contributes specialized behaviors that the core team doesn't need to maintain as part of the default workflow.

That said, I absolutely hear you on the "pick one and let's talk it through" guidance, and I'll follow it. Here are my responses to each point:

---

2.1 Parallel Execution

I appreciate the pushback, and I want to clarify what this extension does — and doesn't — change.

The extension does not alter the stage sequence within a unit. Functional Design → NFR Requirements → NFR Design → Infrastructure Design → Code Generation → Build & Test remains untouched. Every approval gate stays in place. What it does is allow independent units with no cross-dependencies to generate concurrently — and only after a formal safety assessment confirms zero risk to accuracy.

The reason I built this comes from a practical gap I experienced with the mob construction model that AI-DLC promotes. The white paper envisions teams collaborating around AI-generated artifacts — mob elaboration, mob construction. But during Construction, when the agent is sequentially generating Unit 3 after finishing Unit 2, the mob is waiting. The most expensive resource in the room — the team's collective attention — is idle.

Parallel execution solves this by letting the agent generate independent units concurrently, so the mob can diverge to review multiple units simultaneously. Critical path units get priority, and the team's time is used on what humans do best: reviewing, approving, and catching issues — not watching sequential generation. This actually makes the mob more productive, not less collaborative.

I'd also note that the white paper itself states: "A Unit can be executed through one or more Bolts, which may run in parallel or sequentially." The concept of parallel execution across independent work streams is already in the methodology's foundational vision. This extension provides the safety framework to make that vision practical — with wave dependency plans, pre-flight accuracy gates, convergence validation, and an automatic fallback to sequential whenever accuracy risk is detected.

That said, I hear you on the rule count. 19 rules is the comprehensive version — I'm open to distilling this to a tighter core (wave planning, pre-flight gate, convergence check, dispatch model, knowledge sharing, and session resume) and positioning the rest as recommended practices rather than enforced rules. Would that framing be worth exploring in a focused issue?

---

2.2 Build & Test Execution

I'd love to open a focused issue for this one. You're right that the safety and scope implications deserve their own discussion.

I'll note that the white paper describes the AI agent as actively executing tests: "the AI agent executes the test suites, analyses the results and correlates failure points with code changes." The extension brings the open-source implementation closer to that described vision. But I understand the gap between vision and current implementation requires careful handling — especially around what the agent is allowed to execute in user environments.

I'll open a standalone issue focused on the safety model (sandboxing, confirmation steps, retry caps) and how test execution fits with the existing overconfidence-prevention rules.

---

2.3 Estimation Guidance

Fair point. The white paper itself questions whether traditional estimation models are relevant in an AI-driven paradigm: "Would effort estimation (story points) be as critical if AI diminishes the boundaries between simple, medium and hard tasks?" I agree this falls outside the scope of agent workflow guidance. Happy to withdraw this one.

---

2.4 Code Safety

I'm glad this resonated — it's the extension I'm most confident about. Every rule was derived from real production incidents where AI-generated code had structural correctness but behavioral incorrectness. I'll open a focused issue to discuss how it fits as an extension, and I'm happy to iterate on scope, rule count, and framing based on the team's guidance.

---

2.5 NFR Compensation

I understand. The existing skip logic may well handle this for most projects. The scenarios I encountered were in very large multi-unit projects where domain-specific latency and timeout needs diverged significantly from global settings. I'll withdraw this as a standalone extension, though I'd note it naturally integrates with the parallel execution discussion (PARALLEL-EXEC-018 covers this case for parallel waves).

---

2.6 Data Profile

I want to push back gently on the "may not generalize well" concern. This gap was identified not through a complex enterprise system, but through running BMAD evaluation against the methodology on a simple Streamlit app with a single animation feature. If data value hallucination shows up in trivial projects, it is not a niche concern — it is a foundational one. The agent guesses or abbreviates categorical values, producing code that compiles but returns empty results at runtime.

Your PII/security concerns are absolutely valid and addressable. The profiling doesn't require production PII — it requires knowing that a column's values are 'ACTIVE', 'INACTIVE', not 'John Smith'. I can add explicit data masking guidance and scope Tier 1 to schema-level metadata rather than row-level data. Tier 3 (user-reported) already works through the human, not the agent accessing data directly.

I'm happy to open a focused issue for this one as well, or fold it into a future discussion once Code Safety and Build & Test are settled.

---

Next Steps

Following your guidance, I'll:

1. Open a focused issue for Code Safety — the one with the most alignment, ready for detailed discussion
2. Open a focused issue for Build & Test Execution — scoped to safety model and the gap between current implementation and white paper vision
3. Withdraw Estimation Guidance and NFR Compensation — close PRs feat: add estimation guidance extension #211 and feat: add NFR compensation extension #213
4. Keep Parallel Execution and Data Profile open for discussion — but won't push for immediate merge; happy to let them evolve through focused issues when the timing is right

Thank you again for the guidance. I genuinely appreciate the team's high bar — it's what makes the project worth contributing to.