Skip to content

vt-c-scaffold

Scaffold a new project with universal folder structure, CLAUDE.md, PRODUCT-VISION.md, and PRD.md. Works for coding, knowledge work, design, and mixed projects.

Plugin: core-standards
Category: Project Setup
Command: /vt-c-scaffold

Scaffold Skill

Scaffold a new project with the right folder structure for Claude Code workflows. Creates the universal base plus type-specific directories.

Relationship to /vt-c-bootstrap

  • /vt-c-scaffold creates the universal project structure (folders, CLAUDE.md, PRODUCT-VISION.md, PRD.md, .gitignore, git init)
  • /vt-c-bootstrap adds full tech-stack configs (package.json, tsconfig, CI workflows) to coding projects

For coding projects: /vt-c-scaffold coding my-app then optionally /vt-c-bootstrap typescript-api .

Invocation

# Interactive mode - prompts for all options
/vt-c-scaffold

# With project type and name
/vt-c-scaffold coding my-service
/vt-c-scaffold knowledge market-research
/vt-c-scaffold design new-dashboard
/vt-c-scaffold mixed feasibility-study

Prerequisites

  • Git - Required for repository initialization
  • GitHub CLI (gh) - Optional, for automatic remote repository creation. Install: brew install gh && gh auth login

Execution Instructions

Step 1: Gather Requirements

If arguments were not provided, use AskUserQuestion to gather:

  1. Project Type - Ask which type:
  2. coding - Software development (then use /vt-c-bootstrap for tech-stack setup)
  3. knowledge - Documentation, research, analysis, content creation
  4. design - Product design, UX design, iterative design workflows

  5. mixed - Research that may lead to code, feasibility studies

  6. Project Name - The directory name (use current directory name if already in the target folder)

Step 2: Check Current Directory

Before creating structure: - If current directory is empty → use current directory - If project-name argument provided AND current directory is different → create new subdirectory - If directory already has files → ask before proceeding, preserve existing files

Step 3: Create Universal Base

All project types get this structure:

project-root/
├── PRODUCT-VISION.md   # Strategic vision (from templates/vt-c-scaffold/base/)
├── PRD.md              # Requirements starter (from templates/vt-c-scaffold/base/)
├── CLAUDE.md           # Project instructions (type-specific template)
├── README.md           # Generated with project name and type
├── .gitignore          # Type-specific (from templates/vt-c-scaffold/)
├── .mcp.json           # MCP server config stub (from templates/vt-c-scaffold/base/)
├── 00-inbox/
│   └── README.md       # Input buffer (from templates/scaffold/base/inbox-README.md)
└── 01-docs/
    └── journal/
        └── .gitkeep

Use the template files from templates/scaffold/base/ for PRODUCT-VISION.md and PRD.md. Fill in the project name in the templates. Use templates/scaffold/base/inbox-README.md for the inbox README. Use templates/scaffold/base/.mcp.json for the MCP server configuration stub. Use templates/scaffold/base/.claudeignore for the .claudeignore file (SPEC-114 / FR-14, FR-16) — copy verbatim to project root for all project types. Hides credentials, secret directories, and context-polluting artifacts from Claude's tool operations when the claudeignore-guard.sh PreToolUse hook is registered.

Step 4: Add Type-Specific Structure

Type: coding

mkdir -p src tests scripts 01-docs/adr 01-docs/runbooks 01-docs/solutions/patterns

Create: - 01-docs/adr/.gitkeep - 01-docs/runbooks/.gitkeep - 01-docs/solutions/patterns/critical-patterns.md (from templates/scaffold/coding/critical-patterns.md) - .env.example with comment: # Environment variables for [project-name] - .gitleaks.toml (from templates/scaffold/coding/.gitleaks.toml) — SPEC-114 / FR-15. Config for the gitleaks CLI secret scanner (user installs gitleaks separately). - Use templates/scaffold/coding/CLAUDE.md for CLAUDE.md - Use templates/scaffold/coding/gitignore-coding for .gitignore

Optional (ask user): - 01-docs/user-manual/ → End-user documentation site (MkDocs). Only create if user opts in. See /vt-c-1-bootstrap for the scaffolded structure. - .beads/ → Persistent issue tracking with Beads. Only create if user opts in. See /vt-c-1-bootstrap for initialization steps.

Type: knowledge

mkdir -p 01-docs/deliverables 01-docs/sources 01-docs/drafts

Create: - 01-docs/deliverables/.gitkeep - 01-docs/sources/.gitkeep - 01-docs/drafts/.gitkeep - Use templates/scaffold/knowledge/CLAUDE.md for CLAUDE.md - Use templates/scaffold/base/gitignore-base for .gitignore

Type: design

mkdir -p 01-docs/deliverables 01-docs/deliverables/implementation-readiness 01-docs/research

Create: - 01-docs/deliverables/.gitkeep - 01-docs/deliverables/implementation-readiness/.gitkeep - 01-docs/research/.gitkeep - .design-state.yaml (from templates/scaffold/design/design-state.yaml) - Use templates/scaffold/design/CLAUDE.md for CLAUDE.md - Use templates/scaffold/base/gitignore-base for .gitignore

Type: mixed

mkdir -p src scripts 01-docs/adr 01-docs/deliverables 01-docs/deliverables/implementation-readiness 01-docs/research 01-docs/solutions/patterns

Create: - 01-docs/adr/.gitkeep - 01-docs/deliverables/.gitkeep - 01-docs/deliverables/implementation-readiness/.gitkeep - 01-docs/research/.gitkeep - 01-docs/solutions/patterns/critical-patterns.md (from templates/scaffold/coding/critical-patterns.md) - .gitleaks.toml (from templates/scaffold/coding/.gitleaks.toml) — SPEC-114 / FR-15. Mixed projects include code. - Use templates/scaffold/mixed/CLAUDE.md for CLAUDE.md - Use templates/scaffold/coding/gitignore-coding for .gitignore

Step 5: Generate README.md

# [Project Name]

[One-line description from PRODUCT-VISION.md if already filled in, otherwise placeholder]

## Getting Started

See [PRODUCT-VISION.md](PRODUCT-VISION.md) for the project vision and [PRD.md](PRD.md) for requirements.

## Project Structure

[Show the created folder structure]

## Claude Code Integration

This project uses [VisiTrans Claude Toolkit](https://github.com/...) standards.
- Project instructions: [CLAUDE.md](CLAUDE.md)
- Global standards: `~/.claude/CLAUDE.md`
- Session journals: `01-docs/journal/`

Step 6: Initialize Git

# Only if .git doesn't exist
git init
git add .
git commit -m "Initialize [project-type] project: [project-name]"

Step 6.5: Register Project in Toolkit

Automatically register this project in the toolkit's project registry so /vt-c-toolkit-review can scan it for procedure improvement proposals.

TOOLKIT_ROOT="TOOLKIT_ROOT"
REGISTRY="$TOOLKIT_ROOT/intake/projects.yaml"

# Check if toolkit exists
if [ -d "$TOOLKIT_ROOT" ]; then
  # Create intake directory if needed
  mkdir -p "$TOOLKIT_ROOT/intake"

  PROJECT_PATH=$(pwd)
  PROJECT_NAME=$(basename "$PROJECT_PATH")
  PROJECT_TYPE="[type from Step 1]"
  DATE=$(date +%Y-%m-%d)

  if [ -f "$REGISTRY" ]; then
    # Check if already registered (skip if present)
    if ! grep -q "$PROJECT_PATH" "$REGISTRY"; then
      # Append new project entry
      cat >> "$REGISTRY" << EOF
  - path: $PROJECT_PATH
    name: $PROJECT_NAME
    type: $PROJECT_TYPE
    registered: $DATE
EOF
    fi
  else
    # Create registry with this project as first entry
    cat > "$REGISTRY" << EOF
# Projects using the V025-claude-toolkit
# Auto-maintained by /vt-c-scaffold, can also be edited manually
projects:
  - path: $PROJECT_PATH
    name: $PROJECT_NAME
    type: $PROJECT_TYPE
    registered: $DATE
EOF
  fi

  # Create toolkit-proposals directory for future feedback
  mkdir -p "01-docs/toolkit-proposals"

  echo "Registered in toolkit project registry."
fi

Note: This step runs silently. If the toolkit is not found at the expected path, it is skipped without error.

Step 7: Unified Repo Governance (Optional)

Ask the user whether to enable unified repo governance:

Use AskUserQuestion: 

Enable unified repo governance?
This adds partition boundaries (deployable/context/sandbox), Git LFS for binaries,
and deployment integrity checks.

Options: - Yes (Recommended) — Run /vt-c-repo-init inline to set up .repo-manifest.yaml, Git LFS, and .gitattributes - No — Skip governance. Can enable later with /vt-c-repo-init

If "Yes": Execute /vt-c-repo-init steps (detect structure, create manifest, init LFS, update .gitignore).

Step 8: GitHub Remote Setup

8a: Check GitHub CLI

  1. Check if gh is installed: 
    command -v gh &>/dev/null

If NOT installed, show setup guide and skip the rest of Step 8: 

⚠ GitHub CLI is required for remote repository setup.

Install:
  brew install gh

Then authenticate:
  gh auth login
    → Select "GitHub.com"
    → Select "HTTPS"
    → Authenticate via browser

After setup, re-run /vt-c-scaffold or manually create the remote:
  gh repo create Visitrans/[project-name] --private --source=. --push

  1. Check authentication: 
    gh auth status 2>&1

If NOT authenticated, guide the user and skip the rest of Step 8: 

⚠ GitHub CLI is installed but not authenticated.

Run:
  gh auth login
    → Select "GitHub.com"
    → Select "HTTPS"
    → Authenticate via browser

Then re-run /vt-c-scaffold or manually create the remote.

  1. Check org membership (informational — does not block): 
    gh org list 2>/dev/null | grep -qi visitrans
    If Visitrans is not in the org list, note this for the fallback option in 8b.

8b: Ask about remote repository

Use AskUserQuestion:

Create a private GitHub remote repository?

Options: - Visitrans org (Recommended) — Creates private repo at github.com/Visitrans/[project-name] - Personal account — Creates private repo under your personal GitHub account - Skip — No remote repository, local only

All VisiTrans repos are always private. Public repos are not offered.

If the org membership check in 8a failed, inform the user: 

Note: Your GitHub account may not be a member of the Visitrans org.
You can still try — if it fails, use the personal account option.

8c: Create the remote

If Visitrans org: 

gh repo create Visitrans/[project-name] --private --source=. --push

If personal account: 

gh repo create [project-name] --private --source=. --push

8d: Verify and display

git remote -v

On success: 

✓ Remote repository created!
  URL: https://github.com/Visitrans/[project-name]

  Reminder: Enable branch protection for main in GitHub settings.
  Recommended: Enable "Automatically delete head branches" in GitHub repo settings.
  This removes remote branches automatically after PR merge.

On failure (permission denied, name conflict, etc.): 

✗ Failed to create remote repository.

Common causes:
- You may not have permission to create repos in the Visitrans org
  → Ask an org admin for the "Repository creator" role
- A repo with this name may already exist
  → Check: gh repo view Visitrans/[project-name]
- Authentication issue
  → Run: gh auth status

You can create the remote manually later:
  gh repo create Visitrans/[project-name] --private --source=. --push

Step 9: Show Next Steps

Based on project type, show appropriate next steps:

Coding: 

Project initialized!

Next steps:
1. Edit PRODUCT-VISION.md with your project vision
2. Run /vt-c-bootstrap [stack] to add tech-stack configs:
   - /vt-c-bootstrap typescript-api
   - /vt-c-bootstrap react-app
   - /vt-c-bootstrap nextjs-app
3. Run /vt-c-kw-prd to create the full PRD
4. Start development: /vt-c-0-start

Available workflows:
- /vt-c-0-start      Development workflow
- /vt-c-kw-prd       Create full PRD
- /vt-c-journal      Capture decisions

Knowledge: 

Project initialized!

Next steps:
1. Edit PRODUCT-VISION.md with your project vision
2. Run /vt-c-kw-prd to create the full PRD
3. Start working: /vt-c-kw-0-start

Available workflows:
- /vt-c-kw-0-start   Knowledge work workflow
- /vt-c-kw-prd       Create full PRD
- /vt-c-journal      Capture decisions
- /vt-c-consolidate  Synthesize learnings

Design: 

Project initialized!

Next steps:
1. Edit PRODUCT-VISION.md with your project vision
2. Start design workflow: /vt-c-pd-0-start
3. Create PRD when ready: /vt-c-pd-2-prd

Available workflows:
- /vt-c-pd-0-start   Product design workflow
- /vt-c-pd-2-prd     Create full PRD
- /vt-c-journal      Capture decisions

Mixed: 

Project initialized!

Next steps:
1. Edit PRODUCT-VISION.md with your project vision
2. Start with research: /vt-c-kw-0-start
3. When code is needed: /vt-c-bootstrap [stack]

Available workflows:
- /vt-c-kw-0-start   Knowledge work (research phase)
- /vt-c-0-start      Development workflow (when code begins)
- /vt-c-kw-prd       Create full PRD
- /vt-c-journal      Capture decisions

Handling Existing Files

  • If PRODUCT-VISION.md, PRD.md, CLAUDE.md, or README.md already exist → do not overwrite, skip with a note
  • If .mcp.json already exists → do not overwrite, skip with a note
  • If .claudeignore already exists → do not overwrite, skip with a note (SPEC-114)
  • If .gitleaks.toml already exists → do not overwrite, skip with a note (SPEC-114)
  • If 00-inbox/ already exists → skip creation, do not overwrite
  • If 01-docs/ or docs/ directory exists → preserve contents, add missing subdirectories
  • If .git exists → skip git init
  • If .gitignore exists → do not overwrite

Template Files Location

All templates are in V025-claude-toolkit/templates/scaffold/: - base/ - Universal files (PRODUCT-VISION.md, PRD.md, inbox-README.md, gitignore-base, .mcp.json, .claudeignore) - coding/ - Coding project files (CLAUDE.md, gitignore-coding, critical-patterns.md, .gitleaks.toml) - knowledge/ - Knowledge work files (CLAUDE.md) - design/ - Design project files (CLAUDE.md, design-state.yaml) - mixed/ - Mixed project files (CLAUDE.md)