Plandex · API Governance Rules

Plandex API Rules

Spectral linting rules defining API design standards and conventions for Plandex.

9 Rules error 2 warn 3 info 4
View Rules File View on GitHub

Rule Categories

plandex

Rules

warn
plandex-operation-summary-title-case
All operation summaries must use Title Case.
$.paths[*][*].summary
warn
plandex-operation-ids-camel-case
operationId must use camelCase.
$.paths[*][*].operationId
error
plandex-tags-required
Each operation must declare at least one tag drawn from the documented Plandex resource taxonomy.
$.paths[*][*]
error
plandex-bearer-auth-required
The Plandex server API uses bearer-token auth issued by the sign-in flow.
$.components.securitySchemes
warn
plandex-server-localhost-default
At least one server URL must point at the default local-mode host (http://localhost:8099) so docs reflect the self-hosted deployment.
$.servers[*].url
info
plandex-plan-id-path-param
Plan-scoped paths must use a {planId} path parameter named consistently.
$.paths[?(@property =~ /\/plans\//)]
info
plandex-branch-id-path-param
Branch-scoped paths must use a {branch} path parameter named consistently.
$.paths[?(@property =~ /\{branch\}/)]
info
plandex-resource-tag-allow-list
Operation tags should be drawn from the documented Plandex resource taxonomy.
$.paths[*][*].tags[*]
info
plandex-streaming-endpoint-naming
Streaming endpoints (tell, build, connect) should keep their canonical paths to remain compatible with the CLI/REPL.
$.paths

Spectral Ruleset

Raw ↑ 
extends: spectral:oas
rules:
  plandex-operation-summary-title-case:
    description: All operation summaries must use Title Case.
    severity: warn
    given: "$.paths[*][*].summary"
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][A-Za-z0-9]*(\\s[A-Z][A-Za-z0-9]*)*)$"

  plandex-operation-ids-camel-case:
    description: operationId must use camelCase.
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  plandex-tags-required:
    description: Each operation must declare at least one tag drawn from the documented Plandex resource taxonomy.
    severity: error
    given: "$.paths[*][*]"
    then:
      field: tags
      function: truthy

  plandex-bearer-auth-required:
    description: The Plandex server API uses bearer-token auth issued by the sign-in flow.
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: BearerAuth
      function: truthy

  plandex-server-localhost-default:
    description: At least one server URL must point at the default local-mode host (http://localhost:8099) so docs reflect the self-hosted deployment.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "(localhost:8099|api\\.plandex\\.ai)"

  plandex-plan-id-path-param:
    description: Plan-scoped paths must use a {planId} path parameter named consistently.
    severity: info
    given: "$.paths[?(@property =~ /\\/plans\\//)]"
    then:
      field: parameters
      function: truthy

  plandex-branch-id-path-param:
    description: Branch-scoped paths must use a {branch} path parameter named consistently.
    severity: info
    given: "$.paths[?(@property =~ /\\{branch\\}/)]"
    then:
      field: parameters
      function: truthy

  plandex-resource-tag-allow-list:
    description: Operation tags should be drawn from the documented Plandex resource taxonomy.
    severity: info
    given: "$.paths[*][*].tags[*]"
    then:
      function: enumeration
      functionOptions:
        values:
          - Accounts
          - Orgs
          - Users
          - Invites
          - Projects
          - Plans
          - Context
          - Conversation
          - Branches
          - Diffs
          - Settings
          - Models
          - FileMap
          - Execution
          - Health

  plandex-streaming-endpoint-naming:
    description: Streaming endpoints (tell, build, connect) should keep their canonical paths to remain compatible with the CLI/REPL.
    severity: info
    given: "$.paths"
    then:
      function: truthy