+
+## Engineering guidance that adapts to the project
+
+A self-contained, language-agnostic knowledge base and policy system for AI coding agents — presented here as a browsable engineering handbook.
+
+[Browse the 72 principles](principles/index.md){ .md-button .md-button--primary }
+[Explore the decision system](core/index.md){ .md-button }
+
+
+
+
+
+
+
+### Principles
+
+Canonical engineering ideas with explicit applicability, rejected interpretations, trade-offs, conflicts, examples, and AI guidance.
+
+[Browse principles →](principles/index.md)
+
+
+
+
+
+### Core Skills
+
+Decision procedures that combine principles into practical modes for clarity, abstraction, testing, compatibility, reliability, performance, and more.
+
+[Explore Core Skills →](core/index.md)
+
+
+
+
+
+### Project profiles
+
+Start from what you are building: application, library, service, worker, pipeline, plugin, prototype, CLI, real-time system, infrastructure tool, and more.
+
+[Choose a project profile →](profiles/index.md)
+
+
+
+
+
+### Technology refinements
+
+See how generic policy is refined for JavaScript, TypeScript, Python, PHP, Go, C++, React, Next.js, Vue, Nuxt, Angular, Symfony, and Drupal.
+
+[Browse languages →](languages/index.md) · [Browse frameworks →](frameworks/index.md)
+
+
+
+
+
1Project evidencetask, repository, explicit context
+
→
+
2Project profiledominant artifact and failure model
+
→
+
3Modifiersverified cross-cutting constraints
+
→
+
4Core Skillscontext-sensitive decision modes
+
→
+
5Technology adapterslanguage and framework semantics
+
→
+
6Resolved policyexplainable engineering decisions
+
No matching entries.
+"""
+
+
+def generate_principles() -> None:
+ registry = load_yaml(ROOT / "principles" / "registry.yaml")
+ categories = {
+ item["id"]: item["name"]
+ for item in load_yaml(ROOT / "principles" / "categories.yaml")["categories"]
+ }
+ principles = registry["principles"]
+ groups = []
+ for category_id, category_name in categories.items():
+ group = [item for item in principles if item["category"] == category_id]
+ if not group:
+ continue
+ rows = []
+ for item in sorted(group, key=lambda value: value["name"]):
+ entry = load_yaml(ROOT / item["source"])
+ name = html.escape(entry["name"])
+ summary = html.escape(entry["summary"])
+ classification = html.escape(entry["classification"])
+ search_text = html.escape(
+ f"{entry['name']} {entry['id']} {entry['summary']} {entry['classification']} {category_name}".lower(),
+ quote=True,
+ )
+ rows.append(
+ f'No matching principles.
+"""
+ write("principles/index.md", page)
+
+
+def load_components(directory: str, metadata_name: str) -> list[dict]:
+ items = []
+ for metadata in sorted((ROOT / directory).glob(f"*/{metadata_name}")):
+ data = load_yaml(metadata)
+ if data:
+ items.append(data)
+ return items
+
+
+def generate_component_hubs() -> None:
+ skills = load_components("core", "skill.yaml")
+ write(
+ "core/index.md",
+ catalog_page(
+ "Core Skills",
+ "Core Skills turn canonical principles into language-independent decision procedures. Choose a Skill to inspect its modes, conflicts, and review rules.",
+ cards(skills),
+ len(skills),
+ ),
+ )
+
+ profiles = load_components("profiles", "profile.yaml")
+ write(
+ "profiles/index.md",
+ catalog_page(
+ "Project profiles",
+ "Profiles configure the dominant artifact and failure model before language or framework refinements are applied.",
+ cards(profiles),
+ len(profiles),
+ ),
+ )
+
+ modifiers = load_components("modifiers", "modifier.yaml")
+ write(
+ "modifiers/index.md",
+ catalog_page(
+ "Engineering modifiers",
+ "Modifiers strengthen policy when a verified cross-cutting constraint applies. They never replace the base project profile.",
+ cards(modifiers),
+ len(modifiers),
+ ),
+ )
+
+ languages = load_components("languages", "adapter.yaml")
+ write(
+ "languages/index.md",
+ catalog_page(
+ "Language adapters",
+ "Language adapters refine generic engineering policy with runtime, type-system, packaging, concurrency, and resource semantics.",
+ cards(languages),
+ len(languages),
+ ),
+ )
+
+ frameworks = load_components("frameworks", "adapter.yaml")
+ write(
+ "frameworks/index.md",
+ catalog_page(
+ "Framework adapters",
+ "Framework adapters refine project policy with lifecycle, boundary, state, extension, and convention decisions.",
+ cards(frameworks),
+ len(frameworks),
+ ),
+ )
+
+
+def generate_evaluations() -> None:
+ scenario_dir = ROOT / "evaluations" / "scenarios"
+ scenarios = []
+ for path in sorted(scenario_dir.glob("*.yaml")):
+ data = load_yaml(path) or {}
+ scenario_id = data.get("id", path.stem)
+ title = data.get("name") or data.get("title") or scenario_id.replace("-", " ").title()
+ request = ((data.get("input") or {}).get("request") or "")
+ scenarios.append((scenario_id, title, request, path.name))
+
+ rows = []
+ for scenario_id, title, request, filename in scenarios:
+ description = html.escape(str(request)) if request else "Executable policy scenario"
+ search_text = html.escape(f"{scenario_id} {title} {request}".lower(), quote=True)
+ rows.append(
+ f'