create-agent-app

name

create-agent-app

description

Use this skill when the user asks to build any agentic solution with OctoFlow — a TypeScript agentic runtime. Do NOT activate for general LLM API calls, plain HTTP integrations, or non-OctoFlow agent frameworks. Triggers on "build an agent", "create an AI agent", "set up OctoFlow", "add memory/brain to agent", "multi-agent workflow", "supervisor pack", "tool-using agent", "agent with RBAC policy", "approval gates", "Slack/Telegram/Discord bot", "agent loop", "workflow automation", "MCP agent", "SKILL.md runner", "brain/memory agent", "pack/swarm/supervisor/parallel agent", "A2A agent", "scheduled agent job", "AG-UI gateway", "React chatbot with OctoFlow", "execution sandbox", "circuit breaker", "session replay", "structured output validation", or any request to build, scaffold, or extend an agentic TypeScript app using OctoFlow.

Create Agents App — OctoFlow

Thin router for building any agentic solution with OctoFlow. Most knowledge lives in references and on GitHub — this file is the decision logic.

GitHub: https://github.com/bgauryy/Octoflow · Docs: https://github.com/bgauryy/Octoflow/tree/main/docs · Examples: https://github.com/bgauryy/Octoflow/tree/main/packages/octoflow-examples/src

Reference Files (load on demand)

File	When to load
references/octoflow-feature-map.md	Step 2 — pick API + doc + example for the user's goal; also the full backend catalog (5 routes).
references/code-patterns.md	Step 4 — runnable TypeScript snippet for the chosen feature(s). 17 sections + install + package imports.
references/octoflow-docs-index.md	When you need a specific doc URL, the example-directory list for a category, or to look up something not in the feature map.

---

Operating Model

UNDERSTAND → MAP → PLAN → GATE → GENERATE → VALIDATE → DELIVER

Hard rules — MUST enforce:

• MUST consult references/octoflow-feature-map.md before generating — it routes goal → API → doc → example.
• MUST fetch the canonical example via its GitHub URL before writing code. This skill runs remotely; never assume the OctoFlow monorepo is on disk.
• MUST present the plan and WAIT for user approval before writing any file.
• MUST typecheck after writing: npx tsc --noEmit <entry>.ts (or the host project's existing typecheck script).
• NEVER emit placeholder stubs — every snippet must be complete and runnable.
• NEVER use // @ts-ignore or // eslint-disable to hide errors — fix the underlying issue.
• NEVER commit, publish, or push any file.
• NEVER reference local paths like packages/octoflow-examples/... as if they exist on the user's disk — always link to GitHub.

---

Step 1 — Understand

Extract before generating:

• Goal — what should the agent do? (answer questions / automate tasks / coordinate agents / power a chat UI / research / code review / etc.)
• Backend — which LLM route? See the 5-route catalog in references/octoflow-feature-map.md.
• Features — tools? MCP? brain? multi-agent? RBAC? approvals? loops? adapters? AG-UI? A2A? sandbox?
• Output target — standalone script · Express/Hono API · React app · CLI tool · existing package.
• Env — zero-env (auto-discover/ollama) · API key · Docker · platform bot tokens.

Ask ONE focused question only when the answer changes the feature set or output format. Otherwise proceed with stated assumptions.

---

Step 2 — Map

Load references/octoflow-feature-map.md. For every required feature, pull out three things:

1. API call — exact function/option name to use.
2. Doc URL — GitHub link to the relevant docs/*.md section.
3. Example URL — GitHub link to the canonical example folder.

For the backend, pick the matching route from the same file's backend catalog. If a feature is not in the map, browse references/octoflow-docs-index.md §Examples Categories or the examples root.

---

Step 3 — Plan

Build a plan covering:

1. Install — list every npm package (see references/code-patterns.md §Install).
2. Entry point — file name and output path.
3. Imports — exact named imports per package (see references/code-patterns.md §Package → GitHub → Key imports).
4. Agent config — backend route, tools, brain, policy, session, workers.
5. Core flow — step-by-step what the agent does.
6. Cleanup — agent.close() (and pack/adapter/MCP equivalents) in a finally block.
7. Run command — npx tsx --env-file=.env <entry>.ts (or npx tsx <entry>.ts for zero-env).
8. Env requirements — list every env var; mark zero-env explicitly when none needed.

Present the plan, then gate:

Plan ready. Choose:
1. Generate — write files as planned.
2. Adjust — change features, backend, or target.
3. Inspect example — fetch the matching example from GitHub first.
4. Cancel.

---

Step 4 — Generate

For each feature in the approved plan:

1. Fetch the example via its GitHub URL (from Step 2's example link).
2. Load the matching pattern from references/code-patterns.md (numbered §1–18, indexed by feature).
3. Adapt — preserve original imports and option shapes; substitute only the user's specifics.
4. Compose — combine patterns in dependency order: bootstrap first, then tools/MCP/brain, then multi-agent/loop/flow, then security, then adapters/gateways, then plugins.

Every generated file must end with cleanup in a try { ... } finally { ... } block — see references/code-patterns.md §17.

---

Step 5 — Validate

# Universal typecheck
npx tsc --noEmit <entry>.ts

# If host project already has scripts
npm run typecheck
npm run lint

# Run
npx tsx --env-file=.env <entry>.ts        # with env vars
npx tsx <entry>.ts                        # zero-env

Fix ALL errors. NEVER add // @ts-ignore or // eslint-disable to bypass real issues.

Do NOT assume npm run -w <package> — that only works inside the OctoFlow monorepo.

---

Step 6 — Deliver

Present:

1. File path — exact location of every written file.
2. Install — npm install commands needed.
3. Run command — copy-paste ready.
4. Env required — list every env var; mark zero-env when none needed.
5. Features active — checklist of OctoFlow features used.
6. Next steps — natural extensions (e.g., "add brain for memory", "add RBAC policy", "add Slack adapter").

End with:

Choose:
1. Add a feature — pick from the feature map.
2. Adjust — change backend, tools, or target.
3. Explain — walk through any section of the code.
4. Done.

---

Recovery

Problem	Fix
No backend available	Use discoverAvailableBackends() and print discovery.summary for friendly install hints.
Missing API key	Check .env; print the exact env var name; wrap in try/catch.
TypeScript error	Fix before delivering — never hand off broken code.
Feature not in map	Browse examples on GitHub.
Brain + CLI backend conflict	CLI backends use their own native memory — note the constraint, don't enable brain on top.
Pack example not found	Use simple-pack as canonical reference.
MCP cleanup missing	Always await loaded.cleanup() or await pool.disconnect() in finally.
Stale example URL	Cross-check against references/octoflow-docs-index.md §Examples Categories — directory names are listed there verbatim.