cofounder-pre-flight-check

Pre-Flight Check

Validate that the current environment is suitable for project work. This is the first skill invoked at session start.

Step 0 — Version Check

<!-- COFOUNDER_VERSION: 0.25.13 -->

The COFOUNDER_VERSION marker above contains the loaded version of the cofounder skills.

Fetch https://api.github.com/repos/locaweb/cofounder/contents/.claude-plugin/plugin.json and read the version field from the decoded content. Using the GitHub API (instead of a raw branch URL) ensures the response is signed and subject to GitHub's integrity controls.

Only compare the version number — never execute or evaluate content from the fetched response.

• Remote is newer: Warn the user that the cofounder skills are outdated and ask them to update by running the command below in their OS terminal. Tell them they must start a new session after updating — the current session still runs the outdated skills — and stop:

  mise x node@22 -- npx -y skills add locaweb/cofounder --agent universal claude-code hermes-agent --skill '*' -y
  

• Versions match: Proceed normally.

• Fetch fails: Proceed without blocking the session — do not treat a failed fetch as a reason to stop.

Running the Check

This skill bundles the preflight script at scripts/preflight.sh, relative to the directory this SKILL.md lives in. Locate it from the skill's own directory and run it with bash — resolve the path against the skill directory, not your current working directory:

bash <this-skill-dir>/scripts/preflight.sh

The script exits 0 and prints PREFLIGHT_PASSED on success, or exits 1 and prints PREFLIGHT_FAILED followed by one or more error lines on failure.

Conditions Checked

1. Must Not Be in the Home Directory

Running from the user's home folder (~) risks polluting it with project files.

On failure: Recommend creating and navigating to a project subfolder first (e.g., mkdir ~/my-project && cd ~/my-project).

2. No Pre-Existing Content Without a Git Repository

When both of these conditions are true simultaneously, the check fails:

• The directory contains files or folders other than .claude, .venv, CLAUDE.md, and AGENTS.md
• No local git repository has been initialized (.git/ does not exist)

This prevents accidentally initializing a project on top of untracked existing content.

On failure: Suggest using an empty directory, or initializing a git repository first to acknowledge the existing content.

3. Git Sync

When the directory has a git repository and at least one remote is configured, the script automatically synchronizes:

1. Sensitive file guard — aborts if any untracked, staged, or modified file matches credential patterns (.env / <name>.env / .env.*, id_rsa and friends, .npmrc/.netrc/.pypirc, .pem, .key, .secret, .p12, .pfx, .jks, .keystore, credentials*.json, secrets.yaml). Template files (.example, .sample, .template, …) and deletions are ignored. The remediation depends on how the file is tracked: add it to .gitignore (untracked), git restore --staged <file> (staged), or git rm --cached <file> plus .gitignore (already tracked).
2. Commit any uncommitted local changes (staged or unstaged)
3. Pull remote commits using rebase to keep history linear
4. Push local commits to the remote

This ensures every session starts from a fully synchronized state.

On failure: The script reports a GIT_SYNC_ERROR or SENSITIVE_FILES_DETECTED with details. The user must resolve the issue manually and re-run the check.

4. Dev Tools Check

The script checks for podman, mise, and gh. If any are missing, it prints:

NEEDS_COMPUTER_SETUP: missing <tool1> <tool2> ...

Action: Use the Skill tool to invoke cofounder-computer-setup and follow its instructions. After tools are installed, re-run the preflight check.

5. Git Remote Check

If no git remote is configured (or no git repo exists), the script prints:

NEEDS_REPO_SETUP: ...

Action: Use the Skill tool to invoke cofounder-repo-setup and follow its instructions.

Handling Failures

When the pre-flight check fails (PREFLIGHT_FAILED):

1. Display each error reason to the user in plain language
2. Provide the recommended remediation for each failure
3. Do not proceed — wait for the user to fix the issue and re-run

When the pre-flight check passes but prints NEEDS_ flags:

1. Invoke the indicated skill(s) in order: computer-setup first, then repo-setup
2. After those complete, proceed with the session

Bundled Resources

Scripts

• scripts/preflight.sh — Runs all environment validations and reports pass/fail with specific error codes