FlowHunt

Build a personal replacement for one FlowHunt agent in an empty repository.
Use TypeScript, Node.js 22, SQLite via better-sqlite3, and the Vercel AI SDK; do not offer alternative stacks.
Scope: a single configurable AI agent, not a general no-code platform. Pick one job and do it well.
The core loop is: load a knowledge base, accept an input (webhook or CLI), route it through a chosen model with a system prompt and a fixed set of tools, take one action, and store the result.
agent.json defines the system prompt, the model (OpenAI or Anthropic, selectable), the tools it may call, and the schedule or trigger.
Ingest a local docs/ folder into a SQLite vector table for retrieval; re-index on a command.
Implement exactly two real tools, an HTTP fetch/POST to a named API using credentials from .env, and a write-to-file or write-to-db action; document how to add a third.
Run on a webhook endpoint and on a cron schedule; keep an immutable log of every run: input, retrieved chunks, model, tokens, tool calls, output, and errors.
Add retries with backoff on 429 and 5xx, a per-run token budget cap, and visible failed runs rather than silent drops.
Put all secrets in .env, ship .env.example, and never commit credentials.
Store all data locally by default and make CSV export straightforward.
Include clear empty, loading, success, and recoverable error states in a plain server-rendered run dashboard.
Write focused tests for retrieval, one tool call, and one end-to-end happy path.
Create a README with setup, the agent config schema, how to add a tool, data location, and cost notes.
Do not add accounts, billing, telemetry, a visual builder, or a connector marketplace.
Deliberately leave out multi-tenant workspaces and team permissions.
Deliberately leave out one-click OAuth for dozens of third-party apps.
Finish by running the tests and listing the exact commands used.

# AGENTS.md — Build guide for FlowHunt

## Project scope
Wire one AI agent to one or two data sources, route a prompt through a chosen model, run a fixed tool/action, and return or store the result on a schedule or webhook.

Catalogue verdict: no. You can build one agent; you cannot build FlowHunt. A single-purpose AI agent, take a knowledge base or a data source, route a prompt through a model, take an action, return the result, is a one-sitting build. But the paid product's value sits outside that solo rebuild: a hosted runner that stays up, 100+ maintained connectors with all the OAuth and schema-drift upkeep behind them, one-provider model routing with credit accounting, a no-code visual builder aimed at people who will not write code, and team workspaces. That is integration breadth plus managed infrastructure, which is a structural moat, not polish. The prompt below is the honest consolation build: the one workflow you actually run, self-hosted, and you own its upkeep from then on.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- OpenAI or Anthropic API key (and any other model providers you route to)
- API or OAuth credentials for each tool the agent actually touches
- a vector store or SQLite for the knowledge base
- a scheduler or webhook endpoint
- a place to host the runner

## Stack and architecture
- Use TypeScript, Node.js 22, SQLite via better-sqlite3, and the Vercel AI SDK.
- Ingest a local docs/ folder into a SQLite vector table for retrieval; re-index on a command.
- Interface for this no-code AI agent and workflow builder workflow: a focused no-code AI agent and workflow builder input, review, and export interface.

## Security and data integrity
- Run on a webhook endpoint and on a cron schedule; keep an immutable log of every run: input, retrieved chunks, model, tokens, tool calls, output, and errors.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: 100+ maintained connectors and the OAuth apps, token refresh, and schema-drift upkeep behind them.

## Agent implementation rules
- Project rule, data: Ingest a local docs/ folder into a SQLite vector table for retrieval; re-index on a command.
- Project rule, behavior: Scope: a single configurable AI agent, not a general no-code platform. Pick one job and do it well.
- Project rule, recovery: Run on a webhook endpoint and on a cron schedule; keep an immutable log of every run: input, retrieved chunks, model, tokens, tool calls, output, and errors.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this no-code AI agent and workflow builder operation with sample or user-owned data: Scope: a single configurable AI agent, not a general no-code platform. Pick one job and do it well.
- Show a concrete result or export: Store all data locally by default and make CSV export straightforward.
- State the practical limit: 100+ maintained connectors and the OAuth apps, token refresh, and schema-drift upkeep behind them.

## Engineering roadmap
1. Phase 1, architecture and data: Use TypeScript, Node.js 22, SQLite via better-sqlite3, and the Vercel AI SDK. Ingest a local docs/ folder into a SQLite vector table for retrieval; re-index on a command.
2. Phase 2, implement: Scope: a single configurable AI agent, not a general no-code platform. Pick one job and do it well.
3. Phase 3, implement: Implement exactly two real tools, an HTTP fetch/POST to a named API using credentials from .env, and a write-to-file or write-to-db action; document how to add a third.
4. Phase 4, review and output: Run on a webhook endpoint and on a cron schedule; keep an immutable log of every run: input, retrieved chunks, model, tokens, tool calls, output, and errors. Store all data locally by default and make CSV export straightforward.
5. Phase 5, recovery and acceptance: Run on a webhook endpoint and on a cron schedule; keep an immutable log of every run: input, retrieved chunks, model, tokens, tool calls, output, and errors. Verify this invariant with a saved fixture: A retry after a provider timeout must not repeat a completed external action without an explicit reconciliation step. State the practical limit: 100+ maintained connectors and the OAuth apps, token refresh, and schema-drift upkeep behind them.

## Paid-product capabilities outside this build
- 100+ maintained connectors and the OAuth apps, token refresh, and schema-drift upkeep behind them
- the no-code visual builder that lets non-developers assemble and edit agents
- one-provider model routing with credit metering across OpenAI, Anthropic, Google, Meta, and Mistral
- managed hosting, execution capacity, and reliability instead of a box you babysit
- team workspaces, shared agents, and role permissions

## Implementation prompt
Build a personal replacement for one FlowHunt agent in an empty repository.
Use TypeScript, Node.js 22, SQLite via better-sqlite3, and the Vercel AI SDK; do not offer alternative stacks.
Scope: a single configurable AI agent, not a general no-code platform. Pick one job and do it well.
The core loop is: load a knowledge base, accept an input (webhook or CLI), route it through a chosen model with a system prompt and a fixed set of tools, take one action, and store the result.
agent.json defines the system prompt, the model (OpenAI or Anthropic, selectable), the tools it may call, and the schedule or trigger.
Ingest a local docs/ folder into a SQLite vector table for retrieval; re-index on a command.
Implement exactly two real tools, an HTTP fetch/POST to a named API using credentials from .env, and a write-to-file or write-to-db action; document how to add a third.
Run on a webhook endpoint and on a cron schedule; keep an immutable log of every run: input, retrieved chunks, model, tokens, tool calls, output, and errors.
Add retries with backoff on 429 and 5xx, a per-run token budget cap, and visible failed runs rather than silent drops.
Put all secrets in .env, ship .env.example, and never commit credentials.
Store all data locally by default and make CSV export straightforward.
Include clear empty, loading, success, and recoverable error states in a plain server-rendered run dashboard.
Write focused tests for retrieval, one tool call, and one end-to-end happy path.
Create a README with setup, the agent config schema, how to add a tool, data location, and cost notes.
Do not add accounts, billing, telemetry, a visual builder, or a connector marketplace.
Deliberately leave out multi-tenant workspaces and team permissions.
Deliberately leave out one-click OAuth for dozens of third-party apps.
Finish by running the tests and listing the exact commands used.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.