specsmith 0.1.0a4__tar.gz

specsmith-0.1.0a4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BitConcepts, LLC.
+
+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.

specsmith-0.1.0a4/PKG-INFO

@@ -0,0 +1,232 @@
+Metadata-Version: 2.4
+Name: specsmith
+Version: 0.1.0a4
+Summary: Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
+Author: BitConcepts
+License: MIT
+Project-URL: Homepage, https://github.com/BitConcepts/specsmith
+Project-URL: Repository, https://github.com/BitConcepts/specsmith
+Project-URL: Changelog, https://github.com/BitConcepts/specsmith/blob/main/CHANGELOG.md
+Keywords: agentic,scaffold,governance,agents-md,cli,specification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+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 :: Code Generators
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: ruff>=0.4; extra == "dev"
+Requires-Dist: mypy>=1.10; extra == "dev"
+Requires-Dist: pre-commit>=3.0; extra == "dev"
+Requires-Dist: types-pyyaml>=6.0; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Dynamic: license-file
+
+# specsmith
+
+[![CI](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/specsmith/badge/?version=latest)](https://specsmith.readthedocs.io/en/latest/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
+
+> Intelligence proposes. Constraints decide. The ledger remembers.
+
+---
+
+## What is specsmith?
+
+`specsmith` is a CLI tool that generates full project scaffolds with built-in AI agent governance. It creates the file structure, CI/CD pipelines, governance documents, and agent integration files that AI coding assistants need to work within a structured, auditable workflow.
+
+Every scaffolded project follows the closed-loop workflow: **propose → check → execute → verify → record**.
+
+## Install
+
+```bash
+pip install specsmith
+```
+
+From source:
+
+```bash
+git clone https://github.com/BitConcepts/specsmith.git
+cd specsmith
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Interactive scaffold
+specsmith init
+
+# From config file
+specsmith init --config scaffold.yml --no-git
+
+# Guided scaffold with architecture definition
+specsmith init --guided
+
+# Import an existing project (generate governance overlay)
+specsmith import --project-dir ./my-existing-project
+specsmith import --project-dir ./my-existing-project --force
+
+# Health checks on an existing governed project
+specsmith audit --project-dir ./my-project
+specsmith validate --project-dir ./my-project
+
+# Ledger maintenance
+specsmith compress --project-dir ./my-project
+
+# Upgrade governance to newer spec version
+specsmith upgrade --spec-version 0.2.0 --project-dir ./my-project
+
+# VCS platform status (CI, alerts, PRs)
+specsmith status --project-dir ./my-project
+
+# Compare governance files against templates
+specsmith diff --project-dir ./my-project
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `specsmith init` | Scaffold a new governed project (interactive or YAML-driven) |
+| `specsmith init --guided` | Scaffold with interactive architecture definition (REQ/TEST stub generation) |
+| `specsmith import` | Import an existing project and generate governance overlay |
+| `specsmith audit [--fix]` | Drift detection and health checks; `--fix` auto-repairs missing files and oversized ledgers |
+| `specsmith validate` | Governance consistency (scaffold.yml, AGENTS.md refs, REQ uniqueness, arch↔req linkage) |
+| `specsmith compress` | Archive old ledger entries to `docs/ledger-archive.md` |
+| `specsmith upgrade` | Re-render governance files for a new spec version |
+| `specsmith status` | Show CI status, dependency alerts, and open PRs from VCS platform CLI |
+| `specsmith diff` | Compare governance files against what spec templates would generate |
+
+## Project Types
+
+specsmith supports 30 project types, each with type-specific directory structures, CI tooling, and governance rules.
+See [full project types reference](https://specsmith.readthedocs.io/project-types/) for details.
+
+| # | Type | Spec Section | Verification Tools |
+|---|------|-------------|--------------------|
+| 1 | Python backend + web frontend | 17.1 | ruff, mypy, pytest, pip-audit |
+| 2 | Python backend + web frontend + tray | 17.2 | ruff, mypy, pytest, pip-audit |
+| 3 | CLI tool (Python) | 17.3 | ruff, mypy, pytest, pip-audit |
+| 4 | Library / SDK (Python) | 17.4 | ruff, mypy, pytest, pip-audit |
+| 5 | Embedded / hardware | 17.5 | clang-tidy, cppcheck, ctest, flawfinder |
+| 6 | FPGA / RTL | 17.6 | vsg, verilator, ghdl, cocotb |
+| 7 | Yocto / embedded Linux BSP | 17.7 | oelint-adv, bitbake |
+| 8 | PCB / hardware design | 17.8 | drc-check, erc-check, kicad-cli |
+| 9 | Web frontend (SPA) | 17.9 | eslint, tsc, vitest, prettier |
+| 10 | Fullstack JS/TS | 17.10 | eslint, tsc, vitest, jest |
+| 11 | CLI tool (Rust) | 17.11 | clippy, cargo check/test/audit, rustfmt |
+| 12 | CLI tool (Go) | 17.12 | golangci-lint, go test, govulncheck |
+| 13 | CLI tool (C/C++) | 17.13 | clang-tidy, cppcheck, ctest, clang-format |
+| 14 | Library / crate (Rust) | 17.14 | clippy, cargo check/test/audit, rustfmt |
+| 15 | Library (C/C++) | 17.15 | clang-tidy, cppcheck, ctest, clang-format |
+| 16 | .NET / C# application | 17.16 | dotnet format/test/audit |
+| 17 | Mobile app | 17.17 | flutter analyze/test, eslint |
+| 18 | DevOps / IaC | 17.18 | tflint, ansible-lint, tfsec, checkov |
+| 19 | Data / ML pipeline | 17.19 | ruff, mypy, pytest, pip-audit |
+| 20 | Microservices | 17.20 | ruff, eslint, pytest, jest, docker compose |
+| 21 | Technical specification | 17.21 | vale, markdownlint, cspell, pandoc |
+| 22 | User manual / documentation | 17.22 | vale, markdownlint, cspell, sphinx |
+| 23 | Research paper / white paper | 17.23 | vale, cspell, chktex, pdflatex |
+| 24 | Business plan / proposal | 17.24 | vale, cspell, prettier, pandoc |
+| 25 | Patent application | 17.25 | vale, cspell, pandoc, claim-ref-check |
+| 26 | Legal / compliance | 17.26 | vale, cspell, pandoc, regulation-ref-check |
+| 27 | Requirements management | 17.27 | vale, markdownlint, req-trace |
+| 28 | API specification | 17.28 | spectral, buf lint, schemathesis |
+| 29 | Monorepo (multi-package) | 17.29 | eslint, ruff, nx/turbo, npm audit |
+| 30 | Browser extension | 17.30 | eslint, web-ext lint, tsc, vitest |
+
+## Agent Integrations
+
+specsmith generates agent-specific governance files so AI assistants understand your project's rules:
+
+| Agent | Generated File |
+|-------|---------------|
+| **AGENTS.md** (cross-tool standard) | `AGENTS.md` (always) |
+| Warp / Oz | `.warp/skills/SKILL.md` |
+| Claude Code | `CLAUDE.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Cursor | `.cursor/rules/governance.mdc` |
+| Gemini CLI | `GEMINI.md` |
+| Windsurf | `.windsurfrules` |
+| Aider | `.aider.conf.yml` |
+
+## VCS Platform Support
+
+CI configs are **tool-aware** — generated from the verification tool registry per project type.
+
+| Platform | CLI | CI Config | Dependency Mgmt | Security |
+|----------|-----|-----------|-----------------|----------|
+| **GitHub** | `gh` | GitHub Actions | Dependabot (pip/cargo/gomod/npm/nuget) | Tool-specific per type |
+| **GitLab** | `glab` | `.gitlab-ci.yml` | Renovate | Tool-specific per type |
+| **Bitbucket** | `bb` | Bitbucket Pipelines | Renovate | Tool-specific per type |
+
+## Branching Strategy
+
+Configure one of three branching strategies per project:
+
+- **gitflow** (default) — `main` + `develop` + feature/release/hotfix branches
+- **trunk-based** — single `main` with short-lived feature branches
+- **github-flow** — `main` + feature branches with PR-based workflow
+
+Branch protection (required reviews, CI checks, no force push) is configurable.
+
+## Configuration
+
+Projects are configured via `scaffold.yml`:
+
+```yaml
+name: my-project
+type: cli-python
+platforms: [windows, linux, macos]
+language: python
+vcs_platform: github
+branching_strategy: gitflow
+require_pr_reviews: true
+required_approvals: 1
+require_ci_pass: true
+integrations: [agents-md, warp, claude-code]
+```
+
+| `specsmith export` | Generate compliance report (REQ coverage, audit summary, tool status) |
+
+## Documentation
+
+Full documentation: [specsmith.readthedocs.io](https://specsmith.readthedocs.io)
+
+## Specification
+
+See [`docs/AGENT-WORKFLOW-SPEC.md`](docs/AGENT-WORKFLOW-SPEC.md) for the complete workflow specification.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.
+
+## License
+
+MIT — Copyright (c) 2026 BitConcepts, LLC. See [LICENSE](LICENSE).

specsmith-0.1.0a4/README.md

@@ -0,0 +1,191 @@
+# specsmith
+
+[![CI](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml/badge.svg)](https://github.com/BitConcepts/specsmith/actions/workflows/ci.yml)
+[![Docs](https://readthedocs.org/projects/specsmith/badge/?version=latest)](https://specsmith.readthedocs.io/en/latest/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+
+Forge governed project scaffolds from the Agentic AI Development Workflow Specification.
+
+> Intelligence proposes. Constraints decide. The ledger remembers.
+
+---
+
+## What is specsmith?
+
+`specsmith` is a CLI tool that generates full project scaffolds with built-in AI agent governance. It creates the file structure, CI/CD pipelines, governance documents, and agent integration files that AI coding assistants need to work within a structured, auditable workflow.
+
+Every scaffolded project follows the closed-loop workflow: **propose → check → execute → verify → record**.
+
+## Install
+
+```bash
+pip install specsmith
+```
+
+From source:
+
+```bash
+git clone https://github.com/BitConcepts/specsmith.git
+cd specsmith
+pip install -e ".[dev]"
+```
+
+## Quick Start
+
+```bash
+# Interactive scaffold
+specsmith init
+
+# From config file
+specsmith init --config scaffold.yml --no-git
+
+# Guided scaffold with architecture definition
+specsmith init --guided
+
+# Import an existing project (generate governance overlay)
+specsmith import --project-dir ./my-existing-project
+specsmith import --project-dir ./my-existing-project --force
+
+# Health checks on an existing governed project
+specsmith audit --project-dir ./my-project
+specsmith validate --project-dir ./my-project
+
+# Ledger maintenance
+specsmith compress --project-dir ./my-project
+
+# Upgrade governance to newer spec version
+specsmith upgrade --spec-version 0.2.0 --project-dir ./my-project
+
+# VCS platform status (CI, alerts, PRs)
+specsmith status --project-dir ./my-project
+
+# Compare governance files against templates
+specsmith diff --project-dir ./my-project
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `specsmith init` | Scaffold a new governed project (interactive or YAML-driven) |
+| `specsmith init --guided` | Scaffold with interactive architecture definition (REQ/TEST stub generation) |
+| `specsmith import` | Import an existing project and generate governance overlay |
+| `specsmith audit [--fix]` | Drift detection and health checks; `--fix` auto-repairs missing files and oversized ledgers |
+| `specsmith validate` | Governance consistency (scaffold.yml, AGENTS.md refs, REQ uniqueness, arch↔req linkage) |
+| `specsmith compress` | Archive old ledger entries to `docs/ledger-archive.md` |
+| `specsmith upgrade` | Re-render governance files for a new spec version |
+| `specsmith status` | Show CI status, dependency alerts, and open PRs from VCS platform CLI |
+| `specsmith diff` | Compare governance files against what spec templates would generate |
+
+## Project Types
+
+specsmith supports 30 project types, each with type-specific directory structures, CI tooling, and governance rules.
+See [full project types reference](https://specsmith.readthedocs.io/project-types/) for details.
+
+| # | Type | Spec Section | Verification Tools |
+|---|------|-------------|--------------------|
+| 1 | Python backend + web frontend | 17.1 | ruff, mypy, pytest, pip-audit |
+| 2 | Python backend + web frontend + tray | 17.2 | ruff, mypy, pytest, pip-audit |
+| 3 | CLI tool (Python) | 17.3 | ruff, mypy, pytest, pip-audit |
+| 4 | Library / SDK (Python) | 17.4 | ruff, mypy, pytest, pip-audit |
+| 5 | Embedded / hardware | 17.5 | clang-tidy, cppcheck, ctest, flawfinder |
+| 6 | FPGA / RTL | 17.6 | vsg, verilator, ghdl, cocotb |
+| 7 | Yocto / embedded Linux BSP | 17.7 | oelint-adv, bitbake |
+| 8 | PCB / hardware design | 17.8 | drc-check, erc-check, kicad-cli |
+| 9 | Web frontend (SPA) | 17.9 | eslint, tsc, vitest, prettier |
+| 10 | Fullstack JS/TS | 17.10 | eslint, tsc, vitest, jest |
+| 11 | CLI tool (Rust) | 17.11 | clippy, cargo check/test/audit, rustfmt |
+| 12 | CLI tool (Go) | 17.12 | golangci-lint, go test, govulncheck |
+| 13 | CLI tool (C/C++) | 17.13 | clang-tidy, cppcheck, ctest, clang-format |
+| 14 | Library / crate (Rust) | 17.14 | clippy, cargo check/test/audit, rustfmt |
+| 15 | Library (C/C++) | 17.15 | clang-tidy, cppcheck, ctest, clang-format |
+| 16 | .NET / C# application | 17.16 | dotnet format/test/audit |
+| 17 | Mobile app | 17.17 | flutter analyze/test, eslint |
+| 18 | DevOps / IaC | 17.18 | tflint, ansible-lint, tfsec, checkov |
+| 19 | Data / ML pipeline | 17.19 | ruff, mypy, pytest, pip-audit |
+| 20 | Microservices | 17.20 | ruff, eslint, pytest, jest, docker compose |
+| 21 | Technical specification | 17.21 | vale, markdownlint, cspell, pandoc |
+| 22 | User manual / documentation | 17.22 | vale, markdownlint, cspell, sphinx |
+| 23 | Research paper / white paper | 17.23 | vale, cspell, chktex, pdflatex |
+| 24 | Business plan / proposal | 17.24 | vale, cspell, prettier, pandoc |
+| 25 | Patent application | 17.25 | vale, cspell, pandoc, claim-ref-check |
+| 26 | Legal / compliance | 17.26 | vale, cspell, pandoc, regulation-ref-check |
+| 27 | Requirements management | 17.27 | vale, markdownlint, req-trace |
+| 28 | API specification | 17.28 | spectral, buf lint, schemathesis |
+| 29 | Monorepo (multi-package) | 17.29 | eslint, ruff, nx/turbo, npm audit |
+| 30 | Browser extension | 17.30 | eslint, web-ext lint, tsc, vitest |
+
+## Agent Integrations
+
+specsmith generates agent-specific governance files so AI assistants understand your project's rules:
+
+| Agent | Generated File |
+|-------|---------------|
+| **AGENTS.md** (cross-tool standard) | `AGENTS.md` (always) |
+| Warp / Oz | `.warp/skills/SKILL.md` |
+| Claude Code | `CLAUDE.md` |
+| GitHub Copilot | `.github/copilot-instructions.md` |
+| Cursor | `.cursor/rules/governance.mdc` |
+| Gemini CLI | `GEMINI.md` |
+| Windsurf | `.windsurfrules` |
+| Aider | `.aider.conf.yml` |
+
+## VCS Platform Support
+
+CI configs are **tool-aware** — generated from the verification tool registry per project type.
+
+| Platform | CLI | CI Config | Dependency Mgmt | Security |
+|----------|-----|-----------|-----------------|----------|
+| **GitHub** | `gh` | GitHub Actions | Dependabot (pip/cargo/gomod/npm/nuget) | Tool-specific per type |
+| **GitLab** | `glab` | `.gitlab-ci.yml` | Renovate | Tool-specific per type |
+| **Bitbucket** | `bb` | Bitbucket Pipelines | Renovate | Tool-specific per type |
+
+## Branching Strategy
+
+Configure one of three branching strategies per project:
+
+- **gitflow** (default) — `main` + `develop` + feature/release/hotfix branches
+- **trunk-based** — single `main` with short-lived feature branches
+- **github-flow** — `main` + feature branches with PR-based workflow
+
+Branch protection (required reviews, CI checks, no force push) is configurable.
+
+## Configuration
+
+Projects are configured via `scaffold.yml`:
+
+```yaml
+name: my-project
+type: cli-python
+platforms: [windows, linux, macos]
+language: python
+vcs_platform: github
+branching_strategy: gitflow
+require_pr_reviews: true
+required_approvals: 1
+require_ci_pass: true
+integrations: [agents-md, warp, claude-code]
+```
+
+| `specsmith export` | Generate compliance report (REQ coverage, audit summary, tool status) |
+
+## Documentation
+
+Full documentation: [specsmith.readthedocs.io](https://specsmith.readthedocs.io)
+
+## Specification
+
+See [`docs/AGENT-WORKFLOW-SPEC.md`](docs/AGENT-WORKFLOW-SPEC.md) for the complete workflow specification.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup and guidelines.
+
+## Security
+
+See [SECURITY.md](SECURITY.md) for vulnerability reporting.
+
+## License
+
+MIT — Copyright (c) 2026 BitConcepts, LLC. See [LICENSE](LICENSE).

specsmith-0.1.0a4/pyproject.toml

@@ -0,0 +1,80 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "specsmith"
+version = "0.1.0a4"
+description = "Forge governed project scaffolds from the Agentic AI Development Workflow Specification."
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.10"
+authors = [
+    {name = "BitConcepts"},
+]
+keywords = ["agentic", "scaffold", "governance", "agents-md", "cli", "specification"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "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 :: Code Generators",
+    "Topic :: Software Development :: Build Tools",
+]
+
+dependencies = [
+    "click>=8.1",
+    "jinja2>=3.1",
+    "pyyaml>=6.0",
+    "pydantic>=2.0",
+    "rich>=13.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0",
+    "pytest-cov>=4.0",
+    "ruff>=0.4",
+    "mypy>=1.10",
+    "pre-commit>=3.0",
+    "types-pyyaml>=6.0",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+]
+
+[project.scripts]
+specsmith = "specsmith.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/BitConcepts/specsmith"
+Repository = "https://github.com/BitConcepts/specsmith"
+Changelog = "https://github.com/BitConcepts/specsmith/blob/main/CHANGELOG.md"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+specsmith = ["templates/**/*.j2"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM"]
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+warn_return_any = true
+warn_unused_configs = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

specsmith-0.1.0a4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

specsmith-0.1.0a4/src/specsmith/__init__.py

@@ -0,0 +1,5 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""specsmith — Forge governed project scaffolds."""
+
+__version__ = "0.1.0a4"

specsmith-0.1.0a4/src/specsmith/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 BitConcepts, LLC. All rights reserved.
+"""Allow running specsmith as ``python -m specsmith``."""
+
+from specsmith.cli import main
+
+main()