ifcore

name: IFCore description: Use when developing on the IFCore compliance checker. Covers contracts, check function conventions, issue reporting, app structure, and development patterns.

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 — group related checks by topic. Examples:

• 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 files directly inside tools/ (no subdirectories) and collects every check_* function. You don't need a wrapper or registry — just follow the naming conventions.

Important: Only checker_*.py files are scanned. Helper files (e.g. tools/utils.py) are fine for shared code but won't be scanned for check_* functions — import them from your checker_*.py files.

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 object is exactly what the platform passes to your functions.

3. Issue Reporting Contract — MANDATORY

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

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_* functions independently — the platform integrates them automatically.

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:

Flow: User uploads IFC → stored in R2 → frontend calls CF Worker → Worker proxies to HF Space → orchestrator runs all check_* functions → results posted back to Worker → stored in D1 → frontend polls and displays.

Teams never touch the platform repo. They only push to their own team repo. Captains handle deploy.sh which pulls, flattens, and pushes to HF.

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