code-factory-agent 0.1.1__tar.gz

code_factory_agent-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,77 @@
+name: Publish
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  verify:
+    name: Verify And Build
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v6
+
+      - name: Validate tag matches package version
+        env:
+          GITHUB_REF_NAME: ${{ github.ref_name }}
+        run: |
+          python - <<'PY'
+          import os
+          import tomllib
+          from pathlib import Path
+
+          tag = os.environ["GITHUB_REF_NAME"]
+          version = tomllib.loads(Path("pyproject.toml").read_text())["project"]["version"]
+          expected = f"v{version}"
+          if tag != expected:
+              raise SystemExit(
+                  f"Release tag {tag!r} does not match pyproject version {version!r}. "
+                  f"Expected {expected!r}."
+              )
+          PY
+
+      - name: Run full verify gate
+        run: make verify
+
+      - name: Build distribution artifacts
+        run: uv build
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist/*
+
+  publish:
+    name: Publish To PyPI
+    needs: verify
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: pypi-dist
+          path: dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

code_factory_agent-0.1.1/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+.pytest_cache/
+.idea/
+__pycache__/
+*.py[cod]
+.coverage
+coverage.json
+htmlcov/
+.linear.toml

code_factory_agent-0.1.1/AGENTS.md

@@ -0,0 +1,36 @@
+# AGENTS.md
+
+## 1. Overview
+This package is a long-running automation service that reads tracker work, creates isolated per-issue workspaces, and runs coding-agent sessions inside them. It exists to keep workflow policy in-repo, make issue execution repeatable, and provide enough observability to operate concurrent agent runs; when behavior is unclear, check `SPEC.md`.
+
+## 2. Folder Structure
+- `src/code_factory`: Python package entrypoints, shared models, and package roots.
+  - `application`: service bootstrap, logging setup, project bootstrap assets, and operator dashboard rendering.
+  - `runtime`: orchestrator, worker, runtime messages, and subprocess/process lifecycle code.
+  - `trackers`: generic tracker boundary plus concrete tracker implementations.
+  - `coding_agents`: generic coding-agent boundary plus concrete coding-agent implementations.
+  - `config`: typed settings models, parsing, defaults, and validation helpers.
+  - `workflow`: `WORKFLOW.md` loading, templates, front-matter parsing, and workflow snapshot/state handling.
+  - `workspace`: workspace path safety, hook execution, workspace lifecycle management, and operator review/AI review flows.
+  - `observability`: operator-facing API payloads, CLI discovery helpers, runtime metadata, and HTTP server.
+  - `prompts`: workflow prompt rendering, review prompt assets, and prompt data shaping.
+- `tests`: behavior, CLI, integration, and architecture tests; keep new tests close to the layer they protect.
+- `pyproject.toml`: package metadata, lint/type/test tool configuration, and `uv` dependency management.
+- `README.md`: operator-facing usage and API/CLI documentation.
+
+## 3. Core Behaviors & Patterns
+- The orchestrator owns authoritative runtime state, workers report events back through messages, and concrete integrations stay behind generic boundaries.
+- Logging is structured around standard library loggers with issue/session context added at call sites; startup, reload, hook, and protocol failures are logged explicitly rather than swallowed.
+- Error handling favors validation up front, early returns on ineligible work, and bounded retries for transient failures; workflow reload errors keep the last known good snapshot active.
+- Architecture is package-oriented and intentionally strict: concrete integrations live under `trackers/*` and `coding_agents/*`, utilities are package-local, and architecture tests guard import boundaries and file-size limits.
+
+## 4. Conventions
+- Put helper functions in utility/support modules, not inside business modules such as actors, managers, services, or clients.
+- Keep source files under 300 lines, prefer focused package-local models over global catch-all model files, and add comments where the control flow is not already obvious.
+
+## 5. Working Agreements
+- Preserve behavior parity with `SPEC.md`, update it carefully before introducing new policy. Make it transparent to the user when a change would require a SPEC update.
+- When changing runtime behavior, follow the existing layer boundaries instead of adding shortcuts across packages or adding root-level implementation modules.
+- Add or update tests with behavior changes, including architecture rules when moving package boundaries or concrete/generic seams.
+- Tests have 100% line and branch coverage with hard gates, add or adjust tests faithfully to keep coverage 100%. Use pragmas only for platform-specific behavior or branches otherwise unreasonable to test. 
+- Run targeted tests (with uv) while iterating, then run full gates (format check, lint, style, coverage, tests) before handoff: `make verify`.

code_factory_agent-0.1.1/LICENSE

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

code_factory_agent-0.1.1/Makefile

@@ -0,0 +1,98 @@
+.PHONY: setup lint format-check typecheck test test-coverage coverage-gate coverage-packages fix repair verify-static verify clean
+
+UV := uv run --project . --extra dev --group dev
+SOURCE_DIR := src/code_factory
+COVERAGE_JSON := coverage.json
+LINE_COVERAGE_MIN := 100
+BRANCH_COVERAGE_MIN := 100
+
+setup:
+	uv sync --extra dev --group dev
+
+lint:
+	@$(UV) ruff check --output-format concise .
+
+format-check:
+	@$(UV) ruff format --check .
+
+typecheck:
+	@$(UV) pyright
+
+test:
+	@$(UV) python -m pytest -q
+
+test-coverage:
+	@$(UV) python -m pytest -q --cov=$(SOURCE_DIR) --cov-branch --cov-report= --cov-report=json:$(COVERAGE_JSON)
+	@$(UV) python -c '\
+import json; \
+from pathlib import Path; \
+totals = json.loads(Path("$(COVERAGE_JSON)").read_text())["totals"]; \
+line_actual = float(totals["percent_statements_covered"]); \
+line_display = totals["percent_statements_covered_display"]; \
+branches = totals["num_branches"]; \
+covered_branches = totals["covered_branches"]; \
+branch_percent = float(totals["percent_branches_covered"]); \
+branch_display = totals["percent_branches_covered_display"]; \
+print(f"Coverage: lines {line_display}% ({line_actual:.2f}%), branches {branch_display}% ({branch_percent:.2f}%, {covered_branches}/{branches})") \
+'
+
+coverage-gate: test-coverage
+	@$(UV) python -c '\
+import json; \
+from pathlib import Path; \
+line_minimum = float("$(LINE_COVERAGE_MIN)"); \
+branch_minimum = float("$(BRANCH_COVERAGE_MIN)"); \
+totals = json.loads(Path("$(COVERAGE_JSON)").read_text())["totals"]; \
+line_actual = float(totals["percent_statements_covered"]); \
+branch_actual = float(totals["percent_branches_covered"]); \
+assert line_actual >= line_minimum, f"Line coverage gate failed: {line_actual:.2f}% < {line_minimum:.2f}%"; \
+assert branch_actual >= branch_minimum, f"Branch coverage gate failed: {branch_actual:.2f}% < {branch_minimum:.2f}%" \
+'
+
+coverage-packages: test-coverage
+	@printf '%s\n' \
+	'import json' \
+	'from collections import defaultdict' \
+	'from pathlib import Path' \
+	'data = json.loads(Path("$(COVERAGE_JSON)").read_text())' \
+	'totals = data["totals"]' \
+	'overall_lines = float(totals["percent_statements_covered"])' \
+	'overall_lines_covered = totals["covered_lines"]' \
+	'overall_lines_total = totals["num_statements"]' \
+	'overall_branches = float(totals["percent_branches_covered"])' \
+	'overall_branches_covered = totals["covered_branches"]' \
+	'overall_branches_total = totals["num_branches"]' \
+	'acc = defaultdict(lambda: {"covered_lines": 0, "num_statements": 0, "covered_branches": 0, "num_branches": 0})' \
+	'for path, meta in data["files"].items():' \
+	'    parts = Path(path).parts' \
+	'    idx = parts.index("code_factory")' \
+	'    package = parts[idx + 1] if len(parts) > idx + 2 else "(root)"' \
+	'    summary = meta["summary"]' \
+	'    acc[package]["covered_lines"] += summary["covered_lines"]' \
+	'    acc[package]["num_statements"] += summary["num_statements"]' \
+	'    acc[package]["covered_branches"] += summary["covered_branches"]' \
+	'    acc[package]["num_branches"] += summary["num_branches"]' \
+	'print(f"overall\tlines {overall_lines:.2f}% ({overall_lines_covered}/{overall_lines_total})\tbranches {overall_branches:.2f}% ({overall_branches_covered}/{overall_branches_total})")' \
+	'for package in sorted(acc):' \
+	'    covered_lines = acc[package]["covered_lines"]' \
+	'    total_lines = acc[package]["num_statements"]' \
+	'    lines_percent = 100.0 if total_lines == 0 else (covered_lines / total_lines * 100)' \
+	'    covered_branches = acc[package]["covered_branches"]' \
+	'    total_branches = acc[package]["num_branches"]' \
+	'    branches_percent = 100.0 if total_branches == 0 else (covered_branches / total_branches * 100)' \
+	'    print(f"{package}\tlines {lines_percent:.2f}% ({covered_lines}/{total_lines})\tbranches {branches_percent:.2f}% ({covered_branches}/{total_branches})")' \
+	| $(UV) python -
+
+fix:
+	@$(UV) ruff check . --fix
+	@$(UV) ruff format .
+
+repair: fix verify
+
+verify-static: lint format-check typecheck
+
+verify: verify-static test coverage-gate
+
+clean:
+	rm -f .coverage $(COVERAGE_JSON)
+	rm -rf htmlcov

code_factory_agent-0.1.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.4
+Name: code-factory-agent
+Version: 0.1.1
+Summary: Extended Python asyncio port of the OpenAI Symphony spec
+Project-URL: Homepage, https://github.com/Benjoyo/code-factory
+Project-URL: Repository, https://github.com/Benjoyo/code-factory
+Project-URL: Documentation, https://github.com/Benjoyo/code-factory/blob/main/README.md
+Project-URL: Issues, https://github.com/Benjoyo/code-factory/issues
+Project-URL: Changelog, https://github.com/Benjoyo/code-factory/releases
+Author: Benjoyo
+License: MIT License
+        
+        Copyright (c) 2026 Benjoyo
+        
+        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.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: aiohttp<4,>=3.11.13
+Requires-Dist: httpx<0.29,>=0.28.1
+Requires-Dist: pydantic<3,>=2.11.7
+Requires-Dist: python-liquid<3,>=2.1.0
+Requires-Dist: pyyaml<7,>=6.0.2
+Requires-Dist: rich<15,>=14.2.0
+Requires-Dist: textual<9,>=8.1.0
+Requires-Dist: typer<0.17,>=0.16.0
+Requires-Dist: watchfiles<2,>=1.1.1
+Provides-Extra: dev
+Requires-Dist: pyright<2,>=1.1.398; extra == 'dev'
+Requires-Dist: pytest-asyncio<1,>=0.25.3; extra == 'dev'
+Requires-Dist: pytest-cov<7,>=6.1.1; extra == 'dev'
+Requires-Dist: pytest<9,>=8.3.5; extra == 'dev'
+Requires-Dist: ruff<0.12,>=0.11.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<h1>Code Factory</h1>
+
+<p><strong>🏭 Orchestrate coding agents via Kanban — high autonomy, isolated per-issue workspaces, single-file repo-owned workflow contract</strong></p>
+
+<p><a href="#quick-start">Quick Start</a> · <a href="https://github.com/Benjoyo/code-factory/blob/main/docs/cli.md">CLI</a> · <a href="https://github.com/Benjoyo/code-factory/blob/main/docs/workflow/README.md">Workflow</a> · <a href="https://github.com/Benjoyo/code-factory/blob/main/SPEC.md">Specification</a></p>
+
+</div>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Benjoyo/code-factory/main/docs/images/code-factory-dashboard.png" alt="Code Factory operator dashboard showing live issue execution, throughput, token usage, and operator links" width="1257" />
+</p>
+
+Code Factory is a Python asyncio implementation and extension of the OpenAI Symphony spec. It
+polls tracker work, creates isolated per-issue workspaces, runs coding-agent
+sessions inside them, and keeps the workflow contract versioned in
+`WORKFLOW.md`.
+
+Use it when you want repeatable issue execution, repo-owned workflow policy,
+and enough observability to operate concurrent agent runs without building a
+custom harness around your coding agent.
+
+## Typical Workflow
+
+![Typical Code Factory workflow showing tracker intake, per-issue workspace creation, coding-agent execution, operator review, and issue state progression](https://raw.githubusercontent.com/Benjoyo/code-factory/main/docs/code-factory-typical-workflow.svg)
+
+## What You Need
+
+- Python 3.12
+- [`uv`](https://docs.astral.sh/uv/)
+- A valid `WORKFLOW.md`
+- Access to the tracker configured in `WORKFLOW.md`
+- A working coding-agent command available to `codex.command`
+
+## Installation
+
+Install `cf` from PyPI as a `uv` tool:
+
+```bash
+uv tool install code-factory-agent
+```
+
+Then run it directly:
+
+```bash
+cf --help
+cf serve --no-guardrails
+```
+
+If you prefer not to install the tool, you can still run it from the repo with
+`uv run cf ...`.
+
+## Quick Start
+
+### 1. Install from PyPI
+
+```bash
+uv tool install code-factory-agent
+```
+
+### 2. Create a starter workflow in a new project
+
+```bash
+cf init
+```
+
+`cf init` walks you through the starter values, renders a
+project-specific `WORKFLOW.md`, and copies this repo's bundled skills into
+`./.agents/skills`. Re-run with `--force` if you want to overwrite an existing
+workflow or skills bundle.
+
+### 3. Start the service
+
+```bash
+cf serve --no-guardrails
+```
+
+If you omit the workflow path, the CLI defaults to `./WORKFLOW.md`.
+
+### 4. Create issues and move to Todo
+
+- Create new issues in Linear Backlog
+- Move ready-for-dev issues to Todo
+
+### 5. Steer agents during execution (optional)
+
+Run:
+
+```bash
+cf steer ENG-123 "also add integration tests please"
+```
+
+This appends operator guidance to an in-flight issue turn.
+
+### 6. Review PRs
+
+Run:
+
+```bash
+cf review ENG-123
+```
+
+This will:
+
+- Launch a review worktree and any configured review servers.
+- Open the browser automatically, if configured.
+- Let you quickly submit PR comments with any problems you find.
+
+### 7. Move issues to Merging, Todo, or Rework
+
+Move reviewed issues to:
+
+- Merging, if review was successful
+- Todo, if you left review comments in the PR
+- Rework, if you left review comments and want a full, clean re-attempt at the issue
+
+## CLI Overview
+
+The main operator commands are:
+
+- `cf init` to bootstrap a repo-local workflow and bundled skills
+- `cf serve` to run the long-lived automation service
+- `cf review` to launch a review worktree and any configured review servers
+- `cf steer` to append operator guidance to an in-flight issue turn
+- `cf issue`, `cf comment`, `cf workpad`, and `cf tracker` for tracker-facing
+  operator actions
+
+See [docs/cli.md](https://github.com/Benjoyo/code-factory/blob/main/docs/cli.md) for the general CLI reference and
+[docs/ticket-cli.md](https://github.com/Benjoyo/code-factory/blob/main/docs/ticket-cli.md) for ticket-oriented commands.
+
+## Ticket Surfaces
+
+Agent sessions use flat `tracker_issue_*`, `tracker_comment_*`,
+`tracker_pr_link`, and `tracker_file_upload` tools for ticket work. The
+orchestrator manages `workpad.md` synchronization to a ticket comment
+automatically during the run.
+
+Operators can use the CLI for the same ticket surface area:
+
+```bash
+cf issue get ISSUE
+cf issue list [--project PROJECT] [--team TEAM] [--state STATE]
+cf issue create --team TEAM --title TITLE
+cf issue update ISSUE
+cf issue move ISSUE --state STATE
+cf issue link-pr ISSUE --url URL
+cf comment list ISSUE
+cf comment create ISSUE
+cf comment update COMMENT
+cf workpad get ISSUE
+cf workpad sync ISSUE
+```
+
+## Workflow
+
+`WORKFLOW.md` is the main operator surface for Code Factory. It keeps tracker
+configuration, active states, prompt sections, completion gates, review setup,
+workspace hooks, and observability settings in the repo so teams can version and
+hot-reload automation policy alongside application code.
+
+See the workflow docs for the current contract:
+
+- [Workflow docs](https://github.com/Benjoyo/code-factory/blob/main/docs/workflow/README.md)
+- [Frontmatter reference](https://github.com/Benjoyo/code-factory/blob/main/docs/workflow/frontmatter.md)
+- [Prompt template reference](https://github.com/Benjoyo/code-factory/blob/main/docs/workflow/prompt-template.md)
+- [Specification](https://github.com/Benjoyo/code-factory/blob/main/SPEC.md)
+
+## Observability
+
+Code Factory exposes a local observability API and, when stderr is attached to a
+TTY, a live terminal dashboard for operators. See
+[docs/observability.md](https://github.com/Benjoyo/code-factory/blob/main/docs/observability.md) for endpoints, dashboard
+behavior, and steering/discovery details.
+
+## Runtime Notes
+
+- Startup validates the workflow and required dispatch settings before the
+  scheduler loop begins.
+- `WORKFLOW.md` is hot-reloaded automatically; valid changes affect future
+  dispatches without restarting the service.
+- Only issues in active workflow states are dispatched.
+
+## Development
+
+For local development from a checkout:
+
+```bash
+git clone git@github.com:Benjoyo/code-factory.git
+cd code-factory
+make setup
+```
+
+Run the CLI directly from the repo with `uv run`:
+
+```bash
+uv run cf --help
+uv run cf serve --no-guardrails
+```
+
+If you want the checkout on your PATH during development, install the local
+editable tool:
+
+```bash
+uv tool install --editable .
+```
+
+Run the full verification suite:
+
+```bash
+make verify
+```