spec-driver 0.1.0__tar.gz

spec_driver-0.1.0/.gitignore

@@ -0,0 +1,222 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+
+# But include our source code in supekku/
+!supekku/
+!supekku/**
+__pycache__

spec_driver-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Lee
+
+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_driver-0.1.0/PKG-INFO

@@ -0,0 +1,140 @@
+Metadata-Version: 2.4
+Name: spec-driver
+Version: 0.1.0
+Summary: Specification-driven development toolkit with multi-language spec sync and documentation generation
+Project-URL: Homepage, https://github.com/davidlee/spec-driver
+Project-URL: Repository, https://github.com/davidlee/spec-driver
+Project-URL: Issues, https://github.com/davidlee/spec-driver/issues
+Author-email: David Lee <david@supekku.dev>
+License: MIT
+License-File: LICENSE
+Keywords: adr,architecture-decision-records,documentation,spec-sync,specification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: python-frontmatter>=1.1.0
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# spec-driver
+
+Specification-driven agentic development toolkit with multi-language spec sync and documentation generation.
+
+Why? 
+- Maintain verifiably accurate, evergreen specs covering your _entire system_
+- Use cheap, fast, deterministically generated docs to complement and audit the work of messy, stochastic agents
+- The combination of markdown and YAML is a surprisingly powerful platform for structured, legible data 
+- Tooling joins related entities through a registry for fast lookup, validation, and relational data propagation
+- Stop banging rocks together
+ 
+## Status
+
+**Alpha** - Under active development. API and CLI may change.
+
+## Features
+
+- **Multi-language spec sync**: Automatically sync specifications with Go and Python codebases
+- **Architecture Decision Records (ADRs)**: Manage and track architectural decisions
+- **Delta/Change tracking**: Track and manage specification changes and revisions
+- **Documentation generation**: Generate documentation from code using AST analysis
+- **Workspace validation**: Ensure consistency across specification artifacts
+
+## Installation
+
+### From GitHub (Development)
+
+```bash
+# Install from latest commit
+uv add git+https://github.com/davidlee/spec-driver
+
+# Or use with uvx (no installation)
+uvx --from git+https://github.com/davidlee/spec-driver spec-driver-sync --help
+```
+
+### From PyPI (Future)
+
+```bash
+uv add spec-driver
+```
+
+## Usage
+
+spec-driver provides multiple CLI commands:
+
+### Specification Sync
+
+```bash
+# Sync specifications with codebase
+spec-driver-sync
+
+# Dry run to see what would be synced
+spec-driver-sync --dry-run
+
+# Sync specific language
+spec-driver-sync --language python
+```
+
+### Architecture Decision Records
+
+```bash
+# Create new ADR
+spec-driver-adr new "Use event sourcing for audit trail"
+
+# List ADRs
+spec-driver-adr list
+
+# Show ADR details
+spec-driver-adr show ADR-001
+```
+
+### Deltas and Changes
+
+```bash
+# Create delta
+spec-driver-delta
+
+# List deltas
+spec-driver-delta-list
+
+# Complete delta
+spec-driver-delta-complete DELTA-001
+```
+
+### Other Commands
+
+- `spec-driver-spec` - Create new specification
+- `spec-driver-spec-list` - List specifications
+- `spec-driver-requirement` - Manage requirements
+- `spec-driver-revision` - Create revision blocks
+- `spec-driver-validate-workspace` - Validate workspace consistency
+
+## Project Integration
+
+spec-driver is designed to be integrated into projects using:
+
+1. **Directory structure**: `specify/` and `change/` directories for artifacts
+2. **Justfile module**: Integration with project build tools
+3. **Agent instructions**: Claude Code integration via agent files
+
+Installation script (future):
+```bash
+uvx spec-driver install
+```
+
+## Development
+
+This package is under active development and API stability is not yet guaranteed.
+
+Current development happens in the [vice](https://github.com/davidlee/vice) repository.
+
+## License
+
+MIT

spec_driver-0.1.0/README.md

@@ -0,0 +1,114 @@
+# spec-driver
+
+Specification-driven agentic development toolkit with multi-language spec sync and documentation generation.
+
+Why? 
+- Maintain verifiably accurate, evergreen specs covering your _entire system_
+- Use cheap, fast, deterministically generated docs to complement and audit the work of messy, stochastic agents
+- The combination of markdown and YAML is a surprisingly powerful platform for structured, legible data 
+- Tooling joins related entities through a registry for fast lookup, validation, and relational data propagation
+- Stop banging rocks together
+ 
+## Status
+
+**Alpha** - Under active development. API and CLI may change.
+
+## Features
+
+- **Multi-language spec sync**: Automatically sync specifications with Go and Python codebases
+- **Architecture Decision Records (ADRs)**: Manage and track architectural decisions
+- **Delta/Change tracking**: Track and manage specification changes and revisions
+- **Documentation generation**: Generate documentation from code using AST analysis
+- **Workspace validation**: Ensure consistency across specification artifacts
+
+## Installation
+
+### From GitHub (Development)
+
+```bash
+# Install from latest commit
+uv add git+https://github.com/davidlee/spec-driver
+
+# Or use with uvx (no installation)
+uvx --from git+https://github.com/davidlee/spec-driver spec-driver-sync --help
+```
+
+### From PyPI (Future)
+
+```bash
+uv add spec-driver
+```
+
+## Usage
+
+spec-driver provides multiple CLI commands:
+
+### Specification Sync
+
+```bash
+# Sync specifications with codebase
+spec-driver-sync
+
+# Dry run to see what would be synced
+spec-driver-sync --dry-run
+
+# Sync specific language
+spec-driver-sync --language python
+```
+
+### Architecture Decision Records
+
+```bash
+# Create new ADR
+spec-driver-adr new "Use event sourcing for audit trail"
+
+# List ADRs
+spec-driver-adr list
+
+# Show ADR details
+spec-driver-adr show ADR-001
+```
+
+### Deltas and Changes
+
+```bash
+# Create delta
+spec-driver-delta
+
+# List deltas
+spec-driver-delta-list
+
+# Complete delta
+spec-driver-delta-complete DELTA-001
+```
+
+### Other Commands
+
+- `spec-driver-spec` - Create new specification
+- `spec-driver-spec-list` - List specifications
+- `spec-driver-requirement` - Manage requirements
+- `spec-driver-revision` - Create revision blocks
+- `spec-driver-validate-workspace` - Validate workspace consistency
+
+## Project Integration
+
+spec-driver is designed to be integrated into projects using:
+
+1. **Directory structure**: `specify/` and `change/` directories for artifacts
+2. **Justfile module**: Integration with project build tools
+3. **Agent instructions**: Claude Code integration via agent files
+
+Installation script (future):
+```bash
+uvx spec-driver install
+```
+
+## Development
+
+This package is under active development and API stability is not yet guaranteed.
+
+Current development happens in the [vice](https://github.com/davidlee/vice) repository.
+
+## License
+
+MIT

spec_driver-0.1.0/example.envrc

@@ -0,0 +1,10 @@
+export NIXPKGS_ALLOW_UNFREE=1
+export UV_CACHE_DIR=$(pwd)/.uv-cache
+
+# silence, nix-direnv
+export DIRENV_LOG_FORMAT="$(printf "\033[2mdirenv: %%s\033[0m")"
+_direnv_hook() {
+  eval "$(direnv export zsh 2> >(egrep -v -e '^....direnv: export' >&2))"
+}
+
+use flake . --impure # --show-trace

spec_driver-0.1.0/pyproject.toml

@@ -0,0 +1,120 @@
+[project]
+name = "spec-driver"
+version = "0.1.0"
+description = "Specification-driven development toolkit with multi-language spec sync and documentation generation"
+authors = [
+    { name = "David Lee", email = "david@supekku.dev" }
+]
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = [
+    "pyyaml>=6.0.3",
+    "python-frontmatter>=1.1.0",
+]
+keywords = ["specification", "documentation", "adr", "architecture-decision-records", "spec-sync"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Documentation",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+
+[project.urls]
+Homepage = "https://github.com/davidlee/spec-driver"
+Repository = "https://github.com/davidlee/spec-driver"
+Issues = "https://github.com/davidlee/spec-driver/issues"
+
+[project.scripts]
+spec-driver-sync = "supekku.scripts.sync_specs:main"
+spec-driver-adr = "supekku.scripts.decision_registry:main"
+spec-driver-delta = "supekku.scripts.create_delta:main"
+spec-driver-delta-complete = "supekku.scripts.complete_delta:main"
+spec-driver-delta-list = "supekku.scripts.list_deltas:main"
+spec-driver-change-registry = "supekku.scripts.change_registry:main"
+spec-driver-change-list = "supekku.scripts.list_changes:main"
+spec-driver-spec = "supekku.scripts.create_new_spec:main"
+spec-driver-spec-list = "supekku.scripts.list_specs:main"
+spec-driver-spec-sync = "supekku.scripts.sync_tech_specs:main"
+spec-driver-requirement = "supekku.scripts.create_requirement:main"
+spec-driver-requirements = "supekku.scripts.requirements:main"
+spec-driver-revision = "supekku.scripts.create_revision:main"
+spec-driver-validate-revision = "supekku.scripts.validate_revision_blocks:main"
+spec-driver-validate-workspace = "supekku.scripts.validate_workspace:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["supekku"]
+exclude = [
+    "supekku/CLAUDE.md",
+    ".direnv/",
+    ".envrc",
+    ".venv/",
+    "flake.nix",
+    "flake.lock",
+    ".uv-",
+    ".uv-cache/",
+    ".pytest_cache/",
+    "**/__pycache__/",
+    "**/*.pyc",
+    "**/*.pyo",
+    "about/",
+]
+# Force-include lib/ since it's in .gitignore (meant for build artifacts, not source)
+#force-include = { "supekku/scripts/lib" = "supekku/scripts/lib" }
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    "supekku/CLAUDE.md",
+    ".direnv/",
+    ".envrc",
+    ".venv/",
+    "flake.nix",
+    "flake.lock",
+    ".uv-",
+    ".uv-cache/",
+    ".pytest_cache/",
+    "**/__pycache__/",
+    "**/*.pyc",
+    "**/*.pyo",
+    "about/", ## fixme
+]
+#force-include = { "supekku/scripts/lib" = "supekku/scripts/lib" }
+
+[dependency-groups]
+dev = [
+    "pytest>=8.4.2",
+    "ruff>=0.14.0",
+    "pylint>=3.3.9",
+]
+
+[tool.pytest.ini_options]
+minversion = "6.0"
+addopts = "-ra"
+testpaths = [
+    "supekku/scripts",
+    "supekku/scripts/lib",
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "N", "UP"]
+ignore = []
+
+[tool.pylint.main]
+disable = [
+    "C0114",  # missing-module-docstring
+    "C0116",  # missing-function-docstring
+]

spec_driver-0.1.0/supekku/AGENTS.md

@@ -0,0 +1,28 @@
+# justfile
+
+From the project root, run
+`just --list supekku`
+
+before submitting code for user approval, run
+`just supekku::all` 
+
+ensure all tests and lint warnings are green - no exceptions(*).
+
+You cannot suppress lint warnings without user approval.
+
+`just supekku::lint`
+
+The point of linting is to improve the quality of the code.
+
+`uv run pylint supekku/scripts/lib/spec_sync` to run pylint on a particular module only.
+
+NEVER prioritise task completion over technical quality or delivering value to users.
+
+(*) - exception: we are currently working towards "lint zero". for this to be
+practical, you must fix all lint warnings in any file you touch, but can leave
+untouched files.
+
+# python
+
+we use uv because nixos. `uv run python`
+

spec_driver-0.1.0/supekku/__init__.py

@@ -0,0 +1,7 @@
+"""
+Supekku: Specification-driven development toolkit.
+
+Multi-language specification sync and documentation generation.
+"""
+
+__version__ = "0.1.0"