Archify with AI agents: from source code to five diagram modes

Archify is not an app that roams through a repository and guesses everything on its own. It is a skill and toolchain that helps an AI agent turn bounded facts or a proposal into structured JSON, validate that source, and render a reviewable standalone HTML artifact.

Think of the AI agent as the surveyor and Archify as the drawing standard. The agent still reads the source, separates known facts from gaps, chooses a viewpoint, and authors the content. Archify checks the schema, composition, geometry, and artifact delivery. It does not understand the system on the agent's behalf.

Two common questions, answered

“Does it read code and draw the flow, or do I design the flow?” It supports both.

• For an existing system, the agent inspects repository evidence and documents the current state.
• Before implementation, you provide a brief and the agent structures a proposed design.

Those modes need different labels. CURRENT is supported by current source. OBSERVED comes from logs or an experiment. PROPOSED is a future design. UNKNOWN marks missing evidence.

“How do I attach it to AI?” The shortest route is the Skills CLI. Then open the agent in the relevant project and name Archify in your prompt:

npx skills add tt-a1i/archify -g

For an explicit project-local Codex install:

npx -y skills add tt-a1i/archify --skill archify --agent codex --copy --yes
node .agents/skills/archify/bin/archify.mjs doctor

Change codex to another agent supported by the official switcher, or add --global to use the skill across projects. Codex discovers ~/.agents/skills/ or .agents/skills/; Claude Code uses ~/.claude/skills/ or .claude/skills/. You can also try it with Codex without a permanent install: npx skills use tt-a1i/archify@archify --agent codex.

Useful search terms include Agent Skills, SKILL.md, skill discovery, Archify typed JSON IR, architecture diagram, workflow diagram, sequence diagram, data lineage, and state machine.

One running example: Tiệm bánh Mây

We will use a fictional online bakery. A customer places an order on the website; the system checks availability, creates the order, requests payment, sends a ticket to the kitchen, and updates the customer.

This is a PROPOSED system, not a tested application. The same story produces five different questions.

Reader question	Best mode
What parts make up the system?	Architecture
What steps process an order?	Workflow
Who calls whom when checkout starts?	Sequence
Where does customer and order data go?	Data Flow
Which states can an order enter?	Lifecycle

A common mistake is forcing all five questions into one diagram. The result may be comprehensive but hard to read. Start with one reader question, not “draw me a very detailed diagram.”

Scenario 1: inspect a repository and document current behavior

Use this for onboarding, investigating a request path, or refreshing documentation that has drifted from code.

The agent should inspect relevant entry points, routes, services, persistence, queues, infrastructure configuration, and tests. Important nodes and relationships need evidence. A filename alone does not prove runtime behavior; if a service is declared but never called, the agent should not invent an edge.

Use the Archify skill to inspect this repository and create an Architecture diagram.

Reader question:
Which components handle an order-creation request?

Requirements:
- Use repository-supported facts only.
- List the files used as evidence for major nodes and edges.
- Separate CURRENT from UNKNOWN; do not invent services.
- Author typed JSON, validate at showcase quality, and deliver HTML.
- Report diagram verification separately from application test status.

A useful handoff includes reviewable JSON, standalone HTML, a delivery receipt, and explicit gaps—not just a picture.

Scenario 2: design a flow before writing code

Use this during discovery, proposal review, or feature alignment.

For Tiệm bánh Mây, the brief might say: check availability, request payment, and send a kitchen ticket. The agent can expose missing actors, decisions, and states. Everything remains PROPOSED until it is implemented and tested.

Use the Archify skill to design a PROPOSED Workflow for an online bakery.

Reader question:
How does an order move from customer confirmation to the kitchen?

Allowed facts:
- Check availability before payment.
- Payment may be accepted or declined.
- Send the order to the kitchen only after acceptance.

State assumptions and UNKNOWN items before authoring JSON.
Do not present a planning sketch as tested behavior.

Archify does not “run the flow” by calling your API, database, or payment sandbox. Proving the design still requires an appropriate prototype, unit test, integration test, or end-to-end test.

Scenario 3: Architecture — map the parts

Architecture answers which components exist, where boundaries sit, and which major relationships connect them. A Tiệm bánh Mây main path might be Customer → Website → Order API → Order Store, with payment and kitchen processing as supporting paths.

Use it for system overviews, onboarding, dependency review, deployment ownership, or architecture deltas. Do not use it to narrate every message.

Use Archify Architecture for Tiệm bánh Mây.
Question: which major components should a new teammate understand, and how do they connect?
Keep the main path prominent. Treat payment and kitchen as secondary paths.
Label the entire artifact PROPOSED.

Quick reading test: can a viewer point to each component and explain its responsibility?

Scenario 4: Workflow — map the work

Workflow explains the actors, actions, and decisions involved in completing a task. It fits business processes, CI/CD, incident response, approvals, and runbooks.

For Tiệm bánh Mây, the happy path is availability check → payment → kitchen ticket. Out of stock, declined payment, and refunds are exceptions. The main path should be easier to follow than the failure branches.

Use Archify Workflow to describe order processing.
Question: where should an operator continue or stop an order?
Show actors, decisions, the happy path, and only failure paths present in the brief.
Do not add retries or timeouts without evidence.

Quick reading test: at each decision, can the viewer identify the condition and next action?

Scenario 5: Sequence — map message order

Sequence answers who calls whom, what arrives first, and how results return. It is useful for API contracts, distributed tracing, and integration debugging.

Use Archify Sequence for POST /orders.
Question: from clicking Place order to receiving an order ID, who calls whom and in what order?
Use only participants supported by source or the brief.
Mark sync/async messages and the declined-payment branch when evidence exists.

Quick reading test: can an engineer reconcile each message with a trace or handler?

Scenario 6: Data Flow — follow the data

Data Flow does more than connect services. It identifies what data is collected, transformed, stored, or sent outside a boundary.

Customer contact details and order lines may enter the Order Store; a payment request goes to a provider; the kitchen ticket may need products and notes without receiving all customer data.

Use Archify Data Flow for a bakery order.
Question: where do customer details, order data, and payment results go?
Distinguish sources, processes, stores, and external sinks.
Label every flow with the data being transferred.
Mark retention, encryption, or PII handling UNKNOWN when evidence is absent.

Quick reading test: can a reviewer identify every boundary crossed by sensitive data?

Scenario 7: Lifecycle — map valid states

Lifecycle explains which states an entity can occupy and which events or guards permit transitions. An order might follow DRAFT → AWAITING_PAYMENT → CONFIRMED → IN_KITCHEN → READY → COMPLETED, while every route to CANCELLED needs an explicit condition.

Use Archify Lifecycle for Order.
Question: which valid paths can a bakery order take through its states?
List the event or guard for each transition.
Mark unsupported states or transitions PROPOSED or UNKNOWN.

Quick reading test: are there unreachable states, states with no exit, or impossible transitions out of terminal states?

A trustworthy pipeline

Narrow reader question
→ bounded evidence or brief
→ typed JSON
→ validate
→ deliver HTML
→ visual-check
→ human screenshot review

A successful showcase validation reports all nine artifact checks with no composition errors or warnings. deliver snapshots the specification, renders it, and atomically commits the HTML. visual-check then measures containment across several desktop viewports and captures light/dark evidence.

The automated visual receipt deliberately remains visualReview: "pending". A human still has to inspect the screenshots before describing the artifact as polished. The entire pipeline verifies the diagram artifact, not application behavior.

Verified demo status

The Tiệm bánh Mây demo contains five JSON sources and five standalone HTML artifacts. All five passed 9/9 showcase, with 0 composition errors, 0 warnings, and successful automated visual checks. Human review inspected light and dark captures at the smallest and largest viewports. Workflow passed with one note: its refund exception is intentionally long but does not overflow.

This is evidence for the Archify authoring pipeline. No Tiệm bánh Mây application was built or executed.

Common failure modes

A polished but fictional topology. Require evidence for important nodes and edges; unresolved items stay UNKNOWN.

One diagram answers too many questions. Split Architecture, Workflow, Sequence, Data Flow, and Lifecycle views.

A proposal is presented as current architecture. Put PROPOSED in the artifact title, subtitle, and handoff.

Validation is treated as an application test. Report diagram verification and application verification separately.

Visual-check runs after failed delivery. The previous good artifact may still exist at the output path. Inspect visuals only after the new delivery succeeds.

Reusable prompt template

Use the Archify skill to create a [TYPE] diagram for [PROJECT/FLOW].

Reader question:
[ONE NARROW QUESTION]

Allowed evidence:
[FILE/PATH/LOG/BRIEF]

Separate CURRENT / OBSERVED / PROPOSED / UNKNOWN.
Do not invent facts. Author typed JSON, validate at showcase quality,
deliver HTML, run visual-check, and report human review separately.
Do not equate diagram validation with application testing.

Official sources

• Archify on GitHub
• Archify Guide

Open Questions

• A public download link for the complete demo will be added after the artifacts are approved and released.