Target Architecture Document

Quick Start

Assume the Enterprise Architect Agent role from

agents/enterprise-architect.md

: align initiatives to business capabilities, target architecture, standards, roadmaps, reuse opportunities, portfolio impact, cross-domain dependencies, and governance actions.

Ask the user which capabilities to include before drafting the target architecture document. If the user already named capabilities, confirm the list and ask for any missing domains, strategic drivers, constraints, or existing architecture inputs.

Before creating any output files, run a

grill-me

style clarification session using

../grill-me/SKILL.md

. Ask one question at a time until the request, scope, capabilities, assumptions, constraints, terminology, and desired output are clear enough to avoid avoidable misunderstanding.

During that clarification session, use

../ubiquitous-language/SKILL.md

whenever terms are vague, overloaded, conflicting, or important enough to become shared domain language. Create or update

<private-lab-root>/GLOSSARY.md

inline as terms are clarified; do not batch glossary updates until the end. Do not write the glossary inside this public toolkit repository when working with real company context.

While creating or updating target architecture section files, also update

<private-lab-root>/GLOSSARY.md

whenever the document introduces or changes domain terms, applications, or data objects. Treat glossary maintenance as part of writing each section, not as a final cleanup task. Use the glossary format and rules from

../ubiquitous-language/SKILL.md

, including the dedicated

## Applications

section and a

## Data objects

section when data objects are identified.

After the clarification session, validate that

<private-lab-root>/GLOSSARY.md

was created or updated during the current run. If it was not created or updated, stop before generating target architecture files and ask the user to run the

grill-me

skill followed by the

ubiquitous-language

skill so the glossary is updated first.

Use the matching template in

templates/

for each generated section file. Use

templates/00-target-architecture-document-template.md

only for the summary and navigation document.

Every generated section file and the summary document must keep the top metadata table from its template. Replace every

{{PLACEHOLDER}}

and every drafting instruction with final, document-specific content; do not leave template guidance in generated artifacts. In particular, replace

{{CONFLUENCE_LINK}}

{{LAST_UPDATE}}

, and

{{OPEN_QUESTIONS_COUNT}}

with document-specific values. Leave

Readability Score

TBD

unless a readability check has actually been run.

Readability guideline: write for business stakeholders first. Aim for a readability score of

40+

for management summaries and section introductions, and

30+

for the remaining body content. Prefer short sentences, concrete nouns, active voice, and plain-language trade-offs. Keep specialist terms only where they affect decisions, risk, cost, ownership, timeline, or support model, and explain them on first use.

Store generated target architecture documents under the private company lab root at

solution-architectures/L1-target-architecture-<slug>/

When this toolkit is used as a submodule, do not write generated target architecture documents under

toolkit/solution-architectures/

or inside this public toolkit repository. Run from the private company lab root, or otherwise target the private lab root explicitly, so output goes to

<private-lab-root>/solution-architectures/

Use one file per major workflow section, plus one stakeholder-facing summary and navigation document:

text

solution-architectures/<slug>/
├── 01-preliminary-phase.md
├── 02-capability-overview.md
├── diagrams/
│   ├── capability-map.drawio
│   └── capability-map.svg
├── 03-phase-a-architecture-vision.md
├── 04-phase-b-business-architecture.md
├── 05-phase-c-application-architecture.md
├── 06-phase-c-data-architecture.md
├── 07-phase-d-technology-architecture.md
├── 08-phase-e-solution-building-blocks.md
├── 09-gap-analysis.md
├── 10-roadmap-themes.md
├── 11-governance-actions.md
├── 12-risks-and-open-questions.md
└── 00-target-architecture-document.md

Store every Draw.io source and same-basename export created for a target architecture document under

solution-architectures/<slug>/diagrams/

. Do not place target architecture diagram files beside the numbered Markdown documents.

Required Inputs

Enterprise and organizational context
Architecture capability, maturity, framework, governance, standards, roles, and reusable assets
Rationale and scope for the target architecture initiative
Capabilities to include
Company mission and vision, strategic drivers, objectives, product vision, and business outcomes
Stakeholders and governance bodies
Current-state application, data, integration, and technology context
Target-state direction, constraints, standards, and roadmap expectations
Candidate delivery slices or architecture work packages
Known risks, dependencies, and open decisions

Workflow

Start with the
```
grill-me
```
clarification session and update
```
<private-lab-root>/GLOSSARY.md
```
with
```
ubiquitous-language
```
as terminology is clarified.
Validate that
```
<private-lab-root>/GLOSSARY.md
```
was created or updated. If not, stop and ask the user to run
```
grill-me
```
and then
```
ubiquitous-language
```
before continuing.
Gather and confirm the capability list from the user.
Determine the output folder as
```
<private-lab-root>/solution-architectures/<slug>/
```
, where
```
<slug>
```
is derived from the target architecture document name.
Create the
```
solution-architectures/<slug>/
```
folder if needed. Create its
```
diagrams/
```
subfolder before generating any target architecture diagram.
For every section below, update
```
<private-lab-root>/GLOSSARY.md
```
before or alongside the section when the section introduces or changes:
- Domain terms and aliases
- Jargon, deprecated terms, or words to avoid, captured in the glossary
```
## Jargon
```
  section
- Applications and the capabilities or functions they deliver
- General canonical data objects, ownership, source-of-truth, and lifecycle notes
- Relationships between terms, applications, and data objects
Do not overwrite an existing section file or summary document unless the user explicitly asks.
Create
```
01-preliminary-phase.md
```
from
```
templates/01-preliminary-phase-template.md
```
using Preliminary Phase input to establish architecture context:

Introduction explaining how enterprise architecture is organized and governed
Enterprise and organizational context - Establishes where architecture operates organizationally
Architecture capability and maturity - Defines where and how enterprise architecture is practiced
Architecture framework and method - Describes the chosen framework and methodological approach
Architecture principles and standards - Establishes reusable rules and constraints
Governance model and decision rights - Defines architecture decision rights and governance mechanisms
Architecture roles and decision forums - Establishes the standing architecture organization
Integration with portfolio, delivery, risk, and other governance
Architecture repository, tools, and reusable assets - Establishes the shared architecture knowledge base

Create
```
02-capability-overview.md
```
from
```
templates/02-capability-overview-template.md
```
with a high-level overview for each included capability:
- Before the capability descriptions, create
```
diagrams/capability-map.drawio
```
  with
```
../create-drawio-diagram/SKILL.md
```
  using
```
../create-drawio-diagram/templates/capability-map.drawio
```
- Place every included layered capability exactly once in its confirmed horizontal layer: Channel, Engagement Services, Integration, or Enterprise Foundation
- Use at most eight capabilities per row in each layer; when a layer needs multiple rows, use the minimum number of rows and distribute its capabilities evenly according to the Capability Map layout rules in
```
../create-drawio-diagram/SKILL.md
```
- Preserve the three cross-cutting columns to the right of the horizontal layers: UI Design and Testing; Observability (Logging, Monitoring & Alerting); DevOps; do not duplicate these as nodes inside a horizontal layer
- Start with the typical cross-cutting capabilities defined by the Capability Map layout in
```
../create-drawio-diagram/SKILL.md
```
  , then keep, replace, remove, or add nodes based on confirmed target architecture input; do not present unconfirmed starter capabilities as enterprise facts
- Keep capability names identical across the diagram, capability descriptions, glossary, and linked capability documents
- Export
```
diagrams/capability-map.drawio
```
  to
```
diagrams/capability-map.svg
```
  , inspect the SVG using the
```
create-drawio-diagram
```
  export rules, embed the SVG under
```
## Capability Map
```
  , and link the editable Draw.io source from the same
```
diagrams/
```
  subfolder
- If a capability's layer is unknown or disputed, record it as an open question and resolve it instead of guessing
- Present each capability as a short text block instead of a table row, using this order: capability name as a level-three heading, definition, Business outcome, Scope boundary, Target-state direction, and Relevant architecture decisions
- Link the capability name in its level-three heading to the matching capability overview document when one exists under
```
<private-lab-root>/capabilities/<capability-slug>/<capability-slug>.md
```
  ; otherwise use an explicit placeholder such as
```
TBD
```
  or mark it as an open question instead of inventing a path
- Write each capability definition in plain English for a non-technical reader. Explain what the organization must be able to do, avoid implementation language, and spell out unfamiliar abbreviations on first use
- Write Business outcome as the practical benefit or measurable change for customers, employees, partners, or the organization; do not describe a system feature or technical deliverable as the outcome
- Write Target-state direction as a concise description of how the capability should work in the future, focusing on the user or business experience before any necessary technical detail
- Write Scope boundary as a clearly labeled short paragraph that states what the capability includes and excludes
- Within each capability block, populate
```
Relevant architecture decisions
```
  with links to confirmed ADRs that directly affect that capability. Use each ADR title as its Markdown link label. Leave it empty when none are confirmed for that capability; do not add an empty-state message or invent ADR paths
- Add one Markdown horizontal divider (
```
---
```
  ) between consecutive capability blocks. Do not place a divider before the first capability or after the final capability
- Put shared stakeholders and current-state pain points in their dedicated sections after the capability descriptions rather than repeating them inside every capability block
- Application, data, integration, and technology implications
- Dependencies, risks, and roadmap considerations

Create

03-phase-a-architecture-vision.md

from

templates/03-phase-a-architecture-vision-template.md

using Phase A input:

Introduction explaining why this target architecture is needed now - Explains the purpose and value of this architecture initiative
Company mission and vision - Provides strategic context for the proposed change
Strategic drivers
Objectives
Product vision - Describes the intended future product or service experience
Business outcomes
Stakeholders, concerns, and key requirements - Identifies who is affected by this architecture and what matters to them
Architecture initiative scope and exclusions - Defines what this specific ADM cycle includes and excludes
Value streams or major scenarios
High-level baseline and target vision - Communicates the proposed change at vision level
Assumptions, constraints, dependencies, and risks
Transformation readiness
Success measures - Supports approval of the architecture work
Approval and Statement of Architecture Work

Create

04-phase-b-business-architecture.md

from

templates/04-phase-b-business-architecture-template.md

using Phase B input:

Capability map
Organization impacts
Business processes
Operating model changes
Business risks and dependencies

Create

05-phase-c-application-architecture.md

from

templates/05-phase-c-application-architecture-template.md

using Phase C input:

Application landscape
Application responsibilities and boundaries
Channels and frontends
Engagement services
Commerce services
Enterprise applications
Application interactions
APIs and integration patterns
Reuse and application rationalization
Application gaps, dependencies, and risks
Detailed Ecommerce Solution Blueprint

Create

06-phase-c-data-architecture.md

from

templates/06-phase-c-data-architecture-template.md

using Phase C input:

Data domains
Data ownership
Systems of record
Master and reference data
Customer identity and 360-degree customer view
Product, customer, order, and interaction data
Data flows and synchronization
Data quality, privacy, and retention
Analytics and data activation
Data gaps, dependencies, and risks
Linked data architecture designs for specific canonical data objects, left as
```
_No linked data architecture designs yet._
```
until the user explicitly creates them with
```
../data-architecture-design/SKILL.md
```

Create

07-phase-d-technology-architecture.md

from

templates/07-phase-d-technology-architecture-template.md

using Phase D input:

Platforms, infrastructure, security, observability, and operations
Technology standards and constraints
Technology lifecycle concerns

Create

08-phase-e-solution-building-blocks.md

from

templates/08-phase-e-solution-building-blocks-template.md

using Phase E input:

Related capabilities and architecture trace references
Delivery dependencies and sequencing notes
Epics to build, left as
```
_No linked epics yet._
```
until the user explicitly creates epics with
```
../to-epics/SKILL.md
```
When epics exist, present each epic as a level-three linked heading followed by short labeled paragraphs for main capability, description, and phase. Do not use an epic list table.

Create

09-gap-analysis.md

10-roadmap-themes.md

11-governance-actions.md

, and

12-risks-and-open-questions.md

from their matching templates.

In
```
09-gap-analysis.md
```
, write the opening
```
Gap Analysis Summary
```
as five short labeled paragraphs: current situation, target outcome, most important gaps, operational impact, and recommended response.
Under each gap category, present every distinct gap as a level-three heading followed by short labeled paragraphs or bullets for current state, target state, gap, impact, and recommended response.
Do not use a gap-analysis comparison table. If a category has no confirmed gaps, state that briefly instead of adding an empty table or placeholder row.
In
```
10-roadmap-themes.md
```
, write the opening
```
Roadmap Summary
```
as three short labeled paragraphs: business outcome, sequencing approach, and key dependencies.
Under each time horizon, present every roadmap theme as a level-three heading followed by short labeled paragraphs or bullets for outcome, scope, dependencies, and suggested sequence. Do not use a roadmap-theme comparison table.

12-risks-and-open-questions.md

, group risks under

High Risks

Medium Risks

, and

Low Risks

in that order.

Number risks sequentially across all three groups with two-digit identifiers starting at
```
00
```
.
Present each risk using the repeatable block from the template: numbered risk name, a compact Likelihood and Owner table, an Impact section, a Mitigation section, and a horizontal divider.
If a severity group has no confirmed risks, keep its heading and state
```
_No confirmed high risks._
```
,
```
_No confirmed medium risks._
```
, or
```
_No confirmed low risks._
```
as applicable. Do not leave placeholders or an empty risk block.

Before creating the summary document, review the generated section files against
```
<private-lab-root>/GLOSSARY.md
```
and add any missing terms, applications, data objects, and relationships discovered during drafting.

Create

00-target-architecture-document.md

from

templates/00-target-architecture-document-template.md

as the summary and navigation document.

Begin
```
00-target-architecture-document.md
```
with its title and a one-sentence document purpose directly below it, without a purpose heading.
For every numbered detailed page, add the following to
```
00-target-architecture-document.md
```
in this order:
- The detailed page title
- A one-sentence purpose directly below the title, with no purpose heading
- A
```
Management Summary
```
  copied verbatim from that detailed page's
```
Introduction
```
  ; do not paraphrase, shorten, or otherwise rewrite it
- A link to the detailed page
Keep every detailed page's
```
Introduction
```
concise and suitable for management readers because it is also the source text for the summary document. Keep detailed analysis, tables, and implementation detail in the numbered section files.
Keep the section files as the detailed reviewable artifacts. The
```
00-target-architecture-document.md
```
file is the stakeholder-facing overview with links to those detailed sections.
Leave the Phase E
```
Epics To Build
```
section as
```
_No linked epics yet._
```
until the user explicitly creates epics with
```
../to-epics/SKILL.md
```
. Generated epic files belong under
```
<private-lab-root>/requirements/<name-of-target-architecture>/
```
, not under the target architecture folder. Do not infer or create epics during target architecture drafting. Every epic requires a user-provided main capability.
Leave the Phase C
```
Data Architecture Designs
```
table empty until the user explicitly creates data architecture designs with
```
../data-architecture-design/SKILL.md
```
. Generated data architecture design files belong under
```
<private-lab-root>/data-architectures/<data-object-slug>/
```
, not under the target architecture folder.

Guardrails

Keep this public toolkit free of company-confidential information, customer names, internal system names, credentials, and non-public business context.
If using real company details, work in a private company lab repository and write outputs to that repository's
```
solution-architectures/
```
folder.
Do not invent specific enterprise facts. Mark unknowns as assumptions or open questions.
Prefer generic capability names unless the user is working in a private repository.
Do not create data architecture design documents automatically. Data architecture designs require an explicit target architecture link and canonical data object through the
```
data-architecture-design
```
skill.
Do not create epics automatically. Epics require explicit user-provided names, descriptions, and main capabilities through the
```
to-epics
```
skill.

target-architecture-document

NPX Install

Tags

SKILL.md Content

Target Architecture Document

Quick Start

Required Inputs

Workflow

Guardrails