npm package: @hstm-labs/aamf
Description: Autonomous Application Modernization Framework
Latest version: 3.6.0

# 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](#what-aamf-does)
- [Why AAMF Exists](#why-aamf-exists)
- [The Complete Process](#the-complete-process)
- [Implementation Readiness (Phase 5)](#phase-5-implementation-readiness)
- [Using the Architecture Agent](#using-the-architecture-agent)
- [Phase 3 and Phase 5 (Domain Decomposition)](#phase-3-and-phase-5-domain-decomposition)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [CLI Commands](#cli-commands)
- [Preparing Your Legacy System](#preparing-your-legacy-system)
- [Who Should Use AAMF](#who-should-use-aamf)
- [Contributing](#contributing)
- [License](#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 agent-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

```mermaid
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

```bash
npm install -g @hstm-labs/aamf
```

### From Source

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

---

## Quick Start

### 1. Initialize a Workspace

```bash
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

```bash
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

```bash
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

```bash
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](#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

```bash
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:**

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

**SQL Server:**

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

**PostgreSQL:**

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

**MySQL:**

```bash
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

```bash
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.