brichan 0.5.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. brichan-0.5.0/LICENSE +21 -0
  2. brichan-0.5.0/PKG-INFO +193 -0
  3. brichan-0.5.0/README.md +149 -0
  4. brichan-0.5.0/pyproject.toml +43 -0
  5. brichan-0.5.0/setup.cfg +4 -0
  6. brichan-0.5.0/src/brichan.egg-info/PKG-INFO +193 -0
  7. brichan-0.5.0/src/brichan.egg-info/SOURCES.txt +44 -0
  8. brichan-0.5.0/src/brichan.egg-info/dependency_links.txt +1 -0
  9. brichan-0.5.0/src/brichan.egg-info/entry_points.txt +6 -0
  10. brichan-0.5.0/src/brichan.egg-info/top_level.txt +1 -0
  11. brichan-0.5.0/src/brida/__init__.py +3 -0
  12. brichan-0.5.0/src/brida/cli/__init__.py +1 -0
  13. brichan-0.5.0/src/brida/cli/_root.py +23 -0
  14. brichan-0.5.0/src/brida/cli/claude.py +58 -0
  15. brichan-0.5.0/src/brida/cli/codex.py +118 -0
  16. brichan-0.5.0/src/brida/cli/provider_commands.py +404 -0
  17. brichan-0.5.0/src/brida/cli/runtime.py +197 -0
  18. brichan-0.5.0/src/brida/contracts/__init__.py +1 -0
  19. brichan-0.5.0/src/brida/contracts/receipts/__init__.py +13 -0
  20. brichan-0.5.0/src/brida/contracts/receipts/discovery.py +5 -0
  21. brichan-0.5.0/src/brida/contracts/receipts/parser.py +5 -0
  22. brichan-0.5.0/src/brida/contracts/receipts/schema.py +35 -0
  23. brichan-0.5.0/src/brida/contracts/receipts/validation.py +1177 -0
  24. brichan-0.5.0/src/brida/lifecycle.py +334 -0
  25. brichan-0.5.0/src/brida/orchestration/__init__.py +23 -0
  26. brichan-0.5.0/src/brida/orchestration/herdr_client.py +8 -0
  27. brichan-0.5.0/src/brida/orchestration/layout.py +5 -0
  28. brichan-0.5.0/src/brida/orchestration/model_routing.py +283 -0
  29. brichan-0.5.0/src/brida/orchestration/worker_launch.py +479 -0
  30. brichan-0.5.0/src/brida/project.py +64 -0
  31. brichan-0.5.0/src/brida/resources/__init__.py +1 -0
  32. brichan-0.5.0/src/brida/resources/dogfood_v1/__init__.py +1 -0
  33. brichan-0.5.0/src/brida/resources/dogfood_v1/config/model-routing.json +38 -0
  34. brichan-0.5.0/src/brida/resources/dogfood_v1/policy/bootstrap.md +23 -0
  35. brichan-0.5.0/src/brida/resources/dogfood_v1/policy/identity.md +18 -0
  36. brichan-0.5.0/src/brida/resources/dogfood_v1/policy/memory-policy.md +14 -0
  37. brichan-0.5.0/src/brida/resources/dogfood_v1/policy/operating-principles.md +13 -0
  38. brichan-0.5.0/src/brida/resources/dogfood_v1/project-memory/index.md +6 -0
  39. brichan-0.5.0/src/brida/resources/dogfood_v1/project-memory/main/current-state.md +9 -0
  40. brichan-0.5.0/src/brida/resources/dogfood_v1/project-memory/main/decisions.md +3 -0
  41. brichan-0.5.0/src/brida/resources/dogfood_v1/project-memory/main/overview.md +8 -0
  42. brichan-0.5.0/src/brida/resources/dogfood_v1/project-memory/main/references.md +3 -0
  43. brichan-0.5.0/src/brida/resources/dogfood_v1/project-memory/main/tasks.md +11 -0
  44. brichan-0.5.0/src/brida/resources/dogfood_v1/skills/herdr-orchestration/SKILL.md +25 -0
  45. brichan-0.5.0/src/brida/resources/dogfood_v1/skills/herdr-orchestration/references/commands.md +24 -0
  46. brichan-0.5.0/src/brida/resources/dogfood_v1/skills/herdr-orchestration/references/task-packet.md +39 -0
brichan-0.5.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Minh Tran
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
brichan-0.5.0/PKG-INFO ADDED
@@ -0,0 +1,193 @@
1
+ Metadata-Version: 2.4
2
+ Name: brichan
3
+ Version: 0.5.0
4
+ Summary: Repository-native AI Chief of Staff orchestration
5
+ Author: Minh Tran
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Minh Tran
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Keywords: ai,orchestration,codex,claude-code,chief-of-staff
29
+ Classifier: Development Status :: 3 - Alpha
30
+ Classifier: Environment :: Console
31
+ Classifier: Intended Audience :: Developers
32
+ Classifier: License :: OSI Approved :: MIT License
33
+ Classifier: Operating System :: POSIX
34
+ Classifier: Programming Language :: Python :: 3
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: Programming Language :: Python :: 3.13
39
+ Classifier: Topic :: Software Development :: Build Tools
40
+ Requires-Python: >=3.10
41
+ Description-Content-Type: text/markdown
42
+ License-File: LICENSE
43
+ Dynamic: license-file
44
+
45
+ # Brichan
46
+
47
+ ![Brichan coordinating a team of AI workers](assets/brida-hero.png)
48
+
49
+ Brichan is an AI Chief of Staff for Codex and Claude Code. Give it a project
50
+ goal; it keeps the necessary context, coordinates independent workers through
51
+ Herdr, checks their evidence, and records useful project state outside chat.
52
+ Its existing runtime package and console commands remain `brida` and
53
+ `brida-*` for compatibility.
54
+
55
+ ## Current dogfood scope
56
+
57
+ The primary one-user dogfood path is now an installed Python package running
58
+ inside an existing top-level Git repository. Installed-project mode currently
59
+ supports Codex on POSIX-compatible systems with Python 3.10+. Herdr is needed
60
+ only when Brida coordinates independent worker sessions.
61
+
62
+ Brida is not published to a package registry yet; the planned PyPI
63
+ distribution name is `brichan` (`pip install brichan`), while the importable
64
+ package stays `brida` and every console command keeps its existing name.
65
+ Until it is published, build the wheel locally from this repository with the
66
+ installer. It can be invoked from any directory and does not activate or
67
+ modify the target project's virtual environment:
68
+
69
+ ```bash
70
+ /absolute/path/to/brida/scripts/install-brida
71
+ ```
72
+
73
+ By default, the script creates a dedicated environment at
74
+ `$HOME/.local/share/brida/venv` and command symlinks in `$HOME/.local/bin`.
75
+ It automatically selects an available Python 3.10+ interpreter with `pip`,
76
+ `setuptools`, `venv`, and `wheel`, builds from a temporary source snapshot,
77
+ and installs all Brida console commands. No virtualenv activation is
78
+ required. If the command directory is not on `PATH`, the installer prints
79
+ the exact export to add to the shell profile.
80
+
81
+ ## Initialize a project
82
+
83
+ Preview the complete footprint before writing:
84
+
85
+ ```bash
86
+ brida init --project /absolute/path/to/repository
87
+ brida init --apply --project /absolute/path/to/repository
88
+ ```
89
+
90
+ `init` defaults to dry-run and performs zero writes. `--apply` creates only a
91
+ versioned `.brida/` directory containing managed policy, model routing, Herdr
92
+ skill resources, and mutable project memory. Repeating it against healthy
93
+ state is idempotent.
94
+
95
+ Diagnose and launch from any directory with an explicit target:
96
+
97
+ ```bash
98
+ brida status --project /absolute/path/to/repository
99
+ brida doctor --project /absolute/path/to/repository
100
+ brida run --project /absolute/path/to/repository -- <codex arguments>
101
+ ```
102
+
103
+ From inside a healthy initialized repository, bare `brida` also launches
104
+ Codex. The installed entrypoint:
105
+
106
+ - leaves `AGENTS.md`, `CLAUDE.md`, `.codex/`, and provider configuration
107
+ untouched;
108
+ - launches external `codex` directly at the target root and never executes
109
+ target-owned `bin/brida-*` wrappers;
110
+ - injects package-owned Brida policy and Herdr skill discovery;
111
+ - rejects native delegation, permission bypasses, cwd/scope widening, profiles,
112
+ remote execution, and arbitrary Codex configuration before `--`;
113
+ - treats option-looking text after `--` as literal prompt content.
114
+
115
+ State diagnostics reject malformed, dangling, symlinked, inaccessible, or
116
+ incompatible `.brida/` state without silently repairing it. Schema v1 has no
117
+ automatic migration: package-version changes require deliberate backup and
118
+ reinitialization. See the
119
+ [installed Codex dogfood guide](docs/guides/installable-dogfood.md) for the
120
+ exact footprint, exit codes, safeguards, and compatibility boundary.
121
+
122
+ ## Checkout compatibility and development
123
+
124
+ The original checkout workflow remains available for development and for
125
+ Claude Code:
126
+
127
+ ```bash
128
+ bin/brida
129
+ bin/brida --runtime claude
130
+ ```
131
+
132
+ Checkout mode uses package-owned `bin/brida-*` wrappers. Installed-project mode
133
+ does not. Coordinator defaults and worker routes are settings-driven, so the
134
+ coordinator and implementation, review, planning, or scan workers may use
135
+ different runtimes. See the [model-routing guide](docs/guides/model-routing.md)
136
+ to change defaults, select a named route, or use a one-off override.
137
+
138
+ The `brida-codex` and `brida-claude` console commands installed by `brichan`
139
+ remain checkout-oriented: `brida-codex` resolves coordinator routing from a
140
+ Brida source checkout (or `BRIDA_ROOT`) or from an already-initialized
141
+ project's `.brida/` state, while `brida-claude` resolves only from a checkout
142
+ or `BRIDA_ROOT`. Both are for development and checkout use, not standalone
143
+ installed-project launches. `--help`/`--version` work from any directory; the
144
+ [installed Codex dogfood guide](docs/guides/installable-dogfood.md) has the
145
+ exact boundary.
146
+
147
+ ## How it works
148
+
149
+ 1. You describe the outcome and constraints.
150
+ 2. Brida reads only the project context needed for that work.
151
+ 3. Brida gives bounded tasks to independent workers through Herdr.
152
+ 4. Brida verifies results, records decisions and status, then reports back.
153
+
154
+ Herdr is the worker control plane. Native runtime delegation stays disabled so
155
+ worker ownership, evidence, and cleanup remain visible.
156
+
157
+ Project context lives in `projects/<project-slug>/` as a small set of Markdown
158
+ files for overview, current state, tasks, decisions, and references. Read the
159
+ [project memory policy](docs/policy/memory-policy.md) for the contract.
160
+
161
+ ## Development
162
+
163
+ Run the complete local validation suite before sharing a change:
164
+
165
+ ```bash
166
+ make check
167
+ ```
168
+
169
+ You can also run individual layers while iterating:
170
+
171
+ ```bash
172
+ make test-unit
173
+ make test-contract
174
+ make test-integration
175
+ make package-check
176
+ ```
177
+
178
+ The importable implementation is in `src/brida/`; stable command wrappers are
179
+ in `bin/` and `scripts/`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the change
180
+ workflow and [the repository layout](docs/architecture/repository-layout.md)
181
+ for module boundaries.
182
+
183
+ ## Learn more
184
+
185
+ - [Model routing and worker launch settings](docs/guides/model-routing.md)
186
+ - [Installed Codex dogfood](docs/guides/installable-dogfood.md)
187
+ - [Documentation index](docs/index.md)
188
+ - [Operating principles](docs/policy/operating-principles.md)
189
+ - [Security policy](SECURITY.md)
190
+
191
+ ## License
192
+
193
+ Brida is available under the [MIT License](LICENSE).
@@ -0,0 +1,149 @@
1
+ # Brichan
2
+
3
+ ![Brichan coordinating a team of AI workers](assets/brida-hero.png)
4
+
5
+ Brichan is an AI Chief of Staff for Codex and Claude Code. Give it a project
6
+ goal; it keeps the necessary context, coordinates independent workers through
7
+ Herdr, checks their evidence, and records useful project state outside chat.
8
+ Its existing runtime package and console commands remain `brida` and
9
+ `brida-*` for compatibility.
10
+
11
+ ## Current dogfood scope
12
+
13
+ The primary one-user dogfood path is now an installed Python package running
14
+ inside an existing top-level Git repository. Installed-project mode currently
15
+ supports Codex on POSIX-compatible systems with Python 3.10+. Herdr is needed
16
+ only when Brida coordinates independent worker sessions.
17
+
18
+ Brida is not published to a package registry yet; the planned PyPI
19
+ distribution name is `brichan` (`pip install brichan`), while the importable
20
+ package stays `brida` and every console command keeps its existing name.
21
+ Until it is published, build the wheel locally from this repository with the
22
+ installer. It can be invoked from any directory and does not activate or
23
+ modify the target project's virtual environment:
24
+
25
+ ```bash
26
+ /absolute/path/to/brida/scripts/install-brida
27
+ ```
28
+
29
+ By default, the script creates a dedicated environment at
30
+ `$HOME/.local/share/brida/venv` and command symlinks in `$HOME/.local/bin`.
31
+ It automatically selects an available Python 3.10+ interpreter with `pip`,
32
+ `setuptools`, `venv`, and `wheel`, builds from a temporary source snapshot,
33
+ and installs all Brida console commands. No virtualenv activation is
34
+ required. If the command directory is not on `PATH`, the installer prints
35
+ the exact export to add to the shell profile.
36
+
37
+ ## Initialize a project
38
+
39
+ Preview the complete footprint before writing:
40
+
41
+ ```bash
42
+ brida init --project /absolute/path/to/repository
43
+ brida init --apply --project /absolute/path/to/repository
44
+ ```
45
+
46
+ `init` defaults to dry-run and performs zero writes. `--apply` creates only a
47
+ versioned `.brida/` directory containing managed policy, model routing, Herdr
48
+ skill resources, and mutable project memory. Repeating it against healthy
49
+ state is idempotent.
50
+
51
+ Diagnose and launch from any directory with an explicit target:
52
+
53
+ ```bash
54
+ brida status --project /absolute/path/to/repository
55
+ brida doctor --project /absolute/path/to/repository
56
+ brida run --project /absolute/path/to/repository -- <codex arguments>
57
+ ```
58
+
59
+ From inside a healthy initialized repository, bare `brida` also launches
60
+ Codex. The installed entrypoint:
61
+
62
+ - leaves `AGENTS.md`, `CLAUDE.md`, `.codex/`, and provider configuration
63
+ untouched;
64
+ - launches external `codex` directly at the target root and never executes
65
+ target-owned `bin/brida-*` wrappers;
66
+ - injects package-owned Brida policy and Herdr skill discovery;
67
+ - rejects native delegation, permission bypasses, cwd/scope widening, profiles,
68
+ remote execution, and arbitrary Codex configuration before `--`;
69
+ - treats option-looking text after `--` as literal prompt content.
70
+
71
+ State diagnostics reject malformed, dangling, symlinked, inaccessible, or
72
+ incompatible `.brida/` state without silently repairing it. Schema v1 has no
73
+ automatic migration: package-version changes require deliberate backup and
74
+ reinitialization. See the
75
+ [installed Codex dogfood guide](docs/guides/installable-dogfood.md) for the
76
+ exact footprint, exit codes, safeguards, and compatibility boundary.
77
+
78
+ ## Checkout compatibility and development
79
+
80
+ The original checkout workflow remains available for development and for
81
+ Claude Code:
82
+
83
+ ```bash
84
+ bin/brida
85
+ bin/brida --runtime claude
86
+ ```
87
+
88
+ Checkout mode uses package-owned `bin/brida-*` wrappers. Installed-project mode
89
+ does not. Coordinator defaults and worker routes are settings-driven, so the
90
+ coordinator and implementation, review, planning, or scan workers may use
91
+ different runtimes. See the [model-routing guide](docs/guides/model-routing.md)
92
+ to change defaults, select a named route, or use a one-off override.
93
+
94
+ The `brida-codex` and `brida-claude` console commands installed by `brichan`
95
+ remain checkout-oriented: `brida-codex` resolves coordinator routing from a
96
+ Brida source checkout (or `BRIDA_ROOT`) or from an already-initialized
97
+ project's `.brida/` state, while `brida-claude` resolves only from a checkout
98
+ or `BRIDA_ROOT`. Both are for development and checkout use, not standalone
99
+ installed-project launches. `--help`/`--version` work from any directory; the
100
+ [installed Codex dogfood guide](docs/guides/installable-dogfood.md) has the
101
+ exact boundary.
102
+
103
+ ## How it works
104
+
105
+ 1. You describe the outcome and constraints.
106
+ 2. Brida reads only the project context needed for that work.
107
+ 3. Brida gives bounded tasks to independent workers through Herdr.
108
+ 4. Brida verifies results, records decisions and status, then reports back.
109
+
110
+ Herdr is the worker control plane. Native runtime delegation stays disabled so
111
+ worker ownership, evidence, and cleanup remain visible.
112
+
113
+ Project context lives in `projects/<project-slug>/` as a small set of Markdown
114
+ files for overview, current state, tasks, decisions, and references. Read the
115
+ [project memory policy](docs/policy/memory-policy.md) for the contract.
116
+
117
+ ## Development
118
+
119
+ Run the complete local validation suite before sharing a change:
120
+
121
+ ```bash
122
+ make check
123
+ ```
124
+
125
+ You can also run individual layers while iterating:
126
+
127
+ ```bash
128
+ make test-unit
129
+ make test-contract
130
+ make test-integration
131
+ make package-check
132
+ ```
133
+
134
+ The importable implementation is in `src/brida/`; stable command wrappers are
135
+ in `bin/` and `scripts/`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the change
136
+ workflow and [the repository layout](docs/architecture/repository-layout.md)
137
+ for module boundaries.
138
+
139
+ ## Learn more
140
+
141
+ - [Model routing and worker launch settings](docs/guides/model-routing.md)
142
+ - [Installed Codex dogfood](docs/guides/installable-dogfood.md)
143
+ - [Documentation index](docs/index.md)
144
+ - [Operating principles](docs/policy/operating-principles.md)
145
+ - [Security policy](SECURITY.md)
146
+
147
+ ## License
148
+
149
+ Brida is available under the [MIT License](LICENSE).
@@ -0,0 +1,43 @@
1
+ [build-system]
2
+ requires = ["setuptools>=68", "wheel"]
3
+ build-backend = "setuptools.build_meta"
4
+
5
+ [project]
6
+ name = "brichan"
7
+ version = "0.5.0"
8
+ description = "Repository-native AI Chief of Staff orchestration"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = {file = "LICENSE"}
12
+ authors = [{name = "Minh Tran"}]
13
+ keywords = ["ai", "orchestration", "codex", "claude-code", "chief-of-staff"]
14
+ classifiers = [
15
+ "Development Status :: 3 - Alpha",
16
+ "Environment :: Console",
17
+ "Intended Audience :: Developers",
18
+ "License :: OSI Approved :: MIT License",
19
+ "Operating System :: POSIX",
20
+ "Programming Language :: Python :: 3",
21
+ "Programming Language :: Python :: 3.10",
22
+ "Programming Language :: Python :: 3.11",
23
+ "Programming Language :: Python :: 3.12",
24
+ "Programming Language :: Python :: 3.13",
25
+ "Topic :: Software Development :: Build Tools",
26
+ ]
27
+ dependencies = []
28
+
29
+ [project.scripts]
30
+ brida = "brida.cli.runtime:main"
31
+ brida-codex = "brida.cli.codex:main"
32
+ brida-claude = "brida.cli.claude:main"
33
+ brida-herdr-agent-start = "brida.orchestration.worker_launch:main"
34
+ brida-validate-receipts = "brida.contracts.receipts.validation:main"
35
+
36
+ [tool.setuptools]
37
+ package-dir = {"" = "src"}
38
+
39
+ [tool.setuptools.packages.find]
40
+ where = ["src"]
41
+
42
+ [tool.setuptools.package-data]
43
+ "brida.resources.dogfood_v1" = ["**/*"]
@@ -0,0 +1,4 @@
1
+ [egg_info]
2
+ tag_build =
3
+ tag_date = 0
4
+
@@ -0,0 +1,193 @@
1
+ Metadata-Version: 2.4
2
+ Name: brichan
3
+ Version: 0.5.0
4
+ Summary: Repository-native AI Chief of Staff orchestration
5
+ Author: Minh Tran
6
+ License: MIT License
7
+
8
+ Copyright (c) 2026 Minh Tran
9
+
10
+ Permission is hereby granted, free of charge, to any person obtaining a copy
11
+ of this software and associated documentation files (the "Software"), to deal
12
+ in the Software without restriction, including without limitation the rights
13
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
14
+ copies of the Software, and to permit persons to whom the Software is
15
+ furnished to do so, subject to the following conditions:
16
+
17
+ The above copyright notice and this permission notice shall be included in all
18
+ copies or substantial portions of the Software.
19
+
20
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
21
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
22
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
23
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
24
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
25
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
26
+ SOFTWARE.
27
+
28
+ Keywords: ai,orchestration,codex,claude-code,chief-of-staff
29
+ Classifier: Development Status :: 3 - Alpha
30
+ Classifier: Environment :: Console
31
+ Classifier: Intended Audience :: Developers
32
+ Classifier: License :: OSI Approved :: MIT License
33
+ Classifier: Operating System :: POSIX
34
+ Classifier: Programming Language :: Python :: 3
35
+ Classifier: Programming Language :: Python :: 3.10
36
+ Classifier: Programming Language :: Python :: 3.11
37
+ Classifier: Programming Language :: Python :: 3.12
38
+ Classifier: Programming Language :: Python :: 3.13
39
+ Classifier: Topic :: Software Development :: Build Tools
40
+ Requires-Python: >=3.10
41
+ Description-Content-Type: text/markdown
42
+ License-File: LICENSE
43
+ Dynamic: license-file
44
+
45
+ # Brichan
46
+
47
+ ![Brichan coordinating a team of AI workers](assets/brida-hero.png)
48
+
49
+ Brichan is an AI Chief of Staff for Codex and Claude Code. Give it a project
50
+ goal; it keeps the necessary context, coordinates independent workers through
51
+ Herdr, checks their evidence, and records useful project state outside chat.
52
+ Its existing runtime package and console commands remain `brida` and
53
+ `brida-*` for compatibility.
54
+
55
+ ## Current dogfood scope
56
+
57
+ The primary one-user dogfood path is now an installed Python package running
58
+ inside an existing top-level Git repository. Installed-project mode currently
59
+ supports Codex on POSIX-compatible systems with Python 3.10+. Herdr is needed
60
+ only when Brida coordinates independent worker sessions.
61
+
62
+ Brida is not published to a package registry yet; the planned PyPI
63
+ distribution name is `brichan` (`pip install brichan`), while the importable
64
+ package stays `brida` and every console command keeps its existing name.
65
+ Until it is published, build the wheel locally from this repository with the
66
+ installer. It can be invoked from any directory and does not activate or
67
+ modify the target project's virtual environment:
68
+
69
+ ```bash
70
+ /absolute/path/to/brida/scripts/install-brida
71
+ ```
72
+
73
+ By default, the script creates a dedicated environment at
74
+ `$HOME/.local/share/brida/venv` and command symlinks in `$HOME/.local/bin`.
75
+ It automatically selects an available Python 3.10+ interpreter with `pip`,
76
+ `setuptools`, `venv`, and `wheel`, builds from a temporary source snapshot,
77
+ and installs all Brida console commands. No virtualenv activation is
78
+ required. If the command directory is not on `PATH`, the installer prints
79
+ the exact export to add to the shell profile.
80
+
81
+ ## Initialize a project
82
+
83
+ Preview the complete footprint before writing:
84
+
85
+ ```bash
86
+ brida init --project /absolute/path/to/repository
87
+ brida init --apply --project /absolute/path/to/repository
88
+ ```
89
+
90
+ `init` defaults to dry-run and performs zero writes. `--apply` creates only a
91
+ versioned `.brida/` directory containing managed policy, model routing, Herdr
92
+ skill resources, and mutable project memory. Repeating it against healthy
93
+ state is idempotent.
94
+
95
+ Diagnose and launch from any directory with an explicit target:
96
+
97
+ ```bash
98
+ brida status --project /absolute/path/to/repository
99
+ brida doctor --project /absolute/path/to/repository
100
+ brida run --project /absolute/path/to/repository -- <codex arguments>
101
+ ```
102
+
103
+ From inside a healthy initialized repository, bare `brida` also launches
104
+ Codex. The installed entrypoint:
105
+
106
+ - leaves `AGENTS.md`, `CLAUDE.md`, `.codex/`, and provider configuration
107
+ untouched;
108
+ - launches external `codex` directly at the target root and never executes
109
+ target-owned `bin/brida-*` wrappers;
110
+ - injects package-owned Brida policy and Herdr skill discovery;
111
+ - rejects native delegation, permission bypasses, cwd/scope widening, profiles,
112
+ remote execution, and arbitrary Codex configuration before `--`;
113
+ - treats option-looking text after `--` as literal prompt content.
114
+
115
+ State diagnostics reject malformed, dangling, symlinked, inaccessible, or
116
+ incompatible `.brida/` state without silently repairing it. Schema v1 has no
117
+ automatic migration: package-version changes require deliberate backup and
118
+ reinitialization. See the
119
+ [installed Codex dogfood guide](docs/guides/installable-dogfood.md) for the
120
+ exact footprint, exit codes, safeguards, and compatibility boundary.
121
+
122
+ ## Checkout compatibility and development
123
+
124
+ The original checkout workflow remains available for development and for
125
+ Claude Code:
126
+
127
+ ```bash
128
+ bin/brida
129
+ bin/brida --runtime claude
130
+ ```
131
+
132
+ Checkout mode uses package-owned `bin/brida-*` wrappers. Installed-project mode
133
+ does not. Coordinator defaults and worker routes are settings-driven, so the
134
+ coordinator and implementation, review, planning, or scan workers may use
135
+ different runtimes. See the [model-routing guide](docs/guides/model-routing.md)
136
+ to change defaults, select a named route, or use a one-off override.
137
+
138
+ The `brida-codex` and `brida-claude` console commands installed by `brichan`
139
+ remain checkout-oriented: `brida-codex` resolves coordinator routing from a
140
+ Brida source checkout (or `BRIDA_ROOT`) or from an already-initialized
141
+ project's `.brida/` state, while `brida-claude` resolves only from a checkout
142
+ or `BRIDA_ROOT`. Both are for development and checkout use, not standalone
143
+ installed-project launches. `--help`/`--version` work from any directory; the
144
+ [installed Codex dogfood guide](docs/guides/installable-dogfood.md) has the
145
+ exact boundary.
146
+
147
+ ## How it works
148
+
149
+ 1. You describe the outcome and constraints.
150
+ 2. Brida reads only the project context needed for that work.
151
+ 3. Brida gives bounded tasks to independent workers through Herdr.
152
+ 4. Brida verifies results, records decisions and status, then reports back.
153
+
154
+ Herdr is the worker control plane. Native runtime delegation stays disabled so
155
+ worker ownership, evidence, and cleanup remain visible.
156
+
157
+ Project context lives in `projects/<project-slug>/` as a small set of Markdown
158
+ files for overview, current state, tasks, decisions, and references. Read the
159
+ [project memory policy](docs/policy/memory-policy.md) for the contract.
160
+
161
+ ## Development
162
+
163
+ Run the complete local validation suite before sharing a change:
164
+
165
+ ```bash
166
+ make check
167
+ ```
168
+
169
+ You can also run individual layers while iterating:
170
+
171
+ ```bash
172
+ make test-unit
173
+ make test-contract
174
+ make test-integration
175
+ make package-check
176
+ ```
177
+
178
+ The importable implementation is in `src/brida/`; stable command wrappers are
179
+ in `bin/` and `scripts/`. See [CONTRIBUTING.md](CONTRIBUTING.md) for the change
180
+ workflow and [the repository layout](docs/architecture/repository-layout.md)
181
+ for module boundaries.
182
+
183
+ ## Learn more
184
+
185
+ - [Model routing and worker launch settings](docs/guides/model-routing.md)
186
+ - [Installed Codex dogfood](docs/guides/installable-dogfood.md)
187
+ - [Documentation index](docs/index.md)
188
+ - [Operating principles](docs/policy/operating-principles.md)
189
+ - [Security policy](SECURITY.md)
190
+
191
+ ## License
192
+
193
+ Brida is available under the [MIT License](LICENSE).
@@ -0,0 +1,44 @@
1
+ LICENSE
2
+ README.md
3
+ pyproject.toml
4
+ src/brichan.egg-info/PKG-INFO
5
+ src/brichan.egg-info/SOURCES.txt
6
+ src/brichan.egg-info/dependency_links.txt
7
+ src/brichan.egg-info/entry_points.txt
8
+ src/brichan.egg-info/top_level.txt
9
+ src/brida/__init__.py
10
+ src/brida/lifecycle.py
11
+ src/brida/project.py
12
+ src/brida/cli/__init__.py
13
+ src/brida/cli/_root.py
14
+ src/brida/cli/claude.py
15
+ src/brida/cli/codex.py
16
+ src/brida/cli/provider_commands.py
17
+ src/brida/cli/runtime.py
18
+ src/brida/contracts/__init__.py
19
+ src/brida/contracts/receipts/__init__.py
20
+ src/brida/contracts/receipts/discovery.py
21
+ src/brida/contracts/receipts/parser.py
22
+ src/brida/contracts/receipts/schema.py
23
+ src/brida/contracts/receipts/validation.py
24
+ src/brida/orchestration/__init__.py
25
+ src/brida/orchestration/herdr_client.py
26
+ src/brida/orchestration/layout.py
27
+ src/brida/orchestration/model_routing.py
28
+ src/brida/orchestration/worker_launch.py
29
+ src/brida/resources/__init__.py
30
+ src/brida/resources/dogfood_v1/__init__.py
31
+ src/brida/resources/dogfood_v1/config/model-routing.json
32
+ src/brida/resources/dogfood_v1/policy/bootstrap.md
33
+ src/brida/resources/dogfood_v1/policy/identity.md
34
+ src/brida/resources/dogfood_v1/policy/memory-policy.md
35
+ src/brida/resources/dogfood_v1/policy/operating-principles.md
36
+ src/brida/resources/dogfood_v1/project-memory/index.md
37
+ src/brida/resources/dogfood_v1/project-memory/main/current-state.md
38
+ src/brida/resources/dogfood_v1/project-memory/main/decisions.md
39
+ src/brida/resources/dogfood_v1/project-memory/main/overview.md
40
+ src/brida/resources/dogfood_v1/project-memory/main/references.md
41
+ src/brida/resources/dogfood_v1/project-memory/main/tasks.md
42
+ src/brida/resources/dogfood_v1/skills/herdr-orchestration/SKILL.md
43
+ src/brida/resources/dogfood_v1/skills/herdr-orchestration/references/commands.md
44
+ src/brida/resources/dogfood_v1/skills/herdr-orchestration/references/task-packet.md
@@ -0,0 +1,6 @@
1
+ [console_scripts]
2
+ brida = brida.cli.runtime:main
3
+ brida-claude = brida.cli.claude:main
4
+ brida-codex = brida.cli.codex:main
5
+ brida-herdr-agent-start = brida.orchestration.worker_launch:main
6
+ brida-validate-receipts = brida.contracts.receipts.validation:main
@@ -0,0 +1 @@
1
+ brida
@@ -0,0 +1,3 @@
1
+ """Brida's importable orchestration core."""
2
+
3
+ __version__ = "0.5.0"
@@ -0,0 +1 @@
1
+ """Stable Brida command-line entrypoints."""