AI Agent Instructions - Copilot Junk Drawer

For Claude Code, GitHub Copilot, and other AI assistants
Read this file first to understand this repository's purpose, structure, and automation.

🎯 Repository Purpose

This is a "junk drawer" repository — a curated collection of powerful, self-contained tools that don't warrant individual repositories. Think of it like a developer's utility drawer: each tool is production-ready, well-documented, and solves a specific problem elegantly.

Philosophy

Tools live here (not in separate repos) when they:

✅ Are production-ready and useful
✅ Don't need independent versioning or CI/CD
✅ Are self-contained with minimal cross-dependencies
❌ Don't require semantic versioning
❌ Don't need community governance

📂 Repository Structure

copilot-junk-drawer/
├── README.md                    # Auto-generated main README
├── .claude.md                   # This file - agent instructions
├── CONTRIBUTING.md              # Contributor guide
├── LICENSE                      # MIT license
├── .github/
│   ├── README.md               # Auto-generation system docs
│   ├── workflows/
│   │   └── update-readme.yml   # GitHub Action for auto-updates
│   └── scripts/
│       ├── generate-readme.js  # README generator (Node.js)
│       └── test-readme-locally.md
├── [tool-name]/                # Each tool in its own folder
│   ├── README.md              # Tool documentation (required)
│   ├── package.json           # Dependencies (if applicable)
│   └── [tool files]           # Implementation files
└── [another-tool]/
    └── ...

🤖 Auto-Generation System

CRITICAL: The README is Auto-Generated

DO NOT manually edit the main README.md except in special circumstances. It is automatically generated from:

Curated tool descriptions in .github/scripts/generate-readme.js
Tool folder discovery (any top-level folder with README.md)
Static sections (Philosophy, Quick Start, Contributing, etc.)

How It Works

GitHub Action (.github/workflows/update-readme.yml):
- Triggers on push to main/master (excluding README.md changes)
- Runs generate-readme.js
- Commits updated README if changed
Generator Script (.github/scripts/generate-readme.js):
- Scans for folders with README.md files
- Uses curated manualMappings for known tools
- Auto-parses README for new tools (fallback)
- Generates complete README with consistent formatting

Testing Locally

ALWAYS test before committing new tools:

# From repo root
node .github/scripts/generate-readme.js

# Check the diff
git diff README.md

✨ Adding a New Tool

When a user asks to add a new tool:

Create folder structure:

mkdir tool-name
cd tool-name
# Create README.md and implementation files

Create comprehensive README.md with:
- Clear title and one-line description
- Purpose/what it does
- Prerequisites (required and optional)
- Installation instructions
- Usage examples with code blocks
- Tech stack
- Example outputs

Add curated entry to .github/scripts/generate-readme.js:

const manualMappings = {
  'tool-name': {
    name: 'tool-name',
    title: 'Tool Display Name',
    subtitle: 'Compelling one-liner hook',
    description: 'Paragraph explaining value.',
    features: [
      'Key feature 1',
      'Key feature 2',
      'Impressive stat or result',
      'Integration capability'
    ],
    stack: 'Node.js, Python, etc.',
    emoji: '🚀' // Pick relevant emoji
  }
};

Test locally:

node .github/scripts/generate-readme.js
git diff README.md

Verify formatting matches existing tools

📝 Current Tools (as of creation)

agentic-assessment (📊)
- AI-assisted development impact analysis
- Git commit history → productivity & quality metrics
- Stack: PowerShell, Python, Node.js, GitHub CLI, Azure CLI
time-narrative (⏱️)
- Clockify AutoTrack → AI-generated weekly narratives
- SQLite extraction → AI agent processing
- Stack: Node.js, SQLite, Claude Code

Curated descriptions for both tools are in generate-readme.js - use these as templates for new tools.

🎨 Style Guidelines

For Tool READMEs:

Use clear headings: Purpose, Prerequisites, Installation, Usage
Include code blocks with language specifiers
Show realistic examples, not toy demos
Document all dependencies explicitly
Keep tone professional but approachable

For Descriptions in manualMappings:

Title: Proper case, no emoji (added automatically)
Subtitle: 5-12 words, compelling hook
Description: 1-3 sentences, what + why + how
Features: 3-4 bullets, concrete capabilities or impressive stats
Stack: Comma-separated list, key technologies only
Emoji: Single relevant emoji (see emoji map in generate-readme.js)

Code Style:

Follow existing patterns in the codebase
Use modern JavaScript (ES6+) for Node.js scripts
PowerShell for Windows-centric automation
Python with type hints when applicable

🚫 What NOT to Do

❌ Don't manually edit main README.md without regenerating
❌ Don't add experimental or half-finished tools
❌ Don't create tools with external dependencies on other tools in repo
❌ Don't commit secrets, API keys, or credentials
❌ Don't add tools that need semantic versioning
❌ Don't use absolute paths (prefer relative or environment variables)

🔍 Common Tasks

User wants to add a new tool:

Ask for tool details (purpose, tech stack, features)
Create folder structure
Write comprehensive README
Add curated entry to generate-readme.js
Test with node .github/scripts/generate-readme.js
Verify output looks good

User wants to update existing tool:

Edit tool's own README.md
Update curated entry in generate-readme.js if main README should change
Test regeneration

User wants to modify automation:

Edit .github/scripts/generate-readme.js for generator logic
Edit .github/workflows/update-readme.yml for workflow
Test locally before committing

User asks about the README:

Explain it's auto-generated
Show them generate-readme.js for customization
Demonstrate local testing

📚 Key Files to Reference

CONTRIBUTING.md - Full contributor guide
.github/README.md - Auto-generation system docs
.github/scripts/generate-readme.js - Generator implementation
Individual tool READMEs - Follow their patterns for new tools

🎯 Best Practices for AI Agents

Always check current tools before suggesting new ones
Test generation before finalizing any changes
Follow existing patterns in code and documentation
Use curated descriptions rather than auto-parsing for quality
Maintain consistency in tone, formatting, emoji usage
Document thoroughly - users should be able to use tools independently
Think "junk drawer" - is this truly self-contained and useful?

💡 Context for Recommendations

When users ask for help:

Prefer curated content over auto-parsing for README descriptions
Suggest testing locally before pushing
Reference existing tools as examples
Explain the auto-generation if they try to edit README manually
Guide towards self-contained solutions that fit the junk drawer philosophy

Remember: This repo is about quality over quantity. Each tool should be polished, documented, and genuinely useful. The auto-generation system ensures consistency, but curated content ensures quality.

Made with ❤️ for future AI agents — help keep this drawer organized!

Source: JeremyVyska/copilot-junk-drawer · 7★ Repo: If this repo had a smell, it would be IKEA pencils. It's all useful, just ... situational

CLAUDE.md — JeremyVyska/copilot-junk-drawer