Metadata-Version: 2.4
Name: nx-ai-engineer
Version: 1.0.1
Summary: Developer Infrastructure Platform for AI-assisted development: knowledge-driven, multi-agent, stdlib-only.
Author: NX AI Engineer
License: MIT
Project-URL: Homepage, https://github.com/erialvaro/nx-ai-engineer
Project-URL: Documentation, https://github.com/erialvaro/nx-ai-engineer/tree/main/packages/nx-cli/nx_cli/_template/docs
Project-URL: Repository, https://github.com/erialvaro/nx-ai-engineer
Project-URL: Changelog, https://github.com/erialvaro/nx-ai-engineer/blob/main/CHANGELOG.md
Keywords: ai,developer-tools,multi-agent,knowledge,cli,platform
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# NX AI Engineer

**v1.0.0** · stdlib-only · zero runtime dependencies · 238 tests green ·
[CHANGELOG](CHANGELOG.md) · [ROADMAP](ROADMAP.md) · [RELEASE_NOTES](RELEASE_NOTES.md)

**NX AI Engineer is a Developer Infrastructure Platform for AI-assisted software
development.** Its job is to organize **knowledge, context and execution** so that
*any* AI model becomes dramatically more effective while building software.

> NX AI Engineer does **not** replace Claude Code, GPT, Gemini or any other model.
> **All intelligence belongs to the model. All organization belongs to NX.**

It installs like any modern tool — a package from PyPI and a single `nxai` CLI —
and works on any stack (Node, Python, Go, Rust, Java, Nx and other monorepos, …),
which it **discovers** at runtime.

> **Guides:**
> [Installer](packages/nx-cli/nx_cli/_template/docs/INSTALLER_GUIDE.md) ·
> [Upgrade](packages/nx-cli/nx_cli/_template/docs/UPGRADE_GUIDE.md) ·
> [Architecture](docs/ARCHITECTURE.md) ·
> [SDK](packages/nx-cli/nx_cli/_template/docs/SDK_GUIDE.md) ·
> [Engine](packages/nx-cli/nx_cli/_template/docs/ENGINE_GUIDE.md) ·
> [Workflow](packages/nx-cli/nx_cli/_template/docs/WORKFLOW_GUIDE.md) ·
> [Plugin](packages/nx-cli/nx_cli/_template/docs/PLUGIN_GUIDE.md) ·
> [Knowledge](packages/nx-cli/nx_cli/_template/docs/KNOWLEDGE_GUIDE.md) ·
> [Project Brain](packages/nx-cli/nx_cli/_template/docs/PROJECT_BRAIN.md) ·
> [Contributing](CONTRIBUTING.md)

## Install

```bash
pip install nx-ai-engineer
nxai version
nxai doctor
```

No manual file copying, ever. The platform code lives in the installed packages;
your project's `.ai-project-assistant/` holds **data only**.

## Quickstart

From the root of any repository:

```bash
nxai init                      # scaffold .ai-project-assistant + audit + Brain + Knowledge + Vault
nxai plan "Add OAuth login"    # plan a goal into a task (agents, order, locks)
nxai execute "Add OAuth login" # full end-to-end flow (Dry Run -> Test -> Execute; dry-run by default)
nxai review                    # consolidated diff review
nxai knowledge status          # the three memories: Brain / Obsidian / Git
nxai docs                      # the bundled guides
```

Everything is **safe by default**: execution always runs **Dry Run → Test →
Execute** and defaults to dry-run.

## What it does

NX turns a single request into a disciplined flow — never "implement immediately":

```
audit → discover → impact → risk → plan → subtasks → agents → order →
implement → test → review → consolidate → document → report
```

It coordinates **specialized agents** (backend, frontend, database, ai, security,
devops, qa, docs, plus read-only architect/planner/reviewer/delivery) that work
safely on the same codebase via advisory locks and isolated git worktrees.

### The three memories

| Memory | Component | Role |
|---|---|---|
| **Operational** | Project Brain (`brain/`) | Structured knowledge — **never code**, never model output. |
| **Organizational** | Obsidian Vault (`obsidian/`, folders `00 Dashboard`…`14 Retrospectives`) | A navigable, auto-synced visual reflection of the Brain. |
| **Historical** | Git (opt-in) | Immutable snapshots of the knowledge over time. |

The **Knowledge Engine** has exactly five responsibilities — *discover, index,
relate, update, deliver_context* — and **never reasons, learns programming, or
interprets code**. It only reduces the model's cognitive load: the richer the
project history, the sharper the model's work, the **fewer tokens** spent.

### The Engineering Contract

How knowledge reaches the agent. An agent doesn't get an ad-hoc prompt — it gets a
**contract**: a declarative, predictable statement of what applies to a task.

```
Task → Engineering Contract → Context Builder → Model → Result → Knowledge Update
```

The contract assembles `context` (files/areas), `knowledge` (ADRs/patterns),
`engineering` (the Engineering Packs that apply), `constraints`, `requirements`
(mandatory tests/validations/checklists) and `brain` facets. **Packs are
contracts**: they declare `applies_to`, so the Backend Agent automatically
receives the **Security**, **LGPD** and **Multi-Tenant** contracts — without anyone
remembering to ask. The contract is **enforced at delivery** (a gate blocks
shipping untested code when an applicable pack mandates tests). See the
[Engineering Contract guide](packages/nx-cli/nx_cli/_template/docs/ENGINEERING_CONTRACT.md).

```bash
nxai contract --agent backend "Implement Google login" --files auth.py --areas api/auth
```

## CLI

| Command | Purpose |
|---|---|
| `nxai init` | Initialize `.ai-project-assistant` (scaffold + audit + Brain + Knowledge + Vault) |
| `nxai audit` | Discover & persist the architecture |
| `nxai plan "<goal>"` | Plan a goal into a task |
| `nxai execute "<goal>"` | Full end-to-end flow (alias of `pipeline`) |
| `nxai review` | Consolidated diff review |
| `nxai knowledge <index\|list\|retrieve\|sync\|status\|graph>` | Knowledge Engine + Providers |
| `nxai obsidian <sync\|status>` | Sync/inspect the Obsidian vault |
| `nxai contract --agent <a> "<task>"` | Build the Engineering Contract for an agent + task |
| `nxai pack <list\|show\|add\|remove>` | Engineering Packs (domain knowledge bundles) |
| `nxai scaffold [--stack ...]` | Lay open-source/GitHub repo standards into the project |
| `nxai graph` | Show the project Knowledge Graph |
| `nxai report` | Consolidated report (status + insights + metrics) |
| `nxai docs [name]` | List the bundled guides, or print one |
| `nxai doctor` | Health-check the install and project |
| `nxai update` | Refresh template assets (keeps Brain/Vault/config/history) |
| `nxai version` | Show version |

…plus `decide`, `dispatch`, `context`, `run`, `deliver`, `pipeline`, `metrics`,
`insights`, `recommend`, `worktree`, `tasks`, `locks`, `unlock`, `status`.
(The legacy `nx` alias is also installed.)

## Engineering Packs

Domain knowledge — not code — that makes the agents apply a domain's rules
correctly:

```bash
nxai pack list                 # browse the catalog
nxai pack add lgpd             # install LGPD/privacy policies + checklists + context
nxai pack add security         # OWASP/ASVS-aligned application security
```

Built-in packs: **lgpd**, **security**, **repo-standards** (stable) plus scaffolds
for owasp, ai, cloud, docker, multi-tenant, observability, testing, billing,
authentication. Once installed, the **Pack Provider** feeds the pack's
policies/checklists/context to the agents working in that domain. Packs contain
**no code and no AI**. See the
[Packs Guide](packages/nx-cli/nx_cli/_template/docs/PACKS_GUIDE.md); third parties
can publish their own (the pack Marketplace).

### Packs (knowledge) × Specialist Agents (execution)

The knowledge lives in the **Pack**; a **Specialist Agent** just executes using it
— *the agent is disposable, the knowledge is not*. The **Database** category ships
`postgres` and `mongodb` (full: rules, patterns, anti-patterns, performance,
checklists, security) plus mysql/sqlserver/oracle/sqlite/redis/cassandra/elastic/
neo4j, with specialist agents **database-relational**, **database-nosql** and a
read-only **database-reviewer** (never implements — it asks and *blocks* on
duplicate tables, redundant indexes, anti-patterns). The Engineering Contract
auto-attaches the right pack to each agent, so the *same* PostgreSQL knowledge
serves the relational, reviewer and migration work without duplication.

```bash
nxai pack add postgres
nxai contract --agent database-relational "Add an orders table"   # postgres pack auto-attached
```

### Standardize a repository

The `repo-standards` pack also ships concrete templates that `nxai scaffold` lays
into a project's repo root — governance files, issue/PR templates and a CI
workflow matched to the stack:

```bash
nxai scaffold --stack auto --dry-run   # preview
nxai scaffold --stack python           # CONTRIBUTING, CODE_OF_CONDUCT, SECURITY,
                                       # .github/ISSUE_TEMPLATE, PR template, CI, .gitignore
```

Idempotent — it never overwrites an existing file without `--force`.

## Architecture

A monorepo of **9 acyclic, stdlib-only packages**:

```
nx-core ← nx-workflow ← nx-sdk
nx-core ← nx-packs
nx-core ← nx-providers ← nx-obsidian ← nx-knowledge
{core, workflow, sdk, knowledge} ← nx-runtime ← nx-cli
```

| Package | Responsibility |
|---|---|
| `nx-core` | Kernel (domain/states/lifecycle/engine), governance, observability, foundation |
| `nx-workflow` | Reusable multi-step workflows |
| `nx-sdk` | Public extension surface (agents/engines/workflows/adapters/plugins/tools) |
| `nx-packs` | Engineering Packs catalog (domain knowledge bundles) |
| `nx-providers` | Knowledge providers (filesystem, git, markdown, ADR, project-brain, packs) + the relate/graph primitive |
| `nx-obsidian` | Obsidian provider + vault sync |
| `nx-knowledge` | Knowledge Engine, registry, memory (Brain), evolution |
| `nx-runtime` | Adapters, schedulers, intelligence, engines, composition-root pipeline |
| `nx-cli` | The official `nxai` CLI + the deployable template |

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md). The acyclic graph is enforced by
`scripts/verify_packages.py`; the full Quality Gate is `scripts/quality_gate.py`.

## Extending

NX is built on an Open/Closed SDK — register agents, engines, workflows, adapters,
plugins and tools without touching the core. See the
[SDK Guide](packages/nx-cli/nx_cli/_template/docs/SDK_GUIDE.md) and
[Plugin Guide](packages/nx-cli/nx_cli/_template/docs/PLUGIN_GUIDE.md).

## Principles

- **All intelligence is the model's.** NX organizes; it never reasons.
- **Stdlib-only core** — zero third-party runtime dependencies.
- **Safe by default** — Dry Run → Test → Execute; nothing destructive without intent.
- **The Brain never stores code** — only structured knowledge.
- **Knowledge is leverage** — more history ⇒ better context ⇒ fewer tokens.

## License

MIT — see [LICENSE](LICENSE).
