nx-ai-engineer 1.0.1__tar.gz

nx_ai_engineer-1.0.1/LICENSE

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

nx_ai_engineer-1.0.1/PKG-INFO

@@ -0,0 +1,243 @@
+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).

nx_ai_engineer-1.0.1/README.md

@@ -0,0 +1,222 @@
+# 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).