refer-another-project

> **DO NOT auto-invoke this skill.** Referencing another project exposes its contents to the current session, which may leak private/client information across project boundaries. Always ask for user confirmation before proceeding.

# Refer Another Project Command

Use this command when you need to reference, copy, or learn from another project's setup, structure, or patterns.

## Resolving Project Paths

Arguments can be **slugs** (short names) or **full paths**. Multiple slugs/paths can be provided, space-separated.

**Slug resolution rule:**

For each slug argument (any argument that is NOT an absolute path starting with `/`):

1. Search for matching directories at `$HOME/repos/*/{slug}` (one level of category directories)
2. If exactly one match is found, use it as the project path
3. If no match is found, **stop and report the error** to the user — do not guess or continue
4. If multiple matches are found, list them and ask the user to clarify

**Examples:**

- `/refer-another-project zmod` → resolves `$HOME/repos/*/zmod` → e.g. `$HOME/repos/zp/zmod`
- `/refer-another-project zmod dotfiles` → resolves both slugs independently
- `/refer-another-project $HOME/repos/zp/zmod` → uses full path directly

```bash
# Resolution command for each slug
ls -d $HOME/repos/*/{slug} 2>/dev/null
```

## Update Mode (`-u` / `--update`)

When `-u` or `--update` is passed, this skill switches to **fix-and-PR mode**: you've found a problem in the referenced project and want to fix it there directly.

### How it works

1. **Remember the current project path** (you'll return here afterward)
2. **`cd` into the resolved project path**
3. **Run `/x-as-pr -co` from the main branch** with the fix instructions
- The `/x-as-pr` workflow handles branching, implementing, reviewing, and opening a draft PR
- Pass any remaining arguments (after the slug and flags) as implementation instructions to `/x-as-pr`
4. **After the PR is created**, `cd` back to the original project and resume work

### PR content rules for update mode

The PR on the referenced project must:

- **Describe the fix in full detail** — what was wrong, why, and how it's fixed
- **NEVER mention the originating project** — do not write which project led to discovering the bug. Each project must remain completely independent. No project names, slugs, paths, or hints about what you were working on when you found the issue
- Use generic phrasing like "discovered during usage" or "found during testing" if context is needed

### Example

```
/refer-another-project -u zmod fix the broken export path in package.json
```

This will:

1. Resolve `zmod` → `$HOME/repos/*/zmod`
2. `cd` into that directory
3. Run `/x-as-pr -co fix the broken export path in package.json`
4. Return to the original project after PR is created

### Constraints

- Only **one slug** is allowed with `-u` (you can't fix multiple projects at once)
- If multiple slugs are provided with `-u`, report an error and stop

## Critical Security Warning

When referencing another project, you MUST protect project-specific sensitive information. Never copy concrete content or secrets - only copy patterns, structures, and configurations.

**NEVER leak the referenced project's name or directory path into the current project's artifacts.** This includes:

- Git commit messages
- PR titles and descriptions
- GitHub issue titles and comments
- Log files, TODO comments, or any written output in the working project

The referenced project may belong to a work client. Exposing client names or project identifiers in public or semi-public artifacts (issues, PRs, commits) causes real problems. Always use generic descriptions like "another project" or "reference implementation" instead.

## What You CAN Copy (Safe)

- **Project structure**: Directory organization, folder naming conventions
- **Configuration patterns**: Build tool configs, linter configs, framework setup patterns
- **Package dependencies**: package.json dependencies (not scripts with project-specific values)
- **Code patterns**: Component structures, utility function patterns, architectural approaches
- **Setup procedures**: How things are configured (but not the concrete values)
- **Type definitions**: Generic type patterns and interfaces
- **Test patterns**: Testing setup and structure (not test data with real values)

## What You MUST NOT Copy (Dangerous)

- **Project titles and names**: Product names, brand names, company names
- **Concrete content**: Article text, documentation content, marketing copy
- **HTML content with specific info**: Pages with real product/company information
- **Database information**: Connection strings, table names with business meaning, credentials
- **API keys and secrets**: Any `.env` values, API tokens, passwords
- **URLs and endpoints**: Production URLs, internal service addresses
- **User data**: Any real user information, emails, names
- **Business logic specifics**: Proprietary algorithms, pricing logic, business rules
- **Internal documentation**: Private docs, internal guides, company-specific processes
- **Asset files**: Images, logos, brand assets that belong to the other project

## Argument Parsing

Parse `$ARGUMENTS` to extract:

- **`-u` or `--update` flag**: If present, switch to update mode (see "Update Mode" above)
- **Slug(s) or path(s)**: Project identifiers to resolve
- **Remaining text** (update mode only): Implementation instructions passed to `/x-as-pr -co`

## Instructions

### Default mode (no `-u` flag)

1. **Identify what you need**: Clearly state what patterns or setup you want to learn from
2. **Read with filtering mindset**: When reading files, mentally separate:
- Generic patterns (copy these)
- Project-specific values (never copy these)
3. **Adapt, don't copy verbatim**: Transform patterns to fit the target project
4. **Replace all identifiers**: Any names, titles, or identifiers must be replaced with appropriate values for the target project
5. **Double-check before writing**: Before writing any file, verify no sensitive info leaked through

## Example Scenario

When copying Docusaurus setup from `$HOME/foo/bar/`:

**Safe to reference:**

- `docusaurus.config.js` structure and plugin configurations
- Directory structure (`docs/`, `src/`, `static/`)
- Theme customization patterns
- Sidebar configuration format
- Build and deployment scripts structure

**Must NOT copy:**

- Site title, tagline, organization name in config
- Actual documentation article content
- Logo and favicon files
- Any URLs (baseUrl, url, GitHub links)
- Author information
- Analytics IDs
- Any text content within markdown files

## Reminder

Always ask yourself: "Does this contain information specific to the source project?" If yes, do not copy it directly. Extract the pattern and apply it fresh to the target project.