docs(humaninloop): refresh agent and skill guidelines (v1.1.0 / v1.3.0)

[deepeshBodh]

Summary

Refresh of docs/AGENT-GUIDELINES.md (v1.0.0 → v1.1.0) and docs/SKILL-GUIDELINES.md (v1.2.0 → v1.3.0) with patterns surfaced from a fresh comparative read of claude-plugins-official, Vercel Labs agent-skills, and superpowers.

What's New

AGENT-GUIDELINES v1.1.0

• §3.1.3 Tool Restriction Tiers — four-tier responsibility model (read-only / write-capable / execution-capable / full surface) with explicit rules. Pattern observed across all production agents in claude-plugins-official.
• §5.5 Agent Anti-Shortcut Doctrine — agent-level analogue of CSO Anti-Leak Rule. Workflow-summary descriptions cause parent agents to bypass dispatch.
• §6.5 Confidence Scoring for Reviewer Agents — 0-100 confidence with threshold (≥80 for Important/Minor). Addresses the over-reporting failure mode that prior guidance didn't cover. Pattern from claude-plugins-official/feature-dev/agents/code-reviewer.md.
• qa-engineer added to persona agent list (was executor in v1.0.0). Executor list now empty by design — reflects trend that judgment-heavy work belongs to persona agents.
• Validation checklist additions (§7.6, §7.8, §7.9) to enforce the new requirements.

SKILL-GUIDELINES v1.3.0

• §1.1.4 Knowledge Skills — new 4th classification for curated rule corpora (rule-per-file, machine-extractable schema). Pattern from agent-skills/skills/react-best-practices/ (74 rule files, identical schema).
• §2.2.1 Tiered word counts + token-budget framing — line-count budgets for knowledge skills; explicit "shared public good" framing for context window economics. Pattern from superpowers/skills/writing-skills.
• §3.6 Two-Tier Validation — distinct structural (machine-checkable, CI-enforceable) vs semantic (pressure-test) validation layers. Pattern from agent-skills/packages/react-best-practices-build/.
• §5.5 Runtime-Aware Path Guidance — avoid hardcoded paths; document runtime-specific behavior in a Runtime Notes section.
• Validation checklist additions (§8.6, §8.7, §8.8).

What Did NOT Change

• Three-Layer Separation (Agent / Skill / Supervisor) — still load-bearing
• Five Anti-Leak Rules in AGENT-GUIDELINES — still load-bearing
• CSO Anti-Leak Rule in SKILL-GUIDELINES — still load-bearing
• TDD discipline / Iron Law — still load-bearing
• Anti-rationalization framework — still load-bearing
• RFC 2119 description format — still load-bearing, validated by 20+ skill audits

Cross-Document Coherence

The two updated documents form a coherent system: SKILL-GUIDELINES §3.6 (Two-Tier Validation) parallels AGENT-GUIDELINES §6.5 (Confidence Scoring), and SKILL-GUIDELINES §2.1.3 (CSO Anti-Leak) parallels AGENT-GUIDELINES §5.5 (Agent Anti-Shortcut). No contradictions across the two updated documents; every cross-reference resolves.

Test Plan

• Pre-commit hook validates conventional-commits format
• No broken markdown links in updated docs (verified via grep — all relative links resolve within the repo)
• CLAUDE.md still references the two doc paths correctly (no path changes)
• Skill-auditor agent should be updated separately to emit findings in the new audit schema (out of scope for this PR — see follow-up below)

Follow-Up Work (Out of Scope)

1. Build scripts/validate-skill-structure.sh for Tier 1 structural validation (referenced as suggested in SKILL-GUIDELINES §3.6)
2. Update skill-auditor agent to emit findings using the new severity/confidence/citation schema
3. Concrete Knowledge Skill exemplar (e.g., naming conventions, security patterns)
4. Decide whether to backfill confidence scoring for the 20 prior PASS audits or grandfather them

🤖 Generated with Claude Code