spec-agent 0.1.0__py3-none-any.whl

spec_agent/__init__.py

@@ -0,0 +1 @@
+# spec_agent package

spec_agent/agent.py

@@ -0,0 +1,174 @@
+from __future__ import annotations
+import json
+import os
+import anthropic
+from typing import Optional
+from spec_agent.config import Config
+from spec_agent.tools.wiki_read import read_wiki_file
+from spec_agent.tools.wiki_write import write_wiki_file
+from spec_agent.tools.wiki_search import search_wiki
+from spec_agent.tools.wiki_index import update_index
+
+TOOL_DEFINITIONS = [
+    {
+        "name": "classify_commit",
+        "description": (
+            "Classify the git commit(s) to determine what type of change was made "
+            "and extract key concepts for wiki linking. Call this first."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "diff": {"type": "string", "description": "The git diff content"},
+                "messages": {"type": "array", "items": {"type": "string"}, "description": "Commit messages"},
+                "repo": {"type": "string", "description": "Repository name"},
+            },
+            "required": ["diff", "messages", "repo"],
+        },
+    },
+    {
+        "name": "search_wiki",
+        "description": "Full-text search across the Obsidian vault to find related existing pages before writing.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "query": {"type": "string", "description": "Search terms"},
+                "limit": {"type": "integer", "default": 5},
+            },
+            "required": ["query"],
+        },
+    },
+    {
+        "name": "read_wiki_file",
+        "description": "Read an existing wiki file to understand its content before updating it.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Path relative to vault root, e.g. features/auth.md"},
+            },
+            "required": ["path"],
+        },
+    },
+    {
+        "name": "write_wiki_file",
+        "description": (
+            "Write a markdown file to the vault. Use mode='create' for new specs, "
+            "mode='update' to append a changelog entry to an existing spec."
+        ),
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "path": {"type": "string", "description": "Path relative to vault root, e.g. features/auth.md"},
+                "content": {"type": "string", "description": "Full markdown content (create) or changelog line(s) (update)"},
+                "mode": {"type": "string", "enum": ["create", "update"], "default": "create"},
+            },
+            "required": ["path", "content"],
+        },
+    },
+    {
+        "name": "update_index",
+        "description": "Append an entry to index.md — the master log. Call this after writing the spec file.",
+        "input_schema": {
+            "type": "object",
+            "properties": {
+                "date": {"type": "string", "description": "ISO date, e.g. 2026-04-07"},
+                "type": {"type": "string", "enum": ["feature", "bug", "refactor", "arch", "chore"]},
+                "title": {"type": "string"},
+                "project": {"type": "string"},
+                "path": {"type": "string", "description": "Vault path without .md, e.g. features/auth"},
+            },
+            "required": ["date", "type", "title", "project", "path"],
+        },
+    },
+]
+
+_SYSTEM_PROMPT = """You are a spec-writing agent. When given a git diff and commit messages, you:
+1. Call classify_commit to understand what changed.
+2. If type is "chore", stop — no spec needed.
+3. Search the wiki for related pages to understand existing context and find pages to link to.
+4. Read any highly relevant existing pages (especially if you might be updating them).
+5. Write or update the appropriate spec file using the right template:
+   - feature: Summary, Problem it solves, Implementation details, Files touched, Related [[wikilinks]], Open questions, Changelog
+   - bug: Root cause, Fix applied, Related [[wikilinks]], Changelog
+   - refactor: What changed, Why, Before/After key diff, Related [[wikilinks]]
+   - arch: Context, Decision, Consequences, Alternatives considered, Related [[wikilinks]]
+6. Call update_index with the new entry.
+
+Use [[wikilink]] syntax for related pages you found via search_wiki. Keep specs factual and grounded in the diff.
+"""
+
+
+def _dispatch_tool(name: str, tool_input: dict, vault_path: str) -> str:
+    if name == "classify_commit":
+        # The agent classifies via its own reasoning — this tool is a no-op
+        # (the agent fills in the classification itself and returns structured JSON)
+        return json.dumps({"status": "classified", "note": "Use your reasoning to determine type and concepts"})
+    elif name == "search_wiki":
+        results = search_wiki(vault_path, tool_input["query"], tool_input.get("limit", 5))
+        return json.dumps(results)
+    elif name == "read_wiki_file":
+        return json.dumps(read_wiki_file(vault_path, tool_input["path"]))
+    elif name == "write_wiki_file":
+        return json.dumps(write_wiki_file(
+            vault_path, tool_input["path"], tool_input["content"],
+            mode=tool_input.get("mode", "create")
+        ))
+    elif name == "update_index":
+        return json.dumps(update_index(vault_path, tool_input))
+    else:
+        return json.dumps({"error": f"Unknown tool: {name}"})
+
+
+def run_agent(
+    diff: str,
+    commit_messages: list[str],
+    repo_name: str,
+    branch: str,
+    cfg: Config,
+    _force_type: Optional[str] = None,  # test hook
+) -> None:
+    """Run the tool-using agent loop."""
+    # Test hook: skip API calls for known chore commits
+    if _force_type == "chore":
+        return
+
+    vault_path = str(cfg.vault_path)
+    client = anthropic.Anthropic(api_key=os.environ.get("ANTHROPIC_API_KEY"))
+
+    user_message = (
+        f"Repository: {repo_name}\n"
+        f"Branch: {branch}\n"
+        f"Commit messages:\n" + "\n".join(f"- {m}" for m in commit_messages) +
+        f"\n\nGit diff (truncated to 50,000 chars):\n```\n{diff[:50_000]}\n```"
+    )
+
+    messages = [{"role": "user", "content": user_message}]
+
+    while True:
+        response = client.messages.create(
+            model=cfg.model,
+            max_tokens=4096,
+            system=_SYSTEM_PROMPT,
+            tools=TOOL_DEFINITIONS,
+            messages=messages,
+        )
+
+        if response.stop_reason == "end_turn":
+            break
+
+        if response.stop_reason == "tool_use":
+            tool_results = []
+            for block in response.content:
+                if block.type == "tool_use":
+                    result = _dispatch_tool(block.name, block.input, vault_path)
+                    tool_results.append({
+                        "type": "tool_result",
+                        "tool_use_id": block.id,
+                        "content": result,
+                    })
+
+            messages.append({"role": "assistant", "content": response.content})
+            messages.append({"role": "user", "content": tool_results})
+        else:
+            # Unexpected stop reason — exit
+            break

spec_agent/cli.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+import os
+import subprocess
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+
+from spec_agent.agent import run_agent
+from spec_agent.config import Config, DEFAULT_CONFIG_PATH, load_config, save_config
+
+console = Console()
+
+_HOOK_SCRIPT = """\
+#!/usr/bin/env bash
+# spec-agent post-push hook
+# Fires after every git push. Passes diff via temp file to avoid shell escaping issues.
+
+set -euo pipefail
+
+REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")
+BRANCH=$(git rev-parse --abbrev-ref HEAD)
+
+# Get commit range pushed
+RANGE=$(git log @{u}..HEAD --format="%H" 2>/dev/null | tail -1)
+if [ -z "$RANGE" ]; then
+    exit 0
+fi
+
+COMMITS=$(git log @{u}..HEAD --format="%s" 2>/dev/null)
+MSG_LEN=$(echo "$COMMITS" | wc -c)
+MIN_CHARS=$(spec-agent config-get min_commit_chars 2>/dev/null || echo "50")
+
+if [ "$MSG_LEN" -lt "$MIN_CHARS" ]; then
+    exit 0
+fi
+
+# Write diff to a temp file to safely handle special characters
+DIFF_FILE=$(mktemp /tmp/spec-agent-diff.XXXXXX)
+git diff @{u}..HEAD 2>/dev/null | head -c 50000 > "$DIFF_FILE"
+
+spec-agent run \\
+    --repo "$REPO_NAME" \\
+    --branch "$BRANCH" \\
+    --messages "$COMMITS" \\
+    --diff-file "$DIFF_FILE" &
+
+exit 0
+"""
+
+
+@click.group()
+def cli():
+    """spec-agent: Auto-generate wiki specs from git commits."""
+
+
+@cli.command()
+@click.option("--repo", required=True, help="Repository name")
+@click.option("--branch", required=True, help="Branch that was pushed")
+@click.option("--messages", required=True, help="Newline-separated commit messages")
+@click.option("--diff-file", required=True, help="Path to temp file containing the git diff")
+@click.option("--config", default=str(DEFAULT_CONFIG_PATH), help="Path to config.yaml")
+def run(repo, branch, messages, diff_file, config):
+    """Run the spec agent (called by git hook)."""
+    cfg = load_config(Path(config))
+
+    if cfg.is_repo_ignored(repo):
+        console.print(f"[dim]spec-agent: skipping ignored repo {repo}[/dim]")
+        return
+
+    if cfg.is_branch_ignored(branch):
+        console.print(f"[dim]spec-agent: skipping ignored branch {branch}[/dim]")
+        return
+
+    commit_messages = [m.strip() for m in messages.strip().splitlines() if m.strip()]
+
+    if not cfg.vault_path.exists():
+        console.print(f"[yellow]spec-agent: vault not found at {cfg.vault_path}. Run: spec-agent init[/yellow]")
+        return
+
+    # Read diff from temp file then clean up
+    diff_path = Path(diff_file)
+    diff = diff_path.read_text(encoding="utf-8", errors="replace") if diff_path.exists() else ""
+    try:
+        diff_path.unlink(missing_ok=True)
+    except Exception:
+        pass
+
+    console.print(f"[cyan]spec-agent:[/cyan] processing push to {repo}/{branch}")
+    run_agent(
+        diff=diff,
+        commit_messages=commit_messages,
+        repo_name=repo,
+        branch=branch,
+        cfg=cfg,
+    )
+    console.print(f"[green]spec-agent:[/green] done — check {cfg.vault_path}")
+
+
+@cli.command()
+@click.option("--vault", required=True, help="Path to Obsidian vault directory")
+def init(vault):
+    """Initialize vault and write config file."""
+    vault_path = Path(vault).expanduser().resolve()
+    vault_path.mkdir(parents=True, exist_ok=True)
+
+    for folder in ["features", "bugs", "refactors", "concepts", "projects"]:
+        (vault_path / folder).mkdir(exist_ok=True)
+
+    index = vault_path / "index.md"
+    if not index.exists():
+        index.write_text(
+            "# Dev Wiki — Index\n\n"
+            "| Date | Type | Title | Project | Link |\n"
+            "|------|------|-------|---------|------|\n"
+        )
+
+    cfg = Config(vault_path=vault_path)
+    save_config(cfg)
+
+    console.print(f"[green]✓[/green] Vault created at {vault_path}")
+    console.print(f"[green]✓[/green] Config saved to {DEFAULT_CONFIG_PATH}")
+    console.print("\nNext step: [bold]spec-agent install-hook[/bold]")
+
+
+@cli.command("install-hook")
+def install_hook():
+    """Install global git post-push hook."""
+    hooks_dir = Path.home() / ".git-hooks"
+    hooks_dir.mkdir(exist_ok=True)
+
+    hook_path = hooks_dir / "post-push"
+    hook_path.write_text(_HOOK_SCRIPT)
+    hook_path.chmod(0o755)
+
+    subprocess.run(
+        ["git", "config", "--global", "core.hooksPath", str(hooks_dir)],
+        check=True
+    )
+
+    console.print(f"[green]✓[/green] Hook installed at {hook_path}")
+    console.print(f"[green]✓[/green] Global git hooksPath set to {hooks_dir}")
+    console.print("\n[bold]Done.[/bold] Every git push will now trigger spec-agent.")
+
+
+@cli.command("config-get")
+@click.argument("key")
+@click.option("--config", default=str(DEFAULT_CONFIG_PATH))
+def config_get(key, config):
+    """Get a config value (used by the hook script)."""
+    cfg = load_config(Path(config))
+    value = getattr(cfg, key, None)
+    if value is not None:
+        click.echo(str(value))
+    else:
+        sys.exit(1)

spec_agent/config.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+import fnmatch
+import yaml
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Optional
+
+DEFAULT_CONFIG_PATH = Path.home() / ".spec-agent" / "config.yaml"
+
+
+@dataclass
+class Config:
+    vault_path: Path
+    model: str = "claude-sonnet-4-6"
+    ignored_repos: list[str] = field(default_factory=list)
+    ignored_branches: list[str] = field(default_factory=lambda: ["dependabot/*", "renovate/*"])
+    min_commit_chars: int = 50
+
+    def is_repo_ignored(self, repo_name: str) -> bool:
+        return repo_name in self.ignored_repos
+
+    def is_branch_ignored(self, branch: str) -> bool:
+        return any(fnmatch.fnmatch(branch, pattern) for pattern in self.ignored_branches)
+
+
+def _defaults() -> dict:
+    return {
+        "vault_path": str(Path.home() / "Documents" / "dev-wiki"),
+        "model": "claude-sonnet-4-6",
+        "ignored_repos": [],
+        "ignored_branches": ["dependabot/*", "renovate/*"],
+        "min_commit_chars": 50,
+    }
+
+
+def load_config(config_path: Path = DEFAULT_CONFIG_PATH) -> Config:
+    data = _defaults()
+    if config_path.exists():
+        with open(config_path) as f:
+            data.update(yaml.safe_load(f) or {})
+    return Config(
+        vault_path=Path(data["vault_path"]),
+        model=data["model"],
+        ignored_repos=data.get("ignored_repos", []),
+        ignored_branches=data.get("ignored_branches", ["dependabot/*", "renovate/*"]),
+        min_commit_chars=int(data.get("min_commit_chars", 50)),
+    )
+
+
+def save_config(cfg: Config, config_path: Path = DEFAULT_CONFIG_PATH) -> None:
+    config_path.parent.mkdir(parents=True, exist_ok=True)
+    with open(config_path, "w") as f:
+        yaml.dump({
+            "vault_path": str(cfg.vault_path),
+            "model": cfg.model,
+            "ignored_repos": cfg.ignored_repos,
+            "ignored_branches": cfg.ignored_branches,
+            "min_commit_chars": cfg.min_commit_chars,
+        }, f, default_flow_style=False)

spec_agent/tools/__init__.py

@@ -0,0 +1 @@
+# spec_agent.tools package

spec_agent/tools/wiki_index.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+from pathlib import Path
+
+_HEADER = "# Dev Wiki — Index\n\n| Date | Type | Title | Project | Link |\n|------|------|-------|---------|------|\n"
+
+
+def update_index(vault_path: str, entry: dict) -> dict:
+    """
+    Append a row to index.md.
+
+    entry keys: date, type, title, project, path
+    path is the relative vault path without .md extension, e.g. "features/auth"
+
+    Returns: {"success": bool}
+    """
+    index_path = Path(vault_path) / "index.md"
+
+    if not index_path.exists():
+        index_path.write_text(_HEADER, encoding="utf-8")
+
+    row = (
+        f"| {entry['date']} "
+        f"| {entry['type']} "
+        f"| {entry['title']} "
+        f"| {entry['project']} "
+        f"| [[{entry['path']}]] |\n"
+    )
+
+    existing = index_path.read_text(encoding="utf-8")
+    index_path.write_text(existing + row, encoding="utf-8")
+    return {"success": True}

spec_agent/tools/wiki_read.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+from pathlib import Path
+import frontmatter
+
+
+def read_wiki_file(vault_path: str, relative_path: str) -> dict:
+    """
+    Read a markdown file from the vault.
+
+    Returns:
+        {
+            "exists": bool,
+            "content": str,          # body text without frontmatter
+            "frontmatter": dict,     # parsed YAML frontmatter (empty if none)
+            "last_updated": str,     # ISO date from frontmatter or ""
+        }
+    """
+    full_path = Path(vault_path) / relative_path
+    if not full_path.exists():
+        return {"exists": False, "content": "", "frontmatter": {}, "last_updated": ""}
+
+    raw = full_path.read_text(encoding="utf-8")
+
+    try:
+        post = frontmatter.loads(raw)
+        meta = dict(post.metadata)
+        body = post.content
+    except Exception:
+        meta = {}
+        body = raw
+
+    return {
+        "exists": True,
+        "content": body,
+        "frontmatter": meta,
+        "last_updated": str(meta.get("date", "")),
+    }

spec_agent/tools/wiki_search.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+import subprocess
+import shutil
+from pathlib import Path
+
+
+def _find_grep() -> str:
+    """Return path to system grep binary."""
+    for candidate in ["/usr/bin/grep", "/usr/local/bin/grep", "grep"]:
+        found = shutil.which(candidate)
+        if found:
+            return found
+    return "grep"
+
+
+def search_wiki(vault_path: str, query: str, limit: int = 5) -> list[dict]:
+    """
+    Full-text search across the vault using grep.
+
+    Returns:
+        [{"path": str, "title": str, "excerpt": str}]
+        path is relative to vault root.
+    """
+    vault = Path(vault_path)
+    results = []
+    seen_files: set[str] = set()
+
+    grep = _find_grep()
+    # -r recursive, -i case-insensitive, -n line numbers, --include only .md
+    # Output format: /path/file.md:linenum:matching line
+    cmd = [grep, "-r", "-i", "-n", "--include=*.md", query, str(vault)]
+
+    try:
+        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
+    except subprocess.TimeoutExpired:
+        return []
+
+    for line in proc.stdout.splitlines():
+        if len(results) >= limit:
+            break
+
+        # Parse: /path/to/file.md:line_num:matching line
+        parts = line.split(":", 2)
+        if len(parts) < 3:
+            continue
+        file_path, _, excerpt = parts
+
+        file_path = file_path.strip()
+        if file_path in seen_files or not file_path.endswith(".md"):
+            continue
+        seen_files.add(file_path)
+
+        try:
+            rel_path = str(Path(file_path).relative_to(vault))
+        except ValueError:
+            continue
+
+        # Read first heading as title
+        try:
+            first_line = Path(file_path).read_text(encoding="utf-8").splitlines()[0]
+            title = first_line.lstrip("#").strip() if first_line.startswith("#") else rel_path
+        except Exception:
+            title = rel_path
+
+        results.append({
+            "path": rel_path,
+            "title": title,
+            "excerpt": excerpt.strip()[:200],
+        })
+
+    return results

spec_agent/tools/wiki_write.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+from pathlib import Path
+
+
+def write_wiki_file(vault_path: str, relative_path: str, content: str, mode: str = "create") -> dict:
+    """
+    Write a markdown file to the vault.
+
+    Args:
+        vault_path: Absolute path to the Obsidian vault directory.
+        relative_path: Path relative to vault root, e.g. "features/auth.md".
+        content: In create mode: full file content. In update mode: changelog line(s) to append.
+        mode: "create" (overwrite) or "update" (append changelog entry).
+
+    Returns:
+        {"success": bool, "path": str, "error": str | None}
+    """
+    full_path = Path(vault_path) / relative_path
+    full_path.parent.mkdir(parents=True, exist_ok=True)
+
+    try:
+        if mode == "create":
+            full_path.write_text(content, encoding="utf-8")
+        elif mode == "update":
+            existing = full_path.read_text(encoding="utf-8") if full_path.exists() else ""
+            if "## Changelog" in existing:
+                # Append after the last changelog entry
+                updated = existing.rstrip() + "\n" + content + "\n"
+            else:
+                # Add a Changelog section
+                updated = existing.rstrip() + "\n\n## Changelog\n\n" + content + "\n"
+            full_path.write_text(updated, encoding="utf-8")
+        else:
+            return {"success": False, "path": relative_path, "error": f"Unknown mode: {mode}"}
+
+        return {"success": True, "path": relative_path, "error": None}
+    except Exception as e:
+        return {"success": False, "path": relative_path, "error": str(e)}

spec_agent-0.1.0.dist-info/METADATA

@@ -0,0 +1,390 @@
+Metadata-Version: 2.4
+Name: spec-agent
+Version: 0.1.0
+Summary: Auto-generate an Obsidian knowledge wiki from every git push, powered by Claude
+Author-email: Vishesh Chaitanya <visheshchaitanya@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/visheshchaitanya/spec-agent
+Project-URL: Repository, https://github.com/visheshchaitanya/spec-agent
+Project-URL: Issues, https://github.com/visheshchaitanya/spec-agent/issues
+Keywords: obsidian,wiki,git,documentation,anthropic,claude,ai,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Version Control :: Git
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.40.0
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: python-frontmatter>=1.1
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# spec-agent
+
+> Auto-generate an Obsidian knowledge wiki from every `git push` — powered by Claude.
+
+Every time you push code, **spec-agent** reads the diff, classifies the change, and writes a structured spec document into your [Obsidian](https://obsidian.md) vault. Over time, your vault becomes a living, visually-navigable graph of everything you've ever built.
+
+Inspired by [Andrej Karpathy's LLM Wiki pattern](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f): the LLM acts as a compiler (raw commits → structured wiki), not a retrieval engine. No RAG, no embeddings — just well-organized markdown with `[[wikilinks]]` that Obsidian renders as a knowledge graph.
+
+---
+
+## How It Works
+
+```
+git push
+  └── ~/.git-hooks/post-push        ← global hook, fires on every repo
+        └── spec-agent run           ← Python CLI
+              └── Claude (tool-use)  ← agentic loop
+                    ├── classify_commit
+                    ├── search_wiki       ← finds related existing pages
+                    ├── read_wiki_file    ← reads context before updating
+                    ├── write_wiki_file   ← creates or updates spec
+                    └── update_index      ← appends row to index.md
+```
+
+The agent:
+1. Classifies the commit type (`feature`, `bug`, `refactor`, `arch`, `chore`)
+2. Searches your vault for related pages to link to
+3. Writes an adaptive spec using the appropriate template
+4. Updates `index.md` — the master log that Claude reads at session start
+
+**Chore commits are skipped.** Bot branches (`dependabot/*`, `renovate/*`) are skipped. Tiny commits (below a configurable character threshold) are skipped.
+
+---
+
+## Features
+
+- **Zero friction** — fires automatically on every `git push`, no developer action needed
+- **Adaptive templates** — selects the right format based on commit type
+  - `feature` → full spec (summary, problem, implementation, files, open questions)
+  - `bug` → short report (root cause, fix applied)
+  - `refactor` → brief note (what changed, why, before/after)
+  - `arch` → ADR format (context, decision, consequences, alternatives)
+- **Accurate `[[wikilinks]]`** — searches vault for existing pages before writing, so links are real
+- **Living index** — `index.md` is a table of every spec ever written; share it with Claude at session start to give it full project memory
+- **Obsidian graph** — concepts referenced by many specs become visual hubs after 10+ specs
+- **Works on every repo** — one global hook installation covers all your projects
+
+---
+
+## Prerequisites
+
+- **Python 3.11+**
+- **An Anthropic API key** — [get one here](https://console.anthropic.com)
+- **Obsidian** — [download here](https://obsidian.md) (free)
+- **Git 2.9+** (for `core.hooksPath` support)
+
+---
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install spec-agent
+```
+
+### From source
+
+```bash
+git clone https://github.com/visheshchaitanya/spec-agent.git ~/.spec-agent
+pip install -e ~/.spec-agent
+```
+
+---
+
+## Setup
+
+### 1. Set your API key
+
+```bash
+export ANTHROPIC_API_KEY="sk-ant-..."
+```
+
+Add this to your shell profile (`~/.zshrc`, `~/.bashrc`, or `~/.zshenv`) to make it permanent:
+
+```bash
+echo 'export ANTHROPIC_API_KEY="sk-ant-..."' >> ~/.zshrc
+```
+
+### 2. Initialize your vault
+
+```bash
+spec-agent init --vault ~/Documents/dev-wiki
+```
+
+This creates the vault directory structure and writes a default `~/.spec-agent/config.yaml`.
+
+Then open `~/Documents/dev-wiki` as a vault in Obsidian (**File → Open vault as folder**).
+
+### 3. Install the global git hook
+
+```bash
+spec-agent install-hook
+```
+
+This creates `~/.git-hooks/post-push` and sets `git config --global core.hooksPath ~/.git-hooks`. The hook fires on every push in every repository on your machine.
+
+### 4. Push anything to test
+
+```bash
+cd ~/any-repo
+git push
+# → spec-agent fires in the background
+# → spec appears in ~/Documents/dev-wiki
+```
+
+---
+
+## Configuration
+
+Config lives at `~/.spec-agent/config.yaml`:
+
+```yaml
+vault_path: ~/Documents/dev-wiki
+model: claude-sonnet-4-6
+ignored_repos: []           # list of repo names to skip entirely
+ignored_branches:
+  - dependabot/*
+  - renovate/*
+min_commit_chars: 50        # skip pushes where total commit message length is below this
+```
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `vault_path` | `~/Documents/dev-wiki` | Absolute path to your Obsidian vault |
+| `model` | `claude-sonnet-4-6` | Anthropic model to use |
+| `ignored_repos` | `[]` | Exact repo names to never process |
+| `ignored_branches` | `[dependabot/*, renovate/*]` | Glob patterns — matching branches are skipped |
+| `min_commit_chars` | `50` | Skip pushes where total commit message length is below this (filters "wip", "fix typo") |
+
+---
+
+## Vault Structure
+
+```
+~/Documents/dev-wiki/
+├── index.md                    ← master log — give this to Claude at session start
+├── features/
+│   ├── alert-ingestion.md
+│   └── auth-system.md
+├── bugs/
+│   ├── fix-status-migration.md
+│   └── fix-null-pointer.md
+├── refactors/
+│   └── extract-auth-middleware.md
+├── concepts/                   ← auto-created graph hubs when first referenced
+│   ├── clickhouse.md
+│   └── jwt.md
+└── projects/
+    └── my-app.md
+```
+
+### index.md — your project memory
+
+`index.md` is a markdown table of every spec ever written:
+
+```markdown
+# Dev Wiki — Index
+
+| Date | Type | Title | Project | Link |
+|------|------|-------|---------|------|
+| 2026-04-07 | bug | Fix status migration | my-app | [[bugs/fix-status-migration]] |
+| 2026-04-05 | feature | Alert ingestion pipeline | my-app | [[features/alert-ingestion]] |
+```
+
+Paste the contents of `index.md` at the start of any Claude session — Claude immediately knows everything you've built across all projects.
+
+### Spec frontmatter
+
+Every generated spec has YAML frontmatter:
+
+```yaml
+---
+type: feature
+project: my-app
+date: 2026-04-07
+commit: a3f9c12
+status: shipped
+---
+```
+
+---
+
+## Giving Claude context at session start
+
+Paste this into your Claude session to give it full project memory:
+
+```
+Here is my dev wiki index — everything I've built:
+
+<paste contents of ~/Documents/dev-wiki/index.md>
+
+I'm working on <task>. Based on the index, what related specs should I look at?
+```
+
+Claude can then ask you to paste specific spec files for deeper context.
+
+---
+
+## CLI Reference
+
+```
+spec-agent [COMMAND] [OPTIONS]
+
+Commands:
+  run           Run the agent (called automatically by git hook)
+  init          Initialize vault directory and write config
+  install-hook  Install global git post-push hook
+  config-get    Read a config value (used internally by hook)
+```
+
+### `spec-agent run`
+
+```
+Options:
+  --repo TEXT        Repository name (required)
+  --branch TEXT      Branch that was pushed (required)
+  --messages TEXT    Newline-separated commit messages (required)
+  --diff-file TEXT   Path to temp file containing the git diff (required)
+  --config TEXT      Path to config.yaml [default: ~/.spec-agent/config.yaml]
+```
+
+### `spec-agent init`
+
+```
+Options:
+  --vault TEXT  Path to Obsidian vault directory (required)
+```
+
+### `spec-agent install-hook`
+
+No options. Installs `~/.git-hooks/post-push` and sets the global git hooks path.
+
+---
+
+## Manual run (without pushing)
+
+You can run the agent manually against any repo:
+
+```bash
+DIFF_FILE=$(mktemp /tmp/spec-agent-diff.XXXXXX)
+git diff HEAD~1..HEAD | head -c 50000 > "$DIFF_FILE"
+
+spec-agent run \
+  --repo "$(basename $(pwd))" \
+  --branch "$(git rev-parse --abbrev-ref HEAD)" \
+  --messages "$(git log HEAD~1..HEAD --format='%s')" \
+  --diff-file "$DIFF_FILE"
+```
+
+---
+
+## Per-repo opt-out
+
+To exclude a specific repo from spec generation, add its name to `ignored_repos` in `~/.spec-agent/config.yaml`:
+
+```yaml
+ignored_repos:
+  - my-private-repo
+  - dotfiles
+```
+
+---
+
+## Development
+
+### Requirements
+
+```bash
+git clone https://github.com/visheshchaitanya/spec-agent.git
+cd spec-agent
+pip install -e ".[dev]"
+```
+
+### Run tests
+
+```bash
+pytest
+```
+
+### Run tests with coverage
+
+```bash
+pytest --cov=spec_agent --cov-report=term-missing
+```
+
+All tests use temporary directories — no vault or API key required.
+
+---
+
+## Architecture
+
+### Tool-using agent loop
+
+The agent runs an Anthropic `messages.create` loop until `stop_reason == "end_turn"`:
+
+```
+client.messages.create(tools=TOOL_DEFINITIONS, ...)
+  → stop_reason == "tool_use"
+      → dispatch tool, collect results
+      → append assistant + user messages
+      → loop
+  → stop_reason == "end_turn"
+      → done
+```
+
+### Tools
+
+| Tool | Purpose |
+|------|---------|
+| `classify_commit` | Agent classifies diff type and extracts concepts (no-op server-side — agent reasons internally) |
+| `search_wiki` | Full-text search across vault using `grep -r` — finds related pages for wikilinks |
+| `read_wiki_file` | Reads existing spec file — enables update mode instead of duplicate creation |
+| `write_wiki_file` | Writes markdown to vault; `mode=update` appends a dated changelog section |
+| `update_index` | Appends row to `index.md` master log |
+
+### Diff safety
+
+Git diffs larger than 50,000 characters are truncated before being passed to the agent. The diff is passed via a temp file (not shell arguments) to avoid escaping issues with special characters.
+
+---
+
+## Roadmap
+
+- [ ] GitHub webhook / cloud daemon (replace local hook with HTTP POST)
+- [ ] Multi-agent parallel processing (Classifier + Writer + Linker)
+- [ ] Obsidian Dataview dashboards
+- [ ] Per-project vault paths
+- [ ] Slack/email notifications on spec creation
+
+---
+
+## Contributing
+
+Pull requests welcome. Please:
+
+1. Fork the repo and create a branch from `main`
+2. Add tests for any new behavior
+3. Ensure `pytest` passes
+4. Open a pull request
+
+---
+
+## License
+
+[MIT](LICENSE) — © 2026 Vishesh Chaitanya

spec_agent-0.1.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+spec_agent/__init__.py,sha256=ih_ux0aSsiTj8Z9Xp6zbI2Y_CcU8_ppqmkdxYwILJk8,21
+spec_agent/agent.py,sha256=Btzs3bUETaGWsJY_7jmD6vxZ1xE2iBaNlcyJNfcM4Z4,7097
+spec_agent/cli.py,sha256=DYFj3G53PxVnA3OjArE4ovYPgKMQua0LAmph9nM5OEs,4907
+spec_agent/config.py,sha256=PM9N9JBO-0h26vCpiCRQrvCWw4j6jsoMEP51mRl1-NY,1997
+spec_agent/tools/__init__.py,sha256=T8z5Dlv-OrCyaYeks_mWv06ypMPbC-7FlNja0Dk5zWE,27
+spec_agent/tools/wiki_index.py,sha256=VL6Wq7wYWCw5XbV3zW4cJkdKuNo5G9x-1Ui9aE4Hyrg,909
+spec_agent/tools/wiki_read.py,sha256=RctG9647QARLKd7PNo65MJ3R85MzS2T6cxsAy8F13jc,1019
+spec_agent/tools/wiki_search.py,sha256=KN-C29NhG6nUrCkkn14NxFW988pgcdk-d7RLS-VYHBE,2053
+spec_agent/tools/wiki_write.py,sha256=YKaXzwaY9NZdJXKcoUgRzpbliJpw_zHweVAE2nwZYcc,1600
+spec_agent-0.1.0.dist-info/licenses/LICENSE,sha256=KojDbQvCgVU70vl_bW281P6F7vKyKIQEUk2ztXcitFY,1074
+spec_agent-0.1.0.dist-info/METADATA,sha256=xTW9bF01aGu_bjrpQFp0GQ55g-3EpP5GESKSpwJnbHE,11363
+spec_agent-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+spec_agent-0.1.0.dist-info/entry_points.txt,sha256=-ZkKHI-FJ8KzcGikiEy6Jc-xilb9peF3HeiZ2wM2a7I,50
+spec_agent-0.1.0.dist-info/top_level.txt,sha256=GSYY8kK7um73Bh3VvVcHCNHMyUerYEl_7EU96gQ807A,11
+spec_agent-0.1.0.dist-info/RECORD,,

spec_agent-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

spec_agent-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+spec-agent = spec_agent.cli:cli

spec_agent-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vishesh Chaitanya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

spec_agent-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+spec_agent