feat: share Advanced Delivery and Lean Delivery arrangements

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Contribution guide
+    url: https://github.com/rafaelob/fleet-codex/blob/main/CONTRIBUTING.md
+    about: Learn how to submit an arrangement, correction or pull request.

.github/ISSUE_TEMPLATE/correction.yml

@@ -0,0 +1,30 @@
+name: Correction or bug
+description: Report a problem or suggest a correction to an existing arrangement or tool.
+title: "[Correction]: "
+body:
+  - type: input
+    id: component
+    attributes:
+      label: Arrangement or component
+      description: For example Advanced Delivery, Lean Delivery, a skill, plugin, spawn hook or installation guide.
+    validations:
+      required: true
+  - type: textarea
+    id: behavior
+    attributes:
+      label: Current and expected behavior
+      description: Explain what happens now and what should happen instead.
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Reproduction and environment
+      description: Include the exact Codex version, platform and minimal reproduction. Remove credentials, personal paths and private project content.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Suggested correction
+      description: If known, describe a fix or link an existing pull request.

.github/ISSUE_TEMPLATE/new-arrangement.yml

@@ -0,0 +1,30 @@
+name: New arrangement
+description: Propose a new lead and subagent combination.
+title: "[Arrangement]: "
+body:
+  - type: textarea
+    id: purpose
+    attributes:
+      label: Purpose and audience
+      description: What work does the arrangement serve, and how does it differ from existing options?
+    validations:
+      required: true
+  - type: textarea
+    id: allocation
+    attributes:
+      label: Proposed allocation
+      description: Describe the lead, specialist roles, model and effort choices, and suggested concurrency.
+    validations:
+      required: true
+  - type: textarea
+    id: components
+    attributes:
+      label: Optional components and licensing
+      description: Identify proposed public skills or hooks, their sources and licenses. Do not include personal configuration or credentials.
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Compatibility and evidence
+      description: Give the Codex version, platform and sanitized observations. State clearly what has not yet been tested.
+    validations:
+      required: true

.github/ISSUE_TEMPLATE/new-component.yml

@@ -0,0 +1,35 @@
+name: New workflow component
+description: Propose an independent skill, plugin or hook for community reuse.
+title: "[Component]: "
+body:
+  - type: dropdown
+    id: kind
+    attributes:
+      label: Component type
+      options:
+        - Skill
+        - Plugin
+        - Hook
+    validations:
+      required: true
+  - type: textarea
+    id: purpose
+    attributes:
+      label: Workflow and value
+      description: Explain the situations this component helps, its boundaries and existing alternatives.
+    validations:
+      required: true
+  - type: textarea
+    id: packaging
+    attributes:
+      label: Package and access
+      description: Describe the format, bundled capabilities, license, dependencies, permissions and external data flow. No credentials or private endpoints.
+    validations:
+      required: true
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Validation and installation evidence
+      description: Include the exact runtime version, platform and sanitized results, or explicitly identify what is not tested yet.
+    validations:
+      required: true

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Arrangement or component and purpose
+
+Describe the intended work, division of responsibility and tradeoffs.
+
+## Changes
+
+List configuration, instruction, skill, plugin or hook changes and licensing provenance.
+
+## Functional evidence
+
+Provide exact Codex version, platform and sanitized results for installation,
+role/model selection and delegation. For hook changes, include real allow/deny
+evidence. State unavailable or unmeasured checks explicitly.
+For component-only PRs, demonstrate the changed component's real entry point.
+For plugins, identify the manifest format, bundled capabilities and upstream
+schema check; structural preflight is not installation evidence.
+
+## Checks
+
+- [ ] Catalog validator and relevant executable tests pass.
+- [ ] No credentials, personal paths, private services or whole-home config dumps.
+- [ ] Component licenses and notices are preserved.
+- [ ] Version, installation instructions and changelog describe the final change.

.github/workflows/validate.yml

@@ -0,0 +1,29 @@
+name: Validate catalog
+
+on:
+  pull_request:
+  push:
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Python ${{ matrix.python }} on ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+        python: ["3.11", "3.14"]
+    steps:
+      - uses: actions/checkout@fbc6f3992d24b796d5a048ff273f7fcc4a7b6c09
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1
+        with:
+          python-version: ${{ matrix.python }}
+      - name: Validate catalog
+        run: python -X utf8 scripts/validate_catalog.py
+      - name: Validate reusable components
+        run: python -X utf8 scripts/validate_components.py
+      - name: Run behavioral tests
+        run: python -X utf8 -m unittest discover -s tests -v

.gitignore

@@ -0,0 +1,4 @@
+__pycache__/
+*.pyc
+.venv/
+.runtime-validation/

AGENTS.md

@@ -0,0 +1,23 @@
+# Maintaining this catalog
+
+Tracker: github — rafaelob/fleet-codex. Issues hold intent, acceptance and delivery evidence.
+
+This file guides work on the catalog itself. Installation snippets are the
+`AGENTS*.snippet.md` files under `arrangements/`; do not install this file as an
+orchestration policy.
+
+- `arrangements/` owns lead/subagent TOMLs and insertable instruction sections.
+- `skills/`, `plugins/` and `hooks/` contain independent, optional components.
+- `docs/` explains installation, tradeoffs and sanitized runtime evidence.
+- Run `python -X utf8 scripts/validate_catalog.py`,
+  `python -X utf8 scripts/validate_components.py` and
+  `python -X utf8 -m unittest discover -s tests -v` from this repository root.
+  These use Python 3.11+ and its standard library; no package manager is required.
+- Keep installable content, code, Issues and PRs in English; translated guides
+  may supplement English documentation. Preserve component licenses and notices.
+- Never include personal configuration, credentials or raw runtime sessions.
+  Keep experimental runtime fixtures in the ignored `.runtime-validation/` area
+  and remove owned temporary credentials and processes when testing ends.
+- Follow `CONTRIBUTING.md` for package contracts and evidence. Update
+  `docs/CHANGELOG.md` for a delivered change; static checks do not prove model,
+  plugin or hook integration.

CONTRIBUTING.md

@@ -0,0 +1,128 @@
+# Contributing
+
+An arrangement describes a useful way to divide work between one lead and its
+subagents. Explain the kinds of work it serves, the tradeoffs, and when a user
+should choose another arrangement. Do not claim cost savings or quality gains
+without identifying the measurements behind them.
+
+All source code, configuration, agent instructions, skills, issues and pull
+requests use English. Optional documentation translations may use another
+language; keep the English guide authoritative and link translations from it.
+
+## Ways to contribute
+
+- Share a new combination through the New arrangement issue form or a PR.
+- Correct instructions, configuration, compatibility evidence or bugs in an
+  existing arrangement through the Correction issue form or a focused PR.
+- Share or improve a standalone skill, plugin, hook, tests or installation guide, with evidence
+  proportional to the behavior changed.
+
+An issue is useful for discussing a substantial change, but not required before
+a small correction. Search existing issues and PRs before opening another.
+
+## Send a pull request
+
+1. Fork this repository on GitHub and clone your fork.
+2. Create a descriptive branch, such as `add-my-arrangement` or
+   `fix-lean-delivery-installation`.
+3. Make one coherent change. For corrections, show the current problem and the
+   resulting behavior; for a new arrangement, include the complete package below.
+4. Run the checks and relevant runtime validation. Review your complete diff for
+   private configuration, credentials and unrelated files.
+5. Commit and push the branch to your fork, then open a PR targeting this
+   repository's `main` branch. Fill in the provided PR template in English.
+6. Address review feedback in the same PR. Maintainers review compatibility,
+   licensing and evidence before merging.
+
+You do not need collaborator access to submit a PR from a public fork. The
+repository provides issue forms, a PR template and CI checks; no private
+coordination tooling or installation is required to contribute.
+
+## Package contract
+
+Create `arrangements/<unique-id>/` with:
+
+| File | Purpose |
+| --- | --- |
+| `arrangement.toml` | Package identity, version, author, license, target Codex version and relative component paths; report tested support separately |
+| `config.toml` | Lead model/effort, V2 settings and thread cap only |
+| `agents/*.toml` | One complete configuration per specialist |
+| `AGENTS.snippet.md` | Standalone orchestration instructions for user or project scope |
+| `README.md` | Use cases, model/role mapping, installation link, limitations and evidence |
+
+An optional with-skill snippet must invoke the packaged skills by their exact names
+and describe when to use them. Declare optional_skills as a nonempty list of
+relative directories; each must resolve inside this repository and contain SKILL.md.
+The with-skill snippet is valid only with that nonempty list; omit both when no
+skill variant is provided. Components have no download-on-use dependencies or
+personal paths.
+The required thread cap is features.multi_agent_v2.max_concurrent_threads_per_session;
+the optional root agents table may contain only default subagent model and
+reasoning-effort values.
+An optional hook is a contained relative directory with a README.md documenting
+installation, supported runtime and entrypoint; its implementation may use any
+supported language and does not require a guard.py file.
+
+Use the current manifests as examples of schema version 1. The validator is the
+executable contract. The five core role keys are `name`, `description`, `model`,
+`model_reasoning_effort` and `developer_instructions`; optional `nickname_candidates`
+is English display metadata only. When present it is a nonempty list of strings:
+each candidate is trimmed, nonblank, unique after trimming, and limited to ASCII
+letters, digits, spaces, hyphens and underscores. Filename and role name must
+match. Put the role's behavior in its instructions, without requiring another
+skill, plugin, MCP server, personal configuration or private service.
+
+Keep credentials, provider connections, permissions, hooks and skills out of role
+TOMLs. If a workflow needs an optional public capability, document it separately
+with installation, license, required access and what happens when it is absent.
+Do not include any credential, local session, transcript, database, login cache,
+private project identifier or personal absolute path.
+
+## Verify before opening a PR
+
+For independent components, use `skills/<skill-name>/`, `plugins/<plugin-name>/`
+or `hooks/<hook-name>/`, not an arrangement's version directory. A component may
+serve any arrangement and must have its own purpose, license/provenance,
+installation/removal instructions and evidence. A plugin may bundle skills,
+public MCP configuration and hooks; follow the [plugin contribution contract](plugins/README.md).
+Do not add a mandatory MCP connection or skill dependency to an agent role.
+The [skill guide](skills/README.md) explains invocation and optional instruction
+sections. A focused component PR need not add or modify an arrangement.
+
+Run with Python 3.11 or newer; no package installation is necessary:
+
+```text
+python -X utf8 scripts/validate_catalog.py
+python -X utf8 scripts/validate_components.py
+python -X utf8 -m unittest discover -s tests -v
+```
+
+Also install the arrangement into a clean user or project scope and demonstrate
+one real delegation: selected role, resolved model/effort, returned artifact and
+parent verification. State the exact CLI version, platform, date, failures and
+unmeasured claims. Do not publish authentication material or raw transcripts.
+An unavailable required check remains a blocker, not a pass.
+
+For a component-only change, exercise that component's real entry point instead
+of unrelated model configurations. Plugin structural preflight is not full
+upstream-schema validation or installation proof: validate the selected manifest
+dialect and demonstrate the bundled capabilities in the named runtime. Report
+zero contributed plugins as zero, not as a passing plugin integration test.
+
+For hooks, show that an allowed call proceeds and a denied call cannot execute
+through the supported runtime path. A script test alone is insufficient. Explain
+which tools/events are covered and which guarantees remain instructions only.
+
+CI validates packages and executable behavior without model credentials. External
+contributors' code runs with read-only repository permissions and no secrets.
+
+## Review and updates
+
+Use a PR for new arrangements and changes to published ones. Bump the arrangement
+version when its behavior changes, update its evidence, and add a changelog entry.
+Preserve contributor attribution and licenses, including notices on derived
+skills. A copied instruction is still a licensed work.
+
+Keep executable tests focused on behavior: malformed configuration, broken paths,
+escaping references, and hook decisions. Documentation consistency belongs in
+the package validator and review, not snapshot tests of prose.