@orchestraworks/cli 0.5.2 → 0.5.4

package/skills/orchestra-fdk/references/troubleshooting.md

@@ -0,0 +1,128 @@
+# Troubleshooting
+
+A phase's exit check failed. Each part below names what you see, what it means, and what to do. Find the
+cause before you change anything, then run the exit check again. Read the facts first, with these commands.
+They only read:
+
+| What | Command |
+|---|---|
+| A conversation | `npx orchestra sessions get <session id> --output json`: `status`, `failureCode`, `failureReason` |
+| Its messages and turns | `npx orchestra sessions list-items <session id> --output json`: rows in `data` |
+| The machines of an environment | `npx orchestra machines list --environment-id <id> --output json` |
+| One machine | `npx orchestra machines get <machine id> --output json`: `status`, `failureReason` |
+| What the cloud saw | `npx orchestra machines get-diagnostics <machine id> --output json` |
+
+On a turn's message item, `turnState` says where the turn is (`QUEUED`, `IN_FLIGHT`, `COMPLETED`, `FAILED`,
+`INTERRUPTED` and others). A failed turn carries `failureCode`, a short code, and `failureReason`, a
+sentence. Read both.
+
+## A machine does not start
+
+A machine's `status` is `PENDING`, `RUNNING`, `STOPPING`, `STOPPED`, `OFFLINE`, `TERMINATED` or `FAILED`.
+A `FAILED` machine names the cause in `failureReason`:
+
+- **`registration_timeout`.** The machine started, but the worker inside it never connected back before the
+  deadline. The deadline is the substrate's start time plus, with a setup script, 10 minutes and a margin.
+  Look at `get-diagnostics`: `substrate.events` and `substrate.outOfMemory`. A custom image or `command`
+  that does not start the worker gives this. Prove the image with `worker check` (`authoring.md`).
+- **`worker_never_registered`.** The cloud said the machine was serving, and nothing connected. Read it as
+  `registration_timeout`.
+- **`setup failed: ...`.** The setup script exited with a code, timed out, or gave no result. The platform
+  does not keep the script's output. Run the script on this computer, in the local environment
+  (`environment.md`, section 4), and fix it there.
+- **`disk missing: ...`.** A declared disk was not mounted.
+
+A turn that failed for its machine carries one of these `failureCode` values:
+`machine_image_unavailable` (the image did not download: check the tag and the pull key Secret),
+`machine_capacity_exhausted`, `machine_storage_unavailable` or `machine_start_failed`. A failed start check
+before any machine is made names the missing capability in `failureReason`.
+
+`503` with `NO_ROOM` on a machine create or resume: there is no room now. Try again after the
+`Retry-After` time.
+
+## A request from the machine is refused
+
+The network edge answers the agent, not you. The agent sees one of these:
+
+- `403` with `destination is not allowed: <host>` and `code` `CREDENTIAL_UNAVAILABLE`. No rule allows the
+  host. `details.reason` is `policy_denied` or `ambiguous_match` (two rules match with equal weight). The
+  answer does not name a rule.
+- `403 egress identity missing` or `egress destination mismatch`, or `502 egress broker unavailable` or
+  `egress upstream unavailable`: a fault on the path, not the rules.
+
+To check the rules the machine has now, read `egressPolicy` in `get-diagnostics`: `defaultAction`, and each
+rule's name, priority, action, hosts and paths. Fix the rules in code and apply. Rules reach running
+machines at once. A `403` from the provider itself, such as GitHub, means the key is there but lacks a
+permission or scope.
+
+## An integration's check command fails
+
+The check command of an integration file (`integrations/`) runs on an agent's machine:
+
+- `403` with `destination is not allowed`: see the part above.
+- `403` with `ambiguous_match`: two rules on one host, at one priority, add the keys of two different
+  platform connections, and the session belongs to neither. Keep the two priorities equal, and set
+  `attributeConnection: true` on the agent target of each trigger that starts the sessions. Or put the two
+  connections in separate environments. Do not raise one rule's priority: that connection's key then goes on
+  every request to the host, also for a session of the other connection.
+- Two Secret rules (not connections) on one host at one priority do not refuse: the first declared wins.
+  Give each its own `paths`.
+- `401` from the provider: the edge added a credential in a form the provider does not take. Check the
+  recipe: `Bearer` or `Basic`, the user name of a Basic pair, or the header name. Check that the token file
+  was loaded at the last apply.
+- `403` from the provider: the credential is there, but its scopes or its user's rights are too narrow.
+- No answer from a host inside the team's network: hosted machines reach the internet only
+  (`environment.md`, section 5, part C).
+
+## A machine in the team's own cloud cannot reach a service
+
+A compute provider's machine (the Launcher) has no network edge of ours in front of it, so no Secret is
+added to its requests. The team sets every credential on the machine (`environment.md`, section 5, part
+C, "Tokens on a compute provider's machines").
+
+- A `401` from the model provider, or "Invalid API key": the worker service's environment does not have
+  the model sign-in. On Windows, read the `SfdkWorker` service's `Environment` registry value.
+- The value is set, but the agent still sends the old one: the worker read its environment before the
+  boot step set it. Restart the worker service (`Restart-Service SfdkWorker` on Windows).
+- A token in the environment's `env` (`provisionSpec.env`): move it to the worker service's environment.
+  The platform stores and returns `env` values, and the VM's startup data carries them in plain text.
+- The boot step cannot read the team's Key Vault: the Launcher attaches no managed identity to its VMs.
+  The team's automation attaches one, and finds the VMs by the tags `orchestra-launcher` and
+  `orchestra-machine`.
+- No answer from a host: the team's own network or firewall blocks it. Our rules can only allow there.
+
+## The sign-in stops working
+
+- `this sign-in has expired or been revoked` or `The stored login is not accepted`: run
+  `npx orchestra auth login` again (`phases/0-start.md`).
+- A token typed at the `--no-browser` prompt cannot renew itself. Sign in through the browser instead.
+- A network error never means a new sign-in is needed. Try the command again.
+
+## A session does not start: limits and credits
+
+- `429` with `code` `QUOTA_EXCEEDED` names a `dimension`, its `limit` and the `current` count:
+  `CONCURRENT_SESSIONS`, `CONCURRENT_MACHINES`, `CREDITS` or `MACHINE_MINUTES_MONTHLY_LIMIT`. Wait for
+  running sessions to end, or send the developer to **Settings › Plan & usage** in the console.
+- A turn that failed this way carries `failureCode` `quota_exceeded`.
+- A trigger that could not start a session shows the reason on the trigger's `lastDecision`. A work item
+  shows a feed note: `No session started for <agent>: ...`.
+- The model gateway answers `403` with `credits_exhausted` or `budget_exceeded`, in the model provider's
+  own error shape, with a `[sfdk]` prefix on the message.
+- `403` with `PLAN_FEATURE_DISABLED`: the plan does not include the feature. This is not a credit problem.
+
+`maxSessionsPerMachine` is not an error. A session past it starts another machine.
+
+## `fdk diff` shows something you did not expect
+
+Each row is `create`, `update`, `refused`, `value-write-pending` or `no-change`. Blocked rows print
+`will fail — <reason>`, and apply refuses them before it writes anything.
+
+- **`value-write-pending` on every diff.** A Secret whose value comes from the shell. Apply writes it each
+  time, because it cannot read the old value. This is expected.
+- **An `update` you did not write.** Someone changed the row in the console or with a command. Apply sets it
+  back to the code. Write the change into the code if it must stay.
+- **Rules or Secrets about to be deleted.** The shell does not hold the tokens. Load the token file
+  (`set -a; . ~/.config/orchestra/tokens.env; set +a`) and run the diff again. Do this before every apply, a
+  repair apply included. When the code declares a token's Secret only if its variable is set, an apply
+  without the variable takes that Secret and its rules off every machine.
+- **Orphans.** Rows with the factory's label that the code no longer declares. Apply does not delete them.

package/templates/bug-fix/agents/bugfix.md

@@ -6,5 +6,5 @@ You fix bugs in the GitHub repository <repository>, one bug per conversation. Th
 3. Fix it with the smallest change and run the test again. Keep the passing output.
 4. Push a branch as soon as the test passes, then open a pull request against the default branch with gh:
    what was wrong, the fix, and the tests you ran.
-5. Publish a report with your sf-report skill: the failing and the passing output, and the change.
+5. Publish a report with your artifacts skill: the failing and the passing output, and the change.
    End with the pull request's link and the report's slug.

package/templates/bug-fix/main.ts

@@ -136,7 +136,7 @@ new Agent(factory, "bugfix", {
   modelSettings: { enableModelGateway: true },
   instructions: readFile("agents/bugfix.md").replaceAll("<repository>", REPOSITORY),
   skills: [
-    Skill.fromId(factory, "skill_sf-report"),
+    Skill.fromId(factory, "skill_artifacts"),
     new Skill(factory, "codebase", { source: "skills/codebase" }),
   ],
 });

package/templates/engineering-team/README.md

@@ -10,36 +10,29 @@ in any of its pipelines can be assigned to any of its agents.
 
 | Path | What it holds |
 |---|---|
-| `main.ts` | The Manager Agent, Engineer Agent sm, md and lg, and Engineer Agent bare for the Bootstrap's baseline; their machines; the model gateway key, and the two token Secrets once they are connected; the Onboarding, Bugs, Features and Support pipelines. |
+| `main.ts` | The Manager Agent and Engineer Agent sm, md and lg; their machines; the model gateway key; the Bugs, Features and Support pipelines. |
 | `agents/` | The agents' instructions. |
-| `lib/` | The inputs, the machines, the keys and the network rules, used by `main.ts`. |
+| `lib/` | The inputs, the machines, the model gateway key and the network rules, used by `main.ts`. |
 
-| Agent | Slug | Harness | Model | Machine | Bitbucket and Jira |
-|---|---|---|---|---|---|
-| Manager Agent | `manager-agent` | claude | `claude-opus-5-5` | `manager-work-lg`: 32 CPU, 64 GB | Tokens added |
-| Engineer Agent lg | `engineer-lg` | claude | `claude-opus-5-5` | `engineer-work-lg`: 32 CPU, 64 GB | Blocked |
-| Engineer Agent md | `engineer-md` | codex | `gpt-6.1-sol` | `engineer-work-md`: 16 CPU, 32 GB | Blocked |
-| Engineer Agent sm | `engineer-sm` | codex | `gpt-6-luna` | `engineer-work-sm`: 2 CPU, 4 GB | Blocked |
-| Engineer Agent bare | `engineer-bare` | claude | `claude-opus-5-5` | `engineer-work-lg`: 32 CPU, 64 GB | Blocked |
+| Agent | Slug | Harness | Model | Machine |
+|---|---|---|---|---|
+| Manager Agent | `manager-agent` | claude | `claude-opus-5-5` | `manager-work-lg`: 32 CPU, 64 GB |
+| Engineer Agent lg | `engineer-lg` | claude | `claude-opus-5-5` | `engineer-work-lg`: 32 CPU, 64 GB |
+| Engineer Agent md | `engineer-md` | codex | `gpt-6.1-sol` | `engineer-work-md`: 16 CPU, 32 GB |
+| Engineer Agent sm | `engineer-sm` | codex | `gpt-6-luna` | `engineer-work-sm`: 2 CPU, 4 GB |
 
-Work goes to Engineer Agent lg first. Engineer Agent sm and md take no work of their own until replays show
-that a kind of work passes on them. Engineer Agent md reviews Engineer Agent lg's changes from the start.
-Engineer Agent bare takes only the Bootstrap's baseline replays. Its instructions, in `agents/engineer-bare.md`,
-hold no work loop, and it never gets a codebase skill.
+Work goes to Engineer Agent lg first. Engineer Agent sm and md take no work of their own until a person
+says that a kind of work may go to them. Engineer Agent md reviews Engineer Agent lg's changes from the start.
 
 | Pipeline | Item prefix | Stages, in order | What it holds |
 |---|---|---|---|
-| Onboarding | `onbd` | Todo, In progress, Needs review, Done | Set up, Bootstrap and every Replay item. |
-| Bugs | `bug` | Triage, Parked, In progress, In review, Done, Won't fix | Bugs. Parked holds a bug that waits until the factory is commissioned (the Bootstrap passes), or a bug a person has set aside. |
+| Bugs | `bug` | Triage, Parked, In progress, In review, Done, Won't fix | Bugs. Parked holds a bug a person has set aside. |
 | Features | `feat` | Backlog, Todo, In progress, In review, Done | Features. |
 | Support | `supp` | Triage, Answering, Waiting on requester, Resolved, Closed | Questions from the team's users. |
 
-An item may move from any stage to any other. An agent moves an item to Needs review or In review when its
-work is ready for a person, or when it needs a decision.
-
-The Onboarding pipeline is temporary. It is retired after commissioning, when another pipeline replaces it.
-To delete it, first close or move its open items, and remove every trigger and workflow that names it. The
-platform refuses to delete a pipeline that still has any of them.
+An item may move from any stage to any other. An agent moves an item to its review stage when its work is
+ready for a person, or when it needs a decision. The review stage is In review in Bugs and Features, and
+Waiting on requester in Support.
 
 Every machine:
 
@@ -49,28 +42,19 @@ Every machine:
 - is open to every host, and adds the model gateway key on `models.orchestraworks.ai` at the network edge,
   so no agent holds it.
 
-Once the tokens are connected, the Manager Agent's machine also adds the Bitbucket token on
-`api.bitbucket.org` (Bearer) and `bitbucket.org` (git over HTTPS, Basic auth), and the Jira token on the Jira
-site host (Basic auth over the account email and the token).
-
-The Engineer Agents' machines deny `bitbucket.org` and `api.bitbucket.org`, and the Jira site host once it is
-set in `inputs.json`. They carry no token. A deny rule wins over the open default.
-
 An environment declared in code keeps only what it declares. So the model gateway rule is declared here on
 every machine. If you remove it, `orchestra fdk apply` removes it from the platform too.
 
 ## How the Engineer Agents get the code
 
-Until commissioning, the Engineer Agents cannot reach Bitbucket or Jira. The code reaches them as a *git
-bundle*, a single file that holds a repository's history:
+The code reaches the Engineer Agents as a *git bundle*, a single file that holds a repository's history. The
+bundle fixes the commit the work starts from, so the author and the reviewer of a change read the same code:
 
-1. The Manager Agent clones the repository and cuts a bundle holding history only up to the commit the work
-   starts from. For a replay, that is the commit before the fix. For real work, it is the tip of the default
-   branch.
+1. The Manager Agent clones the repository, from the address in `inputs.json` or in the item, and cuts a bundle holding history only up to the tip of the
+   default branch.
 2. It uploads the bundle as a File, and writes `Code bundle: <file id>` in the item.
 3. The Engineer Agent downloads it with `orchestra files get-content`, clones from it, and answers with a patch
-   uploaded as another File. Platform calls are not governed by the machine's network rules, so the
-   download works on a blocked machine.
+   uploaded as another File.
 
 Their instructions in `agents/` carry these steps.
 
@@ -89,66 +73,28 @@ ends the turn, so the notice the platform sends when an item is assigned away st
 fixes each confirmed P1 and P2 finding, in at most two rounds, and reports the evidence on the item.
 `agents/engineer-agent.md` carries these steps. To check UI work in a browser, turn on the Chromium block in `lib/setup.sh`.
 
-## Commissioning
-
-*Commissioning* is when the Engineer Agents start real work on the tracker. Then:
-
-1. In `main.ts`, give Engineer Agent sm, md and lg the codebase skill the Bootstrap made. The Bootstrap's
-   Done comment names the skill's slug. Import `Skill` from `"@orchestraworks/cli"`, and add
-   `skills: [Skill.fromSlug(factory, "<skill slug>")]` to those three agents' props. Engineer Agent bare
-   never gets the skill. An apply sets each agent back to this code, so without this line the
-   apply takes the skill away.
-2. In `main.ts`, change the Engineer Agents' `access` from `"blocked"` to `"tokens"`. The deny rules go and
-   the token rules come.
-3. Update the Engineer Agent instructions in `agents/engineer-agent.md`. They say the agent cannot reach
-   Bitbucket or Jira and gets its code as a bundle. Tell it to clone the repository and use the tracker.
-4. Apply when no replay is running. The network edge reads an environment's rules live, so the change
-   reaches every machine at once, machines already running included. A replay that can reach Bitbucket or
-   Jira can find the real fix.
-
 ## Inputs
 
-Nothing about one team is written in the code. It comes from two places:
-
-- `inputs.json`: the repository address, its default branch, the Jira site host and the Jira account email.
-- The shell, at `orchestra fdk apply` only: `ORCHESTRA_FDK_BITBUCKET_TOKEN` and `ORCHESTRA_FDK_JIRA_TOKEN`. No file in this folder holds
-  them.
-
-Every value may be empty. A token is connected only when its shell variable and the inputs it needs are set:
-
-| Token | Shell variable | Inputs it needs |
-|---|---|---|
-| Bitbucket | `ORCHESTRA_FDK_BITBUCKET_TOKEN` | `repositoryUrl`, `repositoryDefaultBranch` |
-| Jira | `ORCHESTRA_FDK_JIRA_TOKEN` | `jiraSite`, `jiraEmail` |
-
-A token that is not connected has no Secret and no rule. Synth prints one warning that names each value still
-missing, and goes on. Until both are connected, the Manager Agent's instructions say what is not connected,
-and tell it to ask for it in Needs review.
-
-## Run it: two applies
-
-The first apply comes before any token or input, so you see the agents and pipelines first.
+The factory declares no code host and no tracker, so it needs no token. `inputs.json` holds two values, and
+both may be empty:
 
-1. Write the factory and apply it:
+- `repositoryUrl`: the address `git clone` takes, on any git host. When it is empty, the Manager Agent takes
+  the address from each item.
+- `repositoryDefaultBranch`: the branch pull requests go to.
 
-   ```bash
-   npm install
-   npm run typecheck
-   npx orchestra fdk diff
-   npx orchestra fdk apply
-   ```
+The machines carry no token for the code host. A public repository clones without one. For a private one,
+the Manager Agent asks on the item how to reach it.
 
-   This creates the five agents, their machines with the model gateway key, and the four pipelines. Synth
-   warns that the repository and the tracker are not connected yet.
+## Run it
 
-2. Connect the repository and the tracker, and apply again:
-   1. Fill in `inputs.json`.
-   2. Save the two tokens in the shell: `export ORCHESTRA_FDK_BITBUCKET_TOKEN=...` and `export ORCHESTRA_FDK_JIRA_TOKEN=...`.
-   3. Run `npx orchestra fdk diff`, then `npx orchestra fdk apply`. The token Secrets and the Manager Agent's token rules are
-      added, and the warning goes away.
+```bash
+npm install
+npm run typecheck
+npx orchestra fdk diff
+npx orchestra fdk apply
+```
 
-Run every later apply with the two token variables set. An apply without them takes the token rules off the
-Manager Agent's machine again.
+This creates the four agents, their machines with the model gateway key, and the three pipelines.
 
 ## After apply: steps the code cannot declare
 
@@ -165,101 +111,19 @@ Manager Agent's machine again.
       `agent-worker` included, and add the new one:
       `{"roleAssignments":[<the existing entries>, {"roleId":"<agent-manager role id>"}]}`.
    5. Send it: `npx orchestra organization-memberships update <membership id> --body @grant.json`.
-2. **Create the score metrics.** The kit cannot declare a metric. Run this once, from this folder:
-   `bash onboarding/create-score-metrics.sh`. It stops at the first error, and a second run skips each
-   metric that exists. It runs `npx orchestra metrics create` once for each metric:
-   - `replay-pass`: true or false, and true is better. It says whether every change was right.
-   - `replay-f05`: a number from 0 to 1, and higher is better. It is the replay's F0.5.
-   - `replay-precision`: a number from 0 to 1. It is the part of the agent's changes that match the real fix,
-     with the work loop's extra tests and doc comments counted as neutral.
-   - `replay-raw-precision`: a number from 0 to 1. It is the same part, with those tests and doc comments
-     counted as changes.
-   - `replay-recall`: a number from 0 to 1. It is the part of the real fix that the agent made.
-
-   The Manager Agent writes a replay's scores into them on its Replay item, with
-   `orchestra metrics write-value <metric> --value <value> --body score.json`. The command has no flag for the
-   subject or the labels, so `score.json` holds both:
-   `{"subject":{"kind":"workItem","id":"<item id>"},"labels":{"arm":"full"}}`. The label `arm` is `full` for
-   an Engineer Agent lg replay and `bare` for an Engineer Agent bare replay.
-3. **Create the first Onboarding items.** The kit cannot declare items. Create them in the Onboarding pipeline, in
-   this order:
-   - "Set up", assigned to the Manager Agent. Assigning it starts the work.
-   - "Bootstrap", left unassigned in Todo. Copy the two values of "The Bootstrap threshold" below into its
-     description.
-
-   Once Set up is in Done, the developer's coding agent (Claude Code or Codex) or a person assigns Bootstrap
-   to `manager-agent`.
-
-## Bootstrap
-
-The Bootstrap is one Onboarding item. It teaches the Engineer Agents this codebase, then tests them on past
-pull requests they have not seen. It is a one-time step before commissioning.
-
-1. **Choose a cut date T.** The test set is 10 recent merged pull requests after T, about 5 bug fixes and 5
-   features. The study set is the 50 merged pull requests just before T, also bugs and features.
-2. **Study.** The Manager Agent reads the code and its history only as they were at T. The default branch
-   already holds the 10 test changes, so reading past T would teach their fixes. It checks out the commit at
-   T into a study copy that holds no later commit, and reads `git log` only up to T. There it reads the 50
-   and writes a direction map: the implicit rules, the hidden connections, the bug and feature map, the
-   directions, and where to look first. It skips `AGENTS.md` and `CLAUDE.md`, because the harness already loads them. Each entry cites two
-   or more commits or files, and an entry with one example is labeled a guess.
-3. **Apply.** It writes the map into a codebase skill on the platform, and points `engineer-sm`,
-   `engineer-md` and `engineer-lg` at it, by name. It never points `engineer-bare` at it, because the bare
-   replays measure an agent with no skill. That makes one new version of each of the three.
-4. **Test.** It creates one Replay item for each of the 10, with a bundle cut at the commit before the fix,
-   and assigns it to `engineer-lg`. These are the *full* replays: the codebase skill and the work loop. When
-   the report is ready, or when it is stuck, the Engineer Agent assigns the item back to `manager-agent`,
-   which scores it:
-   - A replay fails when any change is wrong. Otherwise its score is F0.5, over precision and recall
-     against the real fix.
-   - The work loop's extra tests and doc comments are neutral: neither a match nor a mismatch. Raw
-     precision counts them as changes, and is recorded too.
-   - The Manager Agent also runs the real pull request's tests on the change. For a feature, it judges
-     whether the change does what the ticket asks.
-   - The scores are values of the five score metrics on the Replay item, labeled `arm=full`.
-5. **Baseline.** At the same time, it creates a second Replay item for each of the same 10, and assigns it to
-   `engineer-bare`. These are the *bare* replays: the raw ticket text only, with no codebase skill, no
-   triage notes and no work loop. They are scored with the same rule, and their values are labeled
-   `arm=bare`.
-6. **Calibrate.** Assigning the Bootstrap item back resumes its conversation, which knows the first scores.
-   So the Manager Agent creates a separate "Calibrate" item and assigns it to itself, which starts a new
-   conversation. That conversation re-scores 3 of the 10 full replays without reading the first scores, adds
-   its scores and each disagreement as a comment on the Bootstrap item, and moves the Calibrate item to Done.
-7. **Check the threshold.** The threshold applies to the full replays only. The Manager Agent reports the
-   full and the bare replays side by side on the Bootstrap item: passes, mean F0.5, precision, raw precision
-   and recall. The baseline shows what the study adds, and gates nothing. On a pass, the Manager Agent moves
-   the Bootstrap item to Done and says the factory is ready to commission.
-8. **On a fail**, it writes down what was missing and fixes the skill, without tuning it to the 10 items'
-   real fixes. It then tests a fresh 10 from after T that round 1 did not use, with their own baseline. T
-   stays where it is, so the study copy holds none of them. If fewer than 10 remain, it uses all of them
-   and says how many.
-   After 2 rounds it stops and moves the Bootstrap item to Needs review.
-
-### The Bootstrap threshold
-
-Change these values here, then copy them into the Bootstrap item's description. A round passes when both
-hold:
-
-| Value | Pass at or above |
-|---|---|
-| Full replays that pass, of the 10 | 7 |
-| Mean F0.5 of the 10 full replays | 0.6 |
-
-After commissioning, the team improves the agents from real work, measured with these metrics.
-
-### Holding out the real fixes
-
-- The Engineer Agent's machine cannot reach Bitbucket or Jira, so it cannot look up the real pull request
-  there. It can still reach the rest of the internet, so its instructions also tell it not to search for
-  the fix.
-- Engineer Agents can read the organization's work items, comments, Files, skills and sessions. So before
-  the 10 are scored, the Manager Agent writes no real fix of the 10, and nothing that tells its specifics,
-  into any of them.
-- The scores are metric values and a comment, not a check: only an owner or an admin may write a check, and
-  the kit cannot grant that.
+2. **Name the codebase skill in `main.ts`.** When the Manager Agent makes a codebase skill, it names the
+   skill's slug. Import `Skill` from `"@orchestraworks/cli"`, and add
+   `skills: [Skill.fromSlug(factory, "<skill slug>")]` to the props of Engineer Agent sm, md and lg. An
+   apply sets each agent back to this code, so without this line the apply takes the skill away.
+3. **Send the work by hand.** Nothing brings work in by itself, and the kit cannot declare items. Create an
+   item in Bugs, Features or Support, in the console or with the CLI, and assign it to the Manager Agent:
+   `npx orchestra work-items create --pipeline bugs --title "<title>" --description "<the issue>" --output json`,
+   then `npx orchestra work-items assign <item id> --agent-id manager-agent`. Assigning it starts the Manager
+   Agent's conversation.
 
 ## Later
 
-- No triggers yet. A tracker listener, which turns each new Jira issue into an item, comes later.
+- No integration yet: no code host or tracker connection, token or trigger. To add one, declare its Secret in
+  `lib/environment.ts` and an egress rule that adds it on the provider's hosts.
 - A change the Manager Agent makes to an agent declared here lasts only until the next `orchestra fdk apply`, which
   sets the agent back to this code. Copy a change it wants to keep into this code.

package/templates/engineering-team/agents/engineer-agent.md

@@ -1,3 +1,9 @@
+## Attribution
+You are <self-name>. Mark the work you produce as yours:
+- every commit message and pull request description ends with
+  Co-Authored-By: <self-name> <<self>@agents.orchestraworks.ai>
+- every comment and tracker edit ends with one line: — <self-name>, Orchestra
+
 You are Engineer Agent <self>. You fix issues and build features in this team's code, one item per
 conversation. The item is your first message. Read its comments too: the last one may be a review request
 or a review, and then the review steps below say what to do.
@@ -7,8 +13,8 @@ At the start of every turn, run `orchestra work-items get <item id> --output jso
 item is not assigned to `<self>`, end the turn with one short line that names who holds it, and do nothing
 else.
 
-You cannot reach Bitbucket or Jira from this machine. The code comes as a git bundle, a file the Manager
-Agent uploaded. Its id is on the item's `Code bundle:` line.
+This machine can reach any host. The code for an item comes as a git bundle, a file the Manager Agent
+uploaded, so you and your reviewer start from the same commit. Its id is on the item's `Code bundle:` line.
 
 How you do a work item:
 
@@ -46,8 +52,7 @@ How you do a work item:
 9. When the review is done, report the evidence on the item: the cause or the design, the tests from step 3
    failing before and passing after, the full test runs, the check by hand with its File ids, the patch's
    File id, and each review finding with what you did about it. Then move the item to its review stage:
-   Needs review in Onboarding, In review in Bugs and Features. In Onboarding, also assign the item back to
-   `manager-agent`. Assigning it starts the Manager Agent's conversation, which scores the replay.
+   In review in Bugs and Features, Waiting on requester in Support.
 
 How you ask for a review:
 
@@ -102,8 +107,6 @@ When the item is assigned to you and its last comment is a review of your change
   Never ask for a round 3: after round 2, report as step 9 says, and list each finding still open.
 - When the review confirms no P1 or P2 finding, report as step 9 says.
 
-Do not try to find the issue's real fix anywhere else. When you are stuck or need a decision, move the item
-to its review stage and say exactly what you need. In Onboarding, also assign the item back to
-`manager-agent`.
+When you are stuck or need a decision, move the item to its review stage and say exactly what you need.
 
 Stop any Monitor or background task you started before your final message.