specspec 0.0.1__tar.gz

specspec-0.0.1/.gitignore

@@ -0,0 +1,18 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+*.egg-info/
+.specspec/local/
+.vscode-test/
+node_modules/
+vscode/out/
+vscode/media/
+graph-ui-common/media/vendor/
+electron/build/
+electron/release/
+*.vsix
+# Generated local Python Environments discovery; launch/tasks/workspace stay shared.
+/.vscode/settings.json

specspec-0.0.1/LICENSE

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

specspec-0.0.1/PKG-INFO

@@ -0,0 +1,253 @@
+Metadata-Version: 2.5
+Name: specspec
+Version: 0.0.1
+Summary: Connect intentions, revisable choices and implementation in versioned Markdown
+Project-URL: Homepage, https://github.com/jejay/specspec
+Project-URL: Repository, https://github.com/jejay/specspec
+Project-URL: Documentation, https://github.com/jejay/specspec/tree/main/docs
+Project-URL: Issues, https://github.com/jejay/specspec/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: coding-agents,git,markdown,requirements,specification
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.11
+Requires-Dist: click<9,>=8.1
+Requires-Dist: markdown-it-py<5,>=4
+Requires-Dist: ruamel-yaml<0.19,>=0.18.6
+Provides-Extra: dev
+Requires-Dist: build<2,>=1; extra == 'dev'
+Requires-Dist: pillow<13,>=12; extra == 'dev'
+Requires-Dist: pytest<10,>=8; extra == 'dev'
+Requires-Dist: ruff<1,>=0.11; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jejay/specspec/main/branding/specspec-logo-dark.png">
+  <img src="https://raw.githubusercontent.com/jejay/specspec/main/branding/specspec-logo-light.png" alt="specspec" width="640">
+</picture>
+
+# specspec
+
+**Keep the intention. Reconsider the solution. Know what the code is meant to do.**
+
+An agent can produce working code quickly. Keeping track of *why this solution*,
+which assumptions came from whom, and what should survive a change of approach is
+harder. A long conversation is a poor place to keep that understanding.
+
+specspec connects **your intentions, revisable choices and implementation** in a
+Git-versioned Markdown graph. Read and edit it through a small CLI, your own VS Code
+instance, or a standalone desktop window. People and coding agents use the same
+specification, with full explanations rather than a pile of unchecked task titles.
+
+> Engineering is on the spectrum now
+
+Hands-on engineering and delegated agent work are not a binary choice. You can
+direct one decision carefully and leave the next open. specspec makes that reasoning
+visible; it does not choose your level of delegation or run an agent for you.
+
+**0.0.1 is an early, local-first release.** The CLI and both graph editors are usable;
+expect rough edges and changing interfaces. There is no hosted service, Marketplace
+listing, automatic coding agent, or correctness guarantee. Your specification stays
+in your repository. [Scope and release notes](https://github.com/jejay/specspec/blob/main/CHANGELOG.md) · [Install](https://github.com/jejay/specspec/blob/main/docs/install.md)
+
+## A spectrum, not a checklist
+
+```text
+Manifesto         Help a small team understand its plan
+  Requirement     Make timing and dependencies understandable
+    Requirement   Present tasks on an interactive timeline
+      Requirement Use a local browser view with explicit JSON export
+        Implementation  Explain the view and link its actual source/tests
+```
+
+The timeline is a choice serving an intention, not the intention itself. A later
+approach can replace it without quietly losing the goal. One conclusion can serve
+several intentions: the structure is a rooted DAG, not just a hierarchy.
+
+- **Read the why.** Query a decision and every ancestor that justifies it.
+- **Revise deliberately.** Keep consequential choices separately addressable;
+  compare specification changes with Git and inspect potential downstream effects.
+- **Connect the realization.** Implementation explanations link to files or tracked
+  source regions, with explicit uncertainty when those links stop being reliable.
+- **Work visually or in the terminal.** Both UIs share one renderer and Python
+  backend. The CLI works well with an agent's existing shell tools.
+
+Graph position is a relationship, not an approval or confidence score. Passing
+validation establishes structure, not whether a product actually meets its purpose.
+
+## Choose how to use it
+
+| Entry point | What you install | What you need |
+| --- | --- | --- |
+| **specspec CLI** | Global isolated Python tool | Python 3.11+, uv or pipx; Git including initialization |
+| **specspec-vscode** | Build a VSIX, install into your ordinary editor | Global CLI, VS Code 1.90+, Node 22.12+ and npm 10+ for building |
+| **specspec-desktop** | Run from source or build a portable Electron app | Global CLI and Git; Node/npm for source builds |
+
+The CLI needs **no Node, VS Code or Electron**. The UIs use `specspec` on PATH by
+default; neither bundles a second Python runtime. Desktop targets Windows/Linux;
+macOS users can use the CLI and VS Code. See [platform qualification](https://github.com/jejay/specspec/blob/main/docs/platforms.md).
+
+### Install the CLI globally
+
+Install **[specspec from PyPI](https://pypi.org/project/specspec/)**:
+
+```sh
+uv tool install specspec
+specspec --version
+specspec --help
+```
+
+Or use `pipx install specspec`. Both install a user-wide command in an isolated
+environment, not a dependency in every project. No source checkout or Node is needed
+for the CLI. Upgrade with `uv tool upgrade specspec` or `pipx upgrade specspec`.
+Restart your terminal/editor after fixing PATH with `uv tool update-shell` or
+`pipx ensurepath` if necessary. No administrator or `sudo pip` installation is needed.
+The [installation guide](https://github.com/jejay/specspec/blob/main/docs/install.md) covers source/wheel alternatives and
+replacing an older local build.
+
+### Use it in your own VS Code — no Marketplace
+
+Only UI source builds need a checkout. After installing the CLI:
+
+```sh
+git clone https://github.com/jejay/specspec.git
+cd specspec
+npm ci
+npm run package:vscode
+code --install-extension dist/specspec-vscode-0.0.1.vsix
+```
+
+Reload VS Code, open your project and run **specspec: Open Graph** from the Command
+Palette. Or use **Extensions → … → Install from VSIX…** with that file. This is a
+normal installed extension, not an F5-only development window. No package is sent
+to the Marketplace. [Setup and troubleshooting](https://github.com/jejay/specspec/blob/main/vscode/README.md)
+
+### Run the desktop
+
+From the repository root:
+
+```sh
+npm ci
+npm run desktop
+# Or open this checkout's graph directly:
+npm run desktop -- --project .
+```
+
+Choose **Open project**, select your project and **Trust and Open**. The explicit
+`--project` launch argument authorizes that folder instead. To create a portable
+Windows/Linux package, activate the development Python environment described in
+[contributing](https://github.com/jejay/specspec/blob/main/CONTRIBUTING.md) and run `npm run package:electron`. Output is under
+`dist/`. End users of the portable archive need the global CLI and Git, **not Node**.
+[Desktop guide](https://github.com/jejay/specspec/blob/main/electron/README.md)
+
+## Start a project
+
+In a different directory — this checkout already has a graph:
+
+```sh
+mkdir my-project
+cd my-project
+specspec init -m "# Understand our plan" -m "Help a small team agree on timing."
+specspec query --max-distance 2
+```
+
+Initialization requires Git and initializes a repository when needed. It creates
+`.specspec/` and creates root **`AGENTS.md`**, or appends the
+[shipped guide](https://github.com/jejay/specspec/blob/main/src/specspec/templates/AGENTS.md) after existing instructions.
+The reserved `.specspec/local/` subtree holds ignored recovery and spotlight data,
+not nodes. Staging, commits, identity and hooks remain yours.
+
+Both UIs check for the CLI immediately and show a blocking installation message
+when it is missing. A directory without a graph offers a centered **Initialize
+specspec** action. Opening a folder alone does not create one.
+
+Copy the full manifesto ID printed by `init`, including its trailing `=`, and use
+it in place of `MANIFESTO_ID` below:
+
+```sh
+specspec add --parent MANIFESTO_ID -m "# Readable timing" -m "Show task timing clearly."
+specspec query NODE_ID --max-distance 0 --with-ancestors
+specspec update NODE_ID --replace "task timing" "timing and dependencies"
+specspec check --sources
+specspec diff --with-context
+```
+
+`NODE_ID` is another full ID from the result. Messages are literal Markdown; repeat
+`-m` for paragraphs. `--replace` selects unique passages while tolerating ordinary
+prose wrapping and line-ending differences; inserted text remains literal. Compose
+add/update/delete for one recoverable transaction. See [the CLI guide](https://github.com/jejay/specspec/blob/main/docs/cli.md)
+and each command's concise `--help`. Without messages, text comes from stdin;
+use shell redirection for large bodies.
+
+The hidden `.specspec/` directory contains direct `<id>.md` nodes and the reserved
+`local/` runtime subtree. Headings, query and the graph editor provide discovery.
+Internal schema/protocol details stay out of ordinary usage. The directory is `.specspec`, not the development-only underscore name;
+[upgrade notes](https://github.com/jejay/specspec/blob/main/docs/install.md#upgrading-pre-release-workspaces) explain the boundary.
+
+## See a project change its mind
+
+[The Gantt example](https://github.com/jejay/specspec/blob/main/example/gantt/README.md) has a runnable local planner and an
+independent Git history with two substantial changes of direction.
+Create a real example workspace outside this checkout:
+
+```sh
+python example/gantt/history/checkout.py
+```
+
+Open the resulting folder in either UI and compare `stage/01-code` → `stage/02-spec`
+or `stage/02-code` → `stage/03-spec`. Existing example clones are never reset.
+The tracked `example/gantt/` folder is a snapshot, not its own Git workspace.
+
+## Ownership and boundaries
+
+Markdown is editable directly as well as through the tools. A completed graph is
+rooted and shortcut-free; intermediate invalid graphs remain diagnosable and
+repairable. Deletion removes **exactly selected files** and retains surviving
+conclusions and their declarations. `--require-valid` checks a complete candidate;
+`check` remains strict. There are no stored approval states or parent-review gates.
+
+VS Code file tabs retain native Save, dirty state and undo/redo. Electron and
+managed project actions use locked, original-byte-checked, recoverable writes.
+Interrupted edits need `specspec recover`; this is not a universal Undo or a
+power-loss-safe database. Watchers are hints, with explicit Refresh available.
+
+The renderers load bundled assets and render project text literally. CLI execution
+requires trusted host/project configuration. Source symbols are descriptive; source
+tracking and passing tests supply evidence, not proof of semantic fulfillment.
+Large graphs are not virtualized. Signing, installers, auto-updates and hosted
+agent connectors are outside this initial release.
+
+## Go deeper
+
+- [Installation, upgrades and PATH](https://github.com/jejay/specspec/blob/main/docs/install.md) · [Agent process and template](https://github.com/jejay/specspec/blob/main/docs/agents.md)
+- [CLI reference](https://github.com/jejay/specspec/blob/main/docs/cli.md) · [Query selection](https://github.com/jejay/specspec/blob/main/docs/query.md) · [Canvas controls](https://github.com/jejay/specspec/blob/main/docs/node-canvas.md)
+- [Graph structure](https://github.com/jejay/specspec/blob/main/docs/graph-structure.md) · [Sources](https://github.com/jejay/specspec/blob/main/docs/source-regions.md) · [Deletion](https://github.com/jejay/specspec/blob/main/docs/deletion.md)
+- [Invalid-state repair](https://github.com/jejay/specspec/blob/main/docs/invalid-graphs.md) · [Native documents](https://github.com/jejay/specspec/blob/main/docs/native-editors.md) · [Remote workspaces](https://github.com/jejay/specspec/blob/main/docs/remote-workspaces.md)
+- [Architecture](https://github.com/jejay/specspec/blob/main/docs/architecture.md) · [specspec's own graph](https://github.com/jejay/specspec/blob/main/docs/own-spec.md) · [Brand provenance](https://github.com/jejay/specspec/blob/main/branding/README.md)
+- [Contributing and monorepo commands](https://github.com/jejay/specspec/blob/main/CONTRIBUTING.md) · [Release and PyPI publishing](https://github.com/jejay/specspec/blob/main/docs/releasing.md) · [MIT license](https://github.com/jejay/specspec/blob/main/LICENSE)
+
+## Monorepo map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/specspec/`, `pyproject.toml` | Python library/CLI and packaged initialization guide |
+| `vscode/` | VS Code adapter and local VSIX packaging |
+| `electron/` | Sandboxed desktop adapter and portable packaging |
+| `graph-ui-common/` | Shared renderer, session, host ports and bundled dependency notices |
+| `package.json`, `package-lock.json` | One private npm workspace, locked UI/build dependencies and root commands |
+| `branding/`, `docs/` | Selected identity, onboarding and detailed guides |
+| `.specspec/` | This product's own intentions, choices and implementation explanations |
+| `example/gantt/` | Maintained independent history fixture and runnable example snapshot |
+
+Source and release artifacts are built here; publishing remains an explicit owner
+action. The supplied original dog artwork stays archived, while the application
+and documentation use the selected Spectrum flow identity.

specspec-0.0.1/README.md

@@ -0,0 +1,221 @@
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/jejay/specspec/main/branding/specspec-logo-dark.png">
+  <img src="https://raw.githubusercontent.com/jejay/specspec/main/branding/specspec-logo-light.png" alt="specspec" width="640">
+</picture>
+
+# specspec
+
+**Keep the intention. Reconsider the solution. Know what the code is meant to do.**
+
+An agent can produce working code quickly. Keeping track of *why this solution*,
+which assumptions came from whom, and what should survive a change of approach is
+harder. A long conversation is a poor place to keep that understanding.
+
+specspec connects **your intentions, revisable choices and implementation** in a
+Git-versioned Markdown graph. Read and edit it through a small CLI, your own VS Code
+instance, or a standalone desktop window. People and coding agents use the same
+specification, with full explanations rather than a pile of unchecked task titles.
+
+> Engineering is on the spectrum now
+
+Hands-on engineering and delegated agent work are not a binary choice. You can
+direct one decision carefully and leave the next open. specspec makes that reasoning
+visible; it does not choose your level of delegation or run an agent for you.
+
+**0.0.1 is an early, local-first release.** The CLI and both graph editors are usable;
+expect rough edges and changing interfaces. There is no hosted service, Marketplace
+listing, automatic coding agent, or correctness guarantee. Your specification stays
+in your repository. [Scope and release notes](https://github.com/jejay/specspec/blob/main/CHANGELOG.md) · [Install](https://github.com/jejay/specspec/blob/main/docs/install.md)
+
+## A spectrum, not a checklist
+
+```text
+Manifesto         Help a small team understand its plan
+  Requirement     Make timing and dependencies understandable
+    Requirement   Present tasks on an interactive timeline
+      Requirement Use a local browser view with explicit JSON export
+        Implementation  Explain the view and link its actual source/tests
+```
+
+The timeline is a choice serving an intention, not the intention itself. A later
+approach can replace it without quietly losing the goal. One conclusion can serve
+several intentions: the structure is a rooted DAG, not just a hierarchy.
+
+- **Read the why.** Query a decision and every ancestor that justifies it.
+- **Revise deliberately.** Keep consequential choices separately addressable;
+  compare specification changes with Git and inspect potential downstream effects.
+- **Connect the realization.** Implementation explanations link to files or tracked
+  source regions, with explicit uncertainty when those links stop being reliable.
+- **Work visually or in the terminal.** Both UIs share one renderer and Python
+  backend. The CLI works well with an agent's existing shell tools.
+
+Graph position is a relationship, not an approval or confidence score. Passing
+validation establishes structure, not whether a product actually meets its purpose.
+
+## Choose how to use it
+
+| Entry point | What you install | What you need |
+| --- | --- | --- |
+| **specspec CLI** | Global isolated Python tool | Python 3.11+, uv or pipx; Git including initialization |
+| **specspec-vscode** | Build a VSIX, install into your ordinary editor | Global CLI, VS Code 1.90+, Node 22.12+ and npm 10+ for building |
+| **specspec-desktop** | Run from source or build a portable Electron app | Global CLI and Git; Node/npm for source builds |
+
+The CLI needs **no Node, VS Code or Electron**. The UIs use `specspec` on PATH by
+default; neither bundles a second Python runtime. Desktop targets Windows/Linux;
+macOS users can use the CLI and VS Code. See [platform qualification](https://github.com/jejay/specspec/blob/main/docs/platforms.md).
+
+### Install the CLI globally
+
+Install **[specspec from PyPI](https://pypi.org/project/specspec/)**:
+
+```sh
+uv tool install specspec
+specspec --version
+specspec --help
+```
+
+Or use `pipx install specspec`. Both install a user-wide command in an isolated
+environment, not a dependency in every project. No source checkout or Node is needed
+for the CLI. Upgrade with `uv tool upgrade specspec` or `pipx upgrade specspec`.
+Restart your terminal/editor after fixing PATH with `uv tool update-shell` or
+`pipx ensurepath` if necessary. No administrator or `sudo pip` installation is needed.
+The [installation guide](https://github.com/jejay/specspec/blob/main/docs/install.md) covers source/wheel alternatives and
+replacing an older local build.
+
+### Use it in your own VS Code — no Marketplace
+
+Only UI source builds need a checkout. After installing the CLI:
+
+```sh
+git clone https://github.com/jejay/specspec.git
+cd specspec
+npm ci
+npm run package:vscode
+code --install-extension dist/specspec-vscode-0.0.1.vsix
+```
+
+Reload VS Code, open your project and run **specspec: Open Graph** from the Command
+Palette. Or use **Extensions → … → Install from VSIX…** with that file. This is a
+normal installed extension, not an F5-only development window. No package is sent
+to the Marketplace. [Setup and troubleshooting](https://github.com/jejay/specspec/blob/main/vscode/README.md)
+
+### Run the desktop
+
+From the repository root:
+
+```sh
+npm ci
+npm run desktop
+# Or open this checkout's graph directly:
+npm run desktop -- --project .
+```
+
+Choose **Open project**, select your project and **Trust and Open**. The explicit
+`--project` launch argument authorizes that folder instead. To create a portable
+Windows/Linux package, activate the development Python environment described in
+[contributing](https://github.com/jejay/specspec/blob/main/CONTRIBUTING.md) and run `npm run package:electron`. Output is under
+`dist/`. End users of the portable archive need the global CLI and Git, **not Node**.
+[Desktop guide](https://github.com/jejay/specspec/blob/main/electron/README.md)
+
+## Start a project
+
+In a different directory — this checkout already has a graph:
+
+```sh
+mkdir my-project
+cd my-project
+specspec init -m "# Understand our plan" -m "Help a small team agree on timing."
+specspec query --max-distance 2
+```
+
+Initialization requires Git and initializes a repository when needed. It creates
+`.specspec/` and creates root **`AGENTS.md`**, or appends the
+[shipped guide](https://github.com/jejay/specspec/blob/main/src/specspec/templates/AGENTS.md) after existing instructions.
+The reserved `.specspec/local/` subtree holds ignored recovery and spotlight data,
+not nodes. Staging, commits, identity and hooks remain yours.
+
+Both UIs check for the CLI immediately and show a blocking installation message
+when it is missing. A directory without a graph offers a centered **Initialize
+specspec** action. Opening a folder alone does not create one.
+
+Copy the full manifesto ID printed by `init`, including its trailing `=`, and use
+it in place of `MANIFESTO_ID` below:
+
+```sh
+specspec add --parent MANIFESTO_ID -m "# Readable timing" -m "Show task timing clearly."
+specspec query NODE_ID --max-distance 0 --with-ancestors
+specspec update NODE_ID --replace "task timing" "timing and dependencies"
+specspec check --sources
+specspec diff --with-context
+```
+
+`NODE_ID` is another full ID from the result. Messages are literal Markdown; repeat
+`-m` for paragraphs. `--replace` selects unique passages while tolerating ordinary
+prose wrapping and line-ending differences; inserted text remains literal. Compose
+add/update/delete for one recoverable transaction. See [the CLI guide](https://github.com/jejay/specspec/blob/main/docs/cli.md)
+and each command's concise `--help`. Without messages, text comes from stdin;
+use shell redirection for large bodies.
+
+The hidden `.specspec/` directory contains direct `<id>.md` nodes and the reserved
+`local/` runtime subtree. Headings, query and the graph editor provide discovery.
+Internal schema/protocol details stay out of ordinary usage. The directory is `.specspec`, not the development-only underscore name;
+[upgrade notes](https://github.com/jejay/specspec/blob/main/docs/install.md#upgrading-pre-release-workspaces) explain the boundary.
+
+## See a project change its mind
+
+[The Gantt example](https://github.com/jejay/specspec/blob/main/example/gantt/README.md) has a runnable local planner and an
+independent Git history with two substantial changes of direction.
+Create a real example workspace outside this checkout:
+
+```sh
+python example/gantt/history/checkout.py
+```
+
+Open the resulting folder in either UI and compare `stage/01-code` → `stage/02-spec`
+or `stage/02-code` → `stage/03-spec`. Existing example clones are never reset.
+The tracked `example/gantt/` folder is a snapshot, not its own Git workspace.
+
+## Ownership and boundaries
+
+Markdown is editable directly as well as through the tools. A completed graph is
+rooted and shortcut-free; intermediate invalid graphs remain diagnosable and
+repairable. Deletion removes **exactly selected files** and retains surviving
+conclusions and their declarations. `--require-valid` checks a complete candidate;
+`check` remains strict. There are no stored approval states or parent-review gates.
+
+VS Code file tabs retain native Save, dirty state and undo/redo. Electron and
+managed project actions use locked, original-byte-checked, recoverable writes.
+Interrupted edits need `specspec recover`; this is not a universal Undo or a
+power-loss-safe database. Watchers are hints, with explicit Refresh available.
+
+The renderers load bundled assets and render project text literally. CLI execution
+requires trusted host/project configuration. Source symbols are descriptive; source
+tracking and passing tests supply evidence, not proof of semantic fulfillment.
+Large graphs are not virtualized. Signing, installers, auto-updates and hosted
+agent connectors are outside this initial release.
+
+## Go deeper
+
+- [Installation, upgrades and PATH](https://github.com/jejay/specspec/blob/main/docs/install.md) · [Agent process and template](https://github.com/jejay/specspec/blob/main/docs/agents.md)
+- [CLI reference](https://github.com/jejay/specspec/blob/main/docs/cli.md) · [Query selection](https://github.com/jejay/specspec/blob/main/docs/query.md) · [Canvas controls](https://github.com/jejay/specspec/blob/main/docs/node-canvas.md)
+- [Graph structure](https://github.com/jejay/specspec/blob/main/docs/graph-structure.md) · [Sources](https://github.com/jejay/specspec/blob/main/docs/source-regions.md) · [Deletion](https://github.com/jejay/specspec/blob/main/docs/deletion.md)
+- [Invalid-state repair](https://github.com/jejay/specspec/blob/main/docs/invalid-graphs.md) · [Native documents](https://github.com/jejay/specspec/blob/main/docs/native-editors.md) · [Remote workspaces](https://github.com/jejay/specspec/blob/main/docs/remote-workspaces.md)
+- [Architecture](https://github.com/jejay/specspec/blob/main/docs/architecture.md) · [specspec's own graph](https://github.com/jejay/specspec/blob/main/docs/own-spec.md) · [Brand provenance](https://github.com/jejay/specspec/blob/main/branding/README.md)
+- [Contributing and monorepo commands](https://github.com/jejay/specspec/blob/main/CONTRIBUTING.md) · [Release and PyPI publishing](https://github.com/jejay/specspec/blob/main/docs/releasing.md) · [MIT license](https://github.com/jejay/specspec/blob/main/LICENSE)
+
+## Monorepo map
+
+| Path | Responsibility |
+| --- | --- |
+| `src/specspec/`, `pyproject.toml` | Python library/CLI and packaged initialization guide |
+| `vscode/` | VS Code adapter and local VSIX packaging |
+| `electron/` | Sandboxed desktop adapter and portable packaging |
+| `graph-ui-common/` | Shared renderer, session, host ports and bundled dependency notices |
+| `package.json`, `package-lock.json` | One private npm workspace, locked UI/build dependencies and root commands |
+| `branding/`, `docs/` | Selected identity, onboarding and detailed guides |
+| `.specspec/` | This product's own intentions, choices and implementation explanations |
+| `example/gantt/` | Maintained independent history fixture and runnable example snapshot |
+
+Source and release artifacts are built here; publishing remains an explicit owner
+action. The supplied original dog artwork stays archived, while the application
+and documentation use the selected Spectrum flow identity.

specspec-0.0.1/pyproject.toml

@@ -0,0 +1,53 @@
+[build-system]
+requires = ["hatchling>=1.27,<2"]
+build-backend = "hatchling.build"
+
+[project]
+name = "specspec"
+version = "0.0.1"
+description = "Connect intentions, revisable choices and implementation in versioned Markdown"
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+dependencies = ["click>=8.1,<9", "ruamel.yaml>=0.18.6,<0.19", "markdown-it-py>=4,<5"]
+keywords = ["specification", "coding-agents", "requirements", "markdown", "git"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3 :: Only",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Topic :: Software Development :: Documentation",
+]
+
+[project.urls]
+Homepage = "https://github.com/jejay/specspec"
+Repository = "https://github.com/jejay/specspec"
+Documentation = "https://github.com/jejay/specspec/tree/main/docs"
+Issues = "https://github.com/jejay/specspec/issues"
+
+[project.optional-dependencies]
+dev = ["pytest>=8,<10", "ruff>=0.11,<1", "build>=1,<2", "pillow>=12,<13"]
+
+[project.scripts]
+specspec = "specspec.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/specspec"]
+
+[tool.hatch.build.targets.sdist]
+include = ["/src/specspec", "/pyproject.toml", "/README.md", "/LICENSE"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]

specspec-0.0.1/src/specspec/__init__.py

@@ -0,0 +1,3 @@
+"""specspec's reusable graph and workspace API."""
+
+__version__ = "0.0.1"

specspec-0.0.1/src/specspec/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+main()