specy-road 0.1.0__tar.gz

specy_road-0.1.0/LICENSE

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

specy_road-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: specy-road
+Version: 0.1.0
+Summary: Roadmap-first coordination kit for humans and AI agents
+License: MIT
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: PyYAML>=6.0
+Requires-Dist: jsonschema>=4.20
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: fastapi>=0.115; extra == "dev"
+Requires-Dist: httpx>=0.27; extra == "dev"
+Requires-Dist: requests>=2.31; extra == "dev"
+Provides-Extra: review
+Requires-Dist: openai>=1.40; extra == "review"
+Requires-Dist: anthropic>=0.40; extra == "review"
+Provides-Extra: gui
+Requires-Dist: fastapi>=0.115; extra == "gui"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "gui"
+Requires-Dist: requests>=2.31; extra == "gui"
+Requires-Dist: openai>=1.40; extra == "gui"
+Requires-Dist: anthropic>=0.40; extra == "gui"
+Provides-Extra: gui-next
+Requires-Dist: fastapi>=0.115; extra == "gui-next"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "gui-next"
+Requires-Dist: requests>=2.31; extra == "gui-next"
+Requires-Dist: openai>=1.40; extra == "gui-next"
+Requires-Dist: anthropic>=0.40; extra == "gui-next"
+Dynamic: license-file
+
+<!--
+TODO(post-release): wire automated PyPI build-and-publish on every tagged
+release (v*.*.*), then replace the install-from-source block below with a
+single `pip install specy-road` line.
+-->
+
+# specy-road
+
+> ## ⚠️ Pre-release notice
+> **Stable PyPI** does not list `specy-road` yet (`pip install specy-road` from
+> pypi.org). **Prerelease** tags (for example `v0.1.0-rc1`) publish to
+> **TestPyPI** for smoke installs — see
+> [`docs/contributor-guide.md`](docs/contributor-guide.md). For day-to-day work
+> on **this** repository, keep using an **editable install from `dev`** as in
+> [Install](#install). The TODO comment above is removed after **v0.1.0**
+> ships to PyPI and the install block switches to `pip install`.
+
+**One roadmap for the whole team**—so product, engineering, and coding agents share the same plan.
+
+## What it is
+
+**specy-road** is a toolkit for keeping priorities, written specs, and implementation work aligned. It fits teams that use AI-assisted editors (for example Claude or Cursor) together with product-led planning. Your team maintains a **roadmap** in the repository: what matters, in what order, and what depends on what. A small command-line tool checks that the roadmap is consistent, publishes a readable index, and can build **briefs**—focused packets of context for a single task—so nobody has to reread the entire project to know what to do next.
+
+### Who it’s for
+
+- **Product managers and delivery leads** — A single place for direction, sequencing, and visibility into what is active or blocked.
+- **Developers and coding agents** — Task-sized context, shared contracts, and clear ownership areas so work stays parallel without stepping on the same files.
+
+## Why teams use it
+
+- **Single source of truth** — Less drift between tickets, docs, and “what we agreed.” The roadmap and planning sheets stay tied together; cross-cutting rules live in `shared/` where they belong.
+- **Right-sized context** — `specy-road brief` pulls the relevant planning sheets and contracts for one roadmap item instead of the whole repository story.
+- **Safer parallel work** — Stable IDs, **touch zones**, and `roadmap/registry.yaml` show who is working on what before files collide.
+- **Your tools, your workflow** — The kit is about roadmaps and specs, not a particular IDE or agent ritual. See [docs/philosophy-and-scope.md](docs/philosophy-and-scope.md).
+
+## Getting started
+
+Install the CLI (**Python 3.11+**) and **git**, then follow **[Install](#install)** and **[docs/install-and-usage.md](docs/install-and-usage.md)** for cloning, editable install, and **`specy-road init project`** in an application repo. After that, everyday use boils down to:
+
+### For PMs
+
+1. Prefer **`specy-road gui`** for the dashboard, or edit `roadmap/` and `planning/` directly ([docs/pm-gui.md](docs/pm-gui.md)).
+2. Run **`specy-road export`** and **`specy-road validate`** before you commit.
+
+More detail: [docs/pm-workflow.md](docs/pm-workflow.md). Optional **LLM Review** in the Gantt UI: [docs/pm-llm-review.md](docs/pm-llm-review.md).
+
+### For developers
+
+1. Pick up work with **`specy-road do-next-available-task`**, or **`specy-road brief <NODE_ID>`** for a specific node ([docs/dev-workflow.md](docs/dev-workflow.md)).
+2. Finish with **`specy-road finish-this-task`**, then land changes with your team’s PR process ([docs/git-workflow.md](docs/git-workflow.md)).
+
+## Install
+
+Requires **Python 3.11+** and **git** (with a configured remote — `origin` by default).
+
+> **Stable PyPI pending.** Install from source on the `dev` branch (below). The
+> end-user guide is **[docs/install-and-usage.md](docs/install-and-usage.md)**;
+> prerelease/TestPyPI details live in **[docs/contributor-guide.md](docs/contributor-guide.md)**.
+
+```bash
+git clone https://github.com/shanevigil/specy-road.git
+cd specy-road
+git switch dev               # main is reserved for tagged releases
+python3 -m venv .venv
+source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -e ".[dev,gui-next]"   # add ',review' for optional review-node
+```
+
+Consumer **`init project`**, `roadmap/git-workflow.yaml`, optional **`specyrd`** stubs, and bootstrap prompts are covered in **[docs/install-and-usage.md](docs/install-and-usage.md)**. Toolkit contributors (tests, pre-commit, releases): **[docs/contributor-guide.md](docs/contributor-guide.md)**.
+
+## More on how to work with it
+
+Typical path in an **application** repository after `specy-road init project`: roadmap and planning for direction and detail; validation, export, and briefs for engineering and agents; registry and branches for safe parallel work. Maintainers working on **this** toolkit follow [AGENTS.md](AGENTS.md), [docs/toolkit-development.md](docs/toolkit-development.md), and [docs/contributor-guide.md](docs/contributor-guide.md).
+
+1. **Bootstrap** — `specy-road init project` (once per repo) creates `constitution/`, `roadmap/`, `shared/`, `constraints/`, `schemas/`, `planning/`, `work/`, and `AGENTS.md`.
+2. **Author** — Edit JSON chunks under `roadmap/` (listed in `manifest.json`). See [docs/roadmap-authoring.md](docs/roadmap-authoring.md).
+3. **Validate** — `specy-road validate` (use `--repo-root` if not in the project root).
+4. **Publish views** — `specy-road export` regenerates `roadmap.md` from the merged graph.
+5. **Focus a task** — `specy-road brief <NODE_ID> -o work/brief-<NODE_ID>.md`, then implement against `shared/` contracts cited for that node.
+6. **Branches** — Follow [docs/git-workflow.md](docs/git-workflow.md): register in `roadmap/registry.yaml` on the **integration branch** from `roadmap/git-workflow.yaml`, then `feature/rm-<codename>` (or use `specy-road do-next-available-task`).
+7. **Optional IDE commands** — `specyrd` installs stubs that invoke the CLI; see [docs/contributor-guide.md#ide-command-stubs-specyrd](docs/contributor-guide.md#ide-command-stubs-specyrd).
+
+## Where to read next
+
+| Document | Purpose |
+| -------- | ------- |
+| [docs/install-and-usage.md](docs/install-and-usage.md) | Install from source, `init project`, everyday PM/dev/GUI flows |
+| [docs/contributor-guide.md](docs/contributor-guide.md) | Toolkit contributors: CI parity, pre-commit, releases, `specyrd` |
+| [docs/philosophy-and-scope.md](docs/philosophy-and-scope.md) | What the kit promises and what it leaves to you |
+| [docs/architecture.md](docs/architecture.md) | End-to-end flow: manifest, chunks, validation, briefs |
+| [docs/roadmap-authoring.md](docs/roadmap-authoring.md) | JSON chunks, manifest order, generated `roadmap.md` |
+| [docs/git-workflow.md](docs/git-workflow.md) | Consumer workflow contract (`git-workflow.yaml`), branches, registry, merge-back |
+| [docs/toolkit-development.md](docs/toolkit-development.md) | Short maintainer notes (this repo vs consumer contract) |
+| [docs/optional-ai-tooling-patterns.md](docs/optional-ai-tooling-patterns.md) | Optional patterns (CLAUDE.md, Cursor rules, MCP) for app repos |
+| [suggested_prompts/](suggested_prompts/) | Adoption prompts (clone this repo; not shipped on PyPI) |
+| [AGENTS.md](AGENTS.md) | Short entry for coding agents |
+
+## Related material
+
+- [Spec-Kit](https://github.com/github/spec-kit) — inspiration only
+- [docs/optional-ai-tooling-patterns.md](docs/optional-ai-tooling-patterns.md) — optional AI tooling ideas for application repositories
+
+## Contributing to this repository
+
+To participate in development of the **specy-road** toolkit itself, contact the repository owner. Technical setup: [docs/contributor-guide.md](docs/contributor-guide.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

specy_road-0.1.0/README.md

@@ -0,0 +1,109 @@
+<!--
+TODO(post-release): wire automated PyPI build-and-publish on every tagged
+release (v*.*.*), then replace the install-from-source block below with a
+single `pip install specy-road` line.
+-->
+
+# specy-road
+
+> ## ⚠️ Pre-release notice
+> **Stable PyPI** does not list `specy-road` yet (`pip install specy-road` from
+> pypi.org). **Prerelease** tags (for example `v0.1.0-rc1`) publish to
+> **TestPyPI** for smoke installs — see
+> [`docs/contributor-guide.md`](docs/contributor-guide.md). For day-to-day work
+> on **this** repository, keep using an **editable install from `dev`** as in
+> [Install](#install). The TODO comment above is removed after **v0.1.0**
+> ships to PyPI and the install block switches to `pip install`.
+
+**One roadmap for the whole team**—so product, engineering, and coding agents share the same plan.
+
+## What it is
+
+**specy-road** is a toolkit for keeping priorities, written specs, and implementation work aligned. It fits teams that use AI-assisted editors (for example Claude or Cursor) together with product-led planning. Your team maintains a **roadmap** in the repository: what matters, in what order, and what depends on what. A small command-line tool checks that the roadmap is consistent, publishes a readable index, and can build **briefs**—focused packets of context for a single task—so nobody has to reread the entire project to know what to do next.
+
+### Who it’s for
+
+- **Product managers and delivery leads** — A single place for direction, sequencing, and visibility into what is active or blocked.
+- **Developers and coding agents** — Task-sized context, shared contracts, and clear ownership areas so work stays parallel without stepping on the same files.
+
+## Why teams use it
+
+- **Single source of truth** — Less drift between tickets, docs, and “what we agreed.” The roadmap and planning sheets stay tied together; cross-cutting rules live in `shared/` where they belong.
+- **Right-sized context** — `specy-road brief` pulls the relevant planning sheets and contracts for one roadmap item instead of the whole repository story.
+- **Safer parallel work** — Stable IDs, **touch zones**, and `roadmap/registry.yaml` show who is working on what before files collide.
+- **Your tools, your workflow** — The kit is about roadmaps and specs, not a particular IDE or agent ritual. See [docs/philosophy-and-scope.md](docs/philosophy-and-scope.md).
+
+## Getting started
+
+Install the CLI (**Python 3.11+**) and **git**, then follow **[Install](#install)** and **[docs/install-and-usage.md](docs/install-and-usage.md)** for cloning, editable install, and **`specy-road init project`** in an application repo. After that, everyday use boils down to:
+
+### For PMs
+
+1. Prefer **`specy-road gui`** for the dashboard, or edit `roadmap/` and `planning/` directly ([docs/pm-gui.md](docs/pm-gui.md)).
+2. Run **`specy-road export`** and **`specy-road validate`** before you commit.
+
+More detail: [docs/pm-workflow.md](docs/pm-workflow.md). Optional **LLM Review** in the Gantt UI: [docs/pm-llm-review.md](docs/pm-llm-review.md).
+
+### For developers
+
+1. Pick up work with **`specy-road do-next-available-task`**, or **`specy-road brief <NODE_ID>`** for a specific node ([docs/dev-workflow.md](docs/dev-workflow.md)).
+2. Finish with **`specy-road finish-this-task`**, then land changes with your team’s PR process ([docs/git-workflow.md](docs/git-workflow.md)).
+
+## Install
+
+Requires **Python 3.11+** and **git** (with a configured remote — `origin` by default).
+
+> **Stable PyPI pending.** Install from source on the `dev` branch (below). The
+> end-user guide is **[docs/install-and-usage.md](docs/install-and-usage.md)**;
+> prerelease/TestPyPI details live in **[docs/contributor-guide.md](docs/contributor-guide.md)**.
+
+```bash
+git clone https://github.com/shanevigil/specy-road.git
+cd specy-road
+git switch dev               # main is reserved for tagged releases
+python3 -m venv .venv
+source .venv/bin/activate    # Windows: .venv\Scripts\activate
+pip install -e ".[dev,gui-next]"   # add ',review' for optional review-node
+```
+
+Consumer **`init project`**, `roadmap/git-workflow.yaml`, optional **`specyrd`** stubs, and bootstrap prompts are covered in **[docs/install-and-usage.md](docs/install-and-usage.md)**. Toolkit contributors (tests, pre-commit, releases): **[docs/contributor-guide.md](docs/contributor-guide.md)**.
+
+## More on how to work with it
+
+Typical path in an **application** repository after `specy-road init project`: roadmap and planning for direction and detail; validation, export, and briefs for engineering and agents; registry and branches for safe parallel work. Maintainers working on **this** toolkit follow [AGENTS.md](AGENTS.md), [docs/toolkit-development.md](docs/toolkit-development.md), and [docs/contributor-guide.md](docs/contributor-guide.md).
+
+1. **Bootstrap** — `specy-road init project` (once per repo) creates `constitution/`, `roadmap/`, `shared/`, `constraints/`, `schemas/`, `planning/`, `work/`, and `AGENTS.md`.
+2. **Author** — Edit JSON chunks under `roadmap/` (listed in `manifest.json`). See [docs/roadmap-authoring.md](docs/roadmap-authoring.md).
+3. **Validate** — `specy-road validate` (use `--repo-root` if not in the project root).
+4. **Publish views** — `specy-road export` regenerates `roadmap.md` from the merged graph.
+5. **Focus a task** — `specy-road brief <NODE_ID> -o work/brief-<NODE_ID>.md`, then implement against `shared/` contracts cited for that node.
+6. **Branches** — Follow [docs/git-workflow.md](docs/git-workflow.md): register in `roadmap/registry.yaml` on the **integration branch** from `roadmap/git-workflow.yaml`, then `feature/rm-<codename>` (or use `specy-road do-next-available-task`).
+7. **Optional IDE commands** — `specyrd` installs stubs that invoke the CLI; see [docs/contributor-guide.md#ide-command-stubs-specyrd](docs/contributor-guide.md#ide-command-stubs-specyrd).
+
+## Where to read next
+
+| Document | Purpose |
+| -------- | ------- |
+| [docs/install-and-usage.md](docs/install-and-usage.md) | Install from source, `init project`, everyday PM/dev/GUI flows |
+| [docs/contributor-guide.md](docs/contributor-guide.md) | Toolkit contributors: CI parity, pre-commit, releases, `specyrd` |
+| [docs/philosophy-and-scope.md](docs/philosophy-and-scope.md) | What the kit promises and what it leaves to you |
+| [docs/architecture.md](docs/architecture.md) | End-to-end flow: manifest, chunks, validation, briefs |
+| [docs/roadmap-authoring.md](docs/roadmap-authoring.md) | JSON chunks, manifest order, generated `roadmap.md` |
+| [docs/git-workflow.md](docs/git-workflow.md) | Consumer workflow contract (`git-workflow.yaml`), branches, registry, merge-back |
+| [docs/toolkit-development.md](docs/toolkit-development.md) | Short maintainer notes (this repo vs consumer contract) |
+| [docs/optional-ai-tooling-patterns.md](docs/optional-ai-tooling-patterns.md) | Optional patterns (CLAUDE.md, Cursor rules, MCP) for app repos |
+| [suggested_prompts/](suggested_prompts/) | Adoption prompts (clone this repo; not shipped on PyPI) |
+| [AGENTS.md](AGENTS.md) | Short entry for coding agents |
+
+## Related material
+
+- [Spec-Kit](https://github.com/github/spec-kit) — inspiration only
+- [docs/optional-ai-tooling-patterns.md](docs/optional-ai-tooling-patterns.md) — optional AI tooling ideas for application repositories
+
+## Contributing to this repository
+
+To participate in development of the **specy-road** toolkit itself, contact the repository owner. Technical setup: [docs/contributor-guide.md](docs/contributor-guide.md).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

specy_road-0.1.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=61.2"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "specy-road"
+# Canonical version: `specy_road.__version__` prefers this file when the
+# package lives under this repo; else importlib.metadata; else `0.0.0+unknown`.
+version = "0.1.0"
+description = "Roadmap-first coordination kit for humans and AI agents"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+dependencies = [
+  "PyYAML>=6.0",
+  "jsonschema>=4.20",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=7.0",
+  "fastapi>=0.115",
+  # Required by starlette.testclient.TestClient (tests/test_gui_app.py); not a transitive install.
+  "httpx>=0.27",
+  "requests>=2.31",
+]
+review = [
+  "openai>=1.40",
+  "anthropic>=0.40",
+]
+gui = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+  "requests>=2.31",
+  "openai>=1.40",
+  "anthropic>=0.40",
+]
+gui-next = [
+  "fastapi>=0.115",
+  "uvicorn[standard]>=0.30",
+  "requests>=2.31",
+  "openai>=1.40",
+  "anthropic>=0.40",
+]
+
+[project.scripts]
+specy-road = "specy_road.cli:main"
+specyrd = "specy_road.specyrd_cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["specy_road*"]
+
+[tool.setuptools.package-data]
+specy_road = [
+  "templates/**/*",
+  "templates/project/**/*",
+  "pm_gantt_static/**/*",
+  "bundled_scripts/*.py",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = [".", "specy_road/bundled_scripts"]

specy_road-0.1.0/setup.cfg

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

specy_road-0.1.0/specy_road/__init__.py

@@ -0,0 +1,47 @@
+"""specy-road package (CLI and shared helpers)."""
+
+import tomllib
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+_UNKNOWN_VERSION = "0.0.0+unknown"
+
+
+def _version_from_adjacent_pyproject() -> str | None:
+    """If this ``specy_road`` package lives under a repo root, read declared version there.
+
+    Prefer this over ``importlib.metadata`` when both exist so editable checkouts
+    stay aligned with ``pyproject.toml`` even if install metadata was not refreshed.
+
+    Hardened against malformed input: any I/O error (``OSError``) **or** TOML
+    parse error (``tomllib.TOMLDecodeError``, which subclasses ``ValueError``)
+    falls through to the next resolution step rather than crashing
+    ``import specy_road``.
+    """
+    repo_root = Path(__file__).resolve().parent.parent
+    path = repo_root / "pyproject.toml"
+    if not path.is_file():
+        return None
+    try:
+        with path.open("rb") as f:
+            data = tomllib.load(f)
+    except (OSError, ValueError):
+        # ValueError covers tomllib.TOMLDecodeError (PEP 8 / stdlib hierarchy).
+        return None
+    if not isinstance(data, dict):
+        return None
+    project = data.get("project")
+    if not isinstance(project, dict) or project.get("name") != "specy-road":
+        return None
+    raw = project.get("version")
+    return raw.strip() if isinstance(raw, str) and raw.strip() else None
+
+
+_pyproject_version = _version_from_adjacent_pyproject()
+if _pyproject_version is not None:
+    __version__ = _pyproject_version
+else:
+    try:
+        __version__ = version("specy-road")
+    except PackageNotFoundError:
+        __version__ = _UNKNOWN_VERSION