From abd09b07415b0824ba98497b10b2419abb921af9 Mon Sep 17 00:00:00 2001 From: pate0304 Date: Sat, 1 Aug 2026 16:32:14 -0400 Subject: [PATCH] Improve agent-team README onboarding --- README.md | 204 +++++++++++++++++++++++-------------- artifacts/CHECKSUMS.sha256 | 2 +- 2 files changed, 129 insertions(+), 77 deletions(-) diff --git a/README.md b/README.md index 4943137..d622534 100644 --- a/README.md +++ b/README.md @@ -3,110 +3,156 @@

- Audit your repository. Assemble the smallest capable Codex team. Apply it safely. + Build the right Codex agent team for this repository and goal. +

+ +

+ Codesemble audits bounded project evidence, generates only the specialists + your work needs, and shows every project-local change before applying it.

Quick start · - Usage · - Compiler · - How it works · + How it works · Safety · - Voice approval · - Primitive library · - Comparison + Documentation

--- -## What is Codesemble? +## Why Codesemble? -Codesemble is an open-source, repository-aware team builder for Codex. +- **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. -It reads bounded project signals, asks what outcome you want, and compiles a -Project Capability Map, Work Packages, and the smallest capable set of -project-specific specialists. Every role explains why it exists before -Codesemble generates native project configuration. +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 configures Codex. It does not replace the Codex runtime. +## Quick start -## Who is it for? +### Install the v0.2 candidate -Codesemble is for people working in real repositories who want specialized help -without installing a generic army of agents. +```bash +codex plugin marketplace add VAMFI/codsemble --ref fc247152961c25e79b525a969806991f499a2bac +codex plugin add codsemble@codsemble +``` -- **Solo builders** who want the right 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. +The pinned commit is the merged, validated v0.2 candidate. Start a fresh Codex +session after installation so the plugin skills are discovered. -## How does it work? +### Build your team ```text -Typed evidence → Capability map → Work packages → Admitted team → Exact preview → Confirmed apply +$codsemble:initialize-team Build the recommended Codex team for this workspace. ``` -1. **Audit** — reads bounded, typed project signals offline. -2. **Compile** — derives capabilities and independently delegable Work Packages. -3. **Generate** — proposes Focused, Recommended, and Extended teams with coverage evidence. -4. **Preview** — shows every agent, sandbox, instruction, and configuration change. -5. **Apply** — writes only the fresh exact plan you confirm, with doctor and rollback support. - -[Read the complete workflow →](docs/USAGE.md) +Codesemble audits the workspace and presents Focused, Recommended, and Extended +options. It prepares a side-effect-free exact plan before writing any project +file. -## Why is it different? +### Use your agents -Most agent packs start with a fixed roster. Codesemble starts with your goal and -the typed evidence that can safely specialize it. +After you approve and apply the team, work normally in the primary Codex thread: -The bundled catalog is an extensible primitive library, not the set of teams -Codesemble can produce. Project roles are generated and admitted from Work -Packages. Installed roles and live concurrency stay separate, so a project may -install 12 specialists while allowing only 4 spawned workers at once. +```text +Review the checkout flow, fix the highest-risk issue, and validate the result. +``` -> **Evidence in. Native team out.** +Start another fresh Codex session after apply or configuration changes so the +generated project agents are discovered. -[Explore the primitive library →](docs/ROLE_CATALOG.md) +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. -[See the architecture →](docs/ARCHITECTURE.md) +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. -## Quick start +### Keep the team healthy -### Install - -```bash -codex plugin marketplace add VAMFI/codsemble --ref -codex plugin add codsemble@codsemble +```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. ``` -Start a fresh Codex session so the plugin and project agents are reloaded. +[Open the step-by-step guide →](docs/USAGE.md) + +> **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. -### Build your team +## How it works ```text -$initialize-team Build the recommended Codex team for this workspace. +Repository evidence + your goal → Work Packages → Project team → Preview → Apply ``` -Codesemble audits and prepares a side-effect-free plan first. It applies project -files only after showing the exact diff and receiving the plan's confirmation ID -or its strictly matched, voice-friendly spoken alias. +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. -### Keep it healthy +### Example output ```text -$update-team Re-audit this workspace and preview team changes. -$team-doctor Check this project's generated team and configuration. -$rollback-team Preview rollback of the latest Codesemble transaction. +Repository evidence + GitHub Actions + delivery goal + security requirement + +Recommended Codex team + Delivery specialist owns the delivery Work Package + Security specialist reviews the security boundary + Independent validator verifies the high-risk delivery path + +Spawned-worker ceiling: 4 ``` -[Open the step-by-step guide →](docs/USAGE.md) +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 + +Codesemble does not install a fixed team of 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. + +- **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. + +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. ## What can it create? ```text AGENTS.md bounded orchestration guidance .codex/agents/.toml native specialist definitions -.codex/config.toml optional project concurrency default +.codex/config.toml optional project worker ceiling .codex/codsemble/manifest.json ownership and selected-team record .codex/codsemble/transactions/ reversible transaction history ``` @@ -114,10 +160,8 @@ AGENTS.md bounded orchestration guidance Codesemble does not edit `~/.codex/config.toml`, mark a project trusted, collect credentials, broaden permissions, or publish anything for you. -[Understand configuration safety →](docs/CONFIG_SAFETY.md) - -[Read the privacy boundary →](docs/PRIVACY.md) - +[Understand configuration safety →](docs/CONFIG_SAFETY.md) · +[Read the privacy boundary →](docs/PRIVACY.md) · [Review the threat model →](docs/THREAT_MODEL.md) ## Documentation @@ -126,34 +170,42 @@ credentials, broaden permissions, or publish anything for you. | --- | --- | | Install, initialize, update, diagnose, or roll back | [Usage](docs/USAGE.md) | | Understand the compiler and native Codex outputs | [Architecture](docs/ARCHITECTURE.md) | -| Inspect the EvidenceRef, capability, Work Package, and admission contracts | [Project Capability Compiler](docs/PROJECT_CAPABILITY_COMPILER.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 behavior | [Configuration safety](docs/CONFIG_SAFETY.md) | -| Approve an apply-capable plan from a realtime voice session | [Voice-friendly approval](docs/VOICE_APPROVAL.md) | -| Understand reusable role primitives and dynamic generation | [Primitive library](docs/ROLE_CATALOG.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 the compiler with catalog-surface and single-primary baselines | [Bounded usefulness comparison](docs/USEFULNESS_COMPARISON.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) | ## Project status -Codesemble v0.2.0 is the Project Capability Compiler candidate. It is not merged, -released, or published by this branch. Structural and simulated checks never -prove that every Codex version, policy, model, or operating system will accept a -generated team; runtime claims remain tied to the exact tested payload and host. +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. -[See validation evidence →](docs/VALIDATION.md) +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. +[See validation evidence →](docs/VALIDATION.md) · [View the roadmap →](ROADMAP.md) ## Contributing -Contributions are welcome. 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 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). -Codesemble is an independent open-source project, licensed under +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 c4c03e4..5cfc299 100644 --- a/artifacts/CHECKSUMS.sha256 +++ b/artifacts/CHECKSUMS.sha256 @@ -54,7 +54,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 -74d6b9205727ddf252954cc41440a92dc231b91805e2537d4d8dd764db6ad1c0 README.md +ffc6a562725255b92d420ecf5b25421573dc386c97052a59ca240fa72334f327 README.md 0504448900848d23d063b412d816ad2f5c5e786b4e6e0cb8754803f8f588cc2d ROADMAP.md d2d0dd1a73d5d788475bc040d23b617f7d0ee324d8b40bd081a68b27eada18d2 scripts/build.mjs c6581520fed9f775f87ef1e054c46e786129f03d79b7ad31a441c59e4bdd343a scripts/checksums.mjs