From 7b05d07af6c1d38a1f707dab9b43ae2e143a9d7b Mon Sep 17 00:00:00 2001 From: Jay Patel Date: Tue, 4 Aug 2026 08:56:24 -0400 Subject: [PATCH] Rebase README clarity update onto current main --- README.md | 207 +++++++++++++++---------------------- artifacts/CHECKSUMS.sha256 | 2 +- 2 files changed, 86 insertions(+), 123 deletions(-) diff --git a/README.md b/README.md index 086687d..709a3e3 100644 --- a/README.md +++ b/README.md @@ -3,18 +3,18 @@

- Build the right Codex agent team for this repository and goal. + Turn your project and goal into the smallest useful Codex agent team.

- Codesemble audits bounded project evidence, generates only the specialists - your work needs, and shows every project-local change before applying it. + Codesemble audits your project, proposes the specialists it needs, and gives + you an exact preview, human approval, and rollback.

Quick start · How it works · - Safety · + Safety · Documentation

@@ -26,190 +26,153 @@ ## Why Codesemble? -- **Project-specific** — agents are derived from your repository and intended outcome. -- **Small by design** — every proposed role must cover justified project work. -- **Native and reversible** — Codesemble configures Codex project files with exact preview, Doctor, and rollback support. +- **Understands the project** — recommendations come from repository evidence and your goal. +- **Builds only justified roles** — no fixed team, no role padding, no team to design by hand. +- **Keeps changes reviewable** — project-local setup is previewed before apply and can be rolled back. -Codesemble is an open-source, repository-aware team builder for native Codex -multi-agent orchestration. It configures Codex; it does not replace the Codex -runtime. +Codesemble is for builders and teams who want useful specialists without +maintaining a multi-agent framework. It configures native Codex project files; +it does not replace Codex. ## Quick start -### Install the v0.2 candidate +### 1. Install, then restart Codex ```bash codex plugin marketplace add VAMFI/codsemble --ref fc247152961c25e79b525a969806991f499a2bac codex plugin add codsemble@codsemble ``` -The pinned commit is the merged, validated v0.2 candidate. Start a fresh Codex -session after installation so the plugin skills are discovered. +Open a fresh Codex session so its four Codesemble skills are discovered. The +pinned commit is the merged, validated v0.2 candidate. -### Build your team +### 2. Audit, choose, and approve ```text -$codsemble:initialize-team Build the recommended Codex team for this workspace. +$codsemble:initialize-team Audit this workspace and help me choose the smallest useful team. ``` -Codesemble audits the workspace and presents Focused, Recommended, and Extended -options. It prepares a side-effect-free exact plan before writing any project -file. +Codesemble presents Focused, Recommended, and Extended options, then shows the +exact project files and configuration diff. Choose an apply-capable mode if you +want changes: a preview-only plan is read-only and cannot later be applied. -### Use your agents +Nothing is written until you approve the exact current plan with its +confirmation ID or complete six-word voice challenge. -After you approve and apply the team, work normally in the primary Codex thread: +### 3. Restart and give the team a goal + +After apply, open another fresh Codex session so the generated agents are +discovered. You continue working through the primary thread: ```text -Review the checkout flow, fix the highest-risk issue, and validate the result. +You → primary Codex thread → bounded specialists → primary integrates and reports ``` -Start another fresh Codex session after apply or configuration changes so the -generated project agents are discovered. - -The primary agent remains user-facing and accountable. Project-local -orchestration guidance delegates bounded, separable work to installed -specialists when useful, reconciles their evidence, and keeps final decisions -with the primary thread. - -Installed roles are available capabilities, not always-running processes. The -project worker ceiling limits simultaneous spawned workers, excludes the primary -thread, and is independent of installed role count. - -### Keep the team healthy - ```text -$codsemble:update-team Re-audit this workspace and preview team changes. -$codsemble:team-doctor Check this project's generated team and configuration. -$codsemble:rollback-team Preview rollback of the latest Codesemble transaction. +Use the installed specialists where useful to review the checkout flow, fix the +highest-risk issue, and validate the result. ``` -[Open the step-by-step guide →](docs/USAGE.md) +Specialists run only when the primary delegates separable work; they are not +always running. The primary remains accountable for decisions and final claims. -> **You stay in control.** Audit and preview are read-only. Codesemble writes -> project files only after you approve the exact current plan, refuses stale or -> changed plans, preserves transaction history, and previews rollback before -> restoring managed files. It does not change personal Codex settings or -> publish anything. +Maintain the team with +[`$codsemble:update-team`](docs/USAGE.md#update-a-team), +[`$codsemble:team-doctor`](docs/USAGE.md#diagnose), and +[`$codsemble:rollback-team`](docs/USAGE.md#roll-back). ## How it works ```text -Repository evidence + your goal → Work Packages → Project team → Preview → Apply +Project evidence + your goal → required work → project team → preview → apply ``` -1. **Audit** bounded, typed project signals locally. -2. **Compile** the capabilities and separable work the goal requires. -3. **Generate** evidence-backed Focused, Recommended, and Extended teams. -4. **Preview** every role, sandbox, instruction, and configuration change. -5. **Apply** only the exact fresh plan you confirm, with Doctor and rollback support. +1. **Audit** project signals locally. +2. **Compile** required work into evidence-backed team options. +3. **Preview and apply** only the exact fresh plan you confirm. -### Example output +For example: ```text -Repository evidence +Project evidence GitHub Actions + delivery goal + security requirement Recommended Codex team - Delivery specialist owns the delivery Work Package + Delivery specialist owns the delivery work Security specialist reviews the security boundary - Independent validator verifies the high-risk delivery path + Independent validator verifies the high-risk path Spawned-worker ceiling: 4 ``` -The names and number of agents change with the repository evidence and confirmed -goal. Codesemble explains the evidence and Work Package behind every generated -role before apply. - -[Read the compiler contract →](docs/PROJECT_CAPABILITY_COMPILER.md) · -[See the architecture →](docs/ARCHITECTURE.md) - -## Dynamic teams, not 111 installed agents +The names and number of agents change with the project and goal. Codesemble +explains why every role is present before apply. -Codesemble does not install a fixed team of 111 agents. +### Why 111 does not mean 111 agents -The current 111-entry catalog is a reusable primitive library—not a roster, -recommendation ceiling, team-size target, or concurrency limit. For each -workspace, the compiler derives Work Packages from bounded evidence and explicit -goals, then generates only justified project-specific roles. +The 111-entry catalog is a library of reusable capability primitives—not a team +size, recommendation ceiling, or concurrency limit. Codesemble generates only +the roles justified by the current project: **Focused** covers required work, +**Recommended** adds independent verification only for high-risk required work, +and **Extended** adds only closed-rule optional lifecycle work; it may equal +Recommended. -- **Focused** is the smallest complete team covering required Work Packages. -- **Recommended** adds independent verification only for evidenced high-risk work. -- **Extended** adds only closed-rule, evidence-backed optional lifecycle work and may equal Recommended. +Installed roles and concurrent workers are separate. A project can install 12 +useful specialists while allowing only 4 workers to run at once; the primary +thread is not counted in that worker ceiling. -Catalog size, installed roles, and active workers remain separate. A project may -install 12 useful specialists while allowing only 4 workers to run concurrently. - -[Explore the primitive library →](docs/ROLE_CATALOG.md) · -[See the bounded comparison →](docs/USEFULNESS_COMPARISON.md) - -## Who is it for? - -- **Solo builders** who want useful specialists without designing a team by hand. -- **Maintainers** who need reviewable, reversible project configuration. -- **Product teams** whose work spans engineering, testing, design, docs, growth, or operations. -- **Organizations** that want project-local defaults without silently changing personal Codex settings. +[Read the compiler contract →](docs/PROJECT_CAPABILITY_COMPILER.md) · +[Explore the primitive library →](docs/ROLE_CATALOG.md) -## What can it create? +## What it creates ```text AGENTS.md bounded orchestration guidance .codex/agents/.toml native specialist definitions .codex/config.toml optional project worker ceiling -.codex/codsemble/manifest.json ownership and selected-team record +.codex/codsemble/manifest.json selected team and ownership record .codex/codsemble/transactions/ reversible transaction history ``` -Codesemble does not edit `~/.codex/config.toml`, mark a project trusted, collect -credentials, broaden permissions, or publish anything for you. +## Safety and control -[Understand configuration safety →](docs/CONFIG_SAFETY.md) · -[Read the privacy boundary →](docs/PRIVACY.md) · -[Review the threat model →](docs/THREAT_MODEL.md) +Audit and preview are read-only. Apply refuses the plan if relevant evidence, +runtime capabilities, ownership lineage, or output preimages changed. Codesemble +does not edit personal Codex settings, mark projects trusted, collect +credentials, control Codex runtime permissions, broaden the active sandbox, or +publish anything. + +[Configuration safety →](docs/CONFIG_SAFETY.md) · +[Voice-friendly approval →](docs/VOICE_APPROVAL.md) · +[Privacy →](docs/PRIVACY.md) · +[Threat model →](docs/THREAT_MODEL.md) ## Documentation -| I want to… | Read… | -| --- | --- | -| Install, initialize, update, diagnose, or roll back | [Usage](docs/USAGE.md) | -| Understand the compiler and native Codex outputs | [Architecture](docs/ARCHITECTURE.md) | -| Inspect EvidenceRef, capability, Work Package, and admission contracts | [Project Capability Compiler](docs/PROJECT_CAPABILITY_COMPILER.md) | -| Migrate a v0.1 team safely | [v0.2 migration](docs/MIGRATION_V0_2.md) | -| Review concurrency, no-clobber apply, and recovery | [Configuration safety](docs/CONFIG_SAFETY.md) | -| Approve from a realtime voice session | [Voice-friendly approval](docs/VOICE_APPROVAL.md) | -| Understand reusable primitives and dynamic generation | [Primitive library](docs/ROLE_CATALOG.md) | -| Understand local data handling | [Privacy](docs/PRIVACY.md) | -| Review trust boundaries and abuse cases | [Threat model](docs/THREAT_MODEL.md) | -| See what has actually been tested | [Validation evidence](docs/VALIDATION.md) | -| Compare Codesemble with simpler baselines | [Bounded usefulness comparison](docs/USEFULNESS_COMPARISON.md) | -| Understand the project promise and release gate | [Definition of Done](docs/DEFINITION_OF_DONE.md) | -| Reuse the visual identity correctly | [Brand guide](docs/BRAND.md) | +- **Get started:** [Usage](docs/USAGE.md) and [v0.2 migration](docs/MIGRATION_V0_2.md) +- **Understand generation:** [Architecture](docs/ARCHITECTURE.md) and + [compiler contract](docs/PROJECT_CAPABILITY_COMPILER.md) +- **Review safety:** [Configuration safety](docs/CONFIG_SAFETY.md), + [privacy](docs/PRIVACY.md), and [threat model](docs/THREAT_MODEL.md) +- **Check the evidence:** [Validation](docs/VALIDATION.md) and [bounded comparison](docs/USEFULNESS_COMPARISON.md) +- **Explore the project:** [Roadmap](ROADMAP.md), + [Definition of Done](docs/DEFINITION_OF_DONE.md), and + [brand guide](docs/BRAND.md) ## Project status -Codesemble v0.2.0 is merged on `main` as the Project Capability Compiler -candidate. Its merge-head CI passed on Node 22 and 24 across Ubuntu, macOS, and -Windows, with CodeQL and dependency review also passing. It has not been tagged, -released, or marketplace-published; v0.1.0 remains the latest release. - -Runtime and physical-device claims remain tied to the exact tested payload and -boundary. Structural checks never prove that every Codex version, policy, model, -operating system, or voice device will accept a generated team. +Codesemble v0.2.0 is merged and validated on `main`. It is installable from the +pinned Git source above, but has not been tagged or released; v0.1.0 remains the +latest release. -[See validation evidence →](docs/VALIDATION.md) · -[View the roadmap →](ROADMAP.md) +Validation claims remain tied to the exact tested payload and environment. +[See the evidence →](docs/VALIDATION.md) ## Contributing -Try Codesemble in an isolated repository and report where its audit, proposed -roles, or explanations were incomplete. Contributors can add representative -fixtures, improve compiler policies, strengthen lifecycle tests, or refine the -documentation. - -Start with the [contribution guide](CONTRIBUTING.md), use [support guidance](SUPPORT.md) -for reproducible questions, and report vulnerabilities through the private -process in [SECURITY.md](SECURITY.md). +Try Codesemble in an isolated project and report where its audit, proposed roles, +or explanations were incomplete. See [Contributing](CONTRIBUTING.md), +[Support](SUPPORT.md), and [Security](SECURITY.md). Codesemble is an independent open-source project licensed under the [Apache License 2.0](LICENSE). diff --git a/artifacts/CHECKSUMS.sha256 b/artifacts/CHECKSUMS.sha256 index c9ccfe1..fb58f01 100644 --- a/artifacts/CHECKSUMS.sha256 +++ b/artifacts/CHECKSUMS.sha256 @@ -60,7 +60,7 @@ ec89a95f29bb67625a44663c08b0939cf522158cd094e31015b83c1a20c2062b plugins/codsem a6689d5a15007ba0942ca9ff9538be7a3fc8e1c4b0993191b928063161f57098 plugins/codsemble/skills/update-team/agents/openai.yaml d9297755666b1e88886564fc71bc060872d813c9fe043dd94954a210612491ba plugins/codsemble/skills/update-team/SKILL.md 152eb46211db24f9e4bdb3dd38a11ab0aa7ea6a19bc8a95c0b5d9521fc8ed289 PROJECT_GOAL.md -29c0ecda59afb32e5a2a3cad0ee0751a6dd8073a53d51f519faf52b12dca0a12 README.md +76371ac04ed555fd465ad55dc82738ee6a9290a35e3a47917b45048df12c9085 README.md 0504448900848d23d063b412d816ad2f5c5e786b4e6e0cb8754803f8f588cc2d ROADMAP.md d2d0dd1a73d5d788475bc040d23b617f7d0ee324d8b40bd081a68b27eada18d2 scripts/build.mjs c6581520fed9f775f87ef1e054c46e786129f03d79b7ad31a441c59e4bdd343a scripts/checksums.mjs