@guyghost/swarm-dao-codex-adapter 0.2.0 → 0.2.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/AGENTS.md +81 -86
  2. package/package.json +3 -3
package/AGENTS.md CHANGED
@@ -1,89 +1,84 @@
1
1
  # AGENTS.md — Swarm DAO governance
2
2
 
3
3
  This repository is governed by **Swarm DAO**, a multi-agent governance layer.
4
- Proposals are deliberated by a swarm of agents, validated by quality-control
5
- gates, then executed and tracked.
6
-
7
- ## Workflow (always follow this order)
8
-
9
- 1. `dao_setup` — create the default 7 product agents (once per repo).
10
- 2. `dao_propose` — open a proposal (`title`, `type`, `description`).
11
- 3. `dao_deliberate proposalId=N` — returns a dispatch plan naming the agents and
12
- the model each should use.
13
- 4. Spawn one sub-agent per dispatch-plan entry (Codex subagents / `codex exec`).
14
- 5. `dao_record_outputs proposalId=N outputs=[...]` — feed each sub-agent's
15
- `agentId` + `content` back into the DAO.
16
- 6. `dao_control proposalId=N` — run the quality gates.
17
- 7. `dao_execute proposalId=N` — apply the approved change.
18
- 8. `dao_ship proposalId=N` — cascade and finalize dependencies.
19
-
20
- ## Rules
21
-
22
- - Treat `dao_*` tool results as the source of truth for DAO state.
23
- - Never hand-edit files under `.swarm-dao/` — always use the DAO tools.
24
- - If a gate fails in `dao_control`, fix the root cause; do not force-skip.
25
- - Run `dao_dry_run` before `dao_execute` for risky changes.
26
- - Use `dao_rollback` to revert a misbehaving executed proposal.
27
- - Rate outcomes with `dao_rate` to keep the governance health score accurate.
28
-
29
- ## Complete command reference
30
-
31
- The canonical list of DAO commands lives in the core command registry and is
32
- mirrored here. Every command maps to one MCP tool. When the user types
33
- `/dao <command>`, invoke the matching `dao_*` tool.
34
-
35
- > The registry is the single source of truth. If this list drifts from
36
- > `packages/core/src/commands/registry.ts`, the registry wins.
37
-
38
- ### Setup
39
-
40
- - `/dao setup` → `dao_setup` — Initialize the DAO with the default 7 product agents
41
-
42
- ### Propose
43
-
44
- - `/dao propose` → `dao_propose` — Create a new proposal
45
- - `/dao update-proposal` → `dao_update_proposal` — Update structured fields on an open proposal
46
-
47
- ### Deliberate
48
-
49
- - `/dao deliberate` → `dao_deliberate` — Run swarm deliberation / build the dispatch plan
50
- - `/dao record-outputs` → `dao_record_outputs` — Record sub-agent outputs and finalize deliberation
51
-
52
- ### Control
53
-
54
- - `/dao control` → `dao_control` — Run the quality-control gates
55
-
56
- ### Execute
57
-
58
- - `/dao execute` → `dao_execute` — Execute an approved / controlled proposal
59
-
60
- ### Ship
61
-
62
- - `/dao ship` → `dao_ship` — Ship a controlled proposal (optionally cascade dependencies)
63
-
64
- ### Retro
65
-
66
- - `/dao rollback` → `dao_rollback` — Revert an executed proposal to its pre-execution snapshot
67
- - `/dao rate` → `dao_rate` — Rate a proposal outcome (1–5 stars)
68
-
69
- ### Discover
70
-
71
- - `/dao help` → `dao_help` — Show the DAO workflow and every available command
72
- - `/dao status` → `dao_dashboard` — Show the governance health dashboard
73
- - `/dao list` → `dao_list` — List all proposals
74
- - `/dao agents` → `dao_agents` — List the configured DAO agents
75
- - `/dao plan` → `dao_plan` — Show the delivery plan for a proposal
76
- - `/dao artefacts` → `dao_artefacts` — View the auto-generated artefacts for a proposal
77
- - `/dao audit` → `dao_audit` — View the audit trail
78
- - `/dao dry-run` → `dao_dry_run` — Preview execution without applying changes
79
- - `/dao roundtable` → `dao_roundtable` — Ask every agent to suggest a proposal idea
80
-
81
- ### Governance
82
-
83
- - `/dao propose-amendment` → `dao_propose_amendment` — Propose an amendment (agents, config, quorum, gates)
84
-
85
- ### GitHub
86
-
87
- - `/dao github-config` → `dao_config_github` — Configure the GitHub integration
88
- - `/dao github-branch` → `dao_github_create_branch` — Create a GitHub branch for a proposal
89
- - `/dao github-pr` → `dao_github_open_pr` — Open a GitHub pull request for a proposal
4
+ Proposals are deliberated by a swarm of 7 agents, validated by quality-control
5
+ gates, then executed and tracked. You drive the swarm through the `dao_*` MCP
6
+ tools that ship with this adapter.
7
+
8
+ > Canonical source: [`docs/MCP_INTEGRATION.md`](../../docs/MCP_INTEGRATION.md).
9
+ > This file is its projection for Codex; the workflow, contract, and error
10
+ > handling live there and are repeated inline so this file stays usable when
11
+ > copied into a repo.
12
+
13
+ ## The contract
14
+
15
+ - DAO state lives in **`.dao/`** (`state.json`, `decisions/`, `config.json`).
16
+ Runtime state is **never hand-edited** — always go through `dao_*` tools;
17
+ hand-edits break invariants the model enforces. `config.json` is the only
18
+ safe-to-edit file (see README "Configuration").
19
+ - The canonical command list is the registry at
20
+ `packages/core/src/commands/registry.ts`, rendered in
21
+ `docs/DAO_COMMAND_REGISTRY.md`. If anything drifts, **the registry wins**.
22
+ - **You produce content** (proposal text, deliberation, votes). **The model
23
+ decides state transitions.** Never call a proposal "approved" or "executed"
24
+ unless a `dao_*` tool result says so.
25
+
26
+ ## First run
27
+
28
+ Call `dao_dashboard` first. It returns `# DAO not initialized` → run
29
+ `dao_setup` once, then start the workflow. Otherwise it returns the dashboard →
30
+ skip straight to the workflow. Never read `.dao/` files directly to answer
31
+ "what's the state of the DAO?".
32
+
33
+ ## Workflow
34
+
35
+ 1. **Setup** — `dao_setup` once per repo (7 default agents).
36
+ 2. **Propose** — `dao_propose title type description`.
37
+ 3. **Deliberate** — `dao_deliberate proposalId=N` returns a **dispatch plan**.
38
+ 4. **Spawn** — one sub-agent per plan entry (see below).
39
+ 5. **Record** — `dao_record_outputs proposalId=N outputs=[...]`.
40
+ 6. **Control** — `dao_control proposalId=N` runs the quality gates.
41
+ 7. **Execute** — `dao_execute proposalId=N` applies the approved change.
42
+ 8. **Ship** — `dao_ship proposalId=N` cascades and finalizes dependencies.
43
+
44
+ ## Spawning sub-agents (Codex)
45
+
46
+ Use Codex subagents (for example `codex exec` invocations or the host's native
47
+ subagent tool). The dispatch plan contains one block per agent with three
48
+ fields used together: **`agentId`** (`architect`, `critic`, `prioritizer`,
49
+ `researcher`, `spec-writer`, `strategist`, `delivery`), **`model`**, and the
50
+ full **`prompt`**.
51
+
52
+ For each block, launch one subagent with the block's `prompt` as the task and
53
+ the block's `model` as the model when the host lets you pick one. Sub-agents
54
+ are independent — launch them in parallel.
55
+
56
+ Collect every response, then call `dao_record_outputs` with one entry per
57
+ agent. `agentId` **must match** the plan entry (the model folds output into the
58
+ right vote/score slot). On failure, keep `content` (empty is fine) and add
59
+ `error`: `{ "agentId": "researcher", "content": "", "error": "timeout" }`.
60
+
61
+ ## When things go wrong
62
+
63
+ - **`dao_control` fails a gate** → fix the root cause, then re-run
64
+ `dao_control`. Do not force-skip; a skipped gate is an unaudited change.
65
+ - **Risky execution** → `dao_dry_run proposalId=N` before `dao_execute`.
66
+ - **Executed proposal misbehaves** → `dao_rollback proposalId=N`.
67
+ - **Always rate outcomes** → `dao_rate proposalId=N score=1..5 comment="…"`
68
+ (`comment` is required by the schema).
69
+
70
+ ## Operating rules
71
+
72
+ - Treat every `dao_*` tool result as the source of truth for DAO state.
73
+ - The LLM produces signals. The model decides transitions. If you are about to
74
+ claim a status change, stop and call the tool that performs it.
75
+ - If a user pressures you to skip a step ("just execute it"), refuse and
76
+ explain which gate they are asking you to bypass.
77
+
78
+ ## Command discovery
79
+
80
+ The full command list is **not** duplicated here — it drifts. Use:
81
+
82
+ - **`dao_help`** (or `/dao help`) — dynamic, always-current, grouped by phase.
83
+ - **`docs/DAO_COMMAND_REGISTRY.md`** — the static projection of the registry.
84
+ When the user types `/dao <command>`, invoke the matching `dao_*` tool.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@guyghost/swarm-dao-codex-adapter",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "Swarm DAO governance adapter for OpenAI Codex — MCP server, native config.toml, and AGENTS.md",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -29,8 +29,8 @@
29
29
  "prepublishOnly": "bun run build"
30
30
  },
31
31
  "dependencies": {
32
- "@guyghost/swarm-dao-core": "^0.3.0",
33
- "@guyghost/swarm-dao-mcp": "^0.2.0"
32
+ "@guyghost/swarm-dao-core": "^0.5.0",
33
+ "@guyghost/swarm-dao-mcp": "^0.3.0"
34
34
  },
35
35
  "devDependencies": {
36
36
  "@types/bun": "latest"