cherry-works 0.3.0 → 0.5.0

package/README.md

@@ -114,20 +114,22 @@ Each kind comes up at a different time:
 |---|---|
 | `guide` | a touched file matches one of its `globs`, or on every turn when it has no globs |
 | `sensor` | the `signal` it names is raised, and the harness runs its `run` command |
-| `skill` | one of its `triggers` matches the request, or it is called by name as `/skill-<id>` |
+| `skill` | one of its `triggers` matches the request, or it is called by name as `/<id>` |
 | `playbook` | one of its `triggers` matches; its body is a sequence of skills |
-| `agent` | it is spawned by identity, with only the `tools` it lists |
+| `agent` | it is spawned by its id, with only the `tools` it lists |
 | `posture` | always, wherever the host can be told what to `allow` and `deny` |
 | `corpus` | a primitive's `rationale` cites it, to give the reasoning behind a rule |
 | `mixin` | never on its own; its body is lent to the primitives that pull it in |
-| `mcp` | a primitive's body names it as `mcp:<id>`: a place outside the repository, reached through `cw mcp serve` |
+| `mcp` | a primitive's body names it as `[[<id>]]`: a place outside the repository, reached through `cw mcp serve` |
 
-`cw kinds <kind>` gives the exact fields each kind takes. An identity is
-`kind:id`, and it names exactly one primitive across the whole charter. If two
-files claim the same identity, the build is refused and both files are named.
+`cw kinds <kind>` gives the exact fields each kind takes. An id names exactly
+one primitive across the whole charter, whatever its kind. If two files claim
+the same id, the build is refused and both files are named. A primitive is
+named by its id alone: bare in a header (`rationale: type-safety`), a test or a
+command, and as `[[<id>]]` in a body, which the build turns into a link.
 Every primitive is a folder holding its `index.md`, and any other file in that
 folder is one of its assets, reached from the body as `./<file>`. An id is at
-most 40 characters, and may be grouped with `/`: `mcp:mfbs/billing` is kept at
+most 40 characters, and may be grouped with `/`: the mcp `mfbs/billing` is kept at
 `.cw/charter/mcp/mfbs/billing/index.md`.
 
 `cw build` compiles every primitive to `.cw/out/<kind>/<id>/index.md`, with its
@@ -145,15 +147,15 @@ agent reads it.
 | `cw list [--kind] [--min]` | List what the charter holds |
 | `cw kinds [kind]` | List the kinds, or the fields one of them requires |
 | `cw add <kind> <id> [--header k=v …]` | Write a new primitive |
-| `cw edit <identity>` | Open a primitive's file in your editor |
-| `cw remove <identity> [--yes]` | Delete a primitive this repository authored |
-| `cw explain <identity>` | Show which file declares an identity, what it pulls in and which tests name it |
+| `cw edit <id>` | Open a primitive's file in your editor |
+| `cw remove <id> [--yes]` | Delete a primitive this repository authored |
+| `cw explain <id>` | Show which file declares an id, what it pulls in and which tests name it |
 | `cw doctor` | Check the agents, the charter, the vendor sources and the compiled output |
 | `cw test` | Run every case in `.cw/test/` against the charter |
 | `cw suite add \| edit \| remove` | Manage test files |
 | `cw vendor add <source> [--ref] \| remove \| list` | Install, update, remove or list vendor sources |
 | `cw portal [--port]` | Open the charter in a browser on this machine |
-| `cw mcp auth [identity] [--status]` | Sign in, as yourself, to every place the charter reaches, or to one again |
+| `cw mcp auth [id] [--status]` | Sign in, as yourself, to every place the charter reaches, or to one again |
 | `cw mcp serve` | Serve every place the charter reaches to your agent, over stdio |
 
 `cw doctor` exits with a failure status when the charter has an error, when a
@@ -230,10 +232,22 @@ longer hold.
 cw vendor add git@github.com:your-org/charter-baseline.git --ref v1.2.0
 ```
 
-A vendor source is a git repository with primitives laid out in folders by kind.
-It is installed under `.cw/vendor/<name>/`, pinned to the ref you chose and
-committed. Vendored primitives are read-only. To differ from one, write your own
-primitive under a new identity.
+A vendor source is a git repository set up with `cw init`: author its charter
+there, test it, and push. Only its `.cw/charter/` folder is installed, under
+`.cw/vendor/<name>/`, pinned to the ref you chose and committed. A repository
+without that folder is refused, and so is one that has vendors of its own:
+vendoring is one level deep. Vendored primitives are read-only. To differ from
+one, write your own primitive under a new id.
+
+Run `cw vendor add` again with a new `--ref` to update a source, and
+`cw vendor remove <name>` to take it away. Run `cw build` after either.
+
+### Recommended charter vendors
+
+| Charter | What it gives your agent | Install |
+| --- | --- | --- |
+| [sdd-charter](https://github.com/tamnguyenvt/sdd-charter) | Spec-driven development: a spec set with a status per story and a roadmap of their dependencies, and skills (`/sdd-init`, `/sdd-plan`, `/sdd-implement`, `/sdd-finish`, `/sdd-report`…) that take each story from request to merge, stopping for your yes at each step. | `cw vendor add git@github.com:tamnguyenvt/sdd-charter.git --ref v0.1.0` |
+| [hexagonal-architecture-charter](https://github.com/tamnguyenvt/hexagonal-architecture-charter) | Sets up a hexagonal (ports and adapters) architecture in a folder you choose, then keeps the agent following it. | `cw vendor add git@github.com:tamnguyenvt/hexagonal-architecture-charter.git --ref v0.1.0` |
 
 ## Places outside the repository
 
@@ -258,7 +272,7 @@ The billing service. Look here before changing anything that charges a customer.
 A place is either an `endpoint` reached over HTTP, or a `command` with its
 `args` that `cw` starts as a local process; a local one takes a token only, in
 the environment variable its `tokenEnv` names. Any primitive points the agent
-at a place by naming it in its body as `mcp:mfbs/billing`.
+at a place by naming it in its body as `[[mfbs/billing]]`.
 
 ```bash
 cw build            # adds one entry, cw mcp serve, to your agent's .mcp.json
@@ -274,8 +288,8 @@ given: it serves the tools each place declares and forwards every call under
 your own credential. A place that is down or not signed in to loses only its own
 tools.
 
-A subagent reaches only the places it lists under `tools`: `mcp:<id>` for every
-tool of a place, or `mcp:<id>:<tool>` for one of them.
+A subagent reaches only the places it lists under `tools`: `[[<id>]]` for every
+tool of a place, or `[[<id>]]:<tool>` for one of them.
 
 ## Your agent can write rules too
 

package/dist/cw.js

@@ -3,7 +3,7 @@
 // package.json
 var package_default = {
   name: "cherry-works",
-  version: "0.3.0",
+  version: "0.5.0",
   description: "The charter engine: resolves a charter and compiles it into what a coding agent reads.",
   keywords: [
     "claude-code",
@@ -45,8 +45,6 @@ var package_default = {
     test: 'pnpm run lint:deps && pnpm run build && node --import tsx --test "test/**/*.test.ts"',
     cw: "node --import tsx main.ts",
     "lint:deps": "depcruise src main.ts",
-    "specs:link": "node --import tsx scripts/link-specs.ts",
-    "specs:check": "node --import tsx scripts/link-specs.ts --check",
     release: "node --import tsx scripts/release.ts",
     prepublishOnly: `node -e "console.error('Publish with \\"pnpm release <version>\\", which checks the package first.'); process.exit(1)"`
   },