Highlights
What We Build
An interactive Capstone Scoping Workbench — a React dashboard backed by FastAPI that guides you through structured domain selection, requirements elicitation, architecture pattern matching, and risk qualification, producing a machine-readable
CapstoneProjectManifestJSON consumed directly by the L91–L93 development sprint.A
CapstoneFeasibilityValidatorthat calls Gemini 2.0 Flash to score your proposed vertical against eight production-readiness criteria (data availability, regulatory burden, latency tolerance, LLM dependency surface, and four more) and outputs a numeric feasibility matrix.A
CapstoneRequirementsMatrix— a structured JSON artifact that maps every functional requirement to the specific VAIA lesson (L1–L89) whose implementation pattern satisfies it, creating an explicit curriculum-to-capstone traceability index.A
CapstoneArchitectureBlueprintgenerator that uses your requirements matrix to recommend one of five validated architecture topologies (single-agent RAG, multi-agent orchestration, hybrid FSM+RAG, compliance-hardened, or streaming pipeline) with component-level justifications.A complete
setup.shthat consumes theLegalReportRendereroutput format from L86 to generate your first scope document draft, closing the curriculum loop.
Connection to L89 — Presenting & Defending Agent Architectures L89 built the ArchitecturePresentationEngine and StakeholderAdaptationLayer — the communication scaffolding for defending technical choices to mixed audiences. L90 consumes those patterns in reverse: the Scoping Workbench uses the same stakeholder taxonomy to produce scope documentation that will survive stakeholder review without revision. The SlideNarrativeGenerator output format from L89 becomes the prose template for the CapstoneScopeDocument‘s executive summary section.
Enables L91–L93 — Capstone Development Every artifact produced in this lesson is a direct build input for the development sprint. The CapstoneProjectManifest carries dependency declarations, component scaffolding targets, and acceptance criteria in a format the L91 scaffolding script reads at boot time to generate the correct directory tree, Docker Compose topology, and CI pipeline.
Architecture Context
Place in the 90-Lesson VAIA Path L90 sits at the curriculum’s inflection point — the last lesson whose primary output is a plan rather than a system. Lessons L1–L89 built individual VAIA components: RAG pipelines (L18–L25), multi-agent orchestration (L46–L60), MLOps (L61–L75), compliance hardening (L79–L82), and vertical case studies in finance, healthcare, and legal (L84–L86). L90’s job is to assemble the minimum viable selection from that catalog into a coherent, scoped, feasible project brief that fits a 3-lesson (L91–L93) sprint.
Integration With Prior Components The scoping workbench explicitly references five prior implementation patterns by import path, not by documentation link. This is intentional: it forces the scope document to stay grounded in what was actually built.
Module Objectives Alignment Module 10’s goal is not to build a new component — it is to demonstrate architectural judgment: the ability to scope a greenfield VAIA project from first principles, apply the curriculum’s patterns appropriately, and produce a plan that a senior engineer could execute without ambiguity.
Core Concepts
1. Scope as Architecture Constraint
The most expensive architectural decisions in a VAIA project are made implicitly during scoping — before a line of code exists. Choosing a vertical (legal, healthcare, financial, logistics) determines your regulatory surface. Choosing your primary user persona determines latency tolerance. Choosing your data sources determines whether you need a RAG pipeline, a fine-tuned adapter, or a hybrid. Each choice eliminates roughly 60% of the architecture space. Scoping is not documentation — it is architecture.
A production VAIA scope document must answer five questions deterministically:
Vertical boundary: What domain knowledge is in-scope vs. out-of-scope for the agent?
Regulatory surface: Which compliance frameworks apply, and what do they mandate technically?
Data topology: What does the agent retrieve, and from where?
LLM dependency surface: Which decisions are LLM-generated vs. deterministic?
Failure modes: What is the highest-consequence failure, and how does the architecture prevent it?
2. The Feasibility Matrix
Not every VAIA idea is buildable in a 3-lesson sprint. The CapstoneFeasibilityValidator applies a weighted scoring model across eight dimensions:
A weighted score ≥ 0.72 is required to proceed. Gemini 2.0 Flash generates the rationale for each dimension score; a deterministic scorer produces the numeric output. This is the hybrid determinism pattern from L84–L86 applied to meta-level project management.
3. Architecture Topology Selection
Five topology templates emerged across the curriculum:
Template A — Single-Agent RAG: One agent, one ChromaDB collection, one FastAPI backend. Suitable for narrow-domain Q&A with deterministic retrieval. Highest feasibility for a sprint. Reference: L25.
Template B — Multi-Agent Orchestration: Supervisor + specialist agents (2–4), shared message bus, SQLite WAL audit. Suitable for workflows with distinct sub-tasks. Reference: L52–L55.
Template C — Hybrid FSM + RAG: Finite state machine drives agent lifecycle; RAG handles knowledge retrieval at each state. Suitable for regulated workflows with mandatory state sequencing. Reference: L82, L86.
Template D — Compliance-Hardened: Template C + privilege sanitization layer + append-only hash-chained audit store + Gemini-as-judge evaluation loop. Suitable for healthcare, legal, finance verticals. Reference: L79–L86.
Template E — Streaming Pipeline: Async event-driven, Redis pub/sub, WebSocket frontend, low-latency user-facing. Suitable for real-time monitoring or alerting verticals. Reference: L63, L74.
The CapstoneArchitectureBlueprint generator maps your requirements matrix to one of these templates and outputs a component list with explicit lesson references for each component.
4. Traceability as a Design Invariant
The CapstoneRequirementsMatrix is not a checklist — it is a dependency graph. Every functional requirement points to:
The VAIA lesson that implements it
The named export from that lesson
The acceptance criterion that proves it works
The failure mode if it is omitted
This structure makes the capstone defensible in exactly the way L89 trained: you can answer “why did you choose this component?” with a curriculum reference, a lesson number, and a working code pointer.
Integration
Production Architecture Fit In production VAIA deployments, scoping is a formal gate — typically a written Architecture Decision Record (ADR) reviewed by a principal engineer before any infrastructure is provisioned. The CapstoneScopeDocument follows ADR conventions: context, decision, consequences, and alternatives considered. This is not pedagogical overhead; it is the artifact that prevents expensive mid-sprint pivots.
Enterprise Deployment Patterns Enterprise teams use three scoping anti-patterns that this lesson explicitly trains you to avoid:
Capability-first scoping: Starting with “I want to use multi-agent orchestration” rather than “I need to automate this workflow.” The
CapstoneFeasibilityValidatorblocks this by requiring a use-case description before topology selection is enabled.Optimistic data assumptions: Assuming a clean, labeled corpus exists. The feasibility matrix’s “Data availability” dimension requires you to specify your corpus construction plan at scoping time.
Compliance deferral: Treating regulatory requirements as post-MVP. The scope document’s regulatory surface section is mandatory — it cannot be left blank.
Implementation
GitHub Link
https://github.com/sysdr/vertical-ai-agent-p/tree/main/lesson90/l90-capstone-scoping
Component Architecture
┌─────────────────────────────────────────────────────────┐
│ Capstone Scoping Workbench │
│ │
│ React Dashboard (Vite + Recharts) │
│ ├── DomainSelector │
│ ├── RequirementsElicitor │
│ ├── FeasibilityScorecard │
│ ├── TopologyRecommender │
│ └── ManifestExporter │
│ │
│ FastAPI Backend │
│ ├── CapstoneFeasibilityValidator ← Gemini 2.0 Flash │
│ ├── CapstoneRequirementsMatrix │
│ ├── CapstoneArchitectureBlueprint │
│ ├── CapstoneScopeDocument │
│ └── CapstoneProjectManifest (JSON export) │
│ │
│ Persistence: SQLite WAL (scope versions) │
│ Integration: L86 LegalReportRenderer format │
└─────────────────────────────────────────────────────────┘Control & Data Flow
User selects vertical domain and describes the use case in natural language.
CapstoneFeasibilityValidatorcalls Gemini 2.0 Flash with the use-case description + eight scoring rubrics. Gemini returns rationale; a deterministic scorer calculates weighted score.If score ≥ 0.72,
CapstoneRequirementsMatrixis generated by mapping the use case to VAIA lesson exports.CapstoneArchitectureBlueprintreads the requirements matrix and selects an architecture topology.CapstoneScopeDocumentassembles the executive summary (using L89 prose template), technical plan, and risk register.CapstoneProjectManifestserializes all artifacts to a single JSON file consumed by L91 scaffolding.
State Machine
The scoping workbench is explicitly stateful — users cannot jump to step 4 without completing steps 1–3. This enforces the dependency invariant: architecture selection is downstream of feasibility validation.
IDLE → DOMAIN_DEFINED → USE_CASE_DESCRIBED → FEASIBILITY_SCORED →
REQUIREMENTS_MAPPED → BLUEPRINT_GENERATED → SCOPE_DRAFTED → MANIFEST_EXPORTED
Coding Highlights
CapstoneFeasibilityValidator — Hybrid Determinism Pattern
# backend/capstone_feasibility_validator.py
import google.generativeai as genai
from dataclasses import dataclass
from typing import Dict
WEIGHTS = {
"data_availability": 0.20,
"regulatory_clarity": 0.15,
"latency_tolerance": 0.10,
"llm_dependency": 0.15,
"integration_complexity": 0.15,
"testing_surface": 0.10,
"curriculum_coverage": 0.10,
"novelty_risk": 0.05,
}
THRESHOLD = 0.72
@dataclass
class FeasibilityResult:
scores: Dict[str, float] # deterministic, 0.0–1.0 per dimension
rationales: Dict[str, str] # LLM-generated prose per dimension
weighted_score: float # deterministic aggregate
proceed: bool # deterministic gate
blocking_dimensions: list # dimensions scoring < 0.5
async def validate_feasibility(use_case: str, domain: str) -> FeasibilityResult:
model = genai.GenerativeModel("gemini-2.0-flash")
prompt = f"""You are evaluating a VAIA capstone project proposal.
Domain: {domain}
Use Case: {use_case}
Score each dimension from 0.0 to 1.0 and provide a one-sentence rationale.
Return ONLY valid JSON with keys matching these dimensions:
{list(WEIGHTS.keys())}
Format: {{"dimension": {{"score": 0.0, "rationale": "..."}}}}"""
response = await model.generate_content_async(prompt)
raw = response.text.strip().removeprefix("```json").removesuffix("```")
parsed = json.loads(raw)
scores = {k: float(parsed[k]["score"]) for k in WEIGHTS}
rationales = {k: parsed[k]["rationale"] for k in WEIGHTS}
weighted = sum(scores[k] * WEIGHTS[k] for k in WEIGHTS)
return FeasibilityResult(
scores=scores,
rationales=rationales,
weighted_score=round(weighted, 4),
proceed=weighted >= THRESHOLD,
blocking_dimensions=[k for k, v in scores.items() if v < 0.5],
)Key pattern: Gemini generates rationale text; the numeric score is extracted from a structured JSON field and the weighted aggregate is computed deterministically in Python. No LLM involvement in the pass/fail decision. This is the same hybrid determinism applied in L84’s red-teaming scorer and L86’s contract clause extractor.
CapstoneRequirementsMatrix — Curriculum Traceability
# backend/capstone_requirements_matrix.py
LESSON_EXPORT_CATALOG = {
"RAG pipeline": {"lesson": 25, "export": "AgenticRAGPipeline"},
"Multi-agent orchestration": {"lesson": 52, "export": "AgentOrchestrator"},
"Compliance audit store": {"lesson": 79, "export": "GovernanceComplianceOrchestrator"},
"Bias mitigation": {"lesson": 81, "export": "BiasDetectionMitigationAgent"},
"LLM evaluation": {"lesson": 60, "export": "MultiAgentSystemEvaluator"},
"Fine-tuning adapter": {"lesson": 77, "export": "LoRAAdapterTrainer"},
"Reward alignment": {"lesson": 82, "export": "RewardAlignmentEngine"},
"Streaming frontend": {"lesson": 74, "export": "StreamingMetricsDashboard"},
}
def build_requirements_matrix(requirements: list[str]) -> dict:
"""Maps each requirement to a lesson export and acceptance criterion."""
matrix = {}
for req in requirements:
for pattern, ref in LESSON_EXPORT_CATALOG.items():
if pattern.lower() in req.lower():
matrix[req] = {
**ref,
"acceptance_criterion": f"Import {ref['export']} from L{ref['lesson']} passes integration test",
"failure_mode": f"Missing {ref['export']} causes silent capability degradation"
}
return matrixCapstoneProjectManifest — Machine-Readable Export
# backend/capstone_project_manifest.py
import json, hashlib, datetime
def export_manifest(
scope: dict,
requirements_matrix: dict,
blueprint: dict,
feasibility: dict
) -> dict:
payload = {
"schema_version": "1.0",
"generated_at": datetime.datetime.utcnow().isoformat(),
"curriculum_lesson": 90,
"capstone_vertical": scope["domain"],
"use_case": scope["use_case"],
"feasibility": feasibility,
"requirements": requirements_matrix,
"architecture_blueprint": blueprint,
"component_scaffold_targets": [
v["export"] for v in requirements_matrix.values()
],
"l91_bootstrap_instructions": {
"topology": blueprint["selected_template"],
"entry_lesson_imports": list(requirements_matrix.values()),
"acceptance_criteria": [v["acceptance_criterion"] for v in requirements_matrix.values()],
}
}
payload["manifest_hash"] = hashlib.sha256(
json.dumps(payload, sort_keys=True).encode()
).hexdigest()
return payloadThe manifest_hash field enables the L91 scaffolding script to verify manifest integrity before generating the project directory. Same hash-chain pattern used in L79’s audit store.Validation
Feasibility Gate: Run pytest tests/test_feasibility.py — asserts that a well-specified use case scores ≥ 0.72 and a deliberately vague use case scores < 0.72.
Requirements Coverage: Run pytest tests/test_requirements_matrix.py — asserts that every requirement maps to a lesson number in range [1, 89] with a non-null export name.
Manifest Integrity: Run pytest tests/test_manifest.py — asserts that manifest_hash matches the re-computed hash of the manifest body (tamper-evidence check from L79 pattern).
Frontend Progression: Cypress E2E test confirms that the “Generate Blueprint” button is disabled until feasibility score is displayed — verifying the state machine’s gate invariant.
Success Criteria:
Feasibility validator produces a score in [0.0, 1.0] for any valid input
Requirements matrix covers ≥ 80% of stated functional requirements
Blueprint selects exactly one topology template with ≥ 3 component justifications
Manifest passes hash integrity check
Scope document is ≥ 600 words and includes all five mandatory sections
Assignment
Extend the Feasibility Validator with Domain-Specific Weight Profiles
The default feasibility weight vector is domain-agnostic. For regulated verticals (healthcare, legal, finance), the “regulatory clarity” dimension should carry more weight; for real-time monitoring verticals, “latency tolerance” is more critical.
Implement a DomainWeightProfile that:
Takes the selected domain as input
Returns a domain-adjusted weight vector (must still sum to 1.0)
Passes a parametric test that confirms weight sums to 1.0 for all supported domains
Stores the weight profile used in the
CapstoneProjectManifestso the L91 scaffolding knows which feasibility model was applied
This directly builds toward L91: the development sprint will reference the manifest’s weight profile to determine which compliance components to scaffold by default.
Solution Hints
The weight vector must sum to 1.0 after domain adjustment. Use a normalization step: divide each adjusted weight by the sum of all adjusted weights.
Test with at least three domains: a regulated vertical (e.g., “healthcare”), a real-time vertical (e.g., “infrastructure monitoring”), and a general-purpose vertical (e.g., “customer support”).
The
manifest_hashmust be recomputed after weight profile injection, or your integrity check will fail.Gemini’s score output is a float in the model’s JSON — validate it against
[0.0, 1.0]with a Pydantic validator before passing it to the deterministic scorer to prevent injection of out-of-range values.
Looking Ahead
How This Enables L91–L93 The CapstoneProjectManifest is the single artifact that drives all three development lessons. L91 reads l91_bootstrap_instructions.topology to generate the project directory structure. L92 reads component_scaffold_targets to know which lesson exports to wire together. L93 reads acceptance_criteria to parameterize the final test suite.
Without a validated manifest from L90, the L91 scaffolding script cannot run. This is not a soft dependency — it is a hard boot-time check. This mirrors how production ML systems treat experiment configs: no config, no run.
Module Progress With L90 complete, Module 10 has delivered its first milestone: a validated, machine-readable project plan that bridges 89 lessons of component-building into a coherent final system. L91–L93 will be the proof: every component reference in the manifest is a link back to something you built, and the capstone is the sum of that work.
You have now scoped, designed, and defended a production VAIA system. Build it.