JuroOravec/root-project-setup

Root Project Setup

Guides the user through configuring imported projects in a root repo. This skill covers adding projects, removing projects, and switching between projects. See docs/project-setup.md for the conceptual overview.

Scope

This skill applies only when you have a root repo with this setup:

1. Shared .cursor config — The root repo stores a single .cursor/ directory (agents, skills, rules) at its root.
2. Projects as nested clones — Individual projects are imported under the root as normal git clone directories; they are real directories, not symlinks.
3. Shared AI guidance — All imported projects use the same agents, skills, and rules defined in the root's .cursor/.

root-repo/                      ← root (this skill applies here)
├── .cursor/                   ← shared config (one definition for all)
│   ├── agents/
│   ├── rules/
│   └── skills/
├── project-a/                 ← nested git clone (imported)
├── project-b/                 ← nested git clone (imported)
└── ...

If the workspace is a plain single-project repo (or a monorepo without this imported-clone pattern), this skill does not apply.

When to use

Trigger this skill when:

• Adding one or more projects to this root repo as nested clones.
• Removing one or more projects from this root repo.
• Switching projects — soft (toggle .gitignore) or hard (remove one project folder, clone another).
• The user asks to "add a project", "remove a project", or "switch projects".

Prerequisites

• You are in a root repo with the setup described above (shared .cursor/ and projects as nested clones).
• For adding: the repo URL and branch are known or will be provided by the user.
• For removing: the user has decided whether to store progress (see Phase 2 below).

Workflow

Format: All skills MUST use ### Phase N: Title for each workflow step. Enforced by validation script in CI.

Skill-eval (meta-evaluation): From the project root, run ./scripts/skill-eval.sh start {conversation_id} root-project-setup at workflow start (conversation_id is injected at session start—look for "Conversation ID (for skill-eval)" in context). Capture the printed skill_id from the terminal output. Preserve both conversation_id and skill_id for the duration—if context gets summarized, ensure these IDs are retained. After each phase (or when skipping a phase), run ./scripts/skill-eval.sh complete {skill_id} {phase_no} or ./scripts/skill-eval.sh complete {skill_id} {phase_no} --skipped from the project root.

Create todo tasks for each phase before proceeding.

Phase 1: Determine intent

Ask the user which operation they want:

1. Add — add one or more projects as nested clones.
2. Remove — remove one or more projects (hard switch).
3. Switch — change which project(s) are in focus. Two modes:
   • Soft switch — Toggle .gitignore so tooling skips projects you're not using. Prettier and Cursor (when no .cursorignore) respect .gitignore; ESLint needs includeIgnoreFile from @eslint/compat. No folder deletion; WIP stays local.
   • Hard switch — Remove one project folder and clone another. Requires progress storage before remove. Use when you want to actually drop a project from the repo.

If the user says "switch" or "change projects" and the intent is unclear, ask: "Do you want a soft switch (toggle .gitignore to reduce focus — no push, WIP stays) or a hard switch (remove one folder and clone another — requires storing progress first)?" If still ambiguous after asking, default to soft.

Phase 2a: Soft switch (toggle .gitignore)

When switching projects without removing project folders:

1. Identify projects — which to deactivate (add to ignores) and which to activate (remove from ignores).
2. Edit .gitignore — add paths for projects to ignore (e.g. crawlee-one/), remove or comment out paths to activate. If you have a separate .cursorignore, manage it together with .gitignore; otherwise Cursor uses .gitignore. For ESLint at root: ensure eslint.config.js uses includeIgnoreFile from @eslint/compat to import .gitignore.
3. Remind — "Reload the window (Developer: Reload Window) for indexing and tooling to pick up the change. Your WIP in the deactivated project stays local — no push needed."

Phase 2b: Add projects

For each project to add:

1. Ask for repo URL — e.g. https://github.com/owner/repo.git or [email protected]:owner/repo.git.

2. Ask for branch — which branch to track. Default: main if the user does not specify.

3. Choose path — typically the repo name (e.g. crawlee-one, actor-spec). Confirm with the user if ambiguous.

4. Run clone:

   git clone -b <branch> <repo-url> <path>
   

5. Ensure root ignore is set so imported projects are not tracked by the root repo:

   # add if missing
   echo "<path>/" >> .gitignore
   

6. Commit root metadata only if requested (typically .gitignore updates).

Reminder: After adding, switching, or removing imported projects, the workspace may need a window reload (e.g. Cursor: Developer: Reload Window) for indexing to pick up the changes. Remind the user at the end of the workflow.

Phase 3: Remove projects (including switch)

Before removing any project:

1. Ask about progress storage — "Do you want to store progress before removing? Where? (e.g. push to the project's own repo, create a backup branch, or skip if there is no uncommitted work)"

2. If storing progress:

   • Ensure all changes in the nested project are committed.
   • Push to the project's own remote: cd <path> && git push origin <branch> (or the user's chosen destination).
   • If the user wants a backup branch, create and push it: git checkout -b backup-<date> && git push origin backup-<date>.

3. Then remove the project folder:

   rm -rf <path>
   

4. If desired, update .gitignore (keep entry if it may be re-cloned later; remove entry if fully retiring path).

5. Commit root metadata only if requested (usually .gitignore updates).

If hard switching: After removing, proceed to Phase 2b to clone the replacement project.

Reminder: Switching or removing imported projects may require a window reload for Cursor to refresh indexing. Remind the user at the end.

Phase 4: Window reload reminder

After any add, remove, or switch operation, tell the user:

Project import changes may require a window reload for Cursor to re-index. Use Developer: Reload Window (Cmd+Shift+P) if the new project does not appear in search or if the removed project still appears.

Verification

• [ ] User's intent (add / remove / switch) is confirmed before executing.
• [ ] For add: repo URL and branch are confirmed; path is clear.
• [ ] For add: nested project path is added to root .gitignore if needed.
• [ ] For remove: progress storage is offered and handled inside the nested project repo before deletion.
• [ ] Remove uses rm -rf <path> only after the user confirms.
• [ ] Window reload reminder is given at the end.

Out of scope

• Managing branches inside the imported project itself — treat each imported project as its own repo.
• Creating or modifying skills, agents, or rules — see meta-skill-create, project-polish, etc.