---
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.