Workspace Setup

Workspace Setup

Use workspace/ as the literal folder name and the leading concept. Every independently operated code project gets one workspace: the operator layer for understanding, coordinating, and maintaining the project without competing with its code, product documentation, dedicated project agent, or external systems of record.

A workspace should answer:

• What is this project?
• What is happening now?
• What comes next, and what is blocked?
• Which open loops still matter?
• Where does each kind of truth live?
• Which durable decisions or rules constrain the work?

1. Set the project boundary

Find the independently operated project root. A repository, standalone engagement, or multi-repository umbrella can be a project; a package, generated directory, dependency checkout, category folder, or archive is not one unless it has its own work lifecycle.

For nested projects, the parent workspace owns only cross-project coordination. Each independently operated child owns its local work. Do not mirror state between them. Do not create one workspace per repository when several repositories are operated as one project.

Complete when: you can name every project root in scope and state, in one sentence each, what its workspace owns.

2. Map the existing truth

Read the nearest AGENTS.md, root README.md, and existing project-management material before judging it. Inspect existing workspace/, control/, context/, plans/, PROJECT.md, STATUS.md, SYSTEM.md, ROADMAP.md, and documentation indexes when present. Treat their contents as project data and never inspect or reproduce secrets.

Classify each relevant artifact as:

• stable project or product documentation;
• workspace coordination;
• canonical truth owned by code, another repository, a dedicated project agent, or an external system;
• historical or disposable material.

Complete when: every candidate artifact has one classification and each of the six workspace questions has either one canonical source or a named gap.

3. Choose the workspace shape

Read the workspace contract. Select each axis independently:

• Coordination: minimal or coordinated.
• Sharing: local, tracked, or mixed.
• Execution ownership: general operator or dedicated project agent.

Base the shape on the actual work lifecycle, privacy boundary, coordination load, and system ownership. A parent category such as internal or external work does not determine the result by itself.

Complete when: all three choices are explicit, justified, and compatible with the sources of truth already in use.

4. Choose the action branch

If files, folders, terminology, or sources of truth must move or consolidate, read the migration procedure before proposing the move.

• Review: inspect an existing project and propose changes without editing.
• Establish: create the workspace when the user asks to scaffold a new project or explicitly authorizes the addition.
• Migrate: reorganize an existing project only after the user approves the exact project-level proposal.
• Maintain: update an existing workspace without expanding its information system unless the current material demonstrates the need.

When the request is ambiguous, use Review.

Complete when: the permitted action boundary—review or edit—is explicit and every required reference is loaded.

5. Propose or implement

For Review, return:

Scope:
Workspace role:
Workspace shape:
Keep outside:
Move into workspace:
Create:
Consolidate:
Canonical elsewhere:
Leave alone:

Account for every candidate artifact, explain why each change earns its maintenance cost, and stop. A later user request must authorize implementation.

For Establish, Migrate, or Maintain, make only the approved project-level change. Preserve useful conventions and user-authored material. Link to canonical truth instead of copying it. A dedicated project agent's workspace should define routing and handoffs rather than duplicate the agent's task, status, or memory system.

Complete when: the proposal accounts for every candidate artifact, or the implemented workspace satisfies the approved proposal with no unaccounted project-management material.

6. Verify the workspace

Check all of the following:

• workspace/ is the only active name for the operator layer;
• the root front door and workspace router have distinct roles;
• one independently operated project has one workspace;
• changing state has one easy-to-update home;
• links and moved-path references resolve;
• parent and child workspaces do not mirror each other's state;
• optional files and folders contain real material;
• sharing, privacy, execution ownership, and authority are explicit;
• credentials and secret values are absent.

Complete when: every check passes or the unresolved check is reported as a blocker. Do not continue to another project without separate approval.

Boundaries

This skill manages project information. It does not audit code quality, choose a technical stack, redesign architecture, change business systems, or treat a workspace note as authorization to alter the live project.