Automate the loop end to end

The two endpoints

Both use the same board key as MCP (the fq_... key from your board admin page) as a bearer header.

• GET /api/v1/top-requests?limit=N returns the board's requests ranked by current demand as JSON. Default 5, max 20. Each request is scored by votes plus half-weight comments, with the score fading as the request ages over about 90 days. Newer requests win ties.
• GET /api/v1/top-spec picks the current top-ranked request that is not done and returns a markdown implementation spec for it. Use ?format=json if you want the request metadata alongside the spec text.

Fetching the top spec is one command:

curl -fsS \
  -H "Authorization: Bearer $FEATQ_MCP_KEY" \
  "https://featq.com/api/v1/top-spec" \
  -o spec.md

Weekly GitHub Action

Save this as .github/workflows/featq-ship.yml in your repo. Add FEATQ_MCP_KEY and ANTHROPIC_API_KEY as repository secrets (Settings, then Secrets and variables, then Actions). The secrets live in your repo, not with FeatQ. The example uses Claude Code, but any agent CLI that can read a markdown spec and edit files works the same way.

name: Ship the top feature request

on:
  schedule:
    - cron: "0 9 * * 1"   # Mondays 09:00 UTC
  workflow_dispatch: {}    # allow manual runs

jobs:
  ship-top-request:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4

      - name: Fetch the top-ranked spec from FeatQ
        run: |
          curl -fsS \
            -H "Authorization: Bearer ${{ secrets.FEATQ_MCP_KEY }}" \
            "https://featq.com/api/v1/top-spec" \
            -o spec.md

      - name: Install Claude Code
        run: npm install -g @anthropic-ai/claude-code

      - name: Implement the spec on a branch
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          git config user.name "featq-automation"
          git config user.email "[email protected]"
          git checkout -b featq/top-request-$(date +%Y%m%d)
          claude -p "Read spec.md in the repo root. Implement the feature it \
            describes. Verify the spec's assumptions against the actual code, \
            run the project's checks, and commit the result. Do not commit \
            spec.md itself." \
            --allowedTools "Bash,Read,Edit,Write"

      - name: Open the pull request
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
        run: |
          git push -u origin HEAD
          gh pr create \
            --title "FeatQ: implement the top-ranked request" \
            --body "Implements the current top-ranked request from our FeatQ board. Built from the spec at featq.com/api/v1/top-spec. Review before merging."

Every Monday the workflow pulls the top-ranked spec, has the agent implement it on a branch, and opens a PR. Merge it, close it, or edit it: nothing lands without your review. After merging, have your agent call update_request_status with status done so the changelog and voter emails go out.

Same recipe on a VPS

No GitHub Actions needed. A cron entry and a shell script do the same job on any server where your repo, an agent CLI, and the gh CLI are available.

# crontab -e
# Mondays 09:00, server time
0 9 * * 1 /srv/myapp/featq-ship.sh >> /var/log/featq-ship.log 2>&1

#!/usr/bin/env bash
# /srv/myapp/featq-ship.sh
set -euo pipefail
cd /srv/myapp

# FEATQ_MCP_KEY and ANTHROPIC_API_KEY come from the server's
# environment (for example an env file readable only by this user).

git fetch origin && git checkout main && git pull --ff-only

curl -fsS \
  -H "Authorization: Bearer $FEATQ_MCP_KEY" \
  "https://featq.com/api/v1/top-spec" \
  -o spec.md

git checkout -b "featq/top-request-$(date +%Y%m%d)"

claude -p "Read spec.md in the repo root. Implement the feature it describes. \
  Verify the spec against the actual code, run the project's checks, and \
  commit the result. Do not commit spec.md itself." \
  --allowedTools "Bash,Read,Edit,Write"

git push -u origin HEAD
gh pr create \
  --title "FeatQ: implement the top-ranked request" \
  --body "Implements the current top-ranked request from our FeatQ board. Review before merging."

Keep the keys in the server's environment, readable only by the user that runs the job. Make the script executable with chmod +x featq-ship.sh.

In-session agents: get_ranked_requests

When you are working interactively instead of on a schedule, the MCP tool get_ranked_requests gives your agent the same ranking the v1 endpoints use. Ask your agent something like "what should we build next?" and it can call:

get_ranked_requests({ limit: 5 })

The response includes each request's score and a plain-English description of the ranking, so the agent can explain its pick. From there it can call get_request for full context, generate_spec for a draft, and update_request_status when the work ships. Connection setup is on the MCP page and in the MCP reference.

Honest limits