py-kodo 0.1.5__tar.gz

py_kodo-0.1.5/.gitignore

@@ -0,0 +1,231 @@
+.trash/
+.claude/
+.kodo/
+uv.lock
+.DS_Store
+doc/hidden/
+
+# mise
+mise.toml
+
+# 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
+*.lcov
+.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
+.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/*
+!.pixi/config.toml
+
+# 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/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml

py_kodo-0.1.5/CLAUDE.md

@@ -0,0 +1,226 @@
+# This file contains general coding guidelines for Claude Code
+
+## Class definition
+
+Always model a class by splitting it into private and public members. Public members can be properties and methods, private members can be variables and methods.
+
+Always name-mangle private members of a class. If necessary, provide access to private member variables through read-only properties. You MUST avoid implementation of member variables that need to be modified outside of the class as this is indicative of bad design/architecture.
+
+Never use name-mangled symbols from outside the class.
+
+Add Google Style docstrings to `__init__()`, public methods, and the class itself.
+
+Example:
+
+```python
+class Example:
+    """This is an example of class definition."""
+    __var1: int
+    __var2: str
+
+    def __init__(self, var1: int) -> None:
+        """Docstring for constructor
+
+        Args:
+            var1 (int): bla bla bla
+        """
+        self.__var1 = var1
+        self.__var2 = str(var1 + 1)
+
+    @property
+    def var1(self) -> int:
+        return self.__var1
+
+    def method(self, arg: str) -> str:
+        """Docstring for method
+
+        Args:
+            var1 (int): bla bla bla
+
+        Returns:
+            str: bla bla bla
+
+        """
+        return self.__var2 + arg
+
+    def __private_method(self) -> None:
+        pass
+
+```
+
+## Module definition
+
+Always create __init__.py and py.typed in every python module. Always use relative imports from files within the module. Never use relative imports when importing from other packages.
+
+Always prepend underscore to python files inside a package.
+
+Always define `__all__` in `__init__.py`
+
+Always put ```from __future__ import annotations``` at the top of each python source code file except for `__init__.py` files.
+
+Always provide a Google Style docstring for a module.
+
+Never use star import: ```from somewhere import *  # Never do that!```
+
+Example:
+
+```python
+"""This is an example module"""
+
+from ._local_file import Something
+from another_package.subpackage import Other
+
+__all__ = [
+    'Something',
+    'Other',
+]
+```
+
+## Imports
+
+You MUST NOT use star imports. This is not allowed: `from module import *`.
+
+You MUST NOT import from python files. You MUST ALWAYS import from modules (packages). This is not allowed: `from module.submodule._file import MyClass`.
+
+Instead, export the public name from the package's `__init__.py` (add it to `__init__` and `__all__`) and import it from the package: `from module.submodule import MyClass`. If a name needs to be used outside its package, it MUST be part of that package's public API — promote a private `_helper` to a public name rather than reaching into the `_file` from another package. The only relative `from ._file import X` imports allowed are those a package makes about its own sibling modules (e.g. inside its `__init__.py`); consumers in other packages MUST go through the package's public surface. Tests follow the same rule.
+
+### Layering: `kodo.tools`
+
+`kodo.tools` (the dispatch implementation of every tool in `kodo.toolspecs`) is a dedicated import tier __between__ `toolspecs` (T2) and `subagents`/`llms` (T3). It MUST import only from T0/T1/T2 — in practice `guided_state` + `project` + `toolspecs` — and MUST NEVER import `subagents`, `llms`, or `runtime`. Collaborators from higher tiers (the gate, the session, every engine-side operation) are expressed as structural Protocols inside `kodo.tools` (`GateLike`, `SessionLike`, `EngineServices`) and injected by `runtime`. There is one unified tool surface: every agent (guide included) gets exactly the tools its frontmatter declares, dispatched through a single `ToolDispatcher`. Each tool is a `Tool` subclass (the ABC in `tools/_tool.py`) in its own `tools/_<tool_name>.py` module; its constructor binds the run's `ToolContext` and `handle(self, tool_input)` reads it via the `context` property. The `_TOOL_CLASSES` table in `tools/_dispatch.py` is the single spec→class binding. Verify the ceiling with `grep -rE "^\s*(from|import) kodo\.(subagents|llms|runtime|server)" src/kodo/tools` (must be empty).
+
+## Type hints
+
+You MUST NOT use `Optional`, `Any`, `Dict`, `List`, `TYPE_CHECKING` etc. No loose type safety, no outdated classes.
+
+You MUST use `object` instead of `Any`, and use `cast` or `isinstance` where necessary.
+
+One exception for the "no Any" rule: you are ALLOWED to use `Any` in definitions of kwargs, as this is the only way to make it work.
+
+You MUST use `typename | None` instead of `Optional`.
+
+## Windows-specific pitfalls
+
+### `os.kill(pid, 0)` fires a real Ctrl+C on Windows
+
+On Unix, `os.kill(pid, 0)` is the standard idiom for checking whether a process is alive: signal 0 is never delivered, it just probes for the process.
+
+On Windows the semantics are completely different. Python maps `os.kill` to `GenerateConsoleCtrlEvent` for `CTRL_C_EVENT` and `CTRL_BREAK_EVENT`, and to `TerminateProcess` for `SIGTERM`. Critically, `signal.CTRL_C_EVENT == 0`, so `os.kill(pid, 0)` is identical to `os.kill(pid, signal.CTRL_C_EVENT)`. This calls `GenerateConsoleCtrlEvent(CTRL_C_EVENT, pid)`, which broadcasts a real Ctrl+C event to every process sharing the current console session. Python's console control handler receives it, calls `PyErr_SetInterrupt()`, and the interrupt flag sits armed. The call returns True (success), so the caller never sees an exception — the damage is invisible. The queued interrupt fires later, at the next I/O checkpoint inside any `read()` or `write()` call, raising `KeyboardInterrupt` in an apparently unrelated location.
+
+__Rule:__ Never use `os.kill(pid, 0)` to check process liveness. On Windows use `ctypes.windll.kernel32.OpenProcess(PROCESS_QUERY_LIMITED_INFORMATION, False, pid)` instead: a non-NULL return value means the process exists; no signal is sent.
+
+```python
+@staticmethod
+def __is_running(pid: int) -> bool:
+    if sys.platform == "win32":
+        import ctypes
+        _PROCESS_QUERY_LIMITED_INFORMATION = 0x1000
+        handle = ctypes.windll.kernel32.OpenProcess(
+            _PROCESS_QUERY_LIMITED_INFORMATION, False, pid
+        )
+        if handle:
+            ctypes.windll.kernel32.CloseHandle(handle)
+            return True
+        return False
+    try:
+        os.kill(pid, 0)
+        return True
+    except OSError:
+        return False
+```
+
+### Signal-handler tests must not touch the real signal table
+
+Tests that exercise `signal.signal()`-based code (e.g. `install_signal_handlers`) must mock `signal.signal` via `monkeypatch` rather than calling the real function. The real function changes the process-wide signal table for the entire pytest session. On Windows, replacing the `SIGINT` handler removes asyncio's Ctrl+C wakeup path, causing async tests that run after the signal-handler tests to hang indefinitely inside `asyncio.to_thread` or similar I/O waits.
+
+```python
+def test_install_signal_handlers_sets_shutdown_requested(
+    lifecycle: Lifecycle,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    installed: dict[int, object] = {}
+    monkeypatch.setattr(signal, "signal", lambda signum, h: installed.update({signum: h}))
+
+    lifecycle.install_signal_handlers(lambda: None)
+
+    handler = installed.get(signal.SIGTERM)
+    assert callable(handler)
+    handler(signal.SIGTERM, None)  # type: ignore[operator]
+    assert lifecycle.shutdown_requested is True
+```
+
+`monkeypatch` is automatically undone after each test with no global side-effects.
+
+## Test implementation
+
+Design tests and classes such that unit tests validate behavior, not implementation details. It should not matter how many times a mock was called if the behavior is correct.
+
+Never build tests that rely on private methods or variables.
+
+Test private methods through behavoir of public methods.
+
+## Prompts
+
+When user asks you to review, edit, or generate an LLM prompt, you MUST follow these rules.
+
+### Drafting style
+
+You MUST generate the prompt in a way that minimizes hallucinations. Require the sub-agent to quote source material when it cites it, and to reference identifiers (requirement IDs, codenames, test IDs, file paths with line numbers) by their exact value rather than paraphrasing.
+
+You MUST be specific. You MUST NOT use vague qualifiers such as "almost", "possibly", "maybe", "appropriate", "reasonable", "as needed", "may", "could", or "should consider". Replace each with a definite statement of the rule or with a measurable threshold.
+
+You MUST state the sub-agent's purpose in a single sentence at the top of the prompt, immediately after the agent's name. The prompt MUST keep the sub-agent on that single purpose. Any behavior that falls outside the stated purpose is to be explicitly excluded under "What to Avoid".
+
+### Inputs, outputs, and reporting contract
+
+Every sub-agent MUST have three things defined in its prompt:
+
+1. __The prompt__ — the system prompt itself, including purpose, inputs, workflow, output structure, and exclusions.
+2. __The task__ — the per-invocation user message the engine sends, carrying the input file paths and inline content the agent reads as input.
+3. __The reporting tools__ — `filesystem`/`edit_file`/`create_file`/`read_file` for authors, `read_file`/`document_feedback` for critics, and, where applicable, the user-dialog and escalation tools. Tool names are named in the prompt; their JSON schemas live in code. The prompt MUST NOT restate any schema, so the prompt and the schema cannot drift.
+
+Authoritative locations:
+
+- The agent-facing tool catalog — internal/external names, descriptions, autonomous-mode behavior, and when-to-use guidance for every tool — lives in each tool's `ToolSpec` under [src/kodo/toolspecs/](src/kodo/toolspecs/) (`external_name`, `user_description`, `description`, `autonomous_mode`, `when_to_use`), rendered into the `## Tools` section of every agent prompt by [src/kodo/subagents/_registry.py](src/kodo/subagents/_registry.py). Prompts name tools; they never restate schemas.
+- `filesystem`, `edit_file`, `create_file`, `read_file` — `ToolSpec`s in [src/kodo/toolspecs/](src/kodo/toolspecs/), dispatched in-process by their `Tool` subclasses in [src/kodo/tools/](src/kodo/tools/) (`FilesystemTool`, `EditFileTool`, `CreateFileTool`, `ReadFileTool`).
+- `escalate_blocker`, `ask_user`, `document_feedback` — `ToolSpec`s in [src/kodo/toolspecs/](src/kodo/toolspecs/), one module per tool (`_escalate_blocker.py`, `_ask_user.py`, `_document_feedback.py`).
+
+The agent's frontmatter `tools:` list MUST include every tool the agent calls.
+
+### File-native document contract (replaces the former artifact workspace)
+
+Sub-agents read and write the project's __real files__ directly under `specs/`, `src/`, and `test/` — there is no staging area, no artifact index, and no toolchain-driven file naming. Every document's revision/review history is tracked separately, as a per-file, append-only `.jsonl` evolution log (`kodo.guided_state`; see [STATE_AND_LIFECYCLE.md §1](../../doc/STATE_AND_LIFECYCLE.md)) — agents never read or write that log directly, it is produced entirely by the engine and the `document_feedback` tool.
+
+- __Production__ — authors write a new document with `create_file`, choosing their own path under `specs/`, `src/`, or `test/` (no fixed naming convention — match the project's existing structure). There is no separate "I'm done" tool call; the engine records a `new_revision` entry in that file's evolution log automatically, right after the mirror commit lands.
+- __Revisions__ — an author addressing critic or user feedback edits the __same file in place__ with `edit_file` (a string-match edit; pass the whole new content as `new_string` to regenerate a file end to end). There is no `supersedes` chain to maintain — the jsonl log is the revision history.
+- __Review__ — a critic calls `document_feedback(path, accept, concerns?, summary?)` exactly once per file reviewed: `accept: false` with a non-empty `concerns` array to reject, `accept: true` with empty `concerns` to accept. This is the __only__ output a critic produces — it never edits the file itself, and it never decides what happens next.
+- __Acceptance — engine-owned, not agent-owned__. After a `document_feedback(accept: true)` call, the engine alone drives what happens: autonomous mode immediately marks the file accepted; interactive mode presents it to the user and records their decision. No sub-agent ever fires a review gate or reports completion itself — those tools (`request_user_review_artifact`, `report_artifact_completed`) were removed along with the artifact workspace.
+- __Reading inputs__ — when the engine has not already injected an input document's content into the task message, agents call `read_file` (whole file, specific line ranges, or a regex `pattern` with context lines).
+- __Cross-agent routings__ — when one author challenges another author's file (e.g. Coder suspects a test file Test Coder wrote is wrong), the challenger calls `document_feedback` on that file directly, with concerns in its own vocabulary (e.g. `suspected_test_bug`, `spec_ambiguity`). The engine routes it to the file's usual reviewer loop. There is no separate "routing" tool.
+
+### No free-form output
+
+A sub-agent MUST NOT use free-form text for any output the harness has to interpret or that is delivered to the user. Specifically:
+
+- __Verdicts__ — every verdict is a `document_feedback(path, accept, concerns)` call. Critics MUST NOT signal accept/revise via prose or via convention substrings.
+- __Completion__ — production is a `create_file`/`edit_file` call; acceptance is driven entirely by the engine after a critic's `document_feedback(accept: true)` call — no sub-agent reports completion itself.
+- __Cross-agent routings__ — every routing is a `document_feedback(path, accept=false, concerns=[...])` call targeting the challenged file. Routings MUST NOT be expressed as embedded prose or markdown blocks.
+- __Escalations to the user__ — when an author cannot defensibly make a call (an iteration cap is reached, or a back-and-forth cannot be reconciled), it calls `escalate_blocker` with a structured `reason`, `summary`, and `blocking_paths` array. This relinquishes the decision to the guide; it is an author/coder-side tool, never held by critics.
+- __User dialog__ — agents reach the user only through the common dialog tools, never free-form. `ask_user` elicits or validates a single piece of user-supplied information the agent then acts on itself (used by Narrative Author and by critics gap-filling against user input); the document-review gate is engine-driven, not a sub-agent tool. Which agents hold which tool is set by each agent's frontmatter; `ask_user` is withheld entirely in autonomous mode (no answer to synthesize), and the document-review gate auto-accepts.
+
+Intermediate reasoning text the agent emits between tool calls is allowed but unused; the harness ignores it. Sub-agent prompts SHOULD direct the agent to be terse in such text.
+
+### Transport-agnostic tool contract
+
+Every tool a sub-agent calls MUST be defined as a `ToolSpec` with a JSON Schema in [src/kodo/toolspecs/](src/kodo/toolspecs/), one module per tool. Each tool's dispatch is implemented in [src/kodo/tools/](src/kodo/tools/) — one `Tool` subclass per `_<tool_name>.py` module, routed through a single `ToolDispatcher` the engine builds per agent run (guide and leaf alike). `kodo.tools` is a dedicated import tier between `toolspecs` and `subagents`/`llms`: it may import only `guided_state` + `project` + `toolspecs`, and the gate/session/engine-services it needs are injected via structural Protocols. External MCP tool support is planned post-MVP. The sub-agent prompt MUST name the tool but MUST NOT restate the schema, so prompts remain valid when the transport changes.
+
+### Authoring a new sub-agent prompt — checklist
+
+When adding or revising a sub-agent prompt, the prompt MUST contain, in this order:
+
+1. The agent's name (one line, bold) and a one-sentence purpose statement.
+2. __Inputs__ — what the agent reads, by name and source.
+3. __Workflow__ — numbered stages or phases, each with concrete actions and stop conditions.
+4. __Reporting__ — names of the tools the agent calls, what each one signals, and the order in which they are called over the agent's lifetime. References the tool name only; never restates the schema.
+5. __What to Avoid__ — explicit exclusions, including a line that prohibits free-form output for any of the contracts covered by a reporting tool.
+
+The frontmatter MUST list every tool the agent calls, including reporting tools.

py_kodo-0.1.5/DEPENDENCIES.md

@@ -0,0 +1,133 @@
+# Dependencies
+
+## Manager
+
+- **Manager** — hatch 1.17 (at `~/.local/bin/hatch`).
+- **Manifest** — `pyproject.toml` (PEP 621 project table + hatch env configuration).
+- **Lockfile** — none. Hatch resolves dependencies on-the-fly when the environment is (re)created; there is no lockfile to maintain.
+
+## Kinds
+
+| Kind     | Manifest location                          |
+| -------- | ------------------------------------------ |
+| runtime  | `[project].dependencies`                   |
+| dev      | `[tool.hatch.envs.default].dependencies`   |
+| build    | `[build-system].requires`                  |
+
+## Operations
+
+### runtime
+
+**Add**
+
+```bash
+hatch project add <pkg>
+# Pinned to a specific version:
+hatch project add <pkg>==<version>
+```
+
+Appends `<pkg>` (or `<pkg>==<version>`) to `[project].dependencies` in `pyproject.toml`.
+
+**Remove**
+
+```bash
+hatch project remove <pkg>
+```
+
+Removes `<pkg>` from `[project].dependencies` in `pyproject.toml`.
+
+**Update**
+
+```bash
+hatch project remove <pkg>
+hatch project add <pkg>==<version>
+```
+
+There is no single hatch verb for updating a dependency. Remove the old entry, then add the new one.
+
+### dev
+
+**Add**
+
+```bash
+hatch project add --dev <pkg>
+# Pinned:
+hatch project add --dev <pkg>==<version>
+```
+
+Appends `<pkg>` (or `<pkg>==<version>`) to `[tool.hatch.envs.default].dependencies` in `pyproject.toml`.
+
+**Remove**
+
+```bash
+hatch project remove --dev <pkg>
+```
+
+Removes `<pkg>` from `[tool.hatch.envs.default].dependencies` in `pyproject.toml`.
+
+**Update**
+
+```bash
+hatch project remove --dev <pkg>
+hatch project add --dev <pkg>==<version>
+```
+
+Remove the old entry, then add the new one.
+
+### build
+
+Build-system dependencies (`[build-system].requires`) are not managed by a hatch CLI command.
+Edit `pyproject.toml` directly:
+
+**Add** — In the `[build-system]` section, add the entry to the `requires` list:
+
+```toml
+[build-system]
+requires = ["hatchling", "<pkg>==<version>"]
+```
+
+**Remove** — Remove the entry from the `requires` list:
+
+```toml
+[build-system]
+requires = ["hatchling"]
+```
+
+**Update** — Change the version string in the `requires` list.
+
+After editing, recreate the hatch environment to pick up the change:
+
+```bash
+hatch env create
+```
+
+## Conflict Resolution
+
+Hatch resolves dependencies lazily when the environment is created. To inspect or force a resolution:
+
+```bash
+# Recreate the environment (forces fresh resolution)
+hatch env remove default
+hatch env create
+
+# List installed packages in the hatch environment
+hatch run pip list
+```
+
+There is no lockfile, so transitive dependencies cannot be pinned directly. If a transitive
+dependency version is problematic, add a constraint to the appropriate dependency list
+(`[project].dependencies` for runtime, `[tool.hatch.envs.default].dependencies` for dev)
+and recreate the environment.
+
+## Verify
+
+After any dependency change, recreate the hatch environment and run the static-analysis + test
+steps to confirm nothing is broken:
+
+```bash
+hatch env remove default
+hatch env create
+hatch run lint
+hatch run typecheck
+hatch run test
+```

py_kodo-0.1.5/DEVELOPMENT.md

@@ -0,0 +1,85 @@
+# Development
+
+## Prerequisites
+
+| Tool     | Version       | Notes                                    |
+| -------- | ------------- | ---------------------------------------- |
+| Python   | >= 3.12       | Runtime interpreter.                     |
+| hatch    | >= 1.17       | Build manager. Installed at `~/.local/bin/hatch` or on `PATH`. |
+
+No additional installation is required — the five scripts below drive hatch directly.
+The hatch environment (defined in `pyproject.toml`) is created automatically on first use.
+
+## Build Scripts
+
+All scripts are run from the **project root** (`kodo/`). Each script resolves its own path
+relative to its location in `scripts/`, so `cwd` does not matter for the caller.
+
+| Script                      | What it does                                             | Hatch command(s)                           |
+| --------------------------- | -------------------------------------------------------- | ------------------------------------------ |
+| `scripts/build.{sh,ps1}`    | Build wheel + sdist (quick dev build, no version stamp). | `hatch build`                              |
+| `scripts/format.{sh,ps1}`   | Auto-format source with ruff.                            | `hatch run fmt`                            |
+| `scripts/static_analysis.{sh,ps1}` | Lint with ruff, then type-check with mypy.         | `hatch run lint` && `hatch run typecheck`  |
+| `scripts/test.{sh,ps1}`     | Run the pytest test suite.                               | `hatch run test`                           |
+| `scripts/full_build.{sh,ps1}` | format → build → static_analysis → test, fail fast.   | Delegates to the four scripts above.       |
+
+### Invocation
+
+**Linux / macOS:**
+
+```bash
+./scripts/build.sh
+./scripts/format.sh
+./scripts/static_analysis.sh
+./scripts/test.sh
+./scripts/full_build.sh
+```
+
+**Windows (PowerShell):**
+
+```powershell
+.\scripts\build.ps1
+.\scripts\format.ps1
+.\scripts\static_analysis.ps1
+.\scripts\test.ps1
+.\scripts\full_build.ps1
+```
+
+### Test Selector
+
+`scripts/test` accepts an optional first argument that is passed directly to pytest.
+
+```bash
+# Run the full suite
+./scripts/test.sh
+
+# Run a single test file
+./scripts/test.sh test/test_orders.py
+
+# Run a single test function
+./scripts/test.sh test/test_orders.py::test_refund
+
+# Run by keyword filter
+./scripts/test.sh -k refund
+```
+
+Because hatch passes `{args}` through to the underlying `pytest` command, any valid
+pytest node-id, path, or flag works as the selector.
+
+## Scripts vs. Hatch Direct Commands
+
+The five Kodo scripts cover the standard build model. Additional hatch commands are
+available for day-to-day work:
+
+| Command                  | Purpose                                              |
+| ------------------------ | ---------------------------------------------------- |
+| `hatch run check`        | Run fmt, lint, typecheck, and tests — no build.      |
+| `hatch run build`        | Full release pipeline (version stamp, checks, build, post-increment). |
+| `hatch run check-version` | Sync `__version__` in `__init__.py` from `pyproject.toml`. |
+
+See [`README.md`](README.md) for the full development cycle and release workflow.
+
+## Cross-Platform
+
+The project is pure Python with no native extensions. The `.sh` and `.ps1` pairs
+invoke identical hatch commands; there are no host/target differences.