Happy Path Walkthrough

Happy Path: Creating an App with the Framework

Version: 6.5 | Date: Mar 2026 | Status: ACTIVE

Step-by-step walkthrough of creating an application from scratch using the AI-First Engineering Framework.

---

Prerequisites

• Git installed
• Python 3.10+ installed
• Baseline repo cloned: git clone https://github.com/aforero22/baseline.git
• (Optional) pip install jsonschema pyyaml for artifact validation

---

Step 1: Create Your Project (5 min)

# From the baseline directory
cd baseline
bash scripts/init-project.sh "Mi App SaaS" "mi-app-saas" ~/projects

# Go to your new project
cd ~/projects/mi-app-saas

What just happened:

• Created project directory with all F01-F10 phase folders
• Linked baseline as a git submodule (read-only reference)
• Copied .claude/ context layers (agents, skills, rules, hooks)
• Created AGENTS.md (constitutional document with 7 Golden Principles)
• Created data_classification.yaml and data_provenance_registry.yaml
• Configured MCP server in .claude/mcp_config.json
• Installed pre-commit hook (secret scanning, YAML validation, compliance)
• Made initial git commit

Verify:

python3 baseline/scripts/compliance-linter.py -d project -t solo
# Expected: WARN with low score — we haven't filled anything yet

---

Step 2: Strategy & Problem Framing — F01 (30 min)

2a. Configure your project

Edit project/project-config.yaml:

project:
  name: "Mi App SaaS"
  codename: "mi-app-saas"
  version: "0.1.0"
  status: "discovery"
  started: "2026-03-20"
  description: "AI-powered customer support platform"

track: "solo"   # or "lean" or "full"

sizing:
  bounded_contexts: 2
  estimated_endpoints: 15
  ai_components: "basic"
  ai_assist_level: "heavy"
  regulation_level: "medium"

2b. Define your problem

Edit project/F01_strategy/problem_statement.yaml:

problem:
  name: "Customer Support Overload"
  context: "Small SaaS company receiving 200+ support tickets daily..."
  current_pain:
    - "Response time >24 hours"
    - "Repetitive questions consume 60% of agent time"
  actors_affected:
    - "Support agents"
    - "Customers"
    - "Product team"
  impact:
    operational: "Support team burned out"
    financial: "$8k/month in overtime"
    experience: "NPS dropping from 45 to 32"
    risk: "Customer churn increasing 5% MoM"
  target_outcome: "Reduce response time to <2 hours with AI-assisted responses"

2c. (Lean/Full) Define human-agent responsibilities

If you’re on lean or full track, edit project/F01_strategy/human_agent_responsibility.yaml:

human_agent_responsibility:
  version: "1.0"
  autonomy_levels:
    - id: "L0_human_only"
      name: "Solo Humano"
    - id: "L2_agent_drafts"
      name: "Agente Ejecuta, Humano Revisa"
  responsibilities:
    - capability: "Generacion de codigo"
      phase: "F06"
      current_level: "L2_agent_drafts"
      escalation: "Codigo que toca auth, pagos, o datos sensibles"

2d. Validate

# Validate artifact schema
python3 baseline/scripts/artifact-validator.py -d project -f project-config.yaml
python3 baseline/scripts/artifact-validator.py -d project -f F01_strategy/problem_statement.yaml

# Check Gate A
bash baseline/scripts/gate-check.sh solo a

2d. Commit

git add . && git commit -m "feat(F01): problem statement and project config"

---

Step 3: Domain Discovery — F02 (30 min)

3a. Define capabilities

Edit project/F02_domain/capability_map.yaml:

capabilities:
  - id: "CAP-001"
    name: "AI Response Suggestions"
    description: "Generate suggested responses for support tickets"
    priority: "must"
    bounded_context: "BC-001"
    ai_fit: "ai-complex"
    dependencies: []
  - id: "CAP-002"
    name: "Ticket Classification"
    description: "Auto-classify incoming tickets by category and priority"
    priority: "must"
    bounded_context: "BC-001"
    ai_fit: "ai-simple"
    dependencies: []
  - id: "CAP-003"
    name: "Knowledge Base Search"
    description: "Search internal docs to find relevant answers"
    priority: "must"
    bounded_context: "BC-002"
    ai_fit: "ai-complex"
    dependencies: ["CAP-001"]

3b. Commit

git add . && git commit -m "feat(F02): capability map with 3 core capabilities"

---

Step 4: Data Governance — Early! (20 min)

GP-02: Classify Before You Flow — do this BEFORE building anything with data.

4a. Classify your data

Edit project/data_classification.yaml — add your entities:

data_classification:
  levels:
    # ... (5 levels already templated) ...
  entities:
    - entity: "support_ticket"
      overall_classification: "internal"
      fields:
        - name: "id"
          classification: "internal"
        - name: "subject"
          classification: "internal"
        - name: "body"
          classification: "confidential"
        - name: "customer_email"
          classification: "restricted"
          pii: true
          gdpr_basis: "legitimate_interest"
        - name: "customer_name"
          classification: "restricted"
          pii: true

4b. Register data sources

Edit project/data_provenance_registry.yaml:

provenance_registry:
  version: "1.0"
  last_updated: "2026-03-20"
  owner: "you"
  sources:
    - id: "SRC-001"
      name: "Zendesk Tickets"
      type: "operational"
      classification: "confidential"
      collection_method: "API export"
      license: "internal_proprietary"
      used_in: ["RAG knowledge base", "ticket classification"]
    - id: "SRC-002"
      name: "Internal Knowledge Base"
      classification: "internal"
      license: "internal_proprietary"
      used_in: ["RAG corpus"]

4c. Use MCP to verify classification

python3 baseline/scripts/framework-mcp-server.py classify customer_email
# Expected: RESTRICTED — Mask with PIIGuard
python3 baseline/scripts/framework-mcp-server.py classify ticket_subject
# Expected: PUBLIC or INTERNAL

4d. Commit

git add . && git commit -m "feat(DG): data classification and provenance registry"

---

Step 5: Architecture — F04 (30 min)

5a. Create ADR for stack selection

Create project/F04_architecture/adr_001_stack_selection.md:

# ADR-001: Stack Selection

## Status
Accepted

## Context
Building AI-powered customer support with solo track, heavy AI assist.

## Decision
- Backend: Python 3.12 + FastAPI
- Database: PostgreSQL 15 + pgvector
- AI: Claude Sonnet 4.5 (complex) + Haiku 3.5 (fast)
- Embeddings: text-embedding-3-small
- Observability: Langfuse (free tier)
- Deployment: Railway

## Consequences
- Python ecosystem: rich AI/ML libraries
- pgvector: single DB for both data and embeddings
- Claude: best reasoning for support responses

5b. (Lean/Full) Create AI cost model

If you’re on lean or full track, edit project/F04_architecture/ai_cost_model.yaml:

ai_cost_model:
  version: "1.0"
  models:
    - id: "primary"
      provider: "anthropic"
      model: "claude-sonnet-4-5"
      use_case: "AI-assisted support responses"
      input_cost_per_1m: 3.0
      output_cost_per_1m: 15.0
      estimated_daily_requests: 200
  budget:
    monthly_total_usd: 100.0
  alerts:
    warning_threshold: 0.70
    critical_threshold: 0.90

5c. Gate C check

bash baseline/scripts/gate-check.sh solo c

---

Step 6: Build — F06 (iterative)

6a. Use the Context Router to load relevant guides

python3 baseline/scripts/context-router.py "build a RAG pipeline with customer data"
# Shows exactly which guides, skills, and rules to read

6b. Follow GP-01: Spec-First

Before writing any code, create your data dictionary:

project/F05_contracts/data_dictionary.yaml

entities:
  - entity: "support_ticket"
    bounded_context: "BC-001"
    fields:
      - name: "id"
        type: "uuid"
        sensitivity: "internal"
      - name: "customer_email"
        type: "string"
        sensitivity: "pii"
        validation_rules: "valid email format"

6c. Build incrementally, validate continuously

# After each significant change:
python3 baseline/scripts/compliance-linter.py -d project -t solo --save-metrics project/compliance_history.json
git add . && git commit -m "feat(F06): implement ticket classification endpoint"

---

Step 7: Test & Eval — F07 (30 min)

# Create eval baseline
# project/F07_tevv/ai_evaluation_scorecard.yaml
agents:
  - agent_id: "ticket-classifier"
    dataset_size: 100
    metrics:
      precision: 0.92
      recall: 0.88
      faithfulness: 0.95
      hallucination_rate: 0.03
      latency_p95_ms: 450
    quality_gate_passed: true

---

Step 8: Security & Compliance — F08 (20 min)

# Compliance check
python3 baseline/scripts/compliance-linter.py -d project -t solo --strict
# Gate F
bash baseline/scripts/gate-check.sh solo f

---

Step 9: Deploy & Operate — F09

# Full compliance scan before deploy
python3 baseline/scripts/compliance-linter.py -d project -t solo --strict --save-metrics project/compliance_history.json
# All gates
bash baseline/scripts/gate-check.sh solo all

---

Continuous: Check Compliance Trend

# View metrics history
cat project/compliance_history.json | python3 -c "
import sys, json
data = json.load(sys.stdin)
print(f\"Entries: {len(data['history'])}\")
print(f\"Latest: {data['latest']['score']:.0f}% ({data['latest']['verdict']})\")
print(f\"Trend: {data['trend']['direction']} ({data['trend']['change']:+.1f}%)\")
"

---

Quick Reference: Key Commands

Command	When to use
bash baseline/scripts/init-project.sh "Name" "code" [dir]	Start a new project
python3 baseline/scripts/compliance-linter.py -d project -t solo	Check compliance
python3 baseline/scripts/artifact-validator.py -d project	Validate YAML artifacts
python3 baseline/scripts/framework-mcp-server.py classify <field>	Classify data
python3 baseline/scripts/framework-mcp-server.py principles	View golden principles
python3 baseline/scripts/framework-mcp-server.py route "task"	Get context for a task
bash baseline/scripts/gate-check.sh solo all	Check all gates

---

Quick Reference: Golden Principles

#	Principle	What it means
GP-01	Spec-First, Code-Second	Contract before code
GP-02	Classify Before You Flow	Data classification before AI pipelines
GP-03	Provenance or Rejection	Register all AI data sources
GP-04	Test Before Commit	Tests pass before merge
GP-05	ADR for Irreversible	Document big decisions
GP-06	Human-in-the-Loop	Human approval for high-impact
GP-07	Audit Trail	Log AI decision rationale

---

Last updated: March 2026 — Framework v6.4