mirror of
https://github.com/mvschwarz/openrig.git
synced 2026-11-07 05:56:21 -10:00
docs(contributing): point contributors' agents at what already exists (#829)
Wires the contributor path to maps that already exist. developing-openrig's "Find your way" now points at the full rig --help list, the known problems in docs/reference/help.md, ROADMAP.md and the shipped skills index. It gives the capability map's checkout path, and after "How we judge changes" says where to look. CONTRIBUTING asks contributors to search issues and Discussions and check ROADMAP.md before proposing a feature. The openrig-skills and openrig-architect skills now send "changing OpenRig itself" to developing-openrig instead of a skill that does not exist. All mirrored copies and their edge digests stay in step.
This commit is contained in:
Mike Schwarz authored and GitHub committed
1 parent
e64c3aa667
commit
fcef78aba5
9 files changed
+31
-19
No files matched your search
@@ -23,13 +23,17 @@ not by restarting the daemon you live in.
|
||||
|
||||
| You want to know | Read | How much to trust it |
|
||||
|---|---|---|
|
||||
| What OpenRig can already do, before you decide something is missing | `rig context get onboarding-width/public-what-you-can-do.md` | The capability map; check it before proposing a new command or calling a gap a defect |
|
||||
| What OpenRig can already do, before you decide something is missing | `rig context get onboarding-width/public-what-you-can-do.md`; in this checkout, `packages/daemon/context-packs-src/onboarding-width/public-what-you-can-do.md` (the installed copy can differ) | The capability map; check it before proposing a new command or calling a gap a defect |
|
||||
| Whether a `rig` command already exists | `rig --help`: the full command list, before you decide a command is missing | The running binary; read the whole list, not only the command you expected |
|
||||
| Whether a problem is already known | The "Known problems to compare against" section of [`docs/reference/help.md`](../../../docs/reference/help.md) | Lists known issues by symptom; check an issue's current status before relying on it |
|
||||
| Whether a feature is already planned | [`ROADMAP.md`](../../../ROADMAP.md) | Check it before proposing a feature |
|
||||
| How the packages fit, the request path, where to add a command, route, migration, adapter, skill, context pack or scenario | [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) | Checked against the commit it names; counts come with the command to refresh them |
|
||||
| Whether your change touches a high-risk area, what depends on it, what broke there before | [`docs/as-built/arteries.md`](../../../docs/as-built/arteries.md) | Incomplete by design: absence from it doesn't make a change safe |
|
||||
| What to run before you push, and what each layer can and can't prove | [`docs/as-built/test-layers.md`](../../../docs/as-built/test-layers.md) | Checked against the commit it names |
|
||||
| The exact behaviour of a `rig` command | `rig <command> --help` on the running binary, then `packages/cli/src/commands/` | The binary and the code win over any document |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Most modules predate 0.6; check each one's `last-verified-against-source` marker against `git log` before relying on it |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Each module names the commit it was last checked against in `last-verified-against-source`; compare that marker with `git log` before relying on it |
|
||||
| Rig spec, agent spec and other user-facing reference | [`docs/reference/`](../../../docs/reference/) | Ships to every user; if you find drift, fix it there |
|
||||
| Which shipped skill covers a task | [`skills/_canonical/core/openrig-skills/SKILL.md`](../../../skills/_canonical/core/openrig-skills/SKILL.md) | The index of the skills that ship with OpenRig |
|
||||
| How to open a good pull request, and what review looks like | [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) | Current |
|
||||
|
||||
If none of these answers your question, search the code before inventing an answer. A missing map is worth an issue.
|
||||
@@ -59,6 +63,8 @@ OpenRig is a coordination layer for a trusted environment: it should help agents
|
||||
- A change that removes friction, or makes state more truthful, is usually welcome.
|
||||
- OpenRig runs on agents working in context with tools. Before adding code for a behaviour, ask whether an agent with
|
||||
the right instructions and today's commands could do it. A skill or a page of guidance is often the better change.
|
||||
- Where to look: the capability map above, and the `agent-operated-workflows` skill, which ships in the
|
||||
`openrig-core` plugin (`packages/daemon/assets/plugins/openrig-core/skills/agent-operated-workflows/SKILL.md`).
|
||||
- A change that adds a refusal, a prompt or a required step needs the concrete case in CONTRIBUTING.md: who is
|
||||
harmed, how, and what it costs everyone else.
|
||||
- One concern per pull request. Keep the diff reviewable in one sitting.
|
||||
|
||||
@@ -23,13 +23,17 @@ not by restarting the daemon you live in.
|
||||
|
||||
| You want to know | Read | How much to trust it |
|
||||
|---|---|---|
|
||||
| What OpenRig can already do, before you decide something is missing | `rig context get onboarding-width/public-what-you-can-do.md` | The capability map; check it before proposing a new command or calling a gap a defect |
|
||||
| What OpenRig can already do, before you decide something is missing | `rig context get onboarding-width/public-what-you-can-do.md`; in this checkout, `packages/daemon/context-packs-src/onboarding-width/public-what-you-can-do.md` (the installed copy can differ) | The capability map; check it before proposing a new command or calling a gap a defect |
|
||||
| Whether a `rig` command already exists | `rig --help`: the full command list, before you decide a command is missing | The running binary; read the whole list, not only the command you expected |
|
||||
| Whether a problem is already known | The "Known problems to compare against" section of [`docs/reference/help.md`](../../../docs/reference/help.md) | Lists known issues by symptom; check an issue's current status before relying on it |
|
||||
| Whether a feature is already planned | [`ROADMAP.md`](../../../ROADMAP.md) | Check it before proposing a feature |
|
||||
| How the packages fit, the request path, where to add a command, route, migration, adapter, skill, context pack or scenario | [`ARCHITECTURE.md`](../../../ARCHITECTURE.md) | Checked against the commit it names; counts come with the command to refresh them |
|
||||
| Whether your change touches a high-risk area, what depends on it, what broke there before | [`docs/as-built/arteries.md`](../../../docs/as-built/arteries.md) | Incomplete by design: absence from it doesn't make a change safe |
|
||||
| What to run before you push, and what each layer can and can't prove | [`docs/as-built/test-layers.md`](../../../docs/as-built/test-layers.md) | Checked against the commit it names |
|
||||
| The exact behaviour of a `rig` command | `rig <command> --help` on the running binary, then `packages/cli/src/commands/` | The binary and the code win over any document |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Most modules predate 0.6; check each one's `last-verified-against-source` marker against `git log` before relying on it |
|
||||
| A subsystem in depth | [`docs/as-built/`](../../../docs/as-built/README.md) | Each module names the commit it was last checked against in `last-verified-against-source`; compare that marker with `git log` before relying on it |
|
||||
| Rig spec, agent spec and other user-facing reference | [`docs/reference/`](../../../docs/reference/) | Ships to every user; if you find drift, fix it there |
|
||||
| Which shipped skill covers a task | [`skills/_canonical/core/openrig-skills/SKILL.md`](../../../skills/_canonical/core/openrig-skills/SKILL.md) | The index of the skills that ship with OpenRig |
|
||||
| How to open a good pull request, and what review looks like | [`CONTRIBUTING.md`](../../../CONTRIBUTING.md) | Current |
|
||||
|
||||
If none of these answers your question, search the code before inventing an answer. A missing map is worth an issue.
|
||||
@@ -59,6 +63,8 @@ OpenRig is a coordination layer for a trusted environment: it should help agents
|
||||
- A change that removes friction, or makes state more truthful, is usually welcome.
|
||||
- OpenRig runs on agents working in context with tools. Before adding code for a behaviour, ask whether an agent with
|
||||
the right instructions and today's commands could do it. A skill or a page of guidance is often the better change.
|
||||
- Where to look: the capability map above, and the `agent-operated-workflows` skill, which ships in the
|
||||
`openrig-core` plugin (`packages/daemon/assets/plugins/openrig-core/skills/agent-operated-workflows/SKILL.md`).
|
||||
- A change that adds a refusal, a prompt or a required step needs the concrete case in CONTRIBUTING.md: who is
|
||||
harmed, how, and what it costs everyone else.
|
||||
- One concern per pull request. Keep the diff reviewable in one sitting.
|
||||
|
||||
+3
-3
@@ -11,9 +11,9 @@ change in with the least friction on both sides.
|
||||
OS, Node and tmux versions, which harnesses are involved (or none), and the relevant command and output.
|
||||
Reports are public: remove credentials, private prompts, personal details and private paths
|
||||
before posting. Share a small reproduction rather than a full transcript or instance dump.
|
||||
- **Features and behaviour changes:** open an issue or a Discussion in *Ideas* first. A short
|
||||
"what I am trying to do and what stops me" saves both of us a rewrite. Small, obvious fixes do
|
||||
not need an issue.
|
||||
- **Features and behaviour changes:** open an issue or a Discussion in *Ideas* first. Search issues
|
||||
and Discussions, and check ROADMAP.md, before proposing a feature. A short "what I am trying to do
|
||||
and what stops me" saves both of us a rewrite. Small, obvious fixes do not need an issue.
|
||||
- **Questions:** use [Discussions › Q&A](https://github.com/mvschwarz/openrig/discussions/categories/q-a),
|
||||
not an issue.
|
||||
|
||||
|
||||
@@ -72,7 +72,7 @@ These are auto-delivered to every rig; their name+description are already in you
|
||||
These ship in the OpenRig repo and reach a seat when its profile selects them. To use one, select it in your profile's `uses.skills`, or open it directly at `packages/daemon/specs/agents/shared/skills/core/<skill>/SKILL.md`.
|
||||
|
||||
- **openrig-software-factory** — a user wants continuing reviewed work: manual/team, queue-only orchestration or an explicit Workflow; add one or two seats to the running starter when useful, with context, ownership, concurrency, spend and permission limits. Load `rig context get skills/core/openrig-software-factory/SKILL.md`.
|
||||
- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `openrig-builder`).
|
||||
- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `developing-openrig`).
|
||||
- **openrig-cmux** — driving the `cmux` terminal provider.
|
||||
- **openrig-herdr** — opening/managing seat terminals via the default proof-gated provider.
|
||||
- **agent-startup-and-context-ingestion** — a seat is booting and ingesting its startup context.
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: openrig-architect
|
||||
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
|
||||
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use developing-openrig); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
|
||||
metadata:
|
||||
cli_surfaces_referenced:
|
||||
- agent validate
|
||||
@@ -17,7 +17,7 @@ metadata:
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- developing-openrig
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
|
||||
@@ -72,7 +72,7 @@ These are auto-delivered to every rig; their name+description are already in you
|
||||
These ship in the OpenRig repo and reach a seat when its profile selects them. To use one, select it in your profile's `uses.skills`, or open it directly at `packages/daemon/specs/agents/shared/skills/core/<skill>/SKILL.md`.
|
||||
|
||||
- **openrig-software-factory** — a user wants continuing reviewed work: manual/team, queue-only orchestration or an explicit Workflow; add one or two seats to the running starter when useful, with context, ownership, concurrency, spend and permission limits. Load `rig context get skills/core/openrig-software-factory/SKILL.md`.
|
||||
- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `openrig-builder`).
|
||||
- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `developing-openrig`).
|
||||
- **openrig-cmux** — driving the `cmux` terminal provider.
|
||||
- **openrig-herdr** — opening/managing seat terminals via the default proof-gated provider.
|
||||
- **agent-startup-and-context-ingestion** — a seat is booting and ingesting its startup context.
|
||||
|
||||
@@ -7,10 +7,10 @@
|
||||
"core/cross-host-rig-commands/SKILL.md": "844a578d0f51cf8f02f8bfd7ffb3bbd6a37d511f721266c0d758c49157c1447a",
|
||||
"core/human-in-the-loop/SKILL.md": "14cf0c4a0dc89179121465d4b8d81d40406427351adcdc34f875097d1e6e9ab2",
|
||||
"core/messaging-the-human/SKILL.md": "581372434f27b1994d516e144be1324c7c5981cacf64fef6f09d1a57017faa08",
|
||||
"core/openrig-architect/SKILL.md": "0c3f1b7ff5bf185c9da963905229e951ffe1fb6d45a3cc9247cb747fc1d9a59d",
|
||||
"core/openrig-architect/SKILL.md": "c95f5f2bf1132402ded14d85e5c31d48e9b1e847aaf6c5218ce51dad175bdb5d",
|
||||
"core/openrig-cmux/SKILL.md": "73a86eac45d68b16a38fc0a4438713c634d86061073dac96a4d9e656ea5d34dc",
|
||||
"core/openrig-herdr/SKILL.md": "37508a02f50bb69ee97c22c37ccf70aa8e37dc0784061eb2a5ad813571eebd1a",
|
||||
"core/openrig-skills/SKILL.md": "e5f47e24a4c3cb1afceb1a3a93647313e9c30830aff58faabb5fa57838d1206c",
|
||||
"core/openrig-skills/SKILL.md": "59601122bd3c4b8eb82cc6e31b710528c97a5fde3b09e01076f742fd6e39e73e",
|
||||
"core/openrig-software-factory/SKILL.md": "33930e72341661eaaa9d3c5ac945297926f430d643b6f279fcb7f693ac30b7f7",
|
||||
"core/openrig-software-factory/references/worked-example.md": "ff5485a0e84de43188cf791cc96258abe038d035d439997f21865e33a1916bc5",
|
||||
"core/openrig-upgrade/SKILL.md": "c3555c66abe0426e2990aec024849f644cf43320a65b8f1211e96d3b234f6e83",
|
||||
@@ -81,7 +81,7 @@
|
||||
"openrig-operating-model/templates/PLAYBOOK.md": "ff6f9dc8caab06dc7b9ae21977310ddefa23e925453bd54629ce0a669403bfb0",
|
||||
"openrig-operating-model/templates/SOP.md": "1eaf0daf4f9bbf0715e6a5aaf0f29f030af5fe8b8a10232488ee97c507afa6dc",
|
||||
"openrig-operating-model/templates/SPEC.md": "f126536daa59cea3f1cfb0898d83c7cdf99f6392f6f155ea64fe55187dd0f5f1",
|
||||
"openrig-skills/SKILL.md": "e5f47e24a4c3cb1afceb1a3a93647313e9c30830aff58faabb5fa57838d1206c",
|
||||
"openrig-skills/SKILL.md": "59601122bd3c4b8eb82cc6e31b710528c97a5fde3b09e01076f742fd6e39e73e",
|
||||
"openrig-user/SKILL.md": "b866b2f7fbff98089aeeac33868566b9c8a49f0de0a1d414a8cc73222085a6fd",
|
||||
"orienting-to-an-inherited-seat/CHANGELOG.md": "4d0970e75e5c15b00a48d6a7150376d646257777264fd1b9a191165a8d5a6e84",
|
||||
"orienting-to-an-inherited-seat/SKILL.md": "65300ce0e299cce0148a8bacd51b0475ac1b59cd77a51a9bb2db9d43bda6e208",
|
||||
@@ -104,10 +104,10 @@
|
||||
"core/cross-host-rig-commands/SKILL.md": "844a578d0f51cf8f02f8bfd7ffb3bbd6a37d511f721266c0d758c49157c1447a",
|
||||
"core/human-in-the-loop/SKILL.md": "14cf0c4a0dc89179121465d4b8d81d40406427351adcdc34f875097d1e6e9ab2",
|
||||
"core/messaging-the-human/SKILL.md": "581372434f27b1994d516e144be1324c7c5981cacf64fef6f09d1a57017faa08",
|
||||
"core/openrig-architect/SKILL.md": "0c3f1b7ff5bf185c9da963905229e951ffe1fb6d45a3cc9247cb747fc1d9a59d",
|
||||
"core/openrig-architect/SKILL.md": "c95f5f2bf1132402ded14d85e5c31d48e9b1e847aaf6c5218ce51dad175bdb5d",
|
||||
"core/openrig-cmux/SKILL.md": "73a86eac45d68b16a38fc0a4438713c634d86061073dac96a4d9e656ea5d34dc",
|
||||
"core/openrig-herdr/SKILL.md": "37508a02f50bb69ee97c22c37ccf70aa8e37dc0784061eb2a5ad813571eebd1a",
|
||||
"core/openrig-skills/SKILL.md": "e5f47e24a4c3cb1afceb1a3a93647313e9c30830aff58faabb5fa57838d1206c",
|
||||
"core/openrig-skills/SKILL.md": "59601122bd3c4b8eb82cc6e31b710528c97a5fde3b09e01076f742fd6e39e73e",
|
||||
"core/openrig-software-factory/SKILL.md": "33930e72341661eaaa9d3c5ac945297926f430d643b6f279fcb7f693ac30b7f7",
|
||||
"core/openrig-software-factory/references/worked-example.md": "ff5485a0e84de43188cf791cc96258abe038d035d439997f21865e33a1916bc5",
|
||||
"core/openrig-upgrade/SKILL.md": "c3555c66abe0426e2990aec024849f644cf43320a65b8f1211e96d3b234f6e83",
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
name: openrig-architect
|
||||
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use openrig-builder); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
|
||||
description: Use when designing multi-agent topologies that run ON OpenRig — authoring RigSpec and AgentSpec files for new rigs, creating agent startup content (guidance / skills / culture), or diagnosing why a launched rig's agents aren't behaving as intended. NOT for changing OpenRig itself (use developing-openrig); NOT for ordinary CLI operation of an existing rig (use openrig-user). Covers the full authoring lifecycle from user intent to validated, launchable rig.
|
||||
metadata:
|
||||
cli_surfaces_referenced:
|
||||
- agent validate
|
||||
@@ -17,7 +17,7 @@ metadata:
|
||||
sibling_skills:
|
||||
- openrig-user
|
||||
- openrig-operator
|
||||
- openrig-builder
|
||||
- developing-openrig
|
||||
- openrig-upgrade
|
||||
- forming-an-openrig-mental-model
|
||||
- ai-dev-workflows
|
||||
|
||||
@@ -72,7 +72,7 @@ These are auto-delivered to every rig; their name+description are already in you
|
||||
These ship in the OpenRig repo and reach a seat when its profile selects them. To use one, select it in your profile's `uses.skills`, or open it directly at `packages/daemon/specs/agents/shared/skills/core/<skill>/SKILL.md`.
|
||||
|
||||
- **openrig-software-factory** — a user wants continuing reviewed work: manual/team, queue-only orchestration or an explicit Workflow; add one or two seats to the running starter when useful, with context, ownership, concurrency, spend and permission limits. Load `rig context get skills/core/openrig-software-factory/SKILL.md`.
|
||||
- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `openrig-builder`).
|
||||
- **openrig-architect** — authoring a rig or topology (NOT for changing OpenRig itself — that's `developing-openrig`).
|
||||
- **openrig-cmux** — driving the `cmux` terminal provider.
|
||||
- **openrig-herdr** — opening/managing seat terminals via the default proof-gated provider.
|
||||
- **agent-startup-and-context-ingestion** — a seat is booting and ingesting its startup context.
|
||||
|
||||
Reference in new issue
Block a user