Portfolio Project Initializer

Portfolio Project Initializer V2

Scope

Prepare a personal portfolio website repository for long-term maintenance. This skill only handles engineering foundation: project inspection, standard directories, dependency/configuration completion, resource-path rules, maintenance files, validation, and Git readiness.

Do not create portfolio content, pages, UI design, animation, business logic, complex components, commits, pushes, remote changes, credentials, or repository ownership changes.

Safety Rules

Inspect before editing. Never delete existing files. Never overwrite existing configuration or code. Preserve existing directories and structure; create only missing standard directories and append only clearly missing maintenance rules.

Stop and report before editing when any of these are present:

• Unknown user changes that could be overwritten
• Conflicting or partial frontend setup whose intent is unclear
• Existing files that scaffolding would need to replace
• A package-manager lockfile other than pnpm-lock.yaml
• Missing or suspicious Git user identity
• Any prompt for GitHub username, password, token, permissions, or remote changes

If the repository is dirty but changes are understandable and edits can be limited to new files or safe appends, proceed carefully and describe what will be touched before editing.

Required Initial Inspection

Run targeted checks from the project root before making changes:

pwd
ls
find . -maxdepth 3 -type f -not -path './node_modules/*' -not -path './dist/*' -not -path './.git/*' | sort
find . -maxdepth 3 -type d -not -path './node_modules/*' -not -path './dist/*' -not -path './.git/*' | sort
test -f package.json && cat package.json
test -f vite.config.js && sed -n '1,220p' vite.config.js
test -d src && find src -maxdepth 3 -type f | sort
git status --short --branch
git config user.name || git config --global user.name
git config user.email || git config --global user.email
git remote -v

Classify the project:

• Empty or near-empty portfolio project
• Existing non-React project
• Partial Vite/React project
• Complete Vite/React project
• Unknown or unsafe project requiring confirmation

If the project is not empty, summarize what exists and what can be safely added before editing.

Standard Portfolio Structure

Ensure these directories exist. Keep all existing directories and do not restructure:

src/
  components/
  pages/
  layouts/
  styles/
  utils/
  assets/
public/
  images/
  videos/
  pdf/
projects/

Add .gitkeep only to empty standard directories that must be tracked. Do not add placeholder UI, pages, animations, business logic, or portfolio content.

Technical Stack Standard

Default portfolio stack:

• Vite
• React
• JavaScript
• pnpm
• Tailwind CSS

Check these files:

• package.json
• vite.config.js
• tailwind.config.js
• postcss.config.js

When missing and safe, add minimal baseline files. When present, preserve existing settings and only add missing compatible pieces.

package.json should contain compatible scripts and dependencies:

{
  "type": "module",
  "scripts": {
    "dev": "vite",
    "build": "vite build",
    "preview": "vite preview"
  },
  "dependencies": {
    "react": "latest",
    "react-dom": "latest"
  },
  "devDependencies": {
    "@vitejs/plugin-react": "latest",
    "vite": "latest",
    "tailwindcss": "latest",
    "postcss": "latest",
    "autoprefixer": "latest"
  }
}

Minimal Vite config:

import { defineConfig } from "vite";
import react from "@vitejs/plugin-react";

export default defineConfig({
  plugins: [react()],
});

Minimal Tailwind config:

export default {
  content: ["./index.html", "./src/**/*.{js,jsx}"],
  theme: {
    extend: {},
  },
  plugins: [],
};

Minimal PostCSS config:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
};

If a minimal src/styles/main.css or equivalent global stylesheet already exists, preserve it. If adding Tailwind to a new stylesheet, include only:

@tailwind base;
@tailwind components;
@tailwind utilities;

If no Vite/React entry exists and the project is empty or clearly incomplete, create only the minimum index.html, src/main.jsx, and neutral src/App.jsx needed for React to mount. Keep text generic and avoid portfolio sections or visual design.

Prefer pnpm. If package-lock.json, yarn.lock, or bun.lockb exists, stop and ask before switching package managers.

Resource Rules

Keep resources separated:

• Images: public/images/
• Videos: public/videos/
• PDFs: public/pdf/
• Project materials or notes: projects/
• Bundled source assets: src/assets/

Public resource references must use project-relative public paths:

/images/example.png
/videos/demo.mp4
/pdf/project.pdf

Forbidden in project code and documentation:

• file:///
• C:\, D:\, E:\, or other Windows drive paths
• /Users/
• Desktop-local absolute paths

Scan before finishing:

rg -n "file:///|[A-Z]:\\\\|/Users/|Desktop/" . -g '!node_modules' -g '!dist' -g '!pnpm-lock.yaml'

Replace unsafe resource references only when the correct project-relative public path is clear. Otherwise report the finding.

Maintenance Files

Check README.md and .gitignore.

Ensure .gitignore exists and contains at least:

node_modules/
dist/
.env
.DS_Store
.vscode/

Append only missing ignore rules. Preserve existing project-specific rules.

Create a concise README.md only when absent. If one exists, do not rewrite it without explicit confirmation. A new README should state the project purpose, stack, and directory structure.

pnpm Validation

Run validation after edits:

pnpm install
pnpm build
pnpm dev

Confirm:

• Dependencies install with pnpm
• Vite production build succeeds
• Vite dev server starts
• React entry renders
• Browser can access localhost

Stop the dev server before finalizing unless the user asks to leave it running. If network access, local port binding, or browser access is blocked by the environment, request approval when appropriate; otherwise report the exact command and limitation.

Git Rules

Check:

git status --short --branch
git config user.name || git config --global user.name
git config user.email || git config --global user.email
git remote -v

Do not automatically commit, push, force push, add or change remotes, rename branches, or modify repository credentials. Do not stage files unless the user explicitly asks.

If Git is missing and the user clearly asked for repository initialization, run git init only after confirming the directory is the intended project root.

Final Report

End with a concise report containing:

1. Current technical stack
2. Current project structure
3. Directories created
4. Files modified or created
5. Git status and identity check
6. Whether the project meets the long-term personal portfolio engineering standard
7. Recommended next development step

Mention explicitly that no page development, UI, animation, business logic, portfolio content, commit, push, or remote change was performed.