diff --git a/AGENTS.md b/AGENTS.md index b485b1c..3a091a5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -67,8 +67,8 @@ user has already granted or explicitly waived that review boundary. ## Skill Authoring -Use `write-a-skill` for general skill design and `write-a-compass-skill` for -Compass routing, install, derivation, provenance, retirement, and validation. +Use `write-a-skill` for skill design. Use `compass` to adopt the result into +reviewed Compass source. A skill should make the reader absorb, in its first screen: diff --git a/codex/skills/compass/SKILL.md b/codex/skills/compass/SKILL.md index 5294024..d49c35f 100644 --- a/codex/skills/compass/SKILL.md +++ b/codex/skills/compass/SKILL.md @@ -1,57 +1,34 @@ --- name: compass -description: Maintain Compass source, runtime boundaries, install wiring, retirement, and validation. Invoke manually for Compass repository changes. +description: Capture or apply durable learning in Compass, or refresh the live setup. Use when asked to write, save, adopt, update, or sync something through Compass. --- # Compass -Maintain Compass as reviewed source for portable Codex and Claude behavior. This -skill exists because a strong runtime change can still fail when source routing, -derivation, retirement, policy, and verification disagree. +Turn the user's learning or requested change into the smallest coherent Compass +update. Use this as the single entrypoint for changing reviewed Compass source or +refreshing the live setup. -Use it only when changing Compass itself. +Inspect the Compass repository before deciding where the change belongs. Treat +its current repository guidance, workflows, manifests, scripts, and tests as +authoritative. Do not restate or cache their rules here. -## Preserve The Source Boundaries +## Apply The Learning -- Codex global guidance belongs in `codex/AGENTS.md`. -- Claude global guidance belongs in `claude/CLAUDE.md`. -- Runtime-neutral shared skills and agents belong under `codex/` and derive only - where the manifest says so. -- Claude-specific agent contracts belong under `claude/agents/`. -- Portable opt-in domain packs belong under `carried/` and stay out of global - install lists. -- Compass maintainer reasoning belongs in `workflows/` and `local-docs/`. -- Deterministic truth belongs in scripts, hooks, manifests, schemas, and tests. +Find the existing surface that owns the behavior. Prefer refining, merging, +moving, mechanizing, or retiring material over adding another source. -Read root `AGENTS.md`, `philosophy.md`, `workflows/addition-intake.md`, -`local-docs/maintenance-learnings.md`, and the workflow nearest the change. +When the change creates or revises a reusable skill, use `write-a-skill` for the +skill's contract and language, then follow the repository's current integration +route. -## Change The Whole Ownership Contract +When the request is only to refresh the live installation, use the repository's +reviewed update workflow and script instead of changing source. -When behavior or ownership moves, update the complete route in one change: +## Result -- reviewed source; -- Codex and Claude install or derivation maps; -- source provenance; -- explicit retirement paths; -- policy and required-file checks; -- MCP catalog expectations; -- narrow tests and install round-trip coverage; -- directly related documentation. +Finish with one authoritative expression of the learning, the smallest coherent +diff, directly affected wiring reconciled, stale or duplicate paths removed, +current verification evidence, and a focused pull request when source changed. -Make Compass-owned capability exact. A fallback paragraph is not a substitute -for correct wiring. - -## Validate The Result - -Run narrow tests first, then: - -```powershell -.\scripts\doctor.ps1 -.\scripts\verify-live.ps1 -SkipCodexCommand -git diff --check -``` - -Exercise install and retirement paths when ownership changes. Forward-test -judgment changes with a fresh realistic invocation. Use a focused PR as the -review unit and keep public mutation behind named authority. +Do not merge or make another public mutation without named authority. diff --git a/codex/skills/compass/agents/openai.yaml b/codex/skills/compass/agents/openai.yaml index 6eca0ac..5ef8c11 100644 --- a/codex/skills/compass/agents/openai.yaml +++ b/codex/skills/compass/agents/openai.yaml @@ -1,7 +1,7 @@ interface: display_name: "Compass" - short_description: "Maintain portable Compass setup" - default_prompt: "Use $compass to update durable Compass source and install wiring." + short_description: "Capture durable learning in Compass" + default_prompt: "Use $compass to write this learning into the smallest authoritative Compass surface, or refresh the live setup when that is the request." policy: allow_implicit_invocation: false diff --git a/codex/skills/update-compass/SKILL.md b/codex/skills/update-compass/SKILL.md deleted file mode 100644 index 71d9116..0000000 --- a/codex/skills/update-compass/SKILL.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -name: update-compass -description: Update live Codex setup from latest reviewed Compass origin/main. Use for local Codex config refreshes or latest-to-live flow. ---- - -# Update Compass - -Use the local Compass checkout. Run the reviewed updater instead of copying -files by hand. - -1. Confirm the Compass worktree is clean. -2. Run `.\scripts\update-live.ps1`. -3. Let it fetch `origin/main`, fast-forward local `main`, install the portable - files, overlay every reviewed key from `codex/config.review.toml`, and verify - live sync. -4. Stop if it reports local changes, a non-fast-forward branch, config overlay - validation failure, or install failure. -5. Report the new HEAD, backup path, reviewed config change count, and - verification result. -6. Treat live config keys absent from the reviewed fragment as machine-local and - preserved; never replace the whole live `config.toml`. diff --git a/codex/skills/update-compass/agents/openai.yaml b/codex/skills/update-compass/agents/openai.yaml deleted file mode 100644 index 7cd1c22..0000000 --- a/codex/skills/update-compass/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Update Compass" - short_description: "Refresh live setup from Compass" - default_prompt: "Use $update-compass to refresh my live setup from reviewed Compass main." - -policy: - allow_implicit_invocation: false diff --git a/codex/skills/write-a-compass-skill/SKILL.md b/codex/skills/write-a-compass-skill/SKILL.md deleted file mode 100644 index 2047712..0000000 --- a/codex/skills/write-a-compass-skill/SKILL.md +++ /dev/null @@ -1,75 +0,0 @@ ---- -name: write-a-compass-skill -description: Add, revise, route, install, validate, or retire a skill inside the Compass reviewed source. ---- - -# Write A Compass Skill - -Maintain a Compass skill as runtime guidance and reviewed portable source. Use -`write-a-skill` for role, language, and behavior. This skill owns repository -routing, wiring, provenance, retirement, and validation. - -Read root `AGENTS.md`, `workflows/addition-intake.md`, and the workflow nearest -the change before editing. - -## Select The Narrowest Surface - -- reusable global capability: `codex/skills/`; -- portable opt-in domain pack: `carried/`; -- project-specific capability: the target repository; -- independent persona: `codex/agents/`; -- deterministic mechanic: scripts, hooks, manifests, or tests; -- Compass maintenance process: `workflows/`; -- maintainer evidence or history: `local-docs/`. - -A global skill must provide repeated cross-project value that repays retrieval -and maintenance cost. - -## Update One Ownership Route - -Follow the complete update-together contract in -`workflows/addition-intake.md`. Keep one reviewed source and reconcile every -directly dependent surface: - -- skill source; -- install and Claude derivation maps; -- source record and provenance; -- retired live paths when ownership or names change; -- required-file and policy checks; -- MCP catalog fixtures and other installed-set tests; -- directly related documentation. - -Do not duplicate that checklist inside the skill being authored. A fallback -paragraph is not a substitute for exact wiring. - -Codex and Claude global instruction files remain separately authored because -their runtime contracts differ. Derive only behavior that is truly shared. - -## Preserve Provenance - -An externally adapted skill records the reviewed repository, source path, -immutable ref, license, and deterministic source hash. Keep this evidence in a -reference that normal runtime work does not load. - -## Retire Completely - -A retirement removes the old source and install entries, preserves useful -material in its approved narrower destination, and records every live path -Compass previously owned. A rename is a retirement plus a new skill. - -Never delete unrelated personal skills while cleaning retired copies. - -## Validate Behavior And Wiring - -Run the behavior review from `write-a-skill`, then the narrow tests and: - -```powershell -.\scripts\doctor.ps1 -.\scripts\verify-live.ps1 -SkipCodexCommand -git diff --check origin/main...HEAD -``` - -Exercise install and retirement paths when ownership changes. Forward-test -judgment with a fresh realistic invocation. Use a focused pull request as the -review unit. A green build is evidence; current-head review and named authority -determine readiness and merge. diff --git a/codex/skills/write-a-compass-skill/agents/openai.yaml b/codex/skills/write-a-compass-skill/agents/openai.yaml deleted file mode 100644 index cdf3f29..0000000 --- a/codex/skills/write-a-compass-skill/agents/openai.yaml +++ /dev/null @@ -1,7 +0,0 @@ -interface: - display_name: "Write A Compass Skill" - short_description: "Maintain Compass skill source and install wiring" - default_prompt: "Use $write-a-compass-skill to create, revise, route, validate, or retire this Compass skill across source, manifests, Claude derivation, policy, and tests." - -policy: - allow_implicit_invocation: false diff --git a/codex/skills/write-a-skill/SKILL.md b/codex/skills/write-a-skill/SKILL.md index a116946..68710ec 100644 --- a/codex/skills/write-a-skill/SKILL.md +++ b/codex/skills/write-a-skill/SKILL.md @@ -1,6 +1,6 @@ --- name: write-a-skill -description: Create or revise a reusable agent skill that strongly orients judgment, stays lean, and proves its behavior. +description: Create, revise, or retire a reusable agent skill that strongly orients judgment, stays lean, and preserves a clean lifecycle. --- # Write A Skill @@ -78,6 +78,17 @@ contract must stay exact. Write decisively. Succinct and pithy language helps only when the role remains complete. +## Preserve One Lifecycle + +Maintain one canonical source and derive copies mechanically. Do not hand-edit +installed or generated copies. + +When adapting an external skill, preserve its source, immutable version, license, +and reviewed changes outside normal runtime guidance. + +A rename is retirement plus a new skill. Remove stale names, triggers, install +entries, and owned live copies without touching unrelated user material. + ## Prove The Skill Review behavior, not prose alone: @@ -88,6 +99,7 @@ Review behavior, not prose alone: - Can detail move to a reference or deterministic mechanic? - Does any rule decide something that should remain contextual? - Can any paragraph disappear without losing behavior? +- Do source, derived copies, discovery metadata, and retirement state agree? Forward-test fragile judgment with realistic prompts. Repair the cause of weak behavior instead of appending another warning. @@ -95,4 +107,4 @@ behavior instead of appending another warning. ## Output Return the skill, needed resources, trigger rationale, behavior evidence, known -boundaries, and the durable surface that owns it. +boundaries, lifecycle changes, and the durable surface that owns it. diff --git a/codex/skills/write-a-skill/agents/openai.yaml b/codex/skills/write-a-skill/agents/openai.yaml index 6813244..be4b16c 100644 --- a/codex/skills/write-a-skill/agents/openai.yaml +++ b/codex/skills/write-a-skill/agents/openai.yaml @@ -1,7 +1,7 @@ interface: display_name: "Write A Skill" - short_description: "Write strong lean reusable agent skills" - default_prompt: "Use $write-a-skill to create or revise a reusable skill that establishes a strong role, desired result, evidence standard, and authority boundary before procedure." + short_description: "Write and maintain lean agent skills" + default_prompt: "Use $write-a-skill to create, revise, or retire a reusable skill whose role, desired result, evidence standard, authority boundary, and lifecycle are clear before procedure." policy: allow_implicit_invocation: false diff --git a/manifests/policy-contracts.json b/manifests/policy-contracts.json index 2f9b7e5..b97b87b 100644 --- a/manifests/policy-contracts.json +++ b/manifests/policy-contracts.json @@ -59,17 +59,14 @@ } }, { - "id": "routing-source-referenced-by-compass-skill", + "id": "compass-single-entrypoint", "path": "codex/skills/compass/SKILL.md", "required": [ - "workflows/addition-intake.md" - ] - }, - { - "id": "routing-source-referenced-by-skill-authoring", - "path": "codex/skills/write-a-compass-skill/SKILL.md", - "required": [ - "workflows/addition-intake.md" + "Turn the user's learning or requested change into the smallest coherent Compass", + "current repository guidance, workflows, manifests, scripts, and tests as", + "Do not restate or cache their rules here.", + "use `write-a-skill`", + "reviewed update workflow and script instead of changing source." ] }, { diff --git a/manifests/portable-files.toml b/manifests/portable-files.toml index e1a9932..93d3786 100644 --- a/manifests/portable-files.toml +++ b/manifests/portable-files.toml @@ -37,11 +37,9 @@ skills = [ "specialist-review", "subagent-driven-development", "to-prd", - "update-compass", "using-goals", "which-llm", "workspace-steward", - "write-a-compass-skill", "write-a-skill", ] @@ -82,7 +80,6 @@ derived_skills = [ "to-prd", "using-goals", "workspace-steward", - "write-a-compass-skill", "write-a-skill", ] diff --git a/manifests/retired-skills.json b/manifests/retired-skills.json index d5cfe7f..985656c 100644 --- a/manifests/retired-skills.json +++ b/manifests/retired-skills.json @@ -16,16 +16,19 @@ "input-token-economy", "pr-merge-closeout", "ui-ux-pro-max", + "update-compass", "using-codex-goals", "webmcp-eval-triage", "webmcp-tool-authoring", - "webmcp-verify-tool" + "webmcp-verify-tool", + "write-a-compass-skill" ], "claude_skills": [ "benchmark-infra-reviewer", "benchmark-run-operator", "input-token-economy", - "using-codex-goals" + "using-codex-goals", + "write-a-compass-skill" ], "claude_agents": [ "benchmark-infra-reviewer.md" diff --git a/manifests/skill-sources.json b/manifests/skill-sources.json index 1ccd175..ec5fb1a 100644 --- a/manifests/skill-sources.json +++ b/manifests/skill-sources.json @@ -146,16 +146,6 @@ "claude": "derived" } }, - { - "name": "update-compass", - "owner": "compass", - "source": "codex/skills/update-compass", - "profile": "default", - "targets": { - "codex": "copy", - "claude": "none" - } - }, { "name": "using-goals", "owner": "compass", @@ -191,16 +181,6 @@ "claude": "derived" } }, - { - "name": "write-a-compass-skill", - "owner": "compass", - "source": "codex/skills/write-a-compass-skill", - "profile": "default", - "targets": { - "codex": "copy", - "claude": "derived" - } - }, { "name": "write-a-skill", "owner": "compass", diff --git a/scripts/test-compass-architecture.py b/scripts/test-compass-architecture.py index 1664884..0f26691 100644 --- a/scripts/test-compass-architecture.py +++ b/scripts/test-compass-architecture.py @@ -35,11 +35,13 @@ def manifest(self) -> dict[str, object]: def test_installed_skill_set_matches_current_architecture(self) -> None: manifest = self.manifest() skills = set(manifest["agents"]["skills"]) + self.assertIn("compass", skills) self.assertIn("run-a-micro-experiment", skills) self.assertIn("using-goals", skills) self.assertIn("which-llm", skills) - self.assertIn("write-a-compass-skill", skills) self.assertIn("write-a-skill", skills) + self.assertNotIn("update-compass", skills) + self.assertNotIn("write-a-compass-skill", skills) self.assertNotIn("benchmark-run-operator", skills) self.assertNotIn("input-token-economy", skills) self.assertNotIn("using-codex-goals", skills) @@ -249,6 +251,8 @@ def test_skill_interface_prompts_match_current_architecture(self) -> None: self.assertNotIn("@codex", text, path) self.assertNotIn("using-codex-goals", text, path) self.assertNotIn("input-token-economy", text, path) + self.assertNotIn("$update-compass", text, path) + self.assertNotIn("$write-a-compass-skill", text, path) def test_retired_skill_manifest_is_well_formed(self) -> None: # The manifest is the single source. Name format is owned by @@ -278,8 +282,13 @@ def test_retired_skill_manifest_is_well_formed(self) -> None: "input-token-economy", "using-codex-goals", "benchmark-infra-reviewer.md", + "update-compass", + "write-a-compass-skill", ): self.assertIn(required, all_names) + self.assertIn("update-compass", manifest["user_skills_home"]) + self.assertIn("write-a-compass-skill", manifest["user_skills_home"]) + self.assertIn("write-a-compass-skill", manifest["claude_skills"]) def test_skill_description_cap_matches_shared_constant(self) -> None: common = self.read("scripts/common.ps1")