v4.1 Skill OS Foundation Plan

1. Objective

Design the v4.1 Skill OS Foundation as a planning-only architecture layer for turning MultiModel Dev OS from a project configuration standard into a reusable workflow operating system.

The objective is to define a structured prompting layer, skill registry, tool permission model, guardrail model, context loading strategy, and future business-operator workflow layer while preserving the current zero-runtime-dependency CLI and existing public commands.

v4.1 should not begin as a feature-heavy runtime expansion. It should start with schemas, registries, documentation, validation rules, and conservative CLI inspection surfaces.

Sprint B adds validation for the Sprint A schema and registry layer. Sprint C adds read-only CLI inspection for that layer. Sprint D adds declarative guardrails. Sprint E adds optional workflow metadata references to Skill OS registries. Sprint F adds draft-only business operator templates. These sprints do not execute automation, enforce permissions, or change existing workflow execution behavior.

2. Current Architecture Fit

The current repository already has several primitives that fit the Skill OS direction:

• .ai/prompts/ stores reusable prompt templates.
• .ai/skills/ stores reusable markdown skills.
• .ai/checks/ stores pre-action and post-action checklists.
• .ai/registries/tools.yaml maps supported tools and protocols.
• .ai/registries/workflows.yaml maps repeatable workflow steps.
• .ai/plugins/catalog.yaml describes workflow packs, skills, checks, and prompts.
• .ai/schema/ already contains JSON schema assets for config, templates, adapters, plugins, registry policy, and trusted keys.
• src/cli/handlers/skills.js, src/cli/handlers/workflow.js, src/cli/handlers/plugin.js, and src/cli/handlers/catalog.js provide natural CLI integration points.
• docs/skill-authoring.md, docs/workflow-orchestration.md, docs/tool-registry.md, and docs/tui-safety.md already describe adjacent concepts.

The v4.1 plan should extend these primitives instead of inventing a parallel system. The core design principle is: structured metadata first, runtime automation second.

3. Proposed File Structure

Sprint A adds the initial schema and example layer for v4.1. Sprint B validates that layer. Sprint C exposes it through read-only inspection. Sprint E connects workflow metadata to the layer. Sprint F adds generic operator templates:

.ai/
  prompts/
    race-plus.md
    operator-*.md
  skills/
    operator-*.md
  registries/
    skills.yaml
    prompt-templates.yaml
    tool-permissions.yaml
    agent-clusters.yaml
  schema/
    skill.schema.json
    prompt-template.schema.json
    tool-permission.schema.json
    agent-cluster.schema.json
    workflow.schema.json
docs/
  business-operator-layer.md

Sprint A documentation:

docs/
  structured-prompts.md
  skill-registry.md
  tool-permissions.md
  agent-clusters.md

Potential source modules, if implementation is approved later:

src/
  skill/
    registry.js
    validation.js
    triggers.js
  prompt/
    templates.js
    race-plus.js
  permissions/
    tools.js
    guardrails.js
  skill-os/
    validation.js
    registry-loader.js

Sprint B implements src/skill-os/validation.js as a validation-only foundation module.

Sprint C implements src/skill-os/registry-loader.js and src/cli/handlers/skill-os.js for local read-only inspection.

Sprint E extends .ai/registries/workflows.yaml with optional skill_os metadata and validates references without changing execution.

4. RACE+ Prompting Layer

RACE+ should become the standard prompt contract for reusable task templates.

Required fields:

• Role
• Action
• Context
• Expectation
• Constraints
• Output format
• Verification
• Next action

Design notes:

• Keep prompt templates declarative and inspectable.
• Use placeholder variables with explicit names and descriptions.
• Keep prompts portable across Codex, Claude, Gemini, Cursor, VS Code, and terminal agents.
• Avoid tool-specific assumptions in base templates.
• Allow optional tool-specific adapters to render templates differently.

Potential template structure:

id: release-audit
name: Release Audit
version: 1.0.0
race_plus:
  role: Release engineer
  action: Audit release readiness
  context:
    required_files:
      - package.json
      - CHANGELOG.md
      - docs/release-state.md
  expectation: Produce a blocker-first release report.
  constraints:
    - Do not publish.
    - Do not tag unless explicitly approved.
  output_format: markdown-report
  verification:
    - npm run verify
  next_action: Wait for maintainer approval.

5. Skill Registry Design

The current skill model is markdown-first. v4.1 should add a registry layer that makes skills discoverable, triggerable, and validatable without replacing markdown skills.

Proposed .ai/registries/skills.yaml fields:

• id
• name
• version
• description
• category
• triggers
• required_context
• provided_outputs
• risk_level
• permissions
• recommended_models
• token_budget
• skill_file
• checks
• examples

Trigger model:

• Explicit trigger: user names a skill or workflow.
• Intent trigger: user request matches declared trigger phrases.
• File trigger: active files match declared patterns.
• Workflow trigger: a workflow step references the skill.
• Safety trigger: a risky operation requires a guardrail skill.

Validation rules:

• Skill IDs must be stable, lowercase, and slug-safe.
• Every registry entry must point to an existing markdown skill.
• Required context files must be relative workspace paths.
• Risk level must map to the tool permission model.
• Skills that write files must declare checks.
• Skills that touch release, deploy, payment, DNS, credentials, or ad spend must require confirmation.

6. Tool Permission Model

v4.1 should define a permission registry before expanding automation.

Tool classes:

• read-only: inspection, search, read, status, list, validate.
• draft-only: create proposed text, release notes, plans, or patches without applying external changes.
• write-with-confirmation: local file writes, commits, labels, drafts, issue comments, and other reversible changes after explicit approval.
• restricted-admin: publish, deploy, DNS, billing, ad spend, production credentials, package registry mutation, tag movement, release publishing.

Potential .ai/registries/tool-permissions.yaml fields:

• tool_id
• display_name
• class
• allowed_operations
• blocked_operations
• requires_confirmation
• requires_clean_worktree
• requires_validation
• audit_log

Rules:

• Restricted-admin operations must never be inferred from adjacent tasks.
• Publish and deploy operations require explicit current-turn approval.
• Commands that can delete, reset, force push, rotate secrets, spend money, or expose credentials require hard confirmation.
• Tool permissions must be explainable in docs and visible in CLI inspection output.

7. Hooks and Guardrails

In v4.1 Sprint D, the declarative hooks and guardrails layer is defined and validated.

Minimum guardrails:

• Pre-tool destructive command blocking.
• Secret and environment dump blocking.
• Publish, deploy, DNS, and ad-spend confirmation.
• Post-change validation reminders.
• Session summary capture.

Hook types (implemented as declarative entries):

• pre_tool: inspect intended tool operation before execution.
• pre_write: inspect file write scope before local mutation.
• pre_external_write: inspect operations that affect remote systems.
• post_change: recommend validation commands after local changes.
• session_end: summarize decisions, state, and next steps.

Guardrail design:

• Declarative and Advisory: Guardrails in v4.1 are declarative and advisory only. No live command blocking, MCP tool interception, or runtime automation is active.
• Deterministic and Advisory Flags: Validation requires validation.deterministic: true and validation.advisory_only: true for all v4.1 entries.
• Safety Documentation: Rules are documented in [docs/hooks-and-guardrails.md](file:///f:/multimodel-dev-os/docs/hooks-and-guardrails.md).

8. Agent Cluster Model

Agent clusters should be a routing concept, not a new autonomous execution system.

Proposed clusters:

• Core technical: coding, review, testing, architecture, release validation.
• Growth marketing: SEO, competitor analysis, content planning, campaign briefs.
• Business ops: inbox triage, meeting recap, SOPs, weekly review, project pulse.
• DevOps security: deployment safety, secrets review, registry trust, incident checks.
• Document production: briefs, reports, proposals, slide outlines, client-ready documents.
• Academic execution: research planning, citations, study guides, structured writing.

Each cluster should define:

• Scope.
• Typical skills.
• Allowed tool classes.
• Required context files.
• Outputs.
• Validation expectations.

9. Context Loading Strategy

v4.1 should strengthen context discipline rather than loading more files by default.

Principles:

• Current state beats stale memory.
• Small focused context beats broad dumps.
• Skills declare the context they need.
• Routes should load only the docs, registries, and files needed for the task.
• Session summaries should preserve decisions, blockers, and next actions.

Potential context files:

• .ai/context/current-state.md
• .ai/context/release-state.md
• .ai/context/operator-state.md
• .ai/context/growth-state.md

Loading modes:

• minimal: task title, active file, core rules.
• skill-scoped: skill metadata plus declared required files.
• workflow-scoped: workflow registry entry plus step context.
• release-scoped: release state, changelog, package metadata, CI state.
• operator-scoped: business operator state plus relevant templates.

10. Business Operator Layer

The business operator layer should reuse the same safety model as technical workflows.

Future operational skills:

• Inbox triage.
• Meeting recap.
• KPI snapshot.
• Weekly review.
• SOP builder.
• Project pulse.
• Content brief system.
• Creative intelligence.

Sprint F adds the initial public-facing template foundation for these operator skills. The templates are draft-only, generic, and designed for provided input. They do not call connectors, send messages, publish content, spend money, or update external systems.

Sprint G adds migration and authoring documentation so adopters can move from markdown skills, raw prompts, and workflow-only YAML into Skill OS metadata without assuming runtime automation or permission enforcement.

Design boundaries:

• Default to read-only or draft-only.
• Never send emails, update calendars, publish content, or spend money without explicit confirmation.
• Avoid storing private business details in public templates.
• Keep examples generic and product-facing.
• Use permission classes to separate drafting from external writes.

11. CLI/API Impact

Sprint C adds:

multimodel-dev-os skill-os status
multimodel-dev-os skill-os validate
multimodel-dev-os skill-os list skills
multimodel-dev-os skill-os list prompts
multimodel-dev-os skill-os list permissions
multimodel-dev-os skill-os list clusters
multimodel-dev-os skill-os show skill <id>
multimodel-dev-os skill-os show prompt <id>
multimodel-dev-os skill-os show permission <id>
multimodel-dev-os skill-os show cluster <id>

These commands are read-only. They do not execute automation, enforce permissions, write files, or call external systems.

Sprint E also updates workflow show and workflow list inspection output so declared Skill OS metadata is visible. workflow run semantics are unchanged.

Initial CLI impact should be inspection and validation only:

• skills can continue listing workspace skills.
• show-skill can remain backward compatible.
• A future skill validate or expanded validate-skill can validate registry metadata.
• A future prompts command can list RACE+ templates.
• A future permissions or tool permissions command can inspect tool classes.

No v4.1 planning work should remove existing commands, change output contracts, or require new runtime dependencies.

12. Backward Compatibility

Backward compatibility requirements:

• Existing .ai/skills/*.md files remain valid.
• Existing prompt markdown files remain valid.
• Existing workflow registry entries remain valid.
• Existing plugin catalog metadata remains valid.
• Existing CLI commands remain stable.
• New registries should be optional until validated and documented.

Migration path:

• Phase 1: document schemas and examples.
• Phase 2: add optional validation.
• Phase 3: add CLI inspection.
• Phase 4: add safe workflow integrations.

13. Security Model

Security posture:

• Keep zero runtime dependencies.
• Keep plugin and skill systems declarative.
• Do not allow arbitrary script execution from registries.
• Validate paths and block traversal.
• Classify tool permissions before enabling automation.
• Require explicit confirmation for restricted-admin operations.
• Treat credentials, .env, .npmrc, package publishing, deployment, DNS, and ad-spend as restricted.
• Keep audit logs for high-risk approvals when implementation is approved.

The security model should align with existing registry signing, trust-store, plugin sandboxing, and TUI safety docs.

14. Test Strategy

Planning target test coverage:

• YAML parser fixtures for skill, prompt, and permission registries.
• Schema validation tests for new registry shapes.
• Path safety tests for referenced skill and prompt files.
• CLI handler tests for list/show/validate commands if added.
• Guardrail rule tests for destructive commands, secret dumps, publish/deploy confirmation, and restricted-admin classification.
• Fixture quality tests for bundled examples.
• Regression tests to prove existing skills and workflows still load.

Validation commands should remain:

npm run check:build
npm test
npm run verify
npm run docs:build
npm pack --dry-run

15. Documentation Strategy

Documentation should be introduced before automation:

• docs/structured-prompts.md
• docs/skill-registry.md
• docs/tool-permissions.md
• docs/hooks-and-guardrails.md
• docs/agent-clusters.md
• docs/context-discipline.md
• docs/business-operator-layer.md

Existing docs to update later:

• docs/skill-authoring.md
• docs/tool-registry.md
• docs/workflow-orchestration.md
• docs/tui-safety.md
• docs/future-ai-os-roadmap.md
• README roadmap section

Docs should clearly distinguish planned architecture from released behavior.

16. Implementation Sprints

Recommended v4.1 sprint sequence:

1. Sprint A - schemas and examples: add prompt, skill, permission, and cluster schema drafts plus example registries.
2. Sprint B - validation engine: add validation checks for new registries and referenced files.
3. Sprint C - CLI inspection: add read-only list/show commands for skills, prompts, permissions, and clusters.
4. Sprint D - guardrail docs and checks: add declarative guardrail checks and verification coverage.
5. Sprint E - workflow integration: allow workflows to reference skill IDs and required context without changing execution safety.
6. Sprint F - business operator templates: add draft-only templates for operational skills.
7. Sprint G - docs and migration guide: document adoption and migration from markdown-only skills.
8. Sprint H - release hardening: audit package contents, CI, docs, and public examples.

17. Release Strategy

v4.1 should be released only after the planning docs are converted into tested, documented, backward-compatible primitives.

Recommended release gates:

• No runtime dependency additions.
• Existing CLI smoke tests pass.
• Existing registries remain compatible.
• New schemas are optional and validated.
• Guardrails are documented and tested.
• Package contents remain clean.
• README does not overstate unreleased automation.

Release state should follow docs/release-state.md:

• prepared
• pushed
• tagged
• draft release created
• npmjs published
• GitHub release published
• GitHub Packages mirrored
• fully released

18. Risks

Key risks:

• Scope creep from planning into premature automation.
• Overloading context with too many skills or templates.
• Creating registries that duplicate plugins and workflows instead of connecting them.
• Introducing permission concepts that are not enforced.
• Ambiguous tool classes for external systems.
• Public docs overstating features before implementation.
• Making business-operator workflows look like private operational dumping instead of productized templates.

Mitigations:

• Keep v4.1 schema-first and validation-first.
• Keep defaults read-only or draft-only.
• Use explicit risk levels and permission classes.
• Keep examples generic.
• Require tests for every registry shape.

19. Open Questions

• Should skill registry metadata live beside each markdown skill or in a central .ai/registries/skills.yaml file?
• Should RACE+ prompt templates be YAML-first, markdown-first, or both?
• Should permission classes attach to tools, skills, workflows, or all three?
• Should guardrails be advisory in v4.1 and enforceable in v4.2?
• Should business operator templates ship in core or as an optional catalog pack?
• Should agent clusters be user-facing CLI concepts or documentation-only routing groups first?
• What is the smallest useful CLI surface for v4.1 without adding new runtime behavior?

20. Final Recommendation

Proceed with v4.1 as a Skill OS Foundation release only after explicit implementation approval.

The recommended first implementation step is a schema and validation sprint for RACE+ prompt templates, skill registry metadata, and tool permission classes. Keep all automation read-only or draft-only until the permission model and guardrails are proven through tests and docs.

Do not make v4.1 a broad automation release. Make it the stable foundation that lets future automation scale safely.