mcpField
W
workspace-init

workspace-init

github.com/willoscarAgent workflows51740 installsUpdated 3w ago
Repository

About workspace-init

workspace-init prepares a research workspace in a specified directory by creating its base files and folders. It creates only missing items by default, preserves existing files unless overwrite is explicitly approved, and leaves workflow selection to a later routing step.

Key features

  1. 01Validates the target directory
  2. 02Creates base template files and folders
  3. 03Preserves existing files by default
  4. 04Checks core files and CSV schema
  5. 05Hands the workspace to workflow routing

Use cases

  1. 01Create a workspace for a research project
  2. 02Check and complete a partially initialized workspace

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/willoscar/research-units-pipeline-skills --skill workspace-init

After installing, type/workspace-initin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

assets/workspace-template/
CHECKPOINTS.md
DECISIONS.md
GOAL.md
queries.md
STATUS.md
UNITS.csv
assets/workspace-template/citations/
ref.bib
verified.jsonl
assets/workspace-template/outline/
claim_evidence_matrix.md
mapping.tsv
outline.yml
taxonomy.yml
assets/workspace-template/output/
DRAFT.md
QUALITY_GATE.md
RUN_ERRORS.md
SNAPSHOT.md
assets/workspace-template/papers/
core_set.csv
paper_notes.jsonl
papers_dedup.jsonl
papers_raw.jsonl
scripts/
run.py

Details

From the project README

Workspace Init

Initialization is a boundary: it creates Workspace-owned state and leaves existing state untouched unless overwrite is an explicit operator decision. It does not select a Workflow or execute a Unit.

Inputs

  • Target directory under workspaces/<name>/.
  • Optional explicit overwrite decision.

Outputs

  • STATUS.md, CHECKPOINTS.md, UNITS.csv, and DECISIONS.md.
  • GOAL.md and queries.md.
  • papers/, outline/, citations/, and output/ directories.

Steps

1. Validate the destination

Resolve the target path and reject the repository root. Inspect existing files before deciding whether initialization is missing, partial, or already complete. Never infer overwrite permission from a partial Workspace.

Completion criterion: the destination is a Workspace path and every existing file that could be replaced is known.

2. Materialize the base template

Copy the repository-owned template into the target. Default to create-missing; use --overwrite only after an explicit replacement decision.

Completion criterion: all missing base files and directories are materialized, and no pre-existing file was replaced without explicit permission.

3. Verify the core contract

Confirm that STATUS.md, UNITS.csv, CHECKPOINTS.md, and DECISIONS.md exist. Parse the UNITS.csv header and reject malformed CSV rather than leaving a superficially initialized Workspace.

Completion criterion: the four core files exist and UNITS.csv has the required schema.

4. Hand off to Workflow binding

Leave Workflow selection and Pipeline-specific Unit materialization to pipeline-router or the Pipeline adapter. The generic template is not evidence that a Goal has been routed.

Completion criterion: the Workspace can be passed to the router without requiring any state from chat history.

Context Pointers

  • Read assets/workspace-template/ only when inspecting or changing the base template contract.
  • Read the selected pipelines/*.pipeline.md only after Workflow binding.
  • Use research-pipeline-runner when the user asked to continue beyond initialization.

Script

Quick Start
uv run python .codex/skills/workspace-init/scripts/run.py \
  --workspace workspaces/<name>
All Options
  • --workspace <path>: target Workspace.
  • --overwrite: replace existing template-owned files after explicit approval.
  • --unit-id, --inputs, --outputs, --checkpoint: Pipeline-runner compatibility arguments.
Examples

Inspect the interface before use:

uv run python .codex/skills/workspace-init/scripts/run.py --help

Replace template files only after an explicit reset decision:

uv run python .codex/skills/workspace-init/scripts/run.py \
  --workspace workspaces/<name> \
  --overwrite

Troubleshooting

  • Existing files remain unchanged by default. This is the expected idempotent behavior, not an initialization failure.
  • Never point the script at the repository root; use workspaces/<name>/.

Comments

Markdown supported