How lilmgenius/polysona works
1. What this repo is
- Polysona is a persona orchestration workspace for AI agents, not a conventional app.
- The core idea is a setup phase that extracts a user persona, then a repeatable content loop that uses that persona across different AI agents and hosts.
2. Top-level architecture
- The repository is split into four main planes:
- Persona/agent definitions in agents/, personas/, and skills/
- Local dashboard UI in client/
- Local API/server in server/
- Generated and operational artifacts in content/ and decks/
- Around that, there is host integration for Codex and Claude Code via AGENTS.md, .claude-plugin/, and hooks/.
3. Persona data layer
- Persona state is stored as plain markdown under personas/default/:
- persona.md for the core persona
- nuance.md for subtle traits or tones
- accounts.md for account/platform context
- This is the main persistent input that downstream agents consume, and it is intentionally file-based so it can be reused across tools.
4. Agent pipeline
- The README’s architecture maps to five named agents in agents/:
- profiler: interviews and extracts persona signals
- trendsetter: collects trend topics
- content-writer: generates platform-specific drafts
- virtual-follower: simulates audience QA and ranks outputs
- admin: handles publish/tracking steps
- The repo treats these as distinct responsibilities, so the persona extraction, content generation, QA, and publishing phases are separated.
5. Content lifecycle and storage
- Content artifacts move through content/ subfolders:
- drafts/
- qa/
- published/
- trends/
- This creates a clear data flow from trend discovery to draft generation, QA review, and publication.
- The pipeline is file-oriented, which makes state easy to inspect and portable between AI tools.
6. Dashboard/UI layer
- client/ is a Vite + React + TypeScript frontend.
- Pages like Home, Personas, PersonaDetail, AgentMonitor, ContentPipeline, and VirtualFollower suggest the UI is a local observability dashboard for the persona system.
- Components such as AgentStatusCard, GapAnalysis, InterviewTimeline, FrameworkCoverage, and ContentQualityMeter indicate the UI is focused on pipeline visibility, persona analysis, and QA inspection rather than end-user content consumption.
7. Server/API layer
- server/index.ts and server/routes/api.ts expose the backend for the dashboard and workspace interactions.
- server/lib/ploon.ts appears to hold shared server-side domain logic for the Polysona system.
- The server likely acts as the bridge between the UI and the filesystem-based workspace state: personas, content folders, and status metadata.
8. Host integration boundaries
- This repo is designed to run inside multiple AI environments:
- Codex via AGENTS.md and synced skills
- Claude Code via .claude-plugin/marketplace.json and plugin.json
- hooks/ provides lifecycle hooks like session start and pre/post tool use, which means the repo can shape agent behavior without hardcoding that logic into the app.
9. Skill system
- skills/ contains command-oriented agent instructions grouped by capability:
- interview
- introduce
- trend
- content
- qa
- publish
- status
- export
- These are the operational “verbs” of the system, and scripts/sync-codex-skills.mjs mirrors them into Codex’s expected layout.
- This is an important portability boundary: the same workflow is exposed through different agent runtimes, but the content lives in one repo.
10. Generated/presentational artifacts
- decks/ contains static slide decks and HTML viewers, likely for demos or product presentation.
- assets/ contains branding assets used by the docs and UI.
- process_svg.py suggests some asset preprocessing in the build/content workflow.
11. End-to-end data flow
- The main flow is:
- interview/extract persona → write structured persona files
- collect trends → create drafts
- QA drafts with a simulated follower persona
- publish and track outcomes
- The dashboard provides visibility into that loop, while the filesystem holds the durable state.
12. How to think about the architecture
- This is best drawn as a local-first orchestration system with a UI and API wrapped around a filesystem-backed multi-agent workflow.
- The key boundaries are:
- persona definition vs. content generation
- agent instructions vs. generated outputs
- host-specific integration vs. portable repo assets
- The repo’s main value is not a single app feature, but the repeatable pipeline connecting those layers.
Main entry points: agents Agent specs · content Content pipeline · skills Skills library · server API server
Components 27
Host integration
Runtime-specific wiring for Codex and Claude Code, plus lifecycle hooks and skill syncing.
- Hooks · Lifecycle hooks that shape agent behavior in supported hosts.
hooks - Claude plugin · Claude Code plugin and marketplace metadata.
.claude-plugin - Codex sync · Mirrors skills into Codex-compatible layout.
scripts/sync-codex-skills.mjs
Persona and agents
Persistent persona state, agent role definitions, and reusable skill instructions.
- Persona store · Default persona files used as the durable input for the workflow.
personas/default - Core persona · Primary persona profile consumed by downstream agents.
personas/default/persona.md - Nuance notes · Secondary tone and subtle-trait context for the persona.
personas/default/nuance.md - Account context · Platform and account context for persona-specific operations.
personas/default/accounts.md - Agent specs · Role-specific agent prompts and behavior definitions.
agents - Profiler · Interviews and extracts persona signals.
agents/profiler.md - Trendsetter · Collects trend topics for content planning.
agents/trendsetter.md - Content writer · Generates platform-specific drafts from persona and trend inputs.
agents/content-writer.md - Virtual follower · Simulates audience QA and ranks content quality.
agents/virtual-follower.md - Admin · Handles publish and tracking steps.
agents/admin.md - Skills library · Portable command-oriented instructions shared across runtimes.
skills - Interview · Guides persona extraction interviews.
skills/interview/SKILL.md - Content · Guides content generation workflows.
skills/content/SKILL.md - QA · Guides simulated audience review and critique.
skills/qa/SKILL.md - Publish · Guides publication and tracking steps.
skills/publish/SKILL.md
Workspace runtime
Local API and dashboard that inspect and coordinate the filesystem-backed workflow.
- Dashboard · Local observability UI for personas, agents, and content flow.
client - API server · Backend bridge between the dashboard and filesystem-backed workspace state.
server - Ploon logic · Shared server-side workspace logic.
server/lib/ploon.ts
Artifacts
Generated drafts, QA outputs, published content, and presentation assets.
- Content pipeline · Filesystem-backed lifecycle for drafts, QA, trends, and published outputs.
content - Drafts · Generated content drafts awaiting review.
content/drafts - QA outputs · Review artifacts produced by the virtual follower stage.
content/qa - Published · Final published content artifacts.
content/published - Trends · Collected trend signals used to seed content generation.
content/trends - Decks · Static slide decks and viewers for demos or presentations.
decks
Connections 26
- Persona store → Core persona: contains · The persona store is materialized as markdown files.
- Persona store → Nuance notes: contains · Nuance is stored alongside the core persona.
- Persona store → Account context: contains · Account context lives in the same durable store.
- Agent specs → Profiler: defines · Agent files declare distinct responsibilities.
- Agent specs → Trendsetter: defines · Trend collection is a separate role.
- Agent specs → Content writer: defines · Draft generation is isolated as its own role.
- Agent specs → Virtual follower: defines · QA is modeled as a simulated audience agent.
- Agent specs → Admin: defines · Publishing and tracking are handled separately.
- Skills library → Interview: includes · Interview instructions are one of the portable skills.
- Skills library → Content: includes · Content generation instructions are packaged as a skill.
- Skills library → QA: includes · Quality review behavior is defined as a skill.
- Skills library → Publish: includes · Publication workflow is exposed as a skill.
- Hooks → Agent specs: orchestrates · Lifecycle hooks can steer agent execution in host environments.
- Claude plugin → Hooks: loads · Claude Code integration uses plugin metadata and hooks.
- Codex sync → Skills library: syncs · Skill definitions are mirrored for Codex runtime consumption.
- API server → Ploon logic: uses · API routes rely on shared server-side domain logic.
- Dashboard → API server: calls · The UI talks to the backend for workspace state and actions.
- API server → Persona store: reads · Backend surfaces persona state to the dashboard.
- API server → Content pipeline: reads writes · Backend bridges filesystem content stages.
- Content pipeline → Trends: feeds · Trend discovery seeds the content workflow.
- Content pipeline → Drafts: creates · Drafts are generated from persona and trend inputs.
- Content pipeline → QA outputs: routes to · QA artifacts are produced after follower review.
- Content pipeline → Published: lands in · Approved content is published into the final stage.
- Dashboard → Content pipeline: visualizes · The dashboard emphasizes pipeline visibility and inspection.
- Dashboard → Agent specs: monitors · Agent status and behavior are observable in the UI.
- Decks → Dashboard: supports · Presentation assets complement the local product story.