swfactory 1.0.0__tar.gz

swfactory-1.0.0/LICENSE

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

swfactory-1.0.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.4
+Name: swfactory
+Version: 1.0.0
+Summary: A method and a CLI to build software with coding agents (Claude Code, Codex) on Orca: design, approve, implement, review and publish with evidence.
+Keywords: agents,claude-code,codex,orca,workflow,cli,software-factory
+Author: MarianodelRio
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Classifier: Typing :: Typed
+Requires-Dist: pyyaml>=6.0
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/MarianodelRio/swfactory
+Project-URL: Documentation, https://github.com/MarianodelRio/swfactory/blob/main/docs/guide.md
+Project-URL: Changelog, https://github.com/MarianodelRio/swfactory/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/MarianodelRio/swfactory/issues
+Description-Content-Type: text/markdown
+
+# swfactory
+
+[![PyPI](https://img.shields.io/pypi/v/swfactory)](https://pypi.org/project/swfactory/)
+[![CI](https://github.com/MarianodelRio/swfactory/actions/workflows/ci.yml/badge.svg)](https://github.com/MarianodelRio/swfactory/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/MarianodelRio/swfactory/blob/main/LICENSE)
+
+A method, five agent skills and a CLI to build software with coding agents (Claude Code and Codex)
+on local Orca: design and approve a change, implement each task in its own Orca workspace, review
+it and publish it with evidence, follow everything on a live board, and keep what was learned in
+the project's memory.
+
+Orca runs the agents and the workspaces; the Factory brings the method and keeps its state in
+readable files under `.factory/`. You talk to the agent in natural language (Spanish or English);
+everything it writes to the repository is in English.
+
+The [user guide](https://github.com/MarianodelRio/swfactory/blob/main/docs/guide.md) explains every
+step in detail: what each skill does, what you decide, task states, notes and recovery, configuration and what to do when something goes wrong.
+
+## Requirements
+
+- Linux or macOS with Git (Windows is not supported).
+- Orca **1.4.229** or later, running locally (remote hosts are
+  refused), with its `orca` CLI on your `PATH`.
+- [Claude Code](https://claude.com/claude-code) and/or Codex, available as agents in Orca.
+- [uv](https://docs.astral.sh/uv/) (it provides Python 3.11+), with `~/.local/bin` on your `PATH`
+  (`uv tool update-shell` adds it).
+- Optional: [`gh`](https://cli.github.com/), authenticated, to open pull requests. Without it the
+  Factory pushes the task branch and leaves the PR to you.
+
+## Install
+
+Once per machine, with uv (recommended):
+
+```bash
+uv tool install swfactory   # the `swfactory` command, in ~/.local/bin
+swfactory install-skill     # copies /factory-init to ~/.claude/skills/ and ~/.agents/skills/
+```
+
+It is a regular Python package, so `pipx install swfactory` or `pip install swfactory` (inside a
+virtual environment) work too. The skills call `swfactory`, so it has to be installed, not only run
+once. To try it without installing: `uvx swfactory --version`.
+
+**Upgrade:** `uv tool upgrade swfactory` (or `pipx upgrade swfactory`), then
+`swfactory install-skill`, then `/factory-init` in each project to update its skills.
+
+## The five skills
+
+| Skill | What for |
+|---|---|
+| `/factory-init` | Prepare or update a repository: it analyzes it, proposes one plan (create, modify, delete with reason, respect, Orca actions) and applies it after a single confirmation, with backups. "solo el análisis" shows the plan only. |
+| `/factory-design` | Design a change: it shows a short outline first, writes the design with its acceptance criteria and tasks, and has it critiqued. You approve it by saying "apruebo CHG-NNNN" (Claude asks for permission before the approval commit). |
+| `/factory-implement` | Implement an approved task: from the main checkout it claims the task, creates its Orca workspace and launches the lead agent there. The lead writes tests and code, checkpoints, verifies every criterion with evidence, runs the reviews, updates the memory and finishes. |
+| `/factory-board` | The live kanban board: opens it in an Orca tab (or your browser), closes it, gives its URL or saves a snapshot. |
+| `/factory-status` | How everything is going, what needs you, notes and pauses for a running agent ("deja una nota en CHG-…", "pausa CHG-…"), recovering an interrupted task and memory maintenance. |
+
+The skills call the `swfactory` CLI for everything that must be exact. You do not need to use it,
+but you can: `swfactory --help` lists every command.
+
+## Five-minute walkthrough
+
+In a Claude Code (or Codex) terminal in Orca, at the root of your repository:
+
+1. **Prepare the repo.**
+   ```
+   /factory-init
+   ```
+   Read the plan and confirm it. It registers the repo in Orca with its base branch, installs the
+   five skills in the repo, writes `AGENTS.md`, `docs/` and `.factory/config.toml` with your test, lint
+   and typecheck commands, and leaves everything uncommitted. Review the diff and commit it on the
+   base branch (or ask the agent to).
+
+2. **Design a change.**
+   ```
+   /factory-design add weekly recurrence to bookings
+   ```
+   Say OK to the outline; it writes `.factory/changes/CHG-0001/design.md` and `tasks.yaml`.
+   Read it and approve it:
+   ```
+   apruebo CHG-0001
+   ```
+   Accept the permission prompt. "vale" or "ok" is not an approval.
+
+3. **Implement a task.**
+   ```
+   /factory-implement CHG-0001-01 con claude, revisa claude
+   ```
+   ("with claude, review claude": the lead agent and the conformance reviewer.) A new workspace
+   appears in Orca's sidebar with its agent; your main session is free. Open the workspace to watch
+   it or talk to the agent.
+
+4. **Follow it.**
+   ```
+   /factory-status
+   /factory-board
+   ```
+   You see each task's state, acceptance criteria verified, reviews and the next step. The board
+   is a live kanban in an Orca tab (and in your browser, at the address `swfactory board status`
+   prints) with every agent and subagent running in each task. When the
+   task is `done`, the lead offers to push the branch and open the PR.
+
+5. **Integrate.** Review the PR and merge it yourself; the Factory never merges. Tasks that depend
+   on it move from `pending` to `ready` once it is on the base branch.
+
+## Good to know
+
+- Approving or rejecting a design always needs your explicit message. Claude Code and Codex also
+  ask for permission before running it (`.claude/settings.json` and `.codex/rules/factory.rules`;
+  Codex reads project rules only if you trust the project in Codex).
+- A task is `done` only when every acceptance criterion has evidence, the checks pass and the
+  required reviews passed on the final commit.
+- The Factory only pushes the task branch: no force push, merge or branch deletion.
+- Orca may launch Claude with `--dangerously-skip-permissions` (its `agentDefaultArgs` setting).
+  The approval rule still asks in that mode. `swfactory doctor` warns when Claude's own settings
+  skip permission prompts (`bypassPermissions`); it cannot read Orca's setting.
+- Orca does not say whether the agent inside a terminal is still running: `/factory-status` marks
+  a task `interrupted` only when its terminal is closed. An agent that exited in an open terminal
+  looks alive; more than 10 minutes without a checkpoint only gives a warning.
+- Orca does not report the model an agent used; the Factory records the `--model` it passed.
+- **Verified:** end to end on Linux with Claude Code and Orca 1.4.229. **Implemented, not yet
+  verified on a real machine:** Codex (skills in `.agents/skills/`, the approval rule, reviews) and
+  macOS (the CI runs the tests there). **Not supported:** Windows.
+
+## Development
+
+```bash
+git clone https://github.com/MarianodelRio/swfactory && cd swfactory
+uv sync                 # create the environment with dev tools
+uv run pytest -q        # tests
+uv run ruff check .     # lint
+uv run mypy src         # typecheck
+uv tool install .       # install the `swfactory` command from this checkout
+```
+
+Changes are listed in [CHANGELOG.md](https://github.com/MarianodelRio/swfactory/blob/main/CHANGELOG.md); how to publish a version is in
+[docs/releasing.md](https://github.com/MarianodelRio/swfactory/blob/main/docs/releasing.md). License: [MIT](https://github.com/MarianodelRio/swfactory/blob/main/LICENSE).

swfactory-1.0.0/README.md

@@ -0,0 +1,135 @@
+# swfactory
+
+[![PyPI](https://img.shields.io/pypi/v/swfactory)](https://pypi.org/project/swfactory/)
+[![CI](https://github.com/MarianodelRio/swfactory/actions/workflows/ci.yml/badge.svg)](https://github.com/MarianodelRio/swfactory/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/MarianodelRio/swfactory/blob/main/LICENSE)
+
+A method, five agent skills and a CLI to build software with coding agents (Claude Code and Codex)
+on local Orca: design and approve a change, implement each task in its own Orca workspace, review
+it and publish it with evidence, follow everything on a live board, and keep what was learned in
+the project's memory.
+
+Orca runs the agents and the workspaces; the Factory brings the method and keeps its state in
+readable files under `.factory/`. You talk to the agent in natural language (Spanish or English);
+everything it writes to the repository is in English.
+
+The [user guide](https://github.com/MarianodelRio/swfactory/blob/main/docs/guide.md) explains every
+step in detail: what each skill does, what you decide, task states, notes and recovery, configuration and what to do when something goes wrong.
+
+## Requirements
+
+- Linux or macOS with Git (Windows is not supported).
+- Orca **1.4.229** or later, running locally (remote hosts are
+  refused), with its `orca` CLI on your `PATH`.
+- [Claude Code](https://claude.com/claude-code) and/or Codex, available as agents in Orca.
+- [uv](https://docs.astral.sh/uv/) (it provides Python 3.11+), with `~/.local/bin` on your `PATH`
+  (`uv tool update-shell` adds it).
+- Optional: [`gh`](https://cli.github.com/), authenticated, to open pull requests. Without it the
+  Factory pushes the task branch and leaves the PR to you.
+
+## Install
+
+Once per machine, with uv (recommended):
+
+```bash
+uv tool install swfactory   # the `swfactory` command, in ~/.local/bin
+swfactory install-skill     # copies /factory-init to ~/.claude/skills/ and ~/.agents/skills/
+```
+
+It is a regular Python package, so `pipx install swfactory` or `pip install swfactory` (inside a
+virtual environment) work too. The skills call `swfactory`, so it has to be installed, not only run
+once. To try it without installing: `uvx swfactory --version`.
+
+**Upgrade:** `uv tool upgrade swfactory` (or `pipx upgrade swfactory`), then
+`swfactory install-skill`, then `/factory-init` in each project to update its skills.
+
+## The five skills
+
+| Skill | What for |
+|---|---|
+| `/factory-init` | Prepare or update a repository: it analyzes it, proposes one plan (create, modify, delete with reason, respect, Orca actions) and applies it after a single confirmation, with backups. "solo el análisis" shows the plan only. |
+| `/factory-design` | Design a change: it shows a short outline first, writes the design with its acceptance criteria and tasks, and has it critiqued. You approve it by saying "apruebo CHG-NNNN" (Claude asks for permission before the approval commit). |
+| `/factory-implement` | Implement an approved task: from the main checkout it claims the task, creates its Orca workspace and launches the lead agent there. The lead writes tests and code, checkpoints, verifies every criterion with evidence, runs the reviews, updates the memory and finishes. |
+| `/factory-board` | The live kanban board: opens it in an Orca tab (or your browser), closes it, gives its URL or saves a snapshot. |
+| `/factory-status` | How everything is going, what needs you, notes and pauses for a running agent ("deja una nota en CHG-…", "pausa CHG-…"), recovering an interrupted task and memory maintenance. |
+
+The skills call the `swfactory` CLI for everything that must be exact. You do not need to use it,
+but you can: `swfactory --help` lists every command.
+
+## Five-minute walkthrough
+
+In a Claude Code (or Codex) terminal in Orca, at the root of your repository:
+
+1. **Prepare the repo.**
+   ```
+   /factory-init
+   ```
+   Read the plan and confirm it. It registers the repo in Orca with its base branch, installs the
+   five skills in the repo, writes `AGENTS.md`, `docs/` and `.factory/config.toml` with your test, lint
+   and typecheck commands, and leaves everything uncommitted. Review the diff and commit it on the
+   base branch (or ask the agent to).
+
+2. **Design a change.**
+   ```
+   /factory-design add weekly recurrence to bookings
+   ```
+   Say OK to the outline; it writes `.factory/changes/CHG-0001/design.md` and `tasks.yaml`.
+   Read it and approve it:
+   ```
+   apruebo CHG-0001
+   ```
+   Accept the permission prompt. "vale" or "ok" is not an approval.
+
+3. **Implement a task.**
+   ```
+   /factory-implement CHG-0001-01 con claude, revisa claude
+   ```
+   ("with claude, review claude": the lead agent and the conformance reviewer.) A new workspace
+   appears in Orca's sidebar with its agent; your main session is free. Open the workspace to watch
+   it or talk to the agent.
+
+4. **Follow it.**
+   ```
+   /factory-status
+   /factory-board
+   ```
+   You see each task's state, acceptance criteria verified, reviews and the next step. The board
+   is a live kanban in an Orca tab (and in your browser, at the address `swfactory board status`
+   prints) with every agent and subagent running in each task. When the
+   task is `done`, the lead offers to push the branch and open the PR.
+
+5. **Integrate.** Review the PR and merge it yourself; the Factory never merges. Tasks that depend
+   on it move from `pending` to `ready` once it is on the base branch.
+
+## Good to know
+
+- Approving or rejecting a design always needs your explicit message. Claude Code and Codex also
+  ask for permission before running it (`.claude/settings.json` and `.codex/rules/factory.rules`;
+  Codex reads project rules only if you trust the project in Codex).
+- A task is `done` only when every acceptance criterion has evidence, the checks pass and the
+  required reviews passed on the final commit.
+- The Factory only pushes the task branch: no force push, merge or branch deletion.
+- Orca may launch Claude with `--dangerously-skip-permissions` (its `agentDefaultArgs` setting).
+  The approval rule still asks in that mode. `swfactory doctor` warns when Claude's own settings
+  skip permission prompts (`bypassPermissions`); it cannot read Orca's setting.
+- Orca does not say whether the agent inside a terminal is still running: `/factory-status` marks
+  a task `interrupted` only when its terminal is closed. An agent that exited in an open terminal
+  looks alive; more than 10 minutes without a checkpoint only gives a warning.
+- Orca does not report the model an agent used; the Factory records the `--model` it passed.
+- **Verified:** end to end on Linux with Claude Code and Orca 1.4.229. **Implemented, not yet
+  verified on a real machine:** Codex (skills in `.agents/skills/`, the approval rule, reviews) and
+  macOS (the CI runs the tests there). **Not supported:** Windows.
+
+## Development
+
+```bash
+git clone https://github.com/MarianodelRio/swfactory && cd swfactory
+uv sync                 # create the environment with dev tools
+uv run pytest -q        # tests
+uv run ruff check .     # lint
+uv run mypy src         # typecheck
+uv tool install .       # install the `swfactory` command from this checkout
+```
+
+Changes are listed in [CHANGELOG.md](https://github.com/MarianodelRio/swfactory/blob/main/CHANGELOG.md); how to publish a version is in
+[docs/releasing.md](https://github.com/MarianodelRio/swfactory/blob/main/docs/releasing.md). License: [MIT](https://github.com/MarianodelRio/swfactory/blob/main/LICENSE).

swfactory-1.0.0/pyproject.toml

@@ -0,0 +1,78 @@
+[project]
+name = "swfactory"
+version = "1.0.0"
+description = "A method and a CLI to build software with coding agents (Claude Code, Codex) on Orca: design, approve, implement, review and publish with evidence."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "agents",
+    "claude-code",
+    "codex",
+    "orca",
+    "workflow",
+    "cli",
+    "software-factory",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = ["PyYAML>=6.0"]
+
+[[project.authors]]
+name = "MarianodelRio"
+
+[project.urls]
+Homepage = "https://github.com/MarianodelRio/swfactory"
+Documentation = "https://github.com/MarianodelRio/swfactory/blob/main/docs/guide.md"
+Changelog = "https://github.com/MarianodelRio/swfactory/blob/main/CHANGELOG.md"
+Issues = "https://github.com/MarianodelRio/swfactory/issues"
+
+[project.scripts]
+swfactory = "swfactory.cli:run"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-xdist>=3",
+    "ruff>=0.6",
+    "mypy>=1.11",
+    "types-PyYAML",
+]
+
+[build-system]
+requires = ["uv_build>=0.8,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-n auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "UP",
+    "B",
+]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

swfactory-1.0.0/pyproject.toml.orig

@@ -0,0 +1,56 @@
+[project]
+name = "swfactory"
+version = "1.0.0"
+description = "A method and a CLI to build software with coding agents (Claude Code, Codex) on Orca: design, approve, implement, review and publish with evidence."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "MarianodelRio" }]
+keywords = ["agents", "claude-code", "codex", "orca", "workflow", "cli", "software-factory"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development",
+    "Typing :: Typed",
+]
+dependencies = ["PyYAML>=6.0"]
+
+[project.urls]
+Homepage = "https://github.com/MarianodelRio/swfactory"
+Documentation = "https://github.com/MarianodelRio/swfactory/blob/main/docs/guide.md"
+Changelog = "https://github.com/MarianodelRio/swfactory/blob/main/CHANGELOG.md"
+Issues = "https://github.com/MarianodelRio/swfactory/issues"
+
+[project.scripts]
+swfactory = "swfactory.cli:run"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-xdist>=3", "ruff>=0.6", "mypy>=1.11", "types-PyYAML"]
+
+[build-system]
+requires = ["uv_build>=0.8,<0.14"]
+build-backend = "uv_build"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-n auto"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+python_version = "3.11"
+strict = true

swfactory-1.0.0/src/swfactory/__init__.py

@@ -0,0 +1,8 @@
+"""swfactory: a method and a CLI to build software with coding agents on Orca."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("swfactory")
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0.0.0"

swfactory-1.0.0/src/swfactory/__main__.py

@@ -0,0 +1,3 @@
+from swfactory.cli import run
+
+run()