Files
阿白叔andClaude Opus 4.7 ea1819f1d2 feat: rename to praxis, package as Claude Code plugin
Reframe team-guide as praxis (Greek for "practice"): Simgreek's coding
agent rulebook, distributed as a Claude Code plugin so SessionStart
hook can force-inject the using-praxis bootstrap.

- Add .claude-plugin/{marketplace,plugin}.json: makes this repo a
  one-plugin marketplace installable via /plugin marketplace add.
- Add hooks/{hooks.json,session-start,run-hook.cmd}: SessionStart
  hook reads using-praxis SKILL.md and injects it into context as
  hookSpecificOutput.additionalContext (Claude Code) or
  additional_context (Cursor) or additionalContext (Copilot CLI).
- Migrate library/<topic>/SPEC.md → skills/<topic>/SKILL.md with
  YAML frontmatter (name + when-to-invoke description).
- Add skills/using-praxis: bootstrap with iron law, red-flags table,
  catalog, instruction priority, sub-agent stop, Codex/Cursor fallback.
- Add skills/debugging: 4-phase root-cause investigation with
  3-fixes-failed → architectural problem rule.
- Add skills/verification: evidence-before-claims gate with
  rationalization table.
- Drop library/, references in AGENTS.md updated to skills/.
- Rename throughout: team-guide → praxis.
- README rewritten with both install paths (plugin / external spec)
  and updated bootstrap prompt.

Codex / Cursor / non-Claude users still get the spec by reading
AGENTS.md and skills/ files manually — only the auto-injection
requires Claude Code.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-25 18:02:48 +08:00

8.4 KiB

name, description
name description
git-upload Use when pushing code to a remote, especially first push, adding a new file type the repo hasn't committed before, cleaning up .gitignore, or after suspecting a leaked secret

git-upload — what to commit, what not to

This is a focused spec for what belongs in version control and what doesn't. Branch / commit message / PR / tagging rules live in praxis AGENTS.md §3.

The first rule

git status and git diff --cached before every push. Read every file name in the staging list. Most accidents happen because the author didn't notice an extra file got staged.

What goes in

Source and infrastructure for the project. Things that:

  • Are written by humans (or AI under a human's review).
  • Are reasonably small (text or small binaries — a few MB at most).
  • Are the canonical version, not a derivative or cache.

Concretely:

  • Source code, scripts, tests
  • Configuration templates (e.g. .env.example) — never real values
  • Schemas, fixtures, small reference datasets that are part of the project
  • Documentation (Markdown, small images for docs)
  • Lockfiles (package-lock.json, poetry.lock, Cargo.lock, etc.) — always commit these
  • Build / CI configuration
  • License, README, CHANGELOG

What stays out

Secrets and credentials

Never commit any of these, even once, even temporarily.

  • API keys, tokens, passwords (any provider)
  • .env, .env.local, .env.production, *.pem, *.key, id_rsa, *.pfx, *.p12
  • OAuth client secrets, webhook signing keys
  • Database connection strings with embedded passwords
  • Cloud credentials (~/.aws/credentials, service account JSON)
  • Personal access tokens in URLs (https://user:TOKEN@host/repo.git)
  • Cookies, session tokens, signed JWTs from real users

A "delete the secret" commit later is not enough — the secret stays in history. See Recovering from a leaked secret.

Generated and runtime files

These are derivatives — regenerable from sources, not source themselves.

# Build outputs
dist/  build/  out/  target/  .next/  .nuxt/

# Dependency caches
node_modules/  .venv/  venv/  __pycache__/  .pytest_cache/  .mypy_cache/
.tox/  .gradle/  vendor/  Pods/

# Editor / IDE state
.vscode/  .idea/  *.swp  .DS_Store  Thumbs.db  desktop.ini

# Local runtime / logs
logs/  *.log  tmp/  .cache/  runtime-temp/  feedback-records/
generated_*/  reports/

The exception: vendored dependencies that you deliberately want under version control (offline / air-gapped builds). That's a project decision documented in the project's AGENTS.md, not the default.

Large binaries

5 MB → stop. Talk about Git LFS or out-of-band storage first.

Common offenders to scan for before pushing:

  • Model weights (.bin, .safetensors, .gguf, .ckpt, .pt, .onnx)
  • Datasets (.parquet, .arrow, .zip, .tar.gz, .7z over a few MB)
  • Videos, raw images, audio
  • Database dumps, full backups
  • Vendor SDK installers

Once a large binary is in history, the repo is bloated forever (unless you rewrite history). Catch it before push, not after.

Personal / machine-specific files

  • Personal editor settings — those go in ~/.<editor> not the repo
  • Agent personal config — .claude/settings.local.json, ~/.codex/config.toml (the personal one)
  • Per-machine paths, hostnames, debug toggles
  • Temporary scratch files, half-written notes

User and customer data

  • Real PII (names, emails, phone numbers from real people)
  • Real internal records, customer logs, support tickets
  • Anything covered by NDA or compliance scope

If sample data is needed for tests, generate it synthetically or use public fixtures.

.gitignore patterns

A baseline for most projects (adapt to the language):

# OS
.DS_Store
Thumbs.db
desktop.ini

# Editors
.vscode/
.idea/
*.swp
*~

# Secrets
.env
.env.*
!.env.example
*.pem
*.key
id_rsa*
*.pfx
*.p12

# Agent local state
.claude/settings.local.json
.claude/projects/
.claude/sessions/

# Python
__pycache__/
*.py[cod]
.venv/
venv/
.pytest_cache/
.mypy_cache/

# Node
node_modules/
npm-debug.log*
yarn-error.log

# Build outputs (uncomment what applies)
# dist/
# build/
# out/

# Logs / temp
*.log
tmp/
.cache/

Two rules for .gitignore:

  1. Be deliberate about negations (!.env.example etc.) — they override broader rules and are the source of "why isn't this file ignored" confusion.
  2. .gitignore only ignores untracked files. A file already in the index keeps being tracked even if you add it to .gitignore. To actually stop tracking it: git rm --cached <file> then commit.

Staging discipline

git add . and git add -A are dangerous when there are unrecognized untracked files. The safe pattern:

git status --short          # see what's changed
git add <specific files>    # stage by name
git diff --cached           # read what's actually being committed
git commit -m "..."

If you have many related files and want to use a glob, prefer git add src/foo/ (a directory) over git add . (the world).

Sensitive-info scan

Before push, especially when you've added new files:

git diff --cached

For periodic / pre-release scans across the working tree:

git grep -nE "sk-|hf_|Bearer |apiKey|ANTHROPIC_API_KEY|OPENAI_API_KEY|password|secret" \
  -- ':!*.lock' ':!vendor/**' ':!**/__pycache__/**'

Hits need human judgment — demo keys in comments and real keys both match the same regex. Don't blind-commit and don't blind-delete.

For a stronger sweep, use a dedicated tool (gitleaks, trufflehog, or your platform's secret scanning). They have richer rule sets than the regex above. Run them at least before any first-time push to a new remote.

Recovering from a leaked secret

When a real secret has been committed (and possibly pushed):

  1. Invalidate the secret immediately. Rotate the key/token at the provider before doing anything else. This is the only step that actually makes the leak safe — everything below is cleanup.
  2. Replace the secret locally. Move it to .env (which is gitignored) or your secrets manager.
  3. Notify collaborators. They need to know not to base work on the compromised commit until history is rewritten.
  4. Decide whether to rewrite history. For a public repo or one with a short history, use git filter-repo (preferred over the deprecated filter-branch) or your platform's secret-removal tooling. After rewrite, force-push with team agreement and ask everyone to re-clone.
  5. Document the incident briefly — what leaked, when, how, what was done. Future-you will want this when a similar mistake happens.

A "delete the key" commit on top is not safe. The secret is still in history and accessible to anyone who clones.

URLs with embedded credentials

A common slip: pushing with a token-embedded URL writes the token into .git/config:

remote "origin"
  url = https://user:TOKEN@host/owner/repo.git

Fix: after pushing, reset the URL to the credential-free form and let the credential helper handle auth:

git remote set-url origin https://host/owner/repo.git

Verify with git remote -v. The token also lives in shell history and in any .bash_history / PowerShell history file — clear it if the token is sensitive enough to warrant rotation.

First push to a new remote

A short checklist when initializing a project:

  • .gitignore covers secrets, build outputs, editor state, agent local state
  • No .env (or any .env.* other than .env.example) in the tree
  • No files >5 MB in the tree
  • git status shows only files you mean to commit
  • git diff --cached reads cleanly — no surprise content
  • Repo URL on the remote matches the one you intend; no token in the URL
  • Credential helper is configured (so you don't have to embed tokens in URLs)

After first push: git remote -v should show a clean URL.

Don'ts (summary)

  • Don't git add . with unrecognized untracked files in the tree.
  • Don't commit .env, secrets, tokens, or real credentials — ever, not even temporarily.
  • Don't commit large binaries (>5 MB) without a Git LFS conversation.
  • Don't commit generated / cache directories.
  • Don't commit real user data or PII.
  • Don't try to "clean up" a leaked secret with a delete commit. Rotate first, rewrite history if needed.
  • Don't leave tokens in .git/config after a token-in-URL push.
  • Don't --no-verify to skip pre-commit secret scans.