agentleFS
hushh-labshushh-labs/hushh-research/.agents/skills/one-voice-governance/SKILL.md

one-voice-governance

Skill40 starsChanged 5 days agoApache-2.0View on GitHub

Use when changing One Voice capability authoring, Kai compatibility runtime contracts, generated action gateway contracts, typed-search and voice parity, persona/workspace gating, or BYOK-safe durable voice memory.

The file

We split this skill into the rules it gives an agent

9 rules. About 0 are common, 5 are distinctive, and 4 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    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. Very specific:

    Avoid overlap with frontend, backend-api-contracts, and security-audit.

    line 12
  2. Distinctive:

    Treat local voice action contracts as the authoring source of truth.

    line 65
  3. Distinctive:

    Keep the generated gateway as the single semantic authority.

    line 66
  4. Distinctive:

    Do not add capabilities through runtime heuristics, ad hoc DOM discovery, or parallel voice systems.

    line 68
  5. Distinctive:

    Treat One Voice as the product-facing voice contract.

    line 69
  6. Distinctive:

    Treat persona, workspace, vault, consent, onboarding, rollout, and kill-switch gates as hard preconditions.

    line 71
  7. Very specific:

    Keep shared-runtime context consent-scoped and out of plaintext storage.

    line 72
  8. Very specific:

    Use voice-review-checklist.md before recommending or merging voice-adjacent PRs.

    line 74
  9. Very specific:

    Keep legacy query route inputs as compatibility only.

    line 76

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill 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
SKILL.md

One Voice Governance Skill

Purpose and Trigger

  • Primary scope: one-voice-governance
  • Trigger on One Voice capability authoring, Kai compatibility runtime changes, generated gateway changes, typed-search and voice parity, action workflow chaining, persona/workspace gating, or durable voice memory boundary changes.
  • Avoid overlap with frontend, backend-api-contracts, and security-audit.

Coverage and Ownership

  • Role: owner
  • Owner family: one-voice-governance

Owned repo surfaces:

  1. contracts/kai
  2. consent-protocol/hushh_mcp/services/action_gateway.py
  3. docs/architecture/one/one-voice-runtime-architecture.md
  4. docs/architecture/one/one-voice-kai-compatibility-runtime.md
  5. docs/architecture/finance
  6. hushh-webapp/lib/voice
  7. hushh-webapp/scripts/voice
  8. hushh-webapp/components/kai
  9. hushh-webapp/components/consent
  10. hushh-webapp/app/kai
  11. hushh-webapp/app/profile
  12. hushh-webapp/app/ria
  13. .agents/skills/one-voice-governance

Non-owned surfaces:

  1. frontend
  2. backend-api-contracts
  3. security-audit
  4. docs-governance
  5. quality-contracts

Do Use

  1. Local .voice-action-contract.json, generated gateway, or manifest changes.
  2. Voice/search/UI action parity around stable action_id.
  3. Persona, workspace, vault, consent, onboarding, and durable voice memory gates.

Do Not Use

  1. Generic frontend layout or backend route work without voice/search/action impact.
  2. Generic docs cleanup without voice/action ownership implications.
  3. Security intake where IAM or consent policy is primary.

Read First

  1. docs/architecture/finance/kai-action-gateway-vnext.md
  2. docs/architecture/one/one-voice-runtime-architecture.md
  3. docs/architecture/one/one-agent-hierarchy.md
  4. docs/architecture/one/one-voice-kai-compatibility-runtime.md
  5. .agents/skills/one-voice-governance/references/voice-review-checklist.md

Workflow

  1. Treat local voice action contracts as the authoring source of truth.
  2. Keep the generated gateway as the single semantic authority; do not restore a parallel compatibility manifest.
  3. Reuse stable action_id values across voice, search, UI actionables, analytics, and docs.
  4. Do not add capabilities through runtime heuristics, ad hoc DOM discovery, or parallel voice systems.
  5. Treat One Voice as the product-facing voice contract; keep Kai-era voice routes as compatibility/runtime identifiers until explicitly migrated.
  6. Author workflows only when the UI can move through the same prerequisite chain with settlement between steps.
  7. Treat persona, workspace, vault, consent, onboarding, rollout, and kill-switch gates as hard preconditions.
  8. Keep shared-runtime context consent-scoped and out of plaintext storage. Durable owner-isolated pod experience follows docs/product/principles/private-agent-requirements.md; it must not become a second PKM authority.
  9. Block new microphone, dictation, transcript, or voice-like inputs unless they are approved adapters over the existing gateway path.
  10. Use voice-review-checklist.md before recommending or merging voice-adjacent PRs.
  11. Route changes that affect any voice-reachable screen must update deriveVoiceRouteScreen, local .voice-action-contract.json reachability/targets, generated gateway artifacts, typed-search parity, and One Voice context snapshot expectations in the same change.
  12. Keep legacy query route inputs as compatibility only. Generated route.* actions should target canonical nested routes unless the action intentionally opens a canonical One capability route.
  13. Do not expose broken or unrelated route actions in realtime context. Published voice surface metadata may describe local controls and unavailable state, but it must omit executable actionId values unless that id exists in the generated gateway and is compatible with the active route, vault/persona/cache state, and UI affordance.

Compatibility authoring references:

  • references/wire-voice-action.md
  • references/wire-voice-navigation.md

These refine this owner; they do not introduce another routing authority.

Handoff Rules

  1. Generic UI structure routes to frontend.
  2. Route/request/response contracts route to backend-api-contracts.
  3. Vault and encrypted-storage boundaries route to security-audit.
  4. Documentation-home decisions route to docs-governance.
  5. Verification-policy changes route to quality-contracts.

Required Checks

cd hushh-webapp && npm run build:voice-gateway
cd hushh-webapp && npm run verify:voice-gateway
cd hushh-webapp && npm run typecheck
cd hushh-webapp && npm run test -- __tests__/voice/kai-action-gateway.test.ts __tests__/voice/capability-projection.test.ts __tests__/one-voice/live-client.test.ts __tests__/components/one-voice-hosting-readiness.test.tsx
cd consent-protocol && python3 -m pytest tests/test_one_adk_live_protocol.py tests/services/test_agent_chat_service.py -q
./bin/hushh docs verify

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.