katalyst-forge 2.1.0__py3-none-any.whl

katalyst_forge/__init__.py

@@ -0,0 +1,10 @@
+"""katalyst-forge — The Forge bundle for katalyst-engine.
+
+Provides 33 node-type definitions across 8 wings for software delivery taxonomy.
+"""
+
+from __future__ import annotations
+
+from katalyst_forge.bundle import ForgeBundle
+
+__all__ = ["ForgeBundle"]

katalyst_forge/bundle.py

@@ -0,0 +1,175 @@
+"""Forge bundle — the pre-installed taxonomy for software delivery.
+
+Assembles 33 node types across 8 wings from the wing modules into
+a single ``ForgeBundle`` that implements the engine's ``Bundle``
+protocol. Discovered via the ``katalyst_engine.bundles`` entry point.
+
+"Forge" — where delivery artifacts are forged.
+
+Wing modules:
+- ``wings/system.py``    — system, environment, stack, layer, library, capability
+- ``wings/org.py``       — organization, program, project, team, team_member, role
+- ``wings/practices.py`` — practice_area, competency, skill, tool
+- ``wings/design.py``    — business_domain_model, user_type, user_story, adr, nfr, specification, assertion
+- ``wings/delivery.py``  — work_item, change_entry
+- ``wings/dx.py``        — template, action, template_overlay
+- ``wings/pipeline.py``  — cicd_stage, cicd_job_template, cicd_workflow_template
+- ``wings/agentic.py``   — agent, agent_skill
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from katalyst_engine.bundle.protocol import BundleManifest
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.version import Version
+from katalyst_engine.schema.definition import (
+    NodeDefinition,
+    RelationshipDefinition,
+    SchemaDefinition,
+    WingDefinition,
+)
+from katalyst_engine.schema.manager import SchemaManager
+
+from katalyst_forge.relationships import ALL_RELATIONSHIP_DEFINITIONS
+from katalyst_forge.wings.agentic import AGENTIC_WING, AGENTIC_WING_NODES
+from katalyst_forge.wings.delivery import DELIVERY_WING, DELIVERY_WING_NODES
+from katalyst_forge.wings.design import DESIGN_WING, DESIGN_WING_NODES
+from katalyst_forge.wings.dx import DX_WING, DX_WING_NODES
+from katalyst_forge.wings.org import ORG_WING, ORG_WING_NODES
+from katalyst_forge.wings.pipeline import PIPELINE_WING, PIPELINE_WING_NODES
+from katalyst_forge.wings.practices import PRACTICES_WING, PRACTICES_WING_NODES
+from katalyst_forge.wings.system import SYSTEM_WING, SYSTEM_WING_NODES
+
+# ---------------------------------------------------------------------------
+# Aggregate all definitions from wing modules
+# ---------------------------------------------------------------------------
+
+ALL_NODE_DEFINITIONS: list[NodeDefinition] = [
+    *SYSTEM_WING_NODES,
+    *ORG_WING_NODES,
+    *PRACTICES_WING_NODES,
+    *DESIGN_WING_NODES,
+    *DELIVERY_WING_NODES,
+    *DX_WING_NODES,
+    *PIPELINE_WING_NODES,
+    *AGENTIC_WING_NODES,
+]
+
+ALL_KINDS: frozenset[str] = frozenset(nd.describes_kind for nd in ALL_NODE_DEFINITIONS)
+
+ALL_WING_DEFINITIONS: list[WingDefinition] = [
+    SYSTEM_WING,
+    ORG_WING,
+    DESIGN_WING,
+    DELIVERY_WING,
+    PRACTICES_WING,
+    DX_WING,
+    PIPELINE_WING,
+    AGENTIC_WING,
+]
+
+ALL_WING_NAMES: frozenset[str] = frozenset(wd.identity.name for wd in ALL_WING_DEFINITIONS)
+
+
+# ---------------------------------------------------------------------------
+# Bundle class
+# ---------------------------------------------------------------------------
+
+
+class ForgeBundle:
+    """The Forge bundle — 33 node types across 8 wings.
+
+    This is the pre-installed taxonomy bundle that ships with
+    Katalyst Taxonomy. It models software delivery organizations
+    using systems, stacks, layers, teams, practices, and more.
+
+    "Forge" — where delivery artifacts are forged.
+    """
+
+    @property
+    def manifest(self) -> BundleManifest:
+        return BundleManifest(
+            identity=Identity(kind="bundle", name="forge"),
+            version=Version(major=2, minor=0),
+            provided_kinds=ALL_KINDS,
+            wing_names=ALL_WING_NAMES,
+            description="Forge taxonomy — 33 node types for modeling software delivery organizations",
+        )
+
+    def node_definitions(self) -> list[NodeDefinition]:
+        return list(ALL_NODE_DEFINITIONS)
+
+    def wing_definitions(self) -> list[WingDefinition]:
+        return list(ALL_WING_DEFINITIONS)
+
+    def relationship_definitions(self) -> list[RelationshipDefinition]:
+        return list(ALL_RELATIONSHIP_DEFINITIONS)
+
+    def schema_definition(self) -> SchemaDefinition:
+        return SchemaDefinition(
+            identity=Identity(kind="schema", name="forge"),
+            describes_kind="taxonomy",
+            api_version="v2alpha",
+            schema_version=Version(major=2),
+            node_definitions=tuple(nd.identity for nd in ALL_NODE_DEFINITIONS),
+            wing_definitions=tuple(wd.identity for wd in ALL_WING_DEFINITIONS),
+        )
+
+    def register(self, manager: SchemaManager) -> None:
+        manager.register_schema(
+            self.schema_definition(),
+            node_definitions=self.node_definitions(),
+            wing_definitions=self.wing_definitions(),
+            relationship_definitions=self.relationship_definitions(),
+        )
+
+    # ------------------------------------------------------------------
+    # Optional template declarations
+    # ------------------------------------------------------------------
+
+    def creation_templates(self) -> dict[str, str]:
+        """Return the 7 creation templates for Forge node types.
+
+        Templates are Jinja2-rendered ``.yaml.j2`` files that produce
+        the taxonomy YAML document when a node is created. The ``_base``
+        key provides a generic fallback for kinds without a dedicated
+        template.
+
+        Returns:
+            Mapping of kind name (or ``"_base"``) to template content.
+        """
+        creation_dir = Path(__file__).parent / "templates" / "creation"
+        templates: dict[str, str] = {}
+        if not creation_dir.is_dir():
+            return templates
+        for template_file in sorted(creation_dir.glob("*.yaml.j2")):
+            if template_file.name.startswith("_"):
+                # _base.yaml.j2 → key "_base"
+                key = template_file.stem.split(".")[0]  # "_base"
+            else:
+                # system.yaml.j2 → key "system"
+                key = template_file.stem.split(".")[0]
+            templates[key] = template_file.read_text(encoding="utf-8")
+        return templates
+
+    def scaffold_templates(self) -> dict[str, Path]:
+        """Return scaffold template directories for layer variants.
+
+        Each subdirectory under ``templates/bundled/plugins/layer_types/``
+        is a scaffold variant (e.g. ``app-docker``, ``iac-terragrunt``).
+        Keys use the format ``layer:{variant}`` so the scaffolding plugin
+        can look up templates by ``(node_kind, scaffold_variant)``.
+
+        Returns:
+            Mapping of ``"layer:{variant}"`` to the scaffold directory path.
+        """
+        scaffold_dir = Path(__file__).parent / "templates" / "scaffolds"
+        result: dict[str, Path] = {}
+        if not scaffold_dir.is_dir():
+            return result
+        for child in sorted(scaffold_dir.iterdir()):
+            if child.is_dir():
+                result[f"layer:{child.name}"] = child
+        return result

katalyst_forge/relationships.py

@@ -0,0 +1,263 @@
+"""Relationship definitions for the Forge bundle."""
+
+from __future__ import annotations
+
+from katalyst_engine.core.identity import Identity
+from katalyst_engine.core.relation import Cardinality
+from katalyst_engine.schema.definition import RelationshipDefinition
+
+
+def _rel_id(name: str) -> Identity:
+    return Identity(kind="relationship_definition", name=name)
+
+
+# ── Structural wing ───────────────────────────────────────────────────
+
+CHILD_OF_REL = RelationshipDefinition(
+    identity=_rel_id("child_of"),
+    describes_kind="child_of",
+    description="Hierarchical parent-child containment",
+    wing="structural",
+    display_order=10,
+    cardinality=Cardinality.MANY_TO_ONE,
+    directed=True,
+    structural=True,
+)
+
+EXTENDS_REL = RelationshipDefinition(
+    identity=_rel_id("extends"),
+    describes_kind="extends",
+    description="Node augments target with additional behavior or configuration",
+    wing="structural",
+    display_order=20,
+    cardinality=Cardinality.MANY_TO_MANY,
+    directed=True,
+    structural=True,
+)
+
+DEPENDS_ON_REL = RelationshipDefinition(
+    identity=_rel_id("depends_on"),
+    describes_kind="depends_on",
+    description="Runtime or build dependency between nodes",
+    wing="structural",
+    display_order=30,
+    cardinality=Cardinality.MANY_TO_MANY,
+    directed=True,
+    structural=True,
+)
+
+DEPLOYS_TO_REL = RelationshipDefinition(
+    identity=_rel_id("deploys_to"),
+    describes_kind="deploys_to",
+    description="Node is deployed to an environment",
+    wing="structural",
+    display_order=40,
+    cardinality=Cardinality.MANY_TO_MANY,
+    directed=True,
+    structural=True,
+)
+
+# ── Capability wing ──────────────────────────────────────────────────
+
+PROVIDES_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("provides_capability"),
+    describes_kind="provides_capability",
+    description="System, stack, or layer provides a capability",
+    wing="capability",
+    display_order=100,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+REQUIRES_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("requires_capability"),
+    describes_kind="requires_capability",
+    description="User story requires a capability",
+    wing="capability",
+    display_order=110,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+DEPENDS_ON_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("depends_on_capability"),
+    describes_kind="depends_on_capability",
+    description="Capability depends on another capability",
+    wing="capability",
+    display_order=120,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+SPECIFIES_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("specifies_capability"),
+    describes_kind="specifies_capability",
+    description="Specification defines requirements for a capability",
+    wing="capability",
+    display_order=130,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+TESTS_CAPABILITY_REL = RelationshipDefinition(
+    identity=_rel_id("tests_capability"),
+    describes_kind="tests_capability",
+    description="Assertion verifies a capability",
+    wing="capability",
+    display_order=140,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+# ── Organizational wing ──────────────────────────────────────────────
+
+FILLED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("filled_by"),
+    describes_kind="filled_by",
+    description="Role is filled by team members",
+    wing="organizational",
+    display_order=200,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+DEVELOPS_COMPETENCY_REL = RelationshipDefinition(
+    identity=_rel_id("develops_competency"),
+    describes_kind="develops_competency",
+    description="Practice area develops a competency",
+    wing="organizational",
+    display_order=210,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+USES_TOOL_REL = RelationshipDefinition(
+    identity=_rel_id("uses_tool"),
+    describes_kind="uses_tool",
+    description="Practice area uses a tool",
+    wing="organizational",
+    display_order=220,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+REQUIRES_SKILL_REL = RelationshipDefinition(
+    identity=_rel_id("requires_skill"),
+    describes_kind="requires_skill",
+    description="Competency requires a skill",
+    wing="organizational",
+    display_order=230,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+# ── Verification wing ────────────────────────────────────────────────
+
+VERIFIED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("verified_by"),
+    describes_kind="verified_by",
+    description="Specification is verified by assertions",
+    wing="verification",
+    display_order=300,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+TESTS_SPECIFICATION_REL = RelationshipDefinition(
+    identity=_rel_id("tests_specification"),
+    describes_kind="tests_specification",
+    description="Assertion tests a specification",
+    wing="verification",
+    display_order=310,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+CAPTURES_STORY_REL = RelationshipDefinition(
+    identity=_rel_id("captures_story"),
+    describes_kind="captures_story",
+    description="Specification captures a user story",
+    wing="verification",
+    display_order=320,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+# ── Workflow wing ─────────────────────────────────────────────────────
+
+BLOCKS_REL = RelationshipDefinition(
+    identity=_rel_id("blocks"),
+    describes_kind="blocks",
+    description="Work item blocks another work item",
+    wing="workflow",
+    display_order=400,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+BLOCKED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("blocked_by"),
+    describes_kind="blocked_by",
+    description="Work item is blocked by another work item",
+    wing="workflow",
+    display_order=410,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+SUPERSEDED_BY_REL = RelationshipDefinition(
+    identity=_rel_id("superseded_by"),
+    describes_kind="superseded_by",
+    description="ADR is superseded by another ADR",
+    wing="workflow",
+    display_order=420,
+    cardinality=Cardinality.MANY_TO_ONE,
+)
+
+REFERENCES_ROAD_ITEM_REL = RelationshipDefinition(
+    identity=_rel_id("references_road_item"),
+    describes_kind="references_road_item",
+    description="Change entry references a road item",
+    wing="workflow",
+    display_order=430,
+    cardinality=Cardinality.MANY_TO_ONE,
+)
+
+# ── Pipeline wing ────────────────────────────────────────────────────
+
+STAGE_DEPENDS_ON_REL = RelationshipDefinition(
+    identity=_rel_id("stage_depends_on"),
+    describes_kind="stage_depends_on",
+    description="CI/CD stage depends on another stage",
+    wing="pipeline",
+    display_order=500,
+    cardinality=Cardinality.MANY_TO_MANY,
+)
+
+BELONGS_TO_STAGE_REL = RelationshipDefinition(
+    identity=_rel_id("belongs_to_stage"),
+    describes_kind="belongs_to_stage",
+    description="CI/CD job template belongs to a stage",
+    wing="pipeline",
+    display_order=510,
+    cardinality=Cardinality.MANY_TO_ONE,
+)
+
+# ── Aggregate list ────────────────────────────────────────────────────
+
+ALL_RELATIONSHIP_DEFINITIONS: list[RelationshipDefinition] = [
+    # structural
+    CHILD_OF_REL,
+    EXTENDS_REL,
+    DEPENDS_ON_REL,
+    DEPLOYS_TO_REL,
+    # capability
+    PROVIDES_CAPABILITY_REL,
+    REQUIRES_CAPABILITY_REL,
+    DEPENDS_ON_CAPABILITY_REL,
+    SPECIFIES_CAPABILITY_REL,
+    TESTS_CAPABILITY_REL,
+    # organizational
+    FILLED_BY_REL,
+    DEVELOPS_COMPETENCY_REL,
+    USES_TOOL_REL,
+    REQUIRES_SKILL_REL,
+    # verification
+    VERIFIED_BY_REL,
+    TESTS_SPECIFICATION_REL,
+    CAPTURES_STORY_REL,
+    # workflow
+    BLOCKS_REL,
+    BLOCKED_BY_REL,
+    SUPERSEDED_BY_REL,
+    REFERENCES_ROAD_ITEM_REL,
+    # pipeline
+    STAGE_DEPENDS_ON_REL,
+    BELONGS_TO_STAGE_REL,
+]

katalyst_forge/templates/creation/_base.yaml.j2

@@ -0,0 +1,12 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: {{ node_type }}
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    templateVersion: "{{ template_version }}"
+{{ parents_block }}  environments:
+{{ environments_block }}

katalyst_forge/templates/creation/layer.yaml.j2

@@ -0,0 +1,21 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: layer
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    layout: root
+    layerType: "{{ layer_type }}"
+    templateVersion: "{{ template_version }}"
+    layerTypeVersion: "{{ layer_type_version }}"
+  parents:
+    node: "{{ parent_stack }}"
+  environments:
+{{ environments_block }}
+  dependsOn:
+    nodes:
+      - "{{ parent_stack }}"
+  extensions: {}

katalyst_forge/templates/creation/project.yaml.j2

@@ -0,0 +1,16 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: project
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    templateVersion: "{{ template_version }}"
+  parents:
+    node: "{{ parent }}"
+  environments:
+{{ environments_block }}
+  project:
+    status: active

katalyst_forge/templates/creation/stack.yaml.j2

@@ -0,0 +1,18 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: stack
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    layout: root
+    templateVersion: "{{ template_version }}"
+  parents:
+    node: "{{ parent_system }}"
+  environments:
+{{ environments_block }}
+  dependsOn:
+    nodes:
+      - "{{ parent_system }}"

katalyst_forge/templates/creation/system.yaml.j2

@@ -0,0 +1,15 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: system
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    layout: root
+    templateVersion: "{{ template_version }}"
+{{ parents_block }}  environments:
+{{ environments_block }}
+  dependsOn:
+    nodes: []

katalyst_forge/templates/creation/team.yaml.j2

@@ -0,0 +1,16 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: team
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    templateVersion: "{{ template_version }}"
+  parents:
+    node: "{{ parent }}"
+  environments:
+{{ environments_block }}
+  team:
+    unitType: squad

katalyst_forge/templates/creation/team_member.yaml.j2

@@ -0,0 +1,17 @@
+apiVersion: katalyst.taxonomy/v2alpha
+kind: team_member
+metadata:
+  name: "{{ name }}"
+spec:
+  description: "{{ description }}"
+  owners:
+    - "{{ primary_owner }}"
+  annotations:
+    templateVersion: "{{ template_version }}"
+  parents:
+    node: "{{ parent }}"
+  environments:
+{{ environments_block }}
+  teamMember:
+    role: engineer
+    email: "{{ primary_owner }}"

katalyst_forge/templates/scaffolds/app-docker/.dockerignore

@@ -0,0 +1,51 @@
+# Git
+.git
+.gitignore
+
+# Documentation
+*.md
+docs/
+
+# Tests
+tests/
+test/
+__tests__/
+*.test.js
+*.spec.js
+coverage/
+
+# Development files
+.env.local
+.env.development
+.env*.local
+*.log
+
+# IDE and editor
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# OS files
+.DS_Store
+Thumbs.db
+
+# Node.js
+node_modules/
+npm-debug.log*
+
+# Build artifacts (if building outside Docker)
+dist/
+build/
+*.tsbuildinfo
+
+# Taxonomy files (not needed in container)
+layer.yaml
+*.yaml
+!docker-compose.yaml
+
+# Docker files (avoid recursion)
+Dockerfile*
+docker-compose*.yaml
+.dockerignore

katalyst_forge/templates/scaffolds/app-docker/.env.example

@@ -0,0 +1,14 @@
+# Environment configuration for {{ layer_name }}
+# Copy this file to .env and adjust values for your environment
+
+# Application
+NODE_ENV=development
+LOG_LEVEL=debug
+
+# Server
+HOST_PORT=8080
+
+# Add your environment-specific variables below
+# DATABASE_URL=postgres://user:pass@localhost:5432/db
+# REDIS_URL=redis://localhost:6379
+# API_KEY=your-api-key

katalyst_forge/templates/scaffolds/app-docker/README.md

@@ -0,0 +1,40 @@
+# {{ system_name }}/{{ stack_name }}/{{ layer_name }} layer
+
+Layer type: app-docker
+
+This scaffold creates a Docker-based application structure:
+
+- `layer.yaml` - taxonomy node descriptor.
+- `Dockerfile` - multi-stage Docker build.
+- `docker-compose.yaml` - local development orchestration.
+- `.dockerignore` - files excluded from Docker context.
+- `<environment>/` - environment-specific configuration.
+
+Copy `env-template/` for each environment and adjust the configuration files.
+
+## Local Development
+
+```bash
+# Build the image
+docker compose build
+
+# Run locally
+docker compose up
+
+# Run with environment overrides
+docker compose --env-file ./dev/.env up
+```
+
+## Building for Production
+
+```bash
+# Build with specific tag
+docker build -t {{ layer_name }}:latest .
+
+# Build for specific environment
+docker build --build-arg ENVIRONMENT=prod -t {{ layer_name }}:prod .
+```
+
+<!-- BEGIN AUTO-LAYER -->
+<!-- This section is managed by scripts. Manual edits inside may be overwritten. -->
+<!-- END AUTO-LAYER -->