Quire setup

Set up Quire end to end: establish a stable CLI, install the current harness integration, establish account and model readiness, create concise project guidance, run doctor, and finish with deterministic readiness plus a concrete optional first-verification suggestion.

The parent coding agent owns setup and target prerequisites. Quire receives an already-running target through the request, --url, or QUIRE_WEB_URL; it does not install dependencies, manage secrets, migrate or seed data, create fixtures, guess ports, or start, restart, or supervise the target.

.quire/runbook.md is runtime guidance for the Quire Agent. It contains only durable, repository-specific facts that help the Agent recognize and access the target in its Run brief, exercise important workflows safely, recognize success, and choose trusted checks. Generic Quire behavior stays in Quire's own instructions.

1. Use the current Git top-level as the project root. Outside Git, use an explicit caller-provided root; never infer user-home scope.

2. Identify the active harness as exactly one of amp, claude, codex, cursor, opencode, or pi. Ask only when the environment does not make it clear.

3. Run quire --version. Do not use npx as a readiness probe: adapters need a stable quire command later.

4. If the command is missing, explain that npm install -g @quireco/cli writes the global package and npm cache, then ask permission for that command. If permission is declined, stop before installing an adapter that cannot run.

5. Install the selected project integration with:

   quire agent install --harness <harness> --project "$project_root" --json

   Project setup authorizes these repository-local files. Confirm every returned path remains under the project root and do not stage or commit them. The installer supports project-local integration only.

6. Determine whether the selected harness can load newly written agent definitions in its current process. Use the harness's known capability; do not probe by dispatching a task or starting a Run.

7. If it cannot hot-load them, record harness activation as restart required. Continue the remaining deterministic setup in the current parent session, but do not invoke the Quire adapter, silently fall back to a generic agent, or claim native Quire invocation. After the readiness checks, tell the user to restart or reload the harness and resume from the ready integration. Only a session in which the adapter is active may offer the first verification.

The installer owns the shared verify and triage skills, the selected harness adapter, and the managed Quire block in root AGENTS.md. Do not recreate or manually repair those files. Report malformed managed markers from the installer.

Every Run requires valid Quire account authentication, a pinned workspace, and one available hosted model source.

Run quire whoami --json and use its server-verified identity, workspace, and modelAccess rather than inferring readiness from local files. This check may refresh stale local Quire auth. Run quire doctor --json after account auth is ready; it may create the configured local runs directory. These are expected machine-local setup checks. Never read or print auth files or secret values.

• If account auth is missing or invalid, explain that quire login opens interactive authentication and writes local Quire auth, then ask permission immediately before running it.
• In a remote environment without browser login, ask the user to configure QUIRE_API_TOKEN through that environment's secret UI. Never request or print the token; request outbound access to the configured Quire API host when egress is restricted.
• Prefer a connected personal ChatGPT subscription when selected; it does not require Quire Credits.
• When personal ChatGPT needs connection or reconnection, direct the user to https://quire.sh/dashboard?settings=connections. The user completes provider authorization, then the agent reruns the readiness checks.
• When managed inference is selected, require its reported readiness and a positive Quire Credits balance. Direct an owner or admin to https://quire.sh/dashboard?settings=billing only when fresh CLI output requires a top-up.
• Follow the exact login, connection, billing, or retry action from fresh whoami and doctor output. Do not report readiness from stale output.

Quire account auth, hosted model access, and target-product test accounts are separate concerns.

Inspect before asking: read root guidance, the existing runbook when present, product docs, package/workspace scripts, deployment configuration, environment examples, important routes or commands, and trusted tests. Discover only environments the repository actually supports. For each one, determine how the Quire Agent can recognize it from the resolved target, how access works, what data or mutations are safe, and what should happen when access is unavailable. Separate repository facts from assumptions.

Ask concise grouped questions for unknowns that materially change environment recognition, authentication, mutation safety, an important workflow, its success signal, or fixture readiness. Incorporate the answers into the runbook. If the user cannot supply a required fact, report the affected path as not ready rather than guessing or leaving a question in runtime guidance.

1. Consider a target-product account only when an important documented workflow requires authentication.
2. Prefer a repository-supported disposable bootstrap or seeded-account flow when it matches the selected environment and mutation boundary. Record the access method and required account characteristics, not the incidental account created during setup.
3. Otherwise, check for a matching Quire-registered account scoped to the exact target origin.
4. If none exists, ask whether a reusable target account already exists and tell the user not to send its password or any secret.
5. If it exists, guide the user to register it through the authenticated workspace UI at https://quire.sh or, when they prefer the CLI, through the hidden password prompt in quire test-accounts add; then recheck. The parent agent never asks for, handles, or echoes the password.
6. If it does not exist, guide the user through the repository-supported target-product provisioning flow first. Quire does not invent, invite, reset, or seed an undocumented target account.
7. If account setup is deferred, mark only the affected verification path blocked and continue unrelated setup.

Never place passwords in chat, commands, repository files, the runbook, or public artifacts. Put an exact non-secret account identifier in the runbook only when the caller confirms that the identity is durable and selecting it is required; otherwise document the account characteristics and selection procedure.

Confirm the installer produced exactly one current managed Quire block in root AGENTS.md. Do not edit that block manually.

After the runbook is ready, rerun quire doctor --json. An absent target-product test account is not a global doctor failure; it blocks only paths that require it.

Setup is ready when the stable CLI, selected harness integration, account and model access, runbook, managed AGENTS block, and doctor are ready. Integration files may be ready while the current harness process still requires a restart to activate them; report that session blocker explicitly and do not claim the adapter is usable in the current process. Do not start quire run merely to prove setup. A Run uses the selected model source, writes durable local artifacts, may populate hosted-guidance caches, and is nondeterministic; reserve it for a meaningful caller-selected product claim.

Offer a first verification only when the harness adapter is active in the current process. If harness activation is restart required, end with the restart or reload instruction instead; do not dispatch any substitute agent in the current session.

Otherwise, end with one concrete first-verification suggestion grounded in the runbook and the caller's priorities. Prefer an important product workflow over a synthetic smoke. State the exact claim to verify, the caller-supplied target needed, any account or fixture prerequisite, and the permitted mutation boundary.

When the target and prerequisites are ready, ask:

Quire is ready. A useful first check is: “Verify against .” This is deep verification, can easily exceed five minutes, creates run artifacts, and uses your selected model source. When it completes I will return Quire's terminal handoff substantially intact. Would you like me to run it?

Do not start the Run until the user opts in. If they agree, preserve the suggested scope and every additional caller constraint, let the attached quire run continue through its terminal handoff even when it exceeds five minutes, and return the resulting Quire handoff substantially intact. Use only the caller-supplied target; if none is running, ask the caller to start it and provide the URL rather than guessing a target or substituting a code-only smoke.

When the suggested workflow or any other important documented workflow requires authentication, state whether a repository-supported bootstrap, assigned fixture, or matching Quire-registered account is ready. If it is missing, include a separate optional account-readiness next step even when the first suggested verification is public. Offer only the relevant choices: register an existing reusable account, provision one outside Quire, choose a public verification path, or defer authenticated verification. Recommend account setup only for important authenticated workflows, never ask for credentials, and keep the missing account scoped to the affected path. Do not call the first verification deferred unless the user explicitly defers it; otherwise report it as awaiting user opt-in.

Write for retrieval, not completeness. Put the highest-frequency target and access procedure first and state each instruction once. Prefer a short runbook; exceed roughly 800 words only when additional durable workflows materially change what a Run should do.

Use this shape, deleting empty or irrelevant sections:

# Quire runbook

One sentence of product context.

## Environments and access

### <Repository-supported environment>

- How to recognize this environment from the already-resolved target claim or URL.
- Authentication or bootstrap procedure, including return to the requested path and required account characteristics.
- Data ownership and permitted mutation boundary.
- What to report when the target is ambiguous, protected, unreachable, or lacks required access.

## Verification paths

### <Durable workflow or surface>

- Target and entry point:
- Preconditions or fixture state:
- Safe actions and stopping point:
- Success signal:
- Decisive evidence:

## Trusted checks

- Command, when it applies, and what a pass proves.
- Known cost, side effects, flakiness, or false positives.

## Project-specific exceptions

- Only safety, service, or environment constraints that change the default action.

## References

- Only sources that define expected behavior for the paths above.

Authoring rules:

• Write from the Quire Agent's perspective: its Run brief already contains the resolved target. Keep setup, invocation, target lifecycle, and post-Run evaluation in parent guidance.
• Ground every environment, route, account, fixture, command, and policy in repository evidence or caller answers. Verify user-facing routes from declarations, tests, or documented navigation. Document access methods and required account characteristics; include a named account and its selector only when the caller confirms that identity is durable.
• Include each repository-supported environment that materially changes target recognition, authentication, data ownership, mutation safety, or blocker behavior. Do not invent conventional environments such as staging when the repository does not define them.
• Include only durable workflows the caller identifies as important or repository evidence makes clearly critical. Route existence and the transient setup task do not make a workflow important.
• Give each path concrete preconditions, safe actions, a stopping point, a success signal, and decisive evidence. Preserve all assertions inside the caller's named scope without adding adjacent checks; one genuinely noticed out-of-scope issue may be one observation for caller triage.
• Describe product verification paths here and leave Browser, Mobile, Shell, and other runtime availability to each Run's capability context.
• List commands only for durable target access and trusted project checks. Preserve caller-confirmed commands exactly when repository evidence supports them, and state what each check actually proves from its assertions and execution layer.
• Preserve repository-specific self-dogfood facts that change what the Quire Agent should inspect or what evidence proves the product behavior. Keep commands that launch Quire and the parent's post-Run evaluation procedure outside the runbook.
• Keep project exceptions to repository-specific changes in default action. Exclude generic Quire mechanics, setup procedure, implementation architecture, duplicated policy, and verification-path requirements.
• When replacing an existing runbook, retain only current facts that change target selection, access, workflow execution, proof, or safety; remove obsolete, speculative, empty, and low-frequency background detail.
• Cite durable product or repository sources that define expected behavior.

End with:

## Quire setup readiness

- Quire command: `<command>`
- Harness integration: selected harness, project-local paths, or exact blocker
- Harness activation: active in this process, or restart/reload required before a Quire task
- Account and model access: ready or exact next user action
- Runbook: ready, including target/access and verification paths
- Managed AGENTS block: created, refreshed, unchanged, or exact malformed-marker blocker
- Target handoff: how the caller supplies the already-running target
- Authenticated verification paths: ready, not required, or named blocked paths; for each important blocked path include the required non-secret account characteristics and optional account-readiness next step
- Doctor: ready or exact blocker
- First verification: concrete suggested claim, required target and account prerequisites, and whether it is blocked on harness activation, awaiting user opt-in, completed by request, or explicitly deferred; include run id, link, verdict, and decisive evidence only when a Run was actually requested
- Unresolved required facts: none, or the exact readiness blocker and affected paths

Do not claim full readiness when a required item is blocked. Do not claim the whole setup failed when one authenticated path lacks a target-product account.