Skip to content

[feat] Health checks for branches created by teamai push #776

Description

@shusun-lu

Summary

When teamai is used with a Git host whose provider cannot open a PR/MR (a plain ssh:// remote, for
example), teamai push leaves new resources on teamai/push/<user>/<timestamp> with no signal about
whether they are usable. I would like a read-only check that tells the reviewer what is wrong before
the branch is merged by hand.

This is the "Add Skill health checks" / "validation" pair from the roadmap (#647), and it complements
#663 (pushed branches end up with no PR and no visible signal).

What I propose (read-only, no writes)

teamai review <branch> — or a flag on an existing command, see "Open questions" — reporting findings
per branch with three levels: fail (must fix), warn (needs a human decision), info (context):

  • structure — SKILL.md at the first level (skills/<ns>/<name>/SKILL.md); resource declared on
    the axis that namespaces it; namespace declared by some role/project on that axis
  • naming — invalid characters; frontmatter name vs directory name
  • duplicates — the same resource name in two namespaces that can be active together; this makes
    pull fail, so it is worth catching before merge
  • format — frontmatter present, description explains when to use the skill
  • leaks — credential shapes and internal addresses, reusing utils/redact

A machine-readable mode (--json) matters to me so CI can consume the same result.

Non-goals

  • No auto-merge. I am not proposing a --direct-style path to the default branch; merging stays a
    human decision. A "publish" step can be a separate discussion if it is wanted at all.
  • No second implementation of existing logic. The checks should import loadRolesManifest /
    loadProjectsManifest, NAMESPACE_AXIS, parseAgentYaml, scanTeamForPull and utils/redact.
    I am happy to export what is currently module-private (e.g. the secret pattern list) rather than
    duplicating it.
  • Conventions stay off by default. A namespace-prefix rule or a denylist of names would be opt-in
    configuration, not default behaviour.

Open questions

  1. Entry point: extend teamai review, or add a flag to push / status?
  2. Which checks belong in the default fail set? My suggestion: missing SKILL.md, frontmatter
    missing or name mismatch, cross-namespace duplicate names, namespace not declared anywhere, and a
    credential hit. Everything else warn.
  3. Is a merge / "publish" step for these branches in scope for the CLI, now or later?

I already have a working local implementation and can send a PR in whatever shape you prefer, including
a real-CLI end-to-end record with it.

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

    enhancementNew feature or request

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions