Project Scaffold

Initialize and manage research project structure. Creates standardized directories and metadata files that enable seamless handoffs between skills.

Why This Exists

Without scaffolding, every skill asks "Where are your data?" and "Where should I save this?" Project scaffold solves this by:

• Creating canonical paths that all skills respect

• Tracking project state so coordinator knows what's done

• Enabling prerequisite checking ("Can't write findings until analysis is done")

• Providing audit trail for reproducibility

Project Types

Scaffold supports three project types with different structures:

Type Use When Key Directories

qualitative

Interview research, ethnography, content analysis transcripts, codebook, memos

quantitative

Survey, experiments, secondary data analysis raw_data, scripts, models, figures

mixed

Combining qual + quant methods Both sets of directories

Two Modes

Mode 1: New Project

Creates full directory structure and blank metadata files.

/project-scaffold

Title: Why Activists Leave Social Movements Type: qualitative

Mode 2: Adopt Existing Project

Maps existing directories to canonical paths without moving files.

/project-scaffold adopt

My data is in analysis/ My literature is in lit-review/pdfs/

Workflow

Step 1: Gather Project Info

Ask for:

• Project title (required)

• Project type: qualitative , quantitative , or mixed (required)

• Research question (recommended)

• Mode: new or adopt

Step 1b: Initialize Git

After gathering project info, ensure the project directory is a git repository:

• If not already a git repo, run git init

• After creating the directory structure (Step 2), make an initial commit: git add -A && git commit -m "project-scaffold: Initial project structure"

All downstream skills use git for version tracking. Do not create version-suffixed copies of files (e.g., -v2 , -final , -working ). The git history serves as the version trail.

Step 2: Create/Map Structure

Qualitative Projects

project-name/ ├── data/ │ ├── raw/ # Original transcripts, fieldnotes │ └── clean/ # Processed/anonymized versions ├── analysis/ │ ├── codes/ # Codebook, code definitions │ ├── memos/ # Analytical memos │ └── outputs/ # Quote database, matrices ├── library/ │ ├── pdfs/ # PDF and EPUB files │ └── markdown/ # Converted markdown versions ├── literature/ │ ├── database/ # lit-search outputs │ ├── notes/ # reading-agent outputs │ └── synthesis/ # lit-synthesis outputs ├── drafts/ │ ├── sections/ # Individual section drafts │ └── submission/ # Submission-ready manuscripts ├── submissions/ # Final manuscripts ├── references.bib # Canonical bibliography (used by all skills) ├── project.yaml # Project configuration ├── progress.yaml # State tracking └── README.md # Project overview

Quantitative Projects

project-name/ ├── data/ │ ├── raw/ # Original datasets │ ├── processed/ # Cleaned/transformed data │ └── codebooks/ # Variable documentation ├── scripts/ │ ├── cleaning/ # Data preparation scripts │ ├── analysis/ # Statistical analysis scripts │ └── visualization/ # Figure generation scripts ├── models/ # Saved model objects, outputs ├── figures/ # Generated plots and visualizations ├── tables/ # Generated tables ├── library/ │ ├── pdfs/ # PDF and EPUB files │ └── markdown/ # Converted markdown versions ├── literature/ │ ├── database/ │ ├── notes/ │ └── synthesis/ ├── drafts/ │ ├── sections/ │ └── revisions/ ├── submissions/ ├── references.bib ├── project.yaml ├── progress.yaml └── README.md

Mixed Methods Projects

project-name/ ├── data/ │ ├── qualitative/ │ │ ├── raw/ # Transcripts, fieldnotes │ │ └── clean/ │ └── quantitative/ │ ├── raw/ # Datasets │ ├── processed/ │ └── codebooks/ ├── analysis/ │ ├── qualitative/ │ │ ├── codes/ │ │ ├── memos/ │ │ └── outputs/ │ └── quantitative/ │ ├── scripts/ │ ├── models/ │ └── outputs/ ├── figures/ ├── tables/ ├── library/ │ ├── pdfs/ # PDF and EPUB files │ └── markdown/ # Converted markdown versions ├── literature/ │ ├── database/ │ ├── notes/ │ └── synthesis/ ├── drafts/ │ ├── sections/ │ └── revisions/ ├── submissions/ ├── references.bib ├── project.yaml ├── progress.yaml └── README.md

Step 3: Write Metadata Files

Create project.yaml with user input. Schema varies by project type.

Create progress.yaml with type-appropriate phases.

Step 4: Create README

Generate project README with overview and current status.

Step 5: Report

Show user what was created and next steps.

Progress Tracking by Type

Qualitative Phases

status:

Literature

lit_search: not_started lit_synthesis: not_started

Analysis

immersion: not_started coding: not_started interpretation: not_started synthesis: not_started

Writing

theory_draft: not_started methods_draft: not_started findings_draft: not_started bookends_draft: not_started

Quality

verification: not_started revision: not_started

Quantitative Phases

status:

Literature

lit_search: not_started lit_synthesis: not_started

Data

data_acquisition: not_started data_cleaning: not_started

Analysis

eda: not_started # Exploratory data analysis modeling: not_started robustness: not_started # Sensitivity analyses

Outputs

visualization: not_started tables: not_started

Writing

theory_draft: not_started methods_draft: not_started results_draft: not_started bookends_draft: not_started

Quality

replication_check: not_started revision: not_started

Mixed Methods Phases

status:

Literature

lit_search: not_started lit_synthesis: not_started

Qualitative strand

qual_immersion: not_started qual_coding: not_started qual_interpretation: not_started

Quantitative strand

quant_data_prep: not_started quant_eda: not_started quant_modeling: not_started

Integration

integration: not_started # Combining qual + quant

Writing

theory_draft: not_started methods_draft: not_started findings_draft: not_started bookends_draft: not_started

Quality

verification: not_started revision: not_started

Progress Dashboard

When invoked with status argument, generate a dashboard:

/project-scaffold status

Dashboard output (qualitative example):

Project: Why Activists Leave Social Movements

Type: Qualitative | Phase: Analysis

Artifacts Found

• Transcripts: 24 files in data/raw/
• Codebook: analysis/codes/codebook.md
• Quote database: analysis/outputs/quote-database.md
• Theory draft: not found
• Methods draft: not found

Status

Suggested Next Steps

1. Complete interpretation - you have codes but no analytical memos
2. Start theory draft with /argument-builder

Quality Checks Pending

• Quote verification
• Bibliography completeness

Dashboard output (quantitative example):

Project: Income Inequality and Health Outcomes

Type: Quantitative | Phase: Analysis

Artifacts Found

• Raw data: data/raw/nhis_2020.dta
• Cleaned data: data/processed/analysis_sample.csv
• Cleaning script: scripts/cleaning/01_prep_data.R
• Analysis script: scripts/analysis/02_main_models.R
• Figures: 0 files in figures/
• Tables: 0 files in tables/

Status

Suggested Next Steps

1. Complete main models
2. Run robustness checks
3. Generate figures and tables

Quality Checks Pending

• Replication check
• Code review

Integration with Other Skills

research-coordinator

On session start:

• Check for project.yaml

• if missing, invoke project-scaffold

• Read progress.yaml and generate dashboard

• Route to appropriate skills based on project type

All other skills

Skills read project.yaml for paths:

import yaml with open("project.yaml") as f: config = yaml.safe_load(f)

project_type = config["type"] if project_type == "qualitative": data_path = config["paths"]["transcripts"] elif project_type == "quantitative": data_path = config["paths"]["raw_data"]

Access library paths (same for all project types)

bib_path = config["library"]["references_bib"] pdf_dir = config["library"]["pdfs"] md_dir = config["library"]["markdown"]

Skills update progress.yaml when done:

progress["status"]["coding"] = "done" progress["artifacts"]["codebook"] = "analysis/codes/codebook.md" progress["last_updated"] = datetime.now().isoformat()

Commands

Command What It Does

/project-scaffold

Create new project structure

/project-scaffold adopt

Map existing project to schema

/project-scaffold status

Generate progress dashboard

/project-scaffold update

Rescan filesystem and update progress.yaml

Filesystem Scanning by Type

Qualitative Artifacts

Artifact Detection

Transcripts *.txt , *.md , *.docx in paths.transcripts

Codebook codebook.md or codebook.yaml in paths.codebook

Quote database quote-database.md or quotes.json in paths.quotes

Memos *.md files in paths.memos

Quantitative Artifacts

Artifact Detection

Raw data *.csv , *.dta , *.sav , *.xlsx in paths.raw_data

Processed data *.csv , *.parquet , *.rds in paths.processed

Scripts *.R , *.py , *.do in paths.scripts

Models *.rds , *.pkl , *.joblib in paths.models

Figures *.png , *.pdf , *.svg in paths.figures

Tables *.tex , *.html , *.csv in paths.tables

Schema Versioning

Include schema version for forward compatibility:

project.yaml

schema_version: 1 type: qualitative # or quantitative, mixed

If skills encounter newer schema, warn but continue.

Starting the Scaffold

When user invokes:

Check if project.yaml exists

• If yes and no adopt /status flag: "Project already scaffolded. Use /project-scaffold status for dashboard or /project-scaffold adopt to remap paths."

Ask project type:

"What kind of project is this?

• Qualitative - Interviews, ethnography, content analysis

• Quantitative - Survey, experiments, secondary data

• Mixed methods - Combining qual + quant approaches"

Ask for basics:

"Project title?" "Research question (one sentence)?" "Target journals? (optional)"

For adopt mode, ask path questions based on type.

Create structure and files

Report:

"Project scaffolded as [type]. Created:

• [N] directories

• project.yaml (edit to add details)

• progress.yaml (auto-managed by skills)

• README.md

Next steps for [type] project: [type-specific guidance]"