--- name: starbard-coding-standard description: Mandatory Starbard Standard compliance check for all Python code. Enforces SOLID principles, explicit typing, separation of concerns, domain exceptions, testability, and Starbard architecture conventions. Use when generating, reviewing, or refactoring Python code, agents, skills, prompts, services, workflows, and infrastructure adapters in the Starbard ecosystem. Keywords - starbard standard, code review, python standard, SOLID, coding conventions, compliance check, review checklist, architecture check, code quality, starbard code. argument-hint: "[artifact-type: agent|skill|prompt|service|workflow|adapter] [file or description]" --- # Starbard Coding Standard Mandatory governing specification for all Python code in the Starbard ecosystem. Every artifact — agent, skill, service, prompt, workflow, adapter — must pass this check before it is considered done. ## When to Use - Before finalising any generated or refactored Python code - When reviewing a PR or code block for Starbard compliance - When starting a new component (use as a pre-generation checklist) - When auditing existing code against the standard ## When NOT to Use - Non-Python code (JS, shell, YAML) — apply general SOLID principles manually - Trivial one-liners or config-only files where the full check is disproportionate ## Governing Rule > You are not merely writing Python code. You are shaping and preserving the **Starbard Standard**. Every artifact you generate must strengthen coherence, maintainability, architectural integrity, readability, extensibility, and trust in the codebase. --- ## Mandatory Review Process Execute every step in sequence. Do not skip steps. Report pass/fail at each gate. --- ### Step 1 — Classify the Artifact Identify what is being checked: | Type | Examples | |------|---------| | `agent` | orchestrating component with a role | | `skill` | composable isolated capability | | `prompt` | template, builder, context model | | `service` | domain or infrastructure service | | `workflow` | multi-step orchestration | | `adapter` | external provider/SDK integration | | `model` | dataclass, Pydantic model, value object | | `command` | Click CLI command handler | The artifact type determines which component-specific rules apply in Step 8. Load [references/component-patterns.md](references/component-patterns.md) when needed. --- ### Step 2 — Architecture Gate (SOLID) Verify each principle. Mark ✓ or ✗. - [ ] **SRP** — Each class/function has one reason to change. No god classes or god functions. - [ ] **OCP** — Behaviour extended via composition/strategy/registry, not growing switch trees. - [ ] **LSP** — Subtypes/implementations behave consistently with their abstraction. - [ ] **ISP** — Interfaces are narrow. Clients do not depend on methods they don't need. - [ ] **DIP** — High-level policy depends on abstractions, not concrete implementations. **Fail condition:** Any unchecked item without a justified exception → block and revise. --- ### Step 3 — Code Style Gate - [ ] Type annotations present on all public functions, methods, return types, class attributes. - [ ] `dataclass` used where appropriate instead of plain dicts as domain models. - [ ] `Enum` used for constrained symbolic values. - [ ] `Protocol` or ABC used for contracts/interfaces. - [ ] `pathlib.Path` used instead of raw string paths. - [ ] Context managers used for resources. - [ ] Names express intent, not implementation trivia (no `Helper`, `Manager`, `Utils` unless justified). - [ ] Functions are focused — one conceptual job; split if multiple steps needed. - [ ] Classes are cohesive — good roles: builder, validator, service, parser, adapter, orchestrator, registry. **Fail condition:** Untyped public APIs, dict-as-domain-model, god function > ~50 lines doing unrelated things. --- ### Step 4 — Separation of Concerns Gate Verify these concerns are not tangled together: - [ ] Prompt construction is **not** mixed with API transport or result parsing. - [ ] Provider/SDK-specific code is isolated behind an interface or adapter. - [ ] Business rules are **not** inside transport layers or CLI handlers. - [ ] File system / network IO is **not** inside pure domain logic. - [ ] Configuration is **not** hardcoded inside business logic. - [ ] CLI commands are thin (Click parsing + presentation only; orchestration lives elsewhere). Load [references/standard.md#4-project-structure-rules](references/standard.md) for layering guidance when needed. --- ### Step 5 — Error Handling Gate - [ ] Domain-appropriate exception classes used (not bare `Exception`). - [ ] `except` clauses are narrow — only catching what can be handled. - [ ] No silent fallbacks for meaningful failures. - [ ] Context added when re-raising across layers. - [ ] Input validation happens at system boundaries. Check [references/standard.md#6-error-handling-standard](references/standard.md) for examples. --- ### Step 6 — Configuration Gate - [ ] No magic values / hardcoded environment-specific strings in business logic. - [ ] Config represented with typed structures (dataclass, Pydantic) where appropriate. - [ ] Safe defaults provided; critical required settings are not hidden. --- ### Step 7 — Testability Gate - [ ] Dependencies are injected (constructor injection preferred) — not instantiated inside functions. - [ ] No hidden global mutable state. - [ ] Pure domain logic has no IO dependencies. - [ ] External providers mockable at architectural boundaries. --- ### Step 8 — Anti-Pattern Scan Load [references/anti-patterns.md](references/anti-patterns.md) and verify none of the listed anti-patterns are present. **Automatic fail triggers:** - Broad `except Exception:` without boundary-translation justification - Untyped dicts used as primary domain models - Prompt text scattered across orchestration logic - Provider SDK code leaking out of its adapter - Boolean parameter overloads obscuring intent --- ### Step 9 — Component-Specific Gate Load [references/component-patterns.md](references/component-patterns.md) for the artifact type identified in Step 1. Apply the production checklist for that type: - **Agent:** typed config, clear execution entrypoint, provider abstraction, structured result model - **Skill:** explicit input/output schemas, isolated execution, no hidden dependencies - **Prompt:** template/builder, context model, rendering separate from transport - **Workflow:** explicit steps, injected collaborators, typed intermediate models - **Adapter:** abstraction boundary, translation layer, isolated SDK usage --- ### Step 10 — Final Verdict Summarise results: ``` PASS — All gates clear. Code meets Starbard Standard. WARN — Minor issues noted. List them. Code can proceed with documented caveats. FAIL — Gate(s) failed. List each failure with file/line/reason. Revise before proceeding. ``` If **FAIL**, revise the code and re-run from the failed gate. --- ## Decision Heuristics (when uncertain) Apply in priority order: 1. Correctness 2. Clarity 3. Maintainability 4. Testability 5. Architectural consistency 6. Extensibility 7. Conciseness 8. DRY (last — accept duplication if it materially improves clarity) --- ## References - [Full Starbard Standard Specification](references/standard.md) - [Review Checklist (quick reference)](references/review-checklist.md) - [Anti-Patterns Catalogue](references/anti-patterns.md) - [Component Generation Patterns](references/component-patterns.md)