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) 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.

Beads Issue Tracker

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

Quick Reference

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:

   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