Skip to content

Commit d85d840

Browse files
montfortclaude
montfort
and
claude
authored
docs: adopter Loom guide + recommended architecture-model workflow (#280) (#284)
Loom had only dev-facing docs (experimento/README.md) and command-by-command CLI-REFERENCE entries — no adopter-facing page and no narrated workflow. Add `docs/adopters/LOOM.md` (EN + es + zh-CN, auto-listed in the website sidebar): - What Loom is (two surfaces, EXPERIMENTAL framing). - The BIM "one model, many views" mental model: one model.yml + plan.drawio, three projections (status --where, 2D plan, 3D axonometric), live overlay. - The recommended workflow generate → refine → validate → sync → serve, with the **refinement phase made explicit** and shown as human OR AI-assisted. - Honest seed limitations (it's a draft; non-default stacks need config + hand-refinement; has-debt precision). Cross-linked from WORKFLOWS.md ("Seeing the project") in all three locales. Docs-only; no version bump. Redeploys via deploy-website.yml on merge. Closes #280. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent e8ad89f commit d85d840

6 files changed

Lines changed: 387 additions & 0 deletions

File tree

‎docs/adopters/LOOM.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# StrayMark — Loom & the Architecture Map (Experimental)
2+
3+
**See your project: the document web, and the "you are here" map of where the work is happening.**
4+
5+
[![Strange Days Tech](https://img.shields.io/badge/by-Strange_Days_Tech-purple.svg)](https://strangedays.tech)
6+
7+
> ⚠️ **EXPERIMENTAL — Loom v0 (N=1).** Loom is an opt-in, unstable experiment. Its API, CLI surface, on-disk model format, and very existence may change or be removed without a deprecation cycle until it graduates. It is **not** part of the supported Framework or CLI contract — don't build automation against it yet. The `architecture` model and `status --where` ship in the CLI but carry the same experimental caveat.
8+
9+
---
10+
11+
## What Loom is
12+
13+
Loom is StrayMark's third component (alongside the Framework and the CLI): a loopback-only, read-only **development dashboard** that makes a StrayMark project legible to the human eye. It has two surfaces over the same project:
14+
15+
1. **Knowledge Graph** — the web of your StrayMark *documents*, rendered as a live force-directed graph from their frontmatter links (`related`, `originating_ailogs`, …). Select a node and its whole thread of relationships lights up. This view is self-explanatory and needs no setup.
16+
2. **Architecture Map** — the *system's* implementation map: components and layers (your real architecture), with a live **"you are here" status overlay** computed from governance state (active Charters, drift, closed work, open technical debt). It answers the daily *"where are we?"* visually. **This view is driven by a model you author + refine** — the rest of this guide is about that.
17+
18+
Loom never writes into your project — it only *visualizes* what the CLI computes. The CLI commands (`validate`, `audit`, `charter drift`) remain the source of truth and the gate.
19+
20+
---
21+
22+
## The mental model: one model, many views (BIM)
23+
24+
The Architecture Map borrows the **BIM "one model, many views"** idea. There is **one** model, expressed as two linked files under `.straymark/architecture/`:
25+
26+
| File | What it holds | Who owns it |
27+
|---|---|---|
28+
| `model.yml` | The **semantics** — components → file globs, layers, links | You (seeded by the CLI) |
29+
| `plan.drawio` | The **layout** — the boxes-and-arrows diagram (DrawIO/mxGraph) | You (seeded by the CLI) |
30+
31+
From that one model, StrayMark renders **three projections**, all from the *same* status computation so they can't disagree:
32+
33+
- **Textual** — `straymark status --where` (the terminal "you are here").
34+
- **2D plan** — Loom's Architecture tab (your `plan.drawio`, overlaid with live status).
35+
- **3D axonometric** — Loom's `2D | 3D` toggle (an exploded, BIM-style view).
36+
37+
The **status overlay is computed live, never hand-maintained.** You author *structure* (which files belong to which component, how components relate); StrayMark colors it (`active` / `in-progress` / `implemented` / `has-debt` / `uncharted`) from governance signals every time you look.
38+
39+
---
40+
41+
## The recommended workflow
42+
43+
```
44+
generate → refine (human or AI) → validate → sync (as code grows) → loom serve
45+
draft the real model CI gate append-only visualize
46+
```
47+
48+
### 1. Generate — a first-draft seed
49+
50+
```bash
51+
straymark architecture generate
52+
```
53+
54+
Mines your codebase structure (one component per source directory) and enriches it from your ADRs (C4 diagrams + "Affected Components" tables improve labels and add links). It writes `model.yml` + `plan.drawio` with every component in a placeholder `unassigned` layer and the `.straymark` stages 00–09 as placeholder layers.
55+
56+
The seed is **language- and structure-aware** (it descends through `internal/`, `src/`, `pkg/`, … and skips Maven/Gradle scaffolding so a Java module isn't one `main` box). For non-default stacks you can extend it with an `architecture:` section in `.straymark/config.yml` — see [CLI-REFERENCE](./CLI-REFERENCE.md#straymark-architecture-generatesyncvalidate-cli-3250-experimental).
57+
58+
**The seed is a draft, not the answer.** It captures the shape; you make it meaningful in the next step.
59+
60+
### 2. Refine — the phase that matters (human *or* AI)
61+
62+
This is where a generated map becomes a real one. `model.yml` is plain YAML and `plan.drawio` is a standard DrawIO file, so refinement can be done **by a person, by an AI agent, or both**:
63+
64+
- **Rename the layers** from the placeholder stages to your real architecture (e.g. `entrypoints`, `domain`, `persistence`, `web`).
65+
- **Reassign components** out of `unassigned` into those layers.
66+
- **Fix labels** to human names (`internal-modules-commshub` → "CommsHub").
67+
- **Tighten globs** so each component owns exactly its files.
68+
- **Add `links`** between components to capture real dependencies.
69+
- **Lay out the diagram** in DrawIO (open `plan.drawio`) so the 2D plan reads well.
70+
71+
> **AI-assisted refinement.** Because the model is just YAML + DrawIO XML, an AI coding agent can do this directly: point it at `model.yml` and your codebase and ask it to assign layers, fix labels, and add dependency links. It operates the same CLI (`generate` / `validate` / `sync`) and edits the same files you would. The refinement is a normal review-and-edit loop — keep what's right, correct what's wrong.
72+
73+
### 3. Validate — catch model↔plan drift
74+
75+
```bash
76+
straymark architecture validate # text; exits 1 on any signal (CI-gateable)
77+
straymark architecture validate --output json
78+
```
79+
80+
Reports integrity signals: **undrawn** (a component with no diagram cell), **unmodeled** (a diagram cell missing from the model), **empty** (globs that match no files). Errors are now legible (they name the exact cause — e.g. a component id colliding with a layer id), so a malformed model tells you what to fix.
81+
82+
### 4. Sync — keep up as the code grows (append-only)
83+
84+
```bash
85+
straymark architecture sync # dry-run: shows what's new
86+
straymark architecture sync --apply # appends new dirs / ADR components
87+
```
88+
89+
Detects new source directories and ADR components not yet in the model and **appends** them — it **never** clobbers your edits or your DrawIO geometry. Run it when you add a module; refine the new entries the same way.
90+
91+
### 5. Serve — see it live
92+
93+
```bash
94+
straymark loom serve # downloads the loom-* binary on first use, opens the browser
95+
```
96+
97+
Opens both views on `localhost`. The Architecture tab shows your refined plan with the live overlay; the `2D | 3D` toggle gives the axonometric view. Edits to `.straymark/` (or the model) update the open browser in under a second. There's also a terminal-only answer that needs no server:
98+
99+
```bash
100+
straymark status --where # the textual "you are here"
101+
```
102+
103+
---
104+
105+
## Honest limitations (it's a seed, not authoritative output)
106+
107+
- The **generated seed is a starting point.** It will not infer your intended layers or component boundaries — that's the refinement phase, by design.
108+
- **Coverage depends on your stack.** The scan recognizes ~25 languages by default and handles common layouts (Go `internal/`, JS `src/`, multi-module Maven/Gradle). A non-default language or an unusual layout needs an `architecture:` config entry and more hand-refinement — but the seed never *misleads*; it just gives less of a head start.
109+
- The **`has-debt` overlay is as precise as your debt records.** Debt is attributed to the components an open TDE's referenced AILOGs actually modified; coarse `files_modified` lists spread it wider than the debt itself.
110+
- **Loom is N=1.** It has been validated by dogfooding on this project and the Sentinel reference. Expect rough edges; report them.
111+
112+
---
113+
114+
## See also
115+
116+
- [CLI-REFERENCE](./CLI-REFERENCE.md) — `straymark architecture <generate|sync|validate>`, `status --where`, and `loom serve` flags + the `architecture:` config section.
117+
- [WORKFLOWS](./WORKFLOWS.md) — how the architecture map fits the day-to-day StrayMark cadence.
118+
- [ADOPTION-GUIDE](./ADOPTION-GUIDE.md) — getting StrayMark into a project in the first place.

‎docs/adopters/WORKFLOWS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,17 @@ The `/straymark-status` skill (available in Claude Code and Gemini CLI) analyzes
101101
- Document compliance against governance rules
102102
- Overall documentation health
103103

104+
### Seeing the project (Loom, experimental)
105+
106+
For a *visual* answer to "where are we?", the **EXPERIMENTAL** Loom dashboard renders your project as a live document graph plus a "you are here" architecture map:
107+
108+
```bash
109+
straymark status --where # textual "you are here" (no server)
110+
straymark loom serve # the visual dashboard (downloads the loom-* binary on first use)
111+
```
112+
113+
The architecture map is driven by a model you generate and then refine — see the **[Loom & the Architecture Map guide](./LOOM.md)** for the recommended `generate → refine → validate → sync → serve` workflow (the refinement step can be human or AI-assisted).
114+
104115
---
105116

106117
## Using Skills (Active Documentation)

‎docs/i18n/es/adopters/LOOM.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# StrayMark — Loom y el Mapa de Arquitectura (Experimental)
2+
3+
**Mira tu proyecto: la red de documentos y el mapa "estás aquí" de dónde está sucediendo el trabajo.**
4+
5+
[![Strange Days Tech](https://img.shields.io/badge/by-Strange_Days_Tech-purple.svg)](https://strangedays.tech)
6+
7+
> ⚠️ **EXPERIMENTAL — Loom v0 (N=1).** Loom es un experimento opt-in e inestable. Su API, superficie de CLI, formato del modelo en disco y su propia existencia pueden cambiar o eliminarse sin un ciclo de deprecación hasta que se gradúe. **No** forma parte del contrato soportado del Framework ni del CLI — no construyas automatización contra él todavía. El modelo `architecture` y `status --where` se envían en el CLI pero cargan la misma advertencia experimental.
8+
9+
---
10+
11+
## Qué es Loom
12+
13+
Loom es el tercer componente de StrayMark (junto al Framework y al CLI): un **dashboard de desarrollo** loopback-only y de solo lectura que hace legible un proyecto StrayMark al ojo humano. Tiene dos superficies sobre el mismo proyecto:
14+
15+
1. **Knowledge Graph** — la red de tus *documentos* StrayMark, renderizada como un grafo dirigido por fuerzas en vivo a partir de los enlaces de su frontmatter (`related`, `originating_ailogs`, …). Selecciona un nodo y todo su hilo de relaciones se ilumina. Esta vista es autoexplicativa y no necesita configuración.
16+
2. **Mapa de Arquitectura** — el mapa de implementación del *sistema*: componentes y capas (tu arquitectura real), con un **overlay de estado "estás aquí"** en vivo computado a partir del estado de gobernanza (Charters activos, drift, trabajo cerrado, deuda técnica abierta). Responde visualmente al *"¿dónde estamos?"* diario. **Esta vista está dirigida por un modelo que tú redactas + refinas** — el resto de esta guía trata sobre eso.
17+
18+
Loom nunca escribe en tu proyecto — solo *visualiza* lo que el CLI computa. Los comandos del CLI (`validate`, `audit`, `charter drift`) siguen siendo la fuente de verdad y el gate.
19+
20+
---
21+
22+
## El modelo mental: un modelo, muchas vistas (BIM)
23+
24+
El Mapa de Arquitectura toma prestada la idea de **BIM "un modelo, muchas vistas"**. Hay **un** modelo, expresado como dos archivos enlazados bajo `.straymark/architecture/`:
25+
26+
| Archivo | Qué contiene | Quién lo posee |
27+
|---|---|---|
28+
| `model.yml` | La **semántica** — componentes → globs de archivos, capas, enlaces | Tú (sembrado por el CLI) |
29+
| `plan.drawio` | El **layout** — el diagrama de cajas-y-flechas (DrawIO/mxGraph) | Tú (sembrado por el CLI) |
30+
31+
A partir de ese único modelo, StrayMark renderiza **tres proyecciones**, todas desde el *mismo* cómputo de estado para que no puedan contradecirse:
32+
33+
- **Textual** — `straymark status --where` (el "estás aquí" de la terminal).
34+
- **Plan 2D** — la pestaña Architecture de Loom (tu `plan.drawio`, superpuesto con estado en vivo).
35+
- **Axonométrico 3D** — el toggle `2D | 3D` de Loom (una vista explotada al estilo BIM).
36+
37+
El **overlay de estado se computa en vivo, nunca se mantiene a mano.** Tú redactas la *estructura* (qué archivos pertenecen a qué componente, cómo se relacionan los componentes); StrayMark lo colorea (`active` / `in-progress` / `implemented` / `has-debt` / `uncharted`) a partir de señales de gobernanza cada vez que lo miras.
38+
39+
---
40+
41+
## El flujo de trabajo recomendado
42+
43+
```
44+
generate → refine (humano o IA) → validate → sync (a medida que crece el código) → loom serve
45+
draft el modelo real gate CI append-only visualizar
46+
```
47+
48+
### 1. Generate — una semilla de primer borrador
49+
50+
```bash
51+
straymark architecture generate
52+
```
53+
54+
Mina la estructura de tu codebase (un componente por directorio de fuente) y la enriquece a partir de tus ADRs (los diagramas C4 + las tablas "Affected Components" mejoran las etiquetas y añaden enlaces). Escribe `model.yml` + `plan.drawio` con cada componente en una capa placeholder `unassigned` y las etapas 00–09 de `.straymark` como capas placeholder.
55+
56+
La semilla es **consciente del lenguaje y la estructura** (desciende a través de `internal/`, `src/`, `pkg/`, … y omite el scaffolding de Maven/Gradle para que un módulo Java no sea una sola caja `main`). Para stacks no predeterminados puedes extenderla con una sección `architecture:` en `.straymark/config.yml` — ver [CLI-REFERENCE](./CLI-REFERENCE.md#straymark-architecture-generatesyncvalidate-cli-3250-experimental).
57+
58+
**La semilla es un borrador, no la respuesta.** Captura la forma; tú la haces significativa en el siguiente paso.
59+
60+
### 2. Refine — la fase que importa (humano *o* IA)
61+
62+
Aquí es donde un mapa generado se vuelve uno real. `model.yml` es YAML plano y `plan.drawio` es un archivo DrawIO estándar, así que el refinamiento puede hacerlo **una persona, un agente IA, o ambos**:
63+
64+
- **Renombra las capas** de las etapas placeholder a tu arquitectura real (p. ej. `entrypoints`, `domain`, `persistence`, `web`).
65+
- **Reasigna componentes** fuera de `unassigned` hacia esas capas.
66+
- **Corrige las etiquetas** a nombres humanos (`internal-modules-commshub` → "CommsHub").
67+
- **Ajusta los globs** para que cada componente posea exactamente sus archivos.
68+
- **Añade `links`** entre componentes para capturar dependencias reales.
69+
- **Distribuye el diagrama** en DrawIO (abre `plan.drawio`) para que el plan 2D se lea bien.
70+
71+
> **Refinamiento asistido por IA.** Como el modelo es solo YAML + XML de DrawIO, un agente IA de codificación puede hacerlo directamente: apúntalo a `model.yml` y a tu codebase y pídele que asigne capas, corrija etiquetas y añada enlaces de dependencia. Opera el mismo CLI (`generate` / `validate` / `sync`) y edita los mismos archivos que tú. El refinamiento es un ciclo normal de revisar-y-editar — conserva lo que está bien, corrige lo que está mal.
72+
73+
### 3. Validate — atrapa el drift modelo↔plan
74+
75+
```bash
76+
straymark architecture validate # texto; sale 1 ante cualquier señal (gateable en CI)
77+
straymark architecture validate --output json
78+
```
79+
80+
Reporta señales de integridad: **undrawn** (un componente sin celda en el diagrama), **unmodeled** (una celda del diagrama ausente del modelo), **empty** (globs que no coinciden con ningún archivo). Los errores ahora son legibles (nombran la causa exacta — p. ej. un id de componente que colisiona con un id de capa), así que un modelo malformado te dice qué corregir.
81+
82+
### 4. Sync — mantente al día a medida que crece el código (append-only)
83+
84+
```bash
85+
straymark architecture sync # dry-run: muestra lo nuevo
86+
straymark architecture sync --apply # añade nuevos dirs / componentes de ADR
87+
```
88+
89+
Detecta nuevos directorios de fuente y componentes de ADR que aún no están en el modelo y los **añade** — **nunca** pisa tus ediciones ni tu geometría de DrawIO. Ejecútalo cuando añadas un módulo; refina las nuevas entradas de la misma manera.
90+
91+
### 5. Serve — míralo en vivo
92+
93+
```bash
94+
straymark loom serve # descarga el binario loom-* en el primer uso, abre el navegador
95+
```
96+
97+
Abre ambas vistas en `localhost`. La pestaña Architecture muestra tu plan refinado con el overlay en vivo; el toggle `2D | 3D` da la vista axonométrica. Las ediciones en `.straymark/` (o en el modelo) actualizan el navegador abierto en menos de un segundo. También hay una respuesta solo-terminal que no necesita servidor:
98+
99+
```bash
100+
straymark status --where # el "estás aquí" textual
101+
```
102+
103+
---
104+
105+
## Limitaciones honestas (es una semilla, no salida autoritativa)
106+
107+
- La **semilla generada es un punto de partida.** No inferirá tus capas o fronteras de componentes intencionadas — esa es la fase de refinamiento, por diseño.
108+
- **La cobertura depende de tu stack.** El escaneo reconoce ~25 lenguajes por defecto y maneja layouts comunes (Go `internal/`, JS `src/`, Maven/Gradle multi-módulo). Un lenguaje no predeterminado o un layout inusual necesita una entrada de config `architecture:` y más refinamiento a mano — pero la semilla nunca *engaña*; solo da menos ventaja inicial.
109+
- El **overlay `has-debt` es tan preciso como tus registros de deuda.** La deuda se atribuye a los componentes que los AILOGs referenciados de un TDE abierto realmente modificaron; las listas `files_modified` gruesas la esparcen más ampliamente que la deuda misma.
110+
- **Loom es N=1.** Ha sido validado por dogfooding en este proyecto y en la referencia Sentinel. Espera asperezas; repórtalas.
111+
112+
---
113+
114+
## Ver también
115+
116+
- [CLI-REFERENCE](./CLI-REFERENCE.md) — `straymark architecture <generate|sync|validate>`, `status --where`, y los flags de `loom serve` + la sección de config `architecture:`.
117+
- [WORKFLOWS](./WORKFLOWS.md) — cómo encaja el mapa de arquitectura en la cadencia diaria de StrayMark.
118+
- [ADOPTION-GUIDE](./ADOPTION-GUIDE.md) — meter StrayMark en un proyecto en primer lugar.

‎docs/i18n/es/adopters/WORKFLOWS.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -101,6 +101,17 @@ El skill `/straymark-status` (disponible en Claude Code y Gemini CLI) analiza:
101101
- Cumplimiento de documentos contra las reglas de gobernanza
102102
- Estado general de documentación
103103

104+
### Ver el proyecto (Loom, experimental)
105+
106+
Para una respuesta *visual* a "¿dónde estamos?", el dashboard **EXPERIMENTAL** Loom renderiza tu proyecto como un grafo de documentos en vivo más un mapa de arquitectura "estás aquí":
107+
108+
```bash
109+
straymark status --where # "estás aquí" textual (sin servidor)
110+
straymark loom serve # el dashboard visual (descarga el binario loom-* en el primer uso)
111+
```
112+
113+
El mapa de arquitectura está dirigido por un modelo que generas y luego refinas — ver la **[guía de Loom y el Mapa de Arquitectura](./LOOM.md)** para el flujo recomendado `generate → refine → validate → sync → serve` (el paso de refinamiento puede ser humano o asistido por IA).
114+
104115
---
105116

106117
## Usar Skills (Documentación Activa)

0 commit comments

Comments
 (0)