ai-trials

Welcome to the ai-trials project template! This repository is designed to help you kickstart new projects with a clean, organized structure and best practices in mind.

---

🚀 Getting Started

1. Clone the Repository

git clone <your-repo-url>
cd ai-trials

2. Project Structure Overview

• /docs/ — Place all documentation here (e.g., guides, architecture, changelogs).
• /possible-features/ — Use this folder to brainstorm or document potential features.
• /scripts/ — Utility scripts for automation and project management.
  • sync-feature-status.py — Example script for syncing feature status with GitHub.
• README.md — This file! Explains how to use and contribute to the project.

---

🛠️ Usage

Running Scripts

Most automation scripts are in the /scripts/ directory. For example, to run the feature sync script:

# Make sure you have Python 3 and required packages installed
pip install PyGithub python-frontmatter

# Set your GitHub token (required for API access)
export GITHUB_TOKEN=your_token_here

# Run the script
python scripts/sync-feature-status.py

Tip: The script expects a GITHUB_TOKEN environment variable for authentication.

---

📂 Documentation

• All documentation should go in the /docs/ directory.
• Update the documentation whenever you add or change features.
• For more on Markdown: Markdown Guide

---

⚡ VS Code Agent & Workflow Automation

This project is designed to work seamlessly with Visual Studio Code and GitHub Copilot (your AI pair programmer). Here’s how you can supercharge your workflow:

VS Code Agent Features

• GitHub Copilot: Get code suggestions, explanations, and documentation as you type. Use it for:

  • Generating code snippets and functions.
  • Explaining complex code or concepts.
  • Writing and updating documentation automatically.

• Task Automation:

  • Use VS Code’s built-in Tasks (see .vscode/tasks.json if present) to automate running scripts, tests, or linters.
  • Example: Press Ctrl+Shift+B to run the default build or test task.

• Extensions:

  • Install recommended extensions for Python, Markdown, and GitHub integration for a smoother experience.
  • Use the GitHub Pull Requests and Issues extension to manage PRs and issues directly from VS Code.

Workflow Automation

• Scripts:

  • Place automation scripts in /scripts/ and run them via VS Code’s terminal or as tasks.
  • Example: Sync feature status with GitHub using sync-feature-status.py.

• GitHub Actions:

  • Set up workflows in .github/workflows/ to automate testing, linting, or deployment on every push or PR.

• Documentation Automation:

  • Use Copilot or VS Code snippets to quickly generate or update Markdown docs in /docs/.

Best Practices

• Branch Automation:

  • Use VS Code’s Source Control panel to create and switch branches easily.
  • Name branches descriptively (e.g., feature/add-login, bugfix/fix-typo).

• Pull Request Reviews:

  • Use Copilot to help review code, suggest improvements, and auto-generate review comments.

• Consistent Documentation:

  • Automate changelog and documentation updates after each feature or fix.

Tip: Explore the VS Code Command Palette (Ctrl+Shift+P) for automation commands and agent-powered features.

---

🤖 Copilot Agent Mode & Custom Prompts

This project uses GitHub Copilot Agent Mode with custom prompts to enhance your learning and development experience. These prompts are always active and shape every response from the agent. Here’s how they work for you:

What the Prompts Do

• Mentorship & Explanations:

  • The agent acts as your coding mentor, always explaining technical terms in simple language.
  • Uses analogies and real-world examples to make concepts stick.
  • Every new concept or suggestion comes with a small, runnable code example (with comments) to help you learn by doing.

• Formatting & Documentation:

  • All responses are clearly structured with headings, lists, and code blocks for easy reading.
  • All documentation is written in Markdown and placed in the /docs directory.
  • The agent reminds you to update documentation and changelogs after every code change.

• Problem Solving:

  • Breaks down complex problems into smaller, manageable steps.
  • Encourages planning with pseudocode or flowcharts before coding.
  • Suggests relevant unit tests or ways to verify new code.

• GitHub Workflow:

  • Guides you to use GitHub best practices: create a new branch for each feature/fix, use descriptive branch names, and write clear commit messages.
  • Helps you with pull requests, issue tracking, and using labels/milestones.
  • Recommends using GitHub Actions, scripts, and VS Code tasks for automation.

• Collaboration & Automation:

  • Encourages frequent, small commits and clear documentation for easy collaboration.
  • Suggests using VS Code extensions and Copilot for reviews, code suggestions, and workflow automation.

• Browser Automation Features:

  • The agent can interact with web pages directly from VS Code using browser automation tools. This includes navigating, clicking, filling forms, scraping data, and even running end-to-end tests.
  • You can preview websites, automate browser actions, and generate Playwright tests for your web apps—all from your development environment.

• Feature Definition & Implementation Prompts:

  • Define Feature Prompt: When you ask to "define a feature," the agent will help you break down the requirements, clarify the user story, and document the acceptance criteria. This ensures everyone understands what needs to be built before coding starts.
  • Implement Feature Prompt: When you ask to "implement a feature," the agent will guide you through planning, pseudocode, and step-by-step implementation. It will also suggest relevant tests and documentation updates, ensuring a complete and robust solution.

Tip: You can always ask the agent for explanations, code samples, workflow advice, or documentation help. The custom prompts are designed to make learning and collaboration easier for everyone in the project.

---

🤝 Contributing

1. Create a new branch for each feature or fix:

   git checkout -b feature/your-feature-name

2. Commit your changes with clear messages.

3. Push your branch and open a Pull Request (PR).

4. Link issues and request reviews as needed.

Tips for Effective Contributing

• Leverage VS Code & Copilot: Use agent-powered code suggestions, automated documentation, and PR review tools to streamline your workflow.
• Automate Where Possible: Use scripts, tasks, and GitHub Actions to reduce manual work and keep your project consistent.

---

📝 License

Specify your project’s license here.

---

📚 Further Reading

• GitHub Docs: Managing repositories
• PyGithub Documentation
• Python frontmatter

---