Skip to content

Latest commit

 

History

History
150 lines (100 loc) · 4.06 KB

AGENTS.md

File metadata and controls

150 lines (100 loc) · 4.06 KB

AGENTS.md - AI Agent Guidelines for Hacktoolkit

⚠️ This is a PUBLIC Repository

This repository is publicly visible on the internet. Never commit:

  • API keys, tokens, or secrets
  • Passwords or credentials
  • Private business information
  • Customer data
  • Internal URLs or endpoints

If you accidentally commit sensitive data, alert the maintainer immediately. The data is already exposed - a force push doesn't remove it from GitHub's servers or anyone who cloned/forked.

🚀 Deployment Architecture

How It Works

  1. GitHub Pages hosts the production site at www.hacktoolkit.com
  2. The docs/ directory contains the static build output
  3. Any push to master automatically deploys to production
  4. There is no staging environment - master IS production

The Golden Rule

Never push directly to master without explicit approval.

Changes pushed to master go live immediately. This includes:

  • Source code changes (src/)
  • Build artifacts (docs/)
  • Configuration files

🔄 Deployment Workflow

For Testing/Development

  1. Create a feature branch: git checkout -b feature/my-change
  2. Make changes to source files in src/
  3. Test locally with yarn run dev
  4. Build with make build to verify the build succeeds
  5. Do NOT push to master - create a PR for review

For Production Deployment

  1. Get explicit approval from the maintainer
  2. Merge the approved PR to master
  3. Run make deploy to build and stage the deployment
  4. Push to master - GitHub Pages automatically deploys the docs/ folder

Build Commands

yarn run dev      # Local development server
make build       # Production build (outputs to docs/)
make deploy      # Build and stage deployment commit
yarn run lint     # Check for errors

🛡️ Security Guidelines

DO ✅

  • Use environment variables for any secrets (local dev only)
  • Keep sensitive config in .env files (gitignored)
  • Review diffs before committing
  • Ask before making external-facing changes

DON'T ❌

  • Commit .env files or any secrets
  • Hardcode API keys, tokens, or passwords
  • Include internal business data in code or comments
  • Push directly to master without approval

📁 Repository Structure

www.hacktoolkit.com/
├── src/                  # Source code (React/Next.js)
│   ├── pages/           # Page components
│   ├── components/      # Reusable components
│   └── styles/          # CSS/SCSS styles
├── docs/                 # Built static site (auto-generated)
├── public/              # Static assets
├── Makefile             # Build automation
└── package.json         # Dependencies

Important: Source vs Build

  • src/ - Make ALL changes here. This is the source of truth.
  • docs/ - NEVER edit directly. This is auto-generated by make build.

🤖 AI Agent Checklist

Before making any changes:

  1. Is this a public repo? (Yes - don't include secrets)
  2. Am I on a feature branch? (Don't work on master)
  3. Am I editing files in src/, not docs/?
  4. Do I have explicit approval to deploy?

Before pushing:

  1. Run yarn run lint - no errors?
  2. Run make build - build succeeds?
  3. Is this going to master? (If yes, STOP - need approval)

After approval to deploy:

  1. Run make deploy to build and stage
  2. Review the staged changes
  3. Push to master

⚠️ Common Pitfalls

Don't Forget .nojekyll

The make build command automatically creates docs/.nojekyll. This file is required for GitHub Pages to serve files starting with underscores (like _next/). Never delete it manually.

Don't Edit docs/ Directly

Changes to docs/ will be overwritten on the next build. Always edit src/ and rebuild.

Don't Skip the Build Step

Running make deploy ensures:

  • Clean build from source
  • CNAME file is copied
  • .nojekyll file is created
  • Build artifacts are properly staged

📞 Contact

For questions about deployment or access, contact the repository maintainer.