Skip to content

Onboarding: point users at the existing agentwire dev helper session + make it carry the contributor role by default #619

Description

@dotdevdotdev

Premise correction (read first)

The original issue asked to make agentwire dev "a first-class, discoverable CLI command." That command already exists and is already discoverable in agentwire --help. This issue is therefore not about creating a command — it's about closing the onboarding gap (users don't know to run it) and changing the default role it carries.

Verified current state

  • agentwire dev is a real subcommand. Registrar: agentwire/system_cli.py:558-573; implementation: cmd_dev at agentwire/system_cli.py:42-89.
  • It already appears in agentwire --help as: dev Start/attach to dev agentwire session.
  • What it does today (cmd_dev): start-or-attach a tmux session named agentwire, working dir = get_source_dir() (default ~/projects/agentwire-dev, agentwire/core.py:515-522), session type {agent}-bypass (full permissions), roles = agentwire + soul (system_cli.py:57), not the contributor role.
  • The contributor role does not exist yet — it's defined by Add a bundled contributor role (onboarding + issue-filing + fork/PR coaching) and make it the helper-session default; owner overrides locally #620 (still open). agentwire/roles/ currently has agentwire.md, no contributor.md.
  • The first-run flow does not mention the helper session. agentwire init → onboarding "Next steps" (agentwire/onboarding.py:468-475) only points at agentwire portal start, the portal URL, and agentwire init --assisted (which spawns a throwaway agentwire-init/init-role session, onboarding.py:490-498). README Quick Start and docs/wiki/quickstart.md never mention agentwire dev either.
  • The command-palette "open or start a project session" idea the original issue floated as a nice-to-have already ships for the user's own projects: New idea / New session / Open session actions exist (agentwire/static/js/command-palette.js:38-41). It does not surface the agentwire helper session, which is a separate thing.

Goal

Make the agentwire dev helper session a visible front door for new users, and make it carry the contributor role (#620) by default so a non-owner who runs it gets a persona that can install/configure, orchestrate their own projects, explain the system, and help them file issues or fork.

Two pieces of real work:

  1. Default role: switch the role cmd_dev injects from agentwire to contributor (per Add a bundled contributor role (onboarding + issue-filing + fork/PR coaching) and make it the helper-session default; owner overrides locally #620). Blocked on Add a bundled contributor role (onboarding + issue-filing + fork/PR coaching) and make it the helper-session default; owner overrides locally #620 landing the role.
  2. Onboarding discoverability: tell users the helper session exists, at the moments they'd look — first-run output, README/quickstart, and (optionally) a portal "Start here" affordance.

Scope

In scope:

Out of scope / nice-to-have:

  • A dedicated portal "Start here / start the agentwire helper" command-palette entry or affordance. The palette already has project-session actions (command-palette.js:38-41); a helper-session entry could ride along but isn't required.
  • Renaming dev to something more user-facing (e.g. it reads as developer-only). The original issue said "or equivalently named" — flag this as an open question, but renaming a shipped subcommand is a bigger, separate decision; default to keeping dev and improving the surrounding copy.

Approach

  1. (after Add a bundled contributor role (onboarding + issue-filing + fork/PR coaching) and make it the helper-session default; owner overrides locally #620 merges) In cmd_dev (agentwire/system_cli.py:42-89), replace the hard-coded ["agentwire"] role list (line 57) with the contributor role. Keep inject_soul(...) wrapping. Confirm load_roles resolves contributor from agentwire/roles/contributor.md.
  2. First-run copy in agentwire/onboarding.py (the skip_session "Next steps" branch, lines 468-475): add a step like agentwire dev with a short gloss. This is the highest-leverage onboarding surface — it's what every agentwire init run prints.
  3. README + docs/wiki/quickstart.md: add agentwire dev to the documented getting-started path with a one-sentence "what it's for."
  4. (optional) Portal affordance — only if cheap; the palette infra already exists.

Dependencies

Verification

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions