coprogrammer 0.3.0a1__tar.gz → 0.3.0a2__tar.gz

coprogrammer-0.3.0a2/PKG-INFO

@@ -0,0 +1,210 @@
+Metadata-Version: 2.4
+Name: coprogrammer
+Version: 0.3.0a2
+Summary: Shared tasks, file boundaries and handoffs for coding agents.
+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
+
+**Teamwork for coding agents.**
+
+Shared tasks, file boundaries and durable handoffs for **Codex, Claude Code and
+GitHub Copilot** working in the same Git repository.
+
+[![CI](https://github.com/QIU-Guanzong/CoProgrammer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/QIU-Guanzong/CoProgrammer/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-black)](LICENSE)
+
+[简体中文](README.zh-CN.md) · [Try it](#try-the-preview) ·
+[Two-window walkthrough](docs/GETTING_STARTED.md) ·
+[Connect your client](docs/knowledge/README.md) · [Releases](https://github.com/QIU-Guanzong/CoProgrammer/releases)
+
+## The problem
+
+Codex is changing an API. Claude is updating its callers. Both need to know who
+owns the files, when the upstream task is finished, and what happened before a
+window restarted. Separate Git branches keep edits apart; the collaboration
+still needs shared state.
+
+CoProgrammer records **who owns a task, which paths it covers, what blocks it,
+and what the next window needs to know**. Your coding tools write the code;
+CoProgrammer coordinates their work through a local CLI and MCP server.
+
+| Without a shared record | With CoProgrammer |
+| --- | --- |
+| Two windows try to claim overlapping work | Atomic task claims check owners, worktrees and path leases. |
+| A worker starts before an upstream task finishes | Dependencies keep the task blocked until its prerequisite is done. |
+| A handoff disappears in a terminal | Messages and explicit receipts persist across restarts. |
+| A passing test refers to yesterday's files | Check receipts detect changed content, command, runtime or age. |
+| Another computer has a different checkout | A portable handoff compares package version, HEAD, base and file content. |
+
+## Try the preview
+
+Requires **Python 3.10+** and **Git 2.36+**. Use an active Python virtual environment.
+There are no runtime Python dependencies or model keys needed for the demo.
+
+```sh
+python -m pip install --pre --upgrade coprogrammer
+coprogrammer demo
+```
+
+The demo creates two real Git worktrees, runs task claims, dependency and overlap
+checks, sends a handoff, acknowledges it and completes the tasks. It checks each
+result and cleans up the temporary project. No coding client or model is launched.
+
+An excerpt from an actual run:
+
+```text
+[passed] Create two Git worktrees: Two branches share one repository and one Manager event log.
+[passed] Block unfinished dependencies: Claude cannot claim documentation until the API task is finished.
+[passed] Reject overlapping work: A different worktree cannot claim src/api.py while Codex holds src/**.
+```
+
+[What the demo checks →](docs/DEMO.md)
+
+## Use it in your project
+
+The `start` and `status` entry points require **0.3.0a2+**. Start in a committed Git
+checkout on a named branch. Each coding window should use its own Git worktree.
+Add `.coprogrammer/` to your project's `.gitignore` to keep local runtime state
+out of commits.
+
+```sh
+# In the worktree used by Codex
+coprogrammer start --client codex --session codex-api --task api-v2
+coprogrammer status --session codex-api
+
+# In the separate worktree used by Claude Code
+coprogrammer start --client claude --session claude-ui --task api-v2
+coprogrammer status --session claude-ui
+```
+
+`start` registers this window and previews client setup. It does not launch a
+coding tool or install configuration. Add `--dry-run` to preview registration;
+use `--resume` to explicitly refresh the same registered window after a break.
+Status reads never refresh sessions. Default session freshness lasts five minutes.
+
+In the Codex worktree, create a scoped task and inspect the next action:
+
+```sh
+coprogrammer manager task create --session codex-api --id api-v2   --title 'Update the API' --pattern 'src/api/**' --client codex
+coprogrammer status --session codex-api
+coprogrammer manager task claim --session codex-api --id api-v2
+```
+
+Claims return an ownership token. Use it with the existing guard and finish
+commands; the [two-window walkthrough](docs/GETTING_STARTED.md) covers dependency
+setup, messages, receipts and completion. Status distinguishes repository-wide
+readiness from work eligible for the selected window.
+
+### Connect Codex, Claude Code or Copilot
+
+Preview the project-local Skills, Markdown guidance and MCP configuration:
+
+```sh
+coprogrammer setup --client codex --include-content
+```
+
+Review the output, then explicitly create missing files:
+
+```sh
+coprogrammer setup --client codex --apply
+```
+
+Use `claude` or `copilot` for those clients. Existing project instructions are
+preserved; differing Skills or MCP configuration are reported as conflicts.
+Reload the client and follow its normal project/MCP trust flow. Generated
+configuration alone does not establish a connection.
+
+MCP exposes the same local workflows. `workspace_status` provides the combined
+status view; `task_dispatch` previews eligible tasks. The packaged plugin
+contains six Skills, and the CLI serves twelve read-only Markdown resources.
+[Client setup](docs/knowledge/README.md) · [Plugin installation](docs/PLUGIN_QUICKSTART.md)
+
+## What else can it do?
+
+| Need | Entry point |
+| --- | --- |
+| Inspect work and blockers | `coprogrammer status`; [status guide](docs/GETTING_STARTED.md) |
+| Send and acknowledge handoffs | `manager message`; [communication guide](docs/AGENT_RUNTIME_INTEROP.md) |
+| Check file scope before edits | `manager task guard`; [scheduling guide](docs/MULTI_PLATFORM_QUICKSTART.md) |
+| Detect stale test results | `check run` / `check verify`; [check receipts](docs/VALIDATION_EVIDENCE.md) |
+| Continue on another computer | `manager handoff` / `workspace compare`; [portable handoffs](docs/WORKSPACE_HANDOFF.md) |
+| Review a branch for integration | `digest` / `integration-plan`; [CLI reference](docs/GETTING_STARTED.md#prepare-a-pr) |
+| Request a second opinion | Explicit Claude, GLM or DeepSeek review; [multi-platform guide](docs/MULTI_PLATFORM_QUICKSTART.md) |
+
+## How it fits
+
+Use CoProgrammer when you already run coding agents and need shared ownership,
+communication and review evidence across their worktrees. It complements your
+existing coding tools and GitHub review process.
+
+[gstack](https://github.com/garrytan/gstack) provides opinionated development and
+review workflows; [Beads](https://github.com/gastownhall/beads) provides persistent
+agent work tracking; [Gas Town](https://github.com/gastownhall/gastown) manages
+multi-agent workspaces and orchestration. CoProgrammer focuses on local task
+ownership, path coordination, durable handoffs and inspectable integration
+artifacts through a small Python CLI/MCP package.
+[Comparison and design choices →](docs/research/onboarding-2026-10-12.md)
+
+Local worktrees share a Manager. Independent clones have separate Managers:
+portable handoffs compare context and do not transfer a global lease. Path
+leases are cooperative checks, not filesystem permissions. Check records are
+unauthenticated local evidence. PR approval and merging follow your project's
+normal rules. The demo does not establish native client or live provider connectivity.
+
+## Contribute or get help
+
+[Report a reproducible problem](https://github.com/QIU-Guanzong/CoProgrammer/issues) ·
+[Propose an integration](https://github.com/QIU-Guanzong/CoProgrammer/discussions) ·
+[Contributor guide](CONTRIBUTING.md)
+
+Good first contributions include a small client setup example, a clearer error
+message or a regression for a real worktree conflict. Include the command,
+version, expected result and actual result; remove private code and credentials.
+If CoProgrammer helps your team, a star helps others discover it.
+
+For source development:
+
+```sh
+git clone https://github.com/QIU-Guanzong/CoProgrammer.git
+cd CoProgrammer
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+[MIT license](LICENSE). Preview software; feedback and concrete bug reports are welcome.

coprogrammer-0.3.0a2/README.md

@@ -0,0 +1,169 @@
+# CoProgrammer
+
+**Teamwork for coding agents.**
+
+Shared tasks, file boundaries and durable handoffs for **Codex, Claude Code and
+GitHub Copilot** working in the same Git repository.
+
+[![CI](https://github.com/QIU-Guanzong/CoProgrammer/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/QIU-Guanzong/CoProgrammer/actions/workflows/ci.yml)
+[![MIT](https://img.shields.io/badge/license-MIT-black)](LICENSE)
+
+[简体中文](README.zh-CN.md) · [Try it](#try-the-preview) ·
+[Two-window walkthrough](docs/GETTING_STARTED.md) ·
+[Connect your client](docs/knowledge/README.md) · [Releases](https://github.com/QIU-Guanzong/CoProgrammer/releases)
+
+## The problem
+
+Codex is changing an API. Claude is updating its callers. Both need to know who
+owns the files, when the upstream task is finished, and what happened before a
+window restarted. Separate Git branches keep edits apart; the collaboration
+still needs shared state.
+
+CoProgrammer records **who owns a task, which paths it covers, what blocks it,
+and what the next window needs to know**. Your coding tools write the code;
+CoProgrammer coordinates their work through a local CLI and MCP server.
+
+| Without a shared record | With CoProgrammer |
+| --- | --- |
+| Two windows try to claim overlapping work | Atomic task claims check owners, worktrees and path leases. |
+| A worker starts before an upstream task finishes | Dependencies keep the task blocked until its prerequisite is done. |
+| A handoff disappears in a terminal | Messages and explicit receipts persist across restarts. |
+| A passing test refers to yesterday's files | Check receipts detect changed content, command, runtime or age. |
+| Another computer has a different checkout | A portable handoff compares package version, HEAD, base and file content. |
+
+## Try the preview
+
+Requires **Python 3.10+** and **Git 2.36+**. Use an active Python virtual environment.
+There are no runtime Python dependencies or model keys needed for the demo.
+
+```sh
+python -m pip install --pre --upgrade coprogrammer
+coprogrammer demo
+```
+
+The demo creates two real Git worktrees, runs task claims, dependency and overlap
+checks, sends a handoff, acknowledges it and completes the tasks. It checks each
+result and cleans up the temporary project. No coding client or model is launched.
+
+An excerpt from an actual run:
+
+```text
+[passed] Create two Git worktrees: Two branches share one repository and one Manager event log.
+[passed] Block unfinished dependencies: Claude cannot claim documentation until the API task is finished.
+[passed] Reject overlapping work: A different worktree cannot claim src/api.py while Codex holds src/**.
+```
+
+[What the demo checks →](docs/DEMO.md)
+
+## Use it in your project
+
+The `start` and `status` entry points require **0.3.0a2+**. Start in a committed Git
+checkout on a named branch. Each coding window should use its own Git worktree.
+Add `.coprogrammer/` to your project's `.gitignore` to keep local runtime state
+out of commits.
+
+```sh
+# In the worktree used by Codex
+coprogrammer start --client codex --session codex-api --task api-v2
+coprogrammer status --session codex-api
+
+# In the separate worktree used by Claude Code
+coprogrammer start --client claude --session claude-ui --task api-v2
+coprogrammer status --session claude-ui
+```
+
+`start` registers this window and previews client setup. It does not launch a
+coding tool or install configuration. Add `--dry-run` to preview registration;
+use `--resume` to explicitly refresh the same registered window after a break.
+Status reads never refresh sessions. Default session freshness lasts five minutes.
+
+In the Codex worktree, create a scoped task and inspect the next action:
+
+```sh
+coprogrammer manager task create --session codex-api --id api-v2   --title 'Update the API' --pattern 'src/api/**' --client codex
+coprogrammer status --session codex-api
+coprogrammer manager task claim --session codex-api --id api-v2
+```
+
+Claims return an ownership token. Use it with the existing guard and finish
+commands; the [two-window walkthrough](docs/GETTING_STARTED.md) covers dependency
+setup, messages, receipts and completion. Status distinguishes repository-wide
+readiness from work eligible for the selected window.
+
+### Connect Codex, Claude Code or Copilot
+
+Preview the project-local Skills, Markdown guidance and MCP configuration:
+
+```sh
+coprogrammer setup --client codex --include-content
+```
+
+Review the output, then explicitly create missing files:
+
+```sh
+coprogrammer setup --client codex --apply
+```
+
+Use `claude` or `copilot` for those clients. Existing project instructions are
+preserved; differing Skills or MCP configuration are reported as conflicts.
+Reload the client and follow its normal project/MCP trust flow. Generated
+configuration alone does not establish a connection.
+
+MCP exposes the same local workflows. `workspace_status` provides the combined
+status view; `task_dispatch` previews eligible tasks. The packaged plugin
+contains six Skills, and the CLI serves twelve read-only Markdown resources.
+[Client setup](docs/knowledge/README.md) · [Plugin installation](docs/PLUGIN_QUICKSTART.md)
+
+## What else can it do?
+
+| Need | Entry point |
+| --- | --- |
+| Inspect work and blockers | `coprogrammer status`; [status guide](docs/GETTING_STARTED.md) |
+| Send and acknowledge handoffs | `manager message`; [communication guide](docs/AGENT_RUNTIME_INTEROP.md) |
+| Check file scope before edits | `manager task guard`; [scheduling guide](docs/MULTI_PLATFORM_QUICKSTART.md) |
+| Detect stale test results | `check run` / `check verify`; [check receipts](docs/VALIDATION_EVIDENCE.md) |
+| Continue on another computer | `manager handoff` / `workspace compare`; [portable handoffs](docs/WORKSPACE_HANDOFF.md) |
+| Review a branch for integration | `digest` / `integration-plan`; [CLI reference](docs/GETTING_STARTED.md#prepare-a-pr) |
+| Request a second opinion | Explicit Claude, GLM or DeepSeek review; [multi-platform guide](docs/MULTI_PLATFORM_QUICKSTART.md) |
+
+## How it fits
+
+Use CoProgrammer when you already run coding agents and need shared ownership,
+communication and review evidence across their worktrees. It complements your
+existing coding tools and GitHub review process.
+
+[gstack](https://github.com/garrytan/gstack) provides opinionated development and
+review workflows; [Beads](https://github.com/gastownhall/beads) provides persistent
+agent work tracking; [Gas Town](https://github.com/gastownhall/gastown) manages
+multi-agent workspaces and orchestration. CoProgrammer focuses on local task
+ownership, path coordination, durable handoffs and inspectable integration
+artifacts through a small Python CLI/MCP package.
+[Comparison and design choices →](docs/research/onboarding-2026-10-12.md)
+
+Local worktrees share a Manager. Independent clones have separate Managers:
+portable handoffs compare context and do not transfer a global lease. Path
+leases are cooperative checks, not filesystem permissions. Check records are
+unauthenticated local evidence. PR approval and merging follow your project's
+normal rules. The demo does not establish native client or live provider connectivity.
+
+## Contribute or get help
+
+[Report a reproducible problem](https://github.com/QIU-Guanzong/CoProgrammer/issues) ·
+[Propose an integration](https://github.com/QIU-Guanzong/CoProgrammer/discussions) ·
+[Contributor guide](CONTRIBUTING.md)
+
+Good first contributions include a small client setup example, a clearer error
+message or a regression for a real worktree conflict. Include the command,
+version, expected result and actual result; remove private code and credentials.
+If CoProgrammer helps your team, a star helps others discover it.
+
+For source development:
+
+```sh
+git clone https://github.com/QIU-Guanzong/CoProgrammer.git
+cd CoProgrammer
+python -m pip install -e .
+python -m unittest discover -s tests
+```
+
+[MIT license](LICENSE). Preview software; feedback and concrete bug reports are welcome.

{coprogrammer-0.3.0a1 → coprogrammer-0.3.0a2}/pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "coprogrammer"
-version = "0.3.0a1"
-description = "Open protocol and toolkit for semantic integration in multi-agent software development."
+version = "0.3.0a2"
+description = "Shared tasks, file boundaries and handoffs for coding agents."
 readme = "README.md"
 requires-python = ">=3.10"
 license = { file = "LICENSE" }

{coprogrammer-0.3.0a1 → coprogrammer-0.3.0a2}/src/coprogrammer/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.0a1"
+__version__ = "0.3.0a2"

{coprogrammer-0.3.0a1 → coprogrammer-0.3.0a2}/src/coprogrammer/assets/skills/coprogrammer-active-sync/SKILL.md

@@ -14,6 +14,19 @@ that does not require a live Manager read or write.
 Use this workflow during coding when several agents, branches, or worktrees may
 touch overlapping code or shared contracts.
 
+## Quick entry points
+
+With CLI 0.3.0a2+, inspect the current checkout using `coprogrammer status`.
+For a registered window, use `coprogrammer status --session <window-id>` to
+see work eligible for that client and worktree. Read-only status never pulses,
+claims or acknowledges a message. MCP clients can call `workspace_status`.
+
+To register a new window, preview `coprogrammer start --client <client> --session
+<window-id> --task <task> --dry-run`, then run without `--dry-run` when authorized.
+For the same existing window, explicitly add `--resume`; blocked/closed or
+mismatched windows require reconciliation. Start never installs client files
+or launches an agent. Keep the existing preview-first setup workflow.
+
 ## Workflow
 
 For cross-window work, check `coprogrammer --version` in each environment.

{coprogrammer-0.3.0a1 → coprogrammer-0.3.0a2}/src/coprogrammer/cli.py

@@ -410,6 +410,7 @@ def run_git(args: list[str], cwd: Path) -> str:
         cwd=cwd,
         check=False,
         text=True,
+        encoding="utf-8",
         capture_output=True,
         env=env,
     )
@@ -1787,11 +1788,13 @@ def command_manager_briefing(args: argparse.Namespace) -> int:
 def build_parser() -> argparse.ArgumentParser:
     parser = argparse.ArgumentParser(
         prog="coprogrammer",
-        description="Protocol tooling for semantic branch integration.",
+        description="Shared tasks, file boundaries and handoffs for coding agents. Start with 'coprogrammer demo'.",
     )
     subparsers = parser.add_subparsers(dest="command", required=True)
     from . import __version__
     parser.add_argument("--version", action="version", version=__version__)
+    from .onboarding import add_parsers as add_onboarding_parsers
+    add_onboarding_parsers(subparsers)
 
     demo = subparsers.add_parser("demo", help="Run a real offline coordination demo in temporary Git worktrees.")
     demo.add_argument("--json", action="store_true")

{coprogrammer-0.3.0a1 → coprogrammer-0.3.0a2}/src/coprogrammer/manager_store.py

@@ -21,6 +21,23 @@ _LOCKS: dict[str, threading.RLock] = {}
 _LOCKS_GUARD = threading.Lock()
 _LOCAL = threading.local()
 DEFAULT_LOCK_TIMEOUT = 10.0
+_WINDOWS = os.name == "nt"
+
+
+def _replace_event_log(source: str, target: Path) -> None:
+    """Keep the transaction locked across bounded Windows replacement retries."""
+    for attempt in range(6):
+        try:
+            os.replace(source, target)
+            return
+        except OSError as exc:
+            # Windows can briefly refuse replacement while another handle is
+            # closing or a filesystem observer is inspecting the new file.
+            # Retry the same complete, flushed file; never delete the old log.
+            if (not _WINDOWS or getattr(exc, "winerror", None) not in (5, 32, 33)
+                    or attempt == 5):
+                raise
+            time.sleep(0.02 * 2 ** attempt)
 
 
 def _reject_nonfinite(value: str) -> None:
@@ -149,7 +166,7 @@ class EventTransaction:
                     handle.write(json.dumps(event, ensure_ascii=False, sort_keys=True, allow_nan=False) + "\n")
                 handle.flush()
                 os.fsync(handle.fileno())
-            os.replace(temporary, self.path)
+            _replace_event_log(temporary, self.path)
             temporary = None
         except (OSError, TypeError, ValueError, RecursionError) as exc:
             raise RuntimeError(f"cannot commit Manager event log {self.path}: {exc}") from exc

{coprogrammer-0.3.0a1 → coprogrammer-0.3.0a2}/src/coprogrammer/mcp_server.py

@@ -231,7 +231,7 @@ TOOLS.extend(scheduler_mcp.declarations(string_schema))
 TOOLS.extend(workflow_mcp.declarations(string_schema))
 READ_ONLY_TOOLS = {"digest_branch", "manager_status", "manager_briefing", "manager_forecast", "review_summary",
                    "manager_sync", "message_inbox", "manager_wait", "message_thread", "task_board", "task_guard"}
-READ_ONLY_TOOLS.update({"workspace_snapshot", "task_dispatch", "manager_handoff", "handoff_check", "check_verify"})
+READ_ONLY_TOOLS.update({"workspace_status", "workspace_snapshot", "task_dispatch", "manager_handoff", "handoff_check", "check_verify"})
 for _tool in TOOLS:
     _tool["inputSchema"]["additionalProperties"] = False
     _tool["annotations"] = {
@@ -424,7 +424,7 @@ for _name in ("task_create", "task_claim", "task_renew", "task_finish", "task_re
     TOOL_HANDLERS[_name] = lambda ctx, args, name=_name: json.dumps(
         scheduler_mcp.dispatch(name, ctx, args), indent=2, ensure_ascii=False)
 
-for _name in ("workspace_snapshot", "task_dispatch", "manager_handoff", "handoff_check", "check_verify"):
+for _name in ("workspace_status", "workspace_snapshot", "task_dispatch", "manager_handoff", "handoff_check", "check_verify"):
     TOOL_HANDLERS[_name] = lambda ctx, args, name=_name: json.dumps(
         workflow_mcp.dispatch(name, ctx, args), indent=2, ensure_ascii=False)