feat: add Hermes skill builder specialized agent tooling

[ratpackcp7]

Hermes Skill Builder / Specialized Agents v1 — Final Report

Result

PASS — all reviewed SPEC-compliance blockers are fixed and verified in the isolated worktree. The work is ready to stage/commit, but nothing was staged, committed, pushed, activated, restarted, or deployed.

MODEL_PREFLIGHT

• Executor: Codex direct session.
• Direct-session reason: the user assigned the bounded blocker-remediation task directly to this existing Codex worktree.
• OpenCode/subagents: not used or authorized.
• Task class: Level 3 follow-up implementation under the existing SPEC.
• Worktree: /home/chris/projects/worktrees/agent-skills-hermes-skill-builder-v1
• Branch: codex/hermes-skill-builder-v1
• Production impact: none authorized or performed.

Files changed

• .gitignore
• CHANGELOG.md
• HANDOFF.md
• README.md
• agents/skill-agent-builder.md
• docs/skill-builder-specialized-agents.md
• references/hermes-skill-agent-architecture.md
• skills/skill-builder-specialized-agents.zip
• skills/skill-builder-specialized-agents/SKILL.md
• skills/skill-builder-specialized-agents/assets/create_skill_agent.py
• skills/skill-builder-specialized-agents/assets/package_skill.py
• skills/skill-builder-specialized-agents/assets/skill_agent_lib.py
• skills/skill-builder-specialized-agents/assets/validate_skill_agent.py
• skills/skill-builder-specialized-agents/scripts/create-skill-agent.sh
• skills/skill-builder-specialized-agents/scripts/package-skill.sh
• skills/skill-builder-specialized-agents/scripts/validate-skill-agent.sh
• skills/skill-builder-specialized-agents/templates/dispatch-contract.md
• tests/test_skill_agent_tooling.py

What was implemented

• Unsafe-instruction validation now runs from strict validate_skill() and validate_agent(); generic AGENTS.md validation is available through --instructions.
• Prohibited-action coverage includes Hermes/Bob/gateway/service restart, systemctl/service/Docker restart operations, deploy, tmux kill, --no-verify, pushing main/master, and live runtime/config mutation.
• Generator roots must be marked Git repositories/worktrees with local AGENTS.md, HANDOFF.md, skills/, and agents/; symlink escapes and live .hermes roots are rejected.
• Packager inputs must belong to the repository skills/ tree; outputs must be ZIP files beneath that tree. Existing ZIP replacement requires explicit --replace and is atomic.
• Executable skill entrypoints are Bash with set -euo pipefail; Python implementation files are non-executable packaged assets.
• Dry-run NEXT: output points to the Bash entrypoints.
• The ZIP was regenerated and contains nine intended files with no bytecode.
• README, CHANGELOG, HANDOFF, architecture reference, skill workflow, quick-start documentation, and tests were updated.

What was intentionally not implemented

• No live install/copy to /home/chris/.hermes.
• No edits to live Bob/Hermes configuration, SOUL, startup hooks, bob-dispatch, or delegate_task.
• No restart, reload, deploy, process/tmux action, database action, GitHub mutation, staging, commit, push, or PR.
• Runtime activation remains a separate explicitly approved rollout.

Exact verification output

/home/chris/cp7-bridge/scripts/verify_agent_standards.sh /home/chris/projects/worktrees/agent-skills-hermes-skill-builder-v1
exit=0
OK file .../AGENTS.md
OK file .../HANDOFF.md
OK file .../CHANGELOG.md
OK file .../README.md
OK dir .../docs/decisions
Failures: 0

bash -n skills/skill-builder-specialized-agents/scripts/*.sh
exit=0

python3 -m py_compile skills/skill-builder-specialized-agents/assets/*.py tests/test_skill_agent_tooling.py
exit=0

skills/skill-builder-specialized-agents/scripts/validate-skill-agent.sh --root . --all
exit=0
VALIDATION_REPORT: PASS (22 artifact(s))

skills/skill-builder-specialized-agents/scripts/validate-skill-agent.sh --skill skills/skill-builder-specialized-agents/SKILL.md
exit=0
PASS: skills/skill-builder-specialized-agents/SKILL.md
VALIDATION_REPORT: PASS (1 artifact(s))

skills/skill-builder-specialized-agents/scripts/validate-skill-agent.sh --agent agents/skill-agent-builder.md
exit=0
PASS: agents/skill-agent-builder.md
VALIDATION_REPORT: PASS (1 artifact(s))

skills/skill-builder-specialized-agents/scripts/validate-skill-agent.sh --instructions AGENTS.md
exit=0
PASS: AGENTS.md
VALIDATION_REPORT: PASS (1 artifact(s))

python3 -m unittest discover -s tests -p 'test_*skill*agent*.py' -v
exit=0
Ran 20 tests in 0.466s
OK

bash hooks/simplify-ignore-test.sh
exit=0
Results: 21 passed, 0 failed

git diff --check
exit=0

Package verification:

skills/skill-builder-specialized-agents/scripts/package-skill.sh --skill-dir skills/skill-builder-specialized-agents --replace --go
exit=0
PACKAGE_REPORT
result: CREATED
files: 9

python3 -m zipfile -l skills/skill-builder-specialized-agents.zip
exit=0
9 intended files: SKILL.md, four Python assets, three Bash entrypoints, and dispatch-contract.md

Failure-test output

test_all_required_unsafe_patterns_rejected ... ok
test_ft3_unsafe_restart_instruction_rejected ... ok
test_unsafe_instruction_inside_skill_rejected ... ok
test_unsafe_instruction_inside_specialized_agent_rejected ... ok
test_unsafe_instruction_inside_agents_md_rejected ... ok
test_generator_rejects_root_outside_git_worktree_boundary ... ok
test_packager_rejects_external_output_path ... ok
test_packager_rejects_non_zip_repository_output ... ok
test_generator_creates_valid_skill_and_agent ... ok
test_executable_skill_scripts_are_compliant_bash ... ok

Original required failure tests also pass:

FT1 vague task rejected ... ok
FT2 missing SPEC rejected ... ok
FT3 unsafe service restart rejected ... ok
FT4 invalid skill identity rejected ... ok
FT5 overwrite protection ... ok
FT6 placeholder SPEC rejected ... ok

HANDOFF status

• HANDOFF.md: updated with blocker fixes, exact verification commands, Bash/Python layout, and path-boundary behavior.
• Staged: no. The user required stopping before staging/commit.

Commit, push, and PR

• Commit: NO_COMMIT — required pre-commit stop.
• Push result: NO_PUSH_USER_REQUIRED_STOP_BEFORE_COMMIT.
• PR URL: NO_PR_USER_REQUIRED_STOP_BEFORE_COMMIT.

Remaining risks

• Safety detection is deterministic pattern matching, not semantic interpretation; future prohibited command forms may require new fixtures.
• Compatibility --all intentionally preserves legacy skill acceptance; newly created/changed skills must also run strict --skill validation.
• Frontmatter parsing supports the scalar contract fields used here and is not a general YAML implementation.
• The source capability is not active in live Hermes/Bob until a separately approved activation/integration task.

Readiness verdict

READY TO STAGE/COMMIT. All reviewed blockers and required failure tests are resolved. Stop remains at the unstaged, uncommitted boundary.

Stop reason

Task complete at the required pre-staging/pre-commit boundary.

FINAL_REPORT

• status: PASS
• summary: Reviewed SPEC-compliance blockers fixed; hardened source capability is ready to stage/commit.
• files changed: .gitignore, CHANGELOG.md, HANDOFF.md, README.md, agent/docs/reference files, regenerated skill ZIP, skill Bash entrypoints and Python assets, template, tests
• checks/tests run: CP7 standards -> PASS; Bash syntax -> PASS; Python compile -> PASS; validators -> PASS; unittest 20/20 -> PASS; hook tests 21/21 -> PASS; diff check -> PASS; archive regeneration/listing -> PASS
• commit: NO_COMMIT (required stop before staging/commit)
• push result: NO_PUSH_USER_REQUIRED_STOP_BEFORE_COMMIT
• pr url: NO_PR_USER_REQUIRED_STOP_BEFORE_COMMIT
• remaining risks: pattern-based safety detection; legacy compatibility mode is intentionally less strict; source not live-activated
• stop reason: task complete at pre-staging/pre-commit boundary