Skip to content

cianfhoghlaim/cianchosaint / .agents/skills/agno

references/agno-architecture-guide.md

View on GitHub
Multi-Agent System Architecture with Agno &

BAML – Modular Teams Blueprint

Overview of the Architecture

This design introduces a  multi-agent AI system  organized into distinct domain-focused teams, each

orchestrated by  Dagster  pipelines with  DLT  for data ingestion. The architecture leverages  Agno  – an

open-source   framework   for   orchestrating   LLM   agents   –   in   combination   with  BAML   (Boundary   AI

Markup Language) to enforce structured prompt-response formats

1

2

. The data processing stack

unifies batch and streaming workflows by using DuckLake (DuckDB lakehouse) for batch storage and

optionally  RisingWave  for   streaming,   with  Ibis  providing   a   common   interface.   Processed   data

(embeddings,   facts,   metrics)   are   fed   into  CocoIndex  for   vector   indexing   and  Cognee  for   graph/

relational knowledge storage, built on PostgreSQL, LanceDB, and Memgraph

3

4

.

Figure   1  below   illustrates   the   high-level   architecture.   Dagster   orchestrates   three   example   pipelines

(Code Analysis, Sentiment Analysis, Financial Analytics). Each pipeline ingests data (via DLT or Crawl4AI),

indexes   it   (via   CocoIndex),   and   invokes   specialized   Agno   agents   that   produce   structured   outputs

defined by BAML. All results and enriched data flow into a unified knowledge base (Cognee). This allows

the teams to operate independently while contributing to a common semantic index and knowledge

graph.

Figure 1: Multi-agent architecture with domain-specific agent teams. Dagster orchestrates pipelines for each

team (code analysis, sentiment analysis, financial analytics). Each pipeline ingests data (via DLT or Crawl4AI),

updates the DuckLake data lake (with DuckDB + Postgres), triggers CocoIndex for vector indexing, and runs

Agno   LLM   agents   with   BAML   prompts   to   produce   structured   insights.   All   context   and   outputs   feed   into

Cognee’s unified knowledge base (PostgreSQL + Memgraph + LanceDB), enabling cross-domain query and

analysis.

Team 1: Code & Documentation Analysis

Responsibilities: This team focuses on analyzing software repositories – summarizing code structure,

evaluating   documentation,   and   extracting   key   findings.   It   produces   a   structured   report   of   the

repository’s purpose, architecture, code quality, and documentation status

5

6

.

Pipeline   Configuration:  The   code   analysis   pipeline   is   orchestrated   by   Dagster   and   consists   of   the

following stages:

•

Data Ingestion (DLT):  Using  DLT (Data Load Tool), the pipeline ingests repository files (source

code, READMEs, etc.) from a filesystem or git source into a DuckDB/DuckLake instance

7

8

.

DLT’s   filesystem   connector   automatically   scans   directories   and   loads   files,   treating   each   file’s

content as a record

9

10

. This stage runs on triggers (e.g. new repo added or code update) or

on a schedule.

•

Storage   &   Incremental   Updates:  The   repository   data   is   stored   in  DuckLake,   a   lakehouse

format for DuckDB that uses PostgreSQL for metadata and cloud/object storage (e.g. Cloudflare

1

R2) for file data

11

. Every commit of new files or changes results in new Parquet files and an

updated Postgres catalog entry, enabling versioning and multi-user access in DuckDB

12

. The

Postgres   catalog   acts   as   a  trigger   source  for   indexing:   when   repository   data   changes,   a

Postgres trigger (LISTEN/NOTIFY) signals CocoIndex to update the index

13

14

.

•

Indexing  (CocoIndex): CocoIndex  incrementally  indexes  the  repository  content  for  semantic

search. It ingests new or changed file records and generates vector embeddings (for code and

text) and summary metadata. Thanks to CocoIndex’s live update feature, only new/modified files

are   processed,   avoiding   re-embedding   unchanged   files

15

16

.   The   pipeline   uses   a   Postgres

“index tracking” table that CocoIndex listens to; as soon as new files are loaded and an entry is

upserted, CocoIndex receives a NOTIFY event and updates the vector index immediately

17

13

.

This   design   yields   low-latency   indexing   –   an   update   to   the   DuckLake   data   triggers   only   the

necessary embedding updates

18

. Dagster ensures this sequence (ingest -> update index table -

> CocoIndex) happens reliably in order

19

20

.

•

Agno Agents (LLM Analysis):  Once the repository’s content is indexed, an  Agno  agent (or a

small team of agents) performs the analysis. The system message for these agents defines their

role as a “software repository analyst” tasked with summarizing code and documentation

21

22

.

The agent is provided with context from the repository: either the raw text (for smaller repos) or
retrieved   snippets   via   CocoIndex’s   vector   search   (for   large   codebases   that   exceed   context

window)

23

24

. Example: The agent might first get an overview of the project structure (from a

packaged   context   like   a   Repomix   summary)   and   then   use   CocoIndex   to   lookup   specific   file

details on demand

24

. Agno supports such tool use, allowing the agent to call a search function

on the indexed data to dynamically fetch details

24

.

•

Structured Prompt & Output (BAML):  The agent’s prompt and response schema are defined

using BAML to ensure a consistent, parseable report format. In BAML, the task can be defined as

a function: input = repository content, output = structured report. For instance, we specify that the
agent’s   output   should   be   a   JSON   with   fields   like   "summary" ,   "key_findings" ,   and
"conclusion"

. This turns prompt engineering into  schema engineering, making the LLM

25

output deterministic in structure

2

. The agent’s instructions can be multi-step (e.g. “summarize

the code architecture, then list key findings, then give an overall conclusion”), guiding it to populate
each section. Using Agno’s Python API, one might configure an  Agent  with an output schema

and  stepwise  instructions  (checklist  style)  for  these  fields

25

26

.  The  output  is  a  structured

JSON object – for example:

{

"summary":

"This project is an IoT sensor logging system written in C++ and Python...",

"key_findings": [

"The Arduino code handles sensor data gathering using an external XYZ

library.",

"The Python backend has comprehensive unit tests, but logging is

rudimentary.",

"The repository lacks a CI/CD configuration."

],

"conclusion": "Overall, the project is functional and reasonably

documented..."

}

2

– The above format is an example of a BAML-defined schema for repository analysis

27

28

.

•

Multi-Agent Collaboration: Agno allows chaining multiple agents or calls in a deterministic flow

26

.   For   repository   analysis,   one   could   employ   separate   specialized   agents   –   e.g.   one   agent

focuses on code and another on documentation – then use a coordinator agent to merge their

findings

26

.   For   simplicity,   a   single   agent   can   also   handle   both   tasks   in   one   prompt,   as

illustrated above, since BAML ensures it returns all required sections

26

29

. In either approach,

the output is a structured report artifact.

•

Output Integration:  The final JSON report is saved (e.g. in a database or object storage) and

also injected into  Cognee. In Cognee’s graph, the repository could be represented as an entity

node with properties (e.g. languages, repo name) and relations (e.g.  Repo  –has→  Module). The
key findings might be added as linked notes or as vector embeddings (via LanceDB) for future

semantic search. The Cognee knowledge base thus retains the analysis so that other agents (or

users)   can   query   insights   about   this   repo   later.   The   vector   embeddings   produced   for   code

snippets   and   docs   are   stored   via   CocoIndex   (using   LanceDB   under   the   hood   for   similarity

search), and the structured facts (like presence of tests, absence of CI config) can be added as
relationships in the Memgraph graph (for example, Repo – lacks → CI_Config).

Triggers & Schedule: This pipeline can be triggered by version control events (e.g. a new commit or

pull request initiates a fresh analysis), or on a schedule (e.g. nightly scans of designated repositories).

Dagster’s scheduler or sensors can watch for new repository data and launch the pipeline

of DLT’s stateful extraction means only new or changed files are processed on each run

30

31

. The use

32

, and

CocoIndex’s incremental indexer likewise only processes new data, keeping the process efficient

15

33

.

Team 2: Sentiment Analysis & Social Feed Monitoring

Responsibilities:  The sentiment analysis team gathers and interprets unstructured data from news,

forums,  and  social  media  to  gauge  public  sentiment  and  trends.  The  goal  is  to  produce  structured

insights   such   as   sentiment   scores,   key   trending   topics,   and   alerts   on   sentiment   shifts.   This   team’s

output can help explain or contextualize events (for example, correlating social sentiment with market

movements

34

35

).

Pipeline Configuration: The sentiment pipeline handles continuous ingestion of text-rich content and

uses LLM agents to analyze sentiment. Key components:

•

Data Ingestion (Crawl4AI & APIs): For open web sources (blogs, news sites, forums like Hacker

News or Reddit), the pipeline uses  Crawl4AI, an AI-friendly web crawler

36

. Crawl4AI fetches

webpages and outputs clean, markdown-formatted text with minimal noise (e.g. it preserves

main content and reference links, making it LLM-ready)

36

37

. It can even employ LLM-based

strategies during crawl (e.g. asking it to extract specific info from pages)

38

. The crawler can run

on a schedule or be triggered by webhooks (for example, whenever new forum posts or news

articles   appear).   For   social   media   platforms   (like   Twitter/X   or   Discord),   where   content   may

require authentication or API access, the pipeline can use platform-specific APIs or a browser

automation   step.  Feasibility   of   Browser   Agents: Logging   into   Discord   or   similar   sites   via   a

headless browser is possible but not natively handled by Crawl4AI. In practice, one could incorporate

a browser automation agent (using a tool like Playwright or Puppeteer) as part of the pipeline.

Agno agents support tool use, so an agent could be endowed with a “browser” tool to navigate a

site,   login,   and   scrape   protected   content.   However,   this   requires   careful   setup   (managing

3

credentials   or   tokens)   and   might   be   limited   by   site   policies.   For  public   forums   like   Hacker

News, Crawl4AI is sufficient since the content is public HTML – it will scrape threads and output

text that the LLM can parse. For  Discord, a recommended approach is to use Discord’s official

API or webhooks to pull messages from channels (with appropriate authentication) and then

feed that text into the pipeline. In summary, Crawl4AI excels at crawling open websites; to integrate

data behind logins, the pipeline should leverage APIs or a headless browser agent.  (Crawl4AI does

provide   a   Python   API/CLI   for   integration

39

,   but   interactive   login   flows   would   need   custom

steps.)

•

Storage & Streaming: The ingested social/news data can be stored as documents in DuckLake

(e.g. as a table of posts or articles) for persistence. Additionally, if real-time processing is needed

(e.g. analyzing sentiment of live tweets or Discord messages), a streaming pipeline can be set up:

for  instance,  ingest  tweets  via  a  streaming  connector  (Kafka  or  API)  into  RisingWave,  which

maintains a live materialized view of recent sentiment metrics (like a rolling average sentiment).

Ibis  can  unify  this  with  the  batch   historical   data   –   the   same   transformation   (e.g.   computing

sentiment score per hour) can run on DuckDB for history and on RisingWave for live data

40

41

.   For   our   architecture,   suppose   we   treat   social   feed   ingestion   as   a   continuous   stream:

RisingWave could subscribe to a feed (via a connector or a custom source) and compute simple

aggregations (like count of positive/negative posts in the last 5 minutes). This can act as a trigger

for the LLM agent – e.g. if an unusual spike in negative sentiment is observed, trigger an analysis

agent to investigate the content.

•

Indexing (CocoIndex & Embeddings): CocoIndex indexes incoming text data (posts, comments,

articles) incrementally. New items (or even just new daily batches) are embedded into vector

representations (using language model embeddings) so that they can be semantically searched.

The index could include metadata like timestamp, source, and any preliminary sentiment score

from a classifier. As with Team1, CocoIndex live updates can be driven by Postgres triggers or

periodic refresh. The result is a continuously-growing vector store of textual content. This allows

the agents to pull  relevant context  efficiently – for example, fetching all posts about a certain

topic or with certain keywords when analyzing sentiment for that topic.

•

Agno   Agents   (Sentiment   Analysis):  The   team’s   Agno   agent(s)   take   the   raw   text   data   and

produce  a  structured  sentiment  analysis.  A  possible  setup  is  two  agents  in  sequence:  first  a

Topic   Extractor  and   then   a  Sentiment   Summarizer.   The  Topic   Extractor  agent   could   scan   a

batch of recent posts and identify major emerging topics or themes (using an LLM to cluster or

summarize discussions). The Sentiment Summarizer agent then takes those topics along with the

underlying posts as context, and produces a summary of sentiment for each (e.g. Topic A: mostly

positive   reception,   key   quotes...;   Topic   B:   community   is   negative   due   to...).   Alternatively,   a   single
agent can do both – e.g., “Analyze the following social posts and produce a JSON with  topics
and for each topic, the   sentiment   (Positive/Negative/Neutral) and a   summary   of opinions.”

This prompt would be defined in BAML with an output schema specifying a list of topics with

sentiment scores.  System Message & Prompt:  The agent is instructed as a  “sentiment analysis

expert AI that reads social and news content and evaluates the tone and opinions”. The input context

is   a   collection   of   recent   posts/articles   (fetched   via   CocoIndex’s   semantic   search   or   provided

directly from the ingestion stage). Because of BAML, we enforce that the output contain specific

fields   –   for   example:
top_positive_examples ,  top_negative_examples , and  notable_topics .

  overall_sentiment_score

(numerical

  or   categorical),

•

BAML-Structured Output: Using BAML, we define the expected Sentiment Report format. For

instance, the agent could output:

4

{

"overall_sentiment": "Slightly Negative",

"positive_trends": ["Many users excited about feature X", "..."],

"negative_trends": ["Complaints about service Y outage", "..."],

"notable_topics": [

{"topic": "New Feature X Launch", "sentiment": "Positive",

"summary": "Users celebrate the launch..."},

{"topic": "Service Y Outage", "sentiment": "Negative", "summary":

"Widespread frustration about..."}

]

}

This structured result provides a quick view of public sentiment, with supporting details. The
consistency of keys ( overall_sentiment ,  notable_topics , etc.) is guaranteed by the

BAML schema, making it easy to store and query later

2

42

.

•

Adaptive Analysis: The agent can be configured to use tools for deeper analysis. For example, if

quantifiable sentiment is needed, the agent might call a sentiment classifier function on each

post (though often the LLM can infer without an external classifier). Another use of tools: if an

agent wants to verify factual claims in the social data, it could perform a web search or query an

API as part of its reasoning (Agno supports such tool integrations, similar to how one might

equip an agent with a search or calculator tool). This is more relevant if the sentiment analysis

goes into why something is trending (e.g. verifying a news rumor).

•

Output   Integration:  The   resulting   sentiment   insights   are   stored   in  Cognee.   In   the   Cognee

knowledge   graph,   we   might   model   an   entity   for   each  Topic  or  Asset  being   discussed   (for

example, if this system is used in finance context, topics might be crypto tokens or stocks). The

sentiment could be stored as an attribute or related node (e.g.  TopicX  –has→  SentimentScore:
-0.2). The vector index (LanceDB) will store the embeddings of individual posts, which allows

future queries like “find posts similar to this issue” or “retrieve latest positive remarks about X”.

By integrating into the knowledge base, sentiment data can be correlated with other domain

data.   For   instance,   the  financial   team’s   agents  could   query   Cognee   to   retrieve   the   current

sentiment on a particular asset when generating an analysis (cross-team synergy).

Triggers & Streaming: This pipeline can run on a frequent schedule (e.g. every hour) to batch-process

new content, and also leverage streaming for real-time alerts.  Unified DuckLake vs RisingWave:  For

moderate volumes, scheduling DLT + CocoIndex in short intervals can approximate real-time processing

(with Postgres triggers ensuring index updates immediately)

17

. However, if truly low-latency handling

of   high-volume   streams   is   required,   integrating  RisingWave  is   advisable.   RisingWave   can   consume

streams (Twitter firehose, etc.) and maintain rolling metrics with sub-second latency

43

. Ibis enables

the same transformation (e.g. sentiment scoring logic) to run on both historical batch data (DuckDB)

and live streams (RisingWave) without duplicate code

40

41

. In practice, we might use RisingWave to

detect trigger conditions (like sentiment index crossing a threshold) and then use Dagster to kick off the

Agno agent analysis on-demand. Dagster’s sensors could listen to a message or event (via a lightweight

API or poll) indicating “alert: sentiment spike detected”, thereby invoking the sentiment analysis agent

immediately rather than waiting for a schedule.

5

Team 3: Financial Analytics & Anomaly Detection

Responsibilities: The financial analytics team ingests a wide range of structured and unstructured data

in the crypto/finance domain – market prices, on-chain transactions, DeFi protocol metrics, economic
news, etc. – and employs agents to identify trends, correlations, and anomalies. The focus is on  real-

time analytics  (e.g. detecting an on-chain anomaly as it happens) combined with  historical context

(trend analysis over time). This team’s outputs include structured reports on market trends, alerts for

unusual events, and answers to analytical queries, all grounded in data.

Pipeline   Configuration:  The   financial   pipeline   is   the   most   data-intensive,   combining   batch   ETL,

streaming processing, and AI analysis:

•

Data Ingestion (DLT for Batch & Connectors for Stream): Multiple data sources feed into this

pipeline

44

. For batch data, DLT is used to pull periodic snapshots: e.g. daily closing prices from

an exchange API, hourly DeFi protocol stats (TVL, yields) from an API or database, or periodic

snapshots of blockchain state (like a daily summary of new addresses). Each source is set up as a

DLT pipeline (with stateful tracking) writing into DuckDB. For example, one pipeline fetches new
Ethereum blocks and appends them to a  ethereum_blocks  table in DuckDB

, another pulls

45

yesterday’s   trading   volume   for   a   set   of   tokens,   etc.   DLT’s   incremental   loading   (with
write_disposition="merge"  and primary keys) ensures we don’t duplicate data on re-runs

46

47

. For streaming data, we integrate RisingWave to capture live events: e.g. subscribe to

blockchain transaction streams or mempool events, listen to a Kafka topic of real-time trades, or

ingest   database   change   logs   via   CDC

48

49

.   RisingWave’s   connectors   allow   direct   ingestion

from Postgres (for on-chain updates via logical decoding) or Kafka (exchange feeds) in real-time

50

51

. These streams populate RisingWave internal tables continuously. Using Ibis, we can

define   transformations   (windowed   aggregations,   joins)   on   these   streams   to   maintain   live

materialized views  – for example, a view of “total DEX trading volume in last 5 minutes” or

“count   of   large   transfers   (>$1M)   in   last   hour”   that   updates   continuously.  Ibis   Unified   Logic:

Crucially, the same Ibis-defined transformation can also be run on the historical data in DuckDB

for backfills or validation

40

. This unification avoids divergent definitions for metrics in batch vs

streaming.   A   semantic   layer   (defining   metrics   in   YAML,   as   per   the  “boring   semantic   layer”

approach) can further ensure consistency – define metrics once and execute them on either

engine   via   Ibis

52

53

.   In   short,   DuckLake   (DuckDB)   holds   the   long-term   dataset,   while

RisingWave provides the real-time incremental updates, and Ibis bridges them.

•

Storage   (DuckLake   &   Cognee):  All   batch   data   lands   in  DuckLake  tables   (Parquet-backed,

cataloged   in   Postgres),   ensuring   an   ACID   compliant   “data   lakehouse”   for   analytics

54

.   This

serves as the single source of truth for historical data (e.g. price history, historical metrics). The

streaming   results   from   RisingWave   can   be   periodically   persisted   to   DuckLake   as   well   (for

example, end-of-day, flush aggregated results to Parquet)

55

56

, so that no information is lost.

The   Cognee   knowledge   base   ingests   the   enriched   data:   it   builds   a  graph   of   entities   and

relationships  such   as:

 Token– hasPrice →PriceMetric,

 Protocol– hasTVL →Metric,

 Token–

mentionedIn →NewsArticle, etc.

3

57

. Because Cognee combines a graph DB with a vector

index,   it   can   store   numeric   facts   and   also   link   to   relevant   text   (news   or   social   posts)   via

embeddings

3

. For instance, a news article about a hack can be embedded and linked to the

affected protocol’s node in the graph. Memgraph (within Cognee) handles the graph queries –

e.g. find all protocols that have a relation to a certain exchange – and  PostgreSQL  can store

structured tables if needed (though often the data remains in DuckDB; PG might store lighter

metadata or serve as an index table for CocoIndex as discussed). LanceDB (vector store) either

underpins CocoIndex or is integrated in Cognee to handle semantic similarity searches (e.g. find

6

similar events or similar news). The net result is a rich, interconnected store of financial data,

events, and context – a “brain” that agents can query

58

57

.

•

Computed Features & Indexing (CocoIndex):  CocoIndex can be used here not only for text

embedding but also as an ETL layer for feature computation. For example, a CocoIndex flow
could watch the  ethereum_blocks  table for new blocks and compute a summary (number of

transactions, gas used, etc.), or generate embeddings for block metadata (if needed for anomaly

detection by an LLM). It can similarly process new protocol metric entries, attaching tags like

“outlier” if a value deviates strongly from history (potentially via an LLM call or statistical test).

Those results can be stored back (CocoIndex can output to new tables or indexes). Incremental

operation ensures that as each new data point arrives, only lightweight computations are done,

possibly   with   triggers   from   Postgres   (as   in   other   pipelines)   to   react   immediately

59

33

.   All

textual   data   (like   news   headlines,   on-chain   transaction   notes,   GitHub   issue   discussions   if

relevant) are embedded via CocoIndex into the vector index for semantic search. This allows

agents to perform  RAG (Retrieval-Augmented Generation)  by pulling in related context (e.g.

“find news articles mentioning this token in the last week” to explain a price move).

•

Agno   Agents   (Trend   Analysis   &   Anomaly   Detection):  Several   specialized   LLM   agents   are

orchestrated by Agno in this team, potentially working in collaboration

60

:

•

Trend Summarizer Agent: This agent’s role is to analyze recent data and produce a narrative of

market trends. Its system prompt might say: “You are a financial analyst AI tasked with

summarizing the latest trends in the crypto market. Use data provided (prices, volumes, sentiment, on-

chain metrics) to support your summary. Output a structured report.” The input context is pulled

from Cognee: for example, the agent queries Cognee for “latest key metrics for major tokens”

and “any notable events or news in the last 24h” – Cognee can return a bundle of relevant facts

(numbers, and maybe references to events) and vector-retrieved snippets (news headlines, social

sentiment highlights). Armed with this, the LLM produces a structured Market Trends Report.
Using BAML, we define sections such as  "market_overview" ,  "notable_events" ,
"metrics_summary"  and  "outlook"  in the output. The agent then fills these in, citing data

from the context (implicitly or explicitly). The output might look like: market_overview: “BTC and

ETH prices rose ~5%, with altcoins mostly green”; notable_events: list of events (exchange hack,

protocol launch, etc.); metrics_summary: key metrics (trading volumes up 20%, DeFi TVL down 2%,

etc.); outlook: a short forward-looking statement. This structure ensures the result is

comprehensive and machine-consumable (we can store each section in a database or display

nicely in a dashboard).

•

Anomaly Detector Agent: This agent focuses on identifying outliers or unusual patterns.

Triggered either on a schedule or by a real-time event (e.g. if a metric exceeds a threshold), it

examines the latest data for anomalies. The system message might frame it as: “You are an AI risk

analyst that detects anomalies or significant deviations in crypto data and explains them.” The agent

could be fed a digest of changes (e.g. a token’s price jumped by 20% in an hour, or an address
suddenly moved a large sum). The agent then outputs a structured alert, e.g.:  {"entity":
"Token ABC", "anomaly": "Price surged 20% in 1h", "likely_causes": "Rumors

of a partnership (from social media)", "impact": "Liquidations on XYZ

platform, trading volume tripled"} . To do this, the agent again uses Cognee – it might

query for any news or social sentiment related to that token around the time of the anomaly

(leveraging the indexed context) to provide an explanation

34

61

. Because multiple data types

are linked in the knowledge graph, the agent can correlate qualitative signals (tweets, articles)

with quantitative data (price, volume)

62

34

. BAML ensures the output has a fixed schema (so

an alert can be automatically ingested by an alerting system or further pipeline).

7

•

Q&A and Reasoning Agents:  In addition to proactive analysis, the team can include an agent

that answers ad-hoc questions using the Cognee knowledge base. For example, a  Query Agent

might take a user’s question (“Why did Stablecoin X de-peg last night?”) and decompose it: first

retrieve related info (price of X, news of any incident, on-chain data showing large movements),

then formulate an answer. This agent would heavily use the retrieval (vector search in CocoIndex

and graph queries in Cognee) to ground its response. Agno’s framework and Cognee’s API allow

such   an   agent   to   perform   multi-hop   reasoning:   e.g.   find   the   relevant   subgraph   of   entities

. The
(Stablecoin X, Protocol Y, etc.) and data, then call the LLM to synthesize an explanation
output   is   again   structured   (perhaps   a   JSON   with   fields   like   "cause_analysis"   and
"supporting_data_refs"  for traceability).

63

•

Output Integration: All reports and alerts generated are fed back into the Cognee knowledge

base and also can be emitted to external systems (dashboards, email alerts, etc.). In Cognee, a

Trend Report could be stored as a node linked to the date or period it covers, with edges pointing

to the entities it mentions (so you can query “what reports discussed Token ABC?”). An Anomaly

Alert  could similarly be logged in a “Anomaly” relation connected to the entity. Storing these

ensures the system has memory of past analyses – agents could even examine previous reports

to avoid repeating explanations or to see if an anomaly is recurring. Meanwhile, numeric outputs

might be stored in PostgreSQL or DuckDB for easier analytical queries (though Memgraph could
also store attributes on nodes for recent values). The combination of graph + relational + vector

in Cognee means the knowledge base can answer complex queries (some through Cypher/SQL,

some through embedding similarity), giving a rich context to any agent or application

57

4

.

Triggers & Continuous Processing: This pipeline is both schedule-driven and event-driven. A Dagster

schedule might trigger a nightly comprehensive analysis (producing a daily market report), while real-

time events  trigger focused agents: e.g., a RisingWave materialized view can be set with a condition

(like   a   high-value   transaction   counter)   and   use   a  sink  or   custom   notification   to   Dagster   when   a

condition is met

64

65

. Dagster’s sensors or a simple API call can then initiate the anomaly agent

immediately. The architecture allows scaling this: RisingWave handles high-throughput data and keeps

computations   like   aggregation   in   SQL   (sub-second   latency)

43

,   whereas   Agno   agents   handle   the

interpretation of those results. This synergy meets low-latency needs without requiring the LLM to run

on every single event. (For example, rather than the LLM reading every transaction, RisingWave filters to

“only if suspicious pattern X occurs” then engage the LLM.)

Unified Batch & Stream Considerations: Can DuckLake alone handle batch and streaming needs, or is

RisingWave required?  In this design, DuckLake with incremental updates covers a lot: using frequent

mini-batch ingestions and Postgres triggers, new data is indexed and available to agents nearly in real-

time

17

. This “unified DuckLake” approach keeps the system simpler (one primary storage engine) and

works well for moderate data velocities. Ibis provides a unified query interface, so one could simulate

streaming   by   polling   new   data   in   small   intervals   via   Ibis   on   DuckDB.   However,   for  true   streaming

semantics

(millisecond-level   updates,   continuous   SQL   queries,   very   high   event   throughput),

RisingWave is the better choice. RisingWave is purpose-built for real-time incremental processing with

materialized views, and it can ingest millions of events/sec with sub-10ms latencies on queries

43

.

DuckDB/DuckLake is not designed to maintain always-on incremental views; it excels at analytical batch

queries.   Therefore,   the  recommended   setup  is   to   use  both:   DuckLake   for   the   persistent   historical

store, and RisingWave for the live stream processing, unified via Ibis

41

66

. This yields a Lambda/

Delta-style architecture under one hood: RisingWave keeps a live view of recent data (a “speed layer”),

while DuckLake is the source of truth (batch layer)

66

67

. Ibis ensures that the transformations and

business logic are consistent across them. If the use case tolerates a bit of lag and lower complexity,

one  could  attempt  to  rely  on  DuckLake  +  frequent  Dagster  jobs  +  CocoIndex  triggers  only.  But  for

comprehensiveness, this blueprint includes RisingWave to cover high-performance streaming.

8

Integrated Knowledge Base and Orchestration

A core principle of this architecture is modularity with centralized knowledge. Each team operates its

own pipeline and agents, but the outputs coalesce into shared data stores (CocoIndex and Cognee) that
any agent can draw from. This encourages cross-domain insights – for example, a code analysis agent

could query Cognee to see if the repository it’s analyzing has any known security issues mentioned in

the security news (from the sentiment/news pipeline), or the financial agent could include developer

activity (from code repo data) as a factor in analysis.

Cognee   (Hybrid   Graph-Vector   Store):  Cognee   serves   as   the  collective   memory  and   single   query

interface for the agents. It combines multiple backends: - PostgreSQL – storing relational data or acting

as   indexing   metadata   store.   For   instance,   the   Postgres   could   hold   a   consolidated   table   of   all

“documents” or “events” ingested, with IDs and timestamps (which CocoIndex might use as a source

with triggers

14

68

). Also, any structured results (like a table of anomalies or daily summaries) can

reside here for easy querying. - Memgraph – an in-memory graph database for relationships between

entities.   All   entities   extracted   or   defined   by   the   agents   (repos,   code   components,   people,   tokens,

companies, etc.) become nodes in the graph, and relationships form edges (e.g. “Token A is mentioned

in   Document   X”   or   “Developer   Y   contributes   to   Repo   Z”).   This   allows   complex   queries   like   finding

connection   paths   between   items,   community   detection,   etc.   The   graph   enriches   the   context   by

capturing   how   pieces   of   information   relate.   -  LanceDB   (Vector   Index)  –   a   vector   similarity   search

engine   (built   on   Apache   Arrow).   All   embeddings   produced   by   CocoIndex   (from   code   snippets,

documents,   social   posts,   news,   etc.)   are   stored   here,   enabling   semantic   searches   like   “find   similar

documents to X” or “find posts discussing topic Y”. Cognee uses this to answer natural language queries

and to feed relevant chunks into LLM prompts. Example: An agent query “What are people saying about

Project Z in the last month?” could be handled by searching the vector index for top-N similar texts

about Project Z, then traversing the graph to filter by date or source, etc.

By aligning all processing outputs into Cognee, we ensure that each team’s work benefits the others.

Agents query Cognee via its API to retrieve context (Agno agents can be given a tool or function that

queries Cognee with a Cypher/SQL/embedding query)

63

. The response from Cognee might include a

mix of structured data and raw text excerpts, which the agent then incorporates into its reasoning. This

setup was envisioned such that  “agents can retrieve relevant context (latest prices, related news, etc.) via

Cognee’s API and then reason over it”

63

  – indeed, the knowledge base becomes the bridge between

data and AI reasoning.

Dagster   Orchestration: Dagster  is   the   control   plane   that   keeps   this   system   cohesive.   Each   team’s

pipeline is implemented as a Dagster job/graph with tasks (ops/assets) for each step (ingest, transform,

index, agent inference, etc.). Dagster’s scheduler and sensors handle triggering pipelines on schedules

or events

30

. It also provides monitoring – e.g. logging the token usage of LLM calls, caching results,

retrying failed steps, and materializing outputs. The  Dagster + DLT  combination is powerful:  “Dagster

lets you define ops for each step (extract, load to DuckLake, update index, etc.), and DLT handles incremental

extraction/loading   of   source   data”

69

70

.   This   ensures   data   moving   parts   are   robust.   For   example,

Dagster can orchestrate the flow: (1) fetch new data with DLT, (2) load to DuckLake, (3) update Postgres

index table (triggering CocoIndex), (4) invoke the Agno agent step, and (5) store agent results

32

20

. If

any step fails, Dagster can alert and manage retries, without bringing down the whole system. It also

allows modularity – each team’s pipeline can be developed and tested in isolation, then composed in a

larger schedule or triggered by inter-dependencies if needed.

Inter-Team Coordination: While each team focuses on its domain, Dagster can coordinate data flows

between them when necessary. For instance, the sentiment pipeline might feed a summary directly into

9

the financial pipeline (if an event is detected that should immediately trigger a market analysis). This

could be done via Dagster events or by writing to Cognee and having a sensor on the financial pipeline

watch for certain new nodes (e.g. a new “MajorEvent” node triggers deeper analysis). In practice, much

of the coordination is indirect through Cognee – since all data lands there, an agent in Team3 can

simply query what Team2 produced, rather than having a hard-coded pipeline dependency.

Security and Credentials:  If needed (for APIs, etc.), secrets would be managed via Dagster’s secrets

management or a vault (e.g. the Pulumi and 1Password integration mentioned in the docs for deploying

infrastructure

71

72

 ensures keys for APIs or database are handled safely).

Data Flow Summary and Source-Target Mapping

Finally,   we   summarize   how   data   flows   from   sources   to   targets   across   the   teams,   and   how   each

component maps to the technologies used:

•

Code/Repo Data → (DLT) → DuckLake/DuckDB → (CocoIndex) → LanceDB + Cognee: Source
. They
code files and documentation are ingested by DLT from local or remote repositories

73

land in DuckLake (Parquet + PG). CocoIndex picks up new files (via PG triggers) and generates

embeddings

13

16

, storing them in LanceDB (vector index). The content and extracted info also

populate Cognee’s graph (e.g. repo entity, relationships to developers or libraries). Agno’s Repo

Analyzer agent then reads from this index/graph and writes a structured repo report back into

Cognee (and maybe a file or DB table for reports).  Target: Cognee (knowledge graph enriched

with code insights, plus vector index for code text)

5

74

.

•

Documentation   &   Web   Content   →   (Crawl4AI)   →   DuckDB   →   (CocoIndex)   →   LanceDB   +
Cognee: Any external documentation or relevant web pages (like a project’s documentation site

or StackOverflow Q&A) can be crawled by Crawl4AI

37

. The cleaned text is stored and indexed

similar to above, becoming part of the context pool. Agents can use this to cross-reference what

official   docs   say   versus   the   code   (helpful   for   finding   discrepancies   or   missing   docs).  Target:

Cognee (doc nodes linked to repo, embeddings for semantic search).

•

Social   Media/News   →   (Crawl4AI/API)   →   DuckDB   (or   directly   to   index)   →   CocoIndex   →
LanceDB + Cognee: Tweets, forum posts, news articles are ingested either via APIs or crawling.

Some  transient  data  might  bypass  heavy  storage  and  go  straight  into  an  index  (especially  if

using streaming). Generally, storing raw text in a table (with timestamp, source) is useful for

auditing. CocoIndex embeds the text

15

. Cognee stores relationships (e.g. NewsArticle mentions

Token, or Tweet sentiment about Project). The sentiment analysis agent outputs structured trends

which are stored as separate nodes or records (e.g. a  SentimentReport  node connected to  Topic

nodes). Target: Cognee (sentiment metrics per topic, graph links between topics and entities like

products or tokens, vector index of all text for search).

•

Market/On-Chain Data (Batch) → (DLT) → DuckLake (Parquet) → CocoIndex/Transforms →
Cognee/PG: Structured numeric data (prices, volumes, on-chain metrics) flow through DLT into

DuckDB

45

. These are often stored as time-series tables. CocoIndex or custom transformations

compute derived features or labels (like marking unusual values) and insert those into Cognee’s

PG or graph (e.g. a  Metric  node for each day’s price with an edge to the  Token). The data also

stays in DuckDB for any heavy analytical queries.  Target:  Both Cognee (for graph queries and

quick access by agents) and DuckLake (for historical analysis and backup).

10

•

Real-Time Events (Stream) → RisingWave (Materialized views) → (Ibis) → DuckDB (sink) +
. RisingWave
Cognee: Live events like new transactions or trades stream into RisingWave

76

75

maintains computed views (e.g. rolling stats) that agents might query via Postgres interface or a

direct API. It can also output results: e.g. a continuous sink writes out anomalies or aggregated

stats   to   a   DuckDB   table   or   to   Cognee’s   PG.   When   RisingWave   flags   an   event,   it   triggers   the

corresponding agent. Target: Cognee (e.g. a new Anomaly node) and/or direct notifications.

•

Agent   Outputs   (Reports/Alerts)   →   Cognee   (Graph   +   Vector)   +   External   Outputs:  Every
structured output from the agents is stored in the knowledge base and also can be forwarded to

users. For example, a daily trend report could be indexed (so its text is searchable via vectors)

and also emailed to stakeholders. An anomaly alert JSON could be posted to a Slack channel and

also recorded in the graph DB. Cognee’s design ensures these outputs are integrated: an agent’s

conclusions become new knowledge that other agents can consume

4

77

.

Below is a  mapping table  summarizing each team with their primary data sources, processing tools,

and outputs:

Team /
Domain

Data

Sources

(Input)

Local git

Code &

repos, files,

Doc

docs

Analysis

(Markdown,

code files)

Social

media

posts

Sentiment

(Twitter,

Analysis

Discord),

news

articles,

forums

Processing & Tools

Outputs
(Structured)

Storage Targets

DLT (filesystem ingest)

⇒

DuckLake<br>CocoIndex

(file embeddings, code

chunking) ⇒
LanceDB<br>Agno

agents (Repo

Summarizer, Doc QA)

with BAML schema

25

26

Crawl4AI (web scraping

for news/HN) & API

Repository Report

JSON (summary,

key findings, etc.)

Cognee graph (Repo node,

27

<br>Doc

relations)<br>Cognee vector

completeness

index (code/docs)

analysis

(structured)

ingestion for

Sentiment

social<br>DLT (for API

Dashboard JSON

data) ⇒
DuckDB<br>CocoIndex

(text embeddings) ⇒
LanceDB<br>Agno

(overall sentiment,

topics,

examples)<br>Alert

on sentiment spike

agent (Sentiment

(JSON)

Analyzer) with BAML

schema

Cognee graph (Topic and

Sentiment nodes, e.g. Topic–

hasSentiment→Score)<br>Cognee
vector index (posts, articles)

11

Team /

Domain

Data

Sources

(Input)

Processing & Tools

Outputs

(Structured)

Storage Targets

Financial

Analytics

Market

data APIs

(prices,

DLT (batch API pulls) ⇒
DuckLake/DuckDB

44

45

<br>RisingWave

(CDC/Kafka streams) for

volumes),

real-time

43

<br>Ibis

blockchain

(unified transforms on

events

DuckDB & RisingWave)

(ETH, etc.),

40

<br>CocoIndex

protocol

(embedding text data,

stats (DeFi

computing features)

78

APIs),

<br>Agno agents (Trend

economic

Summarizer, Anomaly

news

Detector, Q&A) with

BAML

Market Trend

Report JSON

(sections: overview,

events, metrics)

34

<br>Anomaly

Alert JSON (entity,

description, cause)

<br>Q&A

responses

(structured answer

with references)

Cognee graph (entities: Tokens,

Protocols, etc. with edges for

metrics/events)

58

<br>Cognee

vector index (news, reports,

etc.)<br>DuckLake (historical

tables for metrics, Parquet)

Each   team’s   configuration   includes   a  system   prompt   (role)  for   its   agents,   the  input   context  they

consume (fed from the indexed data), the  output schema  enforced by BAML, and the  triggers  that

initiate  the  pipeline  or  agent  runs.  By  encapsulating   these  in   Dagster  pipelines,   we   achieve   a   clear

separation of concerns with unified outcomes. The table above highlights how different data types are

handled with appropriate tools, yet ultimately all roads lead to Cognee (knowledge base) and CocoIndex

(semantic index).

Integration Summary

In this modular blueprint,  Agno  provides the flexible agent orchestration needed for each analytical

task, while BAML guarantees that each AI agent’s output is well-structured and reliably parsed

1

2

.

The   use   of  Dagster   +   DLT  for   ingestion   and   pipeline   orchestration   brings   reliability   (incremental

loading,   scheduling,   error   handling)   to   feed   the   data-hungry   agents

69

20

.

 DuckLake  and

RisingWave  together   form   a   hybrid   data   backbone   –   DuckLake   for   durable   batch   storage   and

RisingWave for real-time streaming views, unified via Ibis for consistent transformations across both

modes

41

66

.  Crawl4AI  extends   the   system’s   reach   to   external   unstructured   data,   yielding   high-

quality textual context for the LLMs

36

. And Cognee sits at the center as the evolving knowledge graph

and index that every agent consults and updates –  “a persistent ‘brain’ of knowledge that supports both

structured queries and semantic lookups”

3

.

By grouping agents into domain-specific teams, we can tailor each team’s system message, tools, and

triggers to its particular needs, while still enabling collaboration. For example, the financial agents use

Cognee to pull in sentiment from Team2 and developer insights from Team1, painting a holistic picture

that   combines  quantitative  and  qualitative  analysis

34

61

.   Agno’s   multi-agent   workflow   capabilities

ensure that if a task is complex, agents can be chained or work in stages (as we did with topic extraction

then sentiment summary, or separate code and doc analysis)

26

. This approach also makes the system

extensible  – new teams (say, a Compliance Analysis team or Customer Support QA team) could be

added by plugging in another pipeline that feeds into the same backbone.

In   conclusion,   the   architecture   achieves   a  modular   yet   integrated  design:   each   team   is   a   self-

contained pipeline with clear responsibilities and structured LLM interactions, and all teams contribute

to a unified AI-driven data platform. The combination of structured prompt-response handling (BAML) with

12

robust   data   engineering   (DuckLake/Ibis/RisingWave,   DLT,   Dagster)  and  rich   knowledge   integration

(CocoIndex,   Cognee)  ensures   that   insights   are   derived   in   a   repeatable,   transparent,   and   real-time

manner. This blueprint can be implemented incrementally – starting perhaps with batch pipelines and a

few agents, and evolving towards streaming and more agents – to gradually build up an AI-powered

analytics system grounded in both data and knowledge.

Sources:

•

Agno & BAML usage for structured LLM outputs

1

2

•

CocoIndex incremental indexing with Postgres triggers (live updates)

13

16

•

Dagster pipeline orchestration with DLT for incremental ingestion

70

32

•

DuckLake lakehouse format (DuckDB with Postgres metadata)

11

 and Ibis unified batch/stream

logic

40

•

RisingWave streaming integration for real-time processing

43

66

•

Crawl4AI for AI-friendly web scraping and data extraction

36

37

•

Cognee knowledge base combining graph and vector search

3

4

•

Crypto analytics architecture example (multi-agent, Cognee, CocoIndex)

63

58

•

Sentiment analysis in context of crypto (news/social correlation)

34

61

1

2

5

6

7

8

9

10

21

22

23

24

25

26

27

28

29

42

73

74

End-to-End Workflow for

Analyzing Local Git Repositories with DLT, CocoIndex, Repomix, Agno, and BAM.pdf

file://file_000000000cf47246a5fe51c487848593

3

4

34

35

57

58

60

61

62

63

71

72

77

Crypto Analytics Project – Document Summaries and

Spec Update.pdf

file://file_000000004f0072468c419d09ca2c5363

11

12

13

14

15

16

17

18

19

20

30

31

32

33

59

68

69

70

Integrating DuckLake, CocoIndex, and

Dagster for Incremental Updates.pdf

file://file_000000008cbc71f487ff573d73602e63

36

37

38

39

LLM-Assisted Features in Dagster, DLT, Crawl4AI, and CocoIndex.pdf

file://file_0000000068bc7246bfc39455cbe012f1

40

41

52

53

55

56

64

65

66

67

Integrating RisingWave Streaming with DuckLake Batch ETL using

Ibis and a Semantic Layer.pdf

file://file_000000006e747246b8f5a1cf29e99291

43

48

49

50

51

75

76

Integrating RisingWave for Real-Time Streaming and Materialized Views.pdf

file://file_0000000066507246851c7597cc7fa894

44

45

46

47

54

78

Technical Integration Plan_ Dagster + DLT + CocoIndex + Feast + MLflow (with

DuckDB & Dragonfly).pdf

file://file_00000000867471f49c32fd1570040ee9

13



---

# Patterns Analysis

# Agno Codebase: Comprehensive Pattern and Ontology Analysis

## Executive Summary

The Agno framework is a lightweight, modular Python framework for building multi-modal, reasoning agents. The codebase demonstrates sophisticated architecture patterns centered around composable agent systems, knowledge management, and extensible tool ecosystems.

---

## 1. DOMAIN MODELS AND SCHEMAS

### 1.1 Core Agent Domain Model

**Agent Class** - Primary abstraction for agentic behavior
```python
Agent(
    id: str,                                    # Unique identifier
    name: str,                                  # Display name
    model: Model,                               # LLM model instance
    description: str,                           # Agent purpose
    role: str,                                  # Agent role/responsibility
    instructions: str | List[str],              # System prompts
    tools: List[Tool],                          # Available tools
    knowledge: Knowledge,                       # Knowledge base integration
    memory_manager: MemoryManager,              # Custom memory handler
    db: Db,                                     # Storage backend
    session_state: Dict,                        # Per-session state
    dependencies: Dict,                         # Runtime dependencies
    input_schema: BaseModel,                    # Input validation schema
    output_schema: BaseModel,                   # Output schema
    # ... 20+ configuration parameters
)
```

**Key Characteristics:**
- Fully configurable LLM backend
- Tool composition and automatic discovery
- Hybrid knowledge integration (vector + semantic + BM25)
- Session state management with automatic persistence
- Memory system for user/conversation context

### 1.2 Team Domain Model

**Team Class** - Multi-agent coordination
```python
Team(
    name: str,
    model: Model,                               # Team coordinator model
    members: List[Agent],                       # Team member agents
    instructions: str,                          # Team instructions
    db: Db,
    enable_agentic_memory: bool,                # Team-level memory
    enable_agentic_state: bool,                 # Team-level state
    session_state: Dict,                        # Team state
    show_members_responses: bool,               # Show member outputs
)
```

**Example:** OSS Maintainer Team with 5 specialized agents
- PR Review Council (code review expert)
- Issue Triage Specialist (prioritization)
- Security Guardian (vulnerability detection)
- Community Relations Manager (contributor engagement)
- Release Coordinator (release planning)

### 1.3 Workflow Domain Model

**Workflow Class** - Multi-step process orchestration
```python
Workflow(
    name: str,
    description: str,
    steps: List[Step],                         # Sequence of steps
    input_schema: BaseModel,                   # Workflow input
    db: Db,
    # Supports branching, parallel execution, error handling
)

Step(
    name: str,
    agent: Agent | None,                       # Individual agent
    team: Team | None,                         # Or team of agents
    # ... orchestration config
)
```

**Example:** Investment Workflow
1. Research Step (Team with Wikipedia + Search agents)
2. Analysis Step (Stock Analyst agent)
3. Ranking Step (Research Analyst agent)
4. Portfolio Allocation Step (Portfolio Manager agent)

### 1.4 Knowledge Domain Model

**Knowledge Class** - Unified knowledge management
```python
Knowledge(
    vector_db: VectorDb,                       # Embedding storage
    contents_db: Db,                           # Document storage
    embedder: Embedder,                        # Embedding model
    reranker: Reranker | None,                 # Optional reranking
    chunker: ChunkingStrategy,                 # Text chunking
    reader: DocumentReader,                    # Document parsing
)
```

**Supported Backends:**
- PgVector (PostgreSQL with pgvector)
- LanceDB (vector database)
- Chroma (in-memory/persistent)
- Pinecone, Milvus, MongoDB, Weaviate
- LocalAI, Ollama integrations

### 1.5 Memory Domain Model

**MemoryManager Class** - User/session memory handling
```python
MemoryManager(
    model: Model,                              # Summarizer model
    db: Db,
    additional_instructions: str,              # Memory creation rules
    # Custom system prompts for memory generation
)
```

**Memory Types:**
- User Memories: Persistent facts about users
- Session State: Conversation-specific state
- Chat History: Message history management
- Agentic Memory: Agent-managed context

---

## 2. COMPONENT INTERACTION PATTERNS

### 2.1 Agent Execution Flow

```
┌─────────────┐
│ User Input  │
└──────┬──────┘
       │
       ▼
┌──────────────────────────────────┐
│ Pre-Hooks Execution              │
│ - Input validation               │
│ - Input transformation           │
│ - Dependency injection           │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ Context Building                 │
│ - System prompt construction     │
│ - Session history inclusion      │
│ - Knowledge base search          │
│ - Memory retrieval               │
│ - Dependency resolution          │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ LLM Inference                    │
│ - Model prediction               │
│ - Tool selection                 │
│ - Streaming/structured output    │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ Tool Execution Loop              │
│ - Tool call parsing              │
│ - Pre-hook (tool-level)          │
│ - Execute tool                   │
│ - Post-hook (tool-level)         │
│ - Result feedback to LLM         │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ Post-Hooks Execution             │
│ - Output validation              │
│ - Output transformation          │
│ - Side effects (notifications)   │
└──────┬───────────────────────────┘
       │
       ▼
┌──────────────────────────────────┐
│ State Persistence                │
│ - Session state save             │
│ - Memory update                  │
│ - Chat history storage           │
└──────┬───────────────────────────┘
       │
       ▼
┌─────────────┐
│ Final Output│
└─────────────┘
```

### 2.2 Knowledge Base Integration Pattern

```
Query (text)
    │
    ▼
Retrieve (semantic search)
    │
    ├─ BM25 (keyword search)
    ├─ Vector search (embedding-based)
    └─ Hybrid search (combined)
    │
    ▼
Rerank (optional, using dedicated reranker)
    │
    ▼
Context Window
    │
    ▼
LLM Response with Sources
```

### 2.3 Team Execution Pattern

```
User Query
    │
    ▼
Team Coordinator (receives query)
    │
    ├─ Task analysis
    ├─ Agent routing decision
    │
    ├─ Route to Member 1 ──┐
    ├─ Route to Member 2 ──┤ (Parallel or Sequential)
    └─ Route to Member 3 ──┘
    │
    ▼
Response Synthesis
    │
    ├─ Aggregate member responses
    ├─ Synthesize insights
    └─ Format final response
```

### 2.4 Workflow Execution Pattern

```
Workflow Input (validated against input_schema)
    │
    ▼
Execute Step 1 (Team/Agent)
    │
    ├─ Capture output
    ├─ Validate against schema
    └─ Store in workflow state
    │
    ▼
Execute Step 2 (using previous output as input)
    │
    ├─ Branching support
    ├─ Error handling/recovery
    └─ State propagation
    │
    ▼
Execute Step N...
    │
    ▼
Workflow Output (aggregate all steps)
```

---

## 3. ONTOLOGIES AND DATA MODELS

### 3.1 Agent Ontology

**Agent Types by Capability:**
- Basic Agent: Simple instruction following
- RAG Agent: Knowledge-augmented (Retrieval-Augmented Generation)
- Agentic RAG Agent: Knowledge retrieval as tool
- Reasoning Agent: Extended thinking capability
- Multimodal Agent: Image/video understanding
- Team Coordinator: Multi-agent orchestration

**Agent Specialization:**
- Role-based (e.g., "Financial Advisor", "Code Reviewer")
- Capability-based (e.g., has_knowledge_base, enable_user_memories)
- Model-based (gpt-4, claude-3.5, open-source models)

### 3.2 Tool Ontology

**Tool Categories:**
1. **External Integration Tools**
   - Web Search (DuckDuckGo, Tavily, Exa)
   - Social Media (Twitter, LinkedIn, Reddit)
   - Productivity (Gmail, Slack, Jira, GitHub)
   - Finance (YFinance, Financial Datasets API)
   - Information (Wikipedia, ArXiv, PubMed)

2. **Data Processing Tools**
   - CSV Tools, Pandas Tools
   - File Generation, File Operations
   - Visualization, Data transformation

3. **System Tools**
   - Shell/Command execution
   - Python code execution
   - Docker integration

4. **Specialized Tools**
   - Memory Tools (user memory management)
   - Knowledge Tools (knowledge base search)
   - MCP Tools (Model Context Protocol)
   - Custom Tools (user-defined functions)

**Tool Composition Pattern:**
```python
class CustomToolkit(Toolkit):
    def __init__(self, ...):
        super().__init__(...)
        self.register(self.method1)
        self.register(self.method2)
    
    def method1(self, ...): ...
    def method2(self, ...): ...
```

### 3.3 Model Ontology

**Supported Model Families:**
- OpenAI (GPT-4, GPT-5, o1, o3-mini)
- Anthropic (Claude 3/3.5/4)
- Google (Gemini, LLama via Vertex)
- Open Source (Ollama, LocalAI)
- Specialized (Cerebras, Groq, Azure OpenAI)

**Model Capabilities:**
- Base Models: Standard chat completion
- Reasoning Models: Extended thinking (o1, o3-mini)
- Vision Models: Image understanding
- Code Models: Programming-specific
- Embedders: Text to vectors (OpenAI, Cohere, local)

### 3.4 Vector Database Ontology

**Vector DB Implementations:**
- PostgreSQL + pgvector (relational with vector extension)
- LanceDB (fast vector DB)
- Pinecone (cloud vector DB)
- Chroma (embedded/cloud)
- MongoDB Atlas (document + vector)
- Milvus (open-source vector DB)
- Weaviate (GraphQL-based)

**Search Type Options:**
- Keyword (BM25): Lexical matching
- Vector (Semantic): Embedding similarity
- Hybrid: Combined keyword + semantic
- Semantic (Vector only with reranking)

### 3.5 Database Ontology

**Storage Backends:**
- **Relational**: PostgreSQL, MySQL, SingleStore
- **Key-Value**: Redis, DynamoDB
- **Document**: MongoDB, Firestore
- **Specialized**: SurrealDB (hybrid)
- **In-Memory**: In-memory storage for testing
- **Cloud**: Google Cloud Storage, AWS S3

**Usage Pattern:**
```python
db = PostgresDb(db_url="postgresql://...")
# Stores: sessions, chat history, memories, knowledge
```

---

## 4. API PATTERNS

### 4.1 Agent Execution API

**Synchronous Execution:**
```python
response = agent.run(input="...", user_id="...", session_id="...")
# Returns: RunOutput with content, messages, metrics

agent.print_response(input="...")  # Streams to stdout
```

**Asynchronous Execution:**
```python
response = await agent.arun(input="...", stream=True)
# Async variant for concurrent execution

async for chunk in agent.arun(input="...", stream=True):
    # Stream tokens in real-time
    print(chunk.content, end="", flush=True)
```

**Streaming with Events:**
```python
async for event in agent.arun(input="...", stream_intermediate_steps=True):
    if event.event == RunEvent.tool_call_started:
        print(f"Tool: {event.tool.tool_name}")
    elif event.event == RunEvent.run_content:
        print(event.content, end="", flush=True)
```

### 4.2 Tool Definition API

**Function-Based Tools:**
```python
@tool(requires_confirmation=False)
def my_tool(param1: str, param2: int) -> dict:
    """Tool description for LLM."""
    return {"result": ...}

agent = Agent(tools=[my_tool])
```

**Toolkit Class Pattern:**
```python
from agno.tools.toolkit import Toolkit

class CustomTools(Toolkit):
    def __init__(self):
        super().__init__()
        self.register(self.tool_method)
    
    def tool_method(self, param: str) -> str:
        """Registered as a tool."""
        return ...
```

**Pre/Post Tool Hooks:**
```python
def tool_pre_hook(tool, arguments):
    # Validate/transform arguments
    return modified_arguments

def tool_post_hook(tool, result):
    # Process result
    return modified_result
```

### 4.3 Hook System API

**Agent-Level Hooks:**
```python
def pre_hook(run_input: RunInput) -> None:
    """Called before agent execution."""
    # Input validation/transformation

def post_hook(run_output: RunOutput) -> None:
    """Called after agent execution."""
    # Output validation/transformation/side effects

agent = Agent(
    pre_hooks=[pre_hook],
    post_hooks=[post_hook],
)
```

**Hook Exception Handling:**
```python
from agno.exceptions import InputCheckError, OutputCheckError, CheckTrigger

raise InputCheckError(
    "Invalid input",
    check_trigger=CheckTrigger.INPUT_NOT_ALLOWED
)

raise OutputCheckError(
    "Invalid output",
    check_trigger=CheckTrigger.OUTPUT_NOT_ALLOWED
)
```

### 4.4 Structured I/O API

**Input Validation:**
```python
from pydantic import BaseModel, Field

class ResearchQuery(BaseModel):
    topic: str
    focus_areas: List[str] = Field(description="...")
    sources_required: int = Field(default=5)

agent = Agent(input_schema=ResearchQuery)
```

**Output Structuring:**
```python
class AnalysisResult(BaseModel):
    findings: List[str]
    confidence_score: float
    recommendations: List[str]

agent = Agent(output_schema=AnalysisResult)
response = agent.run(input="...")
# response.content is instance of AnalysisResult
```

### 4.5 Dependency Injection API

**Runtime Dependency Injection:**
```python
def expensive_function():
    # Computed at runtime, once per agent.run()
    return get_market_data()

agent = Agent(
    dependencies={"market_data": expensive_function},
    instructions="Use {market_data} in your analysis"
)
```

**Automatic Dependency Injection:**
```python
agent = Agent(
    dependencies={"top_news": get_news},
    add_dependencies_to_context=True
)
```

---

## 5. COMMON CODING PATTERNS

### 5.1 Configuration Pattern

**Modular Configuration:**
```python
# Agents inherit from modular components
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),
    tools=[DuckDuckGoTools(), YFinanceTools()],
    knowledge=Knowledge(vector_db=PgVector(...), embedder=OpenAIEmbedder()),
    db=PostgresDb(db_url=...),
    memory_manager=MemoryManager(model=Claude(...)),
)
```

**Environment-Driven Configuration:**
```python
import os
api_key = os.getenv("OPENAI_API_KEY")
model = OpenAIChat(id="gpt-4o")
```

### 5.2 State Management Pattern

**Session State:**
```python
agent = Agent(
    session_state={"shopping_list": []},
    instructions="Current list: {shopping_list}"
)

# State auto-persisted to DB, accessible across runs
state = agent.get_session_state()
```

**Dynamic State:**
```python
def update_state(session_state):
    session_state["counter"] = session_state.get("counter", 0) + 1

agent = Agent(change_state=update_state)
```

**Agentic State:**
```python
team = Team(
    enable_agentic_state=True,
    session_state={"project": "Agno", "version": "2.1.0"}
)
# Team manages state across conversations
```

### 5.3 Async Pattern

**Concurrent Agent Execution:**
```python
import asyncio

async def gather_reports():
    tasks = [
        agent1.arun("Task 1"),
        agent2.arun("Task 2"),
        agent3.arun("Task 3"),
    ]
    return await asyncio.gather(*tasks)

results = asyncio.run(gather_reports())
```

**Stream Processing:**
```python
async for chunk in agent.arun(input="...", stream=True):
    # Process tokens as they arrive
    await websocket.send(chunk.content)
```

### 5.4 Error Handling Pattern

**Graceful Degradation:**
```python
try:
    response = agent.run(input="...")
except InputCheckError as e:
    # Pre-hook validation failed
    return handle_invalid_input(e)
except OutputCheckError as e:
    # Post-hook validation failed
    return handle_invalid_output(e)
```

### 5.5 Type Safety Pattern

**Pydantic for All Schemas:**
```python
from pydantic import BaseModel, Field

class Agent Config(BaseModel):
    name: str
    role: str = Field(description="Agent role")
    tools: List[str]
    
    model_config = ConfigDict(extra="forbid")
```

**Type Hints Throughout:**
```python
def process_agent_response(response: RunOutput) -> dict:
    """Type hints for IDE support and validation."""
    return {"content": response.content}
```

### 5.6 Documentation Pattern

**Docstring Standard:**
```python
def my_tool(param1: str, param2: int) -> dict:
    """
    Brief description for LLM and documentation.
    
    Args:
        param1: Description for param1
        param2: Description for param2
    
    Returns:
        dict: Returned structure
    """
```

---

## 6. PLUGIN AND EXTENSION PATTERNS

### 6.1 Tool Plugin Pattern

**Custom Tool Registration:**
```python
from agno.tools.toolkit import Toolkit

class MyServiceTools(Toolkit):
    def __init__(self, api_key: str, ...):
        super().__init__()
        self.api_key = api_key
        self.register(self.fetch_data)
        self.register(self.process_data)
    
    def fetch_data(self, ...): ...
    def process_data(self, ...): ...

# Usage: agent = Agent(tools=[MyServiceTools(api_key=...)])
```

### 6.2 Custom Model Integration

**Model Plugin Pattern:**
```python
from agno.models.base import Model

class CustomModel(Model):
    def response(self, messages: List[Message], **kwargs) -> str:
        # Implement your custom inference
        pass

# Usage: agent = Agent(model=CustomModel(...))
```

### 6.3 Custom Database Backend

**Database Plugin Pattern:**
```python
from agno.db.base import Db

class CustomDb(Db):
    def create_session(...): ...
    def get_session(...): ...
    def update_session(...): ...
    # Implement storage interface

agent = Agent(db=CustomDb(...))
```

### 6.4 Hook Extensions

**Custom Middleware Hooks:**
```python
def validation_hook(run_input: RunInput) -> None:
    """Custom pre-processing."""
    if not is_valid(run_input.input_content):
        raise InputCheckError(...)

def transformation_hook(run_output: RunOutput) -> None:
    """Custom post-processing."""
    run_output.content = transform(run_output.content)

agent = Agent(
    pre_hooks=[validation_hook],
    post_hooks=[transformation_hook],
)
```

### 6.5 Tool Hook Pattern

**Fine-Grained Tool Control:**
```python
def tool_requires_approval(tool_name: str, arguments: dict) -> bool:
    return tool_name in ["delete_user", "modify_system"]

def approve_tool_execution(tool_name: str, arguments: dict) -> bool:
    # Custom approval logic
    return user_confirms(f"Execute {tool_name}?")

agent = Agent(
    tools=[...],
    tool_hooks=[...],  # Pre/post tool execution
)
```

---

## 7. STATE MANAGEMENT PATTERNS

### 7.1 Session State Pattern

**Per-User Session State:**
```python
agent.run(
    input="Add milk to my list",
    user_id="user123",
    session_id="session_abc"
)

# State persisted in DB, retrieved on next call
state = agent.get_session_state(user_id="user123", session_id="session_abc")
```

### 7.2 User Memory Pattern

**Persistent User Memories:**
```python
agent = Agent(
    enable_user_memories=True,
    db=PostgresDb(...)
)

agent.run(
    input="I'm John and I like hiking",
    user_id="john@example.com"
)

# System automatically creates user memory:
# "John likes hiking as a hobby"

memories = agent.get_user_memories(user_id="john@example.com")
```

### 7.3 Agentic Memory Pattern

**Team-Level Memory:**
```python
team = Team(
    enable_agentic_memory=True,
    members=[...],
    db=PostgresDb(...)
)

# Team learns about context and remembers
# across multiple conversations
```

### 7.4 Chat History Pattern

**Automatic History Management:**
```python
agent = Agent(
    add_history_to_context=True,
    num_history_runs=5,  # Last 5 messages
    read_chat_history=True,  # Tool to fetch full history
    db=PostgresDb(...)
)

# History auto-managed, can be customized
```

### 7.5 Dynamic State Updates

**On-Run State Modification:**
```python
def update_visit_count(session_state):
    session_state["visit_count"] = session_state.get("visit_count", 0) + 1
    session_state["last_visited"] = datetime.now().isoformat()

agent = Agent(
    session_state={"visit_count": 0},
    change_state=update_visit_count
)
```

---

## 8. WORKFLOW AND PROCESS PATTERNS

### 8.1 Sequential Workflow Pattern

**Research -> Analyze -> Write Pipeline:**
```python
research_step = Step(name="Research", team=research_team)
analysis_step = Step(name="Analysis", agent=analyst_agent)
writing_step = Step(name="Write", agent=writer_agent)

workflow = Workflow(
    name="Content Pipeline",
    steps=[research_step, analysis_step, writing_step],
    db=PostgresDb(...)
)

result = workflow.run(input={"topic": "AI trends"})
```

### 8.2 Branching Workflow Pattern

**Conditional Execution:**
```python
Step(
    name="Route Decision",
    agent=router_agent,
    # Next step depends on output
)

# Parallel execution
Step(
    name="Parallel Analysis",
    agents=[agent1, agent2, agent3],
)
```

### 8.3 Multi-Agent Collaboration Pattern

**OSS Maintainer Team Workflow:**
```
User Query
    ├─ PR Review Council → Code quality analysis
    ├─ Security Guardian → Vulnerability check (parallel)
    ├─ Issue Triage Agent → Issue categorization
    ├─ Community Manager → Contributor engagement
    └─ Release Coordinator → Release planning

Team Coordinator synthesizes all responses
```

### 8.4 Knowledge-Heavy Workflow

**Research Workflow with RAG:**
```
User Query
    │
    ▼
Research Team (Wikipedia + Web Search)
    │
    ├─ Wikipedia Agent searches knowledge
    └─ Search Agent retrieves web data
    │
    ▼
Aggregated Research Data
    │
    ▼
Analysis Agent with Knowledge Base Access
    │
    ├─ Semantic search
    ├─ Hybrid search with reranking
    └─ Source citation
    │
    ▼
Comprehensive Report
```

### 8.5 Human-in-the-Loop Workflow

**Approval Workflow:**
```
Agent generates action
    │
    ├─ Tool requires_confirmation=True
    │
    ▼
Ask user for confirmation
    │
    ├─ Approve → Execute
    ├─ Deny → Skip
    └─ Modify → User provides modified parameters
    │
    ▼
Continue execution
```

---

## 9. ADVANCED PATTERNS

### 9.1 Parser Model Pattern

**Multi-Stage Output Processing:**
```python
agent = Agent(
    model=OpenAIChat(id="gpt-4o"),  # Reasoning
    output_model=OpenAIChat(id="o3-mini"),  # Structured output
    output_schema=AnalysisResult,
)

# Two-stage: generate then structure
response = agent.run(input="...")  # Structured per schema
```

### 9.2 Concurrent Tool Calls

**Parallel Tool Execution:**
```python
agent = Agent(
    tools=[tool1, tool2, tool3],
    parallel_tool_calls=True,
)

# LLM can call multiple tools simultaneously
# Agno executes them in parallel
```

### 9.3 Multimodal Handling

**Image/Video Processing:**
```python
from agno.tools import Toolkit

class MediaTools(Toolkit):
    def analyze_image(self, image_path: str) -> str:
        """Analyze image at path."""
        from PIL import Image
        img = Image.open(image_path)
        return extract_text(img)

agent = Agent(tools=[MediaTools()])
```

### 9.4 Custom Chunking Strategy

**Document Preprocessing:**
```python
from agno.knowledge.chunker import Chunker

class CustomChunker(Chunker):
    def chunk(self, text: str) -> List[str]:
        # Custom splitting logic
        return chunks

knowledge = Knowledge(
    vector_db=PgVector(...),
    chunker=CustomChunker(...)
)
```

### 9.5 Custom Reranking

**Rerank Search Results:**
```python
from agno.knowledge.reranker import Reranker

knowledge = Knowledge(
    vector_db=PgVector(...),
    reranker=CohereReranker(model="rerank-v3.5"),
    # Or: reranker=CustomReranker()
)
```

---

## 10. UNIQUE AND NOVEL PATTERNS

### 10.1 Dependency Injection at Runtime

Unlike traditional frameworks, agno allows **function-based dependency injection** where dependencies are computed fresh for each agent run:

```python
def current_market_conditions():
    return fetch_latest_market_data()  # Called per run

agent = Agent(
    dependencies={"market": current_market_conditions},
    instructions="Consider the market: {market}"
)
```

### 10.2 Structured Output with Parser Models

The **two-stage reasoning + structuring** pattern:
1. Main model generates comprehensive analysis
2. Parser model formats into structured schema
3. Automatic validation against schema

### 10.3 Agentic Knowledge Searching

Knowledge isn't just context injection—agents get **search tools**:
```python
agent = Agent(
    knowledge=Knowledge(...),
    search_knowledge=True,  # Gives agent search tool
)
# Agent decides WHEN and WHAT to search for
```

### 10.4 Seamless Async Integration

Full async support with unified API:
```python
await agent.arun(...)  # Async execution
async for chunk in agent.arun(..., stream=True):  # Streaming
```

### 10.5 Multi-Backend State Management

State automatically synced across multiple backends:
```python
agent = Agent(
    session_state={...},
    db=PostgresDb(...),  # Chat history + memories
    knowledge=Knowledge(
        vector_db=PgVector(...),  # Knowledge storage
        contents_db=PostgresDb(...)  # Document content
    )
)
```

---

## 11. BEST PRACTICES EVIDENT IN CODE

### 11.1 Composition Over Inheritance
- Agents composed of models, tools, knowledge, memory
- Teams composed of agents
- Workflows composed of steps

### 11.2 Explicit Over Implicit
- Explicit tool registration vs auto-discovery
- Explicit hook declaration
- Explicit state management

### 11.3 Type Safety First
- Pydantic BaseModel for all schemas
- Type hints throughout
- Validation at boundaries

### 11.4 Sensible Defaults
- Pre-configured models
- Default hook behaviors
- Optional but powerful features

### 11.5 Extensibility
- Plugin patterns for tools, models, databases
- Custom hooks at multiple levels
- Custom chunkers, rerankers, embedders

### 11.6 Production Ready
- Session persistence
- Memory management
- Error handling with custom exceptions
- Structured logging
- Metrics and telemetry

---

## 12. INTEGRATION PATTERNS

### 12.1 Web Search Integration
```python
from agno.tools.duckduckgo import DuckDuckGoTools

agent = Agent(
    tools=[DuckDuckGoTools()],
    instructions="Search the web when needed"
)
```

### 12.2 GitHub Integration
```python
from agno.tools.github import GithubTools

agent = Agent(
    tools=[GithubTools(access_token=os.getenv("GITHUB_TOKEN"))],
)

# Can: fetch PRs, issues, create comments, etc.
```

### 12.3 Financial Data Integration
```python
from agno.tools.yfinance import YFinanceTools
from agno.tools.financial_datasets import FinancialDatasetsTools

agent = Agent(
    tools=[YFinanceTools(), FinancialDatasetsTools()],
)
```

### 12.4 MCP (Model Context Protocol)
```python
from agno.tools.mcp import MCPTools

agent = Agent(
    tools=[MCPTools(server_url=...)],
)
```

---

## Summary Table: Pattern Categories

| Pattern | Purpose | Example |
|---------|---------|---------|
| **Domain Model** | Define core entities | Agent, Team, Workflow, Knowledge |
| **Composition** | Combine components | Agent(tools=[], knowledge=..., db=...) |
| **Execution Flow** | Multi-stage processing | Input → Context → LLM → Tools → Output |
| **Hook System** | Intercept and modify | pre_hooks, post_hooks, tool_hooks |
| **State Management** | Persist user context | session_state, user_memories, agentic_state |
| **Tool Plugin** | Extend capabilities | Toolkit subclass registration |
| **Streaming** | Real-time output | async for chunk in agent.arun(...) |
| **Workflow** | Multi-step orchestration | Workflow with Step sequences |
| **Team Coordination** | Multi-agent sync | Team with member routing |
| **Error Handling** | Graceful degradation | CheckError with CheckTrigger |

---

## Key Insights

1. **Modular Architecture**: Every component (model, tool, db, knowledge) is pluggable
2. **Async-First**: Full async support for streaming and concurrency
3. **Type-Safe**: Pydantic for all I/O, eliminating runtime surprises
4. **State-Aware**: Sophisticated state management at session/user/team level
5. **Production-Ready**: Persistence, memory, error handling built-in
6. **Extensible**: Multiple extension points without modifying core
7. **Composable**: Agents → Teams → Workflows create powerful abstractions
8. **Knowledge-Native**: RAG as first-class feature, not add-on



---

# AgentOS Research

# AgentOS: Comprehensive Research Report

**Repository:** https://github.com/buildermethods/agent-os
**Version Analyzed:** v2.1.1
**License:** MIT
**Creator:** Brian Casel (Builder Methods)

---

## Executive Summary

AgentOS is a spec-driven development framework designed to transform AI coding agents from "confused interns into productive developers." Rather than being an agent framework in the traditional sense, it's better understood as an **operating system for spec-driven development workflows**—a structured methodology and tooling system that guides AI agents through repeatable, standards-compliant software development processes.

---

## 1. Core Purpose & Philosophy

### The Problem It Solves

AI coding agents struggle with three fundamental challenges:

1. **Lack of Context:** Agents don't inherently understand project architecture, coding standards, or team conventions
2. **Inconsistent Quality:** Without guidance, agents produce code that requires extensive iteration and correction
3. **Workflow Chaos:** Ad-hoc prompting leads to fragmented, non-repeatable development processes

### Value Proposition

AgentOS addresses these issues through a **three-layer context system** that encodes organizational knowledge into executable specifications:

- **Standards Layer:** Team coding conventions, style guides, and technical preferences
- **Product Layer:** Vision, mission, roadmap, and use-case documentation
- **Specs Layer:** Feature-specific specifications with implementation details

The core philosophy: **"Quality code on the first try"** through structured specifications rather than iterative prompting.

### Design Philosophy

AgentOS is built on several key principles:

1. **Spec-Driven Development:** Replace ad-hoc AI prompting with structured, documented workflows
2. **Modular Composition:** Build large processes from small, reusable components (standards, workflows, commands)
3. **Configuration Over Convention:** Support both multi-agent orchestration and single-agent workflows
4. **Profile-Based Inheritance:** Enable configuration sharing and customization through hierarchical profiles
5. **Pragmatic Over Perfect:** Emphasize speed, token efficiency, and practical outcomes over comprehensive coverage

---

## 2. Key Features & Capabilities

### Core Features

**1. Six-Phase Development Workflow**

AgentOS structures development into six distinct, composable phases:

- **plan-product:** Create mission, roadmap, and tech stack documentation
- **shape-spec:** Research and gather requirements for a feature
- **write-spec:** Generate detailed specification documents
- **create-tasks:** Break specs into organized, executable task groups
- **implement-tasks:** Execute implementation following specs and standards
- **orchestrate-tasks:** Coordinate multi-step implementations across task groups

**2. Dual-Mode Architecture**

Supports both:
- **Multi-Agent Mode:** Specialized Claude Code subagents handle specific phases (60-80% context reduction)
- **Single-Agent Mode:** Sequential numbered prompts guide a single agent through workflows

**3. Standards Management**

Hierarchical organization of coding standards:
- **Global:** coding-style, commenting, conventions, error-handling, tech-stack, validation
- **Backend:** api, migrations, models, queries
- **Frontend:** Component patterns, state management, styling
- **Testing:** test-writing guidelines emphasizing minimal, strategic coverage

**4. Profile System**

Inheritable configuration profiles enabling:
- Team-specific standards sharing
- Project-specific customization
- Version-controlled conventions (via git repositories)

**5. Template Processing Pipeline**

Sophisticated compilation system that:
- Processes conditional blocks (IF/UNLESS tags)
- Expands workflow references
- Injects standards at compile time
- Supports multiple output formats (Claude Code commands, Agent OS commands, Claude Code skills)

### What Developers Can Do

- **Bootstrap Projects:** Install pre-configured development workflows into any codebase
- **Standardize Teams:** Share coding conventions and architectural patterns across projects
- **Guide AI Agents:** Provide structured context that reduces iteration cycles
- **Maintain Consistency:** Ensure all AI-generated code follows team standards
- **Scale Knowledge:** Capture and distribute expert knowledge through specifications
- **Customize Workflows:** Adapt the six-phase process to specific project needs

### Primary Use Cases

1. **Greenfield Development:** Starting new products with clear vision, specs, and standards
2. **Legacy Codebases:** Adding structured workflows to existing projects
3. **Team Collaboration:** Sharing development standards across distributed teams
4. **AI-Assisted Development:** Guiding Claude Code, Cursor, Windsurf, and other AI tools
5. **Feature Development:** From planning through implementation with consistent patterns
6. **Knowledge Capture:** Documenting architectural decisions and technical preferences

---

## 3. Patterns & Architecture

### Architectural Patterns

**1. Profile-Based Inheritance**

Hierarchical configuration system where profiles can inherit from parent profiles:

```
profiles/
  default/
    agents/
    commands/
    standards/
    workflows/
  custom-profile/  (inherits from default)
```

Files are resolved through inheritance chain traversal with exclusion patterns preventing unintended inheritance.

**2. Template Processing Pipeline**

Multi-stage compilation process:

```
Source Template
  → Conditional Compilation (IF/UNLESS)
  → Workflow Expansion ({{workflows/...}})
  → Standards Injection ({{standards/*}})
  → PHASE Tag Embedding
  → Output (Commands/Agents/Skills)
```

**3. Multi-Output Compilation**

Single source files compile to multiple formats:
- `.claude/commands/agent-os/` - Claude Code commands
- `agent-os/commands/` - Generic agent commands
- `.claude/agents/agent-os/` - Claude Code subagents
- `.claude/skills/` - Claude Code skills

Controlled by configuration flags:
- `claude_code_commands: true/false`
- `use_claude_code_subagents: true/false`
- `agent_os_commands: true/false`
- `standards_as_claude_code_skills: true/false`

**4. Lazy Resolution**

Resources are loaded on-demand through inheritance chain traversal, preventing duplicate context loading and optimizing token usage.

**5. Safe Replacement Strategy**

Uses temporary files and Perl for multiline text substitution, avoiding shell escaping issues with complex template replacements.

### System Structure

**Installation Structure (Base)**

```
~/agent-os/
  ├── scripts/
  │   ├── base-install.sh
  │   ├── common-functions.sh
  │   ├── create-profile.sh
  │   ├── project-install.sh
  │   └── project-update.sh
  ├── profiles/
  │   └── default/
  │       ├── agents/
  │       ├── commands/
  │       ├── standards/
  │       ├── workflows/
  │       └── claude-code-skill-template.md
  ├── config.yml
  └── CHANGELOG.md
```

**Project Structure (Per-Project Installation)**

```
project-root/
  ├── agent-os/
  │   ├── product/
  │   │   ├── mission.md
  │   │   ├── roadmap.md
  │   │   └── tech-stack.md
  │   ├── specs/
  │   │   └── YYYY-MM-DD-feature-name/
  │   │       ├── planning/
  │   │       │   ├── requirements.md
  │   │       │   └── visuals/
  │   │       ├── spec.md
  │   │       ├── tasks.md
  │   │       ├── orchestration.yml
  │   │       └── implementation/
  │   ├── standards/
  │   │   ├── global/
  │   │   ├── backend/
  │   │   ├── frontend/
  │   │   └── testing/
  │   └── config.yml
  ├── .claude/
  │   ├── commands/agent-os/  (if enabled)
  │   ├── agents/agent-os/    (if subagents enabled)
  │   └── skills/             (if skills enabled)
```

### Design Principles

1. **Modular Composition:** Break workflows into reusable pieces combined at compile-time
2. **Configuration-Driven Behavior:** Validation rules enforce logical constraints
3. **Normalization First:** Normalize inputs (lowercase, hyphen-separated) before processing
4. **Conditional Loading:** Only load context when needed to optimize token usage
5. **Template-Based Generation:** Use templates for consistency across generated files
6. **Safe Defaults with Flexibility:** Provide sensible defaults while allowing customization

---

## 4. Ontology & Concepts

### Key Terminology

**Agents**

Specialized AI personas with specific roles in the development workflow:

- **product-planner:** Creates mission, roadmap, and tech stack documentation
- **spec-initializer:** Sets up spec folder structure
- **spec-shaper:** Researches and gathers requirements
- **spec-writer:** Generates specification documents
- **spec-verifier:** Validates specifications (deprecated in v2.1)
- **tasks-list-creator:** Breaks specs into task groups
- **implementer:** Executes implementation tasks
- **implementation-verifier:** Validates implementation quality

Each agent has:
- **Name:** Identifier for the agent
- **Color:** UI organization (cyan, purple, etc.)
- **Tools:** Available capabilities (Write, Read, Bash, WebFetch, Playwright)
- **Workflow:** Embedded instructions and process guidance

**Commands**

User-invokable workflows that orchestrate development phases:

- `/plan-product` - Create product documentation
- `/shape-spec` - Research feature requirements
- `/write-spec` - Generate specifications
- `/create-tasks` - Break specs into tasks
- `/implement-tasks` - Execute implementations
- `/orchestrate-tasks` - Coordinate multi-step implementations

Commands exist in two forms:
- **multi-agent:** Delegate to specialized subagents
- **single-agent:** Sequential numbered prompts (e.g., `1-product-concept.md`, `2-create-mission.md`)

**Standards**

Reusable coding conventions organized hierarchically:

- **Global Standards:** Cross-cutting concerns (coding-style, conventions, error-handling)
- **Domain Standards:** Backend, frontend, testing-specific guidelines
- **Tech Stack:** Technology selections and framework requirements

Standards can be:
- Embedded in command prompts (default)
- Delivered as Claude Code Skills (optional)

**Workflows**

Reusable process templates embedded in commands:

- **Planning:** gather-product-info, create-product-mission, create-product-roadmap, create-product-tech-stack
- **Specification:** initialize-spec, research-spec, write-spec, verify-spec
- **Implementation:** compile-implementation-standards, create-tasks-list, implement-tasks

Workflows use `{{workflows/category/name}}` syntax for embedding.

**Profiles**

Configuration packages containing agents, commands, standards, and workflows:

- Support inheritance from parent profiles
- Enable team-specific customization
- Version-controlled via git repositories

**Specs**

Feature-specific documentation organized by date:

```
YYYY-MM-DD-feature-name/
  ├── planning/
  │   ├── requirements.md      # User requirements and research
  │   └── visuals/             # Mockups and design assets
  ├── spec.md                  # Technical specification
  ├── tasks.md                 # Task groups and checklists
  ├── orchestration.yml        # Implementation coordination
  └── implementation/          # Implementation artifacts
```

**Task Groups**

Collections of related implementation tasks:

- Organized by specialization (database, API, frontend, testing)
- Include 2-8 focused tests per group (16-34 total per feature)
- Have acceptance criteria and dependencies
- Tracked via checkboxes in `tasks.md`

### Mental Model

AgentOS models software development as a **spec-driven pipeline**:

```
Product Vision
  ↓
Feature Idea
  ↓
Requirements Research (shape-spec)
  ↓
Technical Specification (write-spec)
  ↓
Task Breakdown (create-tasks)
  ↓
Implementation (implement-tasks / orchestrate-tasks)
  ↓
Verified Delivery
```

Each phase produces **artifacts** (documents) that inform subsequent phases. Standards provide **constraints** that ensure consistency. Agents provide **expertise** for specific tasks.

The framework emphasizes:
- **Documentation Before Code:** Specs precede implementation
- **Reuse Before Creation:** Search for existing patterns first
- **Standards Compliance:** All outputs respect team conventions
- **Minimal Testing:** Strategic coverage over comprehensive tests
- **Iterative Refinement:** Verify specs before implementation begins

---

## 5. Integration & Usage

### Installation & Setup

**Step 1: Base Installation**

```bash
# Install AgentOS to ~/agent-os
curl -sSL https://raw.githubusercontent.com/buildermethods/agent-os/main/scripts/base-install.sh | bash
```

Creates base directory with scripts, profiles, and configuration.

**Step 2: Customize Standards**

Edit standards in `~/agent-os/profiles/default/standards/` to match team preferences:

```
~/agent-os/profiles/default/standards/
  ├── global/
  │   ├── tech-stack.md       # Technology selections
  │   ├── conventions.md      # Project organization
  │   └── ...
  ├── backend/
  ├── frontend/
  └── testing/
```

**Step 3: Project Installation**

```bash
# Within your project directory
~/agent-os/scripts/project-install.sh

# With options
~/agent-os/scripts/project-install.sh \
  --profile=custom \
  --claude-code-commands=true \
  --use-claude-code-subagents=true
```

Configuration options:
- `--profile=NAME` - Select configuration profile
- `--claude-code-commands=true/false` - Install Claude Code commands
- `--use-claude-code-subagents=true/false` - Enable multi-agent delegation
- `--agent-os-commands=true/false` - Install generic commands
- `--standards-as-claude-code-skills=true/false` - Convert standards to skills

### Typical Workflow

**1. Product Planning**

```bash
/plan-product
```

Agent gathers product vision and creates:
- `agent-os/product/mission.md` - Vision and strategy
- `agent-os/product/roadmap.md` - Phased development plan
- `agent-os/product/tech-stack.md` - Technical decisions

**2. Shape Specification**

```bash
/shape-spec
```

Agent conducts research interview, gathers requirements, and creates:
- `agent-os/specs/YYYY-MM-DD-feature/planning/requirements.md`
- `agent-os/specs/YYYY-MM-DD-feature/planning/visuals/` (if provided)

**3. Write Specification**

```bash
/write-spec
```

Agent generates technical specification:
- `agent-os/specs/YYYY-MM-DD-feature/spec.md`

Includes:
- Goals and user stories
- Specific requirements
- Visual design references
- Existing code to leverage
- Out-of-scope items

**4. Create Tasks**

```bash
/create-tasks
```

Agent breaks spec into task groups:
- `agent-os/specs/YYYY-MM-DD-feature/tasks.md`

Organized by specialization with acceptance criteria and test requirements.

**5. Implement Tasks**

```bash
/implement-tasks
```

Agent executes implementation following specs and standards.

**6. Orchestrate Tasks (Multi-Step)**

```bash
/orchestrate-tasks
```

Agent coordinates complex implementations:
- Creates `orchestration.yml` with task group assignments
- Delegates to subagents (if enabled) or generates numbered prompts
- Tracks progress through task checkboxes

### Integration with AI Systems

**Claude Code (Primary)**

Multi-agent configuration leverages Claude Code's subagent system:

```yaml
# .claude/agents/agent-os/product-planner.yml
name: product-planner
color: cyan
model: $inherit
tools:
  - Write
  - Read
  - Bash
  - WebFetch
```

Commands delegate to subagents:

```markdown
Use the product-planner subagent to create documentation:
- Gather product details
- Generate mission.md, roadmap.md, tech-stack.md
```

**Single-Agent Tools (Cursor, Windsurf, etc.)**

Sequential numbered prompts guide the agent:

```
1-product-concept.md → 2-create-mission.md → 3-create-roadmap.md → 4-create-tech-stack.md
```

Each file contains complete instructions for that step.

**Standards Delivery**

Two modes:

1. **Embedded (default):** Standards injected directly into command prompts
2. **Claude Code Skills:** Standards converted to discoverable skills

### Update & Maintenance

```bash
# Update project installation
~/agent-os/scripts/project-update.sh

# Options
~/agent-os/scripts/project-update.sh \
  --overwrite-agents \
  --overwrite-commands \
  --dry-run
```

Updates preserve:
- User-created specs in `agent-os/specs/`
- Product documentation in `agent-os/product/`
- Customized standards (if not overwritten)

Updates replace:
- Command definitions
- Agent definitions
- Workflow templates
- Default standards (if flagged)

---

## 6. Unique Differentiators

### What Makes AgentOS Special

**1. Not a Framework, but an Operating System**

Unlike traditional agent frameworks (AutoGPT, CrewAI, LangGraph), AgentOS doesn't provide runtime orchestration. Instead, it's a **development methodology** packaged as installable workflows and standards.

**2. Spec-Driven, Not Prompt-Driven**

Instead of:
```
"Build a user authentication system"
```

AgentOS produces:
```
agent-os/specs/2025-11-20-user-auth/
  ├── planning/requirements.md  (15 specific requirements)
  ├── spec.md                   (detailed technical spec)
  └── tasks.md                  (organized task groups)
```

**3. Dual Architecture**

Uniquely supports both:
- **Multi-agent orchestration** (Claude Code subagents)
- **Single-agent sequential workflows** (numbered prompts)

Same source files compile to both modes.

**4. Standards as First-Class Citizens**

Most frameworks treat coding standards as documentation. AgentOS:
- Embeds standards directly in agent prompts
- Enforces alignment through verification steps
- Can convert standards to discoverable Claude Code Skills

**5. Template Compilation System**

Sophisticated build system that:
- Processes conditional logic (IF/UNLESS blocks)
- Expands workflow references recursively
- Handles multiline template substitution safely
- Generates multiple output formats from single source

**6. Profile-Based Inheritance**

Configuration sharing through hierarchical profiles:
- Base profile with sensible defaults
- Team profiles with shared conventions
- Project-specific overrides

**7. Pragmatic Testing Philosophy**

Explicitly rejects comprehensive test coverage during development:
- 2-8 tests per implementation task group
- Maximum 10 additional integration tests
- Focus on core user flows only
- Defer edge cases to dedicated testing phases

This contrasts with TDD-focused frameworks.

**8. Built for Real Codebases**

Emphasizes:
- Reusing existing components before creating new ones
- Searching for similar patterns in the codebase
- Respecting established conventions
- Incremental adoption in legacy systems

**9. Tool-Agnostic**

Works with any AI coding assistant:
- Claude Code (with advanced subagent features)
- Cursor
- Windsurf
- Gemini Code Assist
- Any tool that supports markdown commands

**10. Version-Controlled Knowledge**

Standards, workflows, and profiles stored in git repositories enable:
- Team-wide consistency
- Change tracking
- Collaborative improvement
- Rollback capabilities

---

## 7. Best Practices

### Recommended Usage Patterns

**1. Start with Product Planning**

Always begin with `/plan-product` to establish:
- Clear vision and mission
- Phased roadmap
- Technical stack decisions

This provides essential context for all subsequent work.

**2. Customize Standards Early**

Before first project installation, edit `~/agent-os/profiles/default/standards/` to match your:
- Technology choices
- Naming conventions
- Architecture patterns
- Error handling approaches

Generic standards produce generic code.

**3. Use Visual Assets**

Include mockups in `planning/visuals/` during `/shape-spec`:
- Reduces ambiguity
- Enables visual analysis
- Prevents UI rework
- Guides component reuse

**4. Verify Before Implementation**

Review generated specs thoroughly:
- Check alignment with requirements
- Validate reuse opportunities
- Confirm test limits (2-8 per group)
- Ensure nothing is over-engineered

Implementation follows specs exactly—validate early.

**5. Search for Reusability**

Both `/write-spec` and `/create-tasks` emphasize:
- Finding similar existing features
- Identifying reusable components
- Leveraging established patterns

This prevents code duplication and maintains consistency.

**6. Keep Tests Minimal**

Follow AgentOS testing philosophy:
- 2-8 focused tests per implementation task group
- Test behavior, not implementation
- Core user flows only during development
- Fast execution (milliseconds)

Resist the urge for comprehensive coverage during feature work.

**7. Use Orchestration for Complex Features**

For multi-step implementations:
- Use `/orchestrate-tasks` instead of direct implementation
- Assign subagents (multi-agent) or follow numbered prompts (single-agent)
- Track progress through task checkboxes
- Update orchestration.yml as work progresses

**8. Maintain Spec-Code Alignment**

As requirements change:
- Update specs first
- Regenerate tasks if needed
- Adjust implementation to match
- Don't let code drift from specifications

**9. Profile Management**

For teams:
- Create custom profiles inheriting from default
- Store in git repositories
- Share across projects: `--profile=team-profile`
- Version control standard changes

**10. Update Regularly**

```bash
# Update base installation
~/agent-os/scripts/base-install.sh

# Update project installations
~/agent-os/scripts/project-update.sh
```

Stay current with workflow improvements and bug fixes.

### Anti-Patterns to Avoid

**1. Skipping Product Planning**

Jumping directly to feature specs without mission/roadmap context produces disconnected features.

**2. Generic Standards**

Leaving placeholder standards (e.g., `[Rails/Django/FastAPI]`) causes agents to make arbitrary tech stack decisions.

**3. Over-Testing During Development**

Writing comprehensive test suites during feature implementation:
- Slows development velocity
- Wastes tokens on edge cases
- Violates AgentOS testing philosophy

**4. Ignoring Existing Code**

Not searching for reusable components before implementation:
- Creates duplicate functionality
- Violates DRY principles
- Increases maintenance burden

**5. Ad-Hoc Prompting**

Using AgentOS but still prompting agents directly:
- Bypasses standards enforcement
- Fragments development workflow
- Loses spec-code traceability

**6. Premature Implementation**

Starting implementation before:
- Requirements are fully gathered
- Specs are written and verified
- Tasks are broken down and organized

**7. Single-Agent for Complex Features**

Using single-agent mode for large, multi-phase implementations:
- Exhausts context windows
- Reduces parallel work opportunities
- Misses subagent specialization benefits

**8. Mixing Approaches**

Inconsistently using:
- Some features with specs, some without
- Some with standards, some ad-hoc
- Some with orchestration, some direct implementation

Consistency is key for maintainability.

---

## Architectural Evolution

### Version History Insights

**v1.0 (Initial Release)**
- Single-agent framework
- Basic command structure
- Manual spec writing

**v1.1 (Context Optimization)**
- Conditional document loading
- 60-80% context reduction
- Prevents duplicate loading

**v1.2 (Multi-Agent Introduction)**
- Specialized Claude Code subagents
- Focused task delegation
- Improved efficiency

**v1.3 (Pre-flight Checks)**
- Centralized agent detection
- Configuration validation
- Better error messages

**v1.4 (Team Collaboration)**
- Per-project standards customization
- Git-based sharing
- Profile inheritance

**v2.0 (Dual-Mode Architecture)**
- Support for both multi-agent and single-agent
- Flexible boolean configuration
- Eliminated rigid mode structures

**v2.1 (Modular Phases)**
- Expanded from 4 to 6 phases
- Pick-and-choose workflow components
- Claude Code Skills support
- Removed unnecessary verifiers

### Design Decisions

**Eliminated in v2.1:**
- Specialized verifiers (consolidated into workflows)
- Roles system (too complex)
- Documentation bloat (streamlined)
- Mandatory workflows (now optional)

**Emphasis on:**
- Speed and token usage optimization
- Flexible workflow composition
- Standards discoverability (Skills)
- Minimal required structure

---

## Technical Implementation Details

### Template Syntax

**Workflow Embedding:**
```markdown
{{workflows/planning/gather-product-info}}
```

**Standards Injection:**
```markdown
{{standards/*}}
{{standards/global/tech-stack}}
```

**Conditional Blocks:**
```markdown
{{#IF use_claude_code_subagents}}
Use the product-planner subagent...
{{#UNLESS use_claude_code_subagents}}
Follow these steps sequentially...
{{#ENDIF}}
```

**Phase Tags:**
```markdown
{{#PHASE 1}}
First step instructions...
{{#PHASE 2}}
Second step instructions...
```

### Configuration Schema

```yaml
# config.yml
version: "2.1.1"
claude_code_commands: true           # Install .claude/commands/agent-os/
use_claude_code_subagents: true      # Install .claude/agents/agent-os/
agent_os_commands: false             # Install agent-os/commands/
standards_as_claude_code_skills: false  # Convert to .claude/skills/
default_profile: "default"           # Profile to use
```

### Key Functions (from common-functions.sh)

- `get_profile_file()` - Traverse inheritance chain for file resolution
- `process_conditionals()` - Handle IF/UNLESS blocks with stack-based tracking
- `compile_agent()` - Orchestrate all template transformations
- `get_yaml_array()` / `get_yaml_value()` - Robust YAML parsing

---

## Comparison to Other Frameworks

| Aspect | AgentOS | AutoGPT | CrewAI | LangGraph |
|--------|---------|---------|---------|-----------|
| **Type** | Development methodology | Autonomous agent | Multi-agent framework | Workflow orchestration |
| **Runtime** | None (compile-time only) | Python runtime | Python runtime | Python runtime |
| **Target** | AI coding assistants | General automation | Role-based teams | Complex workflows |
| **Standards** | First-class, enforceable | Not emphasized | Not emphasized | Not emphasized |
| **Specs** | Core artifact | Optional | Optional | Optional |
| **Installation** | Per-project + base | pip/npm package | pip package | pip package |
| **Language** | Shell scripts + markdown | Python | Python | Python |
| **Output** | Commands/agents/skills | Task execution | Task execution | Graph execution |

AgentOS is unique in being a **compile-time development methodology** rather than a **runtime orchestration framework**.

---

## Strengths & Limitations

### Strengths

1. **Simplicity:** No runtime dependencies, just shell scripts and markdown
2. **Tool-Agnostic:** Works with any AI coding assistant
3. **Standards-Driven:** Enforces consistency through embedded conventions
4. **Flexible Architecture:** Supports both multi-agent and single-agent modes
5. **Version-Controlled:** All configuration in git repositories
6. **Pragmatic:** Emphasizes speed and practical outcomes
7. **Battle-Tested:** Used in production by Builder Methods

### Limitations

1. **Shell-Based:** Requires bash environment, less portable to Windows
2. **No Runtime Orchestration:** Can't dynamically adjust workflows
3. **Manual Updates:** Requires running update scripts
4. **Claude Code Bias:** Advanced features require Claude Code
5. **Limited Customization:** Template system has learning curve
6. **No Metrics:** No built-in tracking of workflow effectiveness

---

## Conclusion

AgentOS represents a fundamentally different approach to AI-assisted development. Rather than providing runtime orchestration like traditional agent frameworks, it offers a **development operating system**—a structured methodology for spec-driven development with AI coding agents.

Its core insight: AI agents need **context, constraints, and process** more than they need autonomy. By encoding team standards, establishing clear workflows, and producing specifications before code, AgentOS transforms the AI coding experience from iterative prompting to structured, repeatable development.

The framework's dual-mode architecture (multi-agent and single-agent) makes it uniquely flexible, while its profile-based inheritance enables team-wide standardization. Its emphasis on pragmatic testing, code reuse, and token efficiency reflects real-world software development priorities.

AgentOS is best suited for:
- Teams standardizing AI-assisted development practices
- Projects requiring consistent coding standards
- Feature development following spec-driven methodologies
- Organizations wanting version-controlled development knowledge

It's less suitable for:
- Ad-hoc exploratory coding
- Dynamic runtime agent orchestration
- Platform-specific automation (requires bash)
- Projects without defined standards or processes

As AI coding assistants become ubiquitous, frameworks like AgentOS that provide **structure and standards** rather than just **autonomy** will likely become increasingly valuable for professional software development teams.

---

## Resources

- **GitHub Repository:** https://github.com/buildermethods/agent-os
- **Documentation:** https://buildermethods.com/agent-os
- **Creator:** Brian Casel (Builder Methods)
- **Community:** Newsletter and YouTube content available
- **License:** MIT (Open Source)
- **Latest Version:** v2.1.1 (October 28, 2025)

---

**Research Conducted:** November 20, 2025
**Researcher:** Claude (Anthropic)
**Repository Analyzed:** buildermethods/agent-os (main branch)
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall