Slygentify

Slygentify helps people and coding agents answer practical questions before working in an unfamiliar local Git repository:

• What applications, packages, and workspace members are present?
• Which runtimes, package managers, tools, frameworks, and CI commands are declared?
• Which component owns the file or path involved in a planned change?
• Which repository facts are missing, conflicting, unsupported, or unsafe to infer?
• Does managed coding-agent guidance still match the current repository?

It builds a bounded, evidence-backed operating map from static repository evidence instead of guessing from conventions or executing discovered project commands. First-class ecosystem inspection covers Python and JavaScript/TypeScript repositories, including mixed repositories and workspaces.

Slygentify 1.0.0 is the first stable public release. Install the exact release from PyPI or use a reviewed source checkout.

What Slygentify helps with

Human-readable interfaces are designed for exploration and review. Coding agents and automation can consume canonical versioned JSON from scan, map, and doctor, or use the corresponding Python APIs.

What Slygentify understands

Slygentify statically inspects supported manifests, workspace declarations, lock and configuration files, and CI workflows. Depending on the ecosystem and available evidence, it can surface:

• component and workspace boundaries and their relationships;
• declared runtimes, package managers, direct dependencies, and entry points;
• configured development tools and directly declared frameworks;
• setup, run, test, lint, format, and build commands declared in project metadata or CI;
• conflicting declarations, malformed supported files, skipped scopes, and important unknowns.

Every conclusion remains classified as verified, inferred, recommended, or unknown, and its supporting evidence remains inspectable. A declared command is evidence that the command appears in repository configuration; it is not proof that the command works or that the team prefers it.

Slygentify does not analyze application business logic, build a symbol or call graph, decide which source files an issue requires changing, resolve dependencies, evaluate dynamic configuration, or execute and verify discovered commands. Sandboxed command verification, cloud services, and runtime CodeGraph or forge integrations are not implemented.

Compatibility

Compatibility means that Slygentify can inspect the named static repository evidence. It does not imply that Slygentify installs the tool, runs its commands, resolves its dependencies, or connects to its hosted service.

Ecosystems and project formats

See the detailed Python and JavaScript/TypeScript inspection references for exact fields, tools, frameworks, and deliberate exclusions.

CI configuration

CI compatibility is inspection-only. Slygentify does not connect to GitHub, Gitea, GitLab, or their runners, and it does not verify that a declared workflow succeeds.

Quickstart

Install the exact stable release with pipx install slygentify==1.0.0 or uv tool install slygentify==1.0.0. The installation guide also covers pip and reviewed source checkouts. Every command accepts a directory inside a local Git repository.

Start with the complete human-readable scan report:

slygentify scan path/to/repository

For a searchable full-screen view intended for people working at a terminal:

slygentify scan path/to/repository --interactive

For a coding agent, script, or other automation, select canonical JSON or narrow the result to the logical path involved in a task:

slygentify scan path/to/repository --format json > scan.json
slygentify map path/to/repository --scope src/example.py

When you want durable coding-agent guidance, review the exact proposed artifacts before allowing a write. After initialization, use doctor following structural, tooling, or workflow changes:

slygentify init path/to/repository --dry-run
slygentify init path/to/repository
slygentify doctor path/to/repository

init is the only implemented command above that writes repository files. It writes AGENTS.md and .slygentify/state.json only after planning and revalidation. Existing unmanaged or human-edited guidance is preserved by default; ordinary init prints a paste-ready section and exits 4 so it can be merged manually. Use --adopt --dry-run to preview management of one visible Slygentify section while preserving surrounding human guidance. --replace is an explicit destructive choice and does not create a backup or merge. See the initialization guide for ownership, recovery, and state-schema behavior.

The Git executable is optional. Without it, tracked-path discovery may be unavailable and an otherwise useful result can be partial; diagnostics explain what was omitted.

See the first-repository tutorial for a runnable walkthrough, the troubleshooting guide for safe recovery, and the CLI guide for complete command behavior. The optional root slygentify.toml is described in the configuration reference.

Effects and safety

Core inspection is local, read-only, bounded, contained within the selected Git root, and network-free. Slygentify does not import the target project, execute commands it discovers, read sensitive paths by default, follow descendant symbolic links, or upload repository content.

Automatic scans, including the fresh scan used by doctor, may invoke one fixed, bounded Git ls-files lookup to retain tracked manifests that checked-out ignore rules hide. --git-executable PATH is a separate, explicit authorization for that exact executable. It is trusted unsandboxed code and may have arbitrary file, process, credential, or network effects; inspect nonstandard or repository-contained executables before selecting one. Doctor does not execute discovered validation commands.

A complete scan completed within the supported inspection boundary; it is not proof that every repository fact is known. A partial scan succeeded but omitted or limited some evidence. Diagnostics and skipped scopes explain the boundary. Diagnostic dispositions distinguish problems, trustworthy limitations, and notices without changing claim classification, completion, or exit behavior. Findings preserve whether claims are verified, inferred, recommended, or unknown.

The detailed contracts are in interaction design, inspection accounting, and the accepted safety ADRs.

Documentation

Start with the first-repository tutorial, or use the documentation index to find a focused guide or reference:

• installation
• first repository tutorial
• concepts and claim classes
• safety boundaries
• task guides
• troubleshooting
• CLI commands
• slygentify.toml and provenance
• Python and JSON APIs
• mixed-repository composition
• Python inspection
• JavaScript and TypeScript inspection
• acceptance measurement
• maintainer release process
• architecture decisions
• support, security, and migration guidance

Development

Slygentify supports Python 3.11 through 3.14 and uses uv with a committed lockfile.

uv sync --locked --all-groups
uv run pytest
uv run --locked mkdocs build --strict
uv run pre-commit run --all-files
uv build --no-sources

The pytest suite enforces 100% statement and branch coverage. The complete locked command set, Doorstop traceability workflow, branch policy, effects review, and Definition of Ready/Done are in CONTRIBUTING.md. Repository automation runs quality, documentation, supported-Python test, packaging, and dependency-vulnerability workflows; the dependency audit requires network access.

Contributions use short-lived branches from develop and reviewed pull requests back to develop. main receives reviewed release promotions. Coding agents may prepare work and evidence but do not approve or merge pull requests, publish releases, or close human gates.

Slygentify is licensed under the Apache License 2.0.