bpsai-pair 0.2.0__py3-none-any.whl

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/context/agents.md.bak

@@ -0,0 +1,196 @@
+# Agents Guide — AI Pair Coding Playbook
+
+**Purpose:** Make GPT-5 / Claude / CodeX effective partners for {{ cookiecutter.primary_goal }} while improving modularity, maintainability, and testability.
+
+**Audience:** Engineers, Tech Leads, and AI Agents connected to this repo.
+
+---
+
+## 0) Ground Rules (READ FIRST)
+
+* **Single Source of Truth:** This repository and the files in `/context` are canonical for all agent runs.
+* **Safety First:** No destructive ops without backups and a PR. Agents must create `*.bak` or use Git branches.
+* **Tests Before Changes:** Add/extend tests that fail *before* implementing a fix/refactor.
+* **Small, Reviewable Diffs:** Keep changes scoped; open PRs early; link to the relevant roadmap task.
+* **Update Context Every Run:** Always persist “Overall/Last/Next” (see §6) after actions.
+
+---
+
+## 1) Repo Layout & Context Discipline
+
+> Keep the agent’s attention on code that matters. Avoid token waste and blind spots.
+
+* **Project Tree (authoritative sketch):**
+
+  ```
+  .
+  ├─ /src                # Application code
+  ├─ /tests              # Unit/integration tests
+  ├─ /services           # External adapters, API clients
+  ├─ /infra              # IaC / deployment (optional)
+  ├─ /docs               # Human-readable docs
+  ├─ /context            # Agent context files (canonical)
+  │   ├─ development.md
+  │   ├─ agents.md
+  │   ├─ project_tree.md
+  │   └─ directory_notes/
+  ├─ /assets/images      # Large/media (EXCLUDED from agent context)
+  └─ ...
+  ```
+
+* **Explicit Exclusions:** `/assets/images`, `/dist`, `/build`, `/node_modules`, binaries, large JSON/CSV.
+  Agents must **assume these exist** and avoid recommending moves/rewrites.
+
+* **Directory Notes (optional but powerful):**
+  Add `/context/directory_notes/<dir>.md` with:
+
+  * Purpose, entry points, invariants, dependency direction.
+  * “Do/Don’t” for this directory.
+  * Local glossary (domain terms, DTOs).
+  * Known pitfalls.
+
+---
+
+## 2) Branching & PR Conventions
+
+* **Branch names:** `feature/<short-goal>` or `refactor/<module>` or `fix/<ticket-id>`
+* **Create branch from:** `main`
+* **PR template must include:**
+
+  * Goal link to `<PHASE N TASK>`
+  * Risk level (Low/Med/High)
+  * Test plan (automated + manual)
+  * Rollback plan
+  * Context update diff (what changed in `/context` files)
+
+---
+
+## 3) Operating Modes
+
+### A) Non-Scripted (Live Collaboration)
+
+1. Create branch: `git checkout -b feature/<FEATURE>`
+2. Connect agent (Claude or GPT-5) to repo URL.
+3. Attach context: `/context/development.md`, `/context/agents.md`, relevant `/context/directory_notes/*`.
+4. **Prompt:**
+
+   ```
+   PHASE 1 GOAL: <PHASE 1 GOAL>
+   Constraints: preserve public APIs, add tests first, no destructive ops.
+   Output: stepwise plan + minimal diffs per step.
+   ```
+
+### B) Scripted (One-Pass Implementation)
+
+1. Create branch: `git checkout -b feature/<FEATURE>`
+2. Attach **only** relevant context files.
+3. **Prompt:**
+
+   ```
+   Create a comprehensive script/commit plan to accomplish <PHASE 1 GOAL> in one pass.
+   Requirements:
+   - Zero breakage; create backups where needed.
+   - Generate/modify tests first to capture intended behavior.
+   - Respect repo conventions, linting, and formatting.
+   - Produce: (a) ordered commit plan, (b) code patches, (c) updated docs, (d) updated context (see §6).
+   ```
+
+---
+
+## 4) Canonical Prompts
+
+### 4.1 Deep Research (Kickoff)
+
+```
+You are a staff-level engineer embedded in this codebase.
+Objective: Produce a comprehensive plan to improve modularity, maintainability, and achieve {{ cookiecutter.primary_goal }}.
+Deliverables:
+- Architecture review (current vs. target), explicit trade-offs.
+- Refactoring map (by module), dependency inversion opportunities, interface boundaries.
+- Test posture upgrade plan (unit/integration/contract), coverage deltas.
+- Risks, complexity hotspots, and rollback strategies.
+- 3-phase roadmap with measurable outcomes.
+Constraints:
+- Respect exclusions listed in agents.md.
+- Assume assets exist where excluded.
+- Prefer small, reversible changes; maximize seam creation for safe refactors.
+```
+
+### 4.2 Roadmap → Files
+
+```
+Convert the roadmap into:
+- /context/development.md   (engineering tasks, test plans, risks)
+- /context/agents.md        (this file; update Operating Modes, Prompts if needed)
+Ensure clear Phase 1/2/3 breakdown with milestone checklists and acceptance criteria.
+```
+
+### 4.3 Implementation Guardrails (per task)
+
+```
+For TASK: <task-name>
+- Propose minimal diff solution.
+- Add/adjust tests first to lock behavior.
+- Provide code patches and commands to run tests/lints.
+- Call out risks + rollback.
+- Update context loop (Overall/Last/Next).
+```
+
+---
+
+## 5) Testing & Quality Gates
+
+* **Unit tests:** focus on pure logic and interfaces.
+* **Integration tests:** external boundaries (DB, queues, HTTP) via testcontainers/mocks.
+* **Contract tests:** for service clients with provider/consumer pacts if applicable.
+* **Coverage targets:** raise or maintain ≥ <TARGET>% lines/branches where practical.
+* **CI gates:** lint, type-check, build, test, basic security scan (SAST/dep audit).
+
+---
+
+## 6) Context Loop (Mandatory)
+
+Agents **must** persist this block at the end of every session in `/context/development.md` (and in any relevant directory note):
+
+```
+## Context Sync (AUTO-UPDATED)
+Overall goal is: {{ cookiecutter.primary_goal }}
+Last action was: <what changed and why> (commit SHA if available)
+Next action will be: <smallest valuable step with owner>
+Blockers/Risks: <if any>
+```
+
+---
+
+## 7) Failure Modes & Rollback
+
+* **If tests fail:** revert last commit or apply backup. Fix tests first, then code.
+* **If unintended API change:** restore interface, add regression test.
+* **If scope creep:** park in `Phase N Backlog` with rationale.
+
+---
+
+## 8) Example Exclusion Prompt
+
+> *Drop into your agent prompt when large dirs are omitted.*
+
+“Relevant image/media assets exist under `/assets/images` but are intentionally excluded from your context to conserve tokens. **Do not** propose changes that relocate, inline, or re-encode assets. Assume paths referenced in code are valid. Focus your analysis on `/src`, `/services`, and `/tests`. If a change seems to require asset inspection, propose an interface-level abstraction instead.”
+
+---
+
+## 9) Definitions
+
+* **Seam:** a point in code where behavior can be changed without editing the code (e.g., via interface, DI, adapter).
+* **Backwards compatibility window:** period where both old and new APIs coexist with deprecation notices.
+
+---
+
+## 10) Tools & Commands (fill per repo)
+
+* **Install:** `<cmd>`
+* **Format/Lint:** `<cmd>`
+* **Test (unit):** `<cmd>`
+* **Test (integration):** `<cmd>`
+* **Type check:** `<cmd>`
+* **Local CI bundle:** `<cmd>`
+

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/context/development.md

@@ -0,0 +1 @@
+# Development Log\n\n**Phase:** (set by first feature)\n**Primary Goal:** (set by first feature)\n\n## Context Sync (AUTO-UPDATED)\n\n- **Overall goal is:** (set by feature)\n- **Last action was:** (set by feature)\n- **Next action will be:** (set by feature)\n- **Blockers:** (set by feature)\n

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/context/development.md.bak

@@ -0,0 +1,10 @@
+# Development Log
+
+**Phase:** (set by first feature)
+**Primary Goal:** (set by first feature)
+
+## Context Sync (AUTO-UPDATED)
+
+- **Overall goal is:** (set by feature)
+- **Last action was:** (set by feature)
+- **Next action will be:** (set by feature)

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/context/directory_notes/.gitkeep

@@ -0,0 +1 @@
+

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/context/project_tree.md

@@ -0,0 +1,7 @@
+
+# Project Tree (snapshot)
+_Generated: <template init>_
+
+```
+<generated by workflow>
+```

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/prompts/deep_research.yml

@@ -0,0 +1,28 @@
+
+id: deep_research
+version: 0.1.0
+inputs:
+  primary_goal: "<PRIMARY GOAL>"
+  exclusions: ["assets/images", "dist", "build", "node_modules"]
+assumptions:
+  - Excluded paths exist and are valid.
+  - Prefer reversible changes and seam creation.
+output:
+  - architecture_review
+  - refactor_map
+  - test_upgrade_plan
+  - risks_and_rollback
+  - three_phase_roadmap
+prompt: |
+  You are a staff-level engineer embedded in this codebase.
+  Objective: Improve modularity, maintainability, and achieve {{ primary_goal }}.
+  Deliverables:
+    - Architecture review (current vs target) with trade-offs
+    - Refactoring map by module, DI boundaries, interfaces
+    - Test posture upgrade plan (unit/integration/contract)
+    - Risks, hotspots, rollback strategies
+    - 3-phase roadmap with measurable outcomes
+  Constraints:
+    - Respect exclusions: {{ exclusions | join(, ) }}
+    - Assume excluded assets exist
+    - Prefer small, reversible changes; maximize seams

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/prompts/implementation.yml

@@ -0,0 +1,25 @@
+
+id: implementation
+version: 0.1.0
+inputs:
+  phase_goal: "<PHASE 1 GOAL>"
+  guardrails:
+    - "Preserve public APIs unless explicitly approved"
+    - "Add/adjust tests first to lock behavior"
+    - "No destructive ops; create backups or checkpoint commits"
+output:
+  - ordered_commit_plan
+  - code_patches
+  - updated_docs
+  - updated_context
+prompt: |
+  Create a comprehensive commit plan to accomplish {{ phase_goal }} in one pass.
+  Respect guardrails:
+  {% for g in guardrails %}
+  - {{ g }}
+  {% endfor %}
+  Produce:
+  - Ordered commits with messages
+  - Patches per commit
+  - Doc updates
+  - Context Loop update (Overall/Last/Next)

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/prompts/roadmap.yml

@@ -0,0 +1,14 @@
+
+id: roadmap
+version: 0.1.0
+inputs:
+  primary_goal: "<PRIMARY GOAL>"
+  coverage_target:  "<TARGET>%"
+output:
+  - development_md
+  - agents_md_update
+prompt: |
+  Convert the accepted plan into two files:
+  1) /context/development.md — engineering tasks, tests, risks with Phase 1/2/3 breakdown and acceptance criteria; coverage target {{ coverage_target }}.
+  2) /context/agents.md — update Operating Modes/Prompts if needed.
+  Ensure milestones are measurable. Keep diffs small and reversible.

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/scripts/README.md

@@ -0,0 +1,11 @@
+# Scripts directory (intentionally minimal)
+
+This project uses the **PairCoder CLI** (Python) — no Bash scripts required.
+Common commands:
+
+```bash
+bpsai-pair-init
+bpsai-pair feature <name> --type feature|fix|refactor --primary "..." --phase "..."
+bpsai-pair pack --out agent_pack.tgz
+bpsai-pair context-sync --last "..." --next "..." --blockers "..."
+```

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/src/.gitkeep

@@ -0,0 +1 @@
+

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/templates/adr.md

@@ -0,0 +1,19 @@
+
+# Architecture Decision Record Template
+
+**Title:** <ADR Title>
+
+**Status:** Draft | Proposed | Accepted | Deprecated
+
+**Context:**
+_<What is the issue that prompted this decision? Background, forces, requirements>_
+
+**Decision:**
+_<What is the chosen solution? Justify why._>
+
+**Alternatives Considered:**
+- _Option A... (pros/cons)_
+- _Option B..._
+
+**Consequences:**
+_<What becomes easier or harder to do because of this decision? Any follow-up actions?>_

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/templates/directory_note.md

@@ -0,0 +1,17 @@
+
+# Directory Note — <dir>
+
+**Purpose:** <why this directory exists>
+**Entry Points:** <files/modules used externally>
+**Invariants:** <constraints, contracts, side effects>
+**Dependencies:** <allowed deps, forbidden deps>
+
+## Do / Don’t
+- Do: <guideline>
+- Don’t: <pitfall>
+
+## Gotchas
+- <common issues>
+
+## Glossary
+- <term>: <definition>

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/tests/example_contract/README.md

@@ -0,0 +1,3 @@
+# Example Contract Tests (Stub)
+
+Provider/consumer pact tests live here. Populate once services are defined.

bpsai_pair/data/cookiecutter-paircoder/{{cookiecutter.project_slug}}/tests/example_integration/README.md

@@ -0,0 +1,3 @@
+# Example Integration Tests (Stub)
+
+Integration tests for external boundaries (DB, HTTP, queues). Configure testcontainers/mocks when services exist.

bpsai_pair/init_bundled_cli.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+import os, sys, stat, shutil
+from pathlib import Path
+try:
+    from importlib.resources import files as res_files
+except ImportError:
+    from importlib_resources import files as res_files  # py<=3.8 fallback
+
+APP_NAME = "bpsai-pair-init"
+
+def copytree_non_destructive(src: Path, dst: Path) -> None:
+    # copy files/dirs only if missing; never overwrite existing files
+    for root, dirs, files in os.walk(src):
+        rel = Path(root).relative_to(src)
+        out_dir = dst / rel
+        out_dir.mkdir(parents=True, exist_ok=True)
+        for name in files:
+            s = Path(root) / name
+            d = out_dir / name
+            if not d.exists():
+                d.parent.mkdir(parents=True, exist_ok=True)
+                shutil.copy2(s, d)
+    # make scripts executable
+    scripts_dir = dst / "scripts"
+    if scripts_dir.exists():
+        for p in scripts_dir.glob("*.sh"):
+            mode = p.stat().st_mode
+            p.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+
+def main(argv: list[str] | None = None) -> int:
+    argv = argv or sys.argv[1:]
+    # Resolve packaged template '{{cookiecutter.project_slug}}'
+    pkg_root = res_files("bpsai_pair") / "data" / "cookiecutter-paircoder"
+    # Find the one subdir under cookiecutter-paircoder (the cookiecutter slug dir)
+    candidates = [p for p in pkg_root.iterdir() if p.is_dir()]
+    if not candidates:
+        print(f"[{APP_NAME}] ERROR: packaged template not found", file=sys.stderr)
+        return 1
+    template_root = candidates[0]  # '{{cookiecutter.project_slug}}'
+    # copy into current directory without clobber
+    dst = Path(".").resolve()
+    copytree_non_destructive(Path(template_root), dst)
+    print(f"[{APP_NAME}] Initialized repo with bundled scaffolding (non-destructive). Review diffs and commit.")
+    return 0
+
+if __name__ == "__main__":
+    raise SystemExit(main())

bpsai_pair/jsonio.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+import json
+from typing import Any, Dict
+
+def dump(data: Dict[str, Any]) -> str:
+    return json.dumps(data, ensure_ascii=False, indent=2, sort_keys=True)