Metadata-Version: 2.4
Name: infinite-neo
Version: 0.1.0
Summary: An AI-native project context and handoff system for coding agents.
Author: Navneet Singh
License-Expression: MIT
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-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: test
Requires-Dist: pytest<9,>=8.4; extra == "test"
Provides-Extra: dev
Requires-Dist: build<2,>=1.5; extra == "dev"
Requires-Dist: mypy<3,>=2.0; extra == "dev"
Requires-Dist: pytest<9,>=8.4; extra == "dev"
Requires-Dist: ruff<1,>=0.15; extra == "dev"
Requires-Dist: twine<7,>=6.2; extra == "dev"
Dynamic: license-file

# Neo Codex OS

**An AI Engineering Operating System for durable project continuity.**

Neo preserves engineering context, understands project state, and guides developers through the software lifecycle so they can spend less time reconstructing context and more time building.

## Project constitution

Neo's founding direction is documented in:

- [`docs/vision.md`](docs/vision.md)
- [`docs/philosophy.md`](docs/philosophy.md)
- [`docs/anti-goals.md`](docs/anti-goals.md)
- [`docs/architecture.md`](docs/architecture.md)
- [`docs/roadmap.md`](docs/roadmap.md)
- [`docs/glossary.md`](docs/glossary.md)
- [`docs/ADR/`](docs/ADR/) for accepted architectural decisions

Contributor and project policies:

- [`CONTRIBUTING.md`](CONTRIBUTING.md)
- [`SECURITY.md`](SECURITY.md)
- [`CHANGELOG.md`](CHANGELOG.md)
- [`docs/releasing.md`](docs/releasing.md)

## Install locally

From this repository:

```powershell
py -m pip install -e .
```

Verify:

```powershell
neo --version
```

## Initialize a project

Inside any project:

```powershell
neo init
```

Or pass a path:

```powershell
neo init C:\Projects\sample-fastapi
```

## Check readiness

```powershell
neo doctor
```

## Show current project state

```powershell
neo status
neo status C:\Projects\sample-fastapi --verbose
```

Status reports where the project is, including explicit uncertainty and
conflicts. It does not recommend what to do next.

## Create a verified handoff

Record explicit human continuation intent for a fresh coding-agent thread:

```powershell
neo handoff --next-step "Run the focused regression test."
neo handoff --question "What causes the failing test?"
```

At least one of `--next-step` or `--question` is required. Neo always shows the
complete proposed `HANDOFF.md` and asks for explicit authorization before its
protected one-file replacement. Repeating an equivalent handoff is a verified,
non-mutating skip. These values are human statements, not Neo recommendations.

## Print reusable prompts

```powershell
neo prompt start
neo prompt handoff
neo prompt debug
neo prompt deploy
```

## Generated project files

```text
AGENTS.md
HANDOFF.md
TASKS.md
DECISIONS.md
.neo/
  context-authoring.md
  start-thread.md
  end-thread.md
  debug.md
  deploy.md
```

Existing files are preserved unless `--force` is used.

Before editing Schema 0.1 structured sections, read
`.neo/context-authoring.md`. It documents the exact writable grammar without
acting as another context document or ProjectState source.

## Development

Install Neo with its bounded development toolchain:

```powershell
py -m pip install -e ".[dev]"
```

Run the same quality gates used by CI:

```powershell
py -m ruff format --check src tests
py -m ruff check src tests
py -m mypy
py -m pytest
py -m build
py -m twine check dist/*
```

Use `py -m ruff format src tests` to apply formatting. GitHub Actions runs the test suite on Windows and Linux across Python 3.10 through 3.14 and smoke-tests built distributions on both operating systems.

See [`CONTRIBUTING.md`](CONTRIBUTING.md) for the complete contribution workflow.

## Typical workflow

```powershell
cd C:\Projects\my-project
neo init
neo doctor
neo status
neo handoff --question "What should the next session investigate?"
neo prompt start
```

## Official skills

Neo's first repository-owned skill is:

```text
skills/
  neo-architect/
    SKILL.md
    agents/openai.yaml
```

`neo-architect` guides architecture and substantial software work through an adaptive SDLC, integrating with Neo context files when they exist. It is currently a repository asset; the `neo` CLI and Python package do not yet install skills into an agent environment.
