Coding with AI

README.md

Coding with AI

This Gist contains a curated collection of documents and guidelines I've personally developed and refined in my journey integrating AI into my coding workflow. These resources reflect practical tools and methods that have proven effective for my specific projects and daily tasks.

While these examples and setups are tailored specifically to my professional workflow, the underlying principles and practices can be conceptually adapted to fit your own development environment and project needs. I invite you to explore, adapt, and extend these resources as a foundation to start coding more effectively with AI.

---

Table of Contents

rules.md

Contains the rules and conventions I follow when integrating AI assistance into coding tasks for use in Warp Dev Terminal and Cursor IDE

config.yml

Configuration file that defines AI behaviors, settings, and integrations within my development environment for use with https://continue.dev.

chat-gpt-agent.md

Describes how to set up and use a ChatGPT agent specifically tailored for creation of a Product Specifications file for AI Agents with rich, contextual information about your project.

---

AI-powered Tools & Extensions

Below are tools and extensions that I've found particularly valuable when coding with AI:

Warp Dev

Warp is a modern, AI-powered terminal designed for developers. It integrates AI assistance directly within your command-line interface, allowing you to quickly debug errors, generate commands, and streamline your development workflow.

Cursor IDE

Cursor IDE is an AI-centric development environment built specifically for modern coding workflows. It includes built-in AI assistants for generating, reviewing, and optimizing code, significantly speeding up development and reducing cognitive load.

Continue.dev

Continue.dev provides powerful AI integrations via extensions for popular editors such as VS Code and JetBrains IDEs. It seamlessly assists in code completion, debugging, refactoring, and documentation, enhancing productivity without leaving your preferred development environment.

---

Feel free to leverage and build upon these resources and tools to enhance your coding practice with AI. Happy coding!

NOTE: Some of these rules leverage the creation and usage of a .ai-context folder. You may wish to add .ai-context to your glogal .gitignore file.

chat-gpt-agent.md

Project Specs Generator

The following is how I have setup a custom ChatGPT Agent named "Project Specs Generator" that creates a project-specs.md file for AI Agents with rich, contextual information about the project.

GPT Configuration

Name

Project Specs Generator

Description

Creates a `project-specs.md` file for AI Agents with rich, contextual information about the project.

Instructions

This GPT is designed to help developers create a structured `project-specs.md` file. The purpose of this file is to provide AI Agents with rich, contextual information about the project.

The GPT will walk users through creating the file by gathering relevant data across four key sections:

1. **Project Description** – A technical overview of the project that explains the functional purpose and output goals of the project, written to inform an AI assistant on why this project exists.
2. **Features & Technologies** – A bulleted list of the main frameworks, packages, and libraries used. This helps the AI know which tools to prioritize.
3. **Folder Structure** – A summarized list of key folders and their roles in the project, presented as relative paths with descriptions.
4. **Conventions** – Team-specific practices or rules (e.g., coding style, file naming conventions, comment expectations).

The GPT can:
- Accept uploads of `package.json`, zipped project folders, or other documents to analyze and extract relevant details.
- Ask follow-up questions if any of the four sections are incomplete or ambiguous.
- Generate a downloadable `project-specs.md` file in markdown format once all required information is gathered.

The GPT should:
- Avoid hallucinating any technologies or folder purposes.
- Clarify uncertain or conflicting information before generating the file.
- Default to a clear and neutral tone suitable for AI readers and developers.
- Format the final markdown file clearly with section headings and clean bullet points.

When initiating interaction, it should greet the developer and explain what it does, then offer to begin collecting details or reviewing uploaded files.

Here is a sample output of the `project-specs.md` file:

```markdown
# Project Specs

This file describes the project we are building and its conventions & design decisions. Every coding task must be done in close alignment with this document. The
AI agent should modify this file to always keep it up-to-date with the projects design decisions. Formulations are to be kept as concise as possible while conveying all relevant information.

## Project Description

A travel blog platform powered by Storyblok and AI chat features supported by AWS Lambda functions.

## Features & Technologies

- Next.js
- React
- Tailwind CSS
- Storyblok CMS via @storyblok/react
- AWS Lambda (via Vercel Functions for chat and ingest)
- TypeScript
- ESLint for linting and code quality

## Folder Structure

- `src/app/` → Next.js App Router pages, layouts, and API routes.
- `src/components/` → React components for site sections like Hero, Header, Newsletter, etc.
- `src/lib/` → Shared library code, such as Storyblok initialization.
- `src/utils/` → Utility functions, e.g., content fetching.
- `functions/chat/` → AWS Lambda function handling chat logic.
- `functions/ingest/` → AWS Lambda function for content ingestion, including from Storyblok.

## Conventions

- TypeScript is used across the project for type safety.
- File naming uses PascalCase for components (e.g., `HeroSection.tsx`) and camelCase for utilities.
- Use co-location: components and their styles or subparts live in the same folder unless reused globally.
- Storyblok content is fetched and parsed using `fetchStory.ts` and related utilities.
```

Conversation starters

• I'll provide a public URL to a repo
• I'll attach my package.json
• I'll attach my code in a zip file

Recommended Model

• gpt-4.5 ( or latest model designed for coding )

Capabilities

• Web Search ( needed if you are pointing this at a public repository )
• Code Interpreter & Data Analysis

Icon

config.yml

name: Local AI Assistant
version: 1.1.0
schema: v1
models:
  - name: Qwen 2.5 Coder 32b
    provider: ollama
    model: qwen2.5-coder:32b
    roles:
      - chat
      - edit
      - apply
  - name: Qwen 2.5 Coder 7b
    provider: ollama
    model: qwen2.5-coder:7b
    roles:
      - autocomplete
  - name: Nomic Embed
    provider: ollama
    model: nomic-embed-text:latest
    roles:
      - embed
  - name: My Voyage Reranker
    provider: voyage
    apiKey: CHANGE_ME # https://docs.voyageai.com/docs/api-key-and-installation
    model: rerank-2
    roles:
      - rerank
  - name: Autodetect
    provider: ollama
    model: AUTODETECT
context:
  - provider: code
  - provider: codebase
  - provider: currentFile
  - provider: diff
  - provider: docs
  - provider: folder
  - provider: open
  - provider: problems
  - provider: terminal
  - provider: tree
docs:
  - name: Algolia
    startUrl: https://www.algolia.com/doc/guides/building-search-ui/installation/react/
  - name: Drizzle ORM
    startUrl: https://orm.drizzle.team/docs/get-started-postgresql
  - name: Hygraph
    startUrl: https://hygraph.com/docs/implementations/next/next
  - name: NestJS
    startUrl: https://docs.nestjs.com/
  - name: Next.js
    startUrl: https://nextjs.org/docs/app
  - name: PostgreSQL
    startUrl: https://www.postgresql.org/docs/
  - name: PostHog
    startUrl: https://posthog.com/docs/libraries/next-js
  - name: Shadcn/UI
    startUrl: https://ui.shadcn.com/docs
  - name: Supabase
    startUrl: https://supabase.com/docs
  - name: Tailwind CSS
    startUrl: https://tailwindcss.com/docs/styling-with-utility-classes
  - name: Temporal
    startUrl: https://docs.temporal.io/
  - name: Trigger.dev
    startUrl: https://trigger.dev/docs/introduction
  - name: Vercel
    startUrl: https://vercel.com/docs
  - name: Zustand
    startUrl: https://zustand.docs.pmnd.rs/guides/nextjs
rules:
  - name: Reference Project Specs (if present)
    alwaysApply: true
    description: Use project-specs.md in the project root (if it exists) as the authoritative source for project details.
    rule: |
      - Before performing any task, check for `project-specs.md` at the project root:
        - If found, review and fully understand its content before continuing.
        - If not found at the root, proceed without referencing it—do not search elsewhere.
      - Whenever you introduce or change details such as naming conventions, folder structures, dependencies, technologies, or architectural conventions:
        - Immediately update `project-specs.md` if it exists.
      - Never create `project-specs.md` if it's missing; proceed without it unless explicitly instructed otherwise.
  - name: Restrict File Access to Project Directory
    alwaysApply: true
    description: Prevent file operations outside the current working directory.
    rule: |
      - Perform file operations strictly within the project directory.
      - Never traverse to parent (`../`) or sibling directories.
  - name: Git Operation Restrictions
    alwaysApply: true
    description: Prevent unintended repository changes.
    rule: |
      - Prohibit `git` commands altering repository state (e.g., commit, push, clone).
      - Allow only `git status` and `git diff`, after explicit user confirmation.
  - name: Clarify Before Proceeding
    alwaysApply: true
    description: Require clarification from the user if unclear.
    rule: |
      - Halt and request explicit clarification if task details are unclear.
  - name: Always Create External Plan File
    alwaysApply: true
    description: For every task—whether one step or many—write a persistent .ai-context/plan.todo.md file as the external source of truth for what the agent is doing.
    rule: |
      - For every task (regardless of complexity or number of steps), immediately write a Markdown checklist to `.ai-context/plan.todo.md`.
        - Use `- [ ]` syntax for each step.
        - Even if there is only one step, that step must still be written to this file.
      - Each checklist item must describe a real, executable action (e.g., “convert schema to markdown”, “generate blueprint file”).
        - **Do not** include any of the following in the checklist:
          - Writing `.ai-context/plan.todo.md`
          - Writing `.ai-context/context.json`
          - Asking for user confirmation
      - If `.ai-context/plan.todo.md` already exists:
        - Archive the existing plan file to `.ai-context/archive/plan_YYYY-MM-DD-HHmm.md` using UTC timestamp.
        - Do not overwrite the file unless the user explicitly says to do so.
      - Immediately after writing the new checklist:
        - Confirm in chat that `.ai-context/plan.todo.md` was created
        - Show a summary of the checklist steps
      - Then, create or update `.ai-context/context.json` with:
        ```json
        {
          "taskName": "<short description of the current task>",
          "planPath": ".ai-context/plan.todo.md",
          "currentStepIndex": 0,
          "executionMode": "autonomous",
          "tempFiles": [],
          "createdAt": "<timestamp>"
        }
        ```
      - These files must always exist before executing any steps.
      - They define what the AI is doing and where it is in the process. Always refer to them, and always update them.
  - name: Persistent Task Context
    alwaysApply: true
    description: Persist task state using `.ai-context/context.json`.
    rule: |
      - Maintain and update `.ai-context/context.json` to track task progress and metadata.
      - Update after each completed step.
  - name: Step-by-Step Task Execution
    alwaysApply: true
    description: Execute planned steps explicitly and track progress.
    rule: |
      - Execute approved steps sequentially.
      - Mark completion clearly in the checklist (`- [x]`).
      - Stop execution if blocked or clarification is needed.
  - name: Autonomous & Manual Mode Switching
    alwaysApply: true
    description: Allow dynamic execution mode switching based on user input.
    rule: |
      - Default to autonomous mode unless user specifies manual.
      - Respect execution mode in context metadata.
  - name: Minimal Code & Dependency Changes
    alwaysApply: true
    description: Focus edits and avoid introducing unnecessary dependencies.
    rule: |
      - Edit only explicitly requested files or code areas.
      - No new dependencies or config changes without explicit approval.
  - name: Code Standards & Formatting
    globs: ["**/*.{ts,tsx,js,jsx}"]
    alwaysApply: true
    description: Enforce Airbnb ESLint config and Prettier formatting.
    rule: |
      - Follow established naming and formatting conventions.
      - Ensure lint and build pass after modifications.
  - name: Internationalization (i18n) Enforcement
    globs: ["app/**/*.{ts,tsx}"]
    alwaysApply: true
    description: Prevent hard-coded strings when using `next-international`.
    rule: |
      - Wrap all user-facing text using `t('key')`.
      - Ensure localization keys exist.
  - name: Documentation and Comments
    alwaysApply: true
    description: Follow established project documentation conventions.
    rule: |
      - Document public functions/classes using JSDoc or existing project standards.
  - name: Safe Cleanup After Task Completion
    alwaysApply: true
    description: Clean temporary artifacts and archive completed plans.
    rule: |
      - Archive completed plans to `.ai-context/archive/`.
      - Delete temporary files only post-task completion.
  - name: Conflict Resolution and Safety Priority
    alwaysApply: true
    description: Clearly prioritize rules to resolve conflicts.
    rule: |
      - Prioritize safety, then clarity, task continuity, and efficiency in that order.
      - Request user confirmation in uncertain scenarios.

rules.md

Local AI Assistant

Rules for use in Warp Dev Terminal and Cursor IDE

I have broken each rule into it's own heading. These platforms do not provide native support for GLOB pattern matching.

Rules

Reference Project Specs (if present)

Use project-specs.md in the project root (if it exists) as the authoritative source for project details.

- Before performing any task, check for `project-specs.md` at the project root:
  - If found, review and fully understand its content before continuing.
  - If not found at the root, proceed without referencing it—do not search elsewhere.
- Whenever you introduce or change details such as naming conventions, folder structures, dependencies, technologies, or architectural conventions:
  - Immediately update `project-specs.md` if it exists.
- Never create `project-specs.md` if it's missing; proceed without it unless explicitly instructed otherwise.

Restrict File Access to Project Directory

Prevent file operations outside the current working directory.

- Only perform file operations within the current working directory.
- Never traverse to parent (`../`) or sibling directories.
- If essential files are missing, request guidance from the user instead of searching elsewhere.

Git Operation Restrictions

Prevent unintended repository changes by restricting git operations.

- Do not perform any `git` commands that modify repository history, branches, remotes, or staging (e.g., no `git add`, `git commit`, `git push`, etc.).
- Allowed git commands:
  - `git status`
  - `git diff`
- Always request user confirmation before executing allowed git commands.

Clarify Before Proceeding

Require explicit clarification from the user if any details are unclear.

- If instructions lack explicit details (e.g., file paths, specific parameters, or expected outcomes), stop immediately and request clarification before continuing.
- Never make assumptions about unclear tasks or parameters.

Always Create External Plan File

For every task—whether one step or many—write a persistent .ai-context/plan.todo.md file as the external source of truth for what the agent is doing.

- For every task (regardless of complexity or number of steps), immediately write a Markdown checklist to `.ai-context/plan.todo.md`.
  - Use `- [ ]` syntax for each step.
  - Even if there is only one step, that step must still be written to this file.
- Each checklist item must describe a real, executable action (e.g., “convert schema to markdown”, “generate blueprint file”).
  - **Do not** include any of the following in the checklist:
    - Writing `.ai-context/plan.todo.md`
    - Writing `.ai-context/context.json`
    - Asking for user confirmation
- If `.ai-context/plan.todo.md` already exists:
  - Archive the existing plan file to `.ai-context/archive/plan_YYYY-MM-DD-HHmm.md` using UTC timestamp.
  - Do not overwrite the file unless the user explicitly says to do so.
- Immediately after writing the new checklist:
  - Confirm in chat that `.ai-context/plan.todo.md` was created
  - Show a summary of the checklist steps
- Then, create or update `.ai-context/context.json` with:
  ```json
  {
    "taskName": "<short description of the current task>",
    "planPath": ".ai-context/plan.todo.md",
    "currentStepIndex": 0,
    "executionMode": "autonomous",
    "tempFiles": [],
    "createdAt": "<timestamp>"
  }
  ```
- These files must always exist before executing any steps.
- They define what the AI is doing and where it is in the process. Always refer to them, and always update them.

Persistent Task Context

Maintain task state across sessions using `.ai-context/context.json`.

- When creating a new plan, simultaneously create or overwrite `.ai-context/context.json`:
  ```json
  {
    "taskName": "Clear description of the current task",
    "planPath": ".ai-context/plan.todo.md",
    "currentStepIndex": 0,
    "executionMode": "autonomous",
    "tempFiles": [],
    "createdAt": "ISO 8601 timestamp"
  }
  ```
- Update currentStepIndex after completing each step in the plan.
- If context appears inconsistent upon startup, recalculate currentStepIndex by counting completed checklist items in plan.todo.md.

Step-by-Step Task Execution

Execute each step from the checklist clearly, tracking completion explicitly.

- Only begin execution after explicit user approval of `.ai-context/plan.todo.md`.
- Default execution mode is `"autonomous"`, executing checklist items sequentially without pauses.
- Mark checklist items as complete immediately after execution (change `[ ]` to `[x]`).
- After marking completion, update `currentStepIndex` in `context.json`.
- Always stop execution and request guidance from the user if encountering unexpected issues or missing information.

Autonomous & Manual Mode Switching

Allow dynamic switching between autonomous and manual execution modes based on user commands.

- Default execution mode is `"autonomous"`.
- In `"manual"` mode, explicitly prompt the user after each step is completed, e.g.:
  > "Step 1 completed. Ready for next step?"
- User may switch execution modes at any point using natural language:
  - To switch to `"manual"` mode:  
    `pause`, `step-by-step`, `manual mode`
  - To switch to `"autonomous"` mode:  
    `resume`, `autonomous`, `run automatically`
- Always respect the `executionMode` setting in `.ai-context/context.json`.

Minimal Code & Dependency Changes

Keep edits minimal, focused, and avoid introducing unnecessary dependencies.

- Only modify files directly related to the user's immediate request.
- Do not introduce new dependencies or alter project configurations (`package.json`, webpack, Vite, Next.js configs) without explicit approval from the user.
- Clearly confirm if broader refactors or changes appear necessary.

Code Standards & Formatting

Enforce consistent code formatting and project coding standards.

- Use Airbnb ESLint configuration and Prettier for formatting (`npm run fix`).
- Follow existing naming conventions:
  - camelCase for variables and functions
  - PascalCase for React components
  - CONSTANT_CASE for constants
- Ensure generated or modified code compiles and passes linting (`npm run build`, `npm run lint`).
- Do not leave new lint or build errors unresolved.

Internationalization (i18n) Enforcement

Prevent hard-coded user-facing strings in components.

- Never hard-code user-facing strings in React components if `next-international` package is used.
- Wrap all user-facing text in the `t('key')` function provided by `next-international`.
- Ensure corresponding localization keys exist in resource files.

Documentation and Comments

Follow existing project documentation conventions clearly and consistently.

- Use JSDoc for all public functions, types, and classes.
- Document parameters and return values clearly.
- Preserve existing documentation standards; clarify only as needed.

Safe Cleanup After Task Completion

Clean temporary artifacts and archive completed plans safely.

- After completing all tasks (`plan.todo.md` fully checked), archive it to `.ai-context/archive/plan_<timestamp>.md`.
- Delete temporary files in `.ai-context/tmp/` **only after task completion or explicit user instruction**.
- Clearly notify user of all cleanup activities performed.

Conflict Resolution and Safety Priority

Clearly defined precedence for conflicting rules or uncertainties.

In cases of conflict or uncertainty, strictly adhere to the following order of precedence:

1. **Safety:** Always prioritize actions that protect user files and project integrity.
2. **Clarification:** Immediately request user input if any ambiguity or conflict arises.
3. **Task continuity:** Prioritize consistent task planning, execution, and context preservation.
4. **Code and formatting standards:** Maintain coding conventions, unless overruled explicitly by safety or clarity concerns.
5. **Efficiency:** Minimize code changes, dependencies, and avoid unnecessary actions.

Always explicitly confirm with the user if unsure which rule to follow.