@orchestraworks/cli 0.5.1 → 0.5.3

package/skills/orchestra-fdk/references/phases/1-discover.md

@@ -0,0 +1,111 @@
+# Phase 1: Discover
+
+**Goal:** you know what to build: a new factory or a new environment, what the codebase needs to run, and
+which services the agents must reach. You write it down before any factory code exists.
+
+Write every finding into `<codebase>/../orchestra-factory-notes.md`, one line for each item, with the file,
+page or command that shows it.
+
+## 1. Read the account: a new factory or a new environment
+
+An organization usually holds one factory, or none yet. Read what it holds before you ask the developer
+anything. These commands only read. `--all-pages` follows every page, and prints the rows as one array:
+
+```bash
+npx --package @orchestraworks/cli orchestra agents list --all-pages --output json
+npx --package @orchestraworks/cli orchestra environments list --all-pages --output json
+npx --package @orchestraworks/cli orchestra pipelines list --all-pages --output json
+npx --package @orchestraworks/cli orchestra workflows list --all-pages --output json
+npx --package @orchestraworks/cli orchestra connections list --output json
+```
+
+A row that an apply made carries the label `sfdk.managedBy`, whose value is the factory's name.
+
+1. Infer what the developer most likely wants:
+   - *No agents and no pipelines:* the account is empty. Infer **a new factory**.
+   - *Rows labeled with a factory name:* a factory exists. Infer **a new environment for that factory**,
+     such as another repository, a bigger machine, or a machine of the team's own.
+   - *Rows with no label:* someone made them by hand or with the CLI. Infer a new factory. If a row's slug
+     is one the starter declares, such as `manager-agent`, the apply updates that row. Say so in phase 2.
+2. Tell the developer what you found, in one or two sentences, for example: "This organization already has
+   the factory `factory`, with the agents Manager Agent, Engineer Agent lg, md and sm."
+3. Ask once, with your question tool, with the inferred choice first and marked as the recommendation.
+
+**A new factory.** Go on with section 2.
+
+The starters build one factory per organization. When the organization already holds a factory and the
+developer wants another one, make a separate organization for it:
+
+1. Create it: `npx --package @orchestraworks/cli orchestra organizations create --name "<name>"`. Read
+   `organizations create --help` for its other flags. When the command refuses, the developer creates the
+   organization in the console at `https://app.orchestraworks.ai`.
+2. Sign in to it as phase 0 says, with `--org <the new organization>`.
+3. Start this phase again, in the new organization.
+
+**A new environment for the existing factory.** Do not run `orchestra fdk init` in phase 4. Edit the factory
+that exists instead:
+
+1. Find the existing factory's folder: the folder with `fdk.json` and `main.ts`. Ask the developer where it
+   is when it is not on this computer.
+2. Load the factory's inputs, the same way every earlier apply loaded them. The engineering-team starter
+   reads `~/.config/orchestra/tokens.env`; the bug-fix starter reads `~/.config/orchestra/fdk-inputs.env`.
+   Load the file with `set -a; . <file>; set +a`, and never print it. Ask the developer when the file is not
+   there. An apply without these inputs removes the token rules the factory has now.
+3. With the inputs loaded, run `npm install` and `npx orchestra fdk diff` in that folder. It must be a clean
+   diff before you edit anything. If it is not, show the changes to the developer and ask what to keep.
+4. Then read the repository (section 2) for the new environment only. Phase 2 plans the new environment and
+   the agent that works on it, and phase 4 adds them to the existing code.
+
+## 2. Read the repository
+
+Read the codebase before you write any factory code. The factory must match it, and the machines most of
+all. Note each item:
+
+- **The operating system it builds and runs on.** These mean Windows: a `.sln` or `.csproj` that targets
+  .NET Framework, WinForms, WPF or IIS, PowerShell build scripts, or `windows-latest` in CI.
+- **The runtime it needs.** A kernel feature, a GPU, nested virtualization, an Android emulator, or a tool
+  for another operating system, such as Xcode, means a full virtual machine or the team's own machine.
+- The languages and toolchains, with their versions: `global.json`, `.nvmrc`, `.tool-versions`, the CI's
+  setup steps.
+- The build and test commands, from the CI file first, then the README and the build scripts.
+- The package feeds, private ones included: `nuget.config`, `.npmrc`, `pip.conf`, a feed in the CI file.
+- The services it needs, such as a database or a queue: a compose file, test containers, connection
+  settings.
+- Docker use: a `Dockerfile`, a compose file, Testcontainers.
+- The repository size: `du -sh <codebase>` and `git -C <codebase> count-objects -vH`.
+- The code host and the tracker: the remote URL (`git -C <codebase> remote get-url origin`), and links in
+  the README, the branch names or the CI file.
+
+These are facts for the later phases. Ask the developer only what the files cannot answer.
+
+## 3. Name each service, by category and provider
+
+For each outside service the agents need, name its category and its provider. Each category has one file in
+`../integrations/`:
+
+| Category | File | Examples |
+|---|---|---|
+| Code host | `code-repo.md` | GitHub, Bitbucket, GitLab, Azure DevOps |
+| Tracker | `issue-tracker.md` | Jira, Linear, GitHub Issues, Azure Boards |
+| Knowledge base | `knowledge-base.md` | Notion, Confluence, Guru |
+| Chat | `messaging.md` | Slack, Microsoft Teams |
+| Package registries | `dependencies.md` | npm, PyPI, NuGet, Maven |
+| CI and CD | `ci-cd.md` | GitHub Actions, Azure Pipelines, Jenkins, CircleCI |
+| Observability | `observability.md` | Sentry, Datadog, New Relic, Grafana |
+| Support desk | `support-desk.md` | Zendesk, Intercom, Freshdesk |
+| Design | `design.md` | Figma |
+| Cloud | `cloud.md` | AWS, Azure, Google Cloud |
+| Databases | `databases.md` | A staging database or a read replica |
+| Secrets managers | `secrets-managers.md` | 1Password, Vault, Azure Key Vault |
+| Incidents | `incident.md` | PagerDuty, Opsgenie |
+| Analytics | `analytics.md` | Pendo, Mixpanel, Amplitude |
+| Feature flags | `feature-flags.md` | LaunchDarkly, Split, Unleash, ConfigCat |
+
+Infer each one from the codebase and the connections list. Then tell the developer what you found, and ask
+once, with your question tool, which code host, which tracker and which other services the agents need.
+Put your inference first, marked as the recommendation. No provider is a default.
+
+## Exit check
+
+`orchestra-factory-notes.md` has a line for each item in sections 2 and 3, or says the item does not apply,
+and it records the answer to section 1: a new factory, or a new environment for a named factory.

package/skills/orchestra-fdk/references/phases/2-plan.md

@@ -0,0 +1,157 @@
+# Phase 2: Plan
+
+**Goal:** the developer approves what you will build, before anything reaches the platform. You plan from
+the starter and from the finding of phase 1, the environment first.
+
+## 1. Choose the starter
+
+Ask one question, with these three choices:
+
+- **An engineering team (your real repository).** Recommended.
+- **A todo app sample.** A small public app, `orchestraworks/todo-app`, for a quick first success.
+- **I already have a factory.ts.**
+
+For a new environment in an existing factory, skip this question: you change the factory that exists.
+
+Read the starter before you change it. It ships in the kit's package, two folders above this skill's folder.
+Select the Claude Code link that exists, resolve it, then go up two:
+`skill_link=.claude/skills/orchestra-fdk; [ -e "$skill_link" ] || skill_link=~/.claude/skills/orchestra-fdk; cat "$(realpath "$skill_link")/../../templates/engineering-team/README.md"`
+(use `.agents/skills/orchestra-fdk` and `~/.agents/skills/orchestra-fdk` for Codex). Read its `main.ts`,
+`lib/environment.ts`, `lib/inputs.ts`, `lib/setup.sh` and `agents/` in the same folder. The README says what
+the starter declares, and why.
+
+The starter declares no integration: no code host, no tracker, no connection and no provider Secret. It
+applies and runs with only the model route, and the first work is created by hand. Phase 3 adds a private
+package feed the build needs before phase 4, and the other services of phase 1 after the first run works.
+
+## 2. Adapt the starter, the environment first
+
+Change the plan to match the notes of phase 1. Write each change into `orchestra-factory-notes.md` with its
+reason, such as "Windows VM, because the solution targets .NET Framework 4.8".
+
+- *The operating system.* A Windows codebase needs a Windows virtual machine. The starter declares Linux
+  only, so plan these hand edits in `lib/environment.ts` and the files beside it:
+  - set `platform: { os: "windows", arch: "amd64", runtime: "vm" }`;
+  - map every size to `"4"` or `"8"`, because a Windows machine takes 4 or 8 CPU;
+  - remove `disks`, because a Windows machine takes no extra disks, and use a folder on its own disk, such
+    as `C:\work`, in place of `/work`;
+  - replace `lib/setup.sh` with a PowerShell `.ps1` script;
+  - Docker there runs Windows containers only, and only for administrators.
+
+  Plan Windows in three stages, in this order, and show the developer all three
+  (`../environment.md`, section 5, "Windows in three stages"):
+  1. Start on hosted Windows with our image. The setup script installs what fits in its 10 minutes. The
+     rest goes in the agent's first turn, and the parked machine keeps it until `ttl` deletes the machine
+     (the orchestra skill, section 4, "Lifetime"). This proves the factory works.
+  2. Then move to the team's own Windows image, with their toolchain installed, through a compute provider
+     in their cloud. Machines start with everything installed, and their licenses stay in their image. The
+     compute provider runs on Azure. Not released yet: on AWS.
+  3. Then keep machines ready with `standbyCapacity` on the agent, so a conversation starts at once.
+
+  `../environment.md`, section 5, has the rest.
+- *The runtime.* `microvm` for most Linux code. `vm` for Windows, an Android device or a kernel of its own.
+  The team's own machine (`host`) for a Mac. `../environment.md`, section 5, "The machine's runtime".
+- *The toolchain and the setup.* The versions the notes name, and the codebase's dependencies.
+- *The size.* Match what the team's CI uses for the same work. Sizes are 2 GB of memory per CPU.
+- *The network.* Egress starts open on every machine, and the first run adds only the model route's key and
+  the key of any private package feed the build needs.
+- *The agents' text.* Where the build or test commands, or the work folder, differ from what `agents/*.md`
+  says, plan to change those lines. Keep the Attribution section at the top of each agent's instructions,
+  and start every new agent's instructions with it (`../authoring.md`, "Every agent's instructions start
+  with an Attribution section").
+- *A `script` agent.* Where a step needs no model judgment, such as a scheduled sync or a data pull, plan a
+  `script` agent. It runs a shell program and no model. The orchestra skill, section 2, says what it can and
+  cannot do.
+
+## 3. The model route
+
+### The private token file
+
+A subscription or an own key needs a token, and so does each service phase 3 connects later. Tokens come
+from one file. Ask the developer to make a file only they can read, outside the codebase:
+
+```bash
+mkdir -p ~/.config/orchestra && touch ~/.config/orchestra/tokens.env && chmod 600 ~/.config/orchestra/tokens.env
+```
+
+They add one line for each token, filled in by them, such as `ORCHESTRA_FDK_GITHUB_TOKEN=...`. Never ask for
+a token in the chat, never print one, and never write one into a file in `<codebase>` or `<factory>`. Load
+the file into a command's shell without printing it: `set -a; . ~/.config/orchestra/tokens.env; set +a`.
+
+### The routes
+
+Each agent needs a way to reach its AI model. There are three equal options. The developer uses the one
+that matches what they already have. Ask which they have, with your question tool, or infer it from what is
+set up, such as an existing factory's model Secret or `ModelProviderKey`. For plan questions, send the
+developer to **Settings › Plan & usage** in the console.
+
+**A Claude or Codex subscription.** The developer signs in a real terminal on their own computer. Run from
+your shell, its browser step hangs. You never read or copy the value.
+
+- *Claude.* `claude setup-token` prints a long-lived token. The developer saves it in the private file as
+  `ORCHESTRA_FDK_CLAUDE_CODE_OAUTH_TOKEN`. The factory stores it as a Secret, and the network edge adds it to
+  calls to `api.anthropic.com`. The machine holds only a placeholder token and an empty API key. Declare the
+  Claude sign-in recipe from `../authoring.md`, "Secrets are recipes, never values". Never put the token in
+  the environment's settings: they are stored and shown in plain text.
+- *Codex.* A personal access token, which begins `at-`. A ChatGPT Business or Enterprise member makes it at
+  `chatgpt.com/admin/access-tokens`, when the workspace owner allows it. Or a separate ChatGPT sign-in:
+  `CODEX_HOME=<dir> codex login`, never a copy of the developer's own `~/.codex` sign-in. A separate sign-in
+  must live on a `/home` volume that every machine using it shares, because each renewal replaces the
+  sign-in. Keep a Codex sign-in off the model gateway: the gateway refuses its requests with
+  `model_not_found`. The sign-in goes in the `ORCHESTRA_WORKER_CODEX_` variables in the environment's `env`,
+  and the worker writes it into Codex's own sign-in file (`../authoring.md`, "The subscription variables").
+  The worker reads them from its own environment: on a hosted machine, from `env`; on an enrolled machine,
+  from the environment the worker runs with. `env` is stored and shown in plain text.
+
+An agent on a subscription turns the model gateway off: remove `enableModelGateway: true` from its model
+settings.
+
+**An Orchestra account, through the model gateway.** One endpoint reaches OpenAI, Anthropic and open
+models. `orchestra model-configs` sets which providers serve a model and in which order, and
+`orchestra model-aliases` gives a model the organization's own name. The organization can add its own
+provider key to the gateway as a `ModelProviderKey` (orchestra skill, section 7). The starter's code uses
+this option as written, so it needs no edit.
+
+**Their own provider API key.** The key is a Secret that the network edge adds to calls straight to the
+provider, with no gateway in between. For Anthropic: `api.anthropic.com → x-api-key: <SECRET>`. For OpenAI:
+`api.openai.com → Authorization: Bearer <SECRET>`. Read the key from a variable such as
+`ORCHESTRA_FDK_ANTHROPIC_API_KEY`, and turn `enableModelGateway` off for the agent.
+
+## 4. Show the plan
+
+Show two tables. Under each table, give each change from the starter with its reason, from the notes.
+
+**Agents.** One row for each agent. Name no machine here.
+
+| Agent | Description | Model (harness) | Skills | Access |
+|---|---|---|---|---|
+| Manager Agent | Triages each item, gives it the code, and assigns it. | `claude-opus-5-5` (`claude`) | The codebase skill, once it exists | The model route. The code host and tracker once phase 3 connects them. Roles `agent-worker` and `agent-manager`. |
+
+Fill in the rows from the plan, not from this example. *Access* names the services the agent reaches and the
+roles it holds. Each new agent gets `agent-worker`: its own sessions, and reads, with no change to
+triggers. The Manager Agent also needs `agent-manager`, which a person grants by hand in phase 4. It can
+change agents, pipelines, work items and workflows.
+
+**Working environment.** One row for each agent.
+
+| Agent | Size (CPU and memory) | Arch (OS and runtime) | Network |
+|---|---|---|---|
+| Manager Agent | 32 CPU, 64 GB | Linux amd64, `microvm` | Open. The model gateway key is added at the network edge. |
+
+Then explain the rest in plain words, from the orchestra skill. Say what each idea is for first, then what
+it is:
+
+- *Pipelines* hold the work items: sections 9 and 10. Show each pipeline's name, item prefix and stages.
+  An item can move from any stage to any other. An agent moves an item to its review stage when it needs a
+  person.
+- *The model route* of section 3, and what it changes in the starter.
+- *What phase 5 proves:* the app runs on an agent's machine, and one small real item goes end to end.
+
+Ask the developer, with your question tool, whether they approve the plan or want changes. Answer each
+question. Change the plan until they approve it.
+
+## Exit check
+
+The developer said yes to the two tables, the model route and the changes, and `orchestra-factory-notes.md`
+holds each change with its reason. For a subscription or an own key, the token file exists with mode 600
+(`stat`). Do not read its contents.

package/skills/orchestra-fdk/references/phases/3-connect.md

@@ -0,0 +1,99 @@
+# Phase 3: Connect
+
+**Goal:** the agents can reach each service the developer chose to connect, on the developer's behalf. The
+developer gives the access. You make sure egress is open.
+
+**When.** A first run needs no optional integration: the starter applies and runs with only the model route.
+But the build may need a private service, such as a private package feed (phase 1, "The package feeds"). The
+machine cannot install the code without it, so phase 5 cannot pass. On a first run, the factory folder does
+not exist yet: phase 4 writes it. So here, only prepare each feed's credential, from
+`../integrations/dependencies.md`: the developer writes its token into the private token file (section 2,
+step 1). Then go to phase 4. It writes the Secret and the rule into `lib/environment.ts` after `init`, and
+checks the access after the apply. When the build needs nothing private, skip this
+phase. After phase 5 passes, come back and connect the code host, the tracker and the other services found in
+phase 1, one at a time. Ask the developer which ones to connect now.
+
+The developer gives access in one of two ways, and egress stays open:
+
+- **A Secret** for a credential. The developer writes the token into the private token file (phase 2,
+  "The private token file"). The apply stores it as a Secret, and the network edge adds it to each matching
+  request. No agent and no person sees it.
+- **An env value** for a setting that is not secret, such as a site address. It goes in the environment's
+  `ENV` in `lib/environment.ts`. Env values are stored and shown in plain text, so a token never goes there.
+
+Egress starts open: the starter uses `EgressPolicy.allowAll()`. Add no allow rule only to reach a host. Add
+the rule that adds a credential, and the open policy does the rest. Tightening is a later step, after the
+factory works (`../environment.md`, section 5, "Network").
+
+## 1. Read the integration file
+
+For each service the developer chose, read its row and its section in the matching file in
+`../integrations/`. Each file starts with a short section on how to give access, then one table:
+
+| Provider | Access | Scopes | Check command |
+|---|---|---|---|
+
+- *Access* is a recipe, `host → header: value`, or a platform connection by its catalog key.
+- *Scopes* is what the token needs, no more.
+- *Check command* is one HTTPS call the agent runs on its machine, with no credential in it: the edge adds
+  it. A `200` alone does not prove the access. Some providers answer `200` without a credential, such as a
+  public repository, or `200` with a failure in the body, such as Slack's `"ok":false` or a GraphQL
+  `errors` list. So the check passes only when the answer shows the provider's success value: the token's
+  own user, the private resource, or the success field the row names.
+
+The agent installs or uses whatever client it prefers. The edge adds the credential to that client's
+requests too, so no client needs a token of its own.
+
+## 2. Give the access
+
+For each service, read the *Access* cell of its row. Do steps 1 and 2 only for a `host → header` recipe,
+which a Secret backs. A platform connection, such as Slack, Microsoft Teams or the GitHub App, takes no token
+file and no Secret: declare the connection in `main.ts` and add its rule, as its file says. For Slack and
+Microsoft Teams, the apply prints the link the developer opens to authorize it (phase 4, section 3). For any
+other OAuth connection, the apply prints no link: the connection stays `NEEDS_ATTENTION`. Read its link with
+`npx orchestra connections get <slug> --output json`, at `auth.authorizationUrl`, and give it to the developer.
+
+1. Ask the developer to make the token on the vendor's page, with the scopes in the row. They add it to the
+   private token file as `ORCHESTRA_FDK_<SERVICE>_TOKEN`. Never ask for it in the chat.
+2. Write the recipe as one Secret and one credential rule in `lib/environment.ts`, on every environment that
+   needs it, as the next table says. The starter's `declareKeys` holds the Secrets, and its egress policy
+   holds the rules after `EgressPolicy.allowAll()`. Put any env value in `ENV`.
+3. Where events should make work, such as a new issue, declare the platform connection and a `Trigger` in
+   `main.ts`. The integration file names the connection's catalog key and its events. The orchestra skill,
+   sections 12 and 17, says what a trigger and a connection are.
+4. Apply as phase 4 says: synth, diff, the developer's yes, then apply, with the token file loaded.
+5. Ask the agent to run the row's check command on its machine, or run it yourself in a session.
+
+### From a recipe to code
+
+| Recipe value | Secret value | Binding |
+|---|---|---|
+| `Bearer <SECRET>` | `SecretValue.fromEnv("<VAR>")` | `bearer("Authorization", secret)` |
+| `Basic <user>:<SECRET>` | `SecretValue.basicAuth("<user>", SecretValue.fromEnv("<VAR>"))` | `basic("Authorization", secret)` |
+| `<SECRET>` alone, in any header | `SecretValue.fromEnv("<VAR>")` | `header("<Header>", secret)` |
+| Any other shape, such as `Token token=<SECRET>` | `SecretValue.fromEnv("<VAR>")` | `inject(secret, { headers: [{ name: "<header>", value: "Token token=${secret}" }] })` |
+
+```ts
+const sentry = new Secret(factory, "sentry-token", { value: SecretValue.fromEnv("ORCHESTRA_FDK_SENTRY_TOKEN") });
+// in the environment's egress, after EgressPolicy.allowAll():
+.allow("sentry", { hosts: ["sentry.io"], priority: 300, credential: bearer("Authorization", sentry) })
+```
+
+Two Secret rules on one host with one priority are a tie: the first declared wins. When two such rules share
+a host, give each its own `paths`, or give the narrower one a higher priority. A platform connection adds its
+own rule: `.allow(<connection>)`, or `.applyPreset(<connection>.egressPolicy())` where its file says so.
+
+Two platform connections of one provider in one environment, such as two GitHub installations, are
+different. Keep their rules at equal priority, and set `attributeConnection: true` on the agent target of
+each trigger that starts their sessions. Or put the two connections in separate environments. A higher
+priority on one rule sends that connection's key on every request to the host, also for a session of the
+other connection.
+
+## Exit check
+
+Every service the developer chose to connect has its access: a Secret from the private token file, an env
+value, or a platform connection the developer authorized. Its check command, run from an agent's machine,
+shows the provider's success value. Every environment keeps `EgressPolicy.allowAll()`.
+
+On a first run, the check is smaller: each private feed's token is in the private token file. Phase 4 checks
+the access after its apply.

package/skills/orchestra-fdk/references/phases/4-build.md

@@ -0,0 +1,159 @@
+# Phase 4: Build
+
+**Goal:** the platform matches the plan the developer approved in phase 2, with the access of phase 3.
+
+A *clean diff* is a `npx orchestra fdk diff` that creates, updates and deletes no agent, environment or
+pipeline. While a token or key is loaded, each Secret it fills shows `value-write-pending` on every diff, even
+right after an apply. That is expected, and a clean diff may show it.
+
+**Load the token file before every diff and every apply, a repair apply included,** once the factory reads
+any token from it. A Secret declared with `SecretValue.fromEnv` takes its value from the shell at apply, so an
+apply without the variable cannot write it, and code that declares a rule only when its token is set drops
+that rule.
+
+## 1. Write the factory
+
+For a new environment in an existing factory, skip this section: edit that factory's folder (phase 1).
+
+1. Make a new, empty folder beside the codebase: `<codebase>/../orchestra-factory`. Call it `<factory>`. Do
+   not install the kit in it before point 2.
+2. In `<factory>`, write the starter the developer chose in phase 2:
+
+   ```bash
+   npx --package @orchestraworks/cli orchestra fdk init --template engineering-team
+   ```
+
+   For the todo app sample, use `--template todo-factory`. It works on the public `orchestraworks/todo-app`.
+   For their own `factory.ts`, copy their folder into `<factory>` instead. It needs `fdk.json` and a
+   `"type": "module"` package.
+
+   Run `init` in the new, empty folder, with no kit installed there: the starter brings its own
+   `package.json`. It writes `README.md`, `main.ts`, `inputs.json`, `package.json`, `fdk.json`,
+   `tsconfig.json`, `agents/` and `lib/`. It overwrites nothing. If a file is in the way, it writes nothing
+   and names it.
+3. In `<factory>`, run `npm install`. From now on, run `npx orchestra` in `<factory>`.
+
+## 2. Edit it to the plan
+
+1. Make each change of phase 2, the environment first, and the model route's change. On a first run, also
+   write the Secret and the rule of each private feed phase 3 prepared (phase 3, section 2, step 2).
+2. Fill in `<factory>/inputs.json`: `repositoryUrl`, the repository's HTTPS address, and
+   `repositoryDefaultBranch` (`git -C <codebase> symbolic-ref refs/remotes/origin/HEAD`). Both may stay
+   empty. Then the Manager Agent takes the address from each item. When the remote is an SSH address, such
+   as `git@<host>:<org>/<repo>.git`, write its HTTPS form, `https://<host>/<org>/<repo>.git`. Azure DevOps
+   is different: `https://dev.azure.com/<organization>/<project>/_git/<repo>`. A hosted
+   machine cannot reach SSH ports, and the network edge adds a credential to HTTPS requests only.
+3. Run `npm run typecheck`, then `npx orchestra fdk synth`, with the token file loaded if the factory reads
+   one. The local proof builds its environment and agent from `fdk.out/plan.json`, which synth writes.
+4. Prove the machine on this computer with `../environment.md`, sections 1 to 6. It writes what worked into
+   the setup script and the environment code. Come back here after its section 6, and synth again in
+   section 3 below.
+
+On a first run, the factory declares the model route and any private package feed the build needs: no code
+host, no tracker and no connection. Phase 3 adds them later, with this same synth, diff, approve and apply.
+
+## 3. Synth, diff, approve, apply
+
+1. Load the token file, if the factory reads one. Run `npm run typecheck`, then `npx orchestra fdk synth`.
+   Read `fdk.out/warnings.json`, and fix each warning or tell the developer why it stays.
+2. Run `npx orchestra fdk diff`. It changes nothing.
+3. Show the developer the change list in plain words: the agents, the environments, the Secrets, the rules,
+   the connections and the pipelines. State each change with its reason. Say what the developer must do in
+   the browser: an install link or an authorize link (phase 3, section 2, says where each one comes from).
+4. Ask them to approve it, with your question tool.
+5. On a yes, and only then, run the apply, with the token file loaded if the factory reads one:
+
+   ```bash
+   npx orchestra fdk apply --require-approval never
+   ```
+
+   The flag is needed because your shell has no terminal to type "y" at. It is safe only after the
+   developer approved the same change list.
+6. When the apply prints an install or authorize link, give it to the developer. When it says a connection
+   needs attention and prints no link, read the link with `npx orchestra connections get <slug> --output json`,
+   at `auth.authorizationUrl`. A GitHub App install link
+   is shown once. Add `--install-timeout 0` to the same approved apply, so it stops at the link rather than
+   waiting. When the developer says the app is installed or the consent is given, run the same apply again.
+   If a link was lost, add `--remint-install-links`: it revokes the old link and prints a new one.
+7. On a first run with a private feed, check its access now. Ask an agent to run the feed's check command
+   from `../integrations/dependencies.md` on its machine, or run it yourself in a session. It must return
+   the private package, not an error or a sign-in page.
+
+An organization on the `individual` plan cannot store a key or add one at the network edge, so the apply
+stops with a plan error. Tell the developer, and point them to **Settings › Plan & usage** in the console.
+
+## 4. The steps the code cannot declare
+
+**Grant the Manager Agent the `agent-manager` role**, for the whole organization. An agent starts with only
+`agent-worker`. `<factory>/README.md`, "After apply: steps the code cannot declare", holds the commands. The
+role list you send replaces the old one, so keep every entry it has now. Ask the developer to approve: "Give
+the Manager Agent the agent-manager role in the whole organization?" On a yes, send the update with
+`--require-approval never`. Then `npx orchestra organization-memberships get <membership id>` lists both
+roles.
+
+## The fast path: one bug in a GitHub repository
+
+`orchestra fdk init` without `--template` writes the bug-fix starter: one agent that takes a bug as its first
+message and answers with a pull request and a report. Take this path when the developer wants one bug fixed
+in a GitHub repository. Do phases 0 and 1 first. Then:
+
+1. Make a new folder beside the codebase, `<codebase>/../orchestra-factory`, called `<factory>`. In it, run
+   `npm init -y`, then `npm install @orchestraworks/cli`.
+2. Write the starter. `<owner>/<name>` is the GitHub repository. Add `--model-key anthropic` or
+   `--model-key openai` only when the organization brings its own model key to the model gateway.
+
+   ```bash
+   npx orchestra fdk init --repository <owner>/<name>
+   ```
+
+3. Run `npm install`, then `npm run typecheck`. Both must pass.
+4. Fill in `<factory>/skills/codebase/SKILL.md` with how the codebase installs, tests and starts, and the
+   services it needs. When the codebase has an `AGENTS.md` or `CLAUDE.md`, write one line naming it instead.
+5. Set the shell inputs. `main.ts` reads them, and `init` printed each with what it is. They come with the
+   hand-over note: `ORCHESTRA_FDK_IMAGE_REPOSITORY`, `ORCHESTRA_FDK_RUNTIME_IMAGE`,
+   `ORCHESTRA_FDK_MODEL_GATEWAY_HOST`, `ORCHESTRA_FDK_IMAGE_PULL_ACCESS_KEY_ID` and
+   `ORCHESTRA_FDK_IMAGE_PULL_SECRET_ACCESS_KEY`, plus `ORCHESTRA_FDK_ANTHROPIC_API_KEY` or
+   `ORCHESTRA_FDK_OPENAI_API_KEY` with `--model-key`. Ask the developer to write them into a file only they
+   can read, and load it in each command that runs `orchestra`:
+   `set -a; . ~/.config/orchestra/fdk-inputs.env; set +a`. Docker on this computer must also be signed in
+   to the image registry, with the details in the same note.
+6. Run `npx orchestra fdk diff` and show the developer the change list. On their yes, run
+   `npx orchestra fdk apply --require-approval never --install-timeout 0`. It builds and pushes the image,
+   prints a GitHub App install link, and stops without waiting. Give the link to the developer, and ask them
+   to say when the app is installed. Then run the same apply again.
+7. Send the bug. The agent's id is `<factory name>-bugfix`, where the factory name is the one `init` printed:
+
+   ```bash
+   npx orchestra sessions start --agent-id <factory name>-bugfix --content '[{"type":"text","text":"<the bug, as the reporter wrote it>"}]' --output json
+   ```
+
+   `--content` is a JSON array of content blocks, never plain text. Escape each `"` in the bug text as `\"`, and write no `'` in it.
+   The answer is `{"session":{…},"firstItem":{…}}`. The session id is `.session.id`.
+8. Wait for the turn to end, in the foreground, with one blocking command:
+
+   ```bash
+   npx orchestra sessions wait <session id> --timeout 540
+   ```
+
+   Do not start the wait in the background and end your turn. A headless agent exits when its turn ends,
+   and the waiting command goes with it. `--timeout 540` ends the wait before a ten-minute command limit.
+   When it times out, it prints the session's last status and exits non-zero: run the same command again.
+9. `sessions wait` shows no progress. To see what the agent did, read the conversation's items:
+   `npx orchestra sessions list-items <session id> --output json`. The rows are in `data`. The developer
+   can watch the same session live in the console at `https://app.orchestraworks.ai`, or in a terminal
+   with `npx orchestra sessions tail <session id>`, which prints each item as it is saved.
+
+The fast path ends when the session's status is `COMPLETE`, and its last message names the pull request and
+the report.
+
+## Exit check
+
+A second `npx orchestra fdk diff`, with the same shell, is a clean diff, each private feed answers its check
+command (section 3, step 7), and these list every agent and environment of the plan:
+
+```bash
+npx orchestra agents list --all-pages --output json
+npx orchestra environments list --all-pages --output json
+```
+
+If the check fails, read `../troubleshooting.md`, "`fdk diff` shows something you did not expect".

package/skills/orchestra-fdk/references/phases/5-prove.md

@@ -0,0 +1,107 @@
+# Phase 5: Prove
+
+**Goal:** the customer's app runs on an agent's machine in the cloud, and a person can reach it. Only then
+does one small real work item go end to end.
+
+Spinning up the app is the most important part of this phase. An agent can fix, test or show the code only
+when its machine can build and run it.
+
+## 1. The app runs on a machine
+
+The starter cannot declare items, and its setup script runs before the code is on the machine. So the first
+item, Set up, created by hand, asks the Manager Agent to get the code, install it and start the app on its
+own machine. No code host connection is needed. The code reaches the machine one of two ways:
+
+- *A public repository:* the agent clones it from its HTTPS address. Egress is open.
+- *A private repository:* cut a git bundle on this computer, outside the codebase, and upload it as a File.
+  Name the file id in the item. The agent downloads it with `orchestra files get-content` and clones from it.
+
+  ```bash
+  git -C <codebase> bundle create <codebase>/../orchestra-setup.bundle <default branch>
+  npx orchestra files create --file <codebase>/../orchestra-setup.bundle --output json
+  ```
+
+1. Create Set up in the Features pipeline:
+
+   ```bash
+   npx orchestra work-items create --pipeline features --title "Set up" --description "<the Set up message>" --output json
+   ```
+
+   The description says:
+   - Clone the repository under `/work`, at the tip of the default branch: from its public address, or from
+     the bundle `Code bundle: <file id>`.
+   - Install the dependencies with the internet.
+   - Write the app's own settings files, such as `.env.local`, from what `../environment.md` found. Use local
+     or test values only. Note in the report any setting or log that names a production or live host, and
+     continue.
+   - Start the whole stack with the project's own scripts, and load its seed data.
+   - Check it the way a person uses it: call the API and check real answers; for a web UI, sign in as a
+     local test user and do one real business operation. Make one smoke request to each app port on the
+     machine, such as `curl -fsS http://127.0.0.1:<port>/`.
+   - Report the machine endpoint of each app port, each command, its result and its time.
+   - Then run the unit, functional and end-to-end tests. Report which ran, which could not, and whether they
+     match the team's CI. The tests do not decide Done: the app running does.
+   - Prove that an Engineer Agent can run the tests from a git bundle of the same commit.
+2. Start it: `npx orchestra work-items assign <item id> --agent-id manager-agent`. Assigning starts the
+   Manager Agent's conversation on the item, and a machine starts for it.
+   For a new environment in an existing factory, the existing Manager Agent runs on its own environment, so
+   it proves nothing about the new one. Assign Set up to the agent you added on the new environment instead:
+   `--agent-id <new agent slug>`. Use the same agent in section 4.
+3. Watch it: `npx orchestra work-items get <id> --output json` lists the item's `sessions`. Run
+   `npx orchestra sessions wait <session id> --timeout 540` in the foreground, and run it again when it times
+   out. The developer can watch the same session in the console at `https://app.orchestraworks.ai`.
+
+## 2. A person can reach the app
+
+1. Find the machine and its endpoints:
+
+   ```bash
+   npx orchestra machines list --environment-id <environment id> --output json
+   npx orchestra machines get <machine id> --output json
+   ```
+
+   Each declared port has an entry in `endpoints`, with its `url` once the machine is `RUNNING`. Only
+   signed-in members of the organization can open it. A port that is not declared has no endpoint: add it to
+   `PORTS` in `lib/environment.ts` and apply as phase 4 says. The apply reaches only machines made after it,
+   so then add the endpoint to the running machine:
+   `npx orchestra machines create-endpoint <machine id> --port <port> --output json`.
+2. Prove it is reachable. Open the `url` with a browser tool in a browser signed in to Orchestra, and take a
+   screenshot of the app's page. Or ask the developer to open it, and to confirm what they see. The Set up
+   report's smoke requests are the second proof.
+3. An app with no web address, such as an Android app, is a screen on the machine. Show it with a *machine
+   view*: a live stream of that screen, which the developer opens from the machine's page in the console.
+   `npx orchestra machines list-views <machine id> --output json` lists the views.
+
+When a step fails, fix it in the environment. Go back to `../environment.md`, prove the fix on this computer,
+and apply it as phase 4 says. Then assign the item again to wake the agent. Note the time before you assign.
+The session can still show the last turn's `COMPLETE`, and then `sessions wait` returns at once. So run
+`npx orchestra sessions get <session id> --output json` first, and wait only once its `lastActiveAt` is later
+than that time. `../troubleshooting.md` names each failure.
+
+## 3. Name the codebase skill
+
+When the Manager Agent makes a codebase skill, it names the skill's slug. Add
+`skills: [Skill.fromSlug(factory, "<skill slug>")]` to Engineer Agent sm, md and lg in `main.ts`, as
+`<factory>/README.md`, "After apply", says. Apply as phase 4 says. Without this line, the next apply takes the
+skill away.
+
+## 4. One small real item, end to end
+
+Only after the app is reachable:
+
+1. Ask the developer for one small, real bug or feature. Create it by hand in Bugs or Features with
+   `npx orchestra work-items create`, and assign it to the Manager Agent, or to the new agent for a new
+   environment in an existing factory (section 1). For a private repository, name a
+   new bundle of the default branch in the item, as in section 1.
+2. The description asks for two things beside the fix:
+   - the change: a pull request once phase 3 has connected the code host, or until then a patch uploaded as a
+     File, which the developer applies and pushes;
+   - a report page that shows the change running on the machine: screenshots from the machine endpoint or
+     the machine view, and the test result. The agent publishes it as an artifact with
+     `orchestra artifacts create`, and names its link in the item.
+3. Wait as in section 1. Read the report with the developer.
+
+## Exit check
+
+The app is reachable at a machine endpoint or a machine view, with a screenshot or a smoke request as proof,
+and the first real item has its change, as a pull request or a patch, and a report page.