pm-engine 1.0.1__tar.gz

pm_engine-1.0.1/.gitignore

@@ -0,0 +1,4 @@
+# Auto-generated files
+/README.md
+/dist/
+/src/pm_engine/templates/

pm_engine-1.0.1/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: pm-engine
+Version: 1.0.1
+Summary: A spec-driven, state-tracked AI coding framework for Gemini CLI
+Requires-Python: >=3.9
+Requires-Dist: rich>=13.0.0
+Requires-Dist: typer>=0.9.0
+Description-Content-Type: text/markdown
+
+# PM Engine 🧠⚡️
+
+**A spec-driven, state-tracked AI coding framework for Gemini CLI.**
+
+AI agents don't suffer from a lack of coding ability; they suffer from a lack of product management and architectural discipline. `pm-engine` acts as a full, elite virtual product team inside your terminal. It forces the AI to challenge your assumptions, lock in a rigorous Product Requirements Document (PRD), and execute code against a rigidly tracked state machine. 
+
+Whether you're scaffolding a fast Astro personal site or building a complex web app, this framework prevents context rot, stops AI hallucination (slop), and manages your project via strict Agile and System Design principles.
+
+---
+
+## 🚀 Quick Start
+
+You can run PM Engine instantly without installing anything globally. Navigate to your project folder and run:
+
+**Using Node (`npm`):**
+```bash
+npx pm-engine init
+```
+**Using Python (uv):**
+```bash
+uvx pm-engine init
+```
+_This will instantly scaffold a `.pm-engine/` directory and inject custom PM personas into your local `.gemini/skills/` folder_.
+
+## 🛠️ The Workflow (Meet the Team)
+Once initialized, start the Gemini CLI in your project directory.
+
+### 1. `/discover` (The Elite Lead PM)
+Start by pitching your idea to the PM agent.
+
+```
+/discover I want to build a real-time collaborative to-do list app.
+```
+_The Lead PM will NOT write code. It will brutally interrogate your assumptions, demanding clear user pain points, KPIs, non-functional requirements (NFRs), and out-of-scope boundaries. Once agreed, it generates a comprehensive `PRD.md`._
+
+### 2. `/plan` (The Staff Engineer)
+Turn the PRD into an architecture blueprint.
+
+```
+/plan
+```
+_The Staff Engineer reads the PRD and defines your database schemas, internal APIs, and architectural decisions (ADRs). It generates a rigid, phase-by-phase execution checklist in `STATE.md`._
+
+### 3. `/execute phase-x` (The Execution Agent)
+Time to build.
+
+```
+/execute phase-1
+```
+_The Execution bot reads the exact, granular tasks for Phase 1 and writes the code sequentially. It aggressively updates checkboxes in `STATE.md` as it works. Because its context is constrained to the active phase, it refuses to hallucinate future features or drift out-of-scope._
+
+### 4. `/review` (The Principal QA Engineer)
+Audit the work.
+
+```
+/review
+```
+_The Principal Engineer audits the code diffs against the `PRD.md` and `STATE.md`. It scans for security flaws, unhandled edge cases, and architectural regressions. If it passes, the Phase is marked as "Complete" in the state matrix._
+
+### 5. `/status` (The Scrum Master Sync)
+Close your laptop for the weekend? When you come back, just type:
+
+```
+/status
+```
+_The Sync Agent reads the state files, remembers exactly where the team left off, briefs you on open blockers, and tells you the exact command to run next to resume velocity._
+
+## 🧠 Architecture: The Dual-Brain System
+PM Engine splits your AI's brain into two distinct, machine-readable halves:
+
+- **The Product Engine (`.pm-engine/product/PRD.md`)**: The persistent memory of what we are building, who we are building it for, and what we are explicitly NOT building. It acts as the ultimate boundary against scope creep.
+- **The Execution Engine (`.pm-engine/state/STATE.md`)**: The rigid state tracker and architecture blueprint. It preserves the context window over long coding sessions by tracking checklists, active files, and blocked dependencies.
+
+## 📦 Manual Installation & Updates
+If you prefer to install the CLI globally instead of using npx/uvx:
+
+### NPM:
+
+```bash
+npm install -g pm-engine
+# To update:
+npm update -g pm-engine
+```
+### UV:
+
+```bash
+uv tool install pm-engine
+# To update:
+uv tool upgrade pm-engine
+```
+
+## 🤝 Contributing
+PM Engine is built as a monorepo to support both Node and Python ecosystems efficiently.
+
+All AI system prompts live in the root `core-prompts/` directory. Both the JS (npm) and Python (uv) CLI wrappers pull from this single source of truth during their respective build processes. If you want to improve how the PM team behaves, tweak the persona templates in `core-prompts/`!

pm_engine-1.0.1/README.md

@@ -0,0 +1,95 @@
+# PM Engine 🧠⚡️
+
+**A spec-driven, state-tracked AI coding framework for Gemini CLI.**
+
+AI agents don't suffer from a lack of coding ability; they suffer from a lack of product management and architectural discipline. `pm-engine` acts as a full, elite virtual product team inside your terminal. It forces the AI to challenge your assumptions, lock in a rigorous Product Requirements Document (PRD), and execute code against a rigidly tracked state machine. 
+
+Whether you're scaffolding a fast Astro personal site or building a complex web app, this framework prevents context rot, stops AI hallucination (slop), and manages your project via strict Agile and System Design principles.
+
+---
+
+## 🚀 Quick Start
+
+You can run PM Engine instantly without installing anything globally. Navigate to your project folder and run:
+
+**Using Node (`npm`):**
+```bash
+npx pm-engine init
+```
+**Using Python (uv):**
+```bash
+uvx pm-engine init
+```
+_This will instantly scaffold a `.pm-engine/` directory and inject custom PM personas into your local `.gemini/skills/` folder_.
+
+## 🛠️ The Workflow (Meet the Team)
+Once initialized, start the Gemini CLI in your project directory.
+
+### 1. `/discover` (The Elite Lead PM)
+Start by pitching your idea to the PM agent.
+
+```
+/discover I want to build a real-time collaborative to-do list app.
+```
+_The Lead PM will NOT write code. It will brutally interrogate your assumptions, demanding clear user pain points, KPIs, non-functional requirements (NFRs), and out-of-scope boundaries. Once agreed, it generates a comprehensive `PRD.md`._
+
+### 2. `/plan` (The Staff Engineer)
+Turn the PRD into an architecture blueprint.
+
+```
+/plan
+```
+_The Staff Engineer reads the PRD and defines your database schemas, internal APIs, and architectural decisions (ADRs). It generates a rigid, phase-by-phase execution checklist in `STATE.md`._
+
+### 3. `/execute phase-x` (The Execution Agent)
+Time to build.
+
+```
+/execute phase-1
+```
+_The Execution bot reads the exact, granular tasks for Phase 1 and writes the code sequentially. It aggressively updates checkboxes in `STATE.md` as it works. Because its context is constrained to the active phase, it refuses to hallucinate future features or drift out-of-scope._
+
+### 4. `/review` (The Principal QA Engineer)
+Audit the work.
+
+```
+/review
+```
+_The Principal Engineer audits the code diffs against the `PRD.md` and `STATE.md`. It scans for security flaws, unhandled edge cases, and architectural regressions. If it passes, the Phase is marked as "Complete" in the state matrix._
+
+### 5. `/status` (The Scrum Master Sync)
+Close your laptop for the weekend? When you come back, just type:
+
+```
+/status
+```
+_The Sync Agent reads the state files, remembers exactly where the team left off, briefs you on open blockers, and tells you the exact command to run next to resume velocity._
+
+## 🧠 Architecture: The Dual-Brain System
+PM Engine splits your AI's brain into two distinct, machine-readable halves:
+
+- **The Product Engine (`.pm-engine/product/PRD.md`)**: The persistent memory of what we are building, who we are building it for, and what we are explicitly NOT building. It acts as the ultimate boundary against scope creep.
+- **The Execution Engine (`.pm-engine/state/STATE.md`)**: The rigid state tracker and architecture blueprint. It preserves the context window over long coding sessions by tracking checklists, active files, and blocked dependencies.
+
+## 📦 Manual Installation & Updates
+If you prefer to install the CLI globally instead of using npx/uvx:
+
+### NPM:
+
+```bash
+npm install -g pm-engine
+# To update:
+npm update -g pm-engine
+```
+### UV:
+
+```bash
+uv tool install pm-engine
+# To update:
+uv tool upgrade pm-engine
+```
+
+## 🤝 Contributing
+PM Engine is built as a monorepo to support both Node and Python ecosystems efficiently.
+
+All AI system prompts live in the root `core-prompts/` directory. Both the JS (npm) and Python (uv) CLI wrappers pull from this single source of truth during their respective build processes. If you want to improve how the PM team behaves, tweak the persona templates in `core-prompts/`!

pm_engine-1.0.1/build.py

@@ -0,0 +1,24 @@
+import shutil
+from pathlib import Path
+
+def bundle():
+    print("📦 Bundling core-prompts for Python packaging...")
+    root_dir = Path(__file__).parent.parent.parent
+    source_dir = root_dir / "core-prompts"
+    dest_dir = Path(__file__).parent / "src" / "pm_engine" / "templates"
+
+    if dest_dir.exists():
+        shutil.rmtree(dest_dir)
+    
+    shutil.copytree(source_dir, dest_dir)
+    print("✓ Templates bundled successfully into src/pm_engine/templates")
+    
+    # Copy README.md for packaging
+    readme_src = root_dir / "README.md"
+    readme_dest = Path(__file__).parent / "README.md"
+    if readme_src.exists():
+        shutil.copy(readme_src, readme_dest)
+        print("✓ README.md copied for packaging")
+
+if __name__ == "__main__":
+    bundle()

pm_engine-1.0.1/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "pm-engine"
+version = "1.0.1"
+description = "A spec-driven, state-tracked AI coding framework for Gemini CLI"
+readme = "README.md"
+requires-python = ">=3.9"
+dependencies = [
+    "typer>=0.9.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+pm-engine = "pm_engine.cli:app"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pm_engine"]

pm_engine-1.0.1/src/pm_engine/cli.py

@@ -0,0 +1,21 @@
+import typer
+from rich.console import Console
+from .commands.init import init_project
+
+app = typer.Typer(help="A spec-driven AI coding framework for Gemini CLI")
+console = Console()
+
+@app.command()
+def init():
+    """Scaffold the .pm-engine directory and inject Gemini CLI skills"""
+    console.print("\n[bold blue]🚀 Initializing PM Engine...[/bold blue]\n")
+    try:
+        init_project()
+        console.print("\n[bold green]✨ PM Engine initialized successfully![/bold green]")
+        console.print("[dim]Run[/dim] [cyan]/discover[/cyan] [dim]in Gemini CLI to start your first PM sync.[/dim]\n")
+    except Exception as e:
+        console.print(f"\n[bold red]❌ Initialization failed:[/bold red] {str(e)}")
+        raise typer.Exit(code=1)
+
+if __name__ == "__main__":
+    app()

pm_engine-1.0.1/src/pm_engine/commands/init.py

@@ -0,0 +1,38 @@
+import os
+import shutil
+from pathlib import Path
+from rich.console import Console
+
+console = Console()
+
+def init_project():
+    target_dir = Path.cwd()
+    pm_engine_dir = target_dir / ".pm-engine"
+    gemini_skills_dir = target_dir / ".gemini" / "skills"
+    
+    # In the built package, templates are inside the pm_engine module
+    source_prompts_dir = Path(__file__).parent.parent / "templates"
+
+    console.print("[dim]📁 Creating directory infrastructure...[/dim]")
+    (pm_engine_dir / "product").mkdir(parents=True, exist_ok=True)
+    (pm_engine_dir / "state" / "phases").mkdir(parents=True, exist_ok=True)
+    gemini_skills_dir.mkdir(parents=True, exist_ok=True)
+
+    def copy_template(src_rel, dest_rel):
+        src_file = source_prompts_dir / src_rel
+        dest_file = target_dir / dest_rel
+        
+        if src_file.exists():
+            shutil.copy(src_file, dest_file)
+        else:
+            console.print(f"[bold yellow]⚠️ Missing template:[/bold yellow] {src_file}")
+
+    console.print("[dim]📄 Injecting PM and State templates...[/dim]")
+    copy_template("product/PRD.md.tmpl", ".pm-engine/product/PRD.md")
+    copy_template("state/STATE.md.tmpl", ".pm-engine/state/STATE.md")
+
+    console.print("[dim]🔌 Wiring up Gemini CLI personas...[/dim]")
+    for skill in ["discover", "plan", "execute", "review", "status"]:
+        copy_template(f"skills/{skill}.md.tmpl", f".gemini/skills/{skill}.md")
+
+    console.print("[bold green]✓ Scaffolding complete.[/bold green]")