agentleFS
RainnystoneRainnystone/skill-orchestration-system/AGENTS.md

skill-orchestration-system

AGENTS.md10 starsChanged 6 months agoMITView on GitHub

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…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repositoryOne other file it gives its agents.

The file

Show its rules and text

We split this AGENTS.md into the rules it gives an agent

24 rules. About 0 are common, 20 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈20

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 4

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

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

    line 17
  2. Distinctive:

    Do not hardcode local absolute paths or user-specific defaults.

    line 36
  3. Distinctive:

    Never mutate state objects.

    line 42
  4. Distinctive:

    Do not delegate deterministic validation to heuristic or probabilistic flows unless the human explicitly approves that tradeoff.

    line 49
  5. Distinctive:

    If code, tests, and active project documents disagree, resolve intended behavior first.

    line 53
  6. Distinctive:

    If a todo list, task list, checklist, plan, or other active tracking surface is in use, update it when each task is completed.

    line 58
  7. Distinctive:

    Do not batch all task-list updates at the very end if task-by-task updates are practical.

    line 59
  8. Very specific:

    If task_plan.md, progress.md, or findings.md are active, keep them aligned with actual task status.

    line 60
  9. Very specific:

    After a full superpowers workflow cycle or another clearly bounded implementation cycle, check whether the active docs and tracking …

    line 64
  10. Very specific:

    If the workspace is NHK-managed and the workstream looks complete, ask whether nhk-archive should be invoked.

    line 65
  11. Distinctive:

    Do not archive automatically.

    line 66
  12. Distinctive:

    Prefer current code, current tests, and active docs first.

    line 71
  13. Distinctive:

    Start with the smallest active document set that can route the task safely.

    line 72
  14. Distinctive:

    Do not close a subagent just because a wait timed out.

    line 83
  15. Distinctive:

    Before replacing or closing a subagent, confirm its actual status, current progress, latest conclusion, and whether keeping it alive still …

    line 84
  16. Distinctive:

    Prefer one primary objective, one main module or surface area, and one verification path per packet.

    line 89
  17. Distinctive:

    If two packets share the same primary production file or test file, default to serial execution unless the plan explains why parallel work …

    line 91
  18. Distinctive:

    If a packet grows across unrelated concerns, long execution chains, or multiple verification paths, split it again.

    line 92
  19. Distinctive:

    When blocked during implementation:

    line 96
  20. Distinctive:

    Stop and wait for the human if the fix would change public CLI semantics, pack merge authority, hidden-library write behavior, source …

    line 103
  21. Distinctive:

    Default full verification is:

    line 112
  22. Very specific:

    Commit format should use conventional prefixes such as feat:, fix:, docs:, test:, refactor:, or chore:.

    line 126
  23. Distinctive:

    Before public commits, check:

    line 128
  24. Distinctive:

    If a sensitive file was accidentally tracked, stop and remove it from the index before pushing.

    line 135

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

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.

Mandatory Execution Rules

Immutable Data Patterns

  • Never mutate state objects. Always return new copies.
  • const newState = { ...oldState, field: newValue }
  • Array operations: slice, map, filter — never splice, push, sort in-place.

Deterministic Boundaries Must Stay Deterministic

  • Validation, schema checks, path checks, reference integrity, and persistence guarantees should be handled by deterministic code.
  • Do not delegate deterministic validation to heuristic or probabilistic flows unless the human explicitly approves that tradeoff.

Keep Rules, Code, Tests, and Active Docs in Sync

  • If code, tests, and active project documents disagree, resolve intended behavior first.
  • Then bring implementation, tests, and active docs back into sync.

Task Tracking Discipline

  • If a todo list, task list, checklist, plan, or other active tracking surface is in use, update it when each task is completed.
  • Do not batch all task-list updates at the very end if task-by-task updates are practical.
  • If task_plan.md, progress.md, or findings.md are active, keep them aligned with actual task status.

Workflow Completion and Archive Check

  • After a full superpowers workflow cycle or another clearly bounded implementation cycle, check whether the active docs and tracking surfaces suggest that a workstream may be complete.
  • If the workspace is NHK-managed and the workstream looks complete, ask whether nhk-archive should be invoked.
  • Do not archive automatically.

Documentation Governance and Context Loading

  • documentation-governance.md, when present, is the source of truth for local documentation lifecycle rules.
  • Prefer current code, current tests, and active docs first; treat archive as reference material rather than a default execution source.
  • Start with the smallest active document set that can route the task safely.
  • Load specs, plans, codemaps, or archive only when the task genuinely needs them.
  • For root tracking discipline, use planning-with-files-zh when the work is multi-session or needs durable recovery.
  • For active specs, plans, TDD, review loops, and implementation workflows, use the relevant superpowers skills.

Subagent Delegation Discipline

  • For complex work, prefer decomposing implementation into bounded tasks and dispatching subagents when the subtasks are independent enough.
  • Subagent dispatch must follow subagent-driven-development; do not improvise a parallel workflow outside that discipline when the task has already been decomposed.
  • Dispatch instructions must state whether the subagent is read-only review or write-authorized implementation.
  • Give each subagent a clean task brief, owned files or modules, verification expectations, and forbidden actions.
  • Do not close a subagent just because a wait timed out.
  • Before replacing or closing a subagent, confirm its actual status, current progress, latest conclusion, and whether keeping it alive still reduces risk or rework.

Implementation Packet Discipline

  • Decompose implementation work into bounded packets before dispatch.
  • Prefer one primary objective, one main module or surface area, and one verification path per packet.
  • Each packet should declare its user-facing goal, owned files, default verification command, and whether it is safe to run in parallel.
  • If two packets share the same primary production file or test file, default to serial execution unless the plan explains why parallel work is still safe.
  • If a packet grows across unrelated concerns, long execution chains, or multiple verification paths, split it again.

Blocker Protocol

When blocked during implementation:

  1. Field missing producer -> add the producer.
  2. Output has no downstream entry -> add to the nearest shared contract.
  3. Code forced to understand semantics -> convert to a staged responsibility boundary.
  4. Naming conflict -> prefer the current SOS canonical name, then sync code, tests, docs, and plans.

Stop and wait for the human if the fix would change public CLI semantics, pack merge authority, hidden-library write behavior, source deletion behavior, or the human-confirmation control model.

Testing and Verification

  • For feature or bugfix work, use test-driven development: write or update tests first, confirm failure when practical, implement, then confirm green.
  • For documentation-only changes, run reference checks such as git diff --check, file existence checks, and privacy scans for public content.
  • For code changes, run the relevant targeted tests first, then the full test suite before calling work complete.
  • Default full verification is:
python -m pytest
  • CLI smoke check:
python -m sos --version

Git and Delivery

  • Commit format should use conventional prefixes such as feat:, fix:, docs:, test:, refactor:, or chore:.
  • Public commits must not include ignored local planning files, local absolute paths, private notes, generated runtime state, caches, or virtual environments.
  • Before public commits, check:
git status --short --ignored
git diff --check
  • If a sensitive file was accidentally tracked, stop and remove it from the index before pushing.
  • Human review is required before broad merges, public behavior changes, or irreversible write-path changes.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.