Skip to content

chore(agents): refactor contributor instructions and workflows #3980

Description

@johntmyers

User Story

I am an OpenShell maintainer using contributor agents to develop and maintain OpenShell. I directly encounter agents following duplicated procedural guidance and referring to outdated workflow labels. I need the repository instructions and contributor skills to describe the current contribution process consistently.

Problem Statement

AGENTS.md repeats issue, PR, and label procedures that also live in contributor skills. Several skills rely on a fixed agent:* queue and enumerate label names that can drift from the repository. Issue and PR guidance also needs to capture the maintainers' requirements for first-hand OpenShell use cases, OpenShell-only reproduction, reviewable UX proposals, extension alternatives, and an issue closed by every PR.

Impact / Why This Matters

Agents act on stale workflow assumptions, and maintainers must correct their issue and PR drafts. Repeating corrections in individual chats does not keep the repository guidance consistent or prevent future agents from following the same outdated instructions.

Description

Focus AGENTS.md on coding conventions. Put procedural contribution guidance in the relevant skills and CONTRIBUTING.md. Use current GitHub state:* label descriptions, assignments, and comments to infer workflow stages and authorization without hard-coding label names in skills. Align issue and PR templates with the updated conventions, remove stale workflow references, and keep documentation instructions focused on what users need to know.

Definition of Done

  • AGENTS.md removes the duplicated workflow, issue/PR, vouch, and plans sections while retaining repository coding conventions.
  • Contributor skills describe triage, technical validation, and human acceptance using current state:* labels, without a fixed label list or dependence on an agent:* queue.
  • Issue guidance requires a first-hand OpenShell use case and asks the human operator when that context is missing.
  • Bug reproduction relies on OpenShell deployments without installing third-party tools solely to reproduce a report.
  • Proposed configuration, CLI, SDK, and other UX changes include notional examples for human review.
  • Alternatives consider applicable extension points and prefer an extension that satisfies the use case; running another service alone does not disqualify it.
  • Every PR closes an issue covering its scope. Multi-PR work has a separate closable issue per PR, with an optional tracking issue.
  • Published documentation guidance calls for minimal necessary changes and avoids duplicate explanations or internal details without user impact.
  • CONTRIBUTING.md, templates, README pointers, stale handling, and maintenance checks agree with these conventions.
  • Verification guidance and PR checklists select checks for affected components and dependencies; unrelated Rust or SDK suites and full repository CI are not blanket prerequisites for guidance or template changes.

Context

This is a scoped maintainer-requested repository workflow refactor. It changes contributor guidance and templates rather than OpenShell runtime behavior.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    state:acceptedA maintainer decided OpenShell should pursue this issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions