nexus-dev-toolkit 3.0.0__tar.gz

nexus_dev_toolkit-3.0.0/LICENSE

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

nexus_dev_toolkit-3.0.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: nexus-dev-toolkit
+Version: 3.0.0
+Summary: LLM-agnostic developer workflow toolkit — Day 0 scaffold + Day 1 EPAV
+Author-email: Ronald dela Cruz <rcdelacruz@users.noreply.github.com>
+License-Expression: MIT
+Project-URL: Homepage, https://nexus.coderstudio.co
+Project-URL: Repository, https://github.com/rcdelacruz/nexus-dev-toolkit
+Project-URL: Issues, https://github.com/rcdelacruz/nexus-dev-toolkit/issues
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.0.0
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Dynamic: license-file
+
+# nexus-dev-toolkit
+
+[![PyPI version](https://img.shields.io/pypi/v/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Developer workflow toolkit for AI-assisted development. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
+
+---
+
+## Why
+
+Ad-hoc AI prompting doesn't scale. Every dev prompts differently, context drifts, and nobody knows what the AI was told last sprint.
+
+`nexus-dev-toolkit` gives your team a single workflow:
+
+- **Day 0** — scaffold the project once, production-grade, zero credentials needed
+- **Day 1** — every feature follows the same four steps: evaluate → plan → apply → validate
+
+Every skill, every rule, every pattern lives in the project repo — versioned, shared, and enforced.
+
+---
+
+## The Workflow
+
+### Day 0 — `/scaffold` (once per project)
+
+```
+nexus init <project-dir>
+```
+
+Sets up `.claude/commands/`, `.claude/settings.json`, and `knowledge/`. Then in Claude Code:
+
+```
+/scaffold
+```
+
+EVALUATE → PLAN → APPLY → VALIDATE. Produces a production-grade project: correct stack from your arch doc, mock auth, mock data, design system, AGENTS.md — all from your architecture document. Runs with `npm install && npm run dev` (or equivalent) from commit one.
+
+### Day 1 — EPAV (every feature, every sprint)
+
+```
+/evaluate   →   /plan   →   /apply   →   /validate
+```
+
+Each step is a built-in skill in `.claude/commands/`. Every task starts with a row from the dev tasks CSV. Every task ends with acceptance criteria verified.
+
+---
+
+## Install
+
+**Requirements:** Python 3.10+, `uv` (recommended) or `pip`
+
+```bash
+# Recommended
+uv tool install nexus-dev-toolkit
+
+# Or via pip
+pip install nexus-dev-toolkit
+```
+
+---
+
+## Quick Start
+
+```bash
+cd my-project
+nexus init .
+```
+
+Then open the project in Claude Code and type `/scaffold`.
+
+---
+
+## Commands
+
+```bash
+nexus init .                 # set up .claude/commands/ + knowledge/ + .mcp.json
+nexus skill add code-review  # create a custom skill in .claude/commands/
+nexus skill list             # list all skills
+nexus rule add api-standards # create a rule in knowledge/rules/
+nexus rule list              # list all rules
+nexus update                 # update to latest version
+```
+
+---
+
+## What `nexus init` Creates
+
+```
+.claude/
+├── commands/
+│   ├── scaffold.md    ← /scaffold  — Day 0 one-time setup
+│   ├── evaluate.md    ← /evaluate  — orient on a task
+│   ├── plan.md        ← /plan      — blueprint, no code
+│   ├── apply.md       ← /apply     — implement the plan
+│   ├── validate.md    ← /validate  — verify acceptance criteria
+│   └── epav.md        ← /epav      — full cycle guide
+└── settings.json      ← PostToolUse hook: graphify auto-updates after every file edit
+knowledge/
+├── rules/             ← coding standards, arch decisions
+├── patterns/          ← reusable implementation patterns
+├── prompts/dev/       ← task prompt templates
+└── retros/            ← retrospective notes
+.mcp.json              ← MCP server config
+```
+
+---
+
+## MCP Server
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "uvx",
+      "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
+    }
+  }
+}
+```
+
+`nexus init` writes `.mcp.json` automatically.
+
+### MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `ingest_architecture_doc` | Load arch doc → `knowledge/rules/arch-summary.md` |
+| `load_task` | Load a CSV task row into context |
+| `generate_project_rules` | Generate `AGENTS.md` from arch doc |
+| `resolve_package_versions` | Resolve exact package versions via real package manager |
+
+---
+
+## Custom Skills
+
+```bash
+nexus skill add my-code-review
+# Edit .claude/commands/my-code-review.md
+# Type /my-code-review in Claude Code
+```
+
+Custom skills live alongside built-in skills in `.claude/commands/` — versioned in your repo, shared across the team.
+
+---
+
+## License
+
+[MIT](LICENSE)

nexus_dev_toolkit-3.0.0/README.md

@@ -0,0 +1,150 @@
+# nexus-dev-toolkit
+
+[![PyPI version](https://img.shields.io/pypi/v/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
+[![Python](https://img.shields.io/pypi/pyversions/nexus-dev-toolkit)](https://pypi.org/project/nexus-dev-toolkit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Developer workflow toolkit for AI-assisted development. Gives any team a structured Day 0 scaffold and repeatable Day 1 feature cycle via the EPAV methodology.
+
+---
+
+## Why
+
+Ad-hoc AI prompting doesn't scale. Every dev prompts differently, context drifts, and nobody knows what the AI was told last sprint.
+
+`nexus-dev-toolkit` gives your team a single workflow:
+
+- **Day 0** — scaffold the project once, production-grade, zero credentials needed
+- **Day 1** — every feature follows the same four steps: evaluate → plan → apply → validate
+
+Every skill, every rule, every pattern lives in the project repo — versioned, shared, and enforced.
+
+---
+
+## The Workflow
+
+### Day 0 — `/scaffold` (once per project)
+
+```
+nexus init <project-dir>
+```
+
+Sets up `.claude/commands/`, `.claude/settings.json`, and `knowledge/`. Then in Claude Code:
+
+```
+/scaffold
+```
+
+EVALUATE → PLAN → APPLY → VALIDATE. Produces a production-grade project: correct stack from your arch doc, mock auth, mock data, design system, AGENTS.md — all from your architecture document. Runs with `npm install && npm run dev` (or equivalent) from commit one.
+
+### Day 1 — EPAV (every feature, every sprint)
+
+```
+/evaluate   →   /plan   →   /apply   →   /validate
+```
+
+Each step is a built-in skill in `.claude/commands/`. Every task starts with a row from the dev tasks CSV. Every task ends with acceptance criteria verified.
+
+---
+
+## Install
+
+**Requirements:** Python 3.10+, `uv` (recommended) or `pip`
+
+```bash
+# Recommended
+uv tool install nexus-dev-toolkit
+
+# Or via pip
+pip install nexus-dev-toolkit
+```
+
+---
+
+## Quick Start
+
+```bash
+cd my-project
+nexus init .
+```
+
+Then open the project in Claude Code and type `/scaffold`.
+
+---
+
+## Commands
+
+```bash
+nexus init .                 # set up .claude/commands/ + knowledge/ + .mcp.json
+nexus skill add code-review  # create a custom skill in .claude/commands/
+nexus skill list             # list all skills
+nexus rule add api-standards # create a rule in knowledge/rules/
+nexus rule list              # list all rules
+nexus update                 # update to latest version
+```
+
+---
+
+## What `nexus init` Creates
+
+```
+.claude/
+├── commands/
+│   ├── scaffold.md    ← /scaffold  — Day 0 one-time setup
+│   ├── evaluate.md    ← /evaluate  — orient on a task
+│   ├── plan.md        ← /plan      — blueprint, no code
+│   ├── apply.md       ← /apply     — implement the plan
+│   ├── validate.md    ← /validate  — verify acceptance criteria
+│   └── epav.md        ← /epav      — full cycle guide
+└── settings.json      ← PostToolUse hook: graphify auto-updates after every file edit
+knowledge/
+├── rules/             ← coding standards, arch decisions
+├── patterns/          ← reusable implementation patterns
+├── prompts/dev/       ← task prompt templates
+└── retros/            ← retrospective notes
+.mcp.json              ← MCP server config
+```
+
+---
+
+## MCP Server
+
+```json
+{
+  "mcpServers": {
+    "nexus": {
+      "command": "uvx",
+      "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"]
+    }
+  }
+}
+```
+
+`nexus init` writes `.mcp.json` automatically.
+
+### MCP Tools
+
+| Tool | Purpose |
+|---|---|
+| `ingest_architecture_doc` | Load arch doc → `knowledge/rules/arch-summary.md` |
+| `load_task` | Load a CSV task row into context |
+| `generate_project_rules` | Generate `AGENTS.md` from arch doc |
+| `resolve_package_versions` | Resolve exact package versions via real package manager |
+
+---
+
+## Custom Skills
+
+```bash
+nexus skill add my-code-review
+# Edit .claude/commands/my-code-review.md
+# Type /my-code-review in Claude Code
+```
+
+Custom skills live alongside built-in skills in `.claude/commands/` — versioned in your repo, shared across the team.
+
+---
+
+## License
+
+[MIT](LICENSE)

nexus_dev_toolkit-3.0.0/nexus_cli.py

@@ -0,0 +1,292 @@
+import json
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+app = typer.Typer(name="nexus", no_args_is_help=True, help="nexus-dev-toolkit — LLM-agnostic developer workflow toolkit")
+skill_app = typer.Typer(name="skill", no_args_is_help=True, help="Manage skills in .claude/commands/")
+rule_app = typer.Typer(name="rule", no_args_is_help=True, help="Manage rules in knowledge/rules/")
+app.add_typer(skill_app, name="skill")
+app.add_typer(rule_app, name="rule")
+
+console = Console()
+
+# ── Built-in skills shipped with the package ──────────────────────────────────
+
+_SKILLS_SRC = Path(__file__).parent / "tools" / "epav" / "skills"
+
+_BUILTIN_SKILLS = [
+    "scaffold.md",
+    "evaluate.md",
+    "plan.md",
+    "apply.md",
+    "validate.md",
+    "epav.md",
+]
+
+# ── .claude/settings.json ────────────────────────────────────────────────────
+
+_CLAUDE_SETTINGS = {
+    "hooks": {
+        "PostToolUse": [
+            {
+                "matcher": ".*",
+                "hooks": [
+                    {
+                        "type": "command",
+                        "command": "graphify update . --force 2>/dev/null || true"
+                    }
+                ]
+            }
+        ]
+    }
+}
+
+# ── knowledge/ scaffold ───────────────────────────────────────────────────────
+
+_KNOWLEDGE_DIRS = [
+    "knowledge/rules",
+    "knowledge/patterns",
+    "knowledge/prompts/dev",
+    "knowledge/retros",
+]
+
+# ── MCP config ────────────────────────────────────────────────────────────────
+
+_MCP_BLOCK = {
+    "nexus": {
+        "command": "uvx",
+        "args": ["--refresh", "--from", "nexus-dev-toolkit", "nexus-mcp"],
+    }
+}
+
+
+def _init_project(project_dir: Path) -> list[str]:
+    """
+    nexus init — sets up:
+      .claude/commands/     ← built-in skills
+      .claude/settings.json ← PostToolUse graphify hook
+      knowledge/            ← empty scaffold
+    """
+    created = []
+
+    # .claude/commands/ — copy built-in skills
+    commands_dir = project_dir / ".claude" / "commands"
+    commands_dir.mkdir(parents=True, exist_ok=True)
+
+    for skill_name in _BUILTIN_SKILLS:
+        src = _SKILLS_SRC / skill_name
+        dest = commands_dir / skill_name
+        if src.exists() and not dest.exists():
+            shutil.copy2(src, dest)
+            created.append(f".claude/commands/{skill_name}")
+
+    # .claude/settings.json — PostToolUse graphify hook
+    settings_path = project_dir / ".claude" / "settings.json"
+    if not settings_path.exists():
+        settings_path.write_text(json.dumps(_CLAUDE_SETTINGS, indent=2))
+        created.append(".claude/settings.json")
+
+    # knowledge/ scaffold
+    for d in _KNOWLEDGE_DIRS:
+        target = project_dir / d
+        target.mkdir(parents=True, exist_ok=True)
+
+    return created
+
+
+def _write_mcp_config(project_dir: Path) -> str:
+    mcp_path = project_dir / ".mcp.json"
+    existing: dict = {}
+    if mcp_path.exists():
+        try:
+            existing = json.loads(mcp_path.read_text())
+        except Exception:
+            pass
+    existing.setdefault("mcpServers", {}).update(_MCP_BLOCK)
+    mcp_path.write_text(json.dumps(existing, indent=2))
+    return ".mcp.json"
+
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+@app.command()
+def init(
+    project_dir: str = typer.Argument(".", help="Project directory to initialize"),
+) -> None:
+    """Initialize .claude/commands/, .claude/settings.json, and knowledge/ in a project."""
+    root = Path(project_dir).resolve()
+    console.print(f"\n  [cyan]▶[/cyan]  Initializing nexus in [bold]{root}[/bold]\n")
+
+    created = _init_project(root)
+    for f in created:
+        console.print(f"  [green]✓[/green]  {f}")
+
+    if not created:
+        console.print("  [yellow]·[/yellow]  Already initialized — nothing to do")
+        return
+
+    mcp = _write_mcp_config(root)
+    console.print(f"  [green]✓[/green]  {mcp}")
+
+    console.print(f"\n  [bold green]Done.[/bold green] Open [bold]{root}[/bold] in Claude Code and type [cyan]/scaffold[/cyan]\n")
+
+
+@app.command()
+def update() -> None:
+    """Update nexus-dev-toolkit to the latest version."""
+    console.print("\n  [cyan]▶[/cyan]  Updating nexus-dev-toolkit…\n")
+    if shutil.which("uv"):
+        subprocess.run(["uv", "tool", "upgrade", "nexus-dev-toolkit"])
+    else:
+        subprocess.run([sys.executable, "-m", "pip", "install", "--upgrade", "nexus-dev-toolkit"])
+    console.print("\n  [green]✓[/green]  Done.\n")
+
+
+# ── skill subcommands ─────────────────────────────────────────────────────────
+
+_SKILL_TEMPLATE = """\
+# /{name}
+
+**{name}** — describe what this skill does.
+
+## When to use
+
+Describe the trigger or context.
+
+## Steps
+
+### 1 — First step
+
+What to do.
+
+### 2 — Second step
+
+What to do next.
+
+### 3 — Output
+
+What the AI should produce when done.
+"""
+
+
+@skill_app.command("add")
+def skill_add(
+    name: str = typer.Argument(..., help="Skill name (e.g. 'code-review')"),
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """Create a new skill in .claude/commands/."""
+    root = Path(project_dir).resolve()
+    dest = root / ".claude" / "commands" / f"{name}.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if dest.exists():
+        console.print(f"  [yellow]·[/yellow]  .claude/commands/{name}.md already exists")
+        return
+
+    dest.write_text(_SKILL_TEMPLATE.format(name=name), encoding="utf-8")
+    console.print(f"  [green]✓[/green]  Created .claude/commands/{name}.md")
+    console.print(f"  [dim]Edit it and type [cyan]/{name}[/cyan] in Claude Code.[/dim]")
+
+
+@skill_app.command("list")
+def skill_list(
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """List all skills in .claude/commands/."""
+    root = Path(project_dir).resolve()
+    commands_dir = root / ".claude" / "commands"
+
+    if not commands_dir.exists():
+        console.print("  [yellow]·[/yellow]  No .claude/commands/ found. Run [cyan]nexus init[/cyan] first.")
+        return
+
+    skills = sorted(commands_dir.glob("*.md"))
+    if not skills:
+        console.print("  [yellow]·[/yellow]  No skills yet. Run [cyan]nexus skill add <name>[/cyan]")
+        return
+
+    table = Table(show_header=True, header_style="dim")
+    table.add_column("Skill", style="cyan")
+    table.add_column("Source")
+
+    builtins = set(_BUILTIN_SKILLS)
+    for s in skills:
+        source = "built-in" if s.name in builtins else "custom"
+        table.add_row(f"/{s.stem}", source)
+
+    console.print(table)
+
+
+# ── rule subcommands ──────────────────────────────────────────────────────────
+
+_RULE_TEMPLATE = """\
+# {name}
+
+_Project rule — read by AI tools via AGENTS.md._
+
+## Rules
+
+- Rule one
+- Rule two
+- Rule three
+
+## Rationale
+
+Why these rules exist.
+"""
+
+
+@rule_app.command("add")
+def rule_add(
+    name: str = typer.Argument(..., help="Rule name (e.g. 'api-standards')"),
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """Create a new rule in knowledge/rules/."""
+    root = Path(project_dir).resolve()
+    dest = root / "knowledge" / "rules" / f"{name}.md"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+
+    if dest.exists():
+        console.print(f"  [yellow]·[/yellow]  knowledge/rules/{name}.md already exists")
+        return
+
+    dest.write_text(_RULE_TEMPLATE.format(name=name), encoding="utf-8")
+    console.print(f"  [green]✓[/green]  Created knowledge/rules/{name}.md")
+
+
+@rule_app.command("list")
+def rule_list(
+    project_dir: str = typer.Option(".", "--dir", "-d"),
+) -> None:
+    """List all rules in knowledge/rules/."""
+    root = Path(project_dir).resolve()
+    rules_dir = root / "knowledge" / "rules"
+
+    if not rules_dir.exists():
+        console.print("  [yellow]·[/yellow]  No knowledge/rules/ found. Run [cyan]nexus init[/cyan] first.")
+        return
+
+    rules = sorted(rules_dir.glob("*.md"))
+    if not rules:
+        console.print("  [yellow]·[/yellow]  No rules yet. Run [cyan]nexus rule add <name>[/cyan]")
+        return
+
+    table = Table(show_header=True, header_style="dim")
+    table.add_column("Rule", style="cyan")
+    for r in rules:
+        table.add_row(r.stem)
+    console.print(table)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()