katalyst-taxonomy 0.15.0

A taxonomy management system for software architecture

Katalyst Taxonomy

Define, organize, and manage your software architecture as code.

Katalyst Taxonomy is a declarative framework for modeling your infrastructure and organization as a hierarchical tree. The Technical Wing organizes systems, subsystems, stacks, and layers; the Portfolio Wing tracks organizations, programs, and projects; and the Organizational Wing maps teams and team members. It brings structure to complex architectures, enabling consistent scaffolding, automated discovery, and seamless CI/CD integration.

---

Why Katalyst?

Modern software architectures sprawl across hundreds of services, each with their own conventions, configurations, and tribal knowledge. Teams struggle with:

• Inconsistent naming - Every service structured differently
• Lost knowledge - New team members can't discover what exists
• Manual scaffolding - Copy-paste leads to drift and errors
• Fragile automation - CI/CD pipelines hardcode paths and assumptions

Katalyst solves these problems by providing a single source of truth for your architecture, expressed as simple YAML files that both humans and tools can understand.

Learn more about why Katalyst

---

Key Features

Feature	Description
Hierarchical Modeling	Technical (System > Subsystem > Stack > Layer), Portfolio (Organization > Program > Project), and Organizational (Organization > Team > Team Member) hierarchies
Declarative YAML	Simple, version-controlled architecture definitions
Schema Validation	Catch errors early with JSON Schema validation
Scaffolding Templates	Generate consistent project structures from layer types
Interactive TUI	Browse and manage your taxonomy visually
Environment-Aware	First-class support for dev/staging/prod environments
Extensible Plugins	57 bundled actions, 12 tools, 4 layer types, git hook management — extend with your own
Git Hook Integration	CommitGuard plugin maps kata actions to pre-commit, Husky, or Lefthook hooks
AI Agents & Skills	Bundled AI coding assistants with taxonomy-aware context

---

Quick Start

Install in Your Repository

# Install Katalyst (requires Python 3.12+)
pip install katalyst-taxonomy

# Initialize a new taxonomy in your repo
kata tax init --yes

# See what was created
kata tax tree

Create Your First Architecture

# Create a system (root of your architecture)
kata tax create system my-platform \
  -d "My application platform" \
  -O [e-mail] \
  -e dev -e prod

# Create a subsystem (logical grouping)
kata tax create subsystem backend \
  --parent my-platform \
  -d "Backend services" \
  -O [e-mail] \
  -e dev -e prod

# Create a stack (deployable component)
kata tax create stack api \
  --parent backend \
  -d "REST API service" \
  -O [e-mail] \
  -e dev -e prod

# Create a layer with scaffolding
kata tax create layer app \
  --parent api \
  --parent-subsystem backend \
  --parent-system my-platform \
  --layer-type app-docker \
  -d "API application container" \
  -O [e-mail] \
  -e dev -e prod

# View your taxonomy
kata tax tree

Output:

my-platform [system]
 backend [subsystem]
    api [stack]
       app [layer]

Explore Interactively

# Launch the terminal UI
uv run python -m katalyst.tui

# Keyboard: arrows to navigate, 'n' to create, 'c' to clone, 'q' to quit

---

Documentation

Guide	Description
Why Katalyst	Value proposition and use cases
Getting Started	Installation and first taxonomy
Core Concepts	Hierarchy, FQTNs, environments
CLI Reference	Complete command documentation
TUI Guide	Interactive terminal interface
Agents & Skills	AI coding assistants for your taxonomy
Layer Types	Built-in scaffolding templates

For Plugin Developers

Guide	Description
Plugin Architecture	How plugins work
Creating Layer Types	Custom scaffolding templates
Creating Actions	Executable layer commands

For Contributors

Guide	Description
Contributing Guide	How to contribute
Architecture	Codebase design
Development Setup	Local environment

---

CLI Commands

# View commands
kata tax tree                    # Hierarchical tree view
kata tax list                    # Detailed list by type
kata tax json                    # Export as JSON
kata tax get <name>              # Get specific node

# Management
kata tax init                    # Initialize taxonomy in repo
kata tax create <type> <name>    # Create new node
kata tax add --layer-type <name> # Add layer type templates
kata tax remove --layer-type <n> # Remove layer type
kata tax upgrade                 # Upgrade installed components
kata tax upgrade --item <name>   # Upgrade a specific item

# Validation
kata tax lint                    # Validate against schemas
kata tax status                  # Show installed components

# AI Agents
kata tax agents init             # Initialize .agents/ and seed bundled agents/skills
kata tax agents list             # List agents and skills (local + bundled)
kata tax agents create <name>    # Create new agent
kata tax agents generate         # Generate from templates
kata tax agents sync             # Sync bundled content after upgrades
kata tax agents validate         # Validate definitions

# File Resolution
kata tax resolve --files <path>...  # Map files to layer FQTNs

# Git Hooks
kata tax hooks detect-tool           # Show configured hook tool
kata tax hooks generate --tool <t>   # Generate native hook config
kata tax hooks run                   # Run actions on affected layers
kata tax hooks validate              # Validate hook config

---

Built-in Layer Types

Type	Description
app-docker	Docker container application with multi-stage build
k8s-kustomize	Kubernetes manifests with Kustomize overlays
k8s-argocd	Argo CD application with GitOps workflow
iac-terragrunt	Terraform modules with Terragrunt wrapper

Add more with kata tax add --layer-type <name> or create your own.

---

Project Structure

After kata tax init, your repository will have:

your-repo/
 .global/
    taxonomy/
       taxonomy.lock    # Tracks installed components
       layer_types/           # Layer type templates
          app-docker/
          k8s-kustomize/
          ...
       actions/               # Action definitions + Just recipes
       commitguard/           # Git hook bindings
       extensions/            # Extension plugins
       capabilities/          # Capability declarations
       cicd/                  # CI/CD templates
 .agents/                        # AI agent definitions
    agents.yaml                 # Configuration
    agents/                     # Agent .md files
    skills/                     # Skill packages
 .taxignore                   # Paths to exclude from discovery

Your taxonomy nodes live alongside your code:

your-repo/
 system.yaml                  # System definition
 backend/
    sub_system.yaml          # Subsystem definition
    api/
       stack.yaml            # Stack definition
       app/
          layer.yaml         # Layer definition
          Dockerfile         # Scaffolded from layer type
          base/
          dev/

---

Development

# Clone and install
git clone https://github.com/esimplicityinc/katalyst-taxonomy.git
cd katalyst-taxonomy
uv sync

# Run tests
uv run pytest

# Run linters
uv run ruff check
uv run pyright

# Run CLI
uv run kata --help

# Run TUI
uv run python -m katalyst.tui --path .

---

License

MIT License

---

Links

• Documentation
• GitHub Issues
• Schema Reference