skilldrop-cli 1.4.0 → 1.6.0

package/packs/ai-engineering/skills/subagent-design/examples/help-center-localization.md

@@ -0,0 +1,146 @@
+# Worked example: a seven-agent localization plan that grades its own work
+
+Input → output oracle for `subagent-design`. Shows a fan-out that is justified but drawn
+wrong: a translator that checks itself, a middle layer with no job, a summary agent standing
+in for a merge, and auto-publishing. It also shows the one barrier the work actually needs.
+
+## Input
+
+> We're localizing our help center with AI agents. My team lead drew up the plan below. Is
+> this the right setup? Our docs lead has to sign off, so keep it short.
+>
+> **Plan:**
+> 1. A Coordinator agent spawns three Language Leads (de, fr, ja).
+> 2. Each Language Lead spawns one Translator agent per article. The Translator translates
+>    the article, then reviews its own translation against the glossary and fixes anything it
+>    finds.
+> 3. When all 960 translations are done, a Summary agent reads them all and writes a report of
+>    quality issues for the docs lead.
+> 4. The Coordinator publishes everything to the help center.
+> 5. We want 7+ agents because more agents run faster.
+>
+> **Facts:**
+> - 320 English articles, about 1,500 words each, into three languages.
+> - A glossary of 410 product terms with an approved translation per language. Style rule: UI
+>   labels stay in English.
+> - Pilot of 40 articles into Japanese: the Translator's self-review marked all 40 "pass". Our
+>   Japanese linguist found 11 with UI labels translated, and 4 where the same term was
+>   translated two different ways in different articles.
+> - Today a linguist per language approves each article before it goes live.
+
+## Output
+
+**Not as drawn. Splitting the work per article is right, but four parts of the plan need to
+change.** Keep one translation job per article and language. A separate agent should check
+each translation instead of the translator checking itself. Code should build the report, not
+a summary agent. Drop the Language Lead layer. And nothing goes live without the linguist,
+who stays the final approval. That leaves two agent roles, each run once per article and
+language, plus code around them. The pilot is the reason: the translator passed its own work
+40 times out of 40, and the linguist found problems in at least 11 of those articles.
+
+Assumed: each article can be translated on its own, given the glossary.
+
+# Orchestration plan: help-center localization (320 articles × de, fr, ja)
+
+> Fan-out justification: **context separation**, because about 480,000 words of source won't
+> fit one context well and each article stands alone. **Role conflict** for checking, because
+> the agent that wrote a translation can't honestly grade it, as the 40/40 pilot showed.
+> Speed comes with the per-article split. It is not a reason on its own.
+
+## Role cards
+
+### orchestrator (code, not an agent)
+- **Mission:** Move each article-language pair through translation, checking and the linguist queue.
+- **Inputs:** article list, glossary, UI-label rule
+- **Denied (isolation):** it doesn't judge translation quality. It acts only on the fields each step returns
+- **Output contract:** `{ article_id: string, lang: "de"|"fr"|"ja", status: "translated"|"checked"|"flagged"|"invalid"|"queued_for_linguist" }[]`
+- **Tools/permissions:** read source articles, write to the linguist's review queue. **No publish permission**
+- **On failure:** marks the item `invalid` with the reason and carries on with the rest
+- **Model:** none needed: routing and merging are code
+
+### translator ×960
+- **Mission:** Translate one article into one language using the glossary.
+- **Inputs:** one source article, that language's glossary, the UI-label rule
+- **Denied (isolation):** other articles' translations, so each job stays small. Consistency across articles comes from the glossary and the term check below
+- **Output contract:** `{ article_id: string, lang: string, body: string, terms: [{ source: string, target: string, in_glossary: bool }], status: "ok"|"blocked", blocked_reason: string|null }`
+- **Tools/permissions:** none beyond its inputs. No write access anywhere
+- **On failure:** `status: "blocked"` with a reason. It never sends a partial translation as `ok`
+- **Model:** mid-size: translating with a fixed glossary doesn't need the largest model
+
+### checker ×960
+- **Mission:** Find every place the translation departs from the source, the glossary or the UI-label rule.
+- **Inputs:** source article, translated `body`, glossary, UI-label rule
+- **Denied (isolation):** the translator's `terms` list and status, so it checks the text instead of confirming the translator's claims about it
+- **Output contract:** `{ article_id: string, lang: string, verdict: "pass"|"fail"|"blocked", findings: [{ type: "glossary"|"ui_label"|"meaning"|"omission", source_excerpt: string, target_excerpt: string, expected: string }] }`
+- **Tools/permissions:** read-only
+- **On failure:** `verdict: "blocked"`, handled exactly like `fail`. It is never counted as a pass
+- **Model:** mid-size: a different agent from the translator, which is what makes the check independent
+
+## Topology
+
+**Shape:** a pipeline per article (translate, then check), **because** no article's
+translation depends on another's. **One barrier per language**, **because** the pilot's 4
+inconsistent terms only show up across articles. Code groups every translator's `terms` by
+source term and flags any term with more than one translation. That check needs all of a
+language's articles, and nothing else in the plan does.
+**Depth:** one level. The Language Leads would only pass articles along, and the orchestrator
+already does that.
+
+```mermaid
+flowchart LR
+    O[orchestrator] --> T["translator ×960"]
+    T --> C["checker ×960"]
+    T -. terms .-> X{"term check per language"}
+    C --> X
+    X --> L["linguist approval"]
+    L -->|approved| P[help center]
+    T -->|invalid output| F[failure list]
+    C -->|invalid output| F
+```
+
+## Aggregation & verification
+
+- **Aggregation:** code. The term check groups by `(lang, source term)`. The report for the
+  docs lead is counts of `findings` by type and language, plus the list of `fail` and
+  `invalid` articles. Output that doesn't match its schema goes to the failure list and never
+  into the report.
+- **Verification:** the checker's job is to find faults, and it never sees the translator's
+  own assessment. A failed article goes to the linguist with its findings attached.
+- **Vote rule:** a single checker. An article is flagged if it has any finding. The linguist's
+  approval gates publishing, as it does today.
+
+## Budget line
+
+No spending cap was given, so none is set here. Model sizes are on each card.
+
+**Left out of the plan:** the Coordinator publishing everything. Every article still goes
+through linguist approval before it goes live. The pilot shows why: the self-check missed all
+11 UI-label errors.
+
+**To confirm**
+- The spending cap for a full run.
+- Whether source articles mark UI labels in a way code can detect. If they do, that check
+  can move from the checker to code.
+- Who reworks a failed article: the linguist, or a second translation pass with the findings.
+
+Next step: design the run around this, meaning retries, the stop conditions and what happens
+when the cap is hit, before the first full batch.
+
+## Why this is the oracle
+
+- **The verifier is separate and adversarial, never the generator.** The plan's step 2 has
+  the translator check itself, and the pilot's 40/40 self-pass is the evidence that this
+  fails. The checker is denied the translator's own claims, so it can't just agree with them.
+- **Aggregation is code, and a barrier needs a named dependency across items.** The summary
+  agent becomes a group-by over typed `findings`. The plan's "when all 960 are done"
+  synchronisation shrinks to one barrier per language, earned by cross-article term
+  consistency, the 4 inconsistent terms no per-article check can see.
+- **Fan out only for a named reason, keep depth to one level, and take budget numbers only
+  from the user.** "More agents run faster" is rejected as a reason. The Language Lead layer
+  is cut. No cap is invented, and auto-publishing is removed and named as removed.
+
+A cheaper pass approves the seven-agent plan and tunes the prompts. It keeps self-review,
+lets a summary agent paraphrase 960 translations, and leaves the Coordinator publishing. That
+ships the pilot's UI-label errors across three languages straight to the live help center. The
+opposite cheap answer, "use one agent", fails too: 480,000 words don't fit one context, and it
+leaves the role conflict in place.

package/packs/ai-engineering/skills/subagent-design/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "subagent-design",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "Decompose a task into an orchestrator and subagents — one-mission role cards with typed output contracts, a topology (pipeline / parallel / judge panel) chosen with a reason, context-isolation rationale, and a verification stage that is never a generator. Use when the user wants to fan work out across multiple agents, design a multi-agent workflow or orchestration, or asks \"should this be one agent or several\".",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["agent-budget", "agent-loop-design", "council-review", "devils-advocate", "feature-implement-loop"],
   "tags": ["subagents", "orchestration", "multi-agent", "fan-out", "agentic", "role-cards"],
-  "model": { "tier": "standard", "rationale": "Design synthesis against a fixed topology catalog and role-card template. The fan-out-or-refuse judgment is bounded by the three-reasons rule; escalate via ambiguous-input on genuinely novel workflow shapes." }
+  "model": { "tier": "heavy", "rationale": "Measured (RFC-0073): on its held-out evals the heavy tier met 100% and 100% of checks in two tier trials, against standard's 86% and light's 85% and 86%, more than 5 points ahead both times; moved once its examples/ oracle shipped (RFC-0074)." }
 }

package/packs/api-builder/skills/prompt-caching-advisor/SKILL.md

@@ -75,6 +75,10 @@ Produce:
 1. **Annotated structure** — show the messages array with `cache_control` placements marked and commented
 2. **Cache strategy summary** — one paragraph: what is cached, why, expected hit rate, and the dominant cost driver before and after
 
+## Useful references in this skill
+
+- [`examples/support-bot-block-order.md`](examples/support-bot-block-order.md) — worked example: a breakpoint under the minimum size and a per-customer block splitting a shared cache, fixed by reordering
+
 ## Anti-patterns
 
 - **Caching dynamic content.** If a user query, timestamp, or per-request database result is inside a cached block, every request is a cache miss — the structure defeats itself. Identify and flag before recommending.

package/packs/api-builder/skills/prompt-caching-advisor/examples/support-bot-block-order.md

@@ -0,0 +1,120 @@
+# Worked example: a cache breakpoint that "didn't move the bill"
+
+Input → output oracle for `prompt-caching-advisor`. Shows a breakpoint that never caches
+because its prefix is under the minimum size, a per-customer block that splits a shared cache
+in two, and the fix as a reordering, not an extra marker.
+
+## Input
+
+> Our support bot runs on Haiku. We added `cache_control` to the instructions block because
+> that's the static part, and the input bill didn't move. Should we add another one on the
+> catalogue? Numbers: about 150,000 requests a day, conversations average 6 turns with a turn
+> every 1–2 minutes, busy all day and quiet overnight. The catalogue is rebuilt once a night
+> at 02:00.
+
+```python
+def build_request(customer, session, question):
+    system = [
+        {"type": "text", "text": INSTRUCTIONS,                # ~3,200 characters
+         "cache_control": {"type": "ephemeral"}},
+        {"type": "text", "text": render_profile(customer)},   # ~1,400 characters, per customer
+        {"type": "text", "text": load_catalogue()},           # ~62,000 characters
+    ]
+    messages = session.history + [{"role": "user", "content": question}]
+    return {"model": MODEL, "max_tokens": 800, "system": system, "messages": messages}
+```
+
+## Output
+
+**Don't add a second marker yet. Fix the order first.** Two things are wrong, and a marker on
+the catalogue in its current position would only fix half of it.
+
+1. **Your current breakpoint caches nothing.** A breakpoint caches the whole prefix up to and
+   including its block. Here that is the instructions alone: 3,200 characters, or about 800
+   tokens. Haiku's minimum is about 1,024 tokens, so the API processes it as normal input,
+   with no error and no saving. That is why the bill didn't move.
+2. **The customer profile sits in front of the catalogue.** The profile differs for every
+   customer, so any breakpoint after it makes a separate cache entry per customer. A marker
+   on the catalogue where it sits now would cache instructions + profile + catalogue together.
+   It would hit only on later turns of the same conversation, and every customer's first turn
+   would pay to write 16,600 tokens to the cache.
+
+Move the catalogue above the profile, put one breakpoint at the end of the catalogue, and put
+a second, moving breakpoint on the latest user turn.
+
+### Annotated structure
+
+| Block | Size (~4 chars/token) | Class | Cached by |
+|---|---|---|---|
+| Instructions | 3,200 ch ≈ 800 tok | Static | BP1 (as part of its prefix) |
+| Catalogue | 62,000 ch ≈ 15,500 tok | Static until the 02:00 rebuild | BP1 |
+| Customer profile | 1,400 ch ≈ 350 tok | Quasi-static (per conversation) | BP2 |
+| Earlier turns | grows each turn | Fixed once sent | BP2 |
+| Latest question | varies | Dynamic | written by BP2 for the *next* turn to read |
+
+```python
+def build_request(customer, session, question):
+    system = [
+        # Static. ~800 tokens: under Haiku's ~1,024 minimum, so no marker of its own.
+        # It is still cached, because BP1's prefix includes it.
+        {"type": "text", "text": INSTRUCTIONS},
+        # Static until the 02:00 rebuild. ~15,500 tokens.
+        {"type": "text", "text": load_catalogue(),
+         "cache_control": {"type": "ephemeral"}},   # BP1: instructions + catalogue, ~16,300 tokens,
+                                                    # identical for every customer
+        # Quasi-static: the same for a whole conversation, different per customer.
+        # It sits after BP1 so it can't split the shared entry.
+        {"type": "text", "text": render_profile(customer)},
+    ]
+    latest = {
+        "role": "user",
+        "content": [{"type": "text", "text": question,
+                     "cache_control": {"type": "ephemeral"}}],  # BP2: profile + all earlier turns + this one
+    }
+    # session.history stores turns WITHOUT cache_control. If the marker is saved into history,
+    # markers pile up turn after turn, and from turn 4 the request carries more than the API's
+    # limit of four breakpoints.
+    messages = session.history + [latest]
+    return {"model": MODEL, "max_tokens": 800, "system": system, "messages": messages}
+```
+
+BP2 is not caching dynamic content. It writes the conversation so far, so that the next turn,
+where this question is now fixed history, can read it. Nothing that changes between requests
+sits in front of BP1, and that is the prefix every customer shares.
+
+Two breakpoints, one per logical boundary: content shared by everyone, then content shared
+within a conversation. A third marker on the instructions would add nothing, because they are
+under the minimum and already inside BP1's prefix.
+
+### Cache strategy summary
+
+BP1 caches the instructions and catalogue, about 16,300 tokens, as one entry shared by every
+customer. At about 150,000 requests a day it stays warm all through the busy hours, so its hit
+rate is near 100%. It misses on the first request after the 02:00 rebuild and after any
+overnight gap longer than the cache's five-minute lifetime. BP2 caches each conversation's
+profile and earlier turns. With turns 1–2 minutes apart, turns 2–6 read it, about 5 of 6
+requests. Before the change, about 16,600 tokens of instructions, profile and catalogue were
+processed at full price on every request, roughly 2.5 billion input tokens a day. After it,
+almost all of that is a cache read, billed at about a tenth of the normal input price. The
+largest costs left are output tokens and each turn's new question. This answer gives no dollar
+figure: the request didn't include prices, and the hit rates above are estimates until the
+response `usage` fields (`cache_read_input_tokens`, `cache_creation_input_tokens`) confirm
+them.
+
+## Why this is the oracle
+
+- **The last block caches everything before it.** The user's mental model, "mark the static
+  block", is per block. A breakpoint marks a prefix. That one rule explains why the
+  instructions marker did nothing (its prefix is 800 tokens) and why a catalogue marker in
+  the current order would be keyed per customer (its prefix includes the profile).
+- **Check the size before recommending a cache.** The fix removes the user's existing marker,
+  because it is under Haiku's minimum. The instructions still get cached, inside BP1.
+- **Never let dynamic or per-user content split a shared prefix.** The profile is not dynamic
+  per request, but it is per customer. Moving it below BP1 turns a per-conversation cache into
+  a shared one. The comment on `session.history` heads off the four-breakpoint error that a
+  moving breakpoint causes when it is stored.
+
+A cheaper pass answers the question as asked: "Yes, add `cache_control` to the catalogue
+block." That gives each conversation a cache entry of its own, a premium cache write on every
+first turn, and a bill that drops far less than expected. The team blames caching, and the
+dead instructions marker stays in the code.

package/packs/api-builder/skills/prompt-caching-advisor/manifest.json

@@ -1,11 +1,11 @@
 {
   "name": "prompt-caching-advisor",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Analyzes a prompt or conversation structure and identifies the highest-value cache breakpoints — where to insert cache_control checkpoints to minimize repeated token processing. Use when designing or optimizing a Claude API integration that uses prompt caching, when input costs are dominated by a static system prompt or few-shot block, or when a multi-turn conversation reprocesses the same context on every turn.",
   "entrypoint": "SKILL.md",
   "deps": { "npm": [], "pip": [] },
   "env": { "required": [], "optional": [] },
   "related": ["token-budget-estimator"],
   "tags": ["claude-api", "caching", "cost", "optimization", "prompt-engineering"],
-  "model": { "tier": "standard", "rationale": "Structural analysis of a prompt with threshold arithmetic and pattern matching — above light (needs API-specific judgment), no need for heavy." }
+  "model": { "tier": "heavy", "rationale": "Measured (RFC-0073): on its held-out evals the heavy tier met 90% and 90% of checks in two tier trials, against standard's 63% and light's 83% and 73%, more than 5 points ahead both times; moved once its examples/ oracle shipped (RFC-0074)." }
 }

package/packs/civil-architect/pack.json

@@ -0,0 +1,60 @@
+{
+  "description": "Building design from a client's room list and a footprint: a schematic floor plan placed at real sizes and drawn as a dimensioned SVG, shown only once a script has checked it for overlapping rooms, rooms outside the footprint, doors on no shared wall, rooms no one can reach and habitable rooms with no window.",
+  "display_name": "Civil architect",
+  "keywords": [
+    "architecture",
+    "architect",
+    "floor plan",
+    "test fit",
+    "concept plan",
+    "zoning",
+    "layout",
+    "dimensions",
+    "svg"
+  ],
+  "links": {
+    "documentation": "https://sananthanarayan.github.io/skilldrop/packs/civil-architect/"
+  },
+  "maintainers": [
+    {
+      "name": "sananthanarayan"
+    }
+  ],
+  "first-value": {
+    "audience-posture": "non-technical",
+    "prerequisites": [
+      "The rooms you need with their sizes, and the footprint's width and depth",
+      "Python 3 on the machine, which the checker and drawing script run on"
+    ],
+    "starter-task": "Get a checked, dimensioned concept plan from a room list and a footprint",
+    "starter-prompt": "Draw a ground floor plan for a 10 m wide × 9 m deep footprint, road on the south, front door from the road. Rooms: foyer 6 m², living 26 m², dining 14 m², kitchen 12.6 m², utility 4 m² next to the kitchen, prayer room 4.5 m² not next to the kitchen or the toilet, guest toilet 3.2 m², and a stair. Living, dining, kitchen and prayer room need windows.",
+    "verification": "floor-plan-layout states its zoning in a few lines, writes an SVG plan with overall dimensions, room sizes and areas, door swings, windows, a scale bar and a north arrow, and shows a room table from a checker that reported no overlaps, every door on a shared wall and every room reachable.",
+    "recovery": "If floor-plan-layout does not activate, ask for it by name (\"use floor-plan-layout\"). If the plan is too tight, ask for a second option with the rooms it may shrink named."
+  },
+  "requires": [
+    "core"
+  ],
+  "journey": {
+    "when": "You have a client's room list and a footprint, and want a first plan to discuss.",
+    "you_bring": [
+      "the rooms, with their sizes or areas",
+      "the footprint's width and depth, or its corner coordinates",
+      "the road or entrance side, and north",
+      "what must sit next to what, and what must be kept apart"
+    ],
+    "steps": [
+      {
+        "skill": "floor-plan-layout",
+        "you_do": "Give it the rooms, the footprint and the entrance side.",
+        "you_get": "Zoning in a few lines, then a dimensioned SVG plan per floor that has passed the checker, with every room's size and area.",
+        "decide": "Take the plan to the client, or ask for another option."
+      },
+      {
+        "skill": "floor-plan-layout",
+        "you_do": "Ask for a second option, naming what may change (a smaller hall, the stair moved).",
+        "you_get": "Another checked plan, with each room that changed against its target."
+      }
+    ],
+    "you_end_with": "A checked concept plan, ready to develop in your CAD or BIM tool."
+  }
+}

package/packs/civil-architect/skills/floor-plan-layout/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: floor-plan-layout
+description: Lay out a schematic floor plan from a space programme and a footprint, and draw it as a dimensioned SVG — rooms placed as rectangles at real sizes, doors and windows on real walls, overall dimensions, a scale bar and north arrow — with a script that fails the plan when rooms overlap, a room spills outside the footprint, a door sits on no shared wall or a room can't be reached from the entrance. Use when an architect asks to "draw a floor plan", "lay out these rooms", "make a plan for a 10 × 9 m footprint", for a concept plan, a test fit, a zoning diagram or a dimensioned layout from room sizes.
+---
+
+# floor-plan-layout
+
+A concept floor plan: every room from the programme placed at its real size inside the
+footprint, connected by doors, lit by windows on outside walls, and drawn to scale. The
+agent does the design reasoning (what goes where and why); a script checks the geometry and
+draws it, so a plan that looks right but has a room overlapping its neighbour or a bedroom
+reachable only through a bathroom never reaches the client. Its inputs are the
+client's room list and the footprint the site allows.
+
+## How to respond
+
+1. **Gather the three inputs.** Take them from the conversation or the files the user names:
+   - **Rooms and target areas,** with adjacencies: an area schedule or the user's list
+   - **The outline** of the floor: footprint width × depth, or corner coordinates, inside the site's envelope
+   - **Fixed points:** the road side and entrance, north, a stair or core position, an existing wall to keep
+
+   Ask at most two questions, only for a missing outline or entrance side. A plan with no
+   footprint and no plot to derive one from is `BLOCKED`.
+
+2. **Decide the zoning before any coordinates.** Write three to six lines:
+   - public rooms (living, reception) on the entrance side; private rooms (bedrooms) away from it
+   - wet rooms (kitchen, toilets, bathrooms) grouped so plumbing stacks, and stacked over each other across floors
+   - every `near` from the programme met by a shared wall, every `apart` by at least one room between
+   - daylight: every habitable room on an outside wall; north or south as the climate wants, stated
+   - the stair in the same place on every floor
+
+   Then place rooms as rectangles on a grid of 0.3 m (1 ft) or its multiples, starting from a
+   corner, so shared walls line up exactly. An L-shaped room is two or three rectangles under
+   one name.
+
+3. **Write `plan.json`** in the shape of [`templates/plan.json`](templates/plan.json): `outline`,
+   each room's `rect` `[x, y, width, depth]` (or `rects`) with `target_area`, `min_width` and
+   `habitable`, every door as `between` two rooms (or `"outside"`) `at` a point on the shared
+   wall, and windows `at` a point on an outside wall. x runs left to right, y from the front
+   (road side) to the back. One file per floor.
+
+4. **Run the checker and fix every FAIL before showing anything.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/plan_check.py" plan.json --svg ground-floor.svg
+   # Other IDEs (from the skill folder)
+   python3 scripts/plan_check.py plan.json --svg ground-floor.svg
+   ```
+
+   Exit 0 means no failures; 1 means a failure (overlap, outside the outline, door on no
+   shared wall, a room unreachable, no entrance); 2 means the input is malformed. Move rooms
+   and rerun until it exits 0. A WARN can stand only with a sentence saying why.
+
+5. **Report in this order:**
+   1. **The plan's path** and one line on its organising idea. ✅ *"Public rooms along the road, wet rooms stacked on the east wall, stair by the entrance so the first floor is reached without crossing the living room."*
+   2. **The zoning lines** from step 2.
+   3. **The checker's room table and result,** unchanged.
+   4. **Every remaining WARN with its reason,** and every area off target with what it traded for.
+   5. **What this plan is not:** schematic, wall thicknesses nominal, no structure, services or code check. The architect checks it against the local rules before it goes further.
+
+**Non-interactive runs** (subagent, CI, headless): take the entrance on the first outline edge
+and north as up, tagged `[assumption]`, and size unsized rooms from the programme. With no
+outline and no plot dimensions, emit `BLOCKED: need the footprint's dimensions or the plot and
+setbacks to derive it`.
+
+## Useful references in this skill
+
+- [`templates/plan.json`](templates/plan.json) — the input shape: a 10 × 9 m ground floor with an L-shaped hall
+- [`scripts/plan_check.py`](scripts/plan_check.py) — overlap, containment, doors on shared walls, reachability, areas, windows; draws the SVG
+- [`examples/ground-floor.md`](examples/ground-floor.md) — worked example: a programme and footprint become a checked, drawn plan, including the FAIL the first draft hit
+
+## Quality bar
+
+- **The checker exits 0.** No plan with an overlap, a room outside the outline, a door on no wall or an unreachable room is shown to the user.
+- **Every room from the programme is on the plan,** at its target area within 10 %, or the difference is explained.
+- **Every stated adjacency is a shared wall,** and every `apart` has a room between.
+- **Every habitable room has a window on an outside wall.**
+- **No bedroom or living space is reached only through a bathroom, toilet or another bedroom.**
+- **The drawing has overall dimensions, room sizes, a scale bar and a north arrow,** and says it is schematic.
+
+## When to use this skill
+
+- ✅ A concept plan or test fit from a programme and footprint
+- ✅ Two or three layout options for the same brief, each checked
+- ✅ Re-planning after the client changes a room
+- ✅ A zoning diagram before detailed design
+
+## When NOT to use this skill
+
+- ❌ Working out the room list and areas from a brief, before any layout: total them first, then plan
+- ❌ How big the footprint may be under setbacks, coverage and FAR: that is a site feasibility check, done before the plan
+- ❌ Construction, working or submission drawings in CAD/BIM: this is a schematic for discussion
+- ❌ Structural grids, MEP routing or a code compliance check
+
+## Anti-patterns to avoid
+
+- ❌ **Drawing the plan in ASCII or Mermaid.** Neither holds a dimension; the SVG does.
+- ❌ **Showing a plan before the checker passes.** The overlap you can't see in a list of coordinates is the one the client finds.
+- ❌ **Rooms that touch "nearly":** a 3.95 and a 4.0 leave a 50 mm sliver no one can build. Use the grid.
+- ❌ **A corridor that serves nothing.** Circulation that reaches no door is area the client pays for.
+- ❌ **Toilet doors opening onto the dining or kitchen,** and a prayer or puja room sharing a wall with a toilet when the brief keeps them apart.
+- ❌ **Calling the plan code-compliant.** The checker tests geometry, not the building code.

package/packs/civil-architect/skills/floor-plan-layout/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "Draw a floor plan for these rooms in a 12 × 15 m footprint",
+    "should_trigger": true
+  },
+  {
+    "query": "Lay out a 3BHK in this footprint and give me a dimensioned plan",
+    "should_trigger": true
+  },
+  {
+    "query": "Can you do a quick test fit of the clinic programme on the ground floor?",
+    "should_trigger": true
+  },
+  {
+    "query": "Make a zoning diagram for the house with the bedrooms away from the road",
+    "should_trigger": true
+  },
+  {
+    "query": "Make a Figma diagram of our microservices",
+    "should_trigger": false
+  },
+  {
+    "query": "Draw a sequence diagram of the checkout flow",
+    "should_trigger": false
+  },
+  {
+    "query": "Build an interactive diagram of our data pipeline I can click through",
+    "should_trigger": false
+  }
+]

package/packs/civil-architect/skills/floor-plan-layout/evals/evals.json

@@ -0,0 +1,57 @@
+{
+  "skill_name": "floor-plan-layout",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "Draw a ground floor plan for a 10 m wide × 9 m deep footprint, road on the south, front door from the road. Rooms: foyer 6 m², living 26 m², dining 14 m², kitchen 12.6 m², utility 4 m² next to the kitchen, prayer room 4.5 m² not next to the kitchen or the toilet, guest toilet 3.2 m², and a stair to the first floor. Living, dining, kitchen and prayer room need windows.",
+      "assertions": [
+        "Writes a plan.json and runs plan_check.py, and the final run exits 0 (no FAIL lines)",
+        "Writes an SVG with overall dimensions, room sizes and areas, a scale bar and a north arrow",
+        "Every room listed is on the plan, each within 10 % of its area or the difference is explained",
+        "The prayer room shares no wall with the kitchen or the toilet",
+        "Living, dining, kitchen and prayer room each have a window on an outside wall",
+        "States the zoning decisions (public at the front, wet rooms grouped, stair placement) before or with the plan",
+        "Says the plan is schematic and not checked against the building code"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Quick test fit: 2-bed apartment, footprint is 7.2 x 10.8 m, entrance in the middle of the long east side. Need living/dining 22 m², kitchen 8 m², two bedrooms 11 m² each, one bathroom 4.5 m², and a hall. Bedrooms must not open off the living room. Just give me the plan.",
+      "assertions": [
+        "Runs plan_check.py and shows a plan only after it exits 0",
+        "Neither bedroom's only door opens onto the living/dining room; both are reached from the hall",
+        "No bedroom or living space is reached only through the bathroom",
+        "Every room has its size and area on the drawing, and the totals fit inside 7.2 × 10.8 m",
+        "Delivers the plan without asking questions first, tagging anything it had to assume",
+        "Does not draw the plan in ASCII or Mermaid"
+      ]
+    },
+    {
+      "id": 3,
+      "held_out": "2026-11-05",
+      "prompt": "make a plan for a 10 x 9 m footprint. 10m runs E-W, entrance on the south side. rooms: living 5x4.5, kitchen 3x3, bed 1 3.5x3.5, bed 2 3x3, bath 2.4x2. bath door must NOT open off the kitchen. single storey holiday cottage at Lake Ternholm, concept only",
+      "assertions": [
+        "It produces an SVG plan with overall dimensions of 10.0 m (E-W) × 9.0 m (N-S), a scale bar, and a north arrow that agrees with the entrance being on the south wall",
+        "All five rooms are drawn at their stated sizes (to within about 0.1 m), all fully inside the footprint, with no two rooms overlapping",
+        "The entrance door is on the south external wall",
+        "Every room can be reached from the entrance through doors, via the living room or a hall/corridor",
+        "The bathroom door does not open into the kitchen, and there is no door between the bathroom and the kitchen",
+        "Windows are only on external walls, never on internal partitions",
+        "It does not invent rooms beyond the five requested plus circulation (no second bathroom, store, garage or porch presented as part of the brief)"
+      ]
+    },
+    {
+      "id": 4,
+      "held_out": "2026-11-05",
+      "prompt": "Hi, attached is the space programme from our meeting with the Okafor-Lindqvist family for their backyard ADU in Brambleton (adu-programme.md). Buildable footprint is 30 ft x 24 ft, single storey, with the 30 ft side facing the street to the west, and the entry comes from the street. Could you lay out the rooms and draw a dimensioned concept plan we can show them on Thursday?",
+      "assertions": [
+        "It reports that the programme's rooms add up to 869 sq ft (320 + 144 + 182 + 121 + 54 + 48) against a 720 sq ft footprint (30 × 24), 149 sq ft over before any circulation, so it cannot fit as given",
+        "It does not hand over a plan where rooms overlap, rooms sit outside the 30 × 24 ft footprint, or rooms have been shrunk without saying which ones and by how much",
+        "It offers concrete ways to fix it (named rooms cut or resized with new sizes, a larger footprint, or a second storey as an option for the user to decide) or asks the user to choose; if it draws a test fit, it lists every changed room size next to the programme size",
+        "Any plan it draws is an SVG dimensioned in feet and inches, 30'-0\" × 24'-0\" overall, with a scale bar and a north arrow that puts the street on the west",
+        "Any plan it draws has the entry door on the west (street) wall, and every room can be reached from it",
+        "It does not invent rooms, a second storey stated as fact, or zoning rules that are not in the prompt or the programme"
+      ]
+    }
+  ]
+}

package/packs/civil-architect/skills/floor-plan-layout/evals/files/4/adu-programme.md

@@ -0,0 +1,12 @@
+# Okafor-Lindqvist ADU - space programme (draft 2)
+
+| Room | Size |
+|---|---|
+| Great room (living + dining) | 20 x 16 ft |
+| Kitchen | 12 x 12 ft |
+| Primary bedroom | 14 x 13 ft |
+| Bedroom 2 | 11 x 11 ft |
+| Bathroom | 9 x 6 ft |
+| Laundry | 8 x 6 ft |
+
+Single storey. Entry from the street side.

package/packs/civil-architect/skills/floor-plan-layout/examples/ground-floor.md

@@ -0,0 +1,65 @@
+# Worked example: ground floor on Plot 14
+
+## Input
+
+> *"Lay out the ground floor for the family house. Programme is in program.json (foyer,
+> living, dining, kitchen, utility, prayer room, guest toilet), footprint 10 m wide × 9 m
+> deep, road on the south side, front door from the road. Keep the prayer room away from the
+> kitchen and the toilet. Stair to the first floor."*
+
+## Zoning, decided before coordinates
+
+- Public front: foyer, then living along the road, so a guest never passes the kitchen.
+- Stair beside the foyer, so the first floor is reached without crossing the living room.
+- Service back: dining, kitchen, utility and toilet across the rear, with a back door from the hall for deliveries.
+- Wet rooms (kitchen, utility, toilet) side by side at the back, so drains run to one side of the plot and stack under the first-floor bathrooms.
+- Prayer room in the south-east corner, off the living room: an outside wall for a window, and the hall, not the kitchen or toilet, on its other side.
+
+## First draft: the checker caught it
+
+The first draft widened the kitchen to 3.2 m. The checker exited 1:
+
+```text
+FAIL Kitchen and Utility overlap by 0.46
+FAIL Kitchen and Toilet overlap by 0.38
+FAIL door 8 (Kitchen – Utility) at (6.6, 6) is not on a wall both sides share
+FAIL Utility cannot be reached from an entrance
+```
+
+The extra 0.2 m pushed the kitchen into the utility and the toilet. The utility door, moved
+to the kitchen's new wall, then sat inside the utility rather than on a wall the two share,
+so the utility could not be reached. Kitchen back to 3.0 m (12.6 m², its target).
+
+## `plan.json`
+
+See [`../templates/plan.json`](../templates/plan.json), unchanged.
+
+## Response
+
+**Plan:** [`ground-floor.svg`](ground-floor.svg). Public rooms along the road, service
+rooms across the back, the stair beside the foyer.
+
+| Room | Size (m) | Area (m²) | Target (m²) |
+|---|---|---:|---:|
+| Foyer | 2.5 × 2.4 | 6.0 | 6.0 |
+| Stair | 2.5 × 2.4 | 6.0 |  |
+| Living | 5.4 × 4.8 | 25.9 | 25.9 |
+| Prayer room | 2.1 × 2.2 | 4.6 | 4.5 |
+| Dining | 3.4 × 4.2 | 14.3 | 14.0 |
+| Kitchen | 3 × 4.2 | 12.6 | 12.6 |
+| Utility | 1.6 × 2.3 | 3.7 | 4.0 |
+| Toilet | 1.6 × 1.9 | 3.0 | 3.2 |
+| Hall | 2.1 × 2.6 + 2 × 4.2 | 13.9 |  |
+| **Rooms** | | **90.0** | |
+| **Outline** | | **90.0** | |
+
+PASS no overlaps, every door on a shared wall, every room reachable.
+
+**Off target:** utility 3.7 m² against 4 (−8 %) and toilet 3.0 against 3.2 (−6 %), both inside
+the 10 % tolerance, traded for keeping the toilet off the prayer room. The hall is 13.9 m²
+because it doubles as the back entrance; a tighter option moves the back door to the utility
+and gives the spare 4 m² to the kitchen.
+
+**What this plan is not:** schematic; walls drawn at a nominal 230 mm; no structure, services
+or bye-law check. The architect checks the toilet's ventilation and the stair's width against
+the local rules.