127 lines
3.9 KiB
Markdown
127 lines
3.9 KiB
Markdown
---
|
|
name: steward-steering
|
|
description: Critical project steering rules for Steward development. Prevents accidental commits of sensitive files and ensures git pushes are explicitly approved before executing.
|
|
---
|
|
|
|
# Steward Project Steering
|
|
|
|
This skill enforces critical guardrails for working on the Steward project. Follow these rules strictly.
|
|
|
|
## Rule 1: Never Commit Sensitive Files
|
|
|
|
### Files That Must NEVER Be Committed to Git
|
|
|
|
These files contain secrets, tokens, API keys, or personal configuration:
|
|
|
|
- `mcp.json` - Contains MCP server tokens and credentials
|
|
- `.env` - Contains environment variables with secrets
|
|
- `config.yaml` - If it contains actual (non-example) values with secrets
|
|
- Any file containing: API keys, tokens, passwords, private URLs, auth credentials
|
|
|
|
### Files That ARE Safe to Commit
|
|
|
|
- `.env.example` - Template showing which env vars are needed (no actual values)
|
|
- `mcp.json.example` - Template showing MCP structure (no actual tokens)
|
|
- `config.example.yaml` - Template/example configuration (no real values)
|
|
- `CONFIGURATION.md` - Documentation
|
|
- Source code, tests, docker-compose templates
|
|
|
|
### Before Committing
|
|
|
|
1. Run `git status` and review all staged files
|
|
2. For each file, ask: "Does this contain secrets, tokens, or sensitive config?"
|
|
3. If YES: Do NOT commit it. Either:
|
|
- Remove it from staging: `git reset <file>`
|
|
- Add it to `.gitignore` if not already there
|
|
- Create an `.example` version without secrets
|
|
4. If NO: Safe to commit
|
|
|
|
### If You Accidentally Commit Secrets
|
|
|
|
Do NOT try to fix with `git filter-repo` or history rewrites. Instead:
|
|
1. Tell the user immediately
|
|
2. User must manually rotate/revoke any compromised tokens
|
|
3. Use `git rm --cached <file>` to stop tracking it
|
|
4. Add to `.gitignore`
|
|
5. Amend the commit or create a new one
|
|
6. Force push to origin only if the branch hasn't been merged to main
|
|
|
|
## Rule 2: Git Push Requires Explicit Approval
|
|
|
|
### When You Can Commit WITHOUT Approval
|
|
|
|
You can commit to the current branch anytime (this is local, safe):
|
|
|
|
```bash
|
|
git add <files>
|
|
git commit -m "message"
|
|
```
|
|
|
|
### When You MUST Ask Before Pushing
|
|
|
|
Any `git push` command requires explicit user approval first:
|
|
|
|
1. **Tell the user:**
|
|
```
|
|
Ready to push branch feature/my-feature to origin. Should I proceed?
|
|
```
|
|
|
|
2. **Wait for user to explicitly say "yes" or "push it"** (or equivalent approval)
|
|
|
|
3. **Only then execute:**
|
|
```bash
|
|
git push origin feature/my-feature
|
|
```
|
|
|
|
### Exceptions (No Approval Needed)
|
|
|
|
- `git push --tags` to push individual tags (assuming the tag commit is already approved)
|
|
- Tags that point to already-approved commits
|
|
|
|
### Why This Rule Exists
|
|
|
|
- Git pushes are permanent and trigger CI/CD
|
|
- Force pushes rewrite history
|
|
- Accidental pushes before review waste CI resources
|
|
- Better to ask than regret
|
|
|
|
## Rule 3: Use `.gitignore` for Sensitive Patterns
|
|
|
|
When sensitive files are generated locally (like `mcp.json`, `.env`), ensure they're in `.gitignore`:
|
|
|
|
```bash
|
|
# .gitignore
|
|
mcp.json # Actual config with secrets
|
|
.env # Local environment file
|
|
config.yaml # If it contains real values
|
|
```
|
|
|
|
Then create `.example` versions:
|
|
|
|
```bash
|
|
mcp.json.example # Template with placeholders
|
|
.env.example # Shows required variables
|
|
config.example.yaml # Shows structure
|
|
```
|
|
|
|
Users copy: `cp mcp.json.example mcp.json` then edit locally.
|
|
|
|
## Checklist Before Each Push
|
|
|
|
- [ ] All staged files reviewed for secrets
|
|
- [ ] `.gitignore` includes sensitive files
|
|
- [ ] `.example` files created where needed
|
|
- [ ] All tests pass (`pytest`)
|
|
- [ ] Ruff checks pass (`ruff check`)
|
|
- [ ] Commit messages follow conventional commits
|
|
- [ ] User has explicitly approved the push
|
|
|
|
## When Unsure
|
|
|
|
If you're unsure whether a file should be committed:
|
|
- Ask the user
|
|
- Error on the side of caution (don't commit)
|
|
- Create an `.example` version instead
|
|
|
|
This is a low-cost insurance policy against leaking secrets.
|