diff --git a/.github/workflows/installer-smoke-test.yml b/.github/workflows/installer-smoke-test.yml index d12eb58..25a1b43 100644 --- a/.github/workflows/installer-smoke-test.yml +++ b/.github/workflows/installer-smoke-test.yml @@ -31,6 +31,14 @@ jobs: - name: Verify Jobs skill packaging and bootstrap run: bash tests/jobs-skill.sh + agents-skill: + name: Agents Skill Installation + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + - name: Verify Agents skill packaging and bootstrap + run: bash tests/agents-skill.sh + unix-installer: name: Unix Installer (${{ matrix.os }}, ${{ matrix.shell_name }}) runs-on: ${{ matrix.os }} diff --git a/README.md b/README.md index 6214883..91267df 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,9 @@ Omit `--global` to install only in the current repository. Then ask your agent: Jobs guides a coding agent through repository setup, private submissions, pipeline and model configuration, durable job execution, automatic PR watching, and recovery. It follows the CLI's setup audit and installs ArchDev if needed. +Tasks are optional: `archdev jobs repo submit` (the canonical replacement for +`archdev push`) sends any committed branch through its configured pipeline. +Use `--task ` only when you want to associate an existing Task. ```bash npx skills add ArchAstro/archdev --skill jobs --global --yes @@ -87,6 +90,21 @@ npx skills add ArchAstro/archdev --skill jobs --global --yes Omit `--global` for repository-only installation. Ask your agent to configure repository automation, run a pipeline, or investigate a failed job. +## Install Agents independently + +Agents guides interactive and headless coding, Factory, saved sessions, +workflows, definitions, and worktree/local-work management. It also covers +`settings provider`: connect your ChatGPT or Grok subscription through OAuth, +use an API key when chosen, manage accounts, and select the intended model. +Agent-only onboarding does not install Jobs. + +```bash +npx skills add ArchAstro/archdev --skill agents --global --yes +``` + +Omit `--global` for repository-only installation. Ask your agent to connect your +provider, run a coding session, resume existing work, or set up Factory. + ## Repository scope This repository owns public distribution: installers, skills, release diff --git a/skills/agents/SKILL.md b/skills/agents/SKILL.md new file mode 100644 index 0000000..dfd55d8 --- /dev/null +++ b/skills/agents/SKILL.md @@ -0,0 +1,159 @@ +--- +name: agents +description: Use to set up and run ArchDev coding agents, resume or stop sessions, run Factory or workflows, inspect custom agent definitions, manage worktrees and local work, or configure settings provider with ChatGPT/Grok subscriptions, API keys, and model aliases. +--- + +# Agents + +Use ArchDev's public `agents` commands to run and manage coding sessions. +You drive setup, select the intended execution mode, retain the returned +identities, and inspect completion or hand the interactive session to the +human. Tasks are optional for ordinary coding sessions; do not create a Task +or DAG just to start an agent. Factory also supports session-led one-off work. + +## 1. Bootstrap + +Resolve the absolute directory containing this loaded `SKILL.md`, independently +of the current repository. Bootstrap returns the executable's absolute path on +stdout and installs or upgrades ArchDev if its Agents/provider commands are +missing. It does not log in or install a daemon itself. + +Bash/Zsh: + +```sh +archdev="$(bash /absolute/path/to/agents/scripts/bootstrap.sh)" +``` + +Fish: + +```fish +set archdev (bash /absolute/path/to/agents/scripts/bootstrap.sh) +``` + +PowerShell: + +```powershell +$archdev = & powershell -NoProfile -File 'C:\absolute\path\to\agents\scripts\bootstrap.ps1' +``` + +Examples below use `"$archdev"`; PowerShell uses `& $archdev` with the same +arguments. Prefer global `--json` for commands that expose structured results. +Some commands, such as provider accounts, still print text. If bootstrap fails, +report the error and point to the [official installer](https://github.com/ArchAstro/archdev#install). +Use help from the installed version; do not assume a new command exists because +an older CLI prints generic help with a successful exit code. + +## 2. Connect account and model access + +Read [providers.md](references/providers.md) when choosing providers, using +subscriptions/API keys, managing accounts, or changing models. + +1. Inspect existing `archdev.json`, the gitignored `archdev.local.json`, and + applicable user model settings. Preserve configured provider choices. +2. From the intended Git repository, run `"$archdev" agents setup` for + agent-only onboarding. It connects ArchDev/model access and validates agent + model settings without installing Jobs, private Git remotes, or Factory + automation. It may persist a missing `factory.model` default after validation. +3. Choose the provider interactively, or use `agents setup --provider openai + --provider-email ` for ChatGPT OAuth; use `xai` for Grok or `archdev` + for the ArchDev model router. The setup selector is `archdev`; the model + provider identifier for that router is `platform`. +4. Keep browser/device-code login running while the human signs in. Check + `auth status` separately from `settings provider status`: ArchDev identity + and BYO model credentials are different authentications. BYO does not remove + ArchDev's account-login requirement. +5. Inspect the chosen provider's model list and select the intended model + explicitly with `--model ` or `/model` inside the TUI. A provider + login alone is not proof the next request uses that provider. Verify the + actual selected model and a small authorized request when setup requires it. + +For existing model access, go straight to the requested operation. Do not run +full `archdev setup` merely to inspect a session or log in to ChatGPT. + +## 3. Choose the execution mode + +| Intent | Command | +| --- | --- | +| Interactive coding session | `agents start [prompt] [--model ]` | +| One headless request | `agents run [--model ] [--output-format json]` | +| Continue a headless session | `agents run --resume --output-format json` | +| Resume an ordinary or Factory TUI | `agents resume [--model ]` | +| Run a named model workflow | `agents workflows run [--input ] [--output-format json]` | +| Start Factory | `agents factory run [--workers ] [--model ]` | +| Inspect saved/live sessions | `agents sessions list` / `show ` / `stop ` | +| Inspect effective custom definitions | `agents definitions list` / `show ` | +| Create/remove lifecycle-managed worktrees | `agents worktrees create [path]` / `remove ` | +| Inspect/clean Factory-owned local work | `agents work list` / `show ` / `clean [ids...]` | + +Read [execution.md](references/execution.md) for workflow/definition authoring, +images, Factory operation, session control, worktree hooks, and cleanup. +`agents` is the ArchDev CLI namespace, not an ArchAgents platform-agent +creation/deployment API. + +`archdev run` is the short Factory alias in builds containing that change; +use `agents factory run` for the unambiguous canonical command. Older builds +used top-level `run --print` for headless execution. Do not use that old +spelling for new automation. Check `agents run --help` for `--resume` before +headless continuation on older installations; upgrade if it is absent. + +### Interactive sessions + +Start the command in a real terminal/persistent PTY. Keep the process handle; +a tool yielding output does not mean the agent exited. Hand the terminal to +the human if they want to interact, or drive normal prompt input through the +PTY when they asked you to operate the session. Do not open duplicate sessions +because one is quiet, or call an interactive TUI complete because startup +printed a banner. Save the real session ID for later inspection/resume. + +### Headless requests + +```sh +"$archdev" agents run "Inspect the failing test and explain its cause" --output-format json +``` + +A prompt is required unless using the image mode documented in the reference. +Supported controls include `--model`, `--max-turns`, `--permission-mode`, and +`--output-format`. Choose permissions from the user's authorized operation; +do not routinely enable bypass mode. A headless command may edit files when +its prompt and permissions allow it, so use the intended checkout. + +Parse the final result, including `session_id`, `is_error`, and `result`, and +check process exit status. Preserve `session_id` for continuation; do not parse +an arbitrary tool log line as the final answer. Verify the requested code or +artifact with the repository's checks before claiming success. For headless +continuation use a saved ordinary session; resume Factory interactively with +`agents resume` so its control lifecycle is restored. + +## 4. Enable Factory only when requested + +Factory coordinates workers, Tasks, one-off work, and repository automation. +It requires an initialized repository: connect model access, then run +`jobs setup` if registration/runner setup is needed. Full `archdev setup` also +performs those steps and can propose repository configuration. + +Before registering, account for the Jobs side effects: registration enables +discovery/remediation of eligible authored PRs, and project defaults may enable +automatic branch publication. `publish.auto: false` does not disable PR +watching. If the user wants no upstream mutations, do not promise isolation by +setting that field; establish the intended automation scope first. + +Run `agents factory run` in a persistent PTY. `--workers` accepts 1–32 and +selects worker concurrency; inspect configured models/capacity before raising +it. `factory.model` configures the overseer; `factory.worker_model` can override +workers. Missing worker model inherits the active overseer selection. Preserve +existing Tasks and session identity when resuming, rather than starting a new +Factory to bypass a blocked assignment. Use the Jobs skill, when installed, +for daemon/private-pipeline recovery and the Tasks skill for a web review loop; +neither companion skill is required merely to install this one. + +## 5. Verify and finish + +Report the chosen command/mode, actual model, session/work ID, observed result, +and any remaining blocker. Use `agents sessions show ` to check a live or +resumable session. Stop only the requested owner with `agents sessions stop +` when asked; do not kill the shared daemon to stop one agent. + +For configuration changes, run `"$archdev" --json check` and inspect effective +sources. Static validation is not evidence that OAuth completed, a subscription +has available capacity, or a job ran. Keep credentials out of commits, logs, +shared pages, and model prompts. Commit/push only within the user's authorization. diff --git a/skills/agents/references/execution.md b/skills/agents/references/execution.md new file mode 100644 index 0000000..a69acb3 --- /dev/null +++ b/skills/agents/references/execution.md @@ -0,0 +1,205 @@ +# Sessions, workflows, Factory, and local work + +Use the bootstrapped executable for these commands. Keep IDs returned by their +owning commands: session ID, work ID, Task ID, and daemon job ID are different +identities. Do not infer one from another's name or filesystem path. + +## 1. Interactive and headless work + +`agents start [prompt]` opens an ordinary interactive session; `agents run +` performs one headless request. Ordinary sessions do not require Jobs +registration and can run outside Git, though Git/worktree features then do not +apply. Agent-only `agents setup` itself runs from a Git repository. + +1. Read repository instructions and establish scope before sending a coding + prompt. Use the current checkout only if edits there are intended. +2. For interactive work, retain the PTY/process and use normal terminal input. + `/model` selects a model; `/help` describes the installed TUI commands. A + terminal session that is waiting for input is not a failed job. +3. For headless work, supply the prompt as one argument and check final output + plus exit status. `--max-turns` bounds agent turns; it is not a wall-clock + timeout. Permission choices are `default`, `acceptEdits`, `plan`, `deny`, + `auto`, and `bypass`; use only the authority the user granted. +4. Continue an ordinary headless conversation with `agents run + --resume `. Do not substitute a fresh session when continuity + matters. Use `agents resume ` for interactive resume, including + Factory sessions; it restores the saved mode. + +### Images + +Image generation is part of `agents run`, with a separate option namespace: + +```sh +archdev agents run --image-list-models +archdev agents run --image-options +archdev agents run --image "A simple red rocket icon" --image-model --image-output-dir +``` + +Use the returned model capabilities/options; do not guess supported sizes or +formats. Image mode uses `--image-model` and `--image-output-format`, not the +ordinary text model/output flags. It can create files and consume provider +usage, so run it when requested and inspect the returned output paths. Do not +combine it with an ordinary headless prompt or workflow invocation. + +## 2. Inspect and stop sessions + +```sh +archdev --json agents sessions list +archdev --json agents sessions show +archdev agents sessions stop +archdev agents resume +``` + +1. Run from the intended project's directory. These commands inspect its + top-level saved/live sessions, not a global list of every worker. +2. `show` reports ordinary/Factory mode, model, repository, activity, child work, + running instances, and resume information. A saved session with no live + owner is resumable, not necessarily crashed. +3. `stop` asks the authenticated live owner to cancel and drain its work. + Factory drains its external workers before acknowledging. Wait for that + acknowledgement; do not replace it with a PID kill or delete control files. +4. Stop preserves session history and identity. If the owner exited/changed + before acknowledgement, inspect again; do not report success from a stale + endpoint. Multiple live incarnations of the same session are handled by + the session control command. +5. Prefer the printed resume command and stable ID. Keep private control + tokens/files out of prompts, shared logs, and commits. + +## 3. Definitions and reusable agent behavior + +`agents definitions` inspects the same effective definitions used for +read-only delegation. It does not deploy platform agents or create Factory +workers. Put a specialist in `/.archdev/agents/api-reviewer.md`: + +```markdown +--- +name: api-reviewer +description: Inspect API contracts and callers for compatibility defects +model: "$session" +tools: [read, grep, find, ls, git] +--- + +Inspect the requested API change and unchanged callers. Report concrete +compatibility defects with file and line evidence. Do not propose unrelated +rewrites. +``` + +1. Project `.archdev/agents/*.md` overrides same-named user definitions under + `~/.archdev/agents`. A name defaults to the filename; description and a + prompt are required. ArchDev's explicit roots do not imply another CLI's + `.claude/agents` fallback. +2. Model can be a selector, alias, inherited `$session`, or ordered selectors. + These are read-only exploration agents. Effective tools are restricted to + the explorer tool set; `disallowed-tools` wins over `tools`. Adding `write` + or permission metadata cannot turn one into a coding worker. +3. Inspect both data and errors with `agents definitions list`, then + `agents definitions show api-reviewer`. Confirm effective source/model/tools; + a malformed definition can be reported while other definitions still load. +4. In an ordinary `agents start` TUI, `/delegate api-reviewer ` invokes a specialist and + `/delegate --bg api-reviewer ` starts background delegation. + `/route ` chooses by name/description matching. `/subagents` and + `/subagents stop ` inspect/stop session subagents. These are TUI slash + commands, not additional shell subcommands under `agents`. Factory has its + own exploration/control tools and does not expose these ordinary-session + delegation commands. +5. Some compatible frontmatter is accepted but not enforced by this runner + (including `permissions`, `max-turns`, `memory`, `skills`, `mcp-scope`, + `effort`, and `color`). Do not promise behavior from those fields. + +Shared skill roots are project/user `.agents/skills`; hooks are project/user +`.archdev/hooks.json`. Use the bundled `docs` agent tool in an ordinary `agents start` session before +extending hooks, skills, workflow schemas, or agent definitions. Factory does +not expose that ordinary-session tool. +That is a tool available to the agent, not an `archdev docs` CLI command. + +## 4. Workflows + +```sh +archdev agents workflows run --input "The bounded request" --output-format json +``` + +Named model-driven workflows load from project `.archdev/workflows` and user +`~/.archdev/workflows`; project definitions override same-named user definitions. +Read the existing definition and its referenced prompts before running it. +Use the ordinary agent session's bundled `docs` topics for declarative workflows/runners when authoring +one, and validate with `archdev check`. An external harness should consult the +installed/schema source rather than inventing a workflow format. + +Workflow nodes own model/tool configuration. The shell command accepts input +and output-format options, not ordinary `--model`, `--resume`, or `--max-turns`. +Inspect the returned status/error/report rather than treating emitted prose +as completion. Review workflows have their own `reviews workflows run` route; +durable command pipelines have `jobs run`. Pick the owner matching the work. + +## 5. Factory operation + +Factory needs a registered repository, ArchDev user authentication, a stable +repository Task source, and an effective `pipeline_bindings.branch_update` +at committed HEAD. It warns about uncommitted config; a working-tree edit +alone does not change that preflight. Follow normal commit authorization and +validate configuration before starting. + +```sh +archdev agents factory run --workers 3 +archdev agents factory run --resume +``` + +1. Give the overseer the desired outcome and constraints through normal TUI + interaction. It owns planning, dispatch, leases, worktrees, workers, private + submission, verification, and recovery. Do not layer a shell scheduler or + duplicate task list around it. +2. For Task graphs, use the native preview → exact-plan review → apply flow. + Approved `plan_hash` must match the unchanged preview. Feedback that changes + the graph requires a new preview/review; do not fabricate an approval hash. +3. Tasks are optional for session-led one-off work. Factory's `factory_workers` + tool can start bounded workers with `delivery: pipeline` (private submission + and exact-commit daemon verification) or `delivery: git` (one existing + branch; worker remains alive until stopped). These are Factory tool actions, + not invented shell commands such as `agents workers start`. +4. `factory.one_off_workers` is `confirm` by default, or can be `auto`/`disabled`. + Honor the native exact-request approval flow. Do not change it to `auto` + simply to avoid waiting for user input. Campaign work is for explicitly + named existing PR branches, not permission to sweep every PR. +5. Lifecycle requests can return a queued receipt. Inspect `command_status` + through the owning Factory control before claiming completion. `watch_job` + provides host-owned notifications; use them rather than inventing another + polling/supervision loop. +6. If workers are idle, inspect current dispatch diagnosis, claimability, + prerequisite state, retry timing, and exact job input before intervening. + A previously ready Task plus an idle worker does not establish a stall. + Retry through the owning Factory/Jobs operation, preserving identities. + +Keep automation within the user's scope, especially commits, upstream pushes, +and PR fixes. A Factory session may delegate work without the outer coding +harness spawning its own extra agent processes. + +## 6. Worktrees and retained local work + +```sh +archdev agents worktrees create feature/name ../feature-work --start-point origin/main +archdev agents worktrees remove ../feature-work +archdev --json agents work list +archdev --json agents work show +archdev agents work clean +``` + +1. Worktree creation invokes repository lifecycle hooks and prepares the runtime + environment. A new branch defaults to HEAD unless `--start-point` is supplied; + an existing branch keeps its own tip. Honor the user's branch policy rather + than blindly copying the example. Use real fetched refs, not guessed ones. +2. ArchDev worktree operations require the local installation/state store. + Direct `git worktree` calls bypass hooks/ownership bookkeeping; do not use + them as a workaround for failed preparation. +3. Remove only intended worktrees. `remove --force` can discard dirty content; + do not use it merely because ordinary removal rejected valuable work. +4. `work list/show` exposes durable local bindings, retained worktrees, and + dead-letter reasons. `work clean` selects terminal eligible work and retains + active/unpublished work. Inspect protected/failed entries; command success + does not imply everything was deleted. Task-backed cleanup may need auth. +5. `agents work reset --yes` permanently discards this project's managed work, + including unpublished changes and local planning/inbox records. Use only + for explicitly authorized reset, not ordinary troubleshooting. +6. There is no `agents work retry`. For dead-letter Factory preparation, inspect + the work, repair its prerequisite, and use Factory's task restart control. + For a failed daemon job use `jobs retry ` when eligible. Changing + Task status to open alone does not clear execution recovery state. diff --git a/skills/agents/references/providers.md b/skills/agents/references/providers.md new file mode 100644 index 0000000..54a9ad9 --- /dev/null +++ b/skills/agents/references/providers.md @@ -0,0 +1,195 @@ +# Providers and your own subscriptions + +Use this reference for model access, `settings provider`, account rotation, +and aliases. It describes ArchDev's implemented integrations; do not promise +subscription eligibility, unlimited usage, particular plan entitlements, or +prices from this document. Verify actual login and model execution. + +## 1. Choose the intended credential path + +| Path | Login | Model selector | +| --- | --- | --- | +| ArchDev model router | `archdev auth login` | `platform/` | +| Your ChatGPT subscription via OpenAI OAuth | `archdev settings provider login openai` | `openai/` | +| Your Grok subscription via xAI OAuth | `archdev settings provider login xai` | `xai/` | +| Your OpenAI/xAI API account | Provider API-key login or supported environment variable | Same direct provider prefix; verify resolved auth method | + +ArchDev account authentication and provider credentials are independent. Agent +execution still needs `archdev auth login` even when model requests use a BYO +account. Subscription OAuth and API keys are distinct paths; adding an API key +does not mean the CLI is using a subscription. Do not silently switch to a +platform/API route when the user requested their subscription. + +The canonical namespace is `settings provider`. Older top-level `provider` +commands remain compatibility aliases sharing the same credential store. + +## 2. Drive subscription login + +```sh +archdev auth status +archdev settings provider login openai --account +archdev settings provider login xai --account +archdev settings provider status +``` + +1. Run only the login for the selected provider/account. Omit `--account` to + use the saved account list or the provider's normal sign-in flow. Keep the + process alive until it reports completion; an opened URL is not success. +2. OpenAI defaults to browser OAuth. Let the human complete sign-in in their + browser; never ask them to paste passwords, OAuth callback codes, or tokens + into the conversation. A printed login URL is available if opening fails. +3. For SSH/headless machines use `settings provider login openai --device-code`. + Present the returned verification URL and short code to the human and wait + for the CLI to complete. The xAI/SuperGrok integration uses device-code OAuth + by default. Do not guess verification URLs or approve on the user's behalf. +4. Inspect `settings provider status` for provider, method, profile, expiry, + and stored count. The text view also reports known OAuth exhaustion times. + Inspect the account actually selected, not merely the email requested. +5. Select that provider's model explicitly and run a small authorized request: + +```sh +archdev settings provider models openai +archdev agents run "Reply with one short sentence confirming you can answer." --model openai/ --output-format json +``` + +Replace the placeholder with a real ID. Report the actual model and outcome, +not a claim that subscription access works based on credential storage alone. + +## 3. Inspect models and select one + +```sh +archdev settings provider list +archdev --json settings provider status +archdev --json settings provider models platform +archdev --json settings provider models openai +archdev --json settings provider models xai +``` + +`models platform` fetches the authenticated live platform catalog. OpenAI/xAI +catalogs are bundled with the installed CLI and can be listed without signing +in; they are discovery, not proof of usable credentials or account capacity. +`provider list`'s platform row is also not an authentication probe: use +`auth status` and an authenticated operation to verify ArchDev access. + +Human-readable model tables print full selectors. JSON returns +`{provider, data: [{id, ...}]}` where `id` is provider-local: prepend the returned +provider once. For example, provider `platform` plus ID `openai/` becomes +`platform/openai/`; provider `openai` plus ID `` becomes +`openai/`. Preserve nested provider-local paths. + +Use `--model ` for a run or `/model` within `agents start`/Factory. +Workflow execution uses models configured on workflow nodes rather than a +`--model` option on `agents workflows run`. Do not assume choosing a model for +one session rewrote every workflow or worker setting. + +## 4. Multiple subscription accounts + +```sh +archdev settings provider accounts openai list +archdev settings provider accounts openai add +archdev settings provider accounts openai remove +archdev settings provider login openai +``` + +The same commands work for `xai`. The saved email list lives in user +`~/.archdev/archdev.json`; adding an email does not authenticate it. Login walks +the saved list, skips stored OAuth accounts, and records account order and the +first active profile. `login --account ` limits that login walk to one +account; it is not a command for deleting the other stored credentials. +The login walk skips an existing OAuth credential for that email even if it is +expired: “Already stored OAuth” is not fresh authentication. Do not loop on +`login --account` expecting it to force refresh. If the credential cannot be +refreshed and a fresh login is needed, the public logout operation is +provider-wide: explain that scope and obtain appropriate authorization before +logging out and reconnecting the intended accounts. + +At runtime, eligible OAuth profiles follow configured ordering/active selection; +accounts in a recorded usage cooldown are skipped. Different model aliases +select providers/models, not specific account-email identities. + +`accounts remove` edits the login-email list; it does **not** remove the stored +credential, so that account can remain eligible. `settings provider logout +` removes all stored credentials for that provider. It does not clear +API-key environment variables. There is no documented per-email logout command; +do not promise one or delete credential-file entries manually. + +```sh +archdev settings provider accounts openai reset +``` + +`reset` clears local OAuth usage-cooldown markers. It does not reset the +provider's quota or erase the account list. Use it when a stale local cooldown +is the demonstrated problem, not as a loop for bypassing exhausted capacity. + +## 5. API keys when explicitly chosen + +The supported CLI shape is `settings provider login --api-key +`. The providers also accept `OPENAI_API_KEY` and `XAI_API_KEY` from the +process environment. Have the user supply secrets through their terminal or +an existing secret mechanism; do not collect raw keys in chat, place them in +project configuration, or emit them in tool logs. Passing a key as a literal +shell argument can expose it in shell history/process inspection. + +Default automatic resolution prefers stored OAuth profiles when present. +Exhausted OAuth profiles do not silently fall through to API keys. Without +that OAuth preference taking effect, environment keys precede stored API keys. +An explicit API-key runtime path has its own resolution. Check `status` and +the actual request/error before concluding which method a model used. + +Credentials are stored under the user's `.archdev` directory; `status` reports +the file path without requiring you to open it. Do not copy credential files +into a repository, import another coding harness's token store, or invent a +second provider store. Changes affect future resolution; already-running +sessions may need an intentional restart to pick up changed configuration. + +## 6. Reusable model configuration + +Use IDs verified above; this example is structural, not a catalog recommendation: + +```json +{ + "modelAliases": { + "coding": [ + {"provider": "openai", "model": "available-model-id"}, + {"provider": "xai", "model": "available-model-id"} + ] + }, + "factory": {"model": "@coding", "worker_model": "@coding"} +} +``` + +Use only accounts/providers the user intends to consume. An alias can hold one +provider/model object or an ordered nonempty array. Select it with `@coding`. +For ordinary invocation, prefer explicit `--model` with a listed selector; +for persistent Factory defaults use `factory.model` and optional +`factory.worker_model`. Unset worker model inherits the active overseer model. + +Personal model precedence is gitignored `/archdev.local.json` → +`~/.archdev/archdev.json` → checked-in `/archdev.json`. Repository policy +has project-first precedence; provider accounts are user-owned. Keep model +preferences separate from credentials. Run `archdev --json check` after edits +and inspect the model in a new invocation. + +Fallback starts at the first candidate each turn. It can advance on auth, +usage, rate-limit, lookup, and transport/backend failures before output starts. +Once streaming output begins, failure stops the turn rather than replaying it +on another model. Invalid prompts and cancellation also stop. A fallback list +is not evidence every candidate works; setup requires at least one available +candidate in each configured agent role. + +## 7. Troubleshoot the owning boundary + +1. **ArchDev says unauthenticated:** check `auth status/login`, not provider + OAuth alone. +2. **Wrong provider/model:** inspect the exact selector, effective aliases, + Factory role override, and workflow node model. Do not change all defaults + to repair one invocation. +3. **OAuth appears stored but calls fail:** inspect expiry, exhaustion and the + actual provider error. Follow the fresh-login caveat above when reauthentication is required; + use device code when browser callbacks cannot reach the login process. +4. **Catalog lists a BYO model but request fails:** bundled availability does + not establish account access; check credentials/capacity and current CLI + version. Do not repeatedly switch endpoints without user intent. +5. **All subscriptions exhausted:** report the cooldown/capacity limitation. + Use an already-authorized fallback or wait; do not silently bill an API key + or the platform router as a recovery shortcut. diff --git a/skills/agents/scripts/bootstrap.ps1 b/skills/agents/scripts/bootstrap.ps1 new file mode 100644 index 0000000..b94ab7e --- /dev/null +++ b/skills/agents/scripts/bootstrap.ps1 @@ -0,0 +1,51 @@ +$ErrorActionPreference = "Stop" + +function Resolve-ArchDevPath([string]$Candidate) { + return (Resolve-Path -LiteralPath $Candidate).Path +} + +function Install-ArchDev { + $installerUrl = if ($env:ARCHDEV_INSTALLER_URL) { + $env:ARCHDEV_INSTALLER_URL + } else { + "https://raw.githubusercontent.com/ArchAstro/archdev/7c16002d66a004b13812cf675042cb1c50fbf6df/install.ps1" + } + $installDir = if ($env:ARCHDEV_INSTALL_DIR) { + $env:ARCHDEV_INSTALL_DIR + } else { + Join-Path $env:LOCALAPPDATA "ArchDev\bin" + } + $installerPath = Join-Path ([IO.Path]::GetTempPath()) ("archdev-install-" + [Guid]::NewGuid().ToString("N") + ".ps1") + try { + Invoke-WebRequest -Uri $installerUrl -OutFile $installerPath + $env:ARCHDEV_INSTALL_DIR = $installDir + & $installerPath -SkipPathUpdate *> $null + if (-not $?) { throw "ArchDev installer failed" } + } finally { + Remove-Item $installerPath -Force -ErrorAction SilentlyContinue + } + return (Resolve-ArchDevPath (Join-Path $installDir "archdev.exe")) +} + +$existing = Get-Command archdev -ErrorAction SilentlyContinue +$archdev = if ($existing) { Resolve-ArchDevPath $existing.Source } else { Install-ArchDev } + +function Test-Agents([string]$Binary) { + $helpText = & $Binary agents run --help 2>$null + if ($LASTEXITCODE -ne 0 -or (($helpText -join "`n") -notmatch "(?m)^Usage: archdev agents run ")) { return $false } + $helpText = & $Binary settings provider models --help 2>$null + return ($LASTEXITCODE -eq 0 -and (($helpText -join "`n") -match "(?m)^Usage: archdev settings provider models ")) +} + +if (-not (Test-Agents $archdev)) { + [Console]::Error.WriteLine("Updating ArchDev because this version lacks Agents and provider commands.") + $archdev = Install-ArchDev +} + +if (-not (Test-Path -LiteralPath $archdev -PathType Leaf)) { + throw "ArchDev installer did not create an executable at $archdev" +} +& $archdev --version *> $null +if ($LASTEXITCODE -ne 0) { throw "ArchDev version verification failed" } +if (-not (Test-Agents $archdev)) { throw "Installed ArchDev does not provide Agents and provider commands" } +Write-Output $archdev diff --git a/skills/agents/scripts/bootstrap.sh b/skills/agents/scripts/bootstrap.sh new file mode 100755 index 0000000..60e7d4b --- /dev/null +++ b/skills/agents/scripts/bootstrap.sh @@ -0,0 +1,53 @@ +#!/usr/bin/env bash + +set -euo pipefail + +installer_revision="7c16002d66a004b13812cf675042cb1c50fbf6df" +installer_url="${ARCHDEV_INSTALLER_URL:-https://raw.githubusercontent.com/ArchAstro/archdev/${installer_revision}/install.sh}" +install_dir="${ARCHDEV_INSTALL_DIR:-$HOME/.local/bin}" + +absolute_path() { + local candidate="$1" + local directory + directory="$(cd -P "$(dirname "$candidate")" && pwd)" + printf '%s/%s\n' "$directory" "$(basename "$candidate")" +} + +install_archdev() { + curl --fail --silent --show-error --location "$installer_url" | + ARCHDEV_INSTALL_DIR="$install_dir" \ + ARCHDEV_INSTALL_SKIP_PATH_UPDATE=true \ + ARCHDEV_INSTALL_SKIP_COMPLETIONS=true \ + bash >&2 +} + +candidate="$(command -v archdev 2>/dev/null || true)" +if [[ -n "$candidate" ]]; then + executable="$(absolute_path "$candidate")" +else + install_archdev + executable="$(absolute_path "$install_dir/archdev")" +fi + +supports_agents() { + "$1" agents run --help 2>/dev/null | grep -Fq "Usage: archdev agents run " && + "$1" settings provider models --help 2>/dev/null | grep -Fq "Usage: archdev settings provider models " +} + +if ! supports_agents "$executable"; then + printf 'Updating ArchDev because this version lacks Agents and provider commands.\n' >&2 + install_archdev + executable="$(absolute_path "$install_dir/archdev")" +fi + +[[ -x "$executable" ]] || { + printf 'ArchDev installer did not create an executable at %s\n' "$executable" >&2 + exit 1 +} + +"$executable" --version >&2 +supports_agents "$executable" || { + printf 'Installed ArchDev does not provide Agents and provider commands.\n' >&2 + exit 1 +} +printf '%s\n' "$executable" diff --git a/skills/jobs/SKILL.md b/skills/jobs/SKILL.md index 18df803..204009e 100644 --- a/skills/jobs/SKILL.md +++ b/skills/jobs/SKILL.md @@ -9,7 +9,10 @@ Drive the operation through the public ArchDev CLI, from repository setup to verified job results. The shared local daemon owns scheduling, worktrees, attempts, and PR automation. Use the canonical `jobs` commands below; older `init`, `push`, `sync`, and `daemon` spellings are compatibility aliases. -This skill does not require a separate orchestration script or Factory. +Tasks are optional. Any committed branch can enter its configured pipeline: +ordinary bug fixes, experiments, maintenance, or work planned outside ArchDev. +Do not create a Task or DAG just to submit code. This skill does not require +a separate orchestration script or Factory. ## 1. Bootstrap and choose the operation @@ -103,6 +106,17 @@ asking for the same approval. ## 3. Submit work and follow its lifecycle +`jobs repo submit` is the canonical replacement for `archdev push`; both use +the same private-push implementation. The ordinary path needs no Task: + +```sh +"$archdev" jobs repo submit +``` + +This submits the current committed branch to its configured branch-update +pipeline. `--task ` only attaches an existing Task association; it is +not a prerequisite for submission, pipeline execution, or automatic publication. + Choose the entry point by the result the user wants: | Intent | Command | Behavior | @@ -117,8 +131,8 @@ Choose the entry point by the result the user wants: not upload your unsaved working tree. Ordinary private submission may rebase the checkout onto current upstream main. Surface that consequence if the user has constrained rebasing; do not bypass it with internal Factory flags. -2. Submit once. Use `jobs repo submit --task ` when delivering an - existing Task; repeat `--task` for several. Retain the actual submitted SHA +2. Submit once with `jobs repo submit`. Optionally add `--task ` when + delivering an existing Task; repeat `--task` for several. Retain the actual submitted SHA and returned job identity, or find it in `jobs list` by project/ref/SHA. Do not infer success from the private ref moving alone. 3. Read `jobs show ` and `jobs logs `. Follow queued → running → terminal diff --git a/tests/agents-skill.sh b/tests/agents-skill.sh new file mode 100755 index 0000000..4b00b56 --- /dev/null +++ b/tests/agents-skill.sh @@ -0,0 +1,64 @@ +#!/usr/bin/env bash +set -euo pipefail +repo="$(cd -P "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" +root="$(mktemp -d)" +root="$(cd -P "$root" && pwd)" +trap 'rm -rf "$root"' EXIT +mkdir -p "$root/home" "$root/project" "$root/installer" +git -C "$root/project" init -q + +# Cross the real skill-manager boundary in both supported installation scopes. +HOME="$root/home" npx --yes skills add "$repo" --global --skill agents --agent codex --yes --copy >/dev/null +test -x "$root/home/.agents/skills/agents/scripts/bootstrap.sh" +( + cd "$root/project" + HOME="$root/home" npx --yes skills add "$repo" --skill agents --agent codex --yes --copy >/dev/null +) +bootstrap="$root/project/.agents/skills/agents/scripts/bootstrap.sh" +test -x "$bootstrap" +test -f "$root/project/.agents/skills/agents/references/providers.md" +test -f "$root/project/.agents/skills/agents/references/execution.md" + +# Substitute only the release boundary: no real installation or account writes. +cat > "$root/installer/install.sh" <<'INSTALLER' +set -eu +printf 'install\n' >> "$ARCHDEV_TEST_INSTALL_LOG" +mkdir -p "$ARCHDEV_INSTALL_DIR" +cat > "$ARCHDEV_INSTALL_DIR/archdev" <<'CLI' +#!/usr/bin/env bash +if [[ "$*" == '--version' ]]; then echo fixture; exit 0; fi +if [[ "$*" == 'agents run --help' ]]; then echo 'Usage: archdev agents run [options] [prompt]'; exit 0; fi +if [[ "$*" == 'settings provider models --help' ]]; then echo 'Usage: archdev settings provider models [options] '; exit 0; fi +exit 1 +CLI +chmod +x "$ARCHDEV_INSTALL_DIR/archdev" +INSTALLER +export ARCHDEV_INSTALLER_URL="file://$root/installer/install.sh" +export ARCHDEV_INSTALL_DIR="$root/bin" +export ARCHDEV_TEST_INSTALL_LOG="$root/installs" + +# A cold install returns one absolute executable path despite PATH omitting it. +binary="$(HOME="$root/home" PATH=/usr/bin:/bin bash "$bootstrap")" +test "$binary" = "$root/bin/archdev" +"$binary" agents run --help +test "$(wc -l < "$root/installs" | tr -d ' ')" = 1 + +# A capable PATH installation must be reused without contacting the installer. +reused="$(PATH="$root/bin:/usr/bin:/bin" bash "$bootstrap")" +test "$reused" = "$binary" +test "$(wc -l < "$root/installs" | tr -d ' ')" = 1 + +# An older CLI is upgraded once; its replacement must satisfy the Agents/provider probes. +printf '#!/usr/bin/env bash\necho "Usage: archdev [options]"\nexit 0\n' > "$binary" +updated="$(PATH="$root/bin:/usr/bin:/bin" bash "$bootstrap")" +test "$updated" = "$binary" +test "$(wc -l < "$root/installs" | tr -d ' ')" = 2 +"$updated" agents run --help + +# An installer failure must fail bootstrap rather than emit a usable-looking path. +if ARCHDEV_INSTALLER_URL="file://$root/missing" PATH=/usr/bin:/bin bash "$bootstrap" > "$root/failed-output" 2>/dev/null; then + echo 'Expected installer failure' >&2 + exit 1 +fi +test ! -s "$root/failed-output" +printf 'Agents skill packages in both scopes; bootstrap handles cold, current, outdated, and failed installs.\n'