npm package: @francisco-donadio/specops
Description: Installable AI Functional Analyst agent for repositories, IDEs, and coding assistants.
Author: Francisco Donadio
Latest version: 0.3.1

# Specops

Specops is a CLI + MCP tool that turns product requests into structured analysis and ticket drafts, then creates tickets in GitHub, Jira, Linear, or Notion.

## Install

Homebrew:

```bash
brew install francisco-donadio/tap/specops
```

npm global:

```bash
npm install -g @francisco-donadio/specops
```

npx (no install):

```bash
npx @francisco-donadio/specops --help
```

More install and upgrade paths: `docs/install-upgrade.md`.

Architecture overview: `docs/how-specops-works.md`.

## Quick Setup

Create config:

```bash
specops init-config
```

Run guided setup:

```bash
specops setup
```

Run environment checks:

```bash
specops doctor --fix-hints
```

Check installed binary details:

```bash
specops version
```

## LLM Providers

Supported:

- OpenAI
- Anthropic (Claude)
- Gemini

Environment-based selection example:

```bash
export SPECOPS_LLM_PROVIDER=openai
export OPENAI_API_KEY=...
export FA_AGENT_MODEL=gpt-4.1-mini
```

Provider keys:

- `OPENAI_API_KEY`
- `ANTHROPIC_API_KEY`
- `GOOGLE_API_KEY`

You can also set these in `specops.config.json` under `llm`:

- `llm.provider`
- `llm.model`
- `llm.apiKeyEnv`

## Core Commands

Analyze:

```bash
specops analyze-feature '{"feature":{"title":"Checkout Revamp","problem":"Drop-off is high after shipping","users":["buyers"]}}'
```

Draft tickets:

```bash
specops draft-tickets "draft tickets for improving onboarding conversion"
```

Suggest business actions:

```bash
specops suggest-business "suggest improvements for activation funnel"
```

Collect context:

```bash
specops collect-context '{"sources":["repo","git","notion"],"query":"checkout"}'
```

Create tickets (dry-run):

```bash
specops 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 Targets

- GitHub: `owner/repo` or `{ "owner": "...", "repo": "..." }`
- Jira: `PROJECT_KEY` or `PROJECT_KEY:BOARD_ID` or `{ "projectKey": "...", "boardId": "..." }`
- Linear: `TEAM_ID` or `TEAM_ID:PROJECT_ID` or `{ "teamId": "...", "projectId": "..." }`
- Notion: `dataSourceId` or `{ "dataSourceId": "..." }`

## Context Management

List/clear persisted context:

```bash
specops context list
specops context list checkout
specops context clear --yes
```

Interactive TUI:

```bash
specops context tui
```

Guide: `docs/context-tui.md`.

## Slack Integration

Run Slack server:

```bash
export SLACK_SIGNING_SECRET=...
export SLACK_BOT_TOKEN=xoxb-...
specops serve-slack
```

Endpoints:

- `POST /slack/events`
- `POST /slack/command`

Ticket creation in Slack uses confirmation flow: run preview first, then reply `confirm create` within 10 minutes for live execution.

Guide: `docs/slack-setup.md`.

## MCP

Generate manifest:

```bash
specops mcp-manifest
```

Run MCP server:

```bash
specops serve-mcp
```

## Security Notes

- Keep `.env` owner-only: `chmod 600 .env`
- Do not commit API keys/tokens
- Enable safe debug logs only when needed: `SPECOPS_SAFE_DEBUG=1`

## License

MIT