Skip to content

API & CLI Reference Manual

praetorctl CLI Commands

  • praetorctl init: Scaffolds a new .standards.yaml manifest with profiles and facets.
  • praetorctl plan: Computes the lattice supremum and performs a dry-run drift calculation.
  • praetorctl sync: Applies declarative standards to branch protections, labels, and CI.
  • praetorctl compile-context: Transpiles AGENTS.md to CLAUDE.md, Cursor rules, and Copilot.
  • praetorctl baseline: Records or verifies legacy brownfield technical debt.
  • praetorctl audit: Validates 100% compliance against the active standards baseline.
  • praetorctl compile-framework-assets --config <kit.yaml> --output <dir>: Writes a framework kit's llms.txt, llms-full.txt, <dir>/.agents/rules/<kit_name>.md and starter templates (ADR-0007 clause 5).

Framework kit assets

compile-framework-assets reads one YAML document with the keys kit_name, language, version, description, rules, skills and components (the FrameworkKitConfig fields in internal/compiler/framework_assets.go); any other key is refused. Both flags are required: --output has no default, so the fixed asset names never overwrite the working tree's own llms.txt by accident.

kit_name: example-ui-kit
language: svelte
version: 5.0.0
description: Svelte 5 component library
rules: [Use Svelte 5 runes exclusively]
skills: [a11y-debugging]
components: [Button, Modal]

kit_name names the agent rule file, so it must be one file-name component: 1-64 letters, digits, ., _ or -, starting with a letter or digit. Anything else, such as ../x or a/b, fails before any file is written (TestCompileFrameworkAssets_RejectsUnsafeKitNameBeforeWriting in internal/compiler/framework_assets_test.go).

Multi-Forge Federation

praetorctl builds only the GitHub driver; GitLab and Gitea drivers come from forge.NewForge, which only tests call.
Multi-forge federation
Text description
  • praetorctl commands: sync --remote (reconcileRemoteForge), issue reconcile (loadFleetIssues), needs epic --publish (publishEpicToForge), GitHub driver (NewGitHubDriver, REST client).
  • Tests only, no production caller: forge package tests (forge_test.go), forge.NewForge (provider switch), GitLab driver (token check only), Gitea driver (gitea or forgejo).
  • sync --remote → GitHub driver (ruleset, labels, metadata).
  • issue reconcile → GitHub driver (list, relabel, tick, close).
  • needs epic --publish → GitHub driver (list, create, link).
  • forge package tests → forge.NewForge (NewForge) → GitLab driver (gitlab).
  • forge.NewForge → Gitea driver (gitea, forgejo).
  • Scenario 1, sync --remote: sync --remote writes the branch ruleset, the label taxonomy and the repository metadata through the GitHub driver. reconcileRemoteForge checks the token, repository and origin, then calls forge.NewGitHubDriver. ReconcileProtection writes the ruleset for main and lts-* and reads it back. ReconcileLabels updates, or creates, each label from .config/labels.yaml. ReconcileRepositoryMetadata writes the declared description, homepage and missing topics, and reports visibility drift.
  • Scenario 2, issue reconcile: issue reconcile lists the issues of each selected repository, relabels the unblocked ones and runs the planning sync. loadFleetIssues builds a GitHub driver per repository and calls ListIssues. With --apply, transitionUnblocked calls AddLabels, then RemoveLabel. With --apply, ApplyPlanning re-reads each parent, ticks closed children with EditIssueBody and closes a finished epic with UpdateIssue.
  • Scenario 3, needs epic --publish: needs epic --publish creates the missing epic issues through the GitHub driver and names each child in the parent. publishEpicToForge passes the GitHub driver to needs.PublishPreMigrationEpic. PrepareIssueBatch checks the token and lists the existing issues by title. IssueBatch.Ensure calls CreateIssue only for a title the forge does not have yet. Once every child exists, linkEpicChildren writes a task-list line per child into the parent with EditIssueBody.
  • (Shortened to 2500 characters; docs/figures/forge-federation.ts holds the full content.)

praetorctl builds only the GitHub driver: sync --remote, issue reconcile and needs epic --publish call forge.NewGitHubDriver directly, and audit and plan read the live Actions state through it. forge.NewForge is internal and has no production caller, so the GitLab and Gitea drivers are reached only from tests. They check that a token is set and return ErrNotImplemented from every enforcement method and from both Actions reads.