Framework delivery

Commission

Posed by the operator on 2026-09-23. Decide how Commonplace delivers what agents read — the framework library, global types, review gates, and skills — to installed projects. Today commonplace-init copies all of it into every project, which confuses users and drifts from the installed code (see design.md). On 2026-09-24, at the operator's direction, the proposal library-served-from-the-installed-package was moved into this workshop as design.md and removed from kb/reference/proposals/, so the design is kept in one place while it changes.

Operator direction and constraints

  • Copy GBrain by default (2026-09-23). GBrain is Commonplace's dominant competitor. Depart from a GBrain method only for a Commonplace-specific reason, and record the reason.
  • One tree, one channel (2026-09-24). The uv-installed package is the only tree that commands, agents, and harnesses read. There is no separate plugin tree, and projects get no copy of framework content. uv is the only release channel. This departs from GBrain, whose CLI and plugins install through separate channels and can skew.
  • One install path on every platform (2026-09-24). If one platform needs something different, every platform does it that way; there are no platform-specific install paths. Symlinks are unreliable on Windows, so nothing is linked.
  • Init only, per project (2026-09-24). No per-machine setup command. commonplace-init writes everything a project needs.
  • Skill stubs (2026-09-24). Each project gets a stub per skill that redirects to the real skill in the installed package. It costs one extra read per skill use; every alternative was worse.
  • Generated routing file (2026-09-24). Agents find the library through a gitignored file that init writes with full paths, not through commands.
  • Sub-agents are emulated where missing (2026-09-24). Users should be able to start using Commonplace in a harness without sub-agents, even though skills that need workers are less useful there. The probing agent designs the emulation for its harness.
  • The source checkout keeps its skill symlinks and does not run init (2026-09-25).
  • Report and source types stay scaffolded into projects (2026-09-25); their schemas stop $ref-ing the global note schema.
  • Plan for harnesses without skills (2026-09-24). The routing file carries a skill index that emulates the skills mechanism; stubs stay for harnesses with native skills.
  • No hooks (2026-09-24). No harness hooks until hooks are standardised. At least one enterprise user runs their own harness.
  • Harness-neutral base (2026-09-24). The design rests on files and a project AGENTS.md, with Agent Skills as an optional layer above that base. The base must still let an agent find a library instruction that the user names in conversation, outside any skill.

Design

Decided and adopted on 2026-09-25 as ADR 086 (commit e6103225). ADR 086, INSTALL.md, and the code are now authoritative. design.md and alternatives.md are the pre-adoption records; do not update them. This workshop stays open for the follow-ups below.

Open questions

  • Missing initialization. In Codex's revision 4 run, an agent in a clone without init found a nearby source checkout and answered from it instead of reporting the missing library.md. The design now has the AGENTS.md template say to stop and ask for init; does that work in both harnesses?
  • Emulated skills. Does the skill index in library.md trigger the right skill reliably when no native skill exists (probe case 9)? In Codex, the agent sees the index only after reading library.md.
  • Skill metadata. Does any harness need skill metadata beyond name and description copied into the stub? The probe's skills had none.
  • The enterprise harness. It loads neither AGENTS.md nor CLAUDE.md. What does load standing instructions there, and who can set it? The probe request asks the agent to find out and propose where the pointer line goes. More generally: which of the design's harness assumptions (H1–H6 in design.md) hold there? The enterprise colleague cannot give detailed answers, so the probe request asks whether an agent in the harness can adapt the design to reach five outcomes, and reports whether each was reached and how large any workaround was, and how it works where company policy allows; the table maps an outcome not reached to the assumption that failed. If the harness is built on Codex's app-server, skills/extraRoots/set may let it discover the package's skills in place.
  • The router skill at scale. It worked with a small index. Does it still select the right instruction with an index the size of the real library?
  • Windows and macOS. Not tested systematically. One Windows observation so far: init crashed on a settings.local.json that PowerShell 5.1 had written with a byte-order mark; fixed in probe revision 5. Still unknown on Windows: the form of Claude Code's read rule for a Windows path. Do the full paths that init writes, and reads of files under share/, work on both?
  • Running sessions. A running Claude Code session picked up skills added after it started. An upgrade inside a running session was not tested.
  • Centrally managed settings. Init writes Claude Code's read rule into the project's .claude/settings.local.json. Does a centrally managed policy override it?

Next steps

  1. Release. Bump the version and publish to PyPI, the only channel; then install from PyPI on a clean machine, including macOS and Windows where possible, and run commonplace-init and commonplace-init --check in a new project.
  2. Probe follow-ups. Claude Code and Codex run the cases added since revision 4: 8 (the stop-on-missing-init rule), 9 (a skill reached through the index alone), and 10 (a sub-agent). Agents in other harnesses answer the same probe request: Gemini CLI, OpenCode, Cursor, Goose, GitHub Copilot, and enterprise harnesses; enterprise results may come back through the operator, anonymised. Findings that change the decision amend ADR 086.
  3. Sub-agent emulation. When an emulation is chosen from the probe results, update cp-skill-ingest to accept it. Its rule allows only a harness-provided sub-agent and forbids launching the harness CLI as a worker. The other skills that need workers (cp-skill-write-multistage, cp-skill-revise-autoreason, analyse-agentic-system) are checked for the same assumption in the same change.
  4. Coupled workshops. Done 2026-09-25: mailbox messages in kb/messages/ ask both workshops under Coupling to reassess the items that assumed a library copy and to reply. Close this item when both replies arrive or their workshops close.

Evaluation boundary

  • Harnesses: Claude Code and Codex, plus the base layer in any harness that meets its stated assumptions.
  • Operating systems: Linux, macOS, and Windows.
  • Places: the source checkout and an installed project.
  • Upgrade cases: an upgrade that changes a skill, one that changes only library files, and one that moves the install location.

Coupling

None open.

Closure

The design is recorded in ADR 086. Close when each follow-up above is done or deferred with a trigger and each open question is answered or deferred with a trigger. Then delete this directory and its entry in kb/work/README.md.

Files

Current:

  • design.md — the design as it stood at adoption (pre-adoption record; ADR 086 is authoritative)
  • alternatives.md — rejected options, why, and the evidence by probe revision (pre-adoption record)
  • probe-package/ — the shared probe (revision 6): a throwaway uv package, a test project, the protocol every harness runs, and a results template
  • probe-request.md — the open request to agents in any harness to run the probe, with a log of replies
  • results-claude-code-r4.md — Claude Code's run of revision 4
  • results-codex-r4.md — Codex's run of revision 4

Background research:

Evidence from earlier revisions, cited by alternatives.md:

Complete file listing (generated at build time)