Metadata-Version: 2.4
Name: agent-spec-vault
Version: 0.1.0
Summary: A lightweight global Markdown spec and decision vault for AI coding agents.
Author: xixifast
License-Expression: MIT
Project-URL: Homepage, https://github.com/xixifast/agent-spec-vault
Project-URL: Repository, https://github.com/xixifast/agent-spec-vault
Project-URL: Issues, https://github.com/xixifast/agent-spec-vault/issues
Keywords: ai-agents,specs,markdown,codex,knowledge-base
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Utilities
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Agent Spec Vault

`agent-spec-vault` is a tiny global Markdown vault for AI coding agents.

It stores durable specs, cross-repo contracts, and decisions in plain Markdown
under a user-level directory. It is intentionally not a task tracker, Kanban
board, daemon, hook system, or project management platform.

## Why

Coding agents often need historical context:

- previous product and architecture specs
- cross-repository contracts
- decisions and tradeoffs
- validation rules that should survive chat resets

Tools such as Beads and Backlog.md are great when you need task tracking. This
tool keeps the narrower part: Markdown-native, agent-readable specs and
decisions that are global rather than tied to one repository.

## Install

Recommended after the first PyPI release:

```bash
pipx install agent-spec-vault
specv init
```

Plain `pip` will also work inside a virtual environment:

```bash
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install agent-spec-vault
specv init
```

One-line installer:

```bash
curl -fsSL https://raw.githubusercontent.com/xixifast/agent-spec-vault/main/scripts/install.sh | bash
```

Before the first PyPI release, the installer falls back to the GitHub source
package automatically.

Without `pipx`, the installer creates a private virtual environment at
`~/.local/share/agent-spec-vault/venv` and links `specv` into `~/.local/bin`.
The equivalent manual commands are:

```bash
python3 -m venv ~/.local/share/agent-spec-vault/venv
~/.local/share/agent-spec-vault/venv/bin/python -m pip install --upgrade \
  agent-spec-vault
mkdir -p ~/.local/bin
ln -sf ~/.local/share/agent-spec-vault/venv/bin/specv ~/.local/bin/specv
~/.local/bin/specv init
```

Unreleased development builds can still be installed from GitHub:

```bash
pipx install git+https://github.com/xixifast/agent-spec-vault.git
```

For local development from a checkout:

```bash
python3 -m pip install -e .
```

Or run from a checkout without installing:

```bash
python3 -m specv --help
```

## Quick Start

```bash
specv init
specv new "Quality analysis display contract" \
  --repos lippi-smart-customer,aics-web-repos,lippi-dingagent-graph-engine \
  --tags quality-analysis,contract
specv decision "Use Markdown vault instead of Beads for historical specs" \
  --tags tooling,specs
specv list
specv search "quality analysis"
specv show spec-20260703-quality-analysis-display-contract
specv index --print
specv prime --repo lippi-smart-customer
```

Default vault location:

```text
~/.agents/spec-vault
```

Override it with:

```bash
SPECV_HOME=/path/to/vault specv list
specv --home /path/to/vault list
```

## Data Model

Everything is ordinary Markdown:

```text
~/.agents/spec-vault/
  README.md
  index.jsonl
  templates/
    spec.md
    decision.md
  specs/
    2026-07-03-quality-analysis-display-contract.md
  decisions/
    2026-07-03-use-markdown-vault.md
```

Each document has a small frontmatter block:

```md
---
id: spec-20260703-quality-analysis-display-contract
kind: spec
title: Quality analysis display contract
status: active
created: 2026-07-03
updated: 2026-07-03
repos:
  - lippi-smart-customer
  - aics-web-repos
tags:
  - quality-analysis
  - contract
---
```

`specv index` writes `index.jsonl`, a compact surface for scripts and agents.

## Commands

| Command | Purpose |
| --- | --- |
| `specv init` | Create the vault directories and templates |
| `specv new <title>` | Create a new spec |
| `specv decision <title>` | Create a decision note |
| `specv list` | List specs and decisions |
| `specv search <query>` | Search metadata and Markdown body |
| `specv show <id>` | Print one document |
| `specv index` | Regenerate `index.jsonl` |
| `specv prime` | Print an agent-friendly summary |
| `specv path` | Print the vault path |

## Suggested Agent Rule

Add a small rule to your global agent instructions:

```text
When a task needs historical specs, cross-repo contracts, or prior design
decisions, search ~/.agents/spec-vault first with specv search or rg. When asked
to preserve a durable spec or decision, write it there instead of creating an
ad hoc file in a business repository.
```

## Scope

This project does:

- global spec and decision storage
- Markdown-native files
- frontmatter metadata for repos, tags, status, and dates
- JSONL index generation
- agent-friendly summary output

This project does not:

- track task claim/close state
- manage dependencies or blockers
- run a daemon or hooks
- replace GitHub Issues, Beads, or Backlog.md
- write into business repositories by default

## Development

```bash
python3 -m unittest discover -s tests -p 'test_*.py'
python3 -m specv --home /tmp/specv-demo init
```

## License

MIT
