Skip to content

Expand STANDARDS.md for Base architecture and Python CLIs #412

@codeforester

Description

@codeforester

STANDARDS.md is still mostly inherited from the earlier Bash-focused version of Base. Current Base has a clearer layered architecture and Python CLI conventions that should be captured as contributor standards.

Scope:

  1. Keep the existing Bash standards, but make them part of a broader Base contributor standard.
  2. Add Base architecture/layering standards: basectl control plane, Bash bootstrap/runtime layer, Python manifest/project layer, base-wrapper, public bin/ surface, and project venv boundaries.
  3. Add Python standards: PEP 8-oriented style, from __future__ import annotations, pathlib.Path, dataclasses where useful, explicit main(argv) -> int, base_cli.App, ctx.log, structured JSON through json.dumps, no import-time side effects beyond command registration.
  4. Make it explicit that Python CLIs intended for direct execution should use base-wrapper in the shebang so they run in the selected project virtual environment.
  5. Add a short “where does this code belong?” table to guide future contributors.
  6. Add CLI behavior, manifest/artifact, testing, documentation, and GitHub workflow standards at a concise level with links to deeper docs.

Acceptance criteria:

  • STANDARDS.md covers Bash, Python, CLI behavior, layering, manifests, testing, docs, and GitHub workflow.
  • The base-wrapper shebang convention for Python CLIs is explicit.
  • The document remains readable and normative rather than becoming a long design essay.
  • The PR is documentation-only unless a tiny supporting reference update is needed.

Metadata

Metadata

Assignees

Projects

No projects

Milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions