Rubber Duck Thursdays! Come Cowork!

Key Concepts

• CLI Tool: A command-line interface tool, in this case, blogmark, designed to be used via the terminal.
• Markdown: A lightweight markup language used for formatting text.
• Front Matter: YAML metadata at the beginning of a markdown file containing information like title, date, author, etc.
• Agent Mode: A feature of GitHub Copilot that allows it to autonomously execute tasks based on a given prompt.
• Vibe Coding: A more relaxed and exploratory approach to coding, often involving AI assistance.
• Product Requirement Document (PRD) / Spec Doc: A document detailing the requirements, functionality, and specifications of a software product.
• Context Engineering: The practice of providing AI tools with sufficient context and information to achieve desired outcomes.
• Grounding: Providing AI with as much information as possible to prevent hallucinations.
• GitHub MCP Server: A GitHub server that automates pull requests, continuous integration, and security triages.
• Copilot Instructions: Custom instructions that provide context about a codebase to Copilot, improving its suggestions and code generation.

Building a CLI Tool with Copilot Agent Mode: BlogMark

Project Goal

The primary goal is to build a Node.js CLI tool called blogmark that converts web blog posts from any URL into markdown files with YAML front matter. This tool aims to streamline the process of converting existing blog content into a format suitable for feeding into Large Language Models (LLMs) for custom writing assistance.

Requirements and Specifications

• Core Functionality:
  • Fetch HTML content from any blog URL.
  • Extract the main article content.
  • Convert HTML to clean markdown.
  • Generate files with YAML front matter (title, date, author, tags, URL).
  • Save the converted blog post to an output directory with sanitized file names.
• CLI Interface:
  • blogmark fetch <URL>: Converts a single URL to markdown.
  • blogmark interactive: Activates interactive mode for fetching URLs.
  • Options for specifying output paths and parsers.
• Technical Specifications:
  • Use CommanderJS for building the CLI interface.
  • Use Axios for making HTTP requests.
  • Use Cheerio for parsing HTML.
  • Use Turndown for converting HTML to markdown.
  • Use js-yaml for handling YAML front matter.
  • Sanitize file names for output.
  • Implement a 10-second HTTP timeout.
  • Create a single class BlogConverter with relevant methods.
• Output Format:
  • YAML front matter at the beginning of the markdown file.
  • Converted markdown content following the front matter.

Step-by-Step Process

1. Setting up the Project:
   • Create a new Node.js project with package.json, .gitignore, and README.md.
   • Create empty files: block-converter.js and cli.js.
   • Create an output folder for storing converted markdown files.
2. Creating a Product Requirement Document (PRD):
   • Write a detailed PRD outlining the project's goals, requirements, and technical specifications.
   • Include information about core functionality, CLI interface, technical specifications, output format, package configuration, and key implementation details.
3. Creating a Prompt File:
   • In VS Code, create a new prompt file (e.g., spec.prompt.md).
   • Set the mode to "agent" and provide a brief description (e.g., "Build the MVP").
   • Paste the content of the PRD into the prompt file.
4. Executing the Prompt File:
   • Click the "play" button in VS Code to run the prompt file in Copilot Agent Mode.
   • Copilot will analyze the prompt and start building the CLI tool.
5. Monitoring and Guiding Agent Mode:
   • Observe the actions taken by Copilot, including updating package.json, creating block-converter.js and cli.js, and running terminal commands.
   • Provide feedback and guidance to Copilot as needed.
6. Testing and Iteration:
   • Test the generated CLI tool using example blog URLs.
   • Identify any issues or areas for improvement.
   • Provide specific instructions to Copilot to address these issues.
   • Re-test the tool after each iteration.
7. Code Review and Refinement:
   • Use Copilot's code review feature to identify potential issues and improvements in the generated code.
   • Apply suggestions to improve code readability, maintainability, and performance.
8. Generating Copilot Instructions:
   • Use the "Generate Instructions" feature in VS Code to create custom Copilot instructions for the project.
   • This will analyze the codebase and generate instructions that provide context to Copilot, improving its suggestions and code generation.
9. Publishing to npm (Future):
   • Thoroughly review the code to ensure it meets quality standards.
   • Publish the blogmark package to the npm registry for public use.

Key Arguments and Perspectives

• Context is King: Providing AI tools with sufficient context and information is crucial for achieving desired outcomes.
• Importance of a PRD: A well-defined PRD is essential for guiding AI tools and ensuring they build the desired product.
• Vibe Coding with Structure: Even in a relaxed coding approach, having a clear plan and specifications can significantly improve results.
• Benefits of Agent Mode: Copilot Agent Mode can automate many repetitive tasks and accelerate the development process.
• Importance of Testing and Iteration: Thorough testing and iterative refinement are necessary to ensure the quality and functionality of the generated code.

Examples and Case Studies

• Converting GitHub Blog Posts: The primary use case is converting blog posts from the GitHub blog into markdown format.
• Testing with Different Blog Platforms: The tool is tested with blog posts from WordPress (GitHub blog), Astro (personal blog), and Medium.
• Addressing Specific Issues: The tool is iteratively improved to handle different HTML structures and properly convert tables.

Technical Terms and Concepts

• Node.js: A JavaScript runtime environment for executing JavaScript code server-side.
• CLI (Command-Line Interface): A text-based interface for interacting with a computer program.
• YAML (YAML Ain't Markup Language): A human-readable data serialization format often used for configuration files.
• Axios: A promise-based HTTP client for making requests in Node.js.
• Cheerio: A fast, flexible, and lean implementation of core jQuery designed specifically for server-side environments.
• Turndown: A JavaScript library for converting HTML to markdown.
• CommanderJS: A Node.js library for building command-line interfaces.
• npm (Node Package Manager): The package manager for the Node.js JavaScript platform.
• Git: A distributed version control system for tracking changes in source code.
• GitHub: A web-based platform for version control and collaboration using Git.
• LLM (Large Language Model): A type of artificial intelligence model that is trained on a large amount of text data and can generate human-like text.

Notable Quotes

• "Context is king when you're building with AI tools."
• "The more specifications in the doc, the better the output."
• "You have to know what you want your product to look like to get successful outputs from any AI agent."

Data, Research Findings, or Statistics

• The GitHub blog is mentioned as a source of writing examples for training an LLM.
• The presenter mentions that women are underrepresented in the tech industry.

Logical Connections

The video logically connects the need for converting blog posts to markdown with the desire to streamline content creation and train custom writing assistants. It then demonstrates how Copilot Agent Mode can be used to build a CLI tool that automates this process. The video also emphasizes the importance of providing sufficient context to AI tools and iteratively refining the generated code.

Synthesis/Conclusion

The video successfully demonstrates how to build a functional CLI tool using GitHub Copilot Agent Mode. It highlights the importance of a well-defined PRD, clear instructions, and iterative testing. The resulting blogmark tool effectively converts web blog posts into markdown format, showcasing the potential of AI-assisted development for automating content creation workflows. The presenter also emphasizes the importance of code review and refinement, even when using AI tools. The creation of Copilot Instructions further enhances the project's maintainability and future development.