Agent Isles
Markdown seas, component islands.
Agent Isles is a semantic Markdown renderer for AI-agent artifacts. Agents write standard Markdown, then embed small HTML “islands” where richer UI is useful. Those islands can be raw Bootstrap markup for simple one-off layout or semantic Lit Web Components for repeated agent-output patterns like risks, decisions, metrics, plans, timelines, checklists, and review surfaces.
Agent Isles is intentionally not a general data-app framework. Its center of gravity is agent-authored documents: plans, reports, decision records, implementation notes, reviews, checklists, and other artifacts that should stay readable as Markdown, reviewable in git, and useful when rendered for humans.
Why this exists
Agent output should be:
- easy to write,
- easy to diff,
- easy to store in git,
- richer than plain Markdown when the task calls for it,
- renderable without forcing every agent to hand-author verbose UI boilerplate,
- structured enough for humans and agents to inspect, patch, and reuse later.
Agent Isles keeps the source format simple while giving agents a compact UI vocabulary. The aim is not maximum frontend expressiveness; the aim is a constrained, reliable document grammar that agents can emit consistently and humans can maintain.
What Agent Isles is for
Agent Isles is designed for artifacts such as:
- project plans and implementation plans,
- decision records and recommendations,
- risk registers and mitigation notes,
- release checklists and review checklists,
- compact status reports and executive summaries,
- migration timelines and roadmap views,
- AI-generated reports that need more structure than a wall of Markdown.
The source should remain boring:
# Migration Plan
<agent-decision verdict="go" title="Use Markdown islands">
Ship the first renderer slice and keep source reviewable.
</agent-decision>
- [ ] Review launch gates
- [x] Add render smoke test
The rendered output can be polished and interactive, but the Markdown source remains the primary artifact.
What Agent Isles is not trying to be
Agent Isles should not grow into a broad dashboard or application framework. It should avoid becoming a place where every report requires custom JavaScript, complex data pipelines, or bespoke UI code.
Use Agent Isles when the valuable thing is the document artifact: a readable source file, semantic islands, and a rendered view that helps people review or act on it. For heavy data exploration, custom charting, multi-page analytical apps, or production analytics workflows, use a purpose-built data-app stack and let Agent Isles stay focused on agent-authored documents.
Demo: source Markdown to rendered report
The public demo lives in examples/demo.md. It is intentionally readable as plain Markdown, but it also includes richer islands:
- Bootstrap cards for quick metrics,
- Markdown tables and code fences for portable evidence,
<agent-decision> elements for recommendations,<agent-risk> elements for caveats and mitigations,<agent-gantt> schedules for phase lanes, milestone weeks, overlapping work, and task details,<agent-status-board> boards for derived RAG/health rollups across workstreams.
Render it locally:
npm install
npm test
npm run render -- --out dist/demo.html
Then open:
dist/demo.html
The renderer turns the Markdown source into a browser-ready HTML report, injects Bootstrap and the Agent Isles theme, and copies the component bundle next to the generated page. This makes the workflow reviewable in pull requests while still producing a credible artifact for humans.
Current status
The first renderer slice exists:
npm install
npm run build
npm run render -- --out dist/demo.html
That renders examples/demo.md to dist/demo.html and copies the component bundle beside it.
Demo
The rendered demo is published by the GitHub Pages workflow after changes land on main.
Installation and npm prerelease path
Agent Isles is prepared for a first npm prerelease, but publication is still a deliberate release action. Do not publish from routine development or automation without explicit maintainer approval.
Local development usage:
npm install
npm run build
node ./bin/isles.mjs render examples/demo.md --out dist/demo.html
To smoke-test the installed command locally before any registry publish:
npm link
isles render examples/demo.md --out dist/demo.html
After an approved npm prerelease is published, the expected consumer paths are:
npm install -g agent-isles@next
isles render ./report.md --out ./report.html
npx agent-isles@next render ./report.md --out ./report.html
