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>
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,.7zover 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:
- Be deliberate about negations (
!.env.exampleetc.) — they override broader rules and are the source of "why isn't this file ignored" confusion. .gitignoreonly 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):
- 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.
- Replace the secret locally. Move it to
.env(which is gitignored) or your secrets manager. - Notify collaborators. They need to know not to base work on the compromised commit until history is rewritten.
- Decide whether to rewrite history. For a public repo or one with a
short history, use
git filter-repo(preferred over the deprecatedfilter-branch) or your platform's secret-removal tooling. After rewrite, force-push with team agreement and ask everyone to re-clone. - 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:
.gitignorecovers 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 statusshows only files you mean to commitgit diff --cachedreads 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/configafter a token-in-URL push. - Don't
--no-verifyto skip pre-commit secret scans.