Functional Analyst Agent

An installable AI agent that works as a Functional Analyst across repositories, IDE workflows, and AI coding assistants.

Why this project

Engineering teams usually start coding before requirements are clear. This agent adds product/functional analysis directly in the developer workflow, so teams can:

• Create ticket drafts with business context
• Analyze feature requests with risks and acceptance criteria
• Suggest business improvements tied to product outcomes

MVP scope

The current build supports:

• Feature analysis from structured JSON
• Context ingestion from repository docs and Notion
• Context ingestion from repository docs, links, git diff, Notion, GitHub issues, Jira issues, and Linear issues
• Query-aware context ranking with token-budgeted fact selection and source citations
• Ticket drafting with default status Backlog
• Ticket creation across providers: GitHub, Jira, Linear, Notion (database entries)
• Provider reliability controls for ticket creation: retries on transient failures, idempotency markers, and partial-failure reporting
• Dual target mode (simple targetRef or provider-specific target object)
• Internal prompt orchestration to generate analysis/tickets/suggestions from user requests
• MCP manifest generation for assistant/IDE integration
• Slack HTTP integration for slash-command and mention workflows

Project structure

src/
  adapters/         # Markdown formatting helpers
  context/          # Context source implementations
  core/             # Functional analyst logic and domain types
  providers/        # GitHub/Jira/Linear/Notion ticket providers
  integrations/     # MCP integration helpers
  index.ts          # CLI entrypoint
docs/
  roadmap.md        # Product roadmap and evolution plan
  how-specops-works.md # End-to-end product architecture and flow
  slack-setup.md    # Slack app setup and confirmation flow
  install-upgrade.md # Install/upgrade paths and conflict troubleshooting

Quick start

npm install
npm run build
npm run start -- mcp-manifest
npm test

Install via Homebrew

brew install francisco-donadio/tap/specops

See docs/homebrew-release.md for release automation details.

Install via npm (global)

npm install -g @francisco-donadio/specops

Run via npx (no install)

npx @francisco-donadio/specops --help

Run from source

git clone https://github.com/francisco-donadio/specops.git
cd specops
npm install
npm run build
npm run dev -- --help

Full install/upgrade guide: docs/install-upgrade.md.

Initialize config

npm run dev -- init-config

This creates specops.config.json in your current directory.

Run interactive setup wizard:

npm run dev -- setup

Run a basic health check:

npm run dev -- doctor

Show installed version details:

specops version

Launch readiness checklist: docs/launch-readiness-checklist.md.

Show setup fix hints for missing checks:

npm run dev -- doctor --fix-hints

doctor now includes a lightweight secret scan over common source/docs files and checks .env permissions.

Manage .env values from CLI:

npm run dev -- env set OPENAI_API_KEY sk-...
npm run dev -- env list
npm run dev -- env unset OPENAI_API_KEY

Security notes:

• Keep .env owner-only (chmod 600 .env)
• Do not commit .env or any tokens in source/docs
• Enable redacted debug logs only when needed: export SPECOPS_SAFE_DEBUG=1

Run Slack integration server (for Slack Events + slash command endpoints):

export SLACK_SIGNING_SECRET=...
export SLACK_BOT_TOKEN=xoxb-...
npm run dev -- serve-slack

Server endpoints:

• POST /slack/events (Events API, app mentions)
• POST /slack/command (slash command request URL)

Full setup guide: docs/slack-setup.md.

Slack ticket creation safety flow:

• Creation requests run in dry-run first.
• Specops asks for explicit confirmation.
• Reply confirm create within 10 minutes to execute the same request live.

Inspect and manage persisted context:

npm run dev -- context list
npm run dev -- context list checkout
npm run dev -- context clear --yes

For multi-repo projects (frontend/backend), set the same contextStore.path and contextStore.project in each repo config so they share one project memory.

Generate provider-specific quickstart commands:

npm run dev -- quickstart --provider=notion

Local examples

Input format rule: specops <command> <input> where <input> can be JSON, natural text, or links (for supported commands).

Context persistence: Specops stores project context in a local SQLite database (default: .specops/context.db) and reuses relevant entries in future runs.

Context budget tuning (optional):

export SPECOPS_CONTEXT_TOKEN_BUDGET=900
export SPECOPS_CONTEXT_MAX_FACTS=15

Natural language (no JSON required):

specops "analyze checkout drop-off for buyers"
specops "draft tickets for improving onboarding using https://example.com/spec"
specops "create tickets in notion for this proposal https://example.com/proposal"

Analyze a feature:

npm run dev -- analyze-feature '{"feature":{"title":"Checkout Revamp","problem":"Drop-off is high after shipping step","users":["buyers"],"kpis":["conversion_rate","checkout_time"]}}'

Draft tickets from a feature:

npm run dev -- draft-tickets '{"feature":{"title":"Checkout Revamp","problem":"Drop-off is high after shipping step","users":["buyers"]}}'

Business suggestions:

npm run dev -- suggest-business "checkout roadmap"

Collect context from repo + Notion:

npm run dev -- collect-context '{"sources":["repo","notion"],"query":"checkout"}'

Collect context from repo docs + git diff + Notion:

npm run dev -- collect-context '{"sources":["repo","git","notion"],"query":"checkout"}'

Collect context including external links and GitHub issues:

npm run dev -- collect-context '{"sources":["repo","link","github"],"query":"checkout","links":["https://example.com/spec"],"githubRepo":"acme/web-app"}'

Collect context from Jira and Linear issue history:

npm run dev -- collect-context '{"sources":["jira","linear"],"query":"checkout incident","jiraProject":"PAY","linearTeamId":"ENG"}'

Create Notion tickets (database entries) in dry-run:

npm run dev -- create-tickets '{"provider":"notion","targetRef":"f336d0bc-b841-465b-8045-024475c079dd","tickets":[{"title":"[FA] Checkout Revamp","description":"Improve checkout flow and reduce drop-off.","labels":["product"],"priority":"medium","status":"Backlog"}],"dryRun":true}'

Create GitHub tickets using provider-specific object:

npm run dev -- create-tickets '{"provider":"github","target":{"owner":"acme","repo":"web-app"},"tickets":[{"title":"[FA] Checkout Revamp","description":"Improve checkout flow and reduce drop-off.","labels":["product"],"priority":"medium","status":"Backlog"}],"dryRun":true}'

Live create-tickets responses include created and optional failed arrays. On transient provider errors, Specops retries automatically; idempotency markers are added so reruns can recover previously created tickets instead of duplicating them.

Provider target formats

Both formats are supported:

• Simple string targetRef
• Provider-specific object target

Examples:

• GitHub
  • targetRef: owner/repo
  • target: {"owner":"acme","repo":"web-app"}
• Jira
  • targetRef: PROJECT_KEY or PROJECT_KEY:BOARD_ID
  • target: {"projectKey":"PAY","boardId":"42"}
• Linear
  • targetRef: TEAM_ID or TEAM_ID:PROJECT_ID
  • target: {"teamId":"ENG","projectId":"proj_123"}
• Notion
  • targetRef: <dataSourceId>
  • target: {"dataSourceId":"..."}

If both are provided, target wins.

Integration patterns

1. Repository mode

• Run as CLI from CI or local scripts to generate analysis artifacts.

2. AI assistant mode

• Use mcp-manifest output to wire this project as an MCP server in tools like Cursor/Cline-compatible environments.

3. IDE mode

• Expose slash commands or tasks that invoke specops commands and store outputs in docs/ or issue systems.

Internal prompts

Prompt templates are internal implementation details. End users call high-level commands (analyze-feature, draft-tickets, suggest-business) and the agent orchestrates prompts internally when LLM credentials are available.

Suggested next milestones

• Add real MCP server transport and tool handlers (currently CLI-compatible mode)
• Add OpenAI/Anthropic structured-output adapters for template execution
• Add integration tests with mocked provider APIs
• Add confidence-weighted follow-up question generation when required context is missing
• Add board-sharing UX helpers for each provider

License

MIT