OSSFIA User Guide

OSSFIA User Guide — Guia Completa de Uso

Version: 1.0.0 | Marzo 2026 Framework: AI Software Factory OS v7.7 Dashboard: panel.ossfia.ai Reemplaza: Quick_Start_15min_Guide.md (v6.5), Happy_Path_Walkthrough_Guide.md (v6.5)

1. Que es OSSFIA (2 min de lectura)

AI Software Factory OS (OSSFIA) es un sistema operativo para fabricas de software dirigidas por agentes autonomos. No es una libreria, no es un IDE, no es un SaaS. Es una metodologia + enforcement + metricas + agents empaquetados como un repositorio Git que se consume como subtree en tu proyecto.

La unidad fundamental de ejecucion es el FAB (Fullstack Agent Builder): una celula autonoma de N agentes especializados (arquitecto, builder, QA, security, ops) que ejecutan el ADLC (Agentic Development Life Cycle) — un lifecycle de 10 fases (F01-F10) que reemplaza al SDLC tradicional.

Inventario del framework

Categoria	Cantidad	Ubicacion
Scripts (enforcement + Factory OS)	33	`scripts/`
Guias operacionales	55	`framework/guides/`
Skills para AI agents	31	`project-template/.claude/skills/`
Agents especializados	15	`project-template/.claude/agents/`
Rules (guardrails)	9	`project-template/.claude/rules/`
JSON Schemas de validacion	53	`scripts/schemas/`
Output contracts	9	`framework/contracts/`
Templates YAML por fase	65	`project-template/project/`
Tests automatizados	229	`tests/`

Las 5 capas de arquitectura

CAPA 5: OPERATIONS    — observar, medir, aprender (DORA, HANDOFF, DISCOVERIES)
CAPA 4: CONTROL       — gobernar, limitar, aprobar (rules, gates, kill-switch, cost-guard)
CAPA 3: EXECUTION     — hacer, conectar, producir (scripts, MCP, CI/CD, worktrees)
CAPA 2: KNOWLEDGE     — saber que hacer y como (guides, skills, agents, specs)
CAPA 1: COGNITION     — decidir, planificar, priorizar (ADLC, FAB orchestrator, intents)

Cada capa se apoya en la anterior. Los agents (Capa 2) usan los scripts (Capa 3) bajo las restricciones de las rules (Capa 4), y todo se mide en Capa 5.

2. Quick Start (15 min)

2.1 Crear proyecto greenfield

git clone https://github.com/aforero22/baseline.git
cd baseline
./scripts/init-project.sh "Mi App" "mi-app" ~/projects

Esto genera en ~/projects/mi-app/:

mi-app/
  baseline/              # Submodule read-only (este framework)
  project/               # Tus artefactos YAML por fase (EDITAR AQUI)
    project-config.yaml  # Config central: track, stack, fase actual
    F01_strategy/        # Templates de estrategia
    F02_domain/          # Templates de dominio
    ...                  # F03 a F10
  .claude/               # Context layers para AI assistants
    rules/               # 9 guardrails automaticos
    skills/              # 31 skills por fase y dominio
    agents/              # 15 agents especializados
    settings.json        # Hooks y permisos
  intent/                # Intent documents para FAB headless
  CLAUDE.md              # Instrucciones para AI assistants
  AGENTS.md              # 7 Golden Principles + context routing
  HANDOFF.md             # Continuidad entre sesiones
  DISCOVERIES.md         # Conocimiento acumulado
  progress-tracker.md    # Tracking de progreso FAB
  .fab-config.yaml       # Config FAB (budget, modo, notificaciones)

2.2 Adopcion brownfield (proyecto existente)

cd mi-proyecto-existente
bash /ruta/a/baseline/scripts/init-brownfield.sh "Mi Proyecto" "mi-proyecto"

El script brownfield es aditivo: agrega baseline/, .claude/, project/, AGENTS.md y CLAUDE.md sin modificar tu codigo existente. Marca brownfield: true en project-config.yaml.

Para adopcion gradual, consultar el skill /brownfield_adoption o la guia Brownfield_Adoption_Guide.md.

2.3 Verificar instalacion

# Verificar compliance general
python3 baseline/scripts/compliance-linter.py -d project -t solo

# Verificar spec-first
python3 baseline/scripts/spec-first-check.py --project-dir . --track solo

# Verificar gates
bash baseline/scripts/gate-check.sh solo all

Si los 3 comandos ejecutan sin errores criticos, la instalacion esta correcta.

2.4 Actualizar el framework

cd mi-proyecto/baseline
git pull origin main
cd ..
git add baseline
git commit -m "chore: update framework to latest"

3. El Ciclo de Desarrollo (ADLC)

El ADLC tiene 10 fases secuenciales. Cada fase produce artefactos YAML que sirven de contexto para la siguiente. Los gates validan que los artefactos esten completos antes de avanzar.

Tabla maestra del ADLC

Fase	Nombre	Skill	Agent principal	Artefactos clave	Gate
F01	Strategy & Problem Framing	`/f01_strategy`	product_manager	problem_statement, scope, risk_register	A
F02	Domain & Capability Discovery	`/f02_domain`	architect	capability_map, event_storming, glosario	B
F03	Context & Knowledge Design	`/f03_knowledge`	architect	knowledge_map, source_inventory, trust_model	-
F04	AI/Deterministic Architecture	`/f04_architecture`	architect	architecture_blueprint, ADRs, component_map	C
F05	Data, Knowledge & Contracts	`/f05_contracts`	spec_writer	OpenAPI specs, data_dictionary, ERD	D
F06	AI-Assisted Build	`/f06_build`	builder	Codigo, tests, build artifacts	-
F07	Continuous TEVV	`/f07_tevv`	qa_engineer	eval_scorecards, test_evidence	E
F08	Security, Compliance & Governance	`/f08_security`	security_reviewer	compliance_matrix, AIBOM, security_review	-
F09	Deploy, Operate & GenOps	`/f09_operations`	devops_engineer	runbooks, dashboards, SLO_baseline	F
F10	Learn & Evolve	`/f10_evolution`	team_lead	improvement_backlog, evolution_plan	-

Flujo de ejecucion

F01 --> F02 --> F03 --> F04 --> F05 --> F06 --> F07 --> F08 --> F09 --> F10
 A       B                      C       D               E               F

Las letras (A-F) son los gates formales. En track Solo, los gates son self-assessment. En track Full, requieren aprobacion humana.

Sprint Pipeline (resumen operativo)

Para el dia a dia dentro de una fase, el ciclo es:

Think --> Plan --> Build --> Review --> Test --> Ship --> Reflect

Usar el skill /sprint_pipeline para el flujo detallado.

4. Spec-First: La Regla de Oro

No se escribe una linea de codigo sin un SPEC que valide la logica de negocio.

El ciclo spec-first

Natural Language (requerimiento)
  --> Validar logica de negocio (tiene sentido?)
    --> SPEC (contrato formal en .openspec/)
      --> Validar SPEC (schema correcto?)
        --> ENTONCES codigo

4 niveles de enforcement

Nivel	Mecanismo	Donde
1. Agent	El builder hace STOP si no encuentra spec en `.openspec/`	Runtime
2. Pre-commit	Hook verifica que todo codigo nuevo tenga spec asociado	Local
3. Linter	`spec-first-check.py` valida correspondencia spec-codigo	CI/Local
4. CI	Gate en pipeline bloquea PRs sin spec	GitHub Actions

Como generar un spec

Invocar el skill /spec_workflow que guia el proceso:

Fase 0: Validar logica de negocio (el requerimiento tiene sentido?)
/specify — Crear el spec formal en .openspec/
/plan — Generar plan de implementacion
/tasks — Descomponer en tareas ejecutables
/implement — Codear contra el spec

Excepciones: .specignore

Para spikes, exploraciones y prototipos que no requieren spec formal:

# .specignore — archivos/directorios exentos de spec-first
scripts/playground/
experiments/
*.spike.ts

5. Skills Disponibles (31)

Los skills se invocan como /nombre_skill en tu agente AI. Cada skill carga instrucciones metodologicas contextuales.

Lifecycle (ADLC F01-F10)

Skill	Fase	Para que
`f01_strategy`	F01	Definir problema, business case, scope, riesgos
`f02_domain`	F02	Modelar dominio, bounded contexts, event storming
`f03_knowledge`	F03	Disenar fuentes, RAG strategy, trust model
`f04_architecture`	F04	Blueprint, ADRs, stack selection, agentic patterns
`f05_contracts`	F05	OpenAPI, data models, event schemas, prompt contracts
`f06_build`	F06	Coding standards, CI/CD, vibe coding practices
`f07_tevv`	F07	Testing, eval scorecards, golden datasets
`f08_security`	F08	OWASP ASI, SAST/SCA, MCP audit, compliance
`f09_operations`	F09	Deploy, SLOs, monitoring, DORA metrics
`f10_evolution`	F10	Improvement backlog, agent evolution, tech debt

Governance y Orquestacion

Skill	Para que
`fab_orchestrator`	Ejecutar ADLC completo como FAB autonomo
`spec_workflow`	Flujo specify/plan/tasks/implement
`sprint_pipeline`	Pipeline think/plan/build/review/test/ship/reflect
`code_review`	Review estructurado con checklist de seguridad y calidad
`security_audit`	Orquestar SAST/SCA + OWASP ASI + MCP audit en una pasada
`eval_workflow`	Crear y ejecutar evaluation suites
`dora_metrics`	Medir DORA + SPACE + DX AI metrics
`agent_teams`	Orquestar multi-agent con Claude Code Agent Teams

Dominio Especifico

Skill	Para que
`database_design`	Schema, migraciones, indexing, data modeling
`rag_pipeline`	Vector DB, chunking, embeddings, reranking, semantic cache
`mcp_setup`	Configurar MCP servers y seguridad
`monitoring_setup`	Dashboards, alertas, logging estructurado, tracing
`cost_management`	Budget tracking, model routing, cost attribution
`performance_analysis`	Latencia, caching, load testing, optimization
`deployment`	CI/CD, canary, rollback, feature flags
`documentation`	Runbooks, architecture docs, API docs, onboarding

Setup y Adopcion

Skill	Para que
`onboarding`	Onboarding de nuevos miembros del equipo
`brownfield_adoption`	Adoptar framework en proyecto existente
`browser_testing`	Testing con browser automation
`design_system`	Design system y componentes UI

6. Agents Disponibles (15)

Los agents se invocan como @nombre_agent. Cada uno tiene un rol, expertise y boundaries definidos.

Agent	Rol	Cuando usarlo
`architect`	Disenar arquitectura, ADRs, stack selection	F04, decisiones de diseno
`builder`	Implementar codigo siguiendo specs	F06, cualquier tarea de coding
`code_reviewer`	Revisar PRs con checklist de calidad	Pre-merge, revisiones de codigo
`data_steward`	Clasificacion de datos, governance, provenance	F03, F05, cualquier pipeline de datos
`database_architect`	Schema design, migraciones, indexing	F05, F06 (data layer)
`devops_engineer`	CI/CD, deploy, infraestructura	F09, pipelines, monitoring
`finops`	Control de costos AI, budgets, routing	F09, optimizacion de costos
`ml_ops_engineer`	MLOps, model versioning, feature stores	F06-F09 con modelos ML
`performance_engineer`	Latencia, caching, load testing	F07, F09 (optimizacion)
`product_manager`	Strategy, specs, acceptance criteria	F01, F02, definicion de producto
`qa_engineer`	Testing, evals, golden datasets	F07, quality assurance
`security_reviewer`	Security review, threat modeling, compliance	F08, auditorias de seguridad
`spec_writer`	Escribir specs formales, OpenAPI, schemas	F05, contratos y specs
`team_lead`	Coordinacion, gates, prioridades	Cross-fase, orchestracion
`technical_writer`	Documentacion, runbooks, guias	F09, F10, documentacion

7. Scripts de Enforcement (Top 10)

7.1 compliance-linter.py — Verificar compliance general

Valida 15+ reglas de compliance incluyendo artefactos requeridos, data governance, specs, y seguridad.

python3 baseline/scripts/compliance-linter.py -d project -t <track>
# Tracks: solo, lean, full
# Output: score 0-100, lista de findings por severidad

7.2 spec-first-check.py — Verificar spec-first

Valida que todo codigo nuevo tenga un spec correspondiente en .openspec/.

python3 baseline/scripts/spec-first-check.py --project-dir . --track <track>
# Severidad: CRITICAL (lean/full), WARNING (solo)

7.3 fab-gate-check.py — Verificar gates autonomos

Evalua si el proyecto cumple los criterios de un gate con confidence scoring.

python3 baseline/scripts/fab-gate-check.py --gate A --project-dir project
# Output: pass/fail con confidence score y arbol de decision

7.4 sast-sca-scanner.py — Security scan estatico

SAST/SCA agnostico de lenguaje. Integra Semgrep, npm audit, pip-audit, govulncheck.

python3 baseline/scripts/sast-sca-scanner.py --project-dir . --output-format json

7.5 owasp-asi-checker.py — OWASP Agentic Security

Verifica cumplimiento de los 10 controles OWASP ASI (Agentic Security Initiative).

python3 baseline/scripts/owasp-asi-checker.py --project-dir . --config project/F08_security/

7.6 mcp-security-audit.py — Auditoria de seguridad MCP

Audita servidores MCP: trust de fuente, autenticacion, transporte, CVEs dinamicos.

python3 baseline/scripts/mcp-security-audit.py --config .claude/mcp_config.json

7.7 dora-metrics.py — Metricas de productividad

Calcula DORA + SPACE + DX AI metrics desde el historial git con atribucion AI.

python3 baseline/scripts/dora-metrics.py --repo-dir . --period 30d

7.8 sbom-generator.py — Software Bill of Materials

Genera SBOM en formato CycloneDX 1.5 o SPDX 3.0 con verificacion de licencias y firma.

python3 baseline/scripts/sbom-generator.py --project-dir . --format cyclonedx --sign

7.9 aibom-generator.py — AI Bill of Materials

Genera inventario de componentes AI del proyecto (modelos, embeddings, prompts, MCP servers).

python3 baseline/scripts/aibom-generator.py --project-dir . --sign

7.10 fab-cost-guard.py — Control de costos

Circuit breakers para costos AI: estados green/yellow/red/critical con senales automaticas.

python3 baseline/scripts/fab-cost-guard.py --config .fab-config.yaml --check
# Output: estado actual del circuit breaker + recomendaciones

8. Tracks: Solo, Lean, Full

No todos los proyectos necesitan las 10 fases completas. OSSFIA define 3 tracks adaptativos.

Tabla comparativa

Aspecto	Solo	Lean	Full
Equipo	1 persona + agents	1-3 personas	3+ personas
Duracion	1-7 dias	2-4 semanas	6-20 semanas
Fases	Flow continuo (3 macro)	3 macro-fases	10 fases completas
Gates	Self-assessment	Gates ligeros	Gates formales (A-F)
Branching	Trunk-based	main + develop + PRs	main + develop + release + merge queue
Ceremony	Minima	Code review en PRs	Review + gates + compliance
Agents	builder + architect	+ code_reviewer, qa	Todos los 15
Deploy	Manual o script	CI/CD basico	CI/CD + canary + rollback
Contexto	MVP, prototipo	Startup, SaaS	Enterprise, regulado
Adopcion AI	Nivel 1-8	Nivel 3-6	Nivel 1-5
Datos	public/internal	public/internal	Todos (incl. restricted)

Cuando usar cada uno

Solo: un developer construyendo un MVP o prototipo en menos de 1 semana. Usa agents como multiplier.
Lean: startup o SaaS con equipo compacto (1-3) donde time-to-market importa mas que ceremony.
Full: sistema regulado (salud, finanzas, gobierno), multiples bounded contexts, datos sensibles.

El track se define en project/project-config.yaml al crear el proyecto y afecta que artefactos son obligatorios, que gates aplican, y que nivel de ceremony se espera.

9. GlassPlane Dashboard (panel.ossfia.ai)

GlassPlane es el dashboard visual de compliance para proyectos OSSFIA.

Como conectar un repositorio

Ir a panel.ossfia.ai
Autenticar con GitHub
Seleccionar el repositorio que tiene baseline/ como subtree
El dashboard lee automaticamente los artefactos en project/

Que muestra

Dimension	Que mide
Compliance Score	Score 0-100 agregado de todas las dimensiones
Spec Coverage	Porcentaje de codigo con spec correspondiente
Gate Status	Estado de cada gate (A-F) por track
Security Posture	Findings SAST/SCA + OWASP ASI + MCP
Data Governance	Clasificacion de datos, provenance, PII
DORA Metrics	Deployment frequency, lead time, MTTR, CFR
Cost Health	Estado del circuit breaker, burn rate
Test Coverage	Cobertura de tests + eval scores
AIBOM/SBOM	Inventario de componentes AI y software
Trend Charts	Evolucion temporal de cada dimension
AI Advisor	Recomendaciones automaticas basadas en gaps

10. Arquitectura de Referencia (Cloudflare)

OSSFIA incluye una arquitectura de referencia completa para despliegue en Cloudflare Workers:

Request --> Worker (API) --> AI Gateway --> Workers AI --> Response
                |                              |
                v                              v
           D1 / KV / R2                  Vectorize (RAG)

El patron AI Gateway centraliza: rate limiting, cost tracking, caching, model routing, fallback, y observabilidad para todas las llamadas a modelos AI.

Para la guia completa: framework/guides/Cloudflare_AI_Gateway_Architecture_Guide.md

11. Governance y Compliance

OSSFIA implementa compliance automatizado para los siguientes marcos regulatorios:

Framework	Cobertura	Script
EU AI Act	Preparado para Agosto 2026. Clasificacion de riesgo, documentacion tecnica, human oversight	`compliance-linter.py`
ISO 42001	33 controles del Annex A verificados automaticamente	`iso42001-annex-check.py`, `iso42001-evidence-collector.py`
OWASP ASI	10 controles de seguridad agentica (ASI01-ASI10)	`owasp-asi-checker.py`
OWASP LLM Top 10	Top 10 vulnerabilidades LLM integradas	`sast-sca-scanner.py`
OWASP MCP	Seguridad de servidores MCP	`mcp-security-audit.py`
NIST AI RMF	Gestion de riesgos AI, trazabilidad	`compliance-linter.py`
SOC 2 Type II	Recoleccion de evidencia automatizada	`soc2-evidence-collector.py`
Singapore MGF	Model Governance Framework para AI agentica	`compliance-linter.py`

Todas las verificaciones se ejecutan en CI via GitHub Actions (security-scan.yml) y se reportan en el GlassPlane Dashboard.

12. Troubleshooting

El compliance linter falla con “project-config.yaml not found”

# Verificar que existe
ls project/project-config.yaml
# Si no existe, regenerar desde template
cp baseline/project-template/project/project-config.yaml project/
# Editar con los valores de tu proyecto

spec-first-check falla con “no specs found”

# Crear directorio de specs si no existe
mkdir -p project/F05_contracts/.openspec/
# O crear .specignore para exentar archivos de exploracion
echo "scripts/playground/" > .specignore

Los tests no pasan en Windows

Algunos scripts bash no son compatibles con Windows nativo. Opciones:

Correr solo tests Python-pure: python3 tests/test_framework.py -k "not bash"
Usar WSL2: wsl bash baseline/scripts/gate-check.sh solo all
Usar Git Bash (incluido con Git for Windows)

Gate fails con “missing artifacts”

# Ver detalle de que falta
bash baseline/scripts/gate-check.sh <track> all --verbose
# El output lista cada artefacto faltante con su ruta esperada

El context router no mapea mi tarea

# Verificar que el router reconoce la tarea
python3 baseline/scripts/context-router.py "descripcion de mi tarea"
# Si no encuentra match, puede que la tarea sea demasiado vaga
# Usar terminos del ADLC: "architecture", "security", "testing", etc.

FAB se queda bloqueado (headless)

# Verificar si hay signal de stop
cat .fab-signal  # Si dice STOP_REQUESTED, el FAB hizo checkpoint y salio

# Revisar estado
cat progress-tracker.md  # Ultima fase completada
cat HANDOFF.md           # Estado al ultimo checkpoint

# Relanzar desde donde se quedo
# El FAB lee HANDOFF.md y continua

Costos fuera de control

# Verificar estado del circuit breaker
python3 baseline/scripts/fab-cost-guard.py --config .fab-config.yaml --check

# Si esta en red/critical, el FAB se pausa automaticamente
# Ajustar budgets en .fab-config.yaml y relanzar

13. Recursos

Repositorio y Dashboard

GitHub: github.com/aforero22/baseline
Dashboard: panel.ossfia.ai

Guias esenciales (empezar por estas)

Guia	Ruta	Cuando leerla
Framework Architecture (5 capas)	`framework/guides/Framework_Architecture_Guide.md`	Para entender como encaja todo
Spec-First Enforcement	`framework/guides/Spec_First_Enforcement_Guide.md`	Antes de escribir codigo
Context Engineering	`framework/guides/Context_Engineering_Guide.md`	Para optimizar la interaccion con agents
Framework Enforcement	`framework/guides/Framework_Enforcement_Guide.md`	Para entender que scripts correr
Brownfield Adoption	`framework/guides/Brownfield_Adoption_Guide.md`	Si adoptas en proyecto existente

Guias de seguridad y compliance

Guia	Ruta
OWASP Agentic Security	`framework/guides/OWASP_Agentic_Security_Guide.md`
Data Governance AI	`framework/guides/Data_Governance_AI_Guide.md`
EU AI Act Conformity	`framework/guides/EU_AI_Act_Conformity_Guide.md`
ISO 42001 Alignment	`framework/guides/ISO_42001_Alignment_Guide.md`
SOC 2 AI Controls	`framework/guides/SOC2_AI_Controls_Guide.md`

Guias operacionales

Guia	Ruta
FAB Intake & Headless	`framework/guides/FAB_Intake_Headless_Workspace_Guide.md`
Agentic Workforce & Factory	`framework/guides/Agentic_Workforce_Factory_Operations_Guide.md`
Multi-Agent Orchestration	`framework/guides/Multi_Agent_Orchestration_Guide.md`
Evals Framework	`framework/guides/Evals_Framework_Guide.md`
Observability & FinOps	`framework/guides/Observability_FinOps_Implementation_Guide.md`
MCP Integration	`framework/guides/MCP_Integration_Guide.md`
Vibe Coding Practices	`framework/guides/Vibe_Coding_Practices_Guide.md`

Documentos fundacionales

Documento	Ruta
Framework Overview	`framework/core/F00_Foundation/CORE_F00_Framework_Overview.md`
Lifecycle 10 Fases (ADLC)	`framework/core/F00_Foundation/CORE_F00_Lifecycle_10_Fases.md`
Multi-Track Execution	`framework/core/F00_Foundation/CORE_F00_Multi_Track_Execution.md`
Roles, RACI & Gates	`framework/core/F00_Foundation/CORE_F00_Roles_RACI_Gates.md`
Manifesto	`framework/core/F00_Foundation/CORE_F00_Manifiesto_Principios_Universales.md`

Apendice: Flujo Rapido para Impacientes

Si solo tienes 5 minutos y quieres empezar a construir:

# 1. Clonar e inicializar
git clone https://github.com/aforero22/baseline.git
cd baseline && ./scripts/init-project.sh "Mi App" "mi-app" ~/projects
cd ~/projects/mi-app

# 2. Definir que vas a construir
# Editar: project/F01_strategy/problem_statement.yaml

# 3. Crear spec antes de codear
# Invocar: /spec_workflow en tu agente AI

# 4. Construir
# Invocar: /f06_build en tu agente AI

# 5. Verificar
python3 baseline/scripts/compliance-linter.py -d project -t solo

Eso es todo. El framework te guia desde ahi.