agent-smith-cli 0.3.1__tar.gz

agent_smith_cli-0.3.1/LICENSE

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

agent_smith_cli-0.3.1/PKG-INFO

@@ -0,0 +1,303 @@
+Metadata-Version: 2.4
+Name: agent-smith-cli
+Version: 0.3.1
+Summary: Build agent instructions from your project's sources.
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Environment :: Console
+Classifier: Programming Language :: Python :: 3 :: Only
+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: Programming Language :: Python :: 3.14
+Requires-Dist: markdown-it-py>=4,<5
+Requires-Dist: tomli>=2 ; python_full_version < '3.11'
+Requires-Python: >=3.10
+Project-URL: Repository, https://github.com/Mehdi-H/agent-smith
+Project-URL: Issues, https://github.com/Mehdi-H/agent-smith/issues
+Description-Content-Type: text/markdown
+
+# Agent Smith 🕶️
+
+[![CI](https://github.com/Mehdi-H/agent-smith/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/Mehdi-H/agent-smith/actions/workflows/release.yml?query=branch%3Amain)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue?logo=python&logoColor=white)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+*Smith* your AGENTS.md file 🕶️
+
+Build agent instructions from your project's sources !
+
+Treat your agent instructions as **living documentation**: regenerate them from
+the sources you maintain as your project evolves.
+
+Run `agent-smith` at your project root to generate **`AGENTS.md`** from your
+README overview, your mise tool declarations, documented just commands,
+architecture decision filenames and optional custom extractors
+
+Forget `/init` skill, the output is _deterministic_, repeatable Markdown, you stay in control
+
+## Demo
+
+> [!NOTE]
+> The CLI is a development preview. Built-in overview, tech-stack, command and ADR
+> sections are available; no package release has been published yet.
+
+
+![agent-smith creating AGENTS.md on the left, with a live Glow preview on the right](docs/demo/agent-smith.gif)
+
+## Install
+
+The PyPI distribution is named **`agent-smith-cli`**; the executable remains
+`agent-smith`. The name `agent-smith` was already taken on PyPI.
+
+Agent Smith supports Python 3.10–3.14. No release is available on PyPI yet:
+start from a checkout of this version of the repository and install the CLI
+from its root directory with uv:
+
+```sh
+uv tool install .
+```
+
+This installs the command in an isolated environment.
+
+> [!TIP]
+> If uv reports that its tool directory is missing from your PATH, run
+> `uv tool update-shell` and restart your terminal.
+
+Alternatively, install with pip in an activated Python virtual environment:
+
+```sh
+python -m pip install .
+```
+
+## Run and verify
+
+```sh
+agent-smith --version
+agent-smith --help
+agent-smith
+```
+
+> [!TIP]
+> To confirm installation, check that `--version` prints the installed Agent Smith version
+> and `--help` displays the available options. Both should exit successfully.
+
+Run the command **from the root of the project you want to document**. It creates
+or replaces `AGENTS.md` in that directory. Successful generation is silent;
+open the file to verify the result. No configuration is needed when you follow
+the conventions below.
+
+```sh
+agent-smith
+cat AGENTS.md
+```
+
+Use `agent-smith --output instructions.md` to choose another output filename.
+The document has an H1 containing its filename, an H2 for each section and a
+quoted footer identifying the command that produced that section.
+
+## Conventions
+
+### Overview: a README.md at the project root
+
+Place a `README.md` at the root with a top-level H1 followed by a nonempty
+introduction. Agent Smith copies the Markdown between that H1 and the first
+following H2 into **Overview**. No extraction script is required.
+
+```markdown
+# My project
+
+Describe what the project does and why someone would use it.
+
+## Installation
+
+This section is outside the extracted overview.
+```
+
+The first H2 ends the overview; if there is no H2, extraction continues to the
+end of the file. Badges, links and GitHub alerts in the introduction are kept.
+An absent README, a missing H1 or an empty introduction produces an error.
+Use `--no-overview` to disable this section.
+
+### Main tech stack: declared tools in a root mise.toml
+
+Put a `mise.toml` at your project root with a nonempty `[tools]` table:
+
+```toml
+[tools]
+python = ["3.14", "3.10"]
+uv = "latest"
+node = { version = "lts", postinstall = "corepack enable" }
+```
+
+Agent Smith automatically adds:
+
+```markdown
+## Main tech stack
+
+- `python` — `3.14`, `3.10`
+- `uv` — `latest`
+- `node` — `lts`
+```
+
+Tool names (including backend prefixes) and declared versions stay in file order.
+Strings, arrays of versions, and tables with a string `version` are supported,
+including arrays of those tables. Installation options are ignored. Agent Smith
+reads TOML directly: mise need not be installed, no hooks or templates execute,
+and aliases such as `latest` remain literal. It does not resolve installed versions,
+merge global/local configuration, or inspect other files such as `.python-version`.
+
+With no root `mise.toml`, this section is omitted. Use `--no-tech-stack` or
+`[tech_stack].enabled = false` to disable it. In the tool's configuration, `source`
+selects another TOML file and `title` changes the heading. An explicit
+`enabled = true` requires that source to exist. Invalid TOML, an empty `[tools]`
+table or an unsupported version declaration fails generation and preserves the
+existing document. The footer names the exact `agent-smith` invocation.
+
+### Available commands: a documented, grouped justfile at the project root
+
+Document your project's practices in a root `justfile` (also detected as
+`Justfile` or `.justfile`). Give each recipe a descriptive comment and a group,
+and provide a `help` recipe that prints the standard `just --list` output:
+
+```just
+# List the project's available commands.
+[group("Help")]
+help:
+    @just --list
+
+# Check modified files for whitespace errors.
+[group("Quality")]
+check-whitespace:
+    git diff --check
+```
+
+[Install just](https://just.systems/man/en/installation.html) and make sure
+`just help` works from the project root. Agent Smith automatically runs that
+command and converts its output to **Available commands**: Markdown lists under
+group subheadings, preserving recipe order, parameters and descriptions.
+For the example above, the section contains:
+
+```markdown
+## Available commands
+
+### Help
+
+- `just help` — List the project's available commands.
+
+### Quality
+
+- `just check-whitespace` — Check modified files for whitespace errors.
+```
+
+The section ends with a footer naming `just help`. Listed recipes are not
+executed; only the help recipe runs. With no root justfile, this section is
+omitted and just is not required. Use `--no-available-commands` to disable it.
+If help fails or does not produce the supported list format, generation fails
+and the existing `AGENTS.md` is preserved. Custom help formats can be supplied
+as Markdown through a custom section instead.
+
+### Architecture decisions: an ADR directory declared in .adr-dir
+
+Use [adr-tools](https://github.com/npryce/adr-tools) and a root `.adr-dir` containing
+the path to your decisions directory, for example `docs/adr`. When that file exists,
+Agent Smith runs `adr list` and adds a compact index:
+
+```markdown
+## Architecture decisions
+
+Directory: `docs/adr`
+
+- `0001-record-architecture-decisions`
+- `0002-use-python`
+```
+
+The directory appears once, using the content of `.adr-dir`. Each bullet contains
+only a filename without its final `.md` extension: numbers, hyphens and ordering
+from `adr list` are preserved. ADR contents and their Markdown headings are never
+read. Use meaningful filenames so the index conveys decisions without loading
+individual records. All records listed by adr-tools are included; their status
+is not inferred from their filenames.
+
+The footer names `adr list`. The command must be installed and runnable from the
+project root, and its listed paths must match `.adr-dir`. With no `.adr-dir`, this
+section is omitted. Empty or invalid metadata, a failed command or unsupported
+output fails generation while preserving the existing document.
+
+Use `--no-architecture-decisions` or `[architecture_decisions].enabled = false`
+to disable this built-in, and `title` to rename its heading. Setting `enabled = true`
+explicitly requires `.adr-dir` even if it was not detected automatically.
+
+## Configure sections
+
+An optional root `agent-smith.toml` customizes built-in sections and adds custom
+extractors. For example, to enable the four built-ins and append tracked files:
+
+```toml
+output = "AGENTS.md"
+
+[overview]
+enabled = true
+source = "README.md"
+title = "Overview"
+
+[available_commands]
+enabled = true
+title = "Available commands"
+command = "just help"
+
+[tech_stack]
+enabled = true
+source = "mise.toml"
+title = "Main tech stack"
+
+[architecture_decisions]
+enabled = true
+title = "Architecture decisions"
+
+[[sections]]
+title = "Tracked files"
+command = "git ls-files"
+```
+
+Each custom section uses its command's UTF-8 stdout as Markdown, followed by a
+footer with the exact command. Sections appear in configuration order after the
+built-in overview, main tech stack, available commands and architecture decisions. Set `[available_commands].enabled = false`
+to disable command discovery, or change its `command` to another source of
+standard just list output, such as `just --list`. Explicit `enabled = true`
+requires the command to work even if no root justfile was detected.
+
+To replace the overview with your own extractor:
+
+```toml
+[overview]
+enabled = false
+
+[[sections]]
+title = "Overview"
+command = "./scripts/my-overview.sh"
+```
+
+Supply your own script for that command. You can also disable the built-in with
+`--no-overview`, and select another configuration with `--config path/to/config.toml`.
+`--output` takes precedence over configuration. Paths and command working
+directories are relative to where you invoke the CLI, including with `--config`.
+The output's parent directory must exist.
+
+> [!WARNING]
+> The help recipe and custom commands run with your permissions. Only generate
+> documents from trusted projects and configurations. If extraction or writing fails, Agent Smith preserves
+> the existing output file; side effects of custom scripts are not rolled back.
+
+> [!NOTE]
+> Identical configuration and extractor outputs produce identical Markdown.
+> Variable command output, such as timestamps, remains variable. Extraction
+> preserves relative links and does not copy reference definitions from outside
+> the overview. No Markdown formatter is applied.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for repository setup, development commands, commit
+conventions and just-in-time architecture decisions. The license is [MIT](LICENSE).

agent_smith_cli-0.3.1/README.md

@@ -0,0 +1,282 @@
+# Agent Smith 🕶️
+
+[![CI](https://github.com/Mehdi-H/agent-smith/actions/workflows/release.yml/badge.svg?branch=main)](https://github.com/Mehdi-H/agent-smith/actions/workflows/release.yml?query=branch%3Amain)
+[![Python 3.10–3.14](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue?logo=python&logoColor=white)](pyproject.toml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+*Smith* your AGENTS.md file 🕶️
+
+Build agent instructions from your project's sources !
+
+Treat your agent instructions as **living documentation**: regenerate them from
+the sources you maintain as your project evolves.
+
+Run `agent-smith` at your project root to generate **`AGENTS.md`** from your
+README overview, your mise tool declarations, documented just commands,
+architecture decision filenames and optional custom extractors
+
+Forget `/init` skill, the output is _deterministic_, repeatable Markdown, you stay in control
+
+## Demo
+
+> [!NOTE]
+> The CLI is a development preview. Built-in overview, tech-stack, command and ADR
+> sections are available; no package release has been published yet.
+
+
+![agent-smith creating AGENTS.md on the left, with a live Glow preview on the right](docs/demo/agent-smith.gif)
+
+## Install
+
+The PyPI distribution is named **`agent-smith-cli`**; the executable remains
+`agent-smith`. The name `agent-smith` was already taken on PyPI.
+
+Agent Smith supports Python 3.10–3.14. No release is available on PyPI yet:
+start from a checkout of this version of the repository and install the CLI
+from its root directory with uv:
+
+```sh
+uv tool install .
+```
+
+This installs the command in an isolated environment.
+
+> [!TIP]
+> If uv reports that its tool directory is missing from your PATH, run
+> `uv tool update-shell` and restart your terminal.
+
+Alternatively, install with pip in an activated Python virtual environment:
+
+```sh
+python -m pip install .
+```
+
+## Run and verify
+
+```sh
+agent-smith --version
+agent-smith --help
+agent-smith
+```
+
+> [!TIP]
+> To confirm installation, check that `--version` prints the installed Agent Smith version
+> and `--help` displays the available options. Both should exit successfully.
+
+Run the command **from the root of the project you want to document**. It creates
+or replaces `AGENTS.md` in that directory. Successful generation is silent;
+open the file to verify the result. No configuration is needed when you follow
+the conventions below.
+
+```sh
+agent-smith
+cat AGENTS.md
+```
+
+Use `agent-smith --output instructions.md` to choose another output filename.
+The document has an H1 containing its filename, an H2 for each section and a
+quoted footer identifying the command that produced that section.
+
+## Conventions
+
+### Overview: a README.md at the project root
+
+Place a `README.md` at the root with a top-level H1 followed by a nonempty
+introduction. Agent Smith copies the Markdown between that H1 and the first
+following H2 into **Overview**. No extraction script is required.
+
+```markdown
+# My project
+
+Describe what the project does and why someone would use it.
+
+## Installation
+
+This section is outside the extracted overview.
+```
+
+The first H2 ends the overview; if there is no H2, extraction continues to the
+end of the file. Badges, links and GitHub alerts in the introduction are kept.
+An absent README, a missing H1 or an empty introduction produces an error.
+Use `--no-overview` to disable this section.
+
+### Main tech stack: declared tools in a root mise.toml
+
+Put a `mise.toml` at your project root with a nonempty `[tools]` table:
+
+```toml
+[tools]
+python = ["3.14", "3.10"]
+uv = "latest"
+node = { version = "lts", postinstall = "corepack enable" }
+```
+
+Agent Smith automatically adds:
+
+```markdown
+## Main tech stack
+
+- `python` — `3.14`, `3.10`
+- `uv` — `latest`
+- `node` — `lts`
+```
+
+Tool names (including backend prefixes) and declared versions stay in file order.
+Strings, arrays of versions, and tables with a string `version` are supported,
+including arrays of those tables. Installation options are ignored. Agent Smith
+reads TOML directly: mise need not be installed, no hooks or templates execute,
+and aliases such as `latest` remain literal. It does not resolve installed versions,
+merge global/local configuration, or inspect other files such as `.python-version`.
+
+With no root `mise.toml`, this section is omitted. Use `--no-tech-stack` or
+`[tech_stack].enabled = false` to disable it. In the tool's configuration, `source`
+selects another TOML file and `title` changes the heading. An explicit
+`enabled = true` requires that source to exist. Invalid TOML, an empty `[tools]`
+table or an unsupported version declaration fails generation and preserves the
+existing document. The footer names the exact `agent-smith` invocation.
+
+### Available commands: a documented, grouped justfile at the project root
+
+Document your project's practices in a root `justfile` (also detected as
+`Justfile` or `.justfile`). Give each recipe a descriptive comment and a group,
+and provide a `help` recipe that prints the standard `just --list` output:
+
+```just
+# List the project's available commands.
+[group("Help")]
+help:
+    @just --list
+
+# Check modified files for whitespace errors.
+[group("Quality")]
+check-whitespace:
+    git diff --check
+```
+
+[Install just](https://just.systems/man/en/installation.html) and make sure
+`just help` works from the project root. Agent Smith automatically runs that
+command and converts its output to **Available commands**: Markdown lists under
+group subheadings, preserving recipe order, parameters and descriptions.
+For the example above, the section contains:
+
+```markdown
+## Available commands
+
+### Help
+
+- `just help` — List the project's available commands.
+
+### Quality
+
+- `just check-whitespace` — Check modified files for whitespace errors.
+```
+
+The section ends with a footer naming `just help`. Listed recipes are not
+executed; only the help recipe runs. With no root justfile, this section is
+omitted and just is not required. Use `--no-available-commands` to disable it.
+If help fails or does not produce the supported list format, generation fails
+and the existing `AGENTS.md` is preserved. Custom help formats can be supplied
+as Markdown through a custom section instead.
+
+### Architecture decisions: an ADR directory declared in .adr-dir
+
+Use [adr-tools](https://github.com/npryce/adr-tools) and a root `.adr-dir` containing
+the path to your decisions directory, for example `docs/adr`. When that file exists,
+Agent Smith runs `adr list` and adds a compact index:
+
+```markdown
+## Architecture decisions
+
+Directory: `docs/adr`
+
+- `0001-record-architecture-decisions`
+- `0002-use-python`
+```
+
+The directory appears once, using the content of `.adr-dir`. Each bullet contains
+only a filename without its final `.md` extension: numbers, hyphens and ordering
+from `adr list` are preserved. ADR contents and their Markdown headings are never
+read. Use meaningful filenames so the index conveys decisions without loading
+individual records. All records listed by adr-tools are included; their status
+is not inferred from their filenames.
+
+The footer names `adr list`. The command must be installed and runnable from the
+project root, and its listed paths must match `.adr-dir`. With no `.adr-dir`, this
+section is omitted. Empty or invalid metadata, a failed command or unsupported
+output fails generation while preserving the existing document.
+
+Use `--no-architecture-decisions` or `[architecture_decisions].enabled = false`
+to disable this built-in, and `title` to rename its heading. Setting `enabled = true`
+explicitly requires `.adr-dir` even if it was not detected automatically.
+
+## Configure sections
+
+An optional root `agent-smith.toml` customizes built-in sections and adds custom
+extractors. For example, to enable the four built-ins and append tracked files:
+
+```toml
+output = "AGENTS.md"
+
+[overview]
+enabled = true
+source = "README.md"
+title = "Overview"
+
+[available_commands]
+enabled = true
+title = "Available commands"
+command = "just help"
+
+[tech_stack]
+enabled = true
+source = "mise.toml"
+title = "Main tech stack"
+
+[architecture_decisions]
+enabled = true
+title = "Architecture decisions"
+
+[[sections]]
+title = "Tracked files"
+command = "git ls-files"
+```
+
+Each custom section uses its command's UTF-8 stdout as Markdown, followed by a
+footer with the exact command. Sections appear in configuration order after the
+built-in overview, main tech stack, available commands and architecture decisions. Set `[available_commands].enabled = false`
+to disable command discovery, or change its `command` to another source of
+standard just list output, such as `just --list`. Explicit `enabled = true`
+requires the command to work even if no root justfile was detected.
+
+To replace the overview with your own extractor:
+
+```toml
+[overview]
+enabled = false
+
+[[sections]]
+title = "Overview"
+command = "./scripts/my-overview.sh"
+```
+
+Supply your own script for that command. You can also disable the built-in with
+`--no-overview`, and select another configuration with `--config path/to/config.toml`.
+`--output` takes precedence over configuration. Paths and command working
+directories are relative to where you invoke the CLI, including with `--config`.
+The output's parent directory must exist.
+
+> [!WARNING]
+> The help recipe and custom commands run with your permissions. Only generate
+> documents from trusted projects and configurations. If extraction or writing fails, Agent Smith preserves
+> the existing output file; side effects of custom scripts are not rolled back.
+
+> [!NOTE]
+> Identical configuration and extractor outputs produce identical Markdown.
+> Variable command output, such as timestamps, remains variable. Extraction
+> preserves relative links and does not copy reference definitions from outside
+> the overview. No Markdown formatter is applied.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for repository setup, development commands, commit
+conventions and just-in-time architecture decisions. The license is [MIT](LICENSE).