specfuse-orchestrator 0.3.0__tar.gz

specfuse_orchestrator-0.3.0/.gitignore

@@ -0,0 +1,34 @@
+# JetBrains project folder
+.idea/
+
+# macOS
+.DS_Store
+
+# Editor swap / backup files
+*.swp
+*.swo
+*~
+.*.swp
+.*.swo
+
+# Logs
+*.log
+
+# Transient orchestrator state
+/events/*.tmp
+/inbox/*.processed/
+# Loop gitignore additions — written by specfuse init / specfuse upgrade.
+# Un-ignore .specfuse/ in case the repo's root .gitignore already ignores it;
+# the loop driver uses git as its state backend and silently misbehaves when
+# .specfuse/ is untracked.
+!.specfuse/
+# Ignore per-feature work/ scratch directories (large, ephemeral).
+.specfuse/**/work/
+# Ignore loop runtime artifacts.
+.specfuse/.loop.lock
+.specfuse/.scratch-*
+.specfuse/scripts/__pycache__/
+
+# specfuse-orchestrator packaging
+/specfuse/orchestrator/_substrate/
+/dist/

specfuse_orchestrator-0.3.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for describing the origin of the Work and
+      reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Support. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or support.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Specfuse contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

specfuse_orchestrator-0.3.0/NOTICE

@@ -0,0 +1,6 @@
+Specfuse Orchestrator
+Copyright 2026 Specfuse contributors
+
+This product is licensed under the Apache License, Version 2.0.
+See the LICENSE file for the full license text, or obtain a copy at:
+http://www.apache.org/licenses/LICENSE-2.0

specfuse_orchestrator-0.3.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: specfuse-orchestrator
+Version: 0.3.0
+Summary: Specfuse orchestrator: initiative coordination drivers for multi-repo Specfuse loops.
+Project-URL: Homepage, https://github.com/Specfuse/orchestrator
+Project-URL: Source, https://github.com/Specfuse/orchestrator
+Author: Specfuse contributors
+License: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Keywords: agents,gate-cycle,orchestrator,planning,specfuse
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Code Generators
+Requires-Python: >=3.10
+Requires-Dist: jsonschema>=4.18
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: coverage>=7.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Specfuse Orchestrator
+
+Specfuse Orchestrator is a filesystem-based coordination layer for multi-agent software development workflows. It uses a directory structure of features, events, and an agent inbox — along with agent configurations, shared skills, rules, schemas, and templates — to let specs, PM, component, and QA agents collaborate on feature delivery without a central runtime. This repository holds the orchestrator scaffolding; downstream projects consume it via a template clone.
+
+For background, goals, and design rationale, see [`docs/orchestrator-vision.md`](docs/orchestrator-vision.md). For the directory layout, protocols, and architectural decisions, see [`docs/orchestrator-architecture.md`](docs/orchestrator-architecture.md). A condensed overview is in [`docs/orchestrator-design-summary.md`](docs/orchestrator-design-summary.md). The phased build plan is in [`docs/orchestrator-implementation-plan.md`](docs/orchestrator-implementation-plan.md).
+
+## Status
+
+Phases 0–4 complete; Phase 4.5 (onboarding agent) added to support real-project adoption. The four operational agents are at frozen v1 baselines; the onboarding meta-role is at v0.1 draft.
+
+| Role | Version | Frozen | Phase |
+|---|---|---|---|
+| [Specs](agents/specs/) | 1.0.1 | yes | Phase 4 |
+| [PM](agents/pm/) | 1.6.3 | yes | Phase 2 |
+| [Component](agents/component/) | 1.5.2 | yes | Phase 1 |
+| [QA](agents/qa/) | 1.5.2 | yes | Phase 3 |
+| [Onboarding](agents/onboarding/) | 0.1.0 | no (draft) | Phase 4.5 |
+
+The idea → spec → plan → implement → QA → done pipeline is operational end-to-end. **Phase 5** (generator feedback loop, override-registry inversion, config-steward meta-agent) is the remaining build phase per the implementation plan.
+
+## Getting started on a real project
+
+**Five-minute path:** see [`GETTING_STARTED.md`](GETTING_STARTED.md). One `git clone` + `./scripts/setup.sh` does the entire one-time setup (strip, git re-init, private GitHub repo creation, upstream remote configuration, personalized next-steps doc). Then `/onboard` in a Claude Code session walks you through the rest.
+
+The orchestration repo is the **process-state store for one product** (singleton per product). Template-cloned to your own org as `<your-org>/<your-product>-orchestration`. Full workflow — including how to **pull upstream improvements** into your downstream over time and how to **contribute fixes back upstream** — is documented in [`docs/upstream-downstream-sync.md`](docs/upstream-downstream-sync.md).
+
+The orchestrator engages **downstream of product discussion**. Brainstorming, business decisions, and feature ideation belong in your project's **product reference repo** (the `/product/` subtree); the orchestrator picks up at feature-intake when an idea crystallizes into a feature.
+
+Two project shapes are supported, both via the same setup script:
+
+- **Greenfield:** new project, no repos yet. The onboarding agent's `bootstrap-greenfield` skill produces a setup checklist covering environment prereqs, repo-creation order, per-repo conventions, and first-feature scoping.
+- **Brownfield:** existing project with code, specs, and possibly in-flight features. The onboarding agent's `repo-inventory` skill walks each repo and produces readiness assessments; `integration-plan` then drafts a phased rollout (pilot → expand → import in-flight → steady state) that brings the project under orchestrator coordination without disrupting current delivery.
+
+The exact sequence — including the literal commands — is in [`GETTING_STARTED.md`](GETTING_STARTED.md). The `setup.sh` script asks for your project type and chooses the right onboarding skill for you.
+
+### Day-to-day operation
+
+Once a project is wired:
+
+- [`docs/operator-runbook.md`](docs/operator-runbook.md) — quickstart for driving a feature from idea through `planning` with the specs agent. Includes environment prerequisites.
+- [`docs/operator-pipeline-reference.md`](docs/operator-pipeline-reference.md) — full-lifecycle operator reference covering PM, component, and QA sessions, inbox handling, spec-issue triage, and escalations.
+
+### Licensing — upstream vs. downstream
+
+This **upstream** repository is licensed under [Apache 2.0](LICENSE). You can incorporate the scaffolding into your own work, including proprietary work, with attribution.
+
+A **downstream** orchestration repo created via [`scripts/setup.sh`](scripts/setup.sh) holds your project's coordination state — `/features/`, `/events/`, `/inbox/`, `/project/` — alongside the upstream-derived scaffolding. Most teams want this content treated as **proprietary**, not Apache 2.0. The setup script handles this automatically:
+
+- The upstream's `LICENSE` (Apache 2.0) is replaced with a **proprietary placeholder** carrying your org name as the copyright holder and the current year.
+- A `NOTICES.md` is created at the downstream's root with full Apache 2.0 attribution and reproduces the upstream's `LICENSE` and `NOTICE` text in full — satisfying Apache 2.0 §4.b for the upstream-derived files (`agents/`, `shared/`, `scripts/`, `docs/`, the top-level Markdown docs, `.github/`, `.claude/`).
+- Modifications you make to upstream-derived files remain governed by Apache 2.0; original work added by you (`/features/`, `/events/`, `/inbox/`, project-specific `/agents/<role>/rules/`, `/project/` content beyond `README.md`) is governed by your downstream's `LICENSE`.
+
+If your downstream is itself open-source rather than proprietary, [`scripts/setup.sh`](scripts/setup.sh) documents the one-line revert to Apache 2.0 in the generated `project/NEXT_STEPS.md`. Either way, the licensing decision is **explicit and visible** in your downstream from day one — no inherited LICENSE files quietly imply terms that don't match your intent.
+
+### Slash commands (in a Claude Code session)
+
+Project-scoped slash commands wrap the most common operations and become available via `/` autocomplete when you open a Claude Code session at the orchestration repo:
+
+- `/onboard` — switch into the onboarding-agent role; runs `repo-inventory`, `integration-plan`, or `bootstrap-greenfield` depending on project state.
+- `/sync-upstream` — periodic upstream sync; reviews and cherry-picks upstream commits since the `UPSTREAM` anchor.
+- `/contribute-upstream` — extract scaffolding-only patches from downstream commits for an upstream PR.
+
+The commands wrap the equivalent shell scripts under [`scripts/`](scripts/) and are documented in [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`docs/upstream-downstream-sync.md`](docs/upstream-downstream-sync.md).

specfuse_orchestrator-0.3.0/README.md

@@ -0,0 +1,63 @@
+# Specfuse Orchestrator
+
+Specfuse Orchestrator is a filesystem-based coordination layer for multi-agent software development workflows. It uses a directory structure of features, events, and an agent inbox — along with agent configurations, shared skills, rules, schemas, and templates — to let specs, PM, component, and QA agents collaborate on feature delivery without a central runtime. This repository holds the orchestrator scaffolding; downstream projects consume it via a template clone.
+
+For background, goals, and design rationale, see [`docs/orchestrator-vision.md`](docs/orchestrator-vision.md). For the directory layout, protocols, and architectural decisions, see [`docs/orchestrator-architecture.md`](docs/orchestrator-architecture.md). A condensed overview is in [`docs/orchestrator-design-summary.md`](docs/orchestrator-design-summary.md). The phased build plan is in [`docs/orchestrator-implementation-plan.md`](docs/orchestrator-implementation-plan.md).
+
+## Status
+
+Phases 0–4 complete; Phase 4.5 (onboarding agent) added to support real-project adoption. The four operational agents are at frozen v1 baselines; the onboarding meta-role is at v0.1 draft.
+
+| Role | Version | Frozen | Phase |
+|---|---|---|---|
+| [Specs](agents/specs/) | 1.0.1 | yes | Phase 4 |
+| [PM](agents/pm/) | 1.6.3 | yes | Phase 2 |
+| [Component](agents/component/) | 1.5.2 | yes | Phase 1 |
+| [QA](agents/qa/) | 1.5.2 | yes | Phase 3 |
+| [Onboarding](agents/onboarding/) | 0.1.0 | no (draft) | Phase 4.5 |
+
+The idea → spec → plan → implement → QA → done pipeline is operational end-to-end. **Phase 5** (generator feedback loop, override-registry inversion, config-steward meta-agent) is the remaining build phase per the implementation plan.
+
+## Getting started on a real project
+
+**Five-minute path:** see [`GETTING_STARTED.md`](GETTING_STARTED.md). One `git clone` + `./scripts/setup.sh` does the entire one-time setup (strip, git re-init, private GitHub repo creation, upstream remote configuration, personalized next-steps doc). Then `/onboard` in a Claude Code session walks you through the rest.
+
+The orchestration repo is the **process-state store for one product** (singleton per product). Template-cloned to your own org as `<your-org>/<your-product>-orchestration`. Full workflow — including how to **pull upstream improvements** into your downstream over time and how to **contribute fixes back upstream** — is documented in [`docs/upstream-downstream-sync.md`](docs/upstream-downstream-sync.md).
+
+The orchestrator engages **downstream of product discussion**. Brainstorming, business decisions, and feature ideation belong in your project's **product reference repo** (the `/product/` subtree); the orchestrator picks up at feature-intake when an idea crystallizes into a feature.
+
+Two project shapes are supported, both via the same setup script:
+
+- **Greenfield:** new project, no repos yet. The onboarding agent's `bootstrap-greenfield` skill produces a setup checklist covering environment prereqs, repo-creation order, per-repo conventions, and first-feature scoping.
+- **Brownfield:** existing project with code, specs, and possibly in-flight features. The onboarding agent's `repo-inventory` skill walks each repo and produces readiness assessments; `integration-plan` then drafts a phased rollout (pilot → expand → import in-flight → steady state) that brings the project under orchestrator coordination without disrupting current delivery.
+
+The exact sequence — including the literal commands — is in [`GETTING_STARTED.md`](GETTING_STARTED.md). The `setup.sh` script asks for your project type and chooses the right onboarding skill for you.
+
+### Day-to-day operation
+
+Once a project is wired:
+
+- [`docs/operator-runbook.md`](docs/operator-runbook.md) — quickstart for driving a feature from idea through `planning` with the specs agent. Includes environment prerequisites.
+- [`docs/operator-pipeline-reference.md`](docs/operator-pipeline-reference.md) — full-lifecycle operator reference covering PM, component, and QA sessions, inbox handling, spec-issue triage, and escalations.
+
+### Licensing — upstream vs. downstream
+
+This **upstream** repository is licensed under [Apache 2.0](LICENSE). You can incorporate the scaffolding into your own work, including proprietary work, with attribution.
+
+A **downstream** orchestration repo created via [`scripts/setup.sh`](scripts/setup.sh) holds your project's coordination state — `/features/`, `/events/`, `/inbox/`, `/project/` — alongside the upstream-derived scaffolding. Most teams want this content treated as **proprietary**, not Apache 2.0. The setup script handles this automatically:
+
+- The upstream's `LICENSE` (Apache 2.0) is replaced with a **proprietary placeholder** carrying your org name as the copyright holder and the current year.
+- A `NOTICES.md` is created at the downstream's root with full Apache 2.0 attribution and reproduces the upstream's `LICENSE` and `NOTICE` text in full — satisfying Apache 2.0 §4.b for the upstream-derived files (`agents/`, `shared/`, `scripts/`, `docs/`, the top-level Markdown docs, `.github/`, `.claude/`).
+- Modifications you make to upstream-derived files remain governed by Apache 2.0; original work added by you (`/features/`, `/events/`, `/inbox/`, project-specific `/agents/<role>/rules/`, `/project/` content beyond `README.md`) is governed by your downstream's `LICENSE`.
+
+If your downstream is itself open-source rather than proprietary, [`scripts/setup.sh`](scripts/setup.sh) documents the one-line revert to Apache 2.0 in the generated `project/NEXT_STEPS.md`. Either way, the licensing decision is **explicit and visible** in your downstream from day one — no inherited LICENSE files quietly imply terms that don't match your intent.
+
+### Slash commands (in a Claude Code session)
+
+Project-scoped slash commands wrap the most common operations and become available via `/` autocomplete when you open a Claude Code session at the orchestration repo:
+
+- `/onboard` — switch into the onboarding-agent role; runs `repo-inventory`, `integration-plan`, or `bootstrap-greenfield` depending on project state.
+- `/sync-upstream` — periodic upstream sync; reviews and cherry-picks upstream commits since the `UPSTREAM` anchor.
+- `/contribute-upstream` — extract scaffolding-only patches from downstream commits for an upstream PR.
+
+The commands wrap the equivalent shell scripts under [`scripts/`](scripts/) and are documented in [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`docs/upstream-downstream-sync.md`](docs/upstream-downstream-sync.md).

specfuse_orchestrator-0.3.0/agents/README.md

@@ -0,0 +1,47 @@
+# Agents
+
+Role configurations for the orchestrator's agents. Four **operational** agents drive per-feature work (specs, PM, component, QA); one **meta-role** (onboarding) operates project-wide to prepare a project for orchestrator coordination. Each role has its own directory with the layout fixed by architecture §5.2:
+
+```
+/agents/<role>/
+    CLAUDE.md       — role prompt and entry point
+    version.md      — current version and changelog
+    skills/         — role-specific skills
+    rules/          — role-specific rule overrides (empty at v1 by design)
+```
+
+Every `CLAUDE.md` opens by pulling in the full [`/shared/rules/`](../shared/rules/README.md) set, then layers its own role-specific behavior on top. The partitioning test is architecture §5.3: **if every role must behave identically under a rule, it belongs in `/shared/`; if two roles would diverge, it belongs under `/agents/<role>/rules/`.** At v1 no role overrides a shared rule; per-role `rules/` directories exist but are intentionally empty.
+
+## Operational roles (per-feature)
+
+| Role | Version | Frozen | Skills |
+|---|---|---|---|
+| [`specs/`](specs/CLAUDE.md) | 1.0.1 | Phase 4 (2026-04-26) | feature-intake, spec-drafting, spec-validation, spec-issue-triage |
+| [`pm/`](pm/CLAUDE.md) | 1.6.3 | Phase 2 (2026-04-23) | task-decomposition, plan-review, issue-drafting, dependency-recomputation, template-coverage-check |
+| [`component/`](component/CLAUDE.md) | 1.5.2 | Phase 1 (2026-04-22) | verification, pr-submission, escalation |
+| [`qa/`](qa/CLAUDE.md) | 1.5.2 | Phase 3 (2026-04-24) | qa-authoring, qa-execution, qa-regression, qa-curation |
+
+- [`specs/`](specs/CLAUDE.md) — partners with the human in an interactive session to draft specifications, run Specfuse validation, and usher a feature from `drafting` through `validating` into `planning`. Reads and writes `/product/`; writes the feature registry during its phase of the lifecycle. Session-driven (the human is the primary driver), unlike the three task-driven downstream agents.
+- [`pm/`](pm/CLAUDE.md) — converts a validated spec into a task graph, co-authors work unit prompts with the human, creates GitHub issues in component repos, and owns dependency recomputation. Sole writer of task-level `pending → ready` transitions.
+- [`component/`](component/CLAUDE.md) — one instance per component repo; picks up `ready` task issues, writes hand-written code, opens PRs, and reconciles overrides for its repo. Does not cross repo boundaries.
+- [`qa/`](qa/CLAUDE.md) — authors test plans, executes them, curates the regression suite. Owns `qa_authoring`, `qa_execution`, `qa_curation`, and `qa_regression` task types; files regression issues against implementation tasks and spec issues when ambiguities surface.
+
+## Meta-roles (project-wide)
+
+| Role | Version | Frozen | Skills |
+|---|---|---|---|
+| [`onboarding/`](onboarding/CLAUDE.md) | 0.1.0 | no (Phase 4.5 draft) | repo-inventory, integration-plan, bootstrap-greenfield |
+
+- [`onboarding/`](onboarding/CLAUDE.md) — prepares a project for orchestrator coordination at integration time. Inventories repos, drafts integration or bootstrap plans, identifies orchestrator-readiness gaps. Operates project-wide rather than per-feature; runs once at integration and rarely thereafter. Artifacts land in [`/project/`](../project/). v0.1 draft, intended to be exercised on a real project and hardened.
+
+A second meta-role (config-steward) is named in architecture §5.1 and §5.4 and lands in **Phase 5** alongside the generator feedback loop. It will watch commits to `/agents/` and `/shared/` and steward version bumps. See [`docs/orchestrator-implementation-plan.md`](../docs/orchestrator-implementation-plan.md) §"Phase 5".
+
+## Versioning and change process
+
+Each role carries a semantic version in `version.md`. Any change to a role's `CLAUDE.md`, skills, or rules requires a version bump and a changelog line. The event log records which agent version handled each event, so behavior changes can be reconstructed after the fact.
+
+The frozen baselines above are the contract Phase 5+ inherits: changes to a frozen surface require architectural justification. Each role's `version.md` cites the freezing work unit and retrospective.
+
+The full change-management protocol — including how version bumps are proposed, reviewed, and applied alongside role-config changes — lives in the config-steward agent's future specification (Phase 5; see architecture §5.4). Until that agent exists, version bumps are made by hand by the committer: bump the version in `version.md`, add a changelog entry describing the change, and commit the bump alongside the underlying change in the same commit.
+
+Role configs are produced and revised in coordination with `/shared/` — the shared substrate every role depends on. When a shared rule, schema, or template changes, re-read every role's `CLAUDE.md` to confirm nothing drifts; when a role config changes, confirm it still reads coherently against the current `/shared/`.

specfuse_orchestrator-0.3.0/agents/component/README.md

@@ -0,0 +1,30 @@
+# Component agent
+
+The component agent is the worker instance that implements tasks inside a single component repository. One instance runs per component repo; its scope is hand-written code in that repo plus the cross-repo artifacts (events, overrides, escalations, spec issues) its tasks produce.
+
+## What it does
+
+- Picks up `ready` task issues in its assigned component repo.
+- Writes hand-written code on a feature branch.
+- Opens a pull request, gated by role-specific verification.
+- Files spec issues when generated code is wrong (never edits generated files in place).
+- Reconciles overrides against its repo after Specfuse regeneration runs.
+- Escalates to the human on the four reasons enumerated in [`escalation-protocol.md`](../../shared/rules/escalation-protocol.md).
+
+## What it does not do
+
+- Planning, task creation, or dependency recomputation (PM agent).
+- Test plan authoring or execution (QA agent).
+- Merge closure (merge watcher, on branch-protection green).
+- Any write to a second repository beyond the one it was instantiated for.
+
+## Layout
+
+- [`CLAUDE.md`](CLAUDE.md) — the agent's configuration: role definition, transitions owned, output artifacts, verification, PR and escalation disciplines, and anti-patterns.
+- [`version.md`](version.md) — current config version and changelog.
+- [`skills/`](skills/) — role-specific skills layered on top of the shared substrate in [`/shared/`](../../shared/).
+- [`rules/`](rules/) — role-specific rule overrides. Empty at v1.0.0 by design.
+
+## Where this role fits
+
+See [`orchestrator-architecture.md`](../../docs/orchestrator-architecture.md) §5 for the full role taxonomy, and §6.2–§6.3 for task state and transition ownership. The architecture document is normative; this directory's files layer operational detail on top of it.

specfuse_orchestrator-0.3.0/agents/onboarding/README.md

@@ -0,0 +1,28 @@
+# Onboarding agent
+
+The onboarding agent is a **meta-role** that prepares a project for orchestrator coordination. Unlike the four operational agents (specs, PM, component, QA) which operate per-feature, the onboarding agent operates **project-wide** — it runs once when a team adopts the orchestrator and occasionally afterward when the project's repo set changes.
+
+## What it does
+
+- **Inventories the project's repositories** — purpose, language/framework, build/test commands, current spec coverage, in-flight work, orchestrator-readiness.
+- **Drafts an integration plan** for brownfield projects — phased transition, which features go through the orchestrator first, how in-flight work is imported, per-repo onboarding checklist, risk register.
+- **Drafts a setup checklist** for greenfield projects — environment prerequisites, repo creation, initial conventions.
+
+## What it does not do
+
+- Per-feature work of any kind (specs, PM, component, QA agents handle that).
+- Run the integration itself — the agent produces a plan; the human executes it.
+- Replace product brainstorming or design — those happen in the project's product reference repo, upstream of the orchestrator (architecture §4.1).
+
+## Layout
+
+- [`CLAUDE.md`](CLAUDE.md) — role configuration.
+- [`version.md`](version.md) — current version (v0.1.0 draft) and changelog.
+- [`skills/`](skills/) — three v0.1 skills: [`repo-inventory`](skills/repo-inventory/SKILL.md), [`integration-plan`](skills/integration-plan/SKILL.md), [`bootstrap-greenfield`](skills/bootstrap-greenfield/SKILL.md).
+- [`rules/`](rules/) — empty at v0.1 by design.
+
+## Where this role fits
+
+This is a Phase 4.5 interlude added to support real-project adoption. Companion meta-role (config-steward, Phase 5) is also project-level rather than per-feature; together they form the orchestrator's meta-role surface. See the implementation plan's "Phase 4.5" section for the rationale.
+
+Artifacts produced by this agent land in [`/project/`](../../project/) in the orchestration repo. That subtree is the durable output of onboarding work — read it cold to understand what the project looks like and how integration is going.

specfuse_orchestrator-0.3.0/agents/pm/README.md

@@ -0,0 +1,32 @@
+# PM agent
+
+The PM agent turns a validated product specification into an executable task graph: it decomposes the feature into implementation and QA tasks, assigns each to the correct component repo, collaborates with the human on work unit prompts, opens GitHub issues, and recomputes task dependencies on every completion. One instance runs per active feature.
+
+## What it does
+
+- Reads a validated feature spec and drafts the task graph into the feature registry frontmatter.
+- Materializes the task graph as a human-editable plan for the `plan_review` stage, and re-ingests the edits as the new source of truth.
+- Opens `work-unit-issue.md`-compliant GitHub issues in the assigned component repos, re-verifying every factual claim about target-repo state at drafting time.
+- Recomputes dependencies on every `task_completed` event and flips newly-unblocked tasks from `pending` to `ready`.
+- Checks Specfuse template coverage at planning time via a stub protocol; escalates gaps rather than discovering them mid-implementation.
+- Closes the feature when its last task reaches `done`.
+
+## What it does not do
+
+- Specification authoring or validation (specs agent).
+- Code or test writing (component and QA agents).
+- Approval of a plan (human owns `plan_review → generating`).
+- Merge closure (merge watcher, gated on branch protection).
+- Writing to `/product/`, `/overrides/`, or any component-repo code path.
+
+## Layout
+
+- [`CLAUDE.md`](CLAUDE.md) — the agent's configuration: role definition, transitions owned, output artifacts, verification, escalation, and anti-patterns.
+- [`version.md`](version.md) — current config version and changelog.
+- [`issue-drafting-spec.md`](issue-drafting-spec.md) — inherited forward specification the issue-drafting skill must honor on day one (authored in WU 1.9).
+- [`skills/`](skills/) — role-specific skills layered on top of the shared substrate in [`/shared/`](../../shared/). Populated by Phase 2 WUs 2.2–2.6.
+- [`rules/`](rules/) — role-specific rule overrides. Empty at v1.0.0 by design.
+
+## Where this role fits
+
+See [`orchestrator-architecture.md`](../../docs/orchestrator-architecture.md) §5 for the full role taxonomy and §6.2–§6.3 for task state and transition ownership. The PM agent is the **sole writer of `pending → ready` task transitions** and the **sole owner of dependency recomputation** — centralizing both is what keeps the dependency graph auditable and race-free. The architecture document is normative; this directory's files layer operational detail on top of it.

specfuse_orchestrator-0.3.0/agents/qa/README.md

@@ -0,0 +1,30 @@
+# QA agent
+
+The QA agent authors test plans from validated acceptance criteria, executes them against the implementation once it lands, files structured regression artifacts when execution fails, and curates the growing regression suite. Its cadence is longitudinal — a single feature traverses qa-authoring → qa-execution → (possibly regression → re-execution) → curation over multiple cycles. One agent instance runs per active QA task; its scope spans the product specs repo (test plans), the component repo(s) under test (indirectly, through regression artifacts), and the orchestration repo (events, inbox, escalations).
+
+## What it does
+
+- Reads a validated feature's acceptance criteria and authors a test plan into `/product/test-plans/FEAT-YYYY-NNNN.md` in the product specs repo.
+- Executes the plan idempotently against the component repo(s) under test and emits structured `qa_execution_completed` or `qa_execution_failed` events keyed on `(task_correlation_id, commit_sha)`.
+- On a qa-execution failure, files a regression artifact via `/inbox/qa-regression/` that spawns a new implementation task — without writing labels or state to the task under test.
+- On a qa-execution repeat failure, escalates `spinning_detected` on the original implementation task via an event, again without any label write.
+- Curates the regression suite within a bounded scan budget: dedups overlaps, retires spec-removed orphans, consolidates failure-clustered tests. All curation changes land through a reviewable PR.
+
+## What it does not do
+
+- Hand-written code or test harness implementation (component agent).
+- Specification authoring outside `/product/test-plans/` (specs agent).
+- Task creation, dependency recomputation, or feature-level state transitions (PM agent).
+- Merge closure (merge watcher, on branch-protection green).
+- Any label or state write on a task the QA agent does not own — including the implementation task under test, even when qa-execution reveals a regression.
+
+## Layout
+
+- [`CLAUDE.md`](CLAUDE.md) — the agent's configuration: role definition, transitions owned, output artifacts, the cross-task regression invariant, verification, escalation, and anti-patterns.
+- [`version.md`](version.md) — current config version and changelog.
+- [`skills/`](skills/) — role-specific skills layered on top of the shared substrate in [`/shared/`](../../shared/). Populated by Phase 3 WUs 3.2–3.5.
+- [`rules/`](rules/) — role-specific rule overrides. Empty at v1.0.0 by design.
+
+## Where this role fits
+
+See [`orchestrator-architecture.md`](../../docs/orchestrator-architecture.md) §5 for the full role taxonomy, §6.2–§6.3 for task state and transition ownership, §6.4 for the spinning-detection / regression-vs-escalation rule the QA agent applies on qa-execution failures, and §4.3 for the canonical test plan location. The architecture document is normative; this directory's files layer operational detail on top of it.

specfuse_orchestrator-0.3.0/agents/specs/README.md

@@ -0,0 +1,29 @@
+# Specs agent
+
+The specs agent partners with the human in an interactive Claude Code session to turn a feature idea into validated product specifications. It creates feature registry entries, drafts OpenAPI / AsyncAPI / Arazzo specifications under `/product/` in the product specs repo, runs Specfuse validation, and triages spec issues routed from downstream agents. Its cadence is session-driven — the human opens a Claude Code session and collaborates with the agent, unlike the three task-driven downstream agents (PM, component, QA) that pick up structured work from issues or event triggers.
+
+## What it does
+
+- Creates feature registry entries in the orchestration repo, minting correlation IDs and emitting `feature_created` events.
+- Drafts and iterates on product specifications collaboratively with the human inside `/product/` in the specs repo.
+- Invokes Specfuse validation and presents actionable feedback on failures.
+- Owns the `drafting → validating → planning` segment of the feature state machine; hands off to the PM agent at `planning`.
+- Triages spec issues routed from downstream agents via `/inbox/spec-issue/`, resolving them in `/product/` or re-routing to the generator project.
+
+## What it does not do
+
+- Task decomposition, dependency recomputation, or issue creation (PM agent).
+- Code or test writing (component and QA agents).
+- Merge gating or closure (merge watcher, on branch-protection green).
+- Any write to `/business/`, `/product/test-plans/`, `/overrides/`, or component-repo code paths.
+
+## Layout
+
+- [`CLAUDE.md`](CLAUDE.md) — the agent's configuration: role definition, interaction model, transitions owned, output surfaces, verification, escalation, and anti-patterns.
+- [`version.md`](version.md) — current config version and changelog.
+- [`skills/`](skills/) — role-specific skills layered on top of the shared substrate in [`/shared/`](../../shared/). Populated by Phase 4 WUs 4.2–4.5 (feature-intake, spec-drafting, spec-validation, spec-issue-triage).
+- [`rules/`](rules/) — role-specific rule overrides. Empty at v1.0.0 by design.
+
+## Where this role fits
+
+See [`orchestrator-architecture.md`](../../docs/orchestrator-architecture.md) §5 for the full role taxonomy, §6.1 for the feature state machine (`drafting → validating → planning` transitions), and §6.3 for transition ownership. The architecture document is normative; this directory's files layer operational detail on top of it.

specfuse_orchestrator-0.3.0/hatch_build.py

@@ -0,0 +1,28 @@
+"""Hatch build hook: copy shared/** into specfuse/orchestrator/_substrate/.
+
+`shared/` is the single source of truth for rules, schemas, and templates;
+this hook mirrors it into the package at build time so the wheel ships a
+self-contained substrate without a committed duplicate.
+"""
+
+import shutil
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class SubstrateBuildHook(BuildHookInterface):
+    def initialize(self, version, build_data):
+        root = Path(self.root)
+        src = root / "shared"
+        dest = root / "specfuse" / "orchestrator" / "_substrate"
+
+        if dest.exists():
+            shutil.rmtree(dest)
+        shutil.copytree(src, dest)
+
+        # `_substrate/` is gitignored (build artifact), so hatchling's default
+        # VCS-aware file selection would otherwise drop it from the wheel.
+        build_data.setdefault("artifacts", []).append(
+            "specfuse/orchestrator/_substrate/**/*"
+        )