The AI Triforce of Seed4j: Power, Wisdom, and Courage for Your Dev Agent

In the Legend of Zelda, the Triforce is the ultimate relic: three golden triangles that together grant the wish of whoever holds them. Alone, each fragment is dangerous in the wrong hands. Together, they bring balance to Hyrule.

I've been thinking about Seed4j's relationship with AI agents through that lens. Not as a finished story, but as a reflection. What would it take to make Seed4j truly AI-native? What are the three fragments we need to forge?

This article is that reflection.

Seed4j is an open-source application generator built around hexagonal architecture. It scaffolds the structure (ports, adapters, configuration, modules) but deliberately stops there. It has never generated business code, and that's a conscious design decision. The domain logic belongs to the developer. Seed4j hands you a well-structured, empty shell, and you fill it.

At the era of AI agents, that boundary gets interesting. An agent can write business code. The question is: can Seed4j guide it to do so correctly, within its own philosophy? Can the agent become the missing piece, not replacing Seed4j's intentional silence, but completing it?

That's what led me to think about three principles: the MCP (Power), the Harness (Wisdom), and the Skills (Courage). Together, they sketch what a Seed4j augmented might look like, an AI-compatible version of the project, without betraying what makes it Seed4j.

Fragment 1: The MCP, The Triforce of Power

"Power without direction destroys. Power with the right interface builds."

The first question is simple: how does an AI agent actually do something with Seed4j, rather than just talk about it?

The answer is a Model Context Protocol server, seed4j-mcp. MCP is an open standard that lets AI agents call tools exposed by external servers. Instead of a human typing commands into a CLI, an MCP-aware agent (Claude Code, Claude Desktop, Cursor, and others) can discover and invoke Seed4j's functionality directly.

The seed4j-mcp server exposes a set of tools that map to the full Seed4j workflow:

Tool	Purpose
list_modules	List every available module, grouped by category
search_modules	Keyword search across slugs, descriptions, and tags
get_module_details	Property definitions for a given module
get_module_dependencies	Prerequisite graph before applying a module
validate_properties	Dry-run schema check (no side effects)
list_presets	Curated pre-ordered stacks (e.g. "Webapp: Vue + Spring Boot")
apply_preset	Resolve a preset and apply all its modules in one call
create_project	Initialize a new base project
apply_modules	Apply an ordered list of modules in a single batch

A typical agent flow: list_presets → get_preset_details → apply_preset. Or for a custom stack: search_modules → get_module_dependencies → validate_properties → apply_modules.

The MCP server acts as a boundary layer. The agent doesn't need to understand Seed4j's internals, it just needs to know what tools exist and what they accept. Every action goes through a defined, typed interface. Power, channeled.

🗡️ What could be done

Publish seed4j-mcp to the official MCP registry, so any agent, regardless of the client, can discover and wire up Seed4j with a single reference. This is the lowest-friction path to making Seed4j a first-class citizen in the AI agent ecosystem.

Fragment 2: The Harness, The Triforce of Wisdom

"Wisdom is knowing where you are, what the rules are, and what not to touch."

Even with the right tools, an agent can still drift. It might apply modules out of order, ignore architectural conventions, or, worse, start writing code where it doesn't belong. Raw power without wisdom is Ganondorf with the Triforce: capable of anything, guided by nothing.

The Harness is how we give the agent a sense of place.

In practice, a harness is a set of files that speak directly to the agent, not documentation written for humans but context written for AI. The most common form today is a file like CLAUDE.md, which Claude Code reads automatically at the start of every session. It tells the agent what the project is, what conventions govern it, and what it should or should not attempt on its own.

Here's where Seed4j has an interesting starting point: it already generates a /documentation folder inside every project. That folder contains explanations of the hexagonal architecture, the module system, and how the generated structure is meant to be used. It was written for developers, but it could become the foundation of an AI-oriented harness.

That's the gap worth closing. The documentation exists, but it wasn't designed with an agent in mind. An AI-ready harness would go further: explaining not just what Seed4j generated, but how an agent should reason about it. Which parts of the codebase are Seed4j's territory (don't touch), which parts are the agent's responsibility (the domain), and where the boundary between the two sits.

This matters because Seed4j's hexagonal structure has a clear separation of concerns (ports, adapters, domain, application layer) and an agent that doesn't understand that separation will eventually violate it. Not out of malice, but out of ignorance. The harness is what turns ignorance into awareness.

🗡️ What could be done

Generate an AI-oriented documentation layer alongside the existing /documentation folder, in a dedicated /ai-context (or similar) that describes the architecture, the conventions, and the agent's role in terms an LLM can act on. Unlike the existing docs, this wouldn't be written for a developer to read linearly; it would be structured to be loaded as context at the start of an agent session, answering the questions the agent would otherwise guess at.

📄 Example: .ai/context.md generated by Seed4j

# Seed4j Project Context

> This file is auto-generated by Seed4j. Do not edit manually.
> Re-generated on every `seed4j apply` command.
> Applied modules history: see `.seed4j/modules/history.json`

## Project
- Name: my-app
- Architecture: Hexagonal (Ports & Adapters)

## Package structure
com.example.myapp
├── domain/
│   ├── model/         ← business entities, pure Java, no framework
│   └── port/
│       ├── in/        ← use case interfaces (input ports)
│       └── out/       ← repository interfaces (output ports)
├── application/       ← use case implementations
└── infrastructure/
    └── adapter/
        ├── in/rest/   ← REST controllers (Spring MVC)
        └── out/persistence/ ← JPA repositories and entities

## What Seed4j owns — do not modify
- All configuration files (application.yml, pom.xml, Docker files)
- Infrastructure wiring and module setup
- Base package structure and adapter boilerplate

## What you (the agent) are responsible for
- Domain model: entities and value objects in domain/model/
- Ports: use case and repository interfaces in domain/port/
- Use cases: business logic implementations in application/
- Adapters: framework wiring in infrastructure/adapter/

## Rules
- NEVER import infrastructure or framework classes into domain/ or application/
- NEVER implement business logic in adapters
- ALWAYS go through a port interface, never call an adapter directly
- Run `./mvnw test` after each implementation step

## Available skills
- .ai/skills/hexagonal-feature.md  → implement a business feature end-to-end
- .ai/skills/apply-module.md       → safely apply a new Seed4j module
- .ai/skills/tdd-domain.md         → TDD workflow for domain logic

💡 There is no universal standard for AI context folders yet. .ai/ is a pragmatic choice: readable, non-conflicting with existing tools, and scoped to the project. A root-level CLAUDE.md or AGENTS.md can simply point to .ai/context.md for compatibility with agents that expect a specific filename.

Fragment 3: The Skills, The Triforce of Courage

"Courage isn't acting blindly. It's knowing the path and walking it, step by step."

This is where the reflection gets most interesting, and where Seed4j's design philosophy creates the most productive tension.

Seed4j gives you a shell. A well-architected, hexagonal, configuration-complete shell, but a shell. It has never generated business logic, and it never will. That's not a limitation; it's a statement. The domain belongs to the developer.

But here's the question worth sitting with: if an AI agent can write the domain code, who teaches it to do so correctly within Seed4j's framework?

That's the role of Skills: not tools (those are the MCP's job), not context (that's the Harness), but workflow. Step-by-step guidance for complex, multi-stage tasks that live in the space Seed4j deliberately leaves empty.

Link didn't walk into Ganon's castle on day one. He completed the dungeons in order, acquired the right items, and followed the critical path. A skill is the dungeon map: a structured sequence the agent follows to reach a goal without going off the rails.

For Seed4j, skills could operate at two levels:

Module-level skills: guiding the agent through the correct application of Seed4j modules. Apply in the right order, resolve dependencies, validate before committing. This is the mechanical layer: making sure the shell is assembled correctly before writing a single line of business code.

Feature-level skills: this is the more ambitious and more interesting layer. A skill that guides an agent through implementing a business feature the Seed4j way: domain object first, then the use case, then the port, then the adapter, tests at every step. Or a TDD-oriented skill: write the failing test, implement the minimum domain logic, make it pass, then wire the infrastructure. All of it respecting the hexagonal boundaries that Seed4j established.

The agent doesn't replace the developer's judgment, it follows a workflow that encodes that judgment. Seed4j's silence on business code wasn't a gap; it was a boundary. Skills are what allow an AI agent to operate inside that boundary without erasing it.

🗡️ What could be done

Develop a library of Seed4j skills for common agent workflows, starting with the most frequent pain points:

• Module application skill: apply a module correctly, resolve its dependency graph, validate before committing.
• Hexagonal feature skill: implement a business feature end-to-end following the hexagonal layering Seed4j establishes.
• TDD skill: red-green-refactor loop with an AI agent, domain-first, infrastructure last.

These skills would live in the Seed4j ecosystem and be referenced by the harness, so the agent knows they exist and when to invoke them.

📄 Example: hexagonal-feature.md skill

# Skill: Implement a Hexagonal Feature

## Goal
Guide the agent through implementing a business feature
respecting Seed4j's hexagonal architecture boundaries.

## Prerequisites
- Project initialized with Seed4j base module
- Persistence module applied (`seed4j apply persistence`)

## Steps

### 1. Define the domain object
- Create the entity in `src/main/java/{package}/domain/model/`
- Pure Java: no framework annotations, no infrastructure imports
- Write a unit test before implementing (red phase)

### 2. Define the ports
- Create the input port (use case interface) in `domain/port/in/`
- Create the output port (repository interface) in `domain/port/out/`
- Ports are Java interfaces only, no implementation here

### 3. Implement the use case
- Implement the input port in `application/`
- Inject the output port by interface, never the adapter directly
- Write the unit test (mock the output port), then implement

### 4. Implement the adapter
- Persistence adapter in `infrastructure/adapter/out/persistence/`
- REST adapter (if REST module applied) in `infrastructure/adapter/in/rest/`
- Wire to the framework (JPA, Spring MVC, Quarkus REST...)

## Rules
- NEVER import infrastructure classes into `domain/` or `application/`
- NEVER skip the port layer to call an adapter directly
- ALWAYS write the failing test before the implementation
- If a layer doesn't exist yet, check which Seed4j module provides it

## Notes
This skill is available because the persistence module is applied.
If the REST module is also applied, expose the use case via a REST adapter in step 4.

The Triforce, Complete

These three fragments are not independent: they form a system, and each one only makes full sense in relation to the others.

The MCP (Power) gives the agent the ability to act on Seed4j. The Harness (Wisdom) anchors it in the reality of the project: its architecture, its conventions, its boundaries. The Skills (Courage) guide it through the workflows that Seed4j intentionally leaves to the developer, without violating the philosophy that makes Seed4j what it is.

Strip any fragment away and the balance breaks. Power without Wisdom is chaos. Wisdom without Courage is paralysis. Courage without Power is intention without effect.

What excites me about this vision is that it doesn't ask Seed4j to become something it's not. It doesn't generate business code, the agent does. It doesn't instruct the developer, the skills do. Seed4j remains the generator of structure. The Triforce is what makes that structure legible to an agent, navigable in its architecture, and extensible through AI-guided workflows.

This is a reflection, not a roadmap. But it feels like the right direction for a Seed4j augmented, a version of the project where AI agents are first-class participants, not afterthoughts bolted on from the outside.

The fragments are out there. Time to find them.

Seed4j is an open-source application generator. The MCP server is available at github.com/avdev4j/seed4j-mcp.