aggregate-platform-architecture

name	aggregate-platform-architecture
description	Combine multiple component architecture summaries into a platform-level architecture document. Use after generating component summaries to create a wholistic platform view.
allowed-tools	Read, Glob, Grep, Write, Bash(ls *), Bash(find *), Bash(python *), Bash(*/arch-query *)

Aggregate Platform Architecture

Combine component architecture summaries into a comprehensive platform-level architecture document focused on synthesis and cross-cutting analysis.

Arguments

Required:

• --platform-dir=<path> - Path to the platform directory containing component .md files (e.g., architecture/rhoai)

Optional:

• --distribution=NAME - Distribution name (e.g., rhoai, odh). Default: derived from directory name.
• --version=VERSION - Platform version string. Default: unknown.
• --generated-by=STRING - Exact string for the "Generated By" metadata field (e.g., Claude Opus 4.6). Default: auto-detect model name + current date.
• --output=FILENAME (default: PLATFORM.md)

When invoked by the orchestrator, all arguments are provided on the command line. When invoked manually, only --platform-dir is required.

Instructions

IMPORTANT - TOOL USAGE:

• Do NOT call ToolSearch. You already have access to: Bash, Read, Write, Glob, Grep.
• Use arch-query via Bash for structured data extraction — do NOT manually read and parse component markdown files.
• When reading multiple files, use parallel tool calls — issue multiple Read calls in a single turn rather than one at a time.

Step 1: Load Structured Data via arch-query

Extract all structured platform data in a single command:

arch-query platform-summary --base-dir={architecture_base_dir} --version={version_dir_name} --output json

Where:

• {architecture_base_dir} is the parent of {platform_dir} (e.g., if --platform-dir=/data/architecture/rhoai.next, use --base-dir=/data/architecture)
• {version_dir_name} is the directory name (e.g., rhoai.next)

This returns a single JSON object containing all components, CRDs, services, endpoints, dependencies, RBAC, controller watches, network policies, and dockerfiles — already aggregated across all components. You do NOT need to read individual component files to get this data.

If arch-query is not available, fall back to reading component files directly (see Fallback section below).

Step 2: Identify Patterns and Relationships

Using the JSON data from Step 1, analyze cross-cutting patterns.

First, generate the deterministic dependency tree:

arch-query deps --base-dir={architecture_base_dir} --version={version_dir_name}

This produces a tree-list showing how the operator deploys and connects all components, with relationship annotations (deploys, CRD watch, manages, API, etc.). Use this output verbatim as the dependency graph in the "Component Relationships > Dependency Graph" section of PLATFORM.md — do NOT generate your own ASCII diagram or box-style graph. The tree-list format with |-- prefixes and parenthetical annotations is the canonical format.

Then analyze from the JSON data:

1. Central components: From the tree + internal_deps, identify components with the most reverse dependencies (other components pointing at them).

2. Integration patterns: From internal_deps and services, identify recurring integration patterns (e.g., CRD-based orchestration, gRPC service mesh, REST API composition).

3. Namespace topology: From component metadata and services, determine how components are deployed across namespaces.

4. Authentication patterns: From component metadata, identify which auth mechanisms are used and by which components (Bearer tokens, mTLS, kube-rbac-proxy, etc.).

5. Container security patterns: From dockerfiles data, identify common patterns (non-root execution, FIPS compliance, UBI base images, capability drops).

6. HA patterns: From component metadata, identify replication and leader election patterns.

Step 3: Read Architectural Analysis Sections

For synthesis that requires the free-form prose from component docs, selectively read the "Architectural Analysis" sections from key components. Use arch-query component <name> --base-dir={architecture_base_dir} --output raw to read specific components, or grep for analysis sections:

grep -l "Architectural Analysis" {platform_dir}/*.md

Then read only those sections from the most architecturally significant components (operators, controllers, core services). Do NOT read every component file — focus on components identified as central in Step 2.

Step 4: Synthesize Data Flows

Identify 3-5 key platform workflows by tracing dependency chains and service interactions from the structured data. For each workflow:

1. Start from a user-facing entry point (dashboard, API, CLI)
2. Trace through internal dependencies and services
3. Document the component chain with actions at each step

Step 5: Write PLATFORM.md

Follow the template exactly as defined in platform template. Read that file before writing.

Structural rules:

• Use exactly the section headings and table column headers from the template — do not rename, reorder, number, or add sections
• If a section has no data, keep the heading and write "None identified." as the content
• The H1 must be # Platform: [Distribution Name] [Version]
• The ## Version-Specific Changes ([version]) section heading includes the version in parentheses

What PLATFORM.md is NOT:

• It is NOT a flat dump of per-component data. All CRDs, endpoints, services, RBAC, secrets, TLS config, Prometheus endpoints, and health probes are queryable via arch-query and the component .md/.json files.
• PLATFORM.md focuses on synthesis: patterns, relationships, workflows, architectural analysis, and cross-cutting observations that only emerge from reading all components together.

Populate the "Generated By" field in the Metadata section:

• If --generated-by was provided, use that exact string followed by on YYYY-MM-DD (use date +%Y-%m-%d to get the date)
• Otherwise, use your model name (e.g., "Claude Opus 4.6") followed by on YYYY-MM-DD

Write the output file to {platform_dir}/{output_filename}.

Step 6: Validate Output

After writing, run the validation script:

python ${CLAUDE_SKILL_DIR}/scripts/validate_platform.py {platform_dir}/PLATFORM.md

If validation fails, read the errors, fix the markdown, re-write the file, and re-validate. Do not proceed to Step 7 until validation passes.

Step 7: Report Results

Output a summary:

Platform architecture aggregated!

Distribution: {distribution}
Version: {version}
Components analyzed: {count}

File created: {platform_dir}/PLATFORM.md

Summary:
- {N} components analyzed
- {N} integration patterns identified
- {N} key workflows documented
- {N} namespaces mapped
- {N} security patterns identified

Fallback: Without arch-query

If arch-query is not available (command not found), fall back to reading component files:

1. List .md files: find {platform_dir} -maxdepth 1 -name "*.md" -type f ! -name "README.md" ! -name "PLATFORM.md" | sort
2. Read component files using parallel Read calls
3. Extract structured data from markdown tables
4. Continue from Step 2

This is slower but produces the same result.

Notes

• PLATFORM.md is a synthesis document, not a data dump. Per-component data lives in the component .md and .json files and is queryable via arch-query.
• The aggregation focuses on platform-level relationships, patterns, and analysis.
• Accuracy > speed — this is a source of truth document.