How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

propose-change - Prompt - OpenSmartRoute

Name: propose-change
Author: fabioc-aloha

Prompt file imported from fabioc-aloha/alex-cognitive-architecture (.github/prompts/propose-change.prompt.md). Copyright stays with the author.

/propose-change — Structured Change Proposal Loop

A lightweight governance ritual for changes that are too big for a single commit message but too small for a full ADR. Produces a plain-text proposal the user can read, annotate inline, and sign off on — then archives the artifact as a decision record.

This is the Loop in action: IDEATE (working notes) → PLAN (proposal) → BUILD (inline resolutions) → TEST (critical thinking / falsifiability) → RELEASE (approval stamp) → IMPROVE (archive + template reuse).

When to Use

Invoke this when the change touches any of:

A trifecta (skill + instruction + muscle) or multiple executors of the same contract
Shared core modules that other surfaces mirror (e.g. TS mirrors of CJS cores)
Upgrade, publish, sync, or release pipelines
Anything with a non-obvious rollback path

Do not invoke for single-file edits, typo fixes, or clearly-scoped bug repairs.

The Loop

1. Working notes (IDEATE)

Create UPGRADE-PROCEDURE-WORKING-NOTES.txt (or equivalent name for the change). Dump raw thinking: the problem, candidate designs, discarded alternatives, known unknowns. No structure required — this is scratch space.

2. Proposal (PLAN)

Create a sibling file: <CHANGE>-PROPOSED.txt. Use plain text, not markdown, so the user can annotate inline with A: lines without worrying about formatting.

Required sections:

Summary — one paragraph, what changes and why
Phase N sections — numbered, exhaustive steps of the mechanical work
Per-project / per-surface flow — operator mental model
Contract / invariants — what must remain true after the change
Critical thinking — apply critical-thinking.instructions.md:
- Alternative hypotheses considered and rejected
- Open questions (Qn, prefixed for inline answers)
- Residual risks (Rn) with mitigation candidates
- Falsifiability tests — how we'd know this design is wrong
Approval checklist — numbered [ ] items the user ticks to sign off
On approval — what the agent will do once signed off (rename working notes to .superseded.txt, propagate resolutions, etc.)

3. User annotation (BUILD)

User opens the proposal and adds A: lines inline under each Qn / Rn they want to resolve. Silence = "accepted as residual risk, revisit later."

4. Agent closeout (TEST + RELEASE)

When the user signals approval (even as terse as "all answered"):

Read §8 verbatim before editing — do not trust summary memory for resolutions (users answer inline with context that matters)
Propagate each A: answer to its proper home:
- Documentation advisories → SKILL.md Hard Rules
- Automated checks → preflight scripts
- New defaults → config or shared cores
Fix any drift the resolutions reveal (if A2 says "add a parity check", the check will almost always fail on its first run — that is the point)
Tick remaining [ ] boxes and stamp status: APPROVED <date>
Ask the user the final yes/no questions flagged in §9 (e.g. rename working notes file?)

5. Archive (IMPROVE)

Move approved proposals to master-wiki/decisions/change-proposals/ and rename the working notes to .superseded.txt. These become reference examples for future proposals.

Hard Rules

Plain text, not markdown. Users annotate inline; markdown rendering hides the annotations in preview.
Never summarize the user's answers — read them verbatim. Compaction and summaries drop nuance that the user explicitly typed.
The parity check you add will catch real drift. Expect it. Fix it in the same closeout.
Silence is acceptance, not consent to change behavior. If a risk has no A: line, accept it as residual and note it in the approval stamp.
One proposal, one approval. Do not stack multiple approvals in the same document — new change, new file.

Reference Examples

See master-wiki/decisions/change-proposals/ for worked examples:

brain-upgrade-v8.3/ — trifecta refactor with shared core + TS mirror + version-stamp migration (2026-04-23)

Worked Example: brain-upgrade v8.3.1 (DP5)

This refactor touched 3 executors (upgrade-brain.cjs, bootstrap.ts, brain-upgrade.cjs), a shared core module (brain-upgrade-core.cjs), and the brain-upgrade trifecta itself. It demonstrates the full propose-change loop in action.

Phase 1 — Working notes (WORKING-NOTES.txt): Raw thinking about the problem: three executors duplicated the same copy/backup/restore logic. Each had its own bugs. The shared core idea emerged, plus the realization that the trifecta must protect itself (old backups cannot overwrite the new skill).

Phase 2 — Proposal (PROPOSED.txt): Structured as: Summary → 5 numbered phases (extract core → wire executors → protect trifecta → fleet testing → documentation) → contract/invariants (BRAIN_SUBDIRS parity, exit codes, .backup.md convention) → critical thinking section with:

Q1: "Should bootstrap.ts duplicate or import the CJS core?" → A: duplicate with parity preflight check (cross-language import is fragile)
Q2: "What if upgrade fails mid-copy?" → A: atomic swap via staging directory
R1: "TS mirror drifts silently from CJS" → Mitigated by release-preflight.cjs parity check that fails the build
Falsifiability: "If fleet tests pass but a real heir upgrade corrupts .github/, the staging-directory approach is wrong"
Approval checklist: 6 items covering each phase + test green + docs updated

Phase 3 — User annotation: User added A: lines under Q1 and Q2. Silence on R1 = accepted residual risk.

Phase 4 — Closeout: Agent propagated answers: Q1 answer → documented in SKILL.md Hard Rules; parity check added to release-preflight.cjs (which indeed caught drift on first run). Q2 answer → staging directory pattern added to brain-upgrade-core.cjs. Approval stamp: APPROVED 2026-04-23.

Phase 5 — Archive: Working notes renamed to .superseded.txt. Proposal stays as reference. Both live in master-wiki/decisions/change-proposals/brain-upgrade-v8.3/.

Key lessons captured in learned-patterns.instructions.md:

"Report → Validate → Approve loop for non-trivial refactors"
"Mechanical vs semantic split in trifectas — both need critical thinking"
"The parity checks you add during closeout will catch real drift — that is the point"

Template

Start new proposals from:

master-wiki/decisions/change-proposals/TEMPLATE.txt

Install propose-change and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

# /propose-change — Structured Change Proposal Loop A lightweight governance ritual for changes that are too big for a single commit message but too small for a full ADR. Produces a plain-text proposal the user can read, annotate inline, and sign off on — then archives the artifact as a decision record. This is **the Loop in action**: IDEATE (working notes) → PLAN (proposal) → BUILD (inline resolutions) → TEST (critical thinking / falsifiability) → RELEASE (approval stamp) → IMPROVE (archive + template reuse). ## When to Use Invoke this when the change touches any of: - A trifecta (skill + instruction + muscle) or multiple executors of the same contract - Shared core modules that other surfaces mirror (e.g. TS mirrors of CJS cores) - Upgrade, publish, sync, or release pipelines - Anything with a non-obvious rollback path Do **not** invoke for single-file edits, typo fixes, or clearly-scoped bug repairs. ## The Loop ### 1. Working notes (IDEATE) Create `UPGRADE-PROCEDURE-WORKING-NOTES.txt` (or equivalent name for the change). Dump raw thinking: the problem, candidate designs, discarded alternatives, known unknowns. No structure required — this is scratch space. ### 2. Proposal (PLAN) Create a sibling file: `<CHANGE>-PROPOSED.txt`. Use plain text, not markdown, so the user can annotate inline with `A:` lines without worrying about formatting. Required sections: 1. **Summary** — one paragraph, what changes and why 2. **Phase N** sections — numbered, exhaustive steps of the mechanical work 3. **Per-project / per-surface flow** — operator mental model 4. **Contract / invariants** — what must remain true after the change 5. **Critical thinking** — apply `critical-thinking.instructions.md`: - Alternative hypotheses considered and rejected - Open questions (Qn, prefixed for inline answers) - Residual risks (Rn) with mitigation candidates - Falsifiability tests — how we'd know this design is wrong 6. **Approval checklist** — numbered `[ ]` items the user ticks to sign off 7. **On approval** — what the agent will do once signed off (rename working notes to `.superseded.txt`, propagate resolutions, etc.) ### 3. User annotation (BUILD) User opens the proposal and adds `A:` lines inline under each Qn / Rn they want to resolve. Silence = "accepted as residual risk, revisit later." ### 4. Agent closeout (TEST + RELEASE) When the user signals approval (even as terse as "all answered"): 1. **Read §8 verbatim** before editing — do not trust summary memory for resolutions (users answer inline with context that matters) 2. Propagate each A: answer to its proper home: - Documentation advisories → SKILL.md Hard Rules - Automated checks → preflight scripts - New defaults → config or shared cores 3. Fix any drift the resolutions reveal (if A2 says "add a parity check", the check will almost always fail on its first run — that is the point) 4. Tick remaining `[ ]` boxes and stamp status: `APPROVED <date>` 5. Ask the user the final yes/no questions flagged in §9 (e.g. rename working notes file?) ### 5. Archive (IMPROVE) Move approved proposals to `master-wiki/decisions/change-proposals/` and rename the working notes to `.superseded.txt`. These become reference examples for future proposals. ## Hard Rules 1. **Plain text, not markdown.** Users annotate inline; markdown rendering hides the annotations in preview. 2. **Never summarize the user's answers — read them verbatim.** Compaction and summaries drop nuance that the user explicitly typed. 3. **The parity check you add will catch real drift.** Expect it. Fix it in the same closeout. 4. **Silence is acceptance, not consent to change behavior.** If a risk has no `A:` line, accept it as residual and note it in the approval stamp. 5. **One proposal, one approval.** Do not stack multiple approvals in the same document — new change, new file. ## Reference Examples See `master-wiki/decisions/change-proposals/` for worked examples: - `brain-upgrade-v8.3/` — trifecta refactor with shared core + TS mirror + version-stamp migration (2026-04-23) ### Worked Example: brain-upgrade v8.3.1 (DP5) This refactor touched 3 executors (`upgrade-brain.cjs`, `bootstrap.ts`, `brain-upgrade.cjs`), a shared core module (`brain-upgrade-core.cjs`), and the brain-upgrade trifecta itself. It demonstrates the full propose-change loop in action. **Phase 1 — Working notes** (`WORKING-NOTES.txt`): Raw thinking about the problem: three executors duplicated the same copy/backup/restore logic. Each had its own bugs. The shared core idea emerged, plus the realization that the trifecta must protect itself (old backups cannot overwrite the new skill). **Phase 2 — Proposal** (`PROPOSED.txt`): Structured as: Summary → 5 numbered phases (extract core → wire executors → protect trifecta → fleet testing → documentation) → contract/invariants (BRAIN_SUBDIRS parity, exit codes, `.backup.md` convention) → critical thinking section with: - Q1: "Should bootstrap.ts duplicate or import the CJS core?" → A: duplicate with parity preflight check (cross-language import is fragile) - Q2: "What if upgrade fails mid-copy?" → A: atomic swap via staging directory - R1: "TS mirror drifts silently from CJS" → Mitigated by `release-preflight.cjs` parity check that fails the build - Falsifiability: "If fleet tests pass but a real heir upgrade corrupts `.github/`, the staging-directory approach is wrong" - Approval checklist: 6 items covering each phase + test green + docs updated **Phase 3 — User annotation**: User added `A:` lines under Q1 and Q2. Silence on R1 = accepted residual risk. **Phase 4 — Closeout**: Agent propagated answers: Q1 answer → documented in SKILL.md Hard Rules; parity check added to `release-preflight.cjs` (which indeed caught drift on first run). Q2 answer → staging directory pattern added to `brain-upgrade-core.cjs`. Approval stamp: `APPROVED 2026-04-23`. **Phase 5 — Archive**: Working notes renamed to `.superseded.txt`. Proposal stays as reference. Both live in `master-wiki/decisions/change-proposals/brain-upgrade-v8.3/`. **Key lessons captured in `learned-patterns.instructions.md`**: - "Report → Validate → Approve loop for non-trivial refactors" - "Mechanical vs semantic split in trifectas — both need critical thinking" - "The parity checks you add during closeout will catch real drift — that is the point" ## Template Start new proposals from: ```text master-wiki/decisions/change-proposals/TEMPLATE.txt ```

{ "prompt": "# /propose-change — Structured Change Proposal Loop\n\nA lightweight governance ritual for changes that are too big for a single commit message\nbut too small for a full ADR. Produces a plain-text proposal the user can read, annotate\ninline, and sign off on — then archives the artifact as a decision record.\n\nThis is **the Loop in action**: IDEATE (working notes) → PLAN (proposal) → BUILD (inline\nresolutions) → TEST (critical thinking / falsifiability) → RELEASE (approval stamp) →\nIMPROVE (archive + template reuse).\n\n## When to Use\n\nInvoke this when the change touches any of:\n\n- A trifecta (skill + instruction + muscle) or multiple executors of the same contract\n- Shared core modules that other surfaces mirror (e.g. TS mirrors of CJS cores)\n- Upgrade, publish, sync, or release pipelines\n- Anything with a non-obvious rollback path\n\nDo **not** invoke for single-file edits, typo fixes, or clearly-scoped bug repairs.\n\n## The Loop\n\n### 1. Working notes (IDEATE)\n\nCreate `UPGRADE-PROCEDURE-WORKING-NOTES.txt` (or equivalent name for the change).\nDump raw thinking: the problem, candidate designs, discarded alternatives, known\nunknowns. No structure required — this is scratch space.\n\n### 2. Proposal (PLAN)\n\nCreate a sibling file: `<CHANGE>-PROPOSED.txt`. Use plain text, not markdown, so\nthe user can annotate inline with `A:` lines without worrying about formatting.\n\nRequired sections:\n\n1. **Summary** — one paragraph, what changes and why\n2. **Phase N** sections — numbered, exhaustive steps of the mechanical work\n3. **Per-project / per-surface flow** — operator mental model\n4. **Contract / invariants** — what must remain true after the change\n5. **Critical thinking** — apply `critical-thinking.instructions.md`:\n - Alternative hypotheses considered and rejected\n - Open questions (Qn, prefixed for inline answers)\n - Residual risks (Rn) with mitigation candidates\n - Falsifiability tests — how we'd know this design is wrong\n6. **Approval checklist** — numbered `[ ]` items the user ticks to sign off\n7. **On approval** — what the agent will do once signed off (rename working\n notes to `.superseded.txt`, propagate resolutions, etc.)\n\n### 3. User annotation (BUILD)\n\nUser opens the proposal and adds `A:` lines inline under each Qn / Rn they want\nto resolve. Silence = \"accepted as residual risk, revisit later.\"\n\n### 4. Agent closeout (TEST + RELEASE)\n\nWhen the user signals approval (even as terse as \"all answered\"):\n\n1. **Read §8 verbatim** before editing — do not trust summary memory for\n resolutions (users answer inline with context that matters)\n2. Propagate each A: answer to its proper home:\n - Documentation advisories → SKILL.md Hard Rules\n - Automated checks → preflight scripts\n - New defaults → config or shared cores\n3. Fix any drift the resolutions reveal (if A2 says \"add a parity check\", the\n check will almost always fail on its first run — that is the point)\n4. Tick remaining `[ ]` boxes and stamp status: `APPROVED <date>`\n5. Ask the user the final yes/no questions flagged in §9 (e.g. rename working\n notes file?)\n\n### 5. Archive (IMPROVE)\n\nMove approved proposals to `master-wiki/decisions/change-proposals/` and rename\nthe working notes to `.superseded.txt`. These become reference examples for\nfuture proposals.\n\n## Hard Rules\n\n1. **Plain text, not markdown.** Users annotate inline; markdown rendering\n hides the annotations in preview.\n2. **Never summarize the user's answers — read them verbatim.** Compaction and\n summaries drop nuance that the user explicitly typed.\n3. **The parity check you add will catch real drift.** Expect it. Fix it in\n the same closeout.\n4. **Silence is acceptance, not consent to change behavior.** If a risk has no\n `A:` line, accept it as residual and note it in the approval stamp.\n5. **One proposal, one approval.** Do not stack multiple approvals in the same\n document — new change, new file.\n\n## Reference Examples\n\nSee `master-wiki/decisions/change-proposals/` for worked examples:\n\n- `brain-upgrade-v8.3/` — trifecta refactor with shared core + TS mirror +\n version-stamp migration (2026-04-23)\n\n### Worked Example: brain-upgrade v8.3.1 (DP5)\n\nThis refactor touched 3 executors (`upgrade-brain.cjs`, `bootstrap.ts`, `brain-upgrade.cjs`),\na shared core module (`brain-upgrade-core.cjs`), and the brain-upgrade trifecta itself.\nIt demonstrates the full propose-change loop in action.\n\n**Phase 1 — Working notes** (`WORKING-NOTES.txt`):\nRaw thinking about the problem: three executors duplicated the same copy/backup/restore\nlogic. Each had its own bugs. The shared core idea emerged, plus the realization that\nthe trifecta must protect itself (old backups cannot overwrite the new skill).\n\n**Phase 2 — Proposal** (`PROPOSED.txt`):\nStructured as: Summary → 5 numbered phases (extract core → wire executors → protect\ntrifecta → fleet testing → documentation) → contract/invariants (BRAIN_SUBDIRS parity,\nexit codes, `.backup.md` convention) → critical thinking section with:\n- Q1: \"Should bootstrap.ts duplicate or import the CJS core?\" → A: duplicate with\n parity preflight check (cross-language import is fragile)\n- Q2: \"What if upgrade fails mid-copy?\" → A: atomic swap via staging directory\n- R1: \"TS mirror drifts silently from CJS\" → Mitigated by `release-preflight.cjs`\n parity check that fails the build\n- Falsifiability: \"If fleet tests pass but a real heir upgrade corrupts `.github/`,\n the staging-directory approach is wrong\"\n- Approval checklist: 6 items covering each phase + test green + docs updated\n\n**Phase 3 — User annotation**:\nUser added `A:` lines under Q1 and Q2. Silence on R1 = accepted residual risk.\n\n**Phase 4 — Closeout**:\nAgent propagated answers: Q1 answer → documented in SKILL.md Hard Rules; parity\ncheck added to `release-preflight.cjs` (which indeed caught drift on first run).\nQ2 answer → staging directory pattern added to `brain-upgrade-core.cjs`.\nApproval stamp: `APPROVED 2026-04-23`.\n\n**Phase 5 — Archive**:\nWorking notes renamed to `.superseded.txt`. Proposal stays as reference. Both\nlive in `master-wiki/decisions/change-proposals/brain-upgrade-v8.3/`.\n\n**Key lessons captured in `learned-patterns.instructions.md`**:\n- \"Report → Validate → Approve loop for non-trivial refactors\"\n- \"Mechanical vs semantic split in trifectas — both need critical thinking\"\n- \"The parity checks you add during closeout will catch real drift — that is the point\"\n\n## Template\n\nStart new proposals from:\n\n```text\nmaster-wiki/decisions/change-proposals/TEMPLATE.txt\n```", "variables": [], "notes": "Report → Validate → Approve loop for non-trivial refactors and architecture changes Mode: agent.", "metadata": { "source": { "provider": "github-prompts", "repository": "https://github.com/fabioc-aloha/alex-cognitive-architecture", "path": ".github/prompts/propose-change.prompt.md", "ref": "3a339b9a3c789d56e04d55eaaf83143df3352d14", "url": "https://github.com/fabioc-aloha/alex-cognitive-architecture/blob/3a339b9a3c789d56e04d55eaaf83143df3352d14/.github/prompts/propose-change.prompt.md", "key": "fabioc-aloha/alex-cognitive-architecture/.github/prompts/propose-change.prompt.md" } } }

propose-change

About

/propose-change — Structured Change Proposal Loop

When to Use

The Loop

1. Working notes (IDEATE)

2. Proposal (PLAN)

3. User annotation (BUILD)

4. Agent closeout (TEST + RELEASE)

5. Archive (IMPROVE)

Hard Rules

Reference Examples

Worked Example: brain-upgrade v8.3.1 (DP5)

Template

Install propose-change and it becomes one more candidate the router can pick - when it fits.

What it costs to adopt - in engineering time.

One base URL

No vendor lock-in

Failover built in

Use it

Manifest

Reviews