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, and GitHub issues
• Ticket drafting with default status Backlog
• Ticket creation across providers: GitHub, Jira, Linear, Notion (database entries)
• 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

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

Quick start

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

Install via Homebrew

brew install francisco-donadio/tap/specops

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

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 setup fix hints for missing checks:

npm run dev -- doctor --fix-hints

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

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).

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"}'

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}'

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