Workspace Governance

A methodology-first workspace governance skill for AI agents. Focuses on principles, decision framework, and safe execution patterns instead of fixed directo...

Security Scan

The skill's files, runtime instructions, and required capabilities are coherent with a workspace-governance purpose — it reads local policy files and scans a declared workspace, requires no external credentials, and enforces confirmation for destructive actions.

Purpose & Capability

Name/description match the actual contents: a methodology-first governance contract plus optional per-platform overlays and validation scripts. The included platform profiles and check scripts (OpenClaw, Hermes, Cursor, Claude) are appropriate for a governance skill that adapts to different runtimes.

Instruction Scope

SKILL.md explicitly instructs the agent to read SKILL_ADAPT.yaml and platform overlay profiles (tools/adapt-profiles/*) and to scan only within a declared workspace_root. That is expected for this skill, but it does mean the agent will read repository files and may inspect environment detection signals (e.g., OPENCLAW_HOME, HERMES_HOME) to choose overlays — the user should be comfortable with local file inspection. The skill also enforces confirmation gates for destructive actions and a non-interactive 'blocked' policy, which limits risky autonomous behavior.

Install Mechanism

Instruction-only skill with no install spec. Files are repository docs and small shell validation scripts (grep/grep checks); nothing downloads or executes remote artifacts. This is the lowest-risk install posture.

Credentials

The skill declares no required environment variables or credentials. Platform profiles reference environment names only as detection signals (to decide which overlay to load), which is proportionate to a policy/adaptation role. No secret-exfiltration or credential requirements are present.

Persistence & Privilege

always:false and normal model invocation settings. The skill does not request permanent platform-wide privileges or modifications to other skills. It does propose writing governance logs (SKILL_ADAPT.yaml logging.file) — users should confirm desired log location and permissions before enabling.

Assessment

This skill appears coherent and self-contained. Before installing, review SKILL_ADAPT.yaml and any platform overlay (tools/adapt-profiles/*) to ensure the declared workspace_root, log file path, and protected/immutable lists match your expectations. Run the included local checks (bash scripts/check_*.sh or make check) in a safe environment to verify behavior. If you plan to run it non-interactively, ensure the runtime provides a safe confirmation channel (or accept that the skill will block on 'ask-user' items). Finally, confirm that logging.file in SKILL_ADAPT.yaml points to an appropriate location to avoid writing logs to sensitive directories.

Methodology-first workspace governance for AI agents.

Chinese Guide

For Chinese readers:

• Quick entry: README.zh-CN.md
• Detailed manual: references/治理手册.zh-CN.md

Purpose

This skill teaches an agent how to design a workspace management strategy that fits its own runtime, platform, and user preferences.

This is not a single directory template and not a rigid SOP.
The agent should adapt based on context, then execute safely.

Core Principles

1. Boundary before structure: define what can be touched first.
2. Plan before action: generate a governance plan before file operations.
3. Reversible before optimized: preserve rollback paths and avoid irreversible changes.
4. Fit current system first: reuse existing conventions when they are workable.
5. User control at key points: destructive operations require explicit confirmation.
6. Evidence-driven decisions: only propose actions based on real scan results.

When to Use

• Workspace is messy and needs cleanup or reorganization.
• User asks to archive/close finished work.
• User asks to create a new project with clear boundaries.
• User asks for workspace audit/health check.
• Agent needs to establish sustainable file governance rules.

Required Capabilities and Preconditions

Before execution, the agent should verify runtime capabilities:

1. File/dir inspection and manipulation (ls, move, rename, archive, delete).
2. Logging output capability (file or structured output sink).
3. User confirmation capability for ambiguous/destructive actions.

Preconditions:

• workspace_root must be defined (user-provided or default current directory).
• If workspace_root is broad/high-risk, require explicit confirmation before scanning.
• If confirmation capability is unavailable, ask-user items are blocking items.

Scope and Boundaries

The agent must define these before execution:

• workspace_root: the manageable boundary for this task.
• immutable_dirs: directories that must never be moved/deleted/renamed.
• protected_files: sensitive files (keys, env, certs, VCS metadata).
• risk_level: low/medium/high based on destructive potential.

If workspace_root is too broad (for example home root), require explicit confirmation before scanning.

Adaptation Model (Platform-Agnostic)

The agent should adapt strategy using this order:

1. User explicit constraints and preferences.
2. Current repository/project conventions.
3. Platform/runtime restrictions.
4. Conservative fallback defaults.

Do not force a fixed folder structure unless the user requests standardization.

Optional Adapt Block

SKILL_ADAPT:
  workspace_root: <path>
  immutable_dirs: [dir1, dir2]
  protected_files: [pattern1, pattern2]
  cache_policy: separate # separate | consolidate
  naming_policy: inherit # inherit | enforce

Adapt Loading Rules (Mandatory)

If SKILL_ADAPT.yaml exists, the agent must read it before planning and execution. If platform profiles exist (for example tools/adapt-profiles/openclaw.yaml), the agent should load the matching profile as an overlay.

Configuration precedence:

1. User explicit instruction in current session.
2. SKILL_ADAPT config.
3. Repository conventions detected from files.
4. Conservative defaults from this skill.

If SKILL_ADAPT parsing fails:

• Do not silently ignore.
• Fall back to conservative defaults.
• Record a warning in governance logs.

Profile merge semantics:

• immutable_dirs: union (security items only increase)
• protected_files: union (protection only increases)
• destructive_guard: override allowed only when strictness is not reduced

Decision Framework

Before any move/delete action, produce a governance plan with:

1. Current State Summary
   • What is cluttered
   • What is ambiguous
   • What is sensitive
2. Target Strategy
   • Keep, move, rename, archive, delete policy
   • Naming and lifecycle policy
   • Cache/temp policy
3. Risk and Rollback
   • Risks per action class
   • Rollback method and checkpoints
4. User Confirmation Items
   • Items that need user decision
   • Items excluded from automation

Plan Output Template

Item	Current	Proposed Action	Target	Risk	Reason
example.tmp	root	delete	—	medium	temporary artifact
report-final.docx	root	ask user	docs or archive	low	destination ambiguous

Execution Pattern (Generic)

Use this pattern regardless of platform:

1. Detect context and runtime capabilities.
2. Load SKILL_ADAPT (if present) and resolve effective policy by precedence.
3. Detect boundaries (workspace_root, immutable/protected scope).
4. Scan inside workspace_root only.
5. Classify findings: keep/move/rename/archive/delete/ask-user.
6. Generate plan table with reasons, risks, and rollback checkpoints.
7. Get confirmation for destructive or ambiguous actions.
8. Execute in small batches with checkpoint logs.
9. Report results and failures.
10. Record governance log for traceability.

If multiple user intents exist, process sequentially and reconfirm between destructive batches.

Non-Interactive Safety Policy (Mandatory)

For non-interactive runtimes (cron, background subagent, execute-only environments):

• If any item is classified as ask-user, the agent must stop with status blocked.
• The agent must output a pending_decisions list and required user input.
• The agent must not silently skip, auto-approve, or auto-delete ambiguous items.
• Destructive actions without confirmation capability must be refused (fail-fast).

Recommended blocked output:

Item	Proposed Action	Block Reason	Needed Input
report-final.docx	ask-user	no confirmation channel	choose destination

Classification Heuristics (Flexible)

Use heuristics, not hard-coded folders:

• Project artifacts: source code, configs, tests, docs tied to one project.
• Reusable assets: media or references used across projects.
• Ephemeral data: cache/tmp/build artifacts/log leftovers.
• Agent/runtime state: tool configs, sessions, internal runtime files.
• Ambiguous items: unclear ownership or destination.

Rules:

• Ambiguous items must be escalated to user decisions.
• Never silently rename if semantic meaning may change.
• Never overwrite existing files on move.

Safety Baseline (Mandatory)

Never Touch Without Explicit User Approval

• Version control metadata (.git/, .svn/, .hg/)
• Secret material (*.key, *.pem, *.p12, private credentials)
• Environment files (.env and equivalents)
• Agent/runtime configuration directories

Destructive Action Guardrails

• Always show dry-run plan first.
• Require explicit confirmation for delete and bulk move.
• Use collision-safe naming on move.
• Keep operation logs and failure reasons.
• Stop and ask user if unexpected high-risk patterns are detected.

Standard Operation Modes

1) Organize

Goal: improve discoverability and reduce clutter with minimal disturbance.

2) Create Project

Goal: initialize a new work area aligned with existing conventions.

3) Archive Project

Goal: transition inactive work into retrievable cold storage with metadata.

4) Hygiene Check

Goal: audit quality signals and output fix recommendations.

Note: The agent should choose implementation details based on local system constraints, not this document's examples.

Skill Interoperability (Optional)

workspace-governance can run standalone, but some scenarios may benefit from companion skills/tools:

• Git or GitHub-related archive verification: use Git/GitHub skill/tooling.
• Cloud/object storage archive lifecycle: use cloud storage skills/tools.
• Team approval workflow before destructive batches: use workflow/approval skills/tools.

Interoperability rule:

• Never assume companion skills are present.
• If a companion capability is required by user intent but unavailable, report blocked with required dependency.

Quality Signals for Audit

Recommended checks:

• Boundary clarity (what is managed vs protected)
• Root clutter level
• Naming consistency
• Build/cache residue
• Archive lifecycle completeness
• Recoverability (rollback/readability of logs)

Output style:

• Pass items with clear evidence.
• Violations with fix suggestion and risk level.
• Summary with actionable next steps.

Logging and Traceability

The agent should keep a lightweight operation record, including:

• Date (YYYY-MM-DD)
• Intent type (organize/create/archive/audit)
• Planned changes vs executed changes
• Success/failure counts
• Unresolved decisions pending user input

Rollback and Checkpoint Schema (Minimum)

Each execution should create:

1. A pre-execution checkpoint (checkpoint_before).
2. A checkpoint per batch (checkpoint_batch_<n>).
3. A final checkpoint (checkpoint_after).

Minimum log fields:

• timestamp (YYYY-MM-DD HH:mm:ss)
• intent (organize/create/archive/audit)
• batch_id
• action (move/rename/archive/delete)
• source_path
• target_path
• result (success/failure/blocked)
• reversible (yes/no)
• rollback_ref (checkpoint id or recovery note)

Anti-Patterns to Avoid

• Forcing a universal directory layout on every system
• Performing bulk cleanup without a dry-run plan
• Treating unknown files as disposable
• Optimizing structure while ignoring user workflow habits
• Mixing agent state and user business content without explicit mapping

Minimal Example (Reference Only)

Example principles in action:

1. Detect workspace boundary and immutable dirs.
2. Scan only within boundary.
3. Mark ambiguous files as ask-user.
4. Confirm plan before delete/move.
5. Execute and log.

This example is illustrative, not normative.

Author

• 作者: Mars2003 （GitHub）
• 日期: 2026-04-28