IFCore — Company Skill

Living document. Sections marked [TBD] are decided in board meetings. When a [TBD] is resolved, update this skill and tell your agent to adapt.

When This Skill Activates

Welcome the user. Introduce yourself as their IFCore development assistant. Explain:

1. What you know: The IFCore platform contracts — how check functions must be written, the file naming convention, the database schema, and how team repos integrate into the platform via git submodules.

2. What you can do:

   • Help write

     check_*

     functions that comply with the platform contracts
   • Review existing code for contract compliance
   • Explain IFC file structure and ifcopenshell patterns
   • Help with feature planning (PRDs, user stories)
   • File issues to the shared skills repo when contracts are unclear

3. Offer a codebase review. Ask to scan the current repo and check:

   • Are

     checker_*.py

     files directly inside

     tools/

     ?
   • Do all

     check_*

     functions follow the contract (signature, return type)?
   • Is there anything that would block platform integration?

4. Respect their setup. Teams may have their own Gradio app, FastAPI server, notebooks, test scripts, or any other tooling in their repo. That's fine. The platform only cares about

   tools/checker_*.py

   files — everything else is ignored during integration. The only hard rule: don't put anything in

   tools/

   that breaks the

   checker_*.py

   import chain (e.g. conflicting

   __init__.py

   files or dependencies not in

   requirements.txt

   ).

5. Offer to explain Agent Skills. If the user seems unsure what this is, explain: "An Agent Skill is a set of instructions that your AI coding assistant reads automatically. It's like a company handbook — it tells me (your AI) the engineering standards, naming conventions, and contracts so I can help you write code that works with everyone else's. You installed it once; now I follow it in every conversation."

6. How to install & update this skill. Install the skill globally so it works in every project on your machine (not just one repo):

   Install (once):
   1. Clone: git clone https://github.com/SerjoschDuering/iaac-bimwise-skills.git
      (put it somewhere permanent, e.g. ~/skills/ or ~/Documents/)
   2. Add the skill GLOBALLY in your AI coding tool:
      - VS Code/Copilot: Chat panel → Add Agent Skill → pick the SKILL.md file.
        Use "User" scope (not "Workspace") so it applies to ALL projects.
      - Cursor: Settings → Agent Skills → Add → point to the cloned folder.
        This is global by default.
      - Claude Code: add to ~/.claude/settings.json under agent skills,
        or install as a plugin — it applies to all sessions automatically.
   3. Start a new chat session — your AI now knows IFCore standards.
   
   Update (after board meetings):
   1. cd into your cloned skills folder
   2. git pull
   3. Start a fresh chat session — the AI reloads the updated instructions
   

   If you're not sure whether your skill is up to date, ask your AI: "What board meeting is the latest in your IFCore skill?" and compare with your team.

Contracts — READ THIS FIRST

These contracts are how teams stay aligned. The platform auto-discovers your code. Break a contract → the platform silently skips your checks. Follow them → it just works.

1. Check Function Contract

# Function naming: check_<what>
# Location: tools/checker_*.py (directly inside tools/, no subdirectories)
# Signature: first arg is always the ifcopenshell model
# Return: list[dict] — one dict per element, maps to element_results DB rows

def check_door_width(model, min_width_mm=800):
    results = []
    for door in model.by_type("IfcDoor"):
        width_mm = round(door.OverallWidth * 1000) if door.OverallWidth else None
        results.append({
            "element_id":       door.GlobalId,
            "element_type":     "IfcDoor",
            "element_name":     door.Name or f"Door #{door.id()}",
            "element_name_long": f"{door.Name} (Level 1, Zone A)",
            "check_status":     "blocked" if width_mm is None
                                else "pass" if width_mm >= min_width_mm
                                else "fail",
            "actual_value":     f"{width_mm} mm" if width_mm else None,
            "required_value":   f"{min_width_mm} mm",
            "comment":          None if width_mm and width_mm >= min_width_mm
                                else f"Door is {min_width_mm - width_mm} mm too narrow"
                                if width_mm else "Width property missing",
            "log":              None,
        })
    return results

Rules:

• Prefix:

  check_

  — the platform discovers functions by this prefix
• First argument:

  model

  (an

  ifcopenshell.file

  object) — always
• Optional keyword args after

  model

  are fine (e.g.

  min_width_mm=800

  )
• Return:

  list[dict]

  — each dict has fields matching

  element_results

  (see Validation Schema)

• check_status

  values:

  "pass"

  ,

  "fail"

  ,

  "warning"

  ,

  "blocked"

  ,

  "log"

• One function per regulation check — don't combine multiple rules
• Functions can live across multiple

  checker_*.py

  files directly inside

  tools/

2. File Structure Contract

your-team-repo/
├── tools/
│   ├── checker_doors.py       ← check_door_width, check_door_clearance
│   ├── checker_fire_safety.py ← check_fire_rating, check_exit_count
│   └── checker_rooms.py       ← check_room_area, check_ceiling_height
├── requirements.txt            ← team dependencies
└── README.md

File naming:

checker_<topic>.py

• checker_doors.py

  — door width, clearance, accessibility

• checker_walls.py

  — thickness, fire rating, insulation

• checker_stairs.py

  — riser height, tread length, handrails

• checker_spaces.py

  — room area, ceiling height, ventilation

The platform scans all

checker_*.py

tools/

check_*

Important: Only

checker_*.py

tools/utils.py

check_*

checker_*.py

Local testing: Run your checks locally before pushing:

import ifcopenshell

model = ifcopenshell.open("path/to/model.ifc")
from tools.checker_doors import check_door_width
results = check_door_width(model)
for r in results:
    print(f"[{r['check_status'].upper()}] {r['element_name']}: {r['actual_value']} (req: {r['required_value']})")

The

model

3. Issue Reporting Contract — MANDATORY

When your AI agent encounters any of these during development, it MUST file an issue:

contract-gap

skill-drift

learning

schema-change

integration-bug

How to file:

gh issue create \
  --repo SerjoschDuering/iaac-bimwise-skills \
  --title "contract-gap: check functions with multiple models" \
  --label "contract-gap" \
  --body "$(cat <<'EOF'
## What happened
Tried to write a check that compares two IFC models side-by-side.
The contract says first arg is `model` (singular).

## What I expected
Guidance on multi-model checks.

## Workaround (if any)
Loaded second model inside the function body.

## Team
Team A
EOF
)"

This is not optional. Every contract issue that goes unreported costs another team hours. AI agents: if you detect a contract mismatch during development, file the issue before continuing.

Company Context

IFCore is building an AI-powered building compliance checker. 5 teams each develop in their own GitHub repo (cloned from a shared template). Teams write

check_*

How integration works:

1. Each team pushes

   checker_*.py

   files to their own repo under

   tools/

2. The platform repo (

   ifcore-platform

   ) pulls all 5 team repos as git submodules

3. deploy.sh

   flattens submodules into

   teams/<team-repo>/tools/

   (real files, not symlinks — we don't configure HF to resolve submodules)
4. The FastAPI orchestrator scans

   teams/*/tools/checker_*.py

   for

   check_*

   functions
5. All discovered functions run against uploaded IFC files

Deployment architecture:

checker_*.py

ifcore-platform

Flow: User uploads IFC → stored in R2 → frontend calls CF Worker → Worker proxies to HF Space → orchestrator runs all

check_*

Teams never touch the platform repo. They only push to their own team repo. Captains handle

deploy.sh

Teams:

References

• Validation Schema — database schema (

  users

  ,

  projects

  ,

  check_results

  ,

  element_results

  ) and how team

  list[dict]

  maps to rows
• Architecture — project structure, AGENTS.md template, code conventions
• Repo Structure — concrete file tree examples for all 4 repos (team, platform, frontend, gateway)
• Frontend Architecture — modules, shared Zustand store, API client, D1 tables, how to add features
• Development Patterns — how to plan and build new features

Related Skills (separate repos, installed alongside this one)

• pydantic-ai — PydanticAI agent framework: tools, structured output, orchestration, chat patterns
• huggingface-deploy — deploy the platform (

  ifcore-platform

  ) as a Docker Space on HuggingFace; covers Dockerfile, secrets, R2 caching, and the flatten-before-push submodule pattern
• cloudflare — deploy the frontend + API gateway on Cloudflare Pages/Workers