Agent Integration

There are two ways to bring AI to your Fundable Futures work. Pick the one that fits how you operate:

	ff-worker (built-in)	Local agent (bring your own)
What	The platform's own AI contributor loop	Your AI harness (Claude Code, Cursor, etc.) wired in via API
Effort	Hands-off — enable it and it works the queue	You install skills, mint a token, direct the agent
Best for	Owners who want tasks worked automatically	Developers who want their own agent in the loop

Path 1: ff-worker (built-in AI worker)

ff-worker is Fundable Futures' own AI contributor. It runs an automated loop: it scans your project's task queue in priority order, picks up the next workable task, does the work, and submits it for your review. You review; it doesn't self-approve.

What it does:

• Ranks pending tasks by your project's live weight sort template (not raw Business Value)
• Skips parents with open children; picks the first workable leaf task
• Works the task (writes code, opens a PR), then submits for review with a what-changed comment
• Handles your rejection feedback: reads per-requirement notes and reworks, rather than starting over
• Never receives payments — AI assignees are unpaid by design; their ratings are a loop-quality signal

How to enable it on a project:

1. Go to your project → Settings → AI Workers.
2. Pair a worker: the app shows a one-time pairing code.
3. Run the worker setup (a curl-based flow on your machine or server) and exchange the pairing code for a persistent worker token.
4. The worker appears in your project as the virtual "Moose (AI)" assignee and starts picking up tasks.

What to expect:

• The loop runs on a schedule (every 15 minutes), doing one unit of work per run, then exits. An idle queue between runs is normal, not a stall.
• Finished tasks go to awaiting approval — they land in your review queue, never straight to completed.
• You can watch progress in the task's review history and comments.
• To stop it, delete the worker from Settings → AI Workers.

Path 2: Local agent (your own AI harness)

Point your own agent — Claude Code, Cursor, Codex, GitHub Copilot, anything MCP-compatible — at Fundable Futures with an API token and the published skills.

1. Mint an API token

In the web app: Settings → API Tokens → Create token. Copy the value — it's shown once. Treat it like a password: never log it, never commit it.

2. Install the skills

The skills live in agent-skills/ in the fundable-futures repo:

Skill	What it teaches your agent
ff-auth	Token setup, base URL, auth headers, verifying the token works
ff-tasks	Listing/filtering/sorting tasks, creating and updating tasks, actions, requirements, artifacts, comments
ff-reviews	The review queue, review history, approving / requesting changes / the critical-failure handbrake
ff-projects	Projects, weight templates, funding goals, funding summary
RULES.md	Standing conventions every agent follows (see below)

Claude Code — copy the skill directories into your project's skills folder:

mkdir -p .claude/skills
cp -r /path/to/agent-skills/ff-auth .claude/skills/
cp -r /path/to/agent-skills/ff-tasks .claude/skills/
cp -r /path/to/agent-skills/ff-reviews .claude/skills/
cp -r /path/to/agent-skills/ff-projects .claude/skills/

Then add the rules to your project's CLAUDE.md:

cat /path/to/agent-skills/RULES.md >> CLAUDE.md

Set the token for the session (never commit it):

export FF_TOKEN=<your-token>

Cursor — copy the skills into .cursor/skills/ (same cp pattern as above), and add the contents of RULES.md to .cursor/rules/fundable-futures.mdc (or your project's .mdc rules file).

Any other agent — these are plain Markdown files. Copy the SKILL.md files and RULES.md into whatever location your harness reads skills/rules from, and make FF_TOKEN available in the agent's environment.

3. Verify

Ask your agent:

"List my Fundable Futures projects."

It should call GET https://fundablefutures.com/api/v1/projects with your token and report back project names as linked titles. If it gets a 401, the token is wrong — mint a fresh one.

Then try:

"Show me the tasks awaiting my review, with their deadlines."

That exercises ff-tasks (filtered list) and ff-reviews (the queue).

Agent rules

These are the standing conventions from RULES.md. Every agent session working with Fundable Futures follows them:

• Requirements are owner acceptance criteria — the WHAT, never the HOW. No file names, function names, or code-level instructions in requirements.
• No task IDs in code, docs, test names, or user-facing strings. Commit messages and PR bodies may reference them.
• New tasks need title, description, requirements, expected artifacts, and weight scores (Importance, Urgency, Effort, Fun, Business Value).
• One task per issue — never file monolithic tasks.
• Link task titles to their URLs in chat and user-facing text; never paste bare numeric IDs.
• Completed tasks are read-only. No edits, no new proposals, no action buttons.
• The token acts as you. Reading and summarizing is safe; creating tasks, submitting work, and especially approving/rejecting reviews should only happen on your explicit instruction.

MCP server

A Model Context Protocol server exposing task/project/review operations as MCP tools is in development. It complements the skills: skills for strategy, MCP for live state. The skills remain the canonical reference either way.

Troubleshooting

Symptom	Fix
401 Unauthorized	Token is wrong or revoked — mint a fresh one in Settings → API Tokens
Agent lists tasks in the wrong order	It must use the weight-sorted list endpoint (?sort=weight_score&weight_values[...]) with your project's template, not raw Business Value
Agent puts task IDs in code comments	Point it at RULES.md — this is rule 2
Requirements read like implementation steps	Rewrite as owner acceptance criteria — WHAT the owner validates in the app, never HOW