Source of truth for the Agentic Readiness Analysis (ARA) / Modernization Readiness Analysis (MODA) analysis orchestrator, built on AWS Transform Continuous Modernization (atx ct). This repo holds the managed transformation definitions (TDs) that ct runs internally, the custom Execution Plan TD, and the agent skill that orchestrates the full workflow.
main = prod. What's merged to main in definitions/managed/ is what the AWS Transform service runs.
├── definitions/
│ ├── managed/ # 4 AWS-managed TDs (what `atx ct` runs internally; main = prod)
│ │ ├── README.md
│ │ ├── agentic-readiness-analysis/ # per-repo ARA
│ │ ├── modernization-readiness-analysis/ # per-repo MODA
│ │ ├── portfolio-agentic-readiness-analysis/ # portfolio ARA + program recs
│ │ │ └── references/program-library.md # AWS Program & GTM Library (runtime-loaded)
│ │ └── portfolio-modernization-readiness-analysis/
│ │ └── references/program-library.md
│ └── custom/ # custom TDs (atx custom def exec) — you invoke these by name
│ ├── eba-execution-plan-generator/ # EBA execution plan TD
│ ├── bpmn-opportunity-analysis/ # BAO: per-repo BPMN agentic opportunity analysis
│ ├── portfolio-bpmn-opportunity-analysis/ # portfolio BAO aggregation
│ └── bridge-analysis/ # ARA↔MOD bridge (agentic-readiness dividend)
├── orchestrator/
│ ├── SKILL.md # Claude/agent skill: full ARA/MODA/EBA workflow
│ └── references/ # getting-started, ct-workflow, execution-plan, troubleshooting
├── tools/
│ └── bpmn-analyzer/ # deterministic BPMN preprocessor (BAO input; Python)
├── scripts/
│ └── publish-td.sh # Publish a TD folder to the ATX registry
├── demo-scripts/ # Full demo harness (setup, reset, live-discovery)
│ ├── 00-full-setup.sh # Bake env: source + discovery + ARA + MODA + export (~45 min)
│ ├── 00-push-repos.sh # [remote mode only] push the pre-baked repos to a GitHub org
│ ├── 01-live-discovery-push.sh # Live beat: new repo appears (3 → 4)
│ ├── 02-reset-live-discovery.sh # Reset for rehearsal
│ └── 99-full-reset.sh # Nuke everything
├── harness/ # change-impact harness — advisory, never blocks a merge
│ ├── DESIGN.md # scored dimensions + the reasoning behind each step
│ ├── usecases.yaml # fixture matrix + coverage axes + expectations
│ ├── fixtures/ # test/demo repos the harness runs the TDs over
│ │ ├── portfolio/ # 10 synthetic legacy repos (also the demo portfolio)
│ │ └── monolith/ # PHP test fixture
│ ├── golden/ # committed baseline reports each MR diffs against
│ ├── should-run.sh # 0. gate: deterministic run|skip path check (no LLM)
│ ├── run-fixtures.sh # 1. publish the edited TD + atx custom def exec
│ ├── skill_table.py # parses the TDs' severity tables; 2. severity gate
│ ├── diff-reports.py # 3. D1–D5 delta + safety alerts -> impact.json
│ ├── score-reports.py # 4. groundedness vs source -> compare.json
│ ├── judge.py # 5. LLM-as-judge -> verdict.json (the only LLM call)
│ ├── validate-contract.py # schema guardrail: structural JSON-contract check
│ ├── post-mr-comment.sh # 6. advisory MR comment
│ └── tests/ # offline test suite (no AWS, no LLM)
├── examples/
│ └── atx-config-exec-plan.yaml # Example EBA config
└── README.md
The AWS-managed definitions that run inside atx ct — you never invoke them by name. atx ct analysis run --type agentic-readiness runs the per-repo ARA TD across every discovered repo, then the portfolio ARA TD aggregates the results (same pattern for --type modernization-readiness). The two portfolio TDs load references/program-library.md (the AWS Program & GTM Library) at runtime to produce engagement-program recommendations. See definitions/managed/README.md.
Custom TDs run via atx custom def exec (not atx ct analysis run) because they consume report/model artifacts as input and produce planning or opportunity outputs rather than per-repo findings. You invoke each by name. The table below is the pointer — each TD's SKILL.md holds the full additionalPlanContext field reference in its Step 0.
| TD | What it does | Required input | How to run |
|---|---|---|---|
eba-execution-plan-generator |
Dependency-aware modernization roadmap from ARA and/or MODA output | ≥1 portfolio report + human planning context (team size, timeline) | atx custom def exec -n eba-execution-plan-generator -p . -g file://atx-config-exec-plan.yaml -x -t (details below) |
bpmn-opportunity-analysis |
BAO — classifies BPMN 2.0 process steps as agentic-AI opportunities (category + autonomy) | JSON from tools/bpmn-analyzer/run_analysis.py (analysis_report_path) |
Run the analyzer first, then atx custom def exec -n bpmn-opportunity-analysis -p . -g file://bao-config.yaml -x -t |
portfolio-bpmn-opportunity-analysis |
Aggregates per-repo BAO reports into a portfolio opportunity view | Auto-discovers per-repo BAO reports (no config required) | atx custom def exec -n portfolio-bpmn-opportunity-analysis -p . -x -t |
bridge-analysis |
Cross-references portfolio ARA + MOD — shared remediation, modernization dividend, dedup | Portfolio ARA report + portfolio MOD report paths + portfolio_name |
atx custom def exec -n bridge-analysis -p . -g file://bridge-config.yaml -x -t |
The EBA TD is the richest — it needs human planning inputs the agent can't infer from code (team size, timeline, budget), documented in full below. The other three take only file-path pointers (or auto-discover their inputs).
Input requirements — at least ONE portfolio report must exist (ARA-only, MODA-only, or both; when both exist the plan covers both dimensions with cross-dependency detection):
<workspace>/
├── portfolio-agentic-readiness-analysis/
│ └── <portfolio>-ara-portfolio-report.json ← from ct portfolio ARA analysis (optional*)
├── portfolio-modernization-readiness-analysis/
│ └── <portfolio>-mod-portfolio-report.json ← from ct portfolio MODA analysis (optional*)
└── services/<repo-name>/
├── agentic-readiness-analysis/<repo>-ara-report.json ← per-repo ARA (optional drill-down)
└── modernization-readiness-analysis/<repo>-mod-report.json ← per-repo MODA (optional drill-down)
*At least one of the two portfolio reports is required — the TD terminates with an error if neither is found. Per-repo reports are read only when deeper granularity is needed.
On local sources, ct writes these artifacts directly into the repo working trees during analysis. Either way, the authoritative location of every report is the report_paths map on the analysis record:
# List every report this analysis produced (repo slug -> absolute path)
atx ct analysis get --id <analysis-id> --json | jq -r '.report_paths | to_entries[] | "\(.key)\t\(.value.ara // .value.mod)"'
# Copy one into place
cp "$(atx ct analysis get --id <ara-id> --json | jq -r '.report_paths["<src>::<repo>"].ara')" \
services/<repo>/agentic-readiness-analysis/<repo>-ara-report.jsonreport_paths is markdown-only. It points into ~/.atxct/shared/analyses/<id>/artifacts/<source>__<repo>/ (portfolio output in sibling _portfolio_ara / _portfolio_mod dirs), which holds essentially only .md. The complete bundle — including the .json the EBA TD consumes and the browser-openable .html — lives in the source-scoped run tree, and for portfolio reports that is the only copy:
# Portfolio bundle: .md .json .html .metadata.json — html/json exist here and nowhere else
ls ~/.atxct/sources/*/*/runs/<analysis-id>/portfolio-*/*-analysis/
# Every artifact of a run (glob — the path segment is the SOURCE's analysis root, not the
# run's type, and per-repo dirs are slug-mangled <source>-<repo>-<16hex>)
find ~/.atxct/sources -path "*runs/<analysis-id>/*" -type fWorking trees receive per-repo bundles only — never portfolio output. See orchestrator/SKILL.md for the full three-location table.
atx ct analysis list-artifactsandget-artifactno longer exist (verified 2026-08-03 on atx 3.9.0 —error: unknown command, zero occurrences in the shipped CLI bundle). Any script still calling them must move toanalysis get --json→report_paths.
Running the EBA TD (requires at least one portfolio report — ARA and/or MODA):
atx custom def exec -n eba-execution-plan-generator -p . -g file://atx-config-exec-plan.yaml -x -tThe -g config (additionalPlanContext) provides the execution constraints that shape how the roadmap is sequenced and phased. These are human inputs the TD cannot infer from code:
# atx-config-exec-plan.yaml
additionalPlanContext: |
portfolio_name: "my-platform"
team_size: 8 # engineers/teams available
timeline_constraint: "12 months" # total modernization timeline
budget_constraint: "$1.2M" # including training + infra
parallel_capacity: 3 # how many services modernized simultaneously
compliance_requirements: # hard deadlines (optional)
- "SOC2 audit by 2026-03"
- "PCI-DSS renewal Q4"
sequencing_overrides: # business-priority ordering (optional)
- "payments-service must complete first"
service_inventory: # auto-populated from ct data
- name: "payments-service"
path: "/path/to/payments-service"
priority: "P0"
tags: ["java", "spring-boot"]
findings_summary: {high: 4, medium: 12, low: 3}
dependency_overrides: # inferred from cross-service findings
- source: "payments-service"
target: "user-service"
type: "sync"| Field | Required | Source |
|---|---|---|
team_size |
Yes | Human input |
timeline_constraint |
Yes | Human input |
budget_constraint |
No | Human input |
parallel_capacity |
No | Human input |
compliance_requirements |
No | Human input |
sequencing_overrides |
No | Human input |
service_inventory[] |
Yes | Auto-populated from atx ct repository list + findings list |
dependency_overrides[] |
No | Auto-inferred from cross-service findings |
The orchestrator skill (orchestrator/references/execution-plan.md) has the full interactive flow for generating this config with an agent. See also examples/atx-config-exec-plan.yaml.
A Claude/agent skill (orchestrator/SKILL.md) that turns an agent into the orchestrator for the full workflow: source setup → discovery → ARA/MODA analysis → findings → Execution Plan. Reference docs in orchestrator/references/ are read on demand (getting started, ct workflow, execution plan, troubleshooting).
Install it for Claude Code, then start Claude from the project root:
mkdir -p ~/.claude/skills/ara-moda-orchestrator
cp -R orchestrator/SKILL.md orchestrator/references ~/.claude/skills/ara-moda-orchestrator/
# re-copy after pulling; a stale copy confidently calls commands that no longer exist
diff -q orchestrator/SKILL.md ~/.claude/skills/ara-moda-orchestrator/SKILL.md \
&& echo "skill is current" || echo "STALE — re-copy"The skill carries the verified atx ct behavior — which commands were removed, when a run is genuinely finished, and where reports actually land. Those are the places an agent working from the CLI's own help text gets it wrong, usually in ways that look like success.
Publishes a TD folder to the ATX registry. The TD name is derived from the folder basename; the description is extracted from the SKILL.md frontmatter (or the first heading of transformation_definition.md).
# Publish
./scripts/publish-td.sh definitions/custom/eba-execution-plan-generator
# Save as draft
./scripts/publish-td.sh definitions/managed/portfolio-agentic-readiness-analysis --draftRequires the atx CLI and AWS_REGION=us-east-1 (or a supported region).
A rubric edit is a one-line diff whose blast radius is a whole portfolio of reports. Reading
the diff tells you what the text now says; it does not tell you that AUTH-Q5 was emitted as a
BLOCKER on 6 of 12 reference reports, above its documented severity. The harness answers that
question mechanically: it re-runs the edited TD over fixture repos, diffs the resulting
reports against a committed baseline, and posts an advisory verdict on the MR.
Every job is allow_failure: true — the harness never blocks a merge. It is a reviewer aid,
not a gate. The only LLM call is the judge, spent once at the very end; the run/skip decision is
a deterministic git diff, not a model.
Fixtures live under harness/fixtures/: portfolio/ holds the 10 synthetic legacy repos (also
the source the demo scripts discover), monolith/ is a PHP fixture for local runs. The
committed baseline each MR diffs against — a full set of per-repo ARA/MOD reports and portfolio
roll-ups — is harness/golden/. See harness/README.md for the pipeline
diagram and setup, and harness/DESIGN.md for the scored dimensions and
the reasoning behind each step.
Automation runs on the internal GitLab instance only, where the AWS credentials live. GitHub stays open for issues and PRs but carries no CI.
examples/atx-config-exec-plan.yaml is a sample EBA additionalPlanContext config.
Prerequisites: AWS credentials (aws sts get-caller-identity), the ATX CLI (curl -fsSL https://transform-cli.awsstatic.com/install.sh | bash), Node.js 22+, and the AWSTransformCustomFullAccess managed policy.
# Check the CLI version. NOTE: inside Claude Code a bare `atx --version` reports
# Builder Toolbox's claude-code build (2.1.x), not atx's — strip the inherited var.
env -u TOOLBOX_TOOL_VERSION atx --version # → 3.9.0
# Region: only us-east-1 resolves for the definition/credential endpoint
export AWS_REGION=us-east-1 AWS_DEFAULT_REGION=us-east-1
# No server to start — analyses run in-process. This is just a health check.
atx ct status --health
# Add a local source (absolute path to a parent directory containing repos,
# each of which must contain a .git directory for discovery to find it)
atx ct source add --name my-portfolio --provider local --path $(pwd)/services
# Discover repositories
atx ct discovery scan --source my-portfolio
# Run ARA (per-repo + portfolio aggregation), then poll
atx ct analysis run --type agentic-readiness --source my-portfolio
atx ct analysis get --id <analysis-id>
# Run MODA (after ARA — do not run both concurrently)
atx ct analysis run --type modernization-readiness --source my-portfolio
# Inspect findings
atx ct findings count --by severity --json
atx ct findings list --json
atx ct serveris deprecated and hidden — never start it; it blocks the shell on:8081and is not required. A hidden--waitdoes exist onanalysis run, but polling is preferable in agent workflows. Both are covered inorchestrator/SKILL.md, which is the current source of truth for CLI behavior.
The orchestrator/SKILL.md skill walks an agent through the same workflow interactively.
See CONTRIBUTING.md. Use the GitHub issue templates to report bugs or suggest enhancements.
See SECURITY.md. Treat analysis reports as confidential — they contain architecture details.
This library is licensed under the MIT-0 License. See the LICENSE file.