Skip to content

LLM Integration

FuncSpec is designed to work with AI coding agents and LLMs. This guide explains how to connect your LLM workflows to FuncSpec so agents can read specs, update progress, record their work, and stay aligned with your project requirements.

How It Works

The typical workflow:

  1. Agent reads the spec item it's working on via the API
  2. Agent reads agent instructions for project conventions and rules
  3. Agent does the work (writes code, creates PRs, etc.)
  4. Agent records its run and links commits back to the spec item
  5. Agent transitions implementation status as work progresses

FuncSpec provides a work package endpoint that bundles everything an agent needs in a single request — the spec item, its functional requirements, dependencies, review history, and codebase context.

Setting Up

1. Create an API Key

Go to Organization Settings → API Keys and create a key. You'll use this for all API calls.

2. Configure LLM Provider (Optional)

If you want FuncSpec's built-in AI features (review, improve, generate), configure your LLM provider:

  • Go to Organization Settings → LLM Configuration
  • Choose Anthropic or OpenAI
  • Paste your API key
  • Optionally set a specific model (defaults to the provider's best)

BYOK — Bring Your Own Key

FuncSpec never stores your prompts or data with the LLM provider. Your API key is used directly, and all requests are made server-side. You control your LLM costs.

3. Set Up Agent Instructions

Write project-specific instructions that your agents will follow. See the Agent Instructions guide for details.

The Work Package

The work package endpoint is the primary way agents interact with FuncSpec. It returns everything needed to work on a spec item:

curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/work_package/T-42"

The response includes:

Field Description
item The spec item (title, description, state, tags, priority)
functional_requirements Parent functional items this tech spec implements
dependencies Items this spec depends on
dependents Items that depend on this spec
siblings Other tech items under the same functional parent
review Latest AI review (score, verdict, findings)
agent_runs Previous agent runs against this item
linked_commits Git commits already linked to this item

Including Codebase Context

Add ?include_codebase=true to include relevant source files:

curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/work_package/T-42?include_codebase=true"

This gives agents the full picture: what to build, what already exists, and what's been done before.

Agent Workflow

Reading Specs

List items that need work:

# Items not yet started
funcspec items list --type tech --implementation-status not_started

# Items that failed review
funcspec items list --review-verdict major_gaps

# Search for specific functionality
funcspec search "authentication"

Or via the API:

# Get all tech items needing implementation
curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/spec/items?type=technical&implementation_status=not_started"

Updating Progress

As the agent works, it should update implementation status:

# Mark as in progress
curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"implementation_status": "in_progress"}' \
  "https://funcspec.net/api/v1/projects/my-project/spec/items/42/transition_implementation"

# Mark as implemented when done
curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"implementation_status": "implemented"}' \
  "https://funcspec.net/api/v1/projects/my-project/spec/items/42/transition_implementation"

Or with the CLI:

funcspec items update T-42 --implementation-status in_progress
funcspec items update T-42 --implementation-status implemented

Recording Agent Runs

After completing work, record the run for audit trail and analytics:

curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_key": "agent-session-abc123",
    "model": "claude-sonnet-4-20250514",
    "provider": "anthropic",
    "status": "completed",
    "input_tokens": 15000,
    "output_tokens": 3000,
    "cost": 0.12,
    "instruction_version": 3
  }' \
  "https://funcspec.net/api/v1/projects/my-project/work_package/T-42/record_run"

The instruction_version field tracks which version of agent instructions the agent was following, helping you correlate instruction changes with agent behavior.

Linking Commits

Link git commits to spec items for traceability:

curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sha": "abc123def456",
    "message": "Implement OAuth2 token refresh flow",
    "committed_at": "2026-03-31T18:30:00Z",
    "source": "github"
  }' \
  "https://funcspec.net/api/v1/projects/my-project/work_package/T-42/link_commit"

Built-in AI Operations

FuncSpec includes AI-powered operations you can trigger via API or CLI:

AI Review

Get an AI assessment of spec quality:

# Single item
funcspec ai review T-42

# All tech items (batch)
funcspec ai review-all

The review returns:

  • Score (0-100): Overall quality rating
  • Verdict: ready, needs_refinement, or major_gaps
  • Coverage map: Which aspects are well-specified vs missing
  • Findings: Specific issues with severity and suggestions

AI Improve

Get AI-suggested improvements:

# Propose improvements (shows diff, doesn't apply)
funcspec ai improve T-42

# In the CLI, you'll be prompted to accept or reject

Generate Tech Specs

Generate technical specifications from functional requirements:

funcspec ai generate F-15

This analyzes a functional item and proposes technical specs to implement it.

Code Audit

Audit code against spec requirements:

funcspec ai audit T-42

Cascade Analysis

When specs change, FuncSpec can analyze the ripple effects:

# Analyze impact of changing an item
curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"spec_item_id": 42, "reason": "API response format changed"}' \
  "https://funcspec.net/api/v1/projects/my-project/cascade/analyze"

# Check which items are stale
curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/cascade/dirty"

Implementation Plans

Group related work items into implementation plans:

# Create a plan
curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"plan": {"title": "OAuth2 Implementation", "description": "Implement OAuth2 auth flow"}}' \
  "https://funcspec.net/api/v1/projects/my-project/plans"

# Generate implementation prompts for the plan
curl -X POST -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/plans/1/generate_prompts"

# Get the generated prompts
curl -H "X-Api-Key: $FUNCSPEC_API_KEY" \
  "https://funcspec.net/api/v1/projects/my-project/prompts?plan_id=1"

Plans can also be created from cascade change reports, automatically populating the affected items.

Example: Full Agent Loop

Here's a complete example of an agent working through a spec item:

#!/bin/bash
API_KEY="your-api-key"
BASE="https://funcspec.net/api/v1/projects/my-project"
ITEM="T-42"

# 1. Get agent instructions
INSTRUCTIONS=$(curl -s "$BASE/agent_instructions?format=markdown")

# 2. Get the work package
WORK=$(curl -s -H "X-Api-Key: $API_KEY" \
  "$BASE/work_package/$ITEM?include_codebase=true")

# 3. Mark as in progress
curl -s -X POST -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"implementation_status": "in_progress"}' \
  "$BASE/spec/items/42/transition_implementation"

# 4. ... agent does the work ...

# 5. Link the commit
curl -s -X POST -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sha": "'$COMMIT_SHA'", "message": "'$COMMIT_MSG'"}' \
  "$BASE/work_package/$ITEM/link_commit"

# 6. Record the run
curl -s -X POST -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "session_key": "'$SESSION_ID'",
    "model": "claude-sonnet-4-20250514",
    "provider": "anthropic",
    "status": "completed",
    "input_tokens": '$INPUT_TOKENS',
    "output_tokens": '$OUTPUT_TOKENS'
  }' \
  "$BASE/work_package/$ITEM/record_run"

# 7. Mark as implemented
curl -s -X POST -H "X-Api-Key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"implementation_status": "implemented"}' \
  "$BASE/spec/items/42/transition_implementation"

Tips

Use Snapshots Before Batch Operations

Before running review-all or apply-all, create a snapshot. FuncSpec does this automatically for apply-all, but it's good practice for any bulk operation.

Check the Self-Documenting API

Hit GET /api/v1/docs for a complete machine-readable API reference, always in sync with the running server.

Rate Limits

API calls are limited by your plan. Check the X-RateLimit-Remaining header. Built-in AI operations also consume LLM tokens from your configured provider.