AAMF — Autonomous Application Modernization Framework

AAMF is an opinionated, enterprise-grade framework for governing AI-assisted application modernization.

It enables teams to safely use AI to reverse-engineer legacy systems, define modern target systems, and plan migrations — without sacrificing rigor, auditability, or engineering trust.

Table of Contents

• What AAMF Does
• Why AAMF Exists
• The Complete Process
• Implementation Readiness (Phase 5)
• Using the Architecture Agent
• Phase 3 and Phase 5 (Domain Decomposition)
• Installation
• Quick Start
• CLI Commands
• Preparing Your Legacy System
• Who Should Use AAMF
• Contributing
• License

What AAMF Does

AAMF provides:

• Structured modernization workflow — Five sequential phases with quality gates
• AI-friendly prompt artifacts — Battle-tested prompts that produce consistent output
• Deterministic validation — JSON Schema validation ensures completeness
• Audit-ready reports — Human-readable and machine-readable outputs
• CI/CD-ready CLI — Integrate validation into your pipelines

AAMF does not execute AI prompts.
It governs and validates the outputs produced by your AI tools (Cursor, Claude, Copilot, etc.).

Why AAMF Exists

AI can analyze legacy systems quickly — but:

• Outputs vary by model and session
• Critical requirements are missed
• Engineers cannot trust incomplete specs
• Leadership lacks defensible artifacts

AAMF exists to make AI outputs:

• Complete — Quality gates enforce minimum requirements
• Consistent — Structured prompts produce predictable results
• Reviewable — Human-readable markdown reports
• Safe — Validation before each phase transition

AI accelerates thinking.
AAMF enforces understanding.

The Complete Process

flowchart TD
    L[Legacy Application] --> Q[Gather Legacy Quirks<br/>& Tribal Knowledge]
    Q --> P1[Phase 1: AI Reverse Engineering]
    P1 --> V1[AAMF Validate<br/>source-system]
    V1 --> SA[Phase 2: Scope Adjustments]
    SA --> P3[Phase 3: AI Target System Spec]
    P3 --> V3[AAMF Validate<br/>target-system]
    V3 --> P4[Phase 4: AI Delta Analysis]
    P4 --> V4[AAMF Validate<br/>delta-analysis]
    V4 --> P5[Phase 5: AI Implementation Readiness]
    P5 --> V5[AAMF Validate<br/>implementation-readiness]
    V5 --> M[Migration Ready]

Phase 1: Source System Reverse Engineering

The AI analyzes your legacy codebase and produces factual, evidence-based documentation of what the system actually does. Phase 1 requires an exhaustive inventory (features, business rules, entities, relationships, workflows, use cases) in .aamf/docstacks/source-system/00-source-exhaustive-inventory.md before generating the 7 source-system documents.

Inputs (place in .aamf/input/):

• Legacy source code (or point the AI at your src/ directory)
• Database schema
• Existing documentation (converted to markdown)
• Tribal knowledge from stakeholders

Outputs:

• Exhaustive inventory at .aamf/docstacks/source-system/00-source-exhaustive-inventory.md (prerequisite to the 7 documents)
• 7 markdown documents in .aamf/docstacks/source-system/
• JSON summary at .aamf/output/source-system/source-system.json

Validation Requirements:

• Minimum 7 documents produced
• Coverage-based exhaustiveness: When the Phase 1 output includes discovery counts (entryPointsDiscovered, tablesInSchema, foreignKeysInSchema, actorRolesDiscovered), validation requires the inventory to cover 100% of discovered items: features ≥ entry points, entities ≥ tables, relationships ≥ FKs, use cases ≥ actor roles. This makes exhaustiveness relative to the source application size rather than fixed minimums.
• Minimum evidence citations and low floors for business rules/workflows (see schema); primary exhaustiveness check is coverage when discovery counts are provided.

Phase 2: Target System Specification

The AI uses the reverse-engineered docs to design a modern target system — without referencing the legacy system directly.

Inputs:

• .aamf/docstacks/source-system/ from Phase 1

Outputs:

• 9 markdown documents in .aamf/docstacks/target-system/
• JSON summary at .aamf/output/target-system/target-system.json

Validation Requirements:

• Minimum 20 functional requirements
• Minimum 20 acceptance criteria
• Minimum 3 user personas
• Minimum 3 state models

Phase 3: Delta Analysis & Migration Planning

The AI compares the source system with the target specification to create a prioritized migration plan.

Inputs:

• .aamf/docstacks/source-system/ from Phase 1
• .aamf/docstacks/target-system/ from Phase 2

Outputs:

• Migration scope document in .aamf/docstacks/delta-analysis/
• JSON summary at .aamf/output/delta-analysis/delta-analysis.json

Validation Requirements:

• Features to keep identified
• Features to modernize (minimum 3)
• Features to deprecate identified
• New features defined (minimum 3)
• Migration phases planned (minimum 3)

Phase 5: Implementation Readiness

The AI evolves the target-system docstack into an implementation-ready docstack: Units of Work (UoW), concrete API contracts, DB schema, master document template, and test specifications. Each UoW is self-contained so an AI implementation agent can execute it in sequence.

Inputs:

• .aamf/docstacks/target-system/ from Phase 3
• .aamf/docstacks/delta-analysis/ from Phase 4
• .aamf/input/scope-adjustments.md

Outputs:

• 9 evolved documents plus UoW documents in .aamf/docstacks/implementation-readiness/
• master-document-template.md, uow/ folder, README.md
• JSON summary at .aamf/output/implementation-readiness/implementation-readiness.json

Validation: aamf validate implementation-readiness

Agent-optimized mode

When the implementation-readiness docstack will be consumed primarily by AI implementation agents (e.g. Cursor, Claude, or other agents that implement each UoW), you can request an agent-optimized docstack. In this mode the generator produces documents that are structured for fast, unambiguous parsing by agents: strict section headers, table- and list-heavy content, explicit code-block labels, and a README subsection that explains document roles and UoW dependency order.

When to use it

• You plan to have AI agents implement UoWs from the docstack with minimal human editing.
• You want consistent structure (e.g. <!-- agent-optimized --> headers, purpose lines under each section) so agents can reliably find API contracts, DB schema, and test specs.
• You prefer tables and bullet lists over prose so agents can resolve FR/BR/UoW references without interpreting long paragraphs.

When to skip it

• The docstack will be read mainly by humans; standard markdown is often easier to read.
• You do not need the extra header blocks or the README “Agent consumption” subsection.

How to activate

Include the word agent-optimized (case-insensitive) in the same message you use to submit the Implementation Readiness prompt to your AI tool.

Examples:

• “Run the implementation-readiness prompt, agent-optimized.”
• “Execute Phase 5. Please use agent-optimized mode.”
• “Generate the implementation-readiness docstack. I want it agent-optimized for AI implementers.”

The AI that runs .aamf/framework/prompts/05_implementation_readiness.prompt.md will detect the phrase and apply the agent-optimized conventions to all generated documents (evolved docs, UoW files, master template, README). No CLI flag is required; activation is entirely via the prompt submission message.

Using the Architecture Agent

AAMF includes an optional Architecture Agent prompt (framework/prompts/architecture-agent.prompt.md) for a single-shot, DDD-focused run that produces both target-system–equivalent design and the implementation-readiness docstack in one pass.

What it is: A single prompt that consumes Phase 1–4 outputs (source-system, scope-adjustments, target-system, delta-analysis) and produces Domain/Bounded Context architecture, microservice specs (REST + GraphQL per BC), and the Phase 5 implementation-readiness pack.

When to use it: You want Domains/Bounded Contexts, REST+GraphQL per BC, and one combined AI run instead of separate Phase 3 and Phase 5.

How to use it:

1. Complete Phases 1–4 as usual (source-system, scope-adjustments, target-system, delta-analysis).
2. Load the Architecture Agent prompt: run aamf start to get the framework path, then open framework/prompts/architecture-agent.prompt.md from your AAMF install.
3. Provide the agent with the same inputs it lists (source-system docstack, scope-adjustments, target-system docstack, delta-analysis docstack).
4. Ensure the output includes the implementation-readiness docstack under .aamf/docstacks/implementation-readiness/ and the JSON summary at .aamf/output/implementation-readiness/implementation-readiness.json in a form that passes aamf validate implementation-readiness. If you need to validate target-system as well, extract or generate a summary at .aamf/output/target-system/target-system.json in the required shape (functionalRequirements, acceptanceCriteria, personas, stateModels).

Optional: For DDD/BC-style output within the standard phase flow, you can also load architecture-agent.prompt.md alongside the Phase 3 or Phase 5 prompt and follow its Domain/BC and output-structure rules.

Phase 3 and Phase 5 (Domain Decomposition)

Phase 3 uses Domain Decomposition only. The prompt is 03b_domain_decomposition_target_system.prompt.md (returned by aamf next for target-system). It produces Domains, Subdomains, Bounded Contexts, Context Map, Ubiquitous Language, and Service Candidates. Output goes to .aamf/docstacks/target-system/ and must produce .aamf/output/target-system/target-system.json so aamf validate target-system works.

Phase 5 uses the DDD docstack layout only: evolved/ (01-functional-requirements.md … 09-test-strategy-and-plans.md), api/<bounded-context>/, events/, schema/, uow/, ADR/, README, and master-document-template. For each Bounded Context, the Service Contract Generator (05b_service_contract_generator.prompt.md) is run to produce REST/GraphQL contracts, domain events, DDL, and UoW seeds; Phase 5 describes this under "Bounded Contexts and Service Contract Generator."

Installation

From npm

npm install -g @hstm-labs/aamf

From Source

git clone https://github.com/your-org/aamf.git
cd aamf
npm install
npm run build
npm link

Quick Start

1. Initialize a Workspace

cd /path/to/your/legacy-application
aamf init

You will see an AAMF ASCII banner and a prompt to select your AI assistant (Cursor, VSCode + Copilot, Windsurf, or Other). Based on your choice, AAMF creates a /aamf-start command (or instructions) that loads the orchestrator prompt from your AAMF installation.

This creates an .aamf/ workspace containing:

• input/ — Place your legacy documents and schema exports here
• output/ — Directories for phase outputs
• docstacks/ — Directories for AI-generated docstacks
• README.md — Usage instructions

Prompts and schemas are not copied — they are provided by your global (or local) AAMF install. The /aamf-start command loads the orchestrator prompt from that install (its path is written into the command when you run init).

2. Run Phase 1

1. In your AI assistant, run /aamf-start (Cursor/Windsurf) or follow .vscode/aamf-start.md (VSCode + Copilot) to load the orchestrator prompt.
2. Run aamf next to get the path to the Phase 1 prompt; give your AI both the orchestrator and Phase 1 prompt.
3. Point the AI at your legacy codebase
4. Let the AI produce the 7 documentation files
5. Ensure the AI saves the JSON summary to .aamf/output/source-system/source-system.json

3. Validate Phase 1

aamf validate source-system

If validation passes, proceed to Phase 2. If it fails, the AI needs to address the gaps.

4. Run Phase 2 — Scope Adjustments

1. Run aamf next for the prompt path, then provide that prompt to your AI.
2. Define exclusions, additions, behavioral changes, and target architecture pattern
3. Output saved to: .aamf/input/scope-adjustments.md

5. Run Phase 3 — Target System Specification

1. Run aamf next for the prompt path; the Phase 3 prompt is domain decomposition (03b_domain_decomposition_target_system.prompt.md). Give your AI the orchestrator and that prompt.
2. Let the AI produce the target-system docstack (Domains, Bounded Contexts, Context Map, etc.).
3. Ensure the AI saves the JSON summary to .aamf/output/target-system/target-system.json

6. Validate Phase 3

aamf validate target-system

7. Run Phase 4 — Delta Analysis

1. Run aamf next for the prompt path, then provide that prompt to your AI.
2. Let the AI produce the migration analysis
3. Ensure the AI saves the JSON summary to .aamf/output/delta-analysis/delta-analysis.json

8. Validate Phase 4

aamf validate delta-analysis

9. Run Phase 5 — Implementation Readiness

1. Run aamf next for the prompt path, then provide that prompt to your AI.
2. (Optional) Include agent-optimized in your message if the docstack will be used mainly by AI implementation agents (see Agent-optimized mode).
3. Let the AI produce the implementation-readiness docstack (evolved docs, UoW folder, master template, README).
4. Ensure the AI saves the JSON summary to .aamf/output/implementation-readiness/implementation-readiness.json

10. Validate Phase 5

aamf validate implementation-readiness

You now have a complete, validated modernization plan and an implementation-ready docstack.

CLI Commands

| Command | Description | |---------|-------------| | aamf init | Initialize workspace, show banner, select assistant, create /aamf-start | | aamf start | Print path to the orchestrator prompt (used by /aamf-start) | | aamf next | Show the next phase and its prompt path | | aamf validate <phase> | Validate phase output against schema | | aamf --version | Show version | | aamf --help | Show help |

Validation Output

Each validation produces:

• validation.report.json — Machine-readable, CI/CD-friendly
• validation.report.md — Human-readable, review-ready

Preparing Your Legacy System

Before running AAMF, prepare your legacy system materials.

Document Format Requirements

AAMF prompts work best with Markdown (.md) or plain text (.txt) documentation.

Convert other formats (PDF, Word, HTML) before starting.

Place All Input Files in .aamf/input/

.aamf/input/
├── schema.sql            # Exported database schema
├── user-guide.md         # Converted from PDF/Word
├── api-reference.md      # Converted from HTML
└── business-rules.txt    # Plain text / tribal knowledge notes

Database Schema Export

Oracle:

sqlplus user/pass@db @generate_ddl.sql > .aamf/input/schema.sql

SQL Server:

mssql-scripter -S server -d database --schema-only -f .aamf/input/schema.sql

PostgreSQL:

pg_dump --schema-only dbname > .aamf/input/schema.sql

MySQL:

mysqldump --no-data dbname > .aamf/input/schema.sql

Who Should Use AAMF

• Platform and architecture teams modernizing legacy systems
• Modernization programs requiring structured governance
• Engineering leaders needing defensible artifacts
• Regulated organizations requiring audit trails
• Consultancies delivering modernization assessments

Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

• Search existing issues before creating new ones
• Include reproduction steps and expected vs actual behavior
• Attach relevant error messages and logs

Submitting Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Run the build: npm run build
5. Commit with clear messages: git commit -m "Add feature X"
6. Push to your fork: git push origin feature/my-feature
7. Open a Pull Request

Development Setup

git clone https://github.com/your-org/aamf.git
cd aamf
npm install
npm run build
npm run dev -- --help

Areas for Contribution

• Prompt improvements — Enhance prompts in framework/prompts/
• Schema refinements — Improve validation in framework/schemas/
• New commands — Add CLI functionality in src/cli/commands/
• Documentation — Improve guides and examples
• Testing — Add test coverage

Code Style

• TypeScript for all source code
• ESM modules ("type": "module")
• Functional approach where practical
• Clear, descriptive commit messages

Project Structure

aamf/
├── bin/                      # CLI entry point
├── dist/                     # Compiled JavaScript
├── framework/
│   ├── config/               # Configuration files
│   ├── prompts/              # AI prompt templates
│   └── schemas/              # JSON validation schemas
├── src/
│   ├── cli/commands/         # CLI command implementations
│   ├── core/                 # Phase and state engines
│   ├── rendering/            # Report generation
│   ├── types/                # TypeScript type definitions
│   └── validation/           # Schema validation
├── package.json
├── tsconfig.json
└── README.md

License

MIT License

Copyright (c) 2024

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.