Metadata-Version: 2.5
Name: specky
Version: 0.3.0
Summary: Cross-agent plugin that generates and maintains functional documentation in place, with a SQLite-backed searchable history and an HTML viewer for non-technical stakeholders.
Project-URL: Homepage, https://github.com/danyyacoub/specky
Project-URL: Documentation, https://github.com/danyyacoub/specky/blob/main/specs/MODULES.md
Project-URL: Changelog, https://github.com/danyyacoub/specky/blob/main/CHANGELOG.md
Project-URL: Repository, https://github.com/danyyacoub/specky
Project-URL: Issues, https://github.com/danyyacoub/specky/issues
Author-email: dany <dany.yacoub@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude-code,claude-code-plugin,documentation,fts5,functional-specs,git-hooks,mcp,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.11
Requires-Dist: anthropic>=0.40.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: markdown>=3.6
Requires-Dist: mcp>=2.0.0
Provides-Extra: bedrock
Requires-Dist: anthropic[bedrock]; extra == 'bedrock'
Description-Content-Type: text/markdown

# specky

Functional docs that keep up with your code.

Most code is now written by AI. The people who own it still need a clear view of what it does:
which features exist, how each workflow runs, and how the edge cases are handled. Reading the code
is no longer a practical way to get that view.

specky keeps a functional doc of your codebase in sync with the code. It writes plain-markdown docs
into your repo, updates them on every commit, and indexes them for three audiences:

- **AI agents** look up what a feature does and which rules it must keep before they change it.
- **Developers** review behaviour and edge cases in the PR, next to the code that changed.
- **Product managers** browse a searchable site of features and recent changes with no code to
  read, and use an agent to explore them or draft proposals.

Because every feature is indexed, finding one is a search, not a crawl through the code. That
work can run on a lower-cost model, which keeps your smartest model on the hard development tasks.

It ships as a Claude Code plugin plus a CLI. Other agents can use it through its MCP server and
skills; see [agent setup][agents].

## Features

### Docs that follow your commits

A git hook documents each commit. It writes a short history note, updates the feature doc the
commit touched, and commits both as a follow-up. Amends and rebases are handled.

![A commit and the doc update specky made for it][shot-commits]

### Any feature documented on demand

`specky document "the refund flow"` has a model search and read the code for that one feature. It
then writes `specs/billing/refund-flow.md`. Running it again updates the doc in place.

![specky document writing a feature doc][shot-document]

### A searchable docs site

`specky render-html` builds a static site that non-engineers can browse, with no server or build
step. It has full-text search over docs and history, tag filters, diagrams, glossary tooltips and
stale-doc badges. Its home page shows recent changes.

![The docs site][shot-site]

### Spec Assistant

`specky serve` adds a chat panel to the site. It answers from the docs and cites them. It can also
draft a spec change step by step: scope, impact, acceptance tests, then the final text.

To share it with your team, deploy it on a server with a login and its own models: see
[Deploy the Spec Assistant](#deploy-the-spec-assistant).

![The Spec Assistant answering a question][shot-assistant]

### A CI gate against doc drift

`specky check` fails a PR that changes code without updating the doc that describes it. It runs
offline and needs no API key. It also lists every number, formula or glossary term a doc in the PR
stopped stating, so a rewrite can't quietly drop a threshold. `specky lint` checks the docs as a
set: terms the glossary doesn't define, tags outside the vocabulary, and numbers two docs disagree
on.

![specky check failing a branch that skipped its doc update][shot-check]

### Docs your agent reads first

An MCP server and skills let Claude Code and other agents answer "what does X do?" from the docs
before reading code. The Claude Code plugin also has a slash command for each CLI workflow, such as
`/specky:check`, `/specky:lint`, `/specky:doctor` and `/specky:verify-migration`. Each one runs the
command and explains the result.

![Claude Code answering from specky's docs][shot-agent]

### Lower-cost models for doc work

Looking up and writing docs doesn't need your strongest model. In Claude Code, set
`[skills] model = "haiku"` in `specky.toml`. specky's skills then hand their lookups and writing to
a subagent on that model, and your session stays on the model you chose for development. Other
agents have their own way to do this; see [agent setup][agents]. For the CLI and the git hooks,
`[ai] <task>_model` sends each kind of call (commit summaries, classification, doc writing, tags,
chat) to its own model.

specky can also import existing docs (`specky adopt`), or check that a rewritten migration lost no
facts (`specky adopt --verify`). It can export docs to PDF or Confluence, summarise a PR's doc
changes, and scaffold tests from a doc's acceptance-test table.

## How it works

1. **Docs live in your repo as markdown**: `specs/<domain>/<topic>.md` for features and workflows,
   and `specs/history/` for commits. A branch's commits share one entry named for the branch, so
   "wip" and "fix typo" don't each get a page. You review and version them like code.
2. **Writing calls your AI provider.** Either the coding agent you already use (Claude Code,
   Codex, Gemini CLI, opencode, Kiro, Cursor Agent or Devin CLI), on its default model or one you name, any
   OpenAI-compatible endpoint, or Claude on Amazon Bedrock (install `specky[bedrock]`; credentials
   come from your AWS config). Only these commands call it: the commit hooks, `sync`,
   `document`, `tag` and the Spec Assistant. They send the diff, code or docs they are working on.
   Keys stay in environment variables.
3. **Reading is offline.** `specky index` builds a SQLite full-text index of the docs and git log
   in `.specky/`, which is gitignored. Search, the site, `check` and the MCP server all read it.

## Install

You need git, Python 3.11+ and [uv][uv], on macOS or Linux. On Windows, use WSL.

```bash
uv tool install specky                            # the CLI
claude plugin marketplace add danyyacoub/specky   # the Claude Code plugin
claude plugin install specky@specky
```

## Set up

In the repo you want documented, run `/specky:setup` in Claude Code. It picks a provider and the
model its skills run on, installs the git hooks and builds the first index. To do the same from a
plain terminal:

```bash
specky init               # choose a provider; writes specky.toml (gitignored)
specky install-git-hook   # document every commit from now on
specky index
```

Next, document a first feature with `specky document "<feature>"`, then open the site with
`/specky:launch-viewer`. If the repo already has docs, preview importing them with
`specky adopt --dry-run`.

The plugin does nothing in a repo until it has a `specky.toml`.

### Other AI agents

The Claude Code plugin wires everything up for you. With other agents, you add specky's MCP server
and copy in its skills yourself. [Agent setup][agents] covers each supported agent.

### CI check

Save this as `.github/workflows/docs.yml`:

```yaml
on:
  pull_request:
  push:
    branches: [main]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with: { fetch-depth: 0 }
      - uses: astral-sh/setup-uv@v5
      - run: uv tool install specky
      - run: specky index && specky check --base "$BASE"
        env:
          BASE: ${{ github.event.pull_request.base.sha || github.event.before || 'HEAD~1' }}
```

### Deploy the Spec Assistant

`specky serve` runs in a container with no `specky.toml`: that file is gitignored, so the image
never has one, and the server's settings come from its environment instead.

**The image.** It needs git and the repo's history, because the index is built from `git log`.
Build the index and the site into the image, then serve on every interface:

```dockerfile
FROM python:3.12-slim
RUN apt-get update && apt-get install -y --no-install-recommends git \
 && rm -rf /var/lib/apt/lists/*
RUN pip install uv && uv tool install 'specky[bedrock]'   # plain `specky` if you don't use Bedrock
ENV PATH="/root/.local/bin:$PATH"
COPY . /repo
WORKDIR /repo
RUN specky index && specky render-html
CMD ["specky", "serve", "--host", "0.0.0.0"]
```

Copy `.git` in (don't `.dockerignore` it). New docs reach the server when the image is rebuilt.

**The login.** Set `SPECKY_AUTH_USERNAME` and `SPECKY_AUTH_PASSWORD`. Every page and API call then
asks for that login, so put the server behind HTTPS.

**Agents.** The server also answers MCP at `/mcp`, behind the same login. It serves the same tools
as `specky-mcp` (`search_docs`, `read_doc`, `get_graph`, `commits_for_doc` and the rest), answered
from the server's copy of the repo. An agent can then use the docs as a knowledge graph with no
checkout and no local install:

```bash
claude mcp add --transport http specky-docs https://docs.example.com/mcp \
  --header "Authorization: Basic $(printf '%s' "$SPECKY_USER:$SPECKY_PASS" | base64)"
```

Any MCP host that can send a header on a Streamable HTTP server works the same way. If
`[serve] token` is set, send `X-Specky-Token` as well.

**The models.** `SPECKY_AI_<KEY>` sets `[ai] <key>`. `SPECKY_AI_PROVIDER` makes the environment the
whole `[ai]` table, so nothing from a local config leaks in. `SPECKY_AI_CHAT_MODEL` and
`SPECKY_AI_DRAFT_MODEL` choose the models for answers and for drafts. Use an API provider: the
`agent` provider needs a coding agent logged in on the machine.

With Claude on Amazon Bedrock, the server needs no key at all:

```bash
SPECKY_AI_PROVIDER=bedrock
SPECKY_AI_MODEL=anthropic.claude-haiku-4-5         # answers
SPECKY_AI_DRAFT_MODEL=anthropic.claude-sonnet-5    # drafts, on a stronger model
SPECKY_AI_AWS_REGION=us-east-1
```

The AWS SDK finds the credentials itself, and specky never stores them:

| Where it runs | Credential |
|---|---|
| ECS or Fargate | the task role on the task definition |
| EKS | a role linked to the pod's service account (Pod Identity or IRSA) |
| EC2 | the instance profile |
| Outside AWS | `AWS_ACCESS_KEY_ID` and `AWS_SECRET_ACCESS_KEY` as platform secrets, or a mounted profile named by `SPECKY_AI_AWS_PROFILE` |

In the Bedrock console, enable the models you named in that region, and allow the role to call
them. With an OpenAI-compatible API instead:

```bash
SPECKY_AI_PROVIDER=openai-compatible
SPECKY_AI_BASE_URL=https://api.deepseek.com/v1
SPECKY_AI_MODEL=deepseek-chat
SPECKY_AI_DRAFT_MODEL=deepseek-reasoner
SPECKY_AI_API_KEY_ENV=DEEPSEEK_API_KEY             # the name of the variable holding the key
DEEPSEEK_API_KEY=…                                 # a platform secret
```

Run `specky doctor` in the container to see what's in effect: the provider, where it came from,
and for Bedrock whether the AWS SDK is installed and a region set. It makes no AI call, so
credentials and model access are first tested by the first question asked in the panel.

### Update and uninstall

```bash
uv tool upgrade specky
claude plugin update specky@specky
```

To pause the hooks, set `SPECKY_DISABLE_HOOK=1`. To remove them, delete the `post-commit`,
`post-merge` and `post-rewrite` hooks that call `specky commit-doc`. Then run
`claude plugin uninstall specky@specky` and `uv tool uninstall specky`.

## Learn more

- `specky --help` lists every command and flag.
- [The full docs][modules] cover every feature and setting. specky wrote them from its own code.
- [CHANGELOG][changelog]
- Contributing: from a checkout, run `uv tool install --editable .`, then
  `claude plugin marketplace add "$PWD"` and `claude plugin install specky@specky`. The plugin then
  loads straight from your checkout. Tests and scripts are in [AGENTS.md][agents-md].

MIT licensed.

[agents]: https://github.com/danyyacoub/specky/blob/main/integrations/README.md
[uv]: https://docs.astral.sh/uv/
[modules]: https://github.com/danyyacoub/specky/blob/main/specs/MODULES.md
[changelog]: https://github.com/danyyacoub/specky/blob/main/CHANGELOG.md
[agents-md]: https://github.com/danyyacoub/specky/blob/main/AGENTS.md
[shot-commits]: https://raw.githubusercontent.com/danyyacoub/specky/main/assets/screenshots/commit-docs.png
[shot-document]: https://raw.githubusercontent.com/danyyacoub/specky/main/assets/screenshots/document.png
[shot-site]: https://raw.githubusercontent.com/danyyacoub/specky/main/assets/screenshots/site.png
[shot-assistant]: https://raw.githubusercontent.com/danyyacoub/specky/main/assets/screenshots/assistant.png
[shot-check]: https://raw.githubusercontent.com/danyyacoub/specky/main/assets/screenshots/check.png
[shot-agent]: https://raw.githubusercontent.com/danyyacoub/specky/main/assets/screenshots/agent.png
