# 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. ## 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 # View issue details bd update --claim # Claim work bd close # 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