Skip to content

Simplify README message and onboarding #23

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pate0304 merged 1 commit into from
Aug 4, 2026
Merged

Simplify README message and onboarding #23

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
207 changes: 85 additions & 122 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,18 +3,18 @@
</p>

<p align="center">
<strong>Build the right Codex agent team for this repository and goal.</strong>
<strong>Turn your project and goal into the smallest useful Codex agent team.</strong>
</p>

<p align="center">
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.
</p>

<p align="center">
<a href="#quick-start">Quick start</a> ·
<a href="#how-it-works">How it works</a> ·
<a href="docs/CONFIG_SAFETY.md">Safety</a> ·
<a href="#safety-and-control">Safety</a> ·
<a href="#documentation">Documentation</a>
</p>

Expand All @@ -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/<role>.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).
2 changes: 1 addition & 1 deletion artifacts/CHECKSUMS.sha256
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down