{
  "markdown": "# 🏡 Garden Structure Designer (Agent Plugin)\n\n> **Translate your backyard vision into build-ready architectural reality without needing an engineering degree.**\n\nThe **Garden Structure Designer** is a modular, AI-native plugin built for advanced agentic environments (like Claude Cowork, Antigravity, and Gemini CLI). It acts as your personal master builder and timber framer—taking hazy, non-technical descriptions of pergolas, gazebos, or pavilions and translating them into structurally sound, permit-ready construction PDF plans.\n\n---\n\n## 🎯 Target Audience\n- **Homeowners & Novice DIYers:** You know what you want it to look like, but you don't know the span mathematics to guarantee it won't collapse under winter snow.\n- **Professional Carpenters & Builders:** You want a rapid way to generate professional intake documents, accurate visual references, and precise cut-lists for your clients while offloading the repetitive drafting work.\n\n---\n\n## 🚀 The Guided Discovery Process\n\nGeneralized AI struggles to design physical structures reliably because the required architectural pipeline is too complex for a single prompt, almost always leading to hallucinations in angles, board-feet, and span physics. \n\nThis plugin solves that by migrating away from LLM-guessing toward a **deterministic, artifact-verified engineering pipeline**. It encapsulates an entire **Multi-Agent Design Firm** backed by strict Python execution:\n\n1. **Vision Alignment (`Interactive-Designer`)**: The agent interviews you. You don't need CAD software. Just upload inspiration images and answer simple questions about the size and style.\n2. **Deterministic Structural Engineering (`Structural-Engine & Code-Validator`)**: You provide your jurisdiction. The engine queries local building code constraints. The AI does *not* guess the math; instead, it feeds parameters into a locked `geometry_engine.py` script to calculate exact roof pitches, rafter tails, compound cuts, and miter joints deterministically. *(Safety and physics override aesthetics 100% of the time).*\n3. **Joinery & Bracing**: Choose between traditional mortise-and-tenon timber framing or modern mechanical fasteners. The system computes anti-racking brace geometry into an immutable JSON data model.\n4. **Validated Blueprinting (`Shop-Blueprint-Generator` & `Validation-Agent`)**: Before any drawing is finalized, it must pass through strict XML schema gates and coordinate drift checks (`svg_validator.py`) to guarantee that what is drawn perfectly matches the engineering math.\n5. **Professional Compilation**: The orchestration layer enforces cross-artifact consistency (ensuring the cut-list math matches the blueprint arrows) and compiles a final PDF construction packet.\n\n---\n\n## 🛡️ The Self-Healing Architecture\n\nThis is not a static prompt chain. The `garden-structure-designer` pipeline features an advanced continuous-improvement infrastructure that actively captures failure modes and automatically repairs itself:\n\n- **Strict Contracts**: All state boundaries (Structural Models, Cut-Lists, Bracing Maps) are heavily enforced via formal JSON Schemas.\n- **Fail-Closed Validation**: If a structural physics check or drawing validation fails, the pipeline halts. Unsafe hallucinated physics cannot slip through.\n- **The Learning Registry**: When the Red-Team `validation-agent` catches a failure, the orchestrator generates a permanent \"lesson\" in the `agent-workspace/`. On subsequent runs, `load_applicable_lessons.py` explicitly injects these learned constraints into the offending skill's prompt *before* it can fail again.\n- **Automated Regression Testing**: Novel pipeline failures automatically trigger `failure_to_test.py` to scaffold PyTest regression suites, locking down edge cases permanently.\n\n---\n\n## 📑 What You Get (The Outputs)\n\nThe ultimate deliverable is a comprehensive **Architectural & Structural Construction Packet (PDF)** matching professional timber-framing standards.\n\n**Output features include:**\n- **Architectural Visualizations:** 4 distinct visual outputs for aesthetic client approval: Plan View, Elevation View, Perspective View (human-vision depth scaling), and Isometric View (axis-parallel mapping without vanishing points).\n- **Shop Blueprints:** A devoted technical cut-sheet generator that produces hyper-detailed, heavily dimensioned CAD-style layouts loaded with exact cut-lengths, arrows, and pitch angles strictly for the carpenter.\n- **Detailed Assembly:** Linear, easy-to-follow step-by-step assembly workflows.\n- **Cut-Lists & Inventories:** Precise timber schedules, joinery maps, and required hardware/fastener quantities.\n\n*(Example outputs match the structural depth and clarity of professional 30x24 Timber Frame Cabin blueprints, ensuring a builder can start cutting wood immediately).*\n\n---\n\n## 🏗️ Under the Hood (Architecture)\n\nBuilt using strict separation-of-concerns, this plugin is completely loosely coupled and self-contained.\n\n### Sub-Agents\n- `interactive-designer`: Conducts the user interview and captures the vision.\n- `design-orchestrator`: Pipeline controller ensuring sequential execution of design components.\n- `validation-agent`: A Red-Team reviewer that critiques physics calculations before document compilation.\n\n### Specialized Skills\n- `intake-normalizer`: Converts conversational text into strict JSON parameters.\n- `building-code-validator`: Maps regions to building code physics constraints.\n- `structural-engine`: Computes timber span mathematics.\n- `joinery-designer` & `bracing-system-designer`: Assigns appropriate structural connections.\n- `drawing-generator`: Emits clean, presentation-ready architectural diagrams (Plan, Elevation, Perspective, Isometric).\n- `shop-blueprint-generator`: Generates hyper-detailed, mathematically annotated cut-sheets with dimensional arrows specifically for the fabrication team.\n- `document-compiler`: Aggregates the structural math, the visual renders, and the shop blueprints into a single formatted Markdown/PDF packet.\n\n---\n\n## 🚪 Main Entry Point: Where to Start\n\n### For End Users & Clients\nStart your design journey by talking to the **`interactive-designer`** agent:\n> *\"I want to design a 14ft hexagonal cedar gazebo with steep roof, decorative knee braces, and sonotube footings in Victoria, BC.\"*\n\nThe **`interactive-designer`** acts as your personal master timber framer. It conducts a conversational interview using progressive disclosure, translates your colloquial words into structured CAD constraints, and automatically triggers the backend engineering pipeline.\n\n```mermaid\nflowchart TD\n    User([👤 User Request]) -->|1. Plain English Description| ID[🎯 interactive-designer Agent]\n    ID -->|Progressive Interview & Spec Normalization| Struct[context/staging/structure.json]\n    Struct -->|2. Automated Hand-off| DO[⚙️ design-orchestrator Agent]\n    DO --> Stages[Stages 0–8: Deterministic Math, CAD Translator, Drawings & QA]\n    Stages --> PDF([📄 outputs/pergola_plan.pdf Construction Package])\n```\n\n### For Engineers & Automated Workflows\nIf you already have a completed `context/staging/structure.json`, you can invoke the backend engine directly:\n- **Agent**: `design-orchestrator` (drives fail-closed Stages 0 to 8 autonomously).\n- **CLI Compilation**: `python3 plugins/garden-structure-designer/scripts/compile_package.py`\n\n---\n\n## 📦 Installation\n\nThis plugin adheres to strict Agentic OS boundaries and requires zero external framework dependencies natively.\n\n### 1. Install via `uvx` (Antigravity / CLI environments)\nInstall all plugins and skills from the central catalog:\n```bash\nuvx --from git+https://github.com/richfrem/agent-plugins-skills plugin-add plugins/ --all -y\n```\nOr install the specific garden structure plugin:\n```bash\nuvx --from git+https://github.com/richfrem/garden-structure-designer plugin-add richfrem/garden-structure-designer\n```\n\n### 2. Install via Claude Code Marketplace\nIf you are using Claude Code directly:\n```bash\n# Add this repository to your known marketplaces\n/plugin marketplace add richfrem/garden-structure-designer\n\n# Open the interactive TUI to browse, discover, and install plugins\n/plugin\n\n# Or install the specific plugin directly\n/plugin install garden-structure-designer\n```\n\n---\n\n## 📐 CAD Solid Geometry Renderer\n\nThe visual drawings are generated by a true **3D Solid Geometry CAD Kernel** (`cad_scene.py`) using a pure-Python scene-graph and face-depth sorted painter's algorithm projection.\n\nThis geometry model features:\n- **Multi-Shape Topologies**: Supports both radial polygonal layouts (hexagonal/octagonal with central hub) and orthogonal rectangular post-and-beam grid layouts (longitudinal girders, transverse cross-ties, and parallel rafters).\n- **Concrete Footing Blocks**: Real 3D concrete square pier blocks extending below grade and rising 4 inches above grade.\n- **Overhang Rafter Tails**: Decorative scalloped overhang tails extending past the posts and beam headers.\n- **Knee Bracing Systems**: 45-degree anti-racking diagonal braces paired per post and seated flush against post faces and beam soffits.\n- **Adaptive Non-Hub pergolas & Purlin Rings**: Automatic suppression of hub-specific constraints when flat or open-span roofs are selected.\n\n### Regenerating Renders & Blueprints\n\nTo regenerate all 8 architectural SVG sheets and shop blueprints using this exact CAD engine:\n\n```bash\npython3 plugins/garden-structure-designer/scripts/render_drawings.py context/staging/structure.json\n```\n\nThis updates the entire visual drawing package in `outputs/` including:\n- `outputs/drawing-isometric-view.svg`\n- `outputs/drawing-perspective-view.svg`\n- `outputs/drawing-plan-view.svg`\n- `outputs/drawing-elevation-view.svg`\n- `outputs/blueprint-isometric.svg`\n- `outputs/blueprint-plan.svg`\n- `outputs/blueprint-elevation.svg`\n- `outputs/blueprint-component-isolation.svg`\n\n---\n\n## Acknowledgements\n\nThis project draws architectural inspiration from two external projects:\n\n1. **[`NousResearch/hermes-agent`](https://github.com/nousresearch/hermes-agent)**: Inspired the v1.3 architectural plumbing, including central registries, deliberate capability exposure, self-improvement review, lesson curation, context/run summaries, error classification, and traceable workflows.\n2. **[`browser-use/browser-harness`](https://github.com/browser-use/browser-harness)**: Inspired the concept of a small protected deterministic core surrounded by agent-editable learning surfaces, reusable skills, helper logic, and run-specific improvements. [1](https://github.com/browser-use/browser-harness)\n\nFor the garden structure designer plugin, those ideas are generalized away from browser automation and applied to construction-document generation:\n\n- deterministic core calculations remain protected;\n- validation failures become durable lessons;\n- repeatable gotchas become regression tests or validators;\n- learned patterns are externalized into editable skill/reference files;\n- future runs can reuse those lessons instead of rediscovering them.\n\nThis acknowledgement is for the self-healing / continuous-learning architecture pattern only. The garden structure designer plugin is an independent project focused on deterministic geometry, construction documentation, validation gates, and design-package generation.\n\n---\n\n## What Counts as a Complete Revision?\n\nA complete revision is not just a prettier render.\n\nA complete revision must update or verify:\n\n| Artifact Category | Files |\n|---|---|\n| Deterministic staging | `context/staging/design-spec.json`, `structural-model.json`, `geometry-calculations.json` |\n| Deterministic drawings | `outputs/drawing-*.svg`, `outputs/blueprint-*.svg` |\n| Shop package | `outputs/shop-blueprint/SB01-cut-list.json` |\n| Validation reports | `context/staging/schema-validation-report.json`, `physics-validation-report.json` |\n| Run summary | `context/staging/design-run-summary.md` |\n| Quality artifacts | `outputs/quality-dashboard.md`, `outputs/run-insights.json` |\n\nPhotorealistic renderings are useful for stakeholder communication, but they are marked as visual concepts only. Construction geometry is governed by validated JSON/SVG artifacts. A revision that only updates Markdown, render prompts, or PNGs has status **PARTIAL**, not **PASS**.\n",
  "bytes": 12256,
  "sha": "66c8c303ee764a42fc572fb6867f17c884b2a3e2c66b3e056253fa60c2e30aa4",
  "repo_slug": "richfrem/garden-structure-designer",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_richfrem_garden_structure_designer_583f8d82/readme"
}