coprogrammer 0.1.0__tar.gz

coprogrammer-0.1.0/LICENSE

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

coprogrammer-0.1.0/PKG-INFO

@@ -0,0 +1,250 @@
+Metadata-Version: 2.4
+Name: coprogrammer
+Version: 0.1.0
+Summary: Open protocol and toolkit for semantic integration in multi-agent software development.
+Author: Qiu Guanzong
+License: MIT License
+        
+        Copyright (c) 2026 Qiu Guanzong
+        
+        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.
+        
+Project-URL: Homepage, https://github.com/QIU-Guanzong/CoProgrammer
+Project-URL: Repository, https://github.com/QIU-Guanzong/CoProgrammer
+Project-URL: Issues, https://github.com/QIU-Guanzong/CoProgrammer/issues
+Keywords: ai,software-development,multi-agent,merge,code-review
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# CoProgrammer
+
+CoProgrammer is an open protocol and toolkit for multi-agent software
+development in the AI coding era.
+
+CoProgrammer 同时支持中文团队协作场景：PR 分支消化报告可以用
+`zh-CN` 输出，也可以通过仓库变量切回英文。
+
+The project starts from one practical belief:
+
+> AI-era merging is not only a text conflict problem. It is a semantic
+> integration problem.
+
+When several humans and AI agents work in parallel, the hard part is no longer
+choosing one side of a merge conflict. The hard part is understanding what each
+branch learned, preserving the useful insight, discarding noise, and rebuilding
+the smallest safe patch on top of the current main branch.
+
+## Where CoProgrammer Sits
+
+CoProgrammer is **not** another parallel-agent orchestrator. It is the missing
+layer between orchestrators and the merge queue:
+
+```text
+UPSTREAM      agent runtimes & orchestrators
+              (Conductor, Sculptor, Vibe Kanban, Claude Squad,
+               Codex, Copilot Cloud Agent, OpenHands, ...)
+              → produce parallel branches
+                      │
+COPROGRAMMER  integration & governance layer
+              protocol → telemetry → conflict forecast →
+              branch digest → integration plan →
+              minimal patch → integration record → policy update
+                      │
+DOWNSTREAM    landing infrastructure
+              (Merge Queue / Merge Trains / Mergify / Graphite,
+               CI, CODEOWNERS, branch protection)
+```
+
+Orchestrators solve "run N agents in parallel without stepping on each other."
+CoProgrammer solves "when N branches come back, decide what deserves to reach
+`main`, and rebuild it safely under main-branch constraints." See
+`docs/ORCHESTRATOR_INTEGRATION.md` for concrete hookup recipes.
+
+## Core Loop
+
+CoProgrammer organizes collaboration as a continuous loop:
+
+1. **Protocol before coding**: define main-branch principles, module
+   boundaries, shared contracts, protected files, and agent permissions.
+2. **Telemetry during coding**: agents publish heartbeats, contract changes,
+   current file ownership, experiments, and blockers.
+3. **Digest after coding**: a feature branch is summarized by intent, core
+   contribution, noise, contract changes, risks, and integration plan.
+4. **Semantic integration**: instead of directly merging a large AI branch, an
+   integration patch is rebuilt from latest `main` under main-branch
+   constraints.
+5. **Validation and feedback**: tests, contract checks, owner review, and merge
+   records update the protocol for the next cycle.
+
+## Repository Map
+
+```text
+.
+├── docs/                 Research route, framework, and MVP design
+├── protocols/            Human-readable collaboration protocols
+├── research/             Structured research leads and prior-art data
+├── schemas/              JSON schemas for machine-readable agent artifacts
+├── templates/            Task, heartbeat, digest, and integration templates
+├── src/coprogrammer/     First CLI scaffold
+├── tests/                Unit tests for the CLI scaffold
+├── AGENTS.md             Minimal stable instructions for coding agents
+├── .coprogrammer.json    Project policy config
+└── .github/              PR template, issue templates, CI, and PR digest workflow
+```
+
+Start with:
+
+- `docs/COORDINATION_LIFECYCLE.md` for the before/during/after collaboration
+  loop: project covenant, Manager Plane synchronization, and post-PR semantic
+  integration;
+- `docs/ECOSYSTEM_EXTENSION_STRATEGY.md` for the research method and MCP,
+  skill, plugin, GitHub automation, and open-source library integration plan;
+- `docs/PLUGIN_QUICKSTART.md` for installing and using the repo-local
+  CoProgrammer Codex plugin;
+- `docs/COMPREHENSIVE_RESEARCH_PLAN.md` for the research program and six-week sprint;
+- `docs/RESEARCH_UPDATE_2026-05-25.md` for the latest Manager Plane evidence update;
+- `docs/RESEARCH_PROTOCOL.md` for how to capture and evaluate research leads;
+- `docs/FAILURE_TAXONOMY.md` for the failure modes CoProgrammer targets;
+- `docs/RESEARCH_LANDSCAPE.md` for current tool landscape and gaps;
+- `docs/OPEN_SOURCE_SCAN.md` for adjacent open-source projects and reusable features;
+- `docs/FEATURE_GAP_MATRIX.md` for product-level comparison;
+- `docs/DISCUSSIONS.md` for discussion categories and research intake;
+- `docs/ARCHITECTURE.md` for the system architecture;
+- `docs/MANAGER_PLANE.md` for the cloud/self-hosted control plane hypothesis;
+- `docs/MANAGER_API_SKETCH.md` for the first Manager API surface;
+- `docs/EVENT_LOG_PROTOTYPE.md` for the local Manager Plane prototype;
+- `docs/AGENT_RUNTIME_INTEROP.md` for integrating with Codex, Copilot, OpenHands, and other runtimes;
+- `docs/CONTEXT_FILE_STRATEGY.md` for keeping `AGENTS.md` small and structured state separate;
+- `docs/INTEGRATION_PATCH_DESIGN.md` for the minimal-patch reconstruction design;
+- `docs/MODEL_ROUTING_POLICY.md` for routing simple work to `codex-5.3` and high-risk work to review;
+- `docs/HIGH_STAR_PROJECT_SCAN_2026-05-26.md` for high-star project patterns to borrow;
+- `docs/FRAMEWORK.md` for the research framework;
+- `docs/ORCHESTRATOR_INTEGRATION.md` for feeding Conductor, Sculptor, Vibe
+  Kanban, and cloud-agent branches into CoProgrammer;
+- `docs/STRATEGY_MEMO_2026-06-10.md` for the latest positioning and priority
+  decisions;
+- `docs/EVAL_PLAN.md` for the AgenticFlict-based evaluation plan;
+- `ACKNOWLEDGMENTS.md` for the projects we learn from and how we credit them.
+
+## Install (pick your surface)
+
+CoProgrammer ships one core through several thin wrappers — use whichever
+your stack already speaks (details: `docs/DISTRIBUTION_STRATEGY.md`):
+
+**MCP server** (Claude Code, Codex, Cursor, any MCP client):
+
+```json
+{ "mcpServers": { "coprogrammer": {
+    "command": "uvx", "args": ["coprogrammer", "mcp", "serve"] } } }
+```
+
+Tools exposed: `digest_branch`, `manager_status`, `manager_forecast`,
+`lease_request`, `heartbeat`, `contract_propose`.
+
+**Agent Skills** (SKILL.md open standard — Claude Code, Codex CLI, Gemini
+CLI, Copilot, Cursor, 35+ tools): copy `plugins/coprogrammer/skills/*` into
+your agent's skills directory.
+
+**GitHub Action** (PR branch digest, zero setup):
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: QIU-Guanzong/CoProgrammer@v0
+  with: { language: zh-CN }
+```
+
+**CLI**: `pipx install coprogrammer` (or from source:
+`python -m pip install -e .`).
+
+**Codex plugin**: `codex plugin marketplace add <this repo>` — see
+`docs/PLUGIN_QUICKSTART.md`.
+
+## First MVP
+
+The first useful version is a **Branch Digest Bot**:
+
+- reads a PR diff and commit history;
+- detects contract-sensitive files and architecture risk signals;
+- generates a branch digest draft;
+- asks reviewers to approve an integration plan before merging;
+- keeps direct AI-generated mega-branches out of `main`.
+
+The first GitHub Actions version is included in
+`.github/workflows/pr-digest.yml`. It generates `branch-digest.md`, uploads it
+as an artifact, and updates a stable PR comment for same-repository PRs.
+
+This repository already contains a minimal local CLI prototype:
+
+```bash
+python -m coprogrammer digest --base origin/main --head HEAD --output branch-digest.md
+python -m coprogrammer digest --base origin/main --head HEAD --language zh-CN
+python -m coprogrammer digest --base origin/main --working-tree
+python -m coprogrammer config validate
+python -m coprogrammer agents check
+python -m coprogrammer manifest validate templates/change-manifest.json
+python -m coprogrammer integration-plan validate templates/integration-plan.json
+python -m coprogrammer heartbeat new --agent agent-a --task "Implement login API"
+python -m coprogrammer manager lease request --holder agent-a --pattern "src/api/**"
+python -m coprogrammer manager contract propose --proposer agent-a --kind api --name "POST /login" --summary "Add login endpoint"
+python -m coprogrammer manager forecast --base origin/main --fail-on-conflict
+python -m coprogrammer manager status
+```
+
+Language can also be controlled by `COPROGRAMMER_LANGUAGE=en|zh-CN`.
+
+For local development:
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+## Project Goals
+
+- Create an open protocol for AI-assisted multi-agent collaboration.
+- Make branch intent, contracts, and insights first-class artifacts.
+- Reduce merge conflicts by forecasting ownership and contract collisions early.
+- Preserve useful experiments without merging noisy generated code.
+- Help reviewers inspect integration plans instead of massive raw diffs.
+
+## Non-Goals
+
+- CoProgrammer is not a replacement for Git, GitHub, GitLab, or CI.
+- CoProgrammer does not blindly auto-merge AI output.
+- CoProgrammer does not treat formatting churn, dependency upgrades, and feature
+  logic as the same kind of change.
+
+## Status
+
+This is an early research and tooling scaffold. The current focus is:
+
+1. protocol design;
+2. branch digest format;
+3. lightweight CLI;
+4. GitHub Action integration;
+5. project policy and risk scoring;
+6. later: semantic integration bot and multi-agent orchestrator.

coprogrammer-0.1.0/README.md

@@ -0,0 +1,209 @@
+# CoProgrammer
+
+CoProgrammer is an open protocol and toolkit for multi-agent software
+development in the AI coding era.
+
+CoProgrammer 同时支持中文团队协作场景：PR 分支消化报告可以用
+`zh-CN` 输出，也可以通过仓库变量切回英文。
+
+The project starts from one practical belief:
+
+> AI-era merging is not only a text conflict problem. It is a semantic
+> integration problem.
+
+When several humans and AI agents work in parallel, the hard part is no longer
+choosing one side of a merge conflict. The hard part is understanding what each
+branch learned, preserving the useful insight, discarding noise, and rebuilding
+the smallest safe patch on top of the current main branch.
+
+## Where CoProgrammer Sits
+
+CoProgrammer is **not** another parallel-agent orchestrator. It is the missing
+layer between orchestrators and the merge queue:
+
+```text
+UPSTREAM      agent runtimes & orchestrators
+              (Conductor, Sculptor, Vibe Kanban, Claude Squad,
+               Codex, Copilot Cloud Agent, OpenHands, ...)
+              → produce parallel branches
+                      │
+COPROGRAMMER  integration & governance layer
+              protocol → telemetry → conflict forecast →
+              branch digest → integration plan →
+              minimal patch → integration record → policy update
+                      │
+DOWNSTREAM    landing infrastructure
+              (Merge Queue / Merge Trains / Mergify / Graphite,
+               CI, CODEOWNERS, branch protection)
+```
+
+Orchestrators solve "run N agents in parallel without stepping on each other."
+CoProgrammer solves "when N branches come back, decide what deserves to reach
+`main`, and rebuild it safely under main-branch constraints." See
+`docs/ORCHESTRATOR_INTEGRATION.md` for concrete hookup recipes.
+
+## Core Loop
+
+CoProgrammer organizes collaboration as a continuous loop:
+
+1. **Protocol before coding**: define main-branch principles, module
+   boundaries, shared contracts, protected files, and agent permissions.
+2. **Telemetry during coding**: agents publish heartbeats, contract changes,
+   current file ownership, experiments, and blockers.
+3. **Digest after coding**: a feature branch is summarized by intent, core
+   contribution, noise, contract changes, risks, and integration plan.
+4. **Semantic integration**: instead of directly merging a large AI branch, an
+   integration patch is rebuilt from latest `main` under main-branch
+   constraints.
+5. **Validation and feedback**: tests, contract checks, owner review, and merge
+   records update the protocol for the next cycle.
+
+## Repository Map
+
+```text
+.
+├── docs/                 Research route, framework, and MVP design
+├── protocols/            Human-readable collaboration protocols
+├── research/             Structured research leads and prior-art data
+├── schemas/              JSON schemas for machine-readable agent artifacts
+├── templates/            Task, heartbeat, digest, and integration templates
+├── src/coprogrammer/     First CLI scaffold
+├── tests/                Unit tests for the CLI scaffold
+├── AGENTS.md             Minimal stable instructions for coding agents
+├── .coprogrammer.json    Project policy config
+└── .github/              PR template, issue templates, CI, and PR digest workflow
+```
+
+Start with:
+
+- `docs/COORDINATION_LIFECYCLE.md` for the before/during/after collaboration
+  loop: project covenant, Manager Plane synchronization, and post-PR semantic
+  integration;
+- `docs/ECOSYSTEM_EXTENSION_STRATEGY.md` for the research method and MCP,
+  skill, plugin, GitHub automation, and open-source library integration plan;
+- `docs/PLUGIN_QUICKSTART.md` for installing and using the repo-local
+  CoProgrammer Codex plugin;
+- `docs/COMPREHENSIVE_RESEARCH_PLAN.md` for the research program and six-week sprint;
+- `docs/RESEARCH_UPDATE_2026-05-25.md` for the latest Manager Plane evidence update;
+- `docs/RESEARCH_PROTOCOL.md` for how to capture and evaluate research leads;
+- `docs/FAILURE_TAXONOMY.md` for the failure modes CoProgrammer targets;
+- `docs/RESEARCH_LANDSCAPE.md` for current tool landscape and gaps;
+- `docs/OPEN_SOURCE_SCAN.md` for adjacent open-source projects and reusable features;
+- `docs/FEATURE_GAP_MATRIX.md` for product-level comparison;
+- `docs/DISCUSSIONS.md` for discussion categories and research intake;
+- `docs/ARCHITECTURE.md` for the system architecture;
+- `docs/MANAGER_PLANE.md` for the cloud/self-hosted control plane hypothesis;
+- `docs/MANAGER_API_SKETCH.md` for the first Manager API surface;
+- `docs/EVENT_LOG_PROTOTYPE.md` for the local Manager Plane prototype;
+- `docs/AGENT_RUNTIME_INTEROP.md` for integrating with Codex, Copilot, OpenHands, and other runtimes;
+- `docs/CONTEXT_FILE_STRATEGY.md` for keeping `AGENTS.md` small and structured state separate;
+- `docs/INTEGRATION_PATCH_DESIGN.md` for the minimal-patch reconstruction design;
+- `docs/MODEL_ROUTING_POLICY.md` for routing simple work to `codex-5.3` and high-risk work to review;
+- `docs/HIGH_STAR_PROJECT_SCAN_2026-05-26.md` for high-star project patterns to borrow;
+- `docs/FRAMEWORK.md` for the research framework;
+- `docs/ORCHESTRATOR_INTEGRATION.md` for feeding Conductor, Sculptor, Vibe
+  Kanban, and cloud-agent branches into CoProgrammer;
+- `docs/STRATEGY_MEMO_2026-06-10.md` for the latest positioning and priority
+  decisions;
+- `docs/EVAL_PLAN.md` for the AgenticFlict-based evaluation plan;
+- `ACKNOWLEDGMENTS.md` for the projects we learn from and how we credit them.
+
+## Install (pick your surface)
+
+CoProgrammer ships one core through several thin wrappers — use whichever
+your stack already speaks (details: `docs/DISTRIBUTION_STRATEGY.md`):
+
+**MCP server** (Claude Code, Codex, Cursor, any MCP client):
+
+```json
+{ "mcpServers": { "coprogrammer": {
+    "command": "uvx", "args": ["coprogrammer", "mcp", "serve"] } } }
+```
+
+Tools exposed: `digest_branch`, `manager_status`, `manager_forecast`,
+`lease_request`, `heartbeat`, `contract_propose`.
+
+**Agent Skills** (SKILL.md open standard — Claude Code, Codex CLI, Gemini
+CLI, Copilot, Cursor, 35+ tools): copy `plugins/coprogrammer/skills/*` into
+your agent's skills directory.
+
+**GitHub Action** (PR branch digest, zero setup):
+
+```yaml
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 }
+- uses: QIU-Guanzong/CoProgrammer@v0
+  with: { language: zh-CN }
+```
+
+**CLI**: `pipx install coprogrammer` (or from source:
+`python -m pip install -e .`).
+
+**Codex plugin**: `codex plugin marketplace add <this repo>` — see
+`docs/PLUGIN_QUICKSTART.md`.
+
+## First MVP
+
+The first useful version is a **Branch Digest Bot**:
+
+- reads a PR diff and commit history;
+- detects contract-sensitive files and architecture risk signals;
+- generates a branch digest draft;
+- asks reviewers to approve an integration plan before merging;
+- keeps direct AI-generated mega-branches out of `main`.
+
+The first GitHub Actions version is included in
+`.github/workflows/pr-digest.yml`. It generates `branch-digest.md`, uploads it
+as an artifact, and updates a stable PR comment for same-repository PRs.
+
+This repository already contains a minimal local CLI prototype:
+
+```bash
+python -m coprogrammer digest --base origin/main --head HEAD --output branch-digest.md
+python -m coprogrammer digest --base origin/main --head HEAD --language zh-CN
+python -m coprogrammer digest --base origin/main --working-tree
+python -m coprogrammer config validate
+python -m coprogrammer agents check
+python -m coprogrammer manifest validate templates/change-manifest.json
+python -m coprogrammer integration-plan validate templates/integration-plan.json
+python -m coprogrammer heartbeat new --agent agent-a --task "Implement login API"
+python -m coprogrammer manager lease request --holder agent-a --pattern "src/api/**"
+python -m coprogrammer manager contract propose --proposer agent-a --kind api --name "POST /login" --summary "Add login endpoint"
+python -m coprogrammer manager forecast --base origin/main --fail-on-conflict
+python -m coprogrammer manager status
+```
+
+Language can also be controlled by `COPROGRAMMER_LANGUAGE=en|zh-CN`.
+
+For local development:
+
+```bash
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+## Project Goals
+
+- Create an open protocol for AI-assisted multi-agent collaboration.
+- Make branch intent, contracts, and insights first-class artifacts.
+- Reduce merge conflicts by forecasting ownership and contract collisions early.
+- Preserve useful experiments without merging noisy generated code.
+- Help reviewers inspect integration plans instead of massive raw diffs.
+
+## Non-Goals
+
+- CoProgrammer is not a replacement for Git, GitHub, GitLab, or CI.
+- CoProgrammer does not blindly auto-merge AI output.
+- CoProgrammer does not treat formatting churn, dependency upgrades, and feature
+  logic as the same kind of change.
+
+## Status
+
+This is an early research and tooling scaffold. The current focus is:
+
+1. protocol design;
+2. branch digest format;
+3. lightweight CLI;
+4. GitHub Action integration;
+5. project policy and risk scoring;
+6. later: semantic integration bot and multi-agent orchestrator.

coprogrammer-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "coprogrammer"
+version = "0.1.0"
+description = "Open protocol and toolkit for semantic integration in multi-agent software development."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Qiu Guanzong" }
+]
+keywords = ["ai", "software-development", "multi-agent", "merge", "code-review"]
+classifiers = [
+  "Development Status :: 2 - Pre-Alpha",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3 :: Only",
+]
+
+[project.urls]
+Homepage = "https://github.com/QIU-Guanzong/CoProgrammer"
+Repository = "https://github.com/QIU-Guanzong/CoProgrammer"
+Issues = "https://github.com/QIU-Guanzong/CoProgrammer/issues"
+
+[project.scripts]
+coprogrammer = "coprogrammer.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

coprogrammer-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

coprogrammer-0.1.0/src/coprogrammer/__init__.py

@@ -0,0 +1,5 @@
+"""CoProgrammer protocol tooling."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"

coprogrammer-0.1.0/src/coprogrammer/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())