--- name: maintain-workspace description: Audit and maintain a project's documentation and temporary delivery resources. Use to consolidate completed delivery records, retire finished worktrees and task-owned scratch files, or investigate disk pressure. Preserve active work, durable evidence and project boundaries; perform cleanup only within actual authority. --- # Maintain Workspace Keep the repository useful to its next human or agent, and retire temporary resources once their purpose has ended. This supports delivery and Complete; it is not a new lifecycle stage or permission to reset a project. Read the [workflow](references/bundle/_shared/development-workflow.md) and [delivery contract](references/bundle/_shared/delivery-contract.md), plus the project's current instructions, roadmap and checkpoint. Reuse an existing maintenance facility where suitable. Keep the operation proportionate: a finished worker may need one worktree removed; closing a feature may need documentation consolidation too. Read [host integration](references/bundle/_shared/host-integration.md) when resolving installed paths, commands or worker capabilities. ## Establish scope and authority Identify the repository, requested delivery scope, intended integration target, active writers, and whether the request authorises an audit, document edits, resource removal or some combination. Honour a read-only request. Reuse explicit standing cleanup permission without asking again, but implementation/merge permission alone does not authorise deleting arbitrary workspaces, history or caches. Under Orchestrate Delivery, audit at setup when useful, after accepted integration, before resource-heavy waves when disk pressure is known, and at closure. Perform eligible maintenance within the recorded grant. Missing removal authority leaves those candidates pending while unrelated authorised work continues. A standalone invocation can perform authorised maintenance without requiring an orchestration session. Workers report resource locations and propose retirement. The coordinator owns shared cleanup and confirms no assignment still uses the resource. This skill does not grant merge, release, deployment, history-rewrite or credential access. A permission rejection is not permission to retry through another tool or broader deletion command; report the rejected operation and reason, continue unaffected work, and seek the required approval through the host. ## Inventory before changing anything Inspect actual state; a worker's report is a lead, not proof. Lead with a short summary: estimated space recoverable (if relevant), eligible candidates, unresolved candidates and the concrete decision needed. Put the detailed inventory behind a disclosure or a link to the existing checkpoint, rather than making the human read it first: | Candidate | Keep / consolidate / remove / investigate | Reason and retained destination | Preservation and ownership evidence | Authority / blocker | |---|---|---|---|---| Record estimated space only where useful. Directory size is not guaranteed reclaimed space: hard links, shared stores and filesystem snapshots affect the result. Avoid scanning unrelated projects or printing secrets. Do not create a permanent audit file for every cleanup. For documents, inspect their content, inbound links, code/configuration references and remaining obligations. Check tracked, modified and untracked state. A folder name such as `docs`, `verification`, `scratch` or `tmp` does not establish disposability. Use available conversation context and Git history to identify prior drafts and unrelated work before asking who owns them. An unreferenced draft can still be intentional; preserve it when outside the cleanup scope or ownership remains uncertain. For execution resources, identify exact paths, their creating task/run, owner, repository/worktree registration, branch/head, integration target and evidence, dirty/untracked/ignored contents, and any live processes or host sessions using them. Useful read-only Git inspections include `git worktree list --porcelain`, per-worktree `git status --porcelain --untracked-files=all`, and `git ls-files --others --ignored --exclude-standard --directory`. These are inputs to a decision, not a deletion script. If cleanup is requested with no adequate grant for removal, finish the inventory and present the concrete candidates and consequences before asking. Never ask for blanket permission to delete every old-looking directory. For any removal batch, provide a reviewable manifest of exact resolved paths, with each worktree's expected head and retained reference. Counts, wildcard patterns and name ranges are summaries, not the removal boundary. Link or collapse the manifest; keep it in the conversation or existing checkpoint unless a separate file is useful. Execution must stay within the authorised manifest and recheck each candidate immediately before removal. ## Consolidate documentation Classify by continuing purpose: - **Keep current:** living capability specs and feature map, glossary, agreed design/source mappings, conventions, preferences, significant decision rationale, usage/operational documentation and reproducible verification procedures. - **Keep while needed:** active plans, checkpoints, worker/reviewer handoffs, pending operations, unresolved findings and exceptions, deferred acceptance, platform-specific gaps, and evidence still needed for review or integration. Completing one platform does not close another. - **Consolidate after acceptance:** completed phase plans, successive reviews/re-reviews and historical handoff prose. Preserve the final accepted outcome, source and integration revisions, evidence boundaries, significant corrections, actual decisions and outstanding obligations in an existing phase completion section or other concise record. - **Remove when redundant and preserved:** superseded execution notes, duplicate reports and regenerable inspection artifacts whose useful content has an authoritative home. Retain independent review provenance and any evidence needed by project retention rules. Preserving review provenance does not require keeping every review file in the working tree forever. Once its scope is accepted and no unresolved obligation depends on it, consolidate redundant reviews while retaining reviewer identity/role, reviewed revisions, significant findings and their resolution, evidence limits and the final outcome. Apply the preservation and link-repair checks below before retiring the originals. Do not remove test fixtures, qualification manifests, schemas, baseline data, scripts, provenance/licence notices or reference inputs merely because they live under `docs/`. Inspect consumers, including checks and generators. Old runbooks can still define deferred acceptance or operational recovery. Before deleting a tracked record, confirm its exact useful version is reachable through a retained Git reference and that the replacement summary is adequate. Git does not preserve current dirty or untracked bytes automatically. Preserve those through an authorised commit or approved durable backup first, excluding secrets; if preservation is unavailable, leave the file. An unreachable object ID or a private temporary directory alone is not durable preservation. Do not create commits or copy sensitive material merely to satisfy cleanup. Keep the current roadmap short and correct: completed outcomes become concise history; active and deferred work stays visible with stable IDs. Reconcile contradictions rather than appending another competing status paragraph. Do not mark delivery complete as a side effect of tidying records. Update inbound links and recovery pointers before removing their targets. Historical details can be referenced as a retained Git revision plus repository path, clearly labelled historical; do not leave a broken working-tree link pretending the file still exists. Avoid moving everything into an archive directory or creating a second specification. Respect any explicit audit/retention requirement. ## Retire execution resources ### Worktrees and review checkouts All of these must be established for each candidate: 1. **Ownership has ended.** The assigned worker/reviewer and any commands it started have finished or been stopped under actual authority. No other assignment, server, terminal process, pending review or recovery operation needs the path. Quiet output, a stale checkpoint, a clean tree or an empty process listing alone does not establish this; reconcile with the coordinator/host. Unknown ownership means keep and investigate. 2. **The result is preserved and accepted.** Confirm the expected head and intended integration target immediately before removal, plus applicable review and combined verification. For merge-based delivery, `git merge-base --is-ancestor ` establishes reachability, not acceptance. For squash/cherry-pick workflows, compare the actual delivered changes and retained evidence; ancestor failure is not proof of lost work or a reason to force removal. Unmerged work is retained unless its disposal is explicitly authorised and preservation requirements are met. 3. **No unique local contents will be lost.** Check staged/unstaged changes, untracked files and ignored contents. Ignored does not mean disposable: credentials, local databases, unique logs and fixtures can be ignored. Dependencies/build output are candidates only after confirming they are reproducible and not needed for pending offline verification. Preserve required logs and reports outside the retiring checkout first. 4. **The operation is bounded.** Resolve the exact candidate path and repository relationship; do not follow symlinks into another workspace, remove the current/main checkout, or operate on a parent containing active work. Recheck status/head/ownership just before the mutation. If they changed, stop and reassess that candidate. Assess acceptance at the candidate's task or review scope, separately from whole-feature acceptance. Outstanding feature decisions or an unrelated failed check do not automatically require retaining every checkout. State whether each pending finding/check affects that candidate and whether its specific local state is needed for review, reproduction or recovery. An accepted, preserved task may retire before the feature closes if all other conditions hold. Conversely, a clean merged tree and a claim that a failure is unrelated are insufficient without supporting evidence; uncertain relevance stays **Investigate**, not **Remove**. Cleanup never waives a failing delivery gate. Remove eligible Git worktrees using the host's supported worktree lifecycle tool, or `git worktree remove ` when appropriate. Preserve branches by default. Branch deletion, stale registration pruning and history cleanup are separate scoped actions, not automatic consequences. A locked worktree or removal refusal needs investigation; never automatically add `--force`, unlock it or fall back to recursive deletion. Preserve a checkout needed for unmerged delivery even when its tests have passed. For independent review clones, apply the same ownership, unique-content and preservation checks; remove only the identified task-owned clone within the grant. Do not assume every folder under a host scratch root belongs to this run. ### Temporary files, caches and generated output Prefer exact task-owned scratch directories whose creating run and lifecycle are known. Retire them after useful findings, reproduction instructions and required artifacts have been saved durably and no process needs them. Keep a small resource list in the existing assignment/checkpoint when creating temporary resources, including purpose and retirement condition, rather than reconstructing ownership later. Never sweep `/tmp`, a host-wide session directory, another project's scratch tree, global package stores, toolchains, model downloads or shared caches. Their cleanup needs its own identified scope and authority. Do not infer safety from age or size. Local build directories may be expensive or impossible to regenerate offline; explain that consequence when relevant. Free-disk pressure does not waive active-work or preservation checks. Where cleanup is interrupted, reconcile which exact paths were removed and which remain before continuing. Do not repeat a broad deletion or infer success from missing output. ## Verify and report For documentation changes, inspect the diff, check relative links and references, and run relevant documentation/generator checks. If a removed artifact is a check input, keep it or explicitly change and verify the consuming workflow within scope. A full application suite is unnecessary for isolated prose cleanup unless the configured gate requires it. After resource removal, inspect the worktree registry, retained branches and integration revision; confirm intended remaining checkouts still exist and their work was not changed. Measure disk space again if space recovery was the objective, distinguishing estimates from observed filesystem change. Record a short outcome in the existing checkpoint or completion record: what was consolidated/removed, where durable history lives, retained branches, verification, and anything kept with its reason. Clear retired paths from active recovery references and reconcile dashboard/roadmap summaries. Pending cleanup is distinct from product acceptance; do not hide a disk blocker or hold an otherwise accepted feature open solely for optional housekeeping. Leave document changes reviewable and uncommitted unless committing is authorised. Follow the delivery contract's focused Conventional Commit policy when committing; never mix unrelated application changes into a cleanup commit. Finish with a concise human summary and any concrete remaining action, not an exhaustive file listing.