skill-orchestration-system: Instructions file for Codex

Agent Instructions

Project Overview

Skill Orchestration System (SOS) is a Python CLI for organizing agent skills into auditable, activatable packs. It scans skill folders, proposes functional packs, writes reviewable plans, applies migrations only with explicit confirmation, generates sos-* pointer skills, and creates backups before writes.

This is the canonical public repository. Public files must stay free of personal paths, private workspace details, tokens, account data, and local planning logs. Local NHK, planning, spec, and archive surfaces may exist in this checkout, but they are intentionally ignored by Git.

Workspace Navigation

Start with the smallest current surface that can route the task safely:

1. AGENTS.md for stable execution rules.
2. coding-agent-guide.md for local task routing, when present.
3. documentation-governance.md for local active/archive rules, when present.
4. task_plan.md, findings.md, and progress.md only when they are active.
5. README.md, README_CN.md, references/, src/, and tests/ for public product work.

Ignored local workflow files include task_plan.md, progress.md, findings.md, coding-agent-guide.md, documentation-governance.md, docs/, and archive/. They are useful for local continuity but must not be committed.

Architecture Boundaries

• CLI writes must stay deterministic, auditable, and dry-run-first.
• scan, propose, and dry-run commands must not mutate active skill roots.
• Config, manifest, vault, backup, restore, sync, and source deletion behavior must be covered by tests.
• Source deletion must remain opt-in and require explicit confirmation.
• Pointer skills should remain short routing surfaces; full skill content belongs in the managed vault.
• Do not hardcode local absolute paths or user-specific defaults.
• Host-specific disable behavior must stay isolated to operation kinds (MOVE_TO_ARCHIVE for Claude, DISABLE_CODEX_SKILL for Codex) and validated in apply._validate_plan before any write.