steward_mirror/.agents/skills/steward-steering/SKILL.md

name, description

name	description
steward-steering	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):

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:

   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:

# .gitignore
mcp.json           # Actual config with secrets
.env               # Local environment file
config.yaml        # If it contains real values

Then create .example versions:

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.