agw

name	agw
description	Drive AGW workspace setup, diagnosis, refresh, lifecycle, and troubleshooting through the up-to-date local `agw` CLI. Use when a user asks an agent to create, prepare, apply, update, refresh, rebuild, start, stop, attach to, inspect, diagnose, or repair an AGW workspace, especially when project-specific Docker/container details are uncertain or personal base-environment guidance changed.

AGW

Use the repository's current CLI as the source of truth. Do not duplicate or invent AGW behavior from memory.

The human interface is natural language. Users should be able to say things like "set up AGW here", "refresh this workspace with my new base prompt", or "start my workspace". The agent uses JSON and agent-oriented CLI output internally.

First Steps

1. Confirm the CLI surface before acting:
   • Prefer go run ./cmd/agw --help from this repository when working on AGW itself.
   • Use agw --help only when intentionally targeting the installed binary.
   • Read command-specific help before using less familiar commands.
2. Read README.md when workflow context is needed.
3. Run agw doctor <workspace> --json or agw doctor --all --json before lifecycle decisions when a workspace already exists.
4. Configured workspaceRoot may use ~/, $HOME, or ${HOME}; the CLI expands and cleans this path when loading config. Legacy configs with one workspaceRoots entry load as workspaceRoot.

Operating Model

• Treat doctor --json output as the state machine and follow its next action unless there is a clear reason not to.
• Default to standalone sidecar mode. Target projects do not need Docker files, Compose files, devcontainer files, or external networks.
• Treat detected project Docker files as hints only.
• Add external networks only when the user explicitly wants the sidecar to reach already-running project services.
• Do not auto-detect or manage target project services unless the user specifically asks or projects[].lifecycle.start / projects[].lifecycle.stop is explicitly configured.
• Do not edit files inside target repositories as part of workspace preparation. AGW owns its workspace files.
• Generate workspace files in a temporary directory outside the AGW workspace directory before workspace apply; apply rejects generated directories that overlap the workspace.
• workspace apply preflights generated files and applies them transactionally; if applying generated files fails, treat the prior workspace files as the intended state and report the apply error.
• If global config includes baseEnvironment.image, prefer that image as the workspace Dockerfile FROM by default, but treat it as a preference rather than a hard requirement when project constraints need another base.
• Do not change Compose image names as a workaround for stale images. Diagnose stale containers/images, then rebuild or remove the old image intentionally.

Common Flow

For a single-project workspace, when the user asks the agent to create or set up an AGW workspace, prefer:

agw workspace new --from /path/to/project
agw workspace prepare <workspace> --agent-json
# Generate workspace files in a temporary directory outside the workspace.
agw workspace apply <workspace> <temp-generated-dir>
agw start <workspace>

workspace new --from may suggest the workspace directory from configured path mappings. For example, a project under ~/ghq/github.com/kenfdev/agw with a mapping from ~/ghq to workspaces should become <AGW_ROOT>/workspaces/github.com/kenfdev/agw. Treat this as a default suggestion, not a user intent override.

For a workspace that groups multiple projects, do not rely on the single project --from default. Ask for or infer a meaningful group id and workspace directory, then create the definition explicitly with repeated --project flags:

agw workspace new \
  --root <AGW_ROOT> \
  --id <workspace-id> \
  --name <workspace-name> \
  --workspace-dir workspaces/<chosen-group-path> \
  --project api=/path/to/api:/workspace/api \
  --project web=/path/to/web:/workspace/web \
  --service dev \
  --workdir /workspace

When the user has not specified a group directory, propose one based on the shared source-root-relative path, organization, product, or repo family, and make clear it can be changed with --workspace-dir. Preserve each target project's host path; do not move, rename, or edit target repositories.

For an existing workspace lifecycle request, prefer:

agw doctor <workspace> --json
agw start <workspace>
agw restart <workspace> [--build] [--force-recreate]
agw stop <workspace>

agw start <workspace> starts the workspace without attaching. Use agw attach <workspace> only when the user explicitly wants an interactive shell in the sidecar. Use agw restart <workspace> to stop then start the workspace without attaching. Add --build, --force-recreate, or both when the user explicitly asks to rebuild or recreate containers.

In agw, press t to start the selected workspace without attaching using the same readiness checks and lifecycle.start handling as agw start. Press R to open a confirmation prompt for restart, force recreate, build, or build plus force recreate. Press tab to move focus between workspaces and the configured base image summary when a base image exists. Press b to open a confirmation prompt before building the focused workspace or base image; press y in that prompt to run the build. TUI start, restart, and build actions stream lifecycle output into the TUI log area as it arrives instead of writing raw Docker output over the terminal layout.

If a reusable base environment image is configured under baseEnvironment, use agw base status to inspect whether it exists and how old Docker reports it is. Use agw base build only when the user asks to build or refresh that shared base image.

If a workspace agw.yaml contains lifecycle.start, agw start runs that shell command from the workspace directory instead of the default docker compose up -d startup step. This is intended for wrappers such as:

lifecycle:
  start: op run --env-file=.env.1password -- docker compose up -d

If projects have explicit lifecycle commands, agw start runs each projects[].lifecycle.start from that project's hostPath in project order before readiness checks and before starting the AGW sidecar. This lets project startup create required external Docker networks before AGW validates and joins them. agw start fails immediately if a project start command fails. agw stop stops the AGW sidecar first, then runs each projects[].lifecycle.stop from the project hostPath in reverse project order. Project stop failures do not prevent later project stop commands from running, but agw stop returns an error if any configured project stop command fails.

projects:
  - name: api
    hostPath: /path/to/api
    containerPath: /workspace/api
    lifecycle:
      start: docker compose up -d
      stop: docker compose down

Compose-first workspace definitions may omit projects[].containerPath and networks.attach when compose.yaml already declares the sidecar service volumes and external networks. In that mode, treat Compose as the source of truth for container runtime shape: doctor and workspace apply infer project container paths from service volume mounts that match projects[].hostPath, and doctor checks external networks attached to the sidecar service. compose.service is accepted as the sidecar service name; existing container.service remains supported for generated/spec-first workspaces. Use explicit containerPath only when a project host path has multiple mounts or AGW must validate one exact container target.

For an existing workspace that should be refreshed from changed global base-environment guidance, dotfiles guidance, tool defaults, or generated workspace files:

agw doctor <workspace> --json
agw workspace prepare <workspace> --agent-json
# Generate updated workspace files from the prompt, preserving project-specific choices.
agw workspace apply <workspace> <temp-generated-dir>

After applying, explain whether a rebuild or restart is needed. Only run agw start, agw restart, agw stop, agw up, agw down, or Docker lifecycle commands when the user asked for that lifecycle action or it is clearly required and low risk.

Use agw workspace network add <workspace> <network> only after confirming that an external Docker network is intended.

Sidecar Generation Guidance

When generating Docker/Compose files from workspace prepare --agent-json:

• Prefer the user's global base-environment guidance when present; do not silently omit mandatory personal tooling such as Tailscale or dotfiles.
• When the agent JSON includes baseEnvironment.image, prefer FROM <image> as the workspace Dockerfile base. This is not mandatory; if the project needs an incompatible image, use the project-appropriate base and explain why in generated workspace documentation or comments.
• Project bind mount sources in generated Compose may use absolute paths, ~/, $HOME, or ${HOME}; workspace apply and doctor expand and clean those sources when checking them against projects.hostPath. If projects[].containerPath is omitted, the service volume target matching projects[].hostPath is inferred from Compose.
• Project file snapshots in workspace prepare --agent-json may be truncated when source files are large. Treat a truncation note as a signal to inspect the source file directly only when the omitted content is needed for the workspace design.
• For Ubuntu 24.04 based sidecars, use the existing ubuntu user unless there is a clear project reason to create another user. Do not unconditionally create UID/GID 1000 users; ubuntu:24.04 already provides ubuntu:1000.
• If Tailscale is installed through the user's tools feature, Compose must also run the Tailscale entrypoint and provide runtime requirements: TS_AUTHKEY or TS_AUTH_KEY, /dev/net/tun, NET_ADMIN, MKNOD, and persistent /var/lib/tailscale state.
• Prefer a workspace-local .env.1password for Tailscale auth key references when the user's base guidance uses 1Password. Do not write real auth keys into generated files.
• If workspace startup needs secrets or another wrapper, set lifecycle.start in agw.yaml to the exact one-line command AGW should run from the workspace directory.
• If project-owned Docker services should start or stop with AGW, set projects[].lifecycle.start and projects[].lifecycle.stop to exact one-line commands AGW should run from each project host path. Do not add these commands based only on detected Docker files without user intent.
• Tailscale SSH authorization is controlled by tailnet policy, not container authorized_keys. If SSH fails with "tailnet policy does not permit", inspect tailscale status --json, node tags, requested login user, and the tailnet ssh ACL/grants.
• If Docker reports an entrypoint or binary missing after Compose changes, suspect a stale image or unrecreated container first. Keep the image name stable, then rebuild with docker compose up -d --build --force-recreate or remove the old image/container deliberately.
• If a workspace has lifecycle.start, do not use agw start --build, agw start --force-recreate, agw restart --build, or agw restart --force-recreate; AGW cannot inject Docker flags into a custom shell command. Ask the user to update the custom lifecycle command or run the needed Docker command directly.
• Dotfiles cloned during image build need BuildKit SSH forwarding. If build fails with an empty SSH agent socket, ask the user to ensure SSH_AUTH_SOCK is set and ssh-add -l works in their terminal.

Human Request Examples

Map user intent to CLI use without teaching users to run agent-oriented flags:

• "Refresh this workspace with my latest base prompt" -> run doctor --json, render workspace prepare --agent-json, regenerate workspace files using the packet prompt, apply them, and report what changed.
• "Update my current AGW container tooling" -> treat this as a refresh from base-environment guidance unless the user names a specific tool change.
• "Make this workspace use my dotfiles/devcontainer-feature defaults" -> prepare with global base guidance included, generate files that preserve project runtime versions, apply them, then advise on rebuild/start.
• "Diagnose why this workspace will not start" -> run doctor --json, follow the reported next action, and use command-specific help before unfamiliar operations.
• "Start my workspace" -> diagnose first when state is unknown; when starting, run configured project lifecycle starts before readiness checks and before starting the AGW workspace sidecar.
• "Restart my workspace and rebuild it" -> diagnose if state is unknown, then run agw restart <workspace> --build.

Error Handling

• If doctor --json reports needs-prepare, render the agent packet with agw workspace prepare <workspace> --agent-json and produce workspace files from its prompt.
• If doctor reports needs-apply, apply generated workspace files from the chosen generated directory.
• If doctor reports a missing external network, ask the user to start the base project services, configure explicit project lifecycle commands, or remove the network selection. During agw start, configured project lifecycle starts run before this network check. Do not manage project services implicitly.
• If the installed agw binary disagrees with this repository, prefer the repository command during development and call out the difference.