AgentFrame is a file-native workspace harness designed to run inside AI coding agents like Claude Code, Cursor, VS Code, or Antigravity. The harness itself is completely domain-neutral. Currently, it supports marketing campaigns and project-management projects, utilizing modular domain packs that can be expanded in the future. The workflow runs through two AGENTS.md modes: Operator handles project execution, and Builder manages system architecture and templates.
This is my workspace where I build and run my projects—longer-term projects, campaigns, and tools. Evolving this codebase is a direct reflection of the type of work that I do day-to-day. Evolving this workspace helps keep the agent focused, fast, and organized. It is free to fork, so feel free to take whatever is useful for your own setups.
- Quick start
- Why this exists
- Domains are packs
- A real project, step by step
- The deterministic harness
- Key features
- At a glance
- Design principles
- Connectors
- Architecture
- Repository structure
- Preview server
- Auditability and state
- Roadmap
- Contributing
- References and lineage
- License
- Contact
-
Clone the repository:
git clone https://github.com/situhacks/agentframe.git cd agentframe -
Open the folder in your coding agent of choice (Claude Code, Codex, Cursor, VS Code, or Antigravity). If you are using Claude Code, it automatically loads
CLAUDE.mdwhich imports the activeAGENTS.mdpersona, pinning the agent's behavior so it survives memory compaction. -
Configure environment variables. Copy
.env.exampleto.envand add optional keys for Gemini (used for Deep Research and image generation) and Composio (used for platform publishing). Both are optional; the system will run locally without them, but you will lose external API connections. If you intend to use Open Design for local visual rendering, runcorepack pnpm installinsidesystem/skills/open-design/source/. -
Scaffold a new project. Instruct the agent to "start a new marketing campaign" or "start a new project-management project". Under the hood, the agent runs
af new-project <slug> --domain <marketing|project-mgmt>to read the domain pack and scaffold the directory structure.
AgentFrame uses two distinct AGENTS.md personas to establish clean boundaries:
- Operator mode runs active projects. It is locked to
workspace/projects/so the agent cannot edit templates, rules, or core processes while executing a project. - Builder mode modifies the system. It has write access to
system/andlibrary/for editing templates, adding process files, or authoring domain packs.
You can swap modes by telling the agent swap to Builder or swap to Operator. The agent will handle the file copy and log the transition to the local audit database automatically.
This system evolves as I run more projects. To pull the latest system updates without losing your local changes, swap to Builder and tell the agent to "pull upstream updates". The sync skill fetches this repository, walks you through changes commit-by-commit, prompts you for how to resolve local customization conflicts, and applies the updates safely. All personal layers—including project workspaces, local logs, and audit databases—are gitignored and remain untouched.
I built the original AgentFrame system to run marketing campaigns because I realized that working on copy and strategy in raw chat windows meant losing context and having files drift over a long campaign. Keeping everything structured and anchored as files in a local workspace makes it much easier to coordinate work over long horizons.
Over time, I wanted to use this workspace and its skills for other tasks: making slide decks, writing emails, and archiving or tracking project details—all related to project management. At first, I jerry-rigged these skills and processes into the open-flow style to make it work. It worked fine for short-term tasks, but it wasn't scalable for long-term projects.
To solve this, I rebuilt AgentFrame to support structured projects and long-horizon work. The new architecture introduces context components—like global profiles for people and channels—along with a dedicated memory and consolidation system.
This design aligns with where the industry is moving, where specialized domain packs (like Claude for Financial Services or Claude for Small Business) are added on top of a core platform. AgentFrame applies that same modular pattern to local workspaces, but adds a robust context and memory layer to keep the workspace lightweight and cost-effective as it evolves over time.
The original marketing-only project is frozen at agentframe-marketing. This repository is its multi-domain successor.
Everything in AgentFrame is built around domain separation.
The core runner (system/af.py) and the routing files (AGENTS.md) carry no domain-specific code. If you search the python scripts for marketing terms or publishing platforms, you will find nothing; the engine is completely blind to what the project is actually about. All domain logic is declared in library/domains/{domain}/.
These are not code-heavy plugins. A domain pack is primarily a collection of deliverable templates—markdown shapes and rules for the files the project produces—along with a small metadata descriptor. All generic skills like research, voice harvesting, and document generation live outside the pack, allowing any domain to use them.
A pack defines its scope through a few key files:
- Deliverable templates (
deliverables/): The templates for the artifacts this domain generates. - A pack descriptor (
pack.md): Declares custom frontmatter fields, valid CLI verbs, and folder structures. The python runner parses this directly using standard library helpers. - A scaffold skeleton (
skeleton.md): Defines the initial structure ofproject.mdwhen the project is created. - An optional rules module (
rules.py): Python validation rules loaded dynamically byaf doctor(for example, verifying character limits or document groupings). - An optional routing fragment (
production.md): Domain-specific step instructions that the Operator mode loads on demand during execution.
Adding support for a new workflow only requires adding a folder under library/domains/; the Accept-Test for the design is that a new domain requires zero modifications to the core engine.
Here is what an end-to-end run looks like in each of the two domains that ship today—one operator, six steps, no handoffs.
The PM pack takes a charter, derives living project context files, and tracks deliverables ad-hoc.
 01 · Operator kickoff — Tell your agent start a new project-management project. The Operator scaffolds the workspace from the PM pack's skeleton, setting up folders for your inputs and outputs, and imports your project charter into the project's sources/ directory.
|
 02 · Derive project context files — From the charter, the agent parses the requirements and derives four living project context files under knowledge/: a RAID log (Risks, Assumptions, Issues, Dependencies), a stakeholder map, a decision log, and a workback schedule.
|
 03 · Maintain context & consolidate — These are not static files. The RAID log moves on a weekly cadence, decisions append as they are made, and the schedule re-plans against deadlines. For long-horizon projects, you can trigger a consolidation pass (the "dream" workflow) to archive resolved items and prune active files, keeping them lean while retaining a complete history of facts and decisions. |
 04 · Ad-hoc deliverables in your voice — Findings, recommendations, decks, and memos are generated from the generic deliverable shape. Drafts inherit your voice parameters from library/context/operator/voice/, and every revision is saved as a versioned snapshot (-v{N}.md) so you can track what changed and rollback if needed.
|
 05 · Deliver — Deliverables are checked against lock criteria, versioned, and delivered. The PM pack rejects publishing verbs, ensuring files remain local to your workspace. |
 06 · Retro — The project closes with a harvest pass. The agent reviews all your manual edits and template overrides, then proposes updates to your core library templates and voice example pairs so the system gets smarter with every run. |
The marketing pack coordinates research, copy creation, image generation, and direct publishing.
 01 · Operator kickoff — Tell your agent start a new marketing campaign. Operator reads your profile, scaffolds the campaign from the marketing pack's skeleton, and calls Composio for workplace context — recent emails, meeting notes, doc activity — so the work starts from what you care about this week, not a cold prompt.
|
 02 · Gemini Deep Research — Deep Research runs against your direction and lands a structured brief and competitor analysis artifact at phase-1-research/research-artifact-v{N}.md.
|
 03 · Copy in your voice — Drafts inherit your voice system from library/context/operator/voice/, then run through the humanizer before lock. Every revision snapshots as its own -v{N}.md, so you can roll back, compare, or read why the copy changed.
|
 04 · Media, your pick — HTML render in your agent for slide-shaped visuals, Gemini Nano Banana for raster variants, Open Design for higher-fidelity decks and carousels, or HyperFrames for HTML-to-video. For Open Design, AgentFrame stages the project for you — design language, mode, and first prompt already loaded. |
 05 · Publish via Composio — Composio's connector to LinkedIn (or X, Instagram, TikTok) sends or schedules the post; af publish records the delivered state and live URL back into the post folder.
|
 06 · Retro — The agent proposes patches to your voice, templates, processes, and skills based on what actually happened. You approve or reject each one; the library evolves. |
A project harness is more than just a folder of files; it requires a way to maintain state, validate structure, and enforce boundaries. AgentFrame is a lightweight, pragmatically built harness. It does not solve every agent coordination problem, but it addresses a very real issue: LLMs are great at drafting but notoriously bad at state tracking and bookkeeping. In my experience, even the best frontier models fail at exact procedure following a significant percentage of the time—mine skipped its versioning and lock steps three times in a single evening (likely because it got distracted).
Because of this, AgentFrame does not ask the model to remember state transitions. Instead, the workflow is guided by a deterministic Python CLI (system/af.py). Commands like new-project, version, lock, and doctor run the exact file modifications, frontmatter updates, and audit logs atomically. They print back the check-lists and guidelines that the agent actually needs to follow. The agent owns the creative judgment; the CLI owns the bookkeeping. Since the CLI is written in standard library Python, it runs identically across Claude Code, Cursor, VS Code, or Antigravity.
Most brand-voice setups rely on a long list of negative rules ("don't use the word leverage") that the agent forgets by the second revision anyway. AgentFrame compiles your actual writing into annotated example pairs—showing a generic version, your rewritten version, and the specific move that separates them.
When the agent drafts, it loads these pairs directly into its context to act as stylistic anchors. Instead of checking off a list of banned words, the agent drafts the substance first, then runs a dedicated style pass applying the exact cadences and markers found in the pairs. This keeps the writing authentic to how you actually talk, without relying on crude system prompts.
Long-horizon projects quickly bloat the agent's active context window with historical chat logs and outdated files. AgentFrame prevents this by separating raw, immutable inputs (transcripts, briefings, and raw docs in sources/) from agent-distilled living files (logs and plans in knowledge/).
As the project moves forward, you can trigger a consolidation pass (the "dream" workflow) that archives resolved risks, closed decisions, and completed milestones into compressed monthly archives. This strips the bloat from the active workspace files, keeping the agent's context window slim, fast, and cost-effective.
Every project closes with an automated harvest pass. Two system skills analyze the project's version history and your manual edits. One skill extracts new voice example pairs from how you polished the agent's drafts, while the other identifies template and process gaps based on how the workflow actually ran. The agent proposes these updates as git-patch suggestions; you review and approve them, allowing the system to naturally evolve with every project you run.
The system is composed of a few simple layers: 2 domain packs, 5 shared deliverables, 16 process files, 16 skill bundles, 3 flows, a two-mode persona configuration, a deterministic CLI, a local preview server, and a two-layer audit trail.
Everything in library/ and system/skills/ is plain text or standard Python, meant to be modified. You set your voice and positioning once under library/context/operator/ (seeded from operator.example/ on first startup) and they are reused automatically across all projects.
| Pack | What it ships |
|---|---|
library/domains/marketing/ |
Campaigns that ship posts. Deliverables: research, business brief, campaign brief, campaign architecture, slide-copy, body-copy, post-final. The publish verb and the post-FINAL assembly live here. |
library/domains/project-mgmt/ |
Consulting / PM projects. A charter goes in, then four living governance docs are derived from it: RAID log, stakeholder map, decision log, workback schedule. No posts, no publish. |
library/domains/TBD/ |
The harness is domain-neutral. More domain packs can be added at any time to support any kind of workflow. |
open-flow is the default across every domain. Add or edit any flow under library/process/flows/.
| Flow | Purpose |
|---|---|
open-flow (default) |
Build-as-you-go. The agent proposes a plan scaled to the objective; you narrow it and set the tempo. The default for every domain. |
marketing-solo-flow |
Marketing, opt-in: a lean fixed phase ladder with one accountable owner. |
marketing-standard-flow |
Marketing, opt-in: a fuller campaign with stakeholder review gates. |
Cross-domain templates under library/deliverables/.
| Template | Output |
|---|---|
design-language |
Visual and style direction |
image-prompts |
Per-asset generation prompts — treatment block + per-asset deltas |
video-spec |
Video concept, scenes, and production plan |
closeout-retro |
Project-level learnings and improvements |
system-retro |
System-level process and architecture improvements |
_meta |
The generic deliverable shape every template inherits |
Process files load on demand — only when the workflow they describe is in play.
| Process | Purpose |
|---|---|
flow-authoring |
Designing or evolving flows |
process-authoring |
Designing or evolving process files |
research-and-signals |
Shared kickoff research: workspace context, live MCP scan, research-method offer |
deliverable-versioning |
Surgical-vs-replacement judgment for *-v{N}.md; bumps run through af version |
lock-event |
Lock trigger and judgment gates; mechanics run through the af CLI |
project-frontmatter |
Frontmatter schema and state handling |
knowledge-base |
Project knowledge substrate schema, storage principles, and ingest workflow |
voice-setup |
Build your voice system from your own writing |
voice-mini-retro |
Lock-time gate that routes your edit-diffs to the voice-harvest skill |
humanizer-integration |
The humanization pass |
image-production |
Image-generation workflow |
video-production |
Video workflow from spec to renders |
deck-production |
Deck path selection (PPTX skill, PPT Master, Open Design) |
preview-server |
When and how to use the local preview hub |
composio-notes |
Connector usage notes and caveats |
browser-fallback |
Browser-automation fallback strategy |
substack-distribution-notes |
Substack publishing conventions |
My current production stack — swap any one for a sharper tool without touching templates or processes.
| Skill | Source |
|---|---|
agentframe-structure |
Project skill — navigates and understands the overall project architecture and state |
deliverable-scaffolding |
Project skill — scaffolds new deliverables from templates with correct frontmatter |
system-improvement |
Project skill — applies patches and improvements to the system itself |
upstream-sync |
Project skill — pulls upstream updates into your copy, commit by commit with approval |
voice-harvest |
Project skill — mines finished work and edit-diffs into voice example pairs |
deliverable-harvest |
Project skill — mines template and process patches from finished projects |
project-consolidate |
Project skill — consolidates and prunes project knowledge and history (dream workflow) |
docx |
Project skill — generates Word documents from markdown deliverables |
pptx |
Project skill — generates PowerPoint presentations from markdown deliverables |
humanizer |
Vendored from blader/humanizer |
hyperframes |
Vendored from heygen-com/hyperframes |
hyperframes-cli |
Vendored from heygen-com/hyperframes |
gsap |
Vendored animation skill for HyperFrames workflows |
ppt-master |
Vendored from hugohe3/ppt-master — native-editable deck generation via SVG→PPTX |
extract-design |
Thin skill over Manavarya09/design-extract; CLI runs via npx designlang |
open-design |
Vendored local-first runtime from nexu-io/open-design for image/deck production |
browser-harness |
Vendored CDP-driven browser workflows via Edge |
- Two-mode routing via
AGENTS.operator.mdandAGENTS.builder.md. - The deterministic CLI at
system/af.py—new-project,lock,version,doctor, plus the domain-dispatchedpublish. The buttons do the bookkeeping atomically and write the paper trail; the agent keeps the judgment. - Project state and outputs as markdown under
workspace/projects/. - A two-layer audit trail:
activity.mdper project plus an append-only SQLite DB atsystem/audit/agentframe.db. - A local preview server at
system/server/for HTML, image, video, PDF, PPTX, and DOCX. - A browser harness at
system/browser/for CDP-driven sessions, with documented fallbacks when a workflow needs a hand.
All project state lives directly in markdown files—including frontmatter, deliverables, and activity.md log files. The active state is never locked in a transient chat session. If you change LLM providers, switch machines, or return to a project after months away, the agent can read the directory and resume the work immediately.
AGENTS.md is the only file loaded into the agent's context by default. All domain packs, flows, processes, and skills are lazy-loaded only when the current step requires them. Keeping the active context small prevents LLM drift, keeps response times fast, and lowers token costs.
Your templates, processes, domain packs, and voice rules are the long-term assets of this workspace—the parts that accumulate value as you run more projects. The actual skills and API connectors are kept decoupled. You can swap an image generator, doc converter, or browser library for a newer tool without altering your underlying workflow.
AgentFrame integrates with external services to support research, media generation, and publishing. All integrations are optional, and the system runs locally without them.
- Generates detailed research briefs, competitor analysis, and signal maps at project kickoff.
- Outputs are saved directly to
phase-1-research/as structured markdown. - Uses
GEMINI_API_KEY(which can be obtained through a standard Google AI Studio developer account).
- Used to generate quick layout variants or high-fidelity images with inline text.
- Integrated through the local preview hub and runs using your shared
GEMINI_API_KEY.
- Acts as a unified MCP gateway to connect your agent to tools like Google Workspace, Slack, LinkedIn, or YouTube.
- Collects live context signals for project kickoff research and publishes final content directly to social channels.
- A bundled local-first design runtime at
system/skills/open-design/source/used to compile SVGs, slides, and carousels. - Requires Node 24 and local dependencies (
corepack pnpm install).
GEMINI_API_KEY=
COMPOSIO_API_KEY=
COMPOSIO_MCP_URL=https://connect.composio.dev/mcpYour coding agent provides the LLM. These keys power the non-LLM tools — research, image generation, and publishing.
┌─── owns ──▶ workspace/projects
┌──── Operator ─────┤
│ └─── reads ─▶ system + library
Operator ──────┤
│ ┌─── owns ──▶ system + library
└─── Builder ──┤
└─── reads ──▶ workspace/projects
── swap AGENTS.md to flip between modes ──
CLAUDE.md ── imports ──▶ AGENTS.md (the active persona; domain-agnostic)
│
▼
project.md → { domain, flow, deliverables[] }
│
┌───────────────────┼────────────────────────────┐
▼ ▼ ▼
library/domains/{domain}/ library/process/flows/{flow}.md library/process/* (shared)
(the pack) (domain-agnostic; open-flow) (lock, versioning, frontmatter)
│
▼
draft X → pack's template ▸ shared template ▸ generic _meta shape
af.py reads project.md → domain → loads the pack and dispatches. The persona, the flows, and the shared processes name no domain; {domain} is the single point where the work is parameterized.
agentframe/
├── CLAUDE.md # thin shim → imports AGENTS.md (pins the persona)
├── AGENTS.md # active persona (Operator | Builder)
├── AGENTS.operator.md
├── AGENTS.builder.md
├── README.md
├── .env.example
├── library/
│ ├── domains/
│ │ ├── marketing/ # pack.md, skeleton.md, rules.py, production.md, deliverables/
│ │ └── project-mgmt/ # pack.md, skeleton.md, deliverables/
│ ├── deliverables/ # shared cross-domain deliverables + _meta shape
│ ├── process/
│ │ └── flows/
│ └── context/
│ ├── _meta/ # channel and person profile schemas
│ └── operator.example/ # default operator voice and positioning context
├── system/
│ ├── af.py # the generic plugin-host spine
│ ├── skills/
│ ├── server/
│ ├── audit/
│ └── builder-backlog.md
└── workspace/
└── projects/
└── example-ai-automation-pov/
Show preview server details
- Local preview hub at
system/server/. - Previews HTML, images, video, PDF, PPTX, and DOCX.
- Folder-tree navigation with hide rules to keep noise down.
- Run with
py -3 system/server/run.py.
Show auditability details
- Project layer:
activity.mdin each project for the human-readable timeline — state transitions throughsystem/af.pywrite it automatically. - System layer: append-only SQLite audit DB at
system/audit/agentframe.db(writer:system/audit/writer.py). - Books check:
python system/af.py doctor [project]verifies schema, head pointers, and per-domain rules; it surfaces drift and never auto-fixes.
Small, demand-driven additions. Nothing here is a rewrite.
- Embedded / RAG indexing over the markdown corpus, so retrieval scales as the library grows past what fits in context.
- Scheduled runs — cron-triggered jobs for recurring work, like a weekly research pull or a digest.
- Agent-to-agent communication over an API, so projects and agents can hand work to each other.
- Per-project knowledge substrate (
sources/immutable + agent-ownedknowledge/) with a user-triggered consolidation pass. - Cross-project context entities (channels, people) referenced by slug.
- More domain packs as the work demands them.
- Preview server v2: better search, nested live reload, stronger video UX.
- PRs for templates, processes, packs, and skills are welcome.
- Open an issue first for major architecture changes.
- agentframe-marketing — the frozen marketing-only predecessor this grew out of
- Composio
- heygen-com/hyperframes
- nexu-io/open-design (Apache-2.0, vendored under
system/skills/open-design/source/) - hugohe3/ppt-master (MIT, vendored under
system/skills/ppt-master/) - Manavarya09/design-extract (MIT, thin skill; CLI runs via
npx designlang) - GreenSock GSAP
- Google AI Studio / Gemini
- blader/humanizer
MIT. See LICENSE.
Built by Brandon Situ over many weekends — and likely many more.
- LinkedIn: linkedin.com/in/brandonsitu
- Email: brandonzsitu@gmail.com