MuNa/CLAUDE.md

# Pattern-Language / Form-Language Design Method — Tooling & Projects

## What this repo is

This repo holds a **reusable method** for synthesizing human-centered
architectural design narratives from Christopher Alexander's pattern
language plus a region-specific form language, together with the
**concrete projects** that apply it. It started as a single project (the
Ecuador museum counter-proposal); the method and tooling were then
generalized out of that project once a second, unrelated project (Harbor
House) needed the same pipeline. Layout:

```
method/                      generalized, project-agnostic tooling + the paper about it
  form-language-prompt-template.md
  paper/                     draft paper on the method, extending buildings-15-02400

projects/
  ecuador-museum/            National Museum of Ecuador counter-proposal (see its CLAUDE.md)
    ref/  narratives/  docs/
  harbor-house/              Harbor House travellers' inn, Sheffield (see its CLAUDE.md)
    ref/  narratives/  docs/
```

Each project directory has its own `CLAUDE.md` with that project's brief,
inputs, deliverable conventions, and status. This root file covers what's
shared: the method itself, and repo-wide conventions.

Related but **separate** repositories (not part of this monorepo):

- `homemaker-addon` — automates spatial layout generation; consumes the
  output of this repo's projects (e.g. the Harbor House proposal) but is
  developed independently and has its own history/tooling.

## Method

The generalized method (`method/`) is described in and extends:

> Postle, B.; Salingaros, N.A. "LLM and Pattern Language Synthesis: A Hybrid
> Tool for Human-Centered Architectural Design." *Buildings* 2025, 15, 2400.
> (`projects/ecuador-museum/ref/buildings-15-02400-v2.txt`) — Bruno is the
> paper's first author. `method/paper/` is a draft follow-up paper covering
> the extension to a second, form-language input and validation across two
> independent projects (Ecuador, Harbor House).

Core idea: Christopher Alexander's *A Pattern Language* (1977) encodes 253
human-centered design patterns, but at 1166 pages it's too unwieldy for
direct practical use, and requires expert familiarity to select and combine
patterns. The method's workaround:

1. A web tool ([APL-Companion](https://apl-companion.netlify.app/apl.html))
   lets someone familiar with the patterns curate a **project-specific
   subset** of the 253, then export it as a condensed PDF (titles +
   paraphrased summaries only, no navigation chrome). PDF exports are
   converted to Markdown once received (see Conventions below).
2. Optionally, a **form language** (region/climate-specific vocabulary of
   materials, massing, color, and ornament) is generated or supplied as a
   second input — `method/form-language-prompt-template.md` generalizes the
   prompting process used to produce one, for reuse on any region/typology.
3. The pattern subset (and form language, if used) is fed to an LLM as
   context, along with a prompt describing the project (purpose, scale,
   local context) and a request for a **narrative description of the human
   experience** of the building — look, feel, and ornamental treatment —
   grounded only in the selected patterns.
4. The LLM's narrative is checked for fidelity against the pattern subset
   (any element not traceable to a selected pattern is a hallucination to be
   caught and regenerated away).
5. Optionally, the narrative can later be used as a prompt for AI image
   synthesis to produce illustrative (not prescriptive) visuals — the paper
   found this reliably reveals human-centered forms even with no style
   imposed. Image generation itself is run externally (by the project owner,
   via whatever tool), not by this tooling; this repo writes the detailed
   image-generation prompts and embeds the resulting images into each
   project's presentation document.

The output of the method is words, not drawings — the operational chain is
*pattern repository → project-specific pattern subset (+ optional form
language) → LLM narrative synthesis → evaluation*.

Per-project specifics (which stakeholder viewpoints to write, deliverable
file layout, status) are in each project's own `CLAUDE.md`:
`projects/ecuador-museum/CLAUDE.md`, `projects/harbor-house/CLAUDE.md`.

## Conventions

- Reference documents received as PDF are converted to Markdown (or plain
  text, for documents like the academic paper where reflowing into headed
  sections isn't worth the effort) and the PDF is then deleted — keeps
  everything in each project's `ref/` greppable and quotable rather than
  needing repeated page-range PDF reads. Check conversions carefully: PDF
  text extraction can silently mis-join hyphenated compounds and drop
  ligatures/symbols.
- Each project follows the same internal shape: `ref/` (inputs — pattern
  subset, form language, brief, chassis), `narratives/` (drafting-stage
  stakeholder narratives), `docs/` (public presentation document, images,
  illustration prompts). See each project's `CLAUDE.md` for the specifics
  of what's in each.


<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:7510c1e2 -->
## Beads Issue Tracker

This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.

### Quick Reference

```bash
bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work
```

### Rules

- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
- Run `bd prime` for detailed command reference and session close protocol
- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files

**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

## Session Completion

**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.

**MANDATORY WORKFLOW:**

1. **File issues for remaining work** - Create issues for anything that needs follow-up
2. **Run quality gates** (if code changed) - Tests, linters, builds
3. **Update issue status** - Close finished work, update in-progress items
4. **PUSH TO REMOTE** - This is MANDATORY:
   ```bash
   git pull --rebase
   git push
   git status  # MUST show "up to date with origin"
   ```
5. **Clean up** - Clear stashes, prune remote branches
6. **Verify** - All changes committed AND pushed
7. **Hand off** - Provide context for next session

**CRITICAL RULES:**
- Work is NOT complete until `git push` succeeds
- NEVER stop before pushing - that leaves work stranded locally
- NEVER say "ready to push when you are" - YOU must push
- If push fails, resolve and retry until it succeeds
<!-- END BEADS INTEGRATION -->