Framework y Blueprint

	Framework (el marco)	Blueprint (el plano)
Qué es	La estructura	Una unidad, definida por completo
De qué se compone	Carpetas, templates (plantillas), propiedades, vocabulary (vocabulario), roles	Un archivo markdown: propiedades arriba, cuerpo debajo
Dónde vive	.eidos/, oculto en la raíz	Una carpeta de colección
¿Portátil?	Sí: la pieza que un equipo le entrega a otro	No: es tu producto

El nombre

Eidos (εἶδος) es griego para el aspecto o la forma de una cosa: el patrón al que se ajusta. El Framework es la forma; un Blueprint es lo que la toma.

La raíz

La raíz es la carpeta donde vive todo. Puede llamarse como sea (Blueprints/ es el nombre por defecto) porque se encuentra por el .eidos/ oculto que hay dentro, nunca por su nombre. Varias raíces pueden convivir en un mismo repositorio.

• DirectorioBlueprints/ la raíz

  • README.md un documento de nivel superior: la puerta de entrada
  • Directorio.eidos/ el Framework

    • …
  • Directorioassets/ carpeta de assets: imágenes y documentos que enlazan los Blueprints

    • …
  • Directorioframes/ una colección: qué es el producto entero

    • architecture.md
  • Directoriospecs/ una colección, agrupada

    • Directorioplayback/ un grupo declarado; un nivel, nada más profundo

      • resume-playback.md un Blueprint por archivo
  • vision.md otro documento de nivel superior

Todo lo que hay en la raíz está declarado. Una carpeta es .eidos/ o está declarada bajo folders con quién la posee. owned_by: "@eidos/collections" es una colección (Blueprints, opcionalmente en grupos), y es el único tipo que el estándar posee; owned_by: "@<tool>/<kind>" es la carpeta de una herramienta (el identificador único de la herramienta, después su propio nombre para lo que contiene la carpeta), y qué contiene, cómo se nombra y qué se comprueba dentro lo dice esa herramienta; sin owned_by es una carpeta tuya, descrita y dejada en paz. Un archivo se lista bajo top_level. Cualquier otra cosa se muestra, y el dueño la declara o la mueve. Las entradas ocultas como .git están exentas.

Una carpeta es de su dueño. Las reglas del estándar sobre variants (variantes), agrupación, templates, índice y nombres llegan hasta @eidos/collections y no más allá. No se lee nada dentro de una carpeta que no posee. Una comprobación señala un dueño mal formado o un tipo @eidos/ que el estándar no nombra, y nunca el de una herramienta, conocida o no. Una herramienta reclama sus carpetas en su propia release; nadie inventa un dueño en su nombre.

El Framework

.eidos/ está oculto como lo están .git y .obsidian/: presente, fuera del camino, y cómodo junto a ellos en un vault.

• Directorio.eidos/

  • Framework.yaml el documento del Framework
  • Directoriotemplates/ un archivo por variant

    • spec.full.md
    • spec.micro.md
    • frame.architecture.md
  • Directorioroles/ cómo le habla un agente a cada tipo de persona

    • developer.md un archivo por tipo de persona
  • Directorioplugins/ una carpeta por herramienta

    • Directorioeidosmd/ la propia de la CLI

      • local.yaml ajustes locales (ignorado por git)
      • Directoriolocal/ archivos locales (ignorado por git)

        • …
  • me.md quién ocupa el asiento (local, ignorado por git)
  • .gitignore ignora me.md, plugins//local.yaml y plugins//local/

El nivel superior de .eidos/ es del estándar. Una herramienta guarda lo que necesita bajo plugins/<name>/ y no toca nada más. Plugins →

Framework.yaml

Uno por raíz: la estructura como datos, con comentarios donde quieras.

.eidos/Framework.yaml

eidos_version: 5.5.0
naming: kebab-case            # kebab-case | TitleCase | Title Case
top_level:                    # every file at the root
  - { title: README, path: ../README.md, description: the front door. }
folders:                      # every folder at the root, each with its owner
  - name: specs
    owned_by: "@eidos/collections"
    description: The product's units, one per blueprint, grouped by domain.
    variants:
      - { name: full, template: templates/spec.full.md, description: the complete spec, default: true }
      - { name: micro, template: templates/spec.micro.md, description: "Intent, Open Questions, ACs, Out of Scope" }
    grouping:
      label: Domains
      property: domain
      groups: []
  - { name: exports, owned_by: "@acme/exports", description: What the exporter writes; the exporter keeps it. }
  - { name: assets, description: Images and documents the blueprints link to. }
properties:
  core: []                    # the standard's four; rewritten by migrate
  custom:
    - { name: status, type: Text, applies_to: all, options: [Draft, Done], meaning: Lifecycle stage. }
    - { name: domain, type: Text, applies_to: [specs], required: true, meaning: The group. }
vocabulary: []                # the root's own terms
index: {}                     # generated by `eidos index`; never hand-edited

• top_level: cada archivo de la raíz, en el orden en que se leen. Un README, cuando la raíz lo tiene, se lista como cualquier otro.
• folders: cada carpeta de la raíz, con owned_by cuando algo la posee (entre comillas, ya que @ no puede empezar un valor YAML sin comillas). Una colección declara además sus variants (default: true en la que usa un Blueprint nuevo; sin ninguna marcada, no tiene predeterminada) y su agrupación, donde un grupo puede nombrar su propia predeterminada con default_variant.
• properties: el contrato de propiedades, un bloque por dueño: core (las del estándar), custom (las tuyas), tools.<tool> (las de una herramienta). Propiedades →
• vocabulary: las palabras con las que se describe el producto a propósito. Empieza vacío.
• index: los Blueprints de cada colección, cada uno con su id, title, summary, path y group. Reconstruido entero por eidos index, que no toca ninguna otra clave. Un Blueprint sin summary se lista sin él y se señala, nunca se inventa. La única vista derivada que define el estándar; cualquier otra vista es de una herramienta.

Regiones

Una herramienta que guarda algo dentro de un archivo markdown lo escribe en una región: un tramo entre dos comentarios HTML que llevan el nombre de la herramienta, cada uno solo en su línea.

<!-- eidosmd:backlinks -->
- [Session Management](../identity/session-management.md)
<!-- /eidosmd:backlinks -->

Dentro es de la herramienta, reescrito entero; fuera es de la persona. El estándar no lee nada de ello, y una comprobación señala solo una apertura sin cierre. El navegador muestra una región tal cual, etiquetada, en lugar de renderizarla.

Por qué importa la separación

El Framework es la pieza que viaja. Tus Blueprints son tu producto e inútiles para cualquier otro. Un Framework es forma sin contenido, y es exactamente lo que un equipo le entrega a otro para que ambos escriban igual. Eso es una semilla: un Framework sin nada dentro. Un Framework, cualquier número de raíces.

También fija la regla que más sorprende: la raíz posee su Framework. Una herramienta lee el Framework de la raíz en la que está, nunca de una copia propia. No hay configuración global, y nada tiene una idea fija de cómo se llaman tus colecciones.

En la CLI: eidos framework imprime todo esto, leído de tu propio .eidos/.

Siguiente

• Colecciones y Blueprints
• Dar forma a tu Framework