Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .modonome/snapshot/badge.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"color":"blue","label":"snapshot","message":"962 files, 130644 tok","schemaVersion":1}
{"color":"blue","label":"snapshot","message":"965 files, 130765 tok","schemaVersion":1}
2 changes: 1 addition & 1 deletion .modonome/snapshot/map.json

Large diffs are not rendered by default.

106 changes: 54 additions & 52 deletions .modonome/snapshot/map.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,8 +2,8 @@

Modonome snapshot. Read this before reading the repo. Tier 0 (signature.json) is the fingerprint: if merkle_root matches your last read, nothing changed. Tier 1 (map.json / map.md) lists modules, public API signatures, import edges, and attention ranking. Cite anchors (F: for files, S: for symbols); each resolves to a path and line so you can act without re-reading the whole repo.

Merkle root: sha256:d3569529943648c8e37037d13887f6ced708ae311f82b89e1a3c54a8a9aca975
Files: 962 Bytes: 3545016 Map tokens: 130644/120000
Merkle root: sha256:742b825c1e2eb8fb210b461e938ea6d9545503edf41f9f7d1fa844b3e0006da4
Files: 965 Bytes: 3558492 Map tokens: 130765/120000

## Modules

Expand Down Expand Up @@ -197,6 +197,8 @@ Files: 962 Bytes: 3545016 Map tokens: 130644/120000
- docs/adr/ADR-041-gauntlet-replay.md [F:40887a152e]: ADR-041: The Gauntlet, a Host-Repo Gate-Integrity Replay
- docs/adr/ADR-042-agentproof-verified.md [F:27086b6de3]: ADR-042: AgentProof Verified and the Hardened Registry
- docs/adr/ADR-043-terraform-module.md [F:c7326495ec]: ADR-043: Terraform module for org-level provisioning
- docs/adr/ADR-044-agent-org-structure.md [F:ffcad313b6]: ADR-044: The agent org structure and its configurability
- docs/agent-org.md [F:c3b2fcfb69]: The Modonome agent org
- docs/audits/claims-audit-2026-06-25.md [F:8a7591db62]: Claims audit, 2026-06-25
- docs/audits/claims-audit-2026-07-01.md [F:6a3a98df8c]: Claims audit, 2026-07-01
- docs/autonomy-plan.md [F:3dcdfa18c0]: Autonomy plan: governed autonomy on free models
Expand Down Expand Up @@ -2626,54 +2628,54 @@ Files: 962 Bytes: 3545016 Map tokens: 130644/120000

## Attention (centrality + pagerank)

1. scripts/lib/messages.mjs centrality=63 pagerank=0.039708
2. design-system/src/lib/cx.ts centrality=32 pagerank=0.028394
3. scripts/lib/message-catalog/index.mjs centrality=58 pagerank=0.011997
4. design-system/src/components/Icon/Icon.tsx centrality=23 pagerank=0.018407
5. design-system/src/index.ts centrality=48 pagerank=0.000747
6. scripts/lib/yaml-lite.mjs centrality=21 pagerank=0.017467
7. scripts/lib/jsonschema.mjs centrality=12 pagerank=0.018386
8. scripts/agent/run-cycle.mjs centrality=22 pagerank=0.004205
9. apps/control-panel/src/state/types.ts centrality=13 pagerank=0.00722
10. scripts/validate-config.mjs centrality=15 pagerank=0.004803
11. design-system/src/components/HelpHint/HelpHint.tsx centrality=12 pagerank=0.006264
12. design-system/src/components/StatusPill/StatusPill.tsx centrality=12 pagerank=0.004465
13. scripts/lib/learnings.mjs centrality=11 pagerank=0.00482
14. scripts/lib/canonical-json.mjs centrality=10 pagerank=0.003788
15. scripts/agent/resolve-role.mjs centrality=10 pagerank=0.003344
16. scripts/lib/snapshot-core.mjs centrality=13 pagerank=0.001249
17. design-system/src/components/Button/Button.tsx centrality=9 pagerank=0.003601
18. scripts/lib/detect-attribution.mjs centrality=7 pagerank=0.0041
19. scripts/validate-work-item.mjs centrality=9 pagerank=0.002777
20. scripts/lib/config-validate.mjs centrality=7 pagerank=0.003555
21. design-system/src/components/IconButton/IconButton.tsx centrality=6 pagerank=0.004178
22. scripts/validate-knowledge-packet.mjs centrality=8 pagerank=0.002631
23. apps/control-panel/src/App.tsx centrality=10 pagerank=0.001064
24. design-system/src/components/WorkItemCard/WorkItemCard.tsx centrality=8 pagerank=0.002181
25. apps/control-panel/server/modonomeWriter.mjs centrality=8 pagerank=0.001899
26. design-system/src/tokens/tokens.ts centrality=6 pagerank=0.00261
27. scripts/lib/lang-adapters/index.mjs centrality=8 pagerank=0.001249
28. scripts/lib/graph.mjs centrality=5 pagerank=0.003031
29. scripts/lib/branch-name.mjs centrality=4 pagerank=0.003576
30. design-system/src/components/Tooltip/Tooltip.tsx centrality=3 pagerank=0.004055
31. scripts/agent/providers.mjs centrality=3 pagerank=0.004045
32. design-system/src/components/WorkItemDrawer/WorkItemDrawer.tsx centrality=7 pagerank=0.001392
33. scripts/snapshot.mjs centrality=8 pagerank=0.000747
34. scripts/lib/secret-patterns.mjs centrality=4 pagerank=0.003169
35. apps/control-panel/src/lib/confirm.tsx centrality=6 pagerank=0.001891
36. apps/control-panel/src/lib/messages.ts centrality=6 pagerank=0.00179
37. scripts/agent/render-prompt.mjs centrality=5 pagerank=0.002208
38. design-system/src/components/Card/Card.tsx centrality=5 pagerank=0.002181
39. design-system/src/lib/format.ts centrality=5 pagerank=0.00218
40. scripts/lib/commit-identity.mjs centrality=3 pagerank=0.003335
41. design-system/src/components/LeaseTable/LeaseTable.tsx centrality=6 pagerank=0.001392
42. scripts/lib/work-item-validate.mjs centrality=4 pagerank=0.00225
43. apps/control-panel/src/screens/SettingsScreen.tsx centrality=6 pagerank=0.000847
44. apps/control-panel/src/state/adapter.ts centrality=6 pagerank=0.000847
45. design-system/src/components/ActivationLadder/ActivationLadder.tsx centrality=5 pagerank=0.001392
46. design-system/src/components/CostPanel/CostPanel.tsx centrality=5 pagerank=0.001392
47. design-system/src/components/GatePanel/GatePanel.tsx centrality=5 pagerank=0.001392
48. design-system/src/components/ProtectedPathRow/ProtectedPathRow.tsx centrality=5 pagerank=0.001392
49. examples/demo-app/src/index.js centrality=6 pagerank=0.000747
50. scripts/build-policy-attestation.mjs centrality=6 pagerank=0.000747
1. scripts/lib/messages.mjs centrality=63 pagerank=0.03962
2. design-system/src/lib/cx.ts centrality=32 pagerank=0.02833
3. scripts/lib/message-catalog/index.mjs centrality=58 pagerank=0.01197
4. design-system/src/components/Icon/Icon.tsx centrality=23 pagerank=0.018366
5. design-system/src/index.ts centrality=48 pagerank=0.000745
6. scripts/lib/yaml-lite.mjs centrality=21 pagerank=0.017428
7. scripts/lib/jsonschema.mjs centrality=12 pagerank=0.018345
8. scripts/agent/run-cycle.mjs centrality=22 pagerank=0.004195
9. apps/control-panel/src/state/types.ts centrality=13 pagerank=0.007204
10. scripts/validate-config.mjs centrality=15 pagerank=0.004792
11. design-system/src/components/HelpHint/HelpHint.tsx centrality=12 pagerank=0.00625
12. design-system/src/components/StatusPill/StatusPill.tsx centrality=12 pagerank=0.004455
13. scripts/lib/learnings.mjs centrality=11 pagerank=0.004809
14. scripts/lib/canonical-json.mjs centrality=10 pagerank=0.00378
15. scripts/agent/resolve-role.mjs centrality=10 pagerank=0.003336
16. scripts/lib/snapshot-core.mjs centrality=13 pagerank=0.001246
17. design-system/src/components/Button/Button.tsx centrality=9 pagerank=0.003593
18. scripts/lib/detect-attribution.mjs centrality=7 pagerank=0.004091
19. scripts/validate-work-item.mjs centrality=9 pagerank=0.002771
20. scripts/lib/config-validate.mjs centrality=7 pagerank=0.003547
21. design-system/src/components/IconButton/IconButton.tsx centrality=6 pagerank=0.004169
22. scripts/validate-knowledge-packet.mjs centrality=8 pagerank=0.002625
23. apps/control-panel/src/App.tsx centrality=10 pagerank=0.001061
24. design-system/src/components/WorkItemCard/WorkItemCard.tsx centrality=8 pagerank=0.002176
25. apps/control-panel/server/modonomeWriter.mjs centrality=8 pagerank=0.001895
26. design-system/src/tokens/tokens.ts centrality=6 pagerank=0.002604
27. scripts/lib/lang-adapters/index.mjs centrality=8 pagerank=0.001246
28. scripts/lib/graph.mjs centrality=5 pagerank=0.003024
29. scripts/lib/branch-name.mjs centrality=4 pagerank=0.003568
30. design-system/src/components/Tooltip/Tooltip.tsx centrality=3 pagerank=0.004046
31. scripts/agent/providers.mjs centrality=3 pagerank=0.004036
32. design-system/src/components/WorkItemDrawer/WorkItemDrawer.tsx centrality=7 pagerank=0.001389
33. scripts/snapshot.mjs centrality=8 pagerank=0.000745
34. scripts/lib/secret-patterns.mjs centrality=4 pagerank=0.003161
35. apps/control-panel/src/lib/confirm.tsx centrality=6 pagerank=0.001887
36. apps/control-panel/src/lib/messages.ts centrality=6 pagerank=0.001786
37. scripts/agent/render-prompt.mjs centrality=5 pagerank=0.002203
38. design-system/src/components/Card/Card.tsx centrality=5 pagerank=0.002176
39. design-system/src/lib/format.ts centrality=5 pagerank=0.002175
40. scripts/lib/commit-identity.mjs centrality=3 pagerank=0.003328
41. design-system/src/components/LeaseTable/LeaseTable.tsx centrality=6 pagerank=0.001389
42. scripts/lib/work-item-validate.mjs centrality=4 pagerank=0.002245
43. apps/control-panel/src/screens/SettingsScreen.tsx centrality=6 pagerank=0.000845
44. apps/control-panel/src/state/adapter.ts centrality=6 pagerank=0.000845
45. design-system/src/components/ActivationLadder/ActivationLadder.tsx centrality=5 pagerank=0.001389
46. design-system/src/components/CostPanel/CostPanel.tsx centrality=5 pagerank=0.001389
47. design-system/src/components/GatePanel/GatePanel.tsx centrality=5 pagerank=0.001389
48. design-system/src/components/ProtectedPathRow/ProtectedPathRow.tsx centrality=5 pagerank=0.001389
49. examples/demo-app/src/index.js centrality=6 pagerank=0.000745
50. scripts/build-policy-attestation.mjs centrality=6 pagerank=0.000745

2 changes: 1 addition & 1 deletion .modonome/snapshot/signature.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"commands":{"build":"","lint":"","test":"npm test"},"entrypoints":["bin/modonome.mjs"],"generated_at":"2026-07-07T13:45:30.712Z","generated_for":"modonome","governance":{"armed":false,"autonomy_enabled":false,"dry_run":true},"instructions":["AGENTS.md","CODEX.md","CONTRIBUTING.md","README.md"],"language_mix":{"(none)":11,"css":50,"diff":15,"html":9,"js":19,"json":131,"jsonl":7,"md":122,"mjs":335,"patch":37,"png":5,"py":4,"sh":1,"svg":1,"tf":4,"toml":2,"ts":61,"tsx":98,"txt":8,"webmanifest":1,"webp":1,"woff2":9,"xml":1,"yaml":9,"yml":21},"merkle_root":"sha256:d3569529943648c8e37037d13887f6ced708ae311f82b89e1a3c54a8a9aca975","preamble":"Modonome snapshot. Read this before reading the repo. Tier 0 (signature.json) is the fingerprint: if merkle_root matches your last read, nothing changed. Tier 1 (map.json / map.md) lists modules, public API signatures, import edges, and attention ranking. Cite anchors (F: for files, S: for symbols); each resolves to a path and line so you can act without re-reading the whole repo.","protected_paths":[".github",".github/CODEOWNERS","package-lock.json"],"schema_version":1,"size":{"bytes":3545016,"files":962},"snapshot_version":20,"stack":{"name":"Node or TypeScript","pm":"npm"},"tier_hashes":{"map":"sha256:4fb4a1960babf7260433e94fc1010c7dcb6e5889a4f06435aa1c29dd3ce4f266","map_md":"sha256:77c6f289aafb293774eac2bc7be0974a05dbfa5cd8153f31dab3567f3358deeb"}}
{"commands":{"build":"","lint":"","test":"npm test"},"entrypoints":["bin/modonome.mjs"],"generated_at":"2026-07-07T14:12:49.749Z","generated_for":"modonome","governance":{"armed":false,"autonomy_enabled":false,"dry_run":true},"instructions":["AGENTS.md","CODEX.md","CONTRIBUTING.md","README.md"],"language_mix":{"(none)":11,"css":50,"diff":15,"html":9,"js":19,"json":132,"jsonl":7,"md":124,"mjs":335,"patch":37,"png":5,"py":4,"sh":1,"svg":1,"tf":4,"toml":2,"ts":61,"tsx":98,"txt":8,"webmanifest":1,"webp":1,"woff2":9,"xml":1,"yaml":9,"yml":21},"merkle_root":"sha256:742b825c1e2eb8fb210b461e938ea6d9545503edf41f9f7d1fa844b3e0006da4","preamble":"Modonome snapshot. Read this before reading the repo. Tier 0 (signature.json) is the fingerprint: if merkle_root matches your last read, nothing changed. Tier 1 (map.json / map.md) lists modules, public API signatures, import edges, and attention ranking. Cite anchors (F: for files, S: for symbols); each resolves to a path and line so you can act without re-reading the whole repo.","protected_paths":[".github",".github/CODEOWNERS","package-lock.json"],"schema_version":1,"size":{"bytes":3558492,"files":965},"snapshot_version":21,"stack":{"name":"Node or TypeScript","pm":"npm"},"tier_hashes":{"map":"sha256:f71ce3c40af63d0f354fdb894025b9c058cdb06e5e2d9741c6485384fbb53469","map_md":"sha256:ec6d4fc8afcba424225141b62b8872c0ea14262e8c4b7ffb944a9658107c9d38"}}
23 changes: 23 additions & 0 deletions .modonome/work-items/WI-045-agent-org-structure.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
{
"schema_version": 1,
"id": "WI-045-agent-org-structure",
"state": "queued",
"attempts": 0,
"max_attempts": 3,
"touches_protected_path": false,
"allowed_edit_set": [
"docs/adr/ADR-044-agent-org-structure.md",
"docs/agent-org.md",
"docs/README.md",
"ARCHITECTURE.md",
".modonome/snapshot/*",
".modonome/work-items/*"
],
"gates": [
"node scripts/check-md-governance.mjs",
"node scripts/check-style.mjs .",
"npm run verify"
],
"queued_at": "2026-07-07",
"type": "update-docs"
}
5 changes: 4 additions & 1 deletion ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -138,7 +138,10 @@ default until an owner arms it.
`.github/workflows/modonome-review.yml` so a change gets an independent review before merge
regardless of who produced it. `review-proposals.mjs` (ADR-040, WI-044) is the same checker
at Checkpoint 1: it vets a proposal before it becomes a work item, so `queue.mjs` can gate
the backlog the way the pull request gates `main`.
the backlog the way the pull request gates `main`. The crew itself (the roster, what each
agent is for, and how each is configured on a model, runner, schedule, and trigger) is
documented in [docs/agent-org.md](docs/agent-org.md), with the structure decision in
[docs/adr/ADR-044-agent-org-structure.md](docs/adr/ADR-044-agent-org-structure.md).
- The snapshot utility (`scripts/snapshot.mjs` plus `scripts/lib/snapshot-*.mjs` and
`scripts/lib/lang-adapters/`). A dependency-free pipeline (walk, Merkle hash, per-file
signature extraction, redaction, import graph with PageRank, tier assembly, deterministic
Expand Down
3 changes: 3 additions & 0 deletions docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,9 @@ governs where docs live.

## Autonomy

- [agent-org.md](agent-org.md): the agent org roster. Who is in the crew, what each agent is
for, and how each is configured on a model, runner, schedule, and trigger. Structure decision
in [adr/ADR-044-agent-org-structure.md](adr/ADR-044-agent-org-structure.md).
- [autonomy-plan.md](autonomy-plan.md): the session-independent plan for governed autonomy
on free models, paired with the WI-026 through WI-040 work-item queue.

Expand Down
90 changes: 90 additions & 0 deletions docs/adr/ADR-044-agent-org-structure.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,90 @@
# ADR-044: The agent org structure and its configurability

**Status:** Accepted
**Date:** 2026-07-07
**Milestone:** 5 (Market researcher and envisioner roles)
**Builds on:** ADR-006 (checker independence), ADR-038 (checker as an author-agnostic review service), ADR-039 (agent capability profiles), ADR-040 (end-to-end operating model), WI-032 (configurable trigger and schedule layer)

## Context

A recurring request is to give Modonome a "robust agent org," in the spirit of collections
like agency-agents: a roster of specialists, each able to run on a chosen model, runtime,
schedule, and trigger (a local model, a hosted Claude model, and so on). The risk in answering
that with a new subsystem is duplication. Modonome already has most of the machinery:

- The `roles` map in `.modonome/config.yaml` is a generic registry. Any key becomes an agent
with no core-code change (`resolveRole` in `scripts/agent/resolve-role.mjs`, WI-040).
- Each role already carries `runner`, `model`, a prioritized `models` list, `skills`, `tools`,
`provider`, and `transport` (ADR-039), resolved against a provider and cost registry
(`scripts/agent/providers.mjs`).
- The operating model is two governed checkpoints: research to backlog, and make to merge
(ADR-040). Every producer, whether the internal loop, a human with a coding agent, or a
scheduled run, converges on the same CI.

Two gaps remained. First, the per-role `schedule` and `trigger` fields were not consumed by
anything, so scheduling meant hand-editing a workflow. WI-032 closes that: `schedule` and an
object `trigger` are now wired, and `scripts/agent/triggers.mjs` derives an execution order from
`after-role` chains and emits `.github/workflows/modonome-schedule.yml`. Second, there was no
single document that states the org: the roster, what each agent is for, and how it is
configured. ADR-040 has the flow but not the roster. This ADR records the structure, and the
canonical roster lives in `docs/agent-org.md`.

## Decision

1. **The agent org is the `roles` registry, governed by two checkpoints.** There is no separate
agent framework. An agent is a config entry; a producer agent advances a proposal to the
backlog only past an independent check, and a diff to `main` only past an independent checker
plus common CI (ADR-040). This is what makes a larger crew safe: every producer passes the
same two checks regardless of which model or runtime produced it.

2. **Adopt the specialist-roster pattern as governed, config-only crew roles, not a flat
personality dump.** A specialist is a role in `.modonome/config.yaml` with its own capability
profile, not a free-standing prompt outside the governance boundary. This keeps the roster
inside the maker/checker/owner structure rather than beside it.

3. **Every agent is configurable on model, runtime, schedule, and trigger from config alone.**
The role fields (`schemas/config.schema.json`) are: `runner` (local or container), `model`
and a prioritized `models` fallback list, `skills` and `tools` (declarative tags), `provider`
and `transport`, `schedule` (`cron`, `timezone`), `trigger` (a string shorthand or an object
with `type`, `after`, `cron`), and `execution_target`. `trigger.after` chains a role after
others; ordering reuses `scripts/lib/graph.mjs` and fails closed on a cycle or a dangling name
before any model call.

4. **Keep the crew lean.** Today it is `maker`, `checker`, `researcher`, and `self-govern`. The
only planned additions are `envisioner` (scoped innovation proposals with a weekly priority
score) and `market-researcher` (an opt-in ecosystem scan, flag-gated by `market_scan_enabled`,
default off). Both are Milestone 5 roles and both are governed producers that feed Checkpoint
1, so they add no new trust surface. The bar for a new role is a distinct purpose that no
existing role covers.

5. **The roster is a single source of truth.** `docs/agent-org.md` (canonical key `agent-org`)
holds the roster table, the per-agent configuration reference, and the "how to add or change
an agent" steps. Other docs link to it rather than restating the roster.

## Consequences

- One legible picture: a reader or an operator can name every agent, see what fires it, and know
which model and runtime it uses, from one page backed by one config file.
- Configurability is real, not aspirational: `schedule` and `trigger` are consumed (WI-032), so a
scheduled crew role needs a config edit, not a hand-written workflow.
- More configurable agents mean more ways to misconfigure a crew. This is bounded by existing
guards: the distinct maker/checker model rule (ADR-006), fail-closed trigger ordering (WI-032),
and the control-panel coverage gate that requires every config lever to have an operator
surface (`scripts/check-control-panel-coverage.mjs`).

## Implementation status

Shipped:

- The generic role registry (WI-040) and agent capability profiles (ADR-039).
- The configurable trigger and schedule layer (WI-032): schema fields, `scripts/agent/triggers.mjs`,
`resolveRoleSequence` consumption, and the generated `.github/workflows/modonome-schedule.yml`.
- This ADR and the canonical roster in `docs/agent-org.md`.

Follow-up, each under its own gates and tracked against Milestone 5:

- The `envisioner` and `market-researcher` roles, with prompts and capability profiles.
- A config-to-runtime generator that emits the container-runner workflow and local schedules
from the same config, plus a freshness gate.
- Per-agent `schedule` and `trigger` editors in the control panel Agents tab, with a regenerate
action on the gated write path.
Loading
Loading