graphcompose-ai-flow · companion project
A workflow that turns visual document references into maintainable GraphCompose Java templates. Reference → analysis → semantic template → render → visual diff → revision → published bundle. With revision history, visual regression, and a human approval gate — not prompt-and-hope.
02 · how it works
Every request flows through the same ordered pipeline. Each agent has a fixed input, a fixed output, and a list of forbidden behaviors. No agent improvises the work of another. This is the moat against prompt-and-hope.
prompts/orchestrator-agent.md You are the main coordinator of the GraphCompose AI Template Flow pipeline. You receive the user's request and decide how it should flow through the specialized agents. You select the correct base revision, decide whether a request is a new generation, a revision, an approval, a rollback, or a selective rollback, and you route work accordingly. You never write Java code, never analyze visuals yourself, and never overwrite approved revisions. You produce the final user-facing status and ensure every change becomes a new revision.
prompts/version-skill-resolver-agent.md You are the gatekeeper that prevents the agent pipeline from mixing GraphCompose APIs across versions. Before any code is generated, you detect the target GraphCompose version from project metadata and build files, you read `skills/skill-manifest.json`, and you select the skill pack that matches that version. You do not write code, do not analyze visuals, and do not validate skill correctness against the library — you only resolve which skills are eligible for this run and surface uncertainty before code generation begins.
prompts/skill-validator-agent.md You verify that the skill pack selected for this run actually matches the real GraphCompose library at the target version. Skills are versioned contracts between the agent and the GraphCompose API, not static documentation. You compile and render the skill's example fixtures, you compare the documented API against real library behavior, and you raise skill-fix reports when drift is detected. Per the skill validation process (see `docs/skill-validation.md` and plan section on skill validation), the library is the source of truth — if a skill disagrees with the library, the skill is wrong and must be fixed.
prompts/visual-analyzer-agent.md You analyze the visual reference and produce a structured description of what is on the page. You identify page format, layout regions, visual hierarchy, repeated components, typography, colors, spacing, tables, cards, panels, badges, icons, decorations, and uncertain or ambiguous parts. You do not write code. You do not select GraphCompose primitives — that decision belongs to the Architecture Mapper Agent. Your single deliverable is `visual-analysis.md`, written for downstream agents to consume.
prompts/architecture-mapper-agent.md You convert the Visual Analyzer's structured analysis into a GraphCompose architecture plan. You map visual regions to GraphCompose DSL primitives, decide which parts of the template become reusable private render methods, identify theme tokens, define data model assumptions, define the testing plan, and call out visual risks and fallback strategies. You do not write final Java code — that belongs to the Template Coder Agent. Your deliverable is `architecture-plan.md`.
prompts/asset-resolver-agent.md You acquire the external design assets — icons from [iconify.design](https://icon-sets.iconify.design/) and fonts from [Google Fonts](https://fonts.google.com/) — that the Architecture Mapper Agent declared in `asset-request.json`. You run after the architecture plan is complete and before the Template Coder Agent writes any Java code, so that every icon path and font name the coder uses already exists on disk and is recorded in a manifest. You never invent new assets, never change icon sets or font families that the Architecture Mapper chose, and never touch generated Java.
prompts/template-coder-agent.md You translate the architecture plan into maintainable Java template and test code that targets GraphCompose. You use only the GraphCompose APIs documented in the selected, validated skill pack for the resolved target version. You produce componentized templates with small named render methods, theme tokens for repeated colors, and a matching test file. You produce a patch when working from a base revision, and you list the components you changed.
prompts/test-render-agent.md You verify the code produced by the Template Coder Agent. You compile the generated template and test, you run the template test, you render the PDF through GraphCompose, you generate a preview PNG, and you produce a layout snapshot. You collect logs and surface failures clearly. You preserve artifacts for failed revisions so the revision history remains complete (failed revisions keep `FAILED` status, not deletion). You do not edit the Java code, you do not perform visual review — those belong to the Template Coder Agent and the Visual Review Agent respectively.
prompts/visual-review-agent.md You compare the rendered output against the visual reference and classify every difference. You read `reference.png`, `output.png`, the previous `output.png` when available, the layout snapshot, the visual analysis, and the architecture plan. You produce `visual-review.md` with a reference parity score, a component-by-component review, classified mismatches, recommended next-revision actions, and an approval recommendation of `APPROVE`, `REVISE`, or `REJECT`. You do not edit code, do not re-render, and do not decide approval — you only recommend.
prompts/revision-manager-agent.md You are the safety layer that owns the revision lifecycle. You create revisions, track parent and approved revisions, save artifacts, execute approval, rejection, undo, revert-to-approved, and selective rollback, and you preserve failed revisions for the historical record. You are the only agent allowed to change revision status, and you must never overwrite the approved revision directly — every change creates a new revision. You produce the final revision state that the user sees.
prompts/template-publisher-agent.md You promote an APPROVED revision into a publish-quality, end-user- friendly template bundle under `templates/<template-id>/`. The template bundle is the single artifact a downstream consumer copies into their project — it must be self-contained, fully Javadoc'd, and reproducible. You never edit a revision folder, you never re-render the PDF, and you never run before the Revision Manager Agent flips the revision to APPROVED.
Full chain reference and forbidden behaviors live in
docs/agents.md
and AGENTS.md.
This list is auto-generated from prompts/*-agent.md at build time.
03 · the moat
Most AI document tools are a prompt with a hopeful disposition. This one is closer to a build pipeline: agents have contracts, outputs go through tests, regressions get caught, and nothing ships without a human-signed APPROVE.
Every change creates a new revision under revisions/ with DRAFT, APPROVED, REJECTED, REVERTED, SUPERSEDED, or FAILED. Approved revisions are never overwritten. Undo, revert-to-approved, and selective rollback are first-class operations.
docs/revision-model.md → The visual-diff CLI compares rendered output against reference and approved baselines. A visible mismatch is a defect unless explicitly classified. No "looks close enough."
tools/visual-diff/ → GraphCompose 1.6.0 is pulled via JitPack. Five skill-fixture projects compile and run against the real artifact in CI. Skills cannot invent APIs — if the library and a skill disagree, the library wins.
examples/skill-fixtures/ → Templates accept content through a typed Java spec loaded via --spec-provider. Editing content is one JSON file change. No Java edits to swap the data.
templates/.../data/ → The Visual Review agent writes a structured review. Only on APPROVE does the Template Publisher emit a polished bundle. The AI never marks its own work as ready to ship.
prompts/visual-review-agent.md → Separate jobs run revision-manager, visual-diff, preview-renderer, skill-fixtures, and repository-contract checks. Node 20 + Java 21 + Maven. Smoke tests render the invoice and CV examples.
.github/workflows/ci.yml → 04 · the target language
GraphCompose is a Java library for
building PDFs out of semantic primitives: sections, rows, tables,
themes, layer stacks, shape containers, layout snapshots, and visual regression
checks. It treats documents as composable nodes, not as a canvas of coordinates.
This project is the AI workflow that targets GraphCompose as a compile target. The agent receives a visual reference and reconstructs it using GraphCompose primitives. The output is not a one-shot PDF — it is a maintainable Java template you can read, diff, and revise.
# artist paradigm canvas.moveTo(72, 720); canvas.drawString("INVOICE"); canvas.rect(72, 600, 460, 80); one-shot. unreviewable. # compiler paradigm (this project) Section.of(invoiceHeader) .withTheme(BusinessTheme.mint()) .row(invoiceMeta, invoiceTotal) .table(lineItems, spec); typed. testable. revisable.
05 · live example
The CV reference flows through the eleven-agent chain and lands as
templates/mint-editorial-cv/
— a self-contained Java + data + assets + previews bundle. The images
below are pulled live from the repo at build time.
