os-knowledge

O.S. Knowledge is an operational knowledge system for agent-assisted software engineering. The repository separates distributable product assets from OSK's own development documentation.

Path	Purpose
catalog/	Canonical distributable OSK content: Skills, Roles, Profiles, and Capabilities.
blueprints/	Canonical workspace layouts for future osk init materialization.
cli/	Reserved Go CLI source root.
docs/	OSK product concepts, decisions, reports, checkpoints, and engineering history; not consumer runtime payload.
templates/	Active authoring templates.
scripts/	Reserved deterministic build, packaging, and release helpers.

Workspace Blueprint

The single alpha project-workspace overlay is documented in Workspace Blueprint. Its future-CLI source package is blueprints/default, containing thin agent entry points, project context, workspace operating guidance, an active engineering log, roadmap, and OSK-managed workspace metadata.

Alpha CLI

Build the offline standalone binary with make build; it produces dist/osk with the current catalog, pinned external-capability payloads, and blueprints embedded. Install it locally with ./install.sh; the installer configures ~/.zshrc or a Bash profile to add the OSK bin directory to PATH. Start a new terminal or source the profile it reports, then use osk -v, osk init, grouped osk list, osk install <capability-id>, and osk status. Installed canonical packages remain flat at .osk/skills/<capability-id>/; OSK retains ownership, catalog grouping, version, fingerprint, and (for external capabilities) provenance metadata in .osk/workspace.yaml. Codex, Claude Code, OpenCode, and TRAE receive small adapters rather than copied canonical packages.

Project status

Run osk status from a project directory to inspect OSK-managed filesystem state without changing the project. It reports the CLI/catalog/blueprint versions, workspace initialization, installed canonical capabilities, supported host exposure, visible external agent capabilities, and detectable OSK inconsistencies.

OSK Project Status

CLI
  version:    0.1.1
  catalog:    2
  blueprint:  0.1.3

Workspace
  root:         /work/example
  initialized:  yes

Installed capabilities
  osk-code-docs                  0.1.0

Agent exposure

  codex
    osk-code-docs                exposed

Health
  canonical OSK skills:  1
  OSK agent exposures:   1
  external capabilities: 0
  orphan adapters:       0
  missing exposures:     0
  inconsistencies:       0
  warnings:              0

installed means OSK found a canonical package below .osk/skills/. exposed means it found an OSK adapter/reference on disk for Codex, Claude Code, OpenCode, or TRAE. An external capability is visible in one of the supported project agent directories but OSK cannot deterministically associate it with an OSK canonical package; it is normal inventory, not a warning. OSK coexists with user-installed and third-party agent capabilities and does not require exclusive ownership of those directories.

TRAE projection

When TRAE is selected as an adapter target, OSK projects canonical Skills into TRAE's native project Skill directory, .trae/skills/<skill-id>/SKILL.md. The generated file is a thin reference; .osk/skills/ remains authoritative.

An explicitly adopted Role can likewise be exposed to TRAE as a native Skill wrapper. For example:

OSK_TARGETS=trae osk install --role product-architect
OSK_TARGETS=trae osk install osk-engineering-reporting

The Role wrapper tells TRAE to read the installed canonical .osk/roles/product-architect/ROLE.md contract. It is not a TRAE custom agent, does not select the IDE's initial agent, and does not alter TRAE tools or permissions. See OSK Runtime Projection v0.

Warnings identify OSK-owned state or an explicitly checked OSK invariant, such as an OSK reference whose canonical package is absent or canonical content missing from workspace metadata. Exposure and external inventory do not prove that a running agent loaded or consumed a Skill. Status does not claim stale/content equivalence because current reference adapters do not retain a comparable canonical artifact hash. osk status --json is deferred.

The first external capability is diagram-design. The release-time packager verifies and embeds its approved portable upstream payload at a pinned commit; install therefore does not clone, fetch, or require GitHub or git at user runtime. OSK preserves the external ownership boundary and validates the shipped upstream self-check when python3 is available.

Canonical Skill Catalog

The OSK-owned Skill catalog is catalog/catalog.yaml; its generation (catalog version) is independent from each Skill's SemVer. Each canonical OSK Skill is a package containing skill.yaml and SKILL.md; skill.yaml is the sole machine-readable authority and SKILL.md is the operating contract. Externally owned capabilities live separately under catalog/capabilities/ so their ownership and upstream lifecycle remain explicit. The alpha Skill package format is defined in docs/osk-skill-package/skill-spec.md.

Category	Skill	Canonical path	Primary responsibility	Common companions
Architecture	osk-adversarial-analysis	catalog/skills/architecture/osk-adversarial-analysis	Falsify engineering assumptions through counterexamples, failure-mode analysis, and evidence-backed hardening.	boundary review, verification, reporting, timebox
Architecture	osk-architecture-review	catalog/skills/architecture/osk-architecture-review	Evaluate system design, boundaries, structural risks, and architecture approval.	timebox, observability, reporting
Documentation	osk-code-docs	catalog/skills/documentation/osk-code-docs	Publish selected canonical knowledge and native API reference as traceable human documentation.	knowledge curator, reporting, timebox
Documentation	osk-knowledge-curator	catalog/skills/documentation/osk-knowledge-curator	Preserve reusable, evidence-backed canonical knowledge.	reporting, timebox
Process	osk-engineering-reporting	catalog/skills/process/osk-engineering-reporting	Preserve durable engineering artifacts and their navigable log relationships.	timebox
Process	osk-execution-timebox	catalog/skills/process/osk-execution-timebox	Bound execution, prevent non-convergence, and create recovery handoff.	observability
Process	osk-execution-observability	catalog/skills/process/osk-execution-observability	Expose decision-relevant live execution state to a supervisor.	timebox, reporting
Process	osk-verification-engineering	catalog/skills/process/osk-verification-engineering	Convert expected behavior into reproducible verification and pinned evidence.	timebox, observability, reporting
Guide / Go	osk-go-guide	catalog/skills/guide/golang/osk-go-guide	Guide idiomatic Go implementation and Go-specific review judgment.	verification, architecture review

Taxonomy

• architecture: system design, boundaries, trade-offs, and structural-risk skills.
• documentation: durable knowledge preservation, curation, and canonicalization.
• process: execution, observability, bounded work, verification, and durable execution records.
• guide: practice guidance scoped to a language, framework, platform, or technical discipline. The canonical directory is guide, not guides; the current Go subcategory is golang.

Engineering Reporting currently remains a process package because that is its established canonical path and manifest category. Its durable-record responsibility has a strong documentation affinity; moving it to documentation is a future taxonomy decision, not an implicit catalog repair.

Composition

Composition combines scoped contracts; it does not make every Skill authoritative over every decision.

Go implementation

skills:
  - osk-go-guide
  - osk-execution-timebox
  - osk-execution-observability
  - osk-engineering-reporting

execution:
  timebox: 45m
  observability: attentive

Architecture review

skills:
  - osk-architecture-review
  - osk-execution-timebox
  - osk-execution-observability
  - osk-engineering-reporting

execution:
  timebox: 60m
  observability: supervised

Verification task

skills:
  - osk-verification-engineering
  - osk-execution-timebox
  - osk-execution-observability
  - osk-engineering-reporting

execution:
  timebox: 45m
  observability: attentive

Go verification task

skills:
  - osk-verification-engineering
  - osk-go-guide
  - osk-execution-timebox
  - osk-execution-observability
  - osk-engineering-reporting

Shared Terminology and Boundaries

• Verification demonstrates behavior against defined expectations through execution and evidence. Validation checks whether an artifact, schema, package, or structure conforms to a contract.
• A progress checkpoint is a live execution update. An engineering checkpoint is a durable recovery artifact. Qualify the term when context does not make it clear.
• Evidence is observable support for a claim, not agent activity or confidence.
• Execution Timebox owns budget, stopping, and recovery rules. Execution Observability owns what live progress, convergence, risk, and blocker state must be visible.
• Execution Observability governs live updates. Engineering Reporting governs durable final or checkpointed records.
• Verification Engineering owns use cases to test cases, automation, execution states, and evidence. Engineering Reporting owns durable presentation; Timebox limits depth but never permits unsupported verification claims.
• Architecture Review owns system-level structural judgment. Go Guide owns language-specific design/implementation guidance; a Go preference is not automatically an architecture defect.

Conflict Resolution

Apply guidance in this order:

1. Task-specific user requirements.
2. Project-specific canonical guidance.
3. Role or process skill.
4. Technology guide.
5. General recommendation.

Safety constraints remain authoritative. A timebox cannot justify false completion, verification evidence cannot be overstated, a technology guide cannot override a documented product contract, and process guidance must not silently redesign architecture. Record project-specific exceptions explicitly and narrowly.