When I\u2019m in a coding rush, I often forget to update copilot-instructions.md after asking GitHub Copilot to do things. It feels redundant to put the same information into both the chat prompt and the instructions file.<\/p>\n
Try Spec Kit: Spec-driven development made practical<\/p>\n
Spec Kit provides a structured process to bring spec-driven development to your coding agent workflows with tools including GitHub Copilot, Claude Code, and Gemini CLI. Plus, it\u2019s open source (and we\u2019re updating it constantly).\u00a0<\/p>\n
\ud83d\udc49 Get started with Spec Kit on GitHub<\/a><\/p>\n Which made me wonder: What if I \u201cwrote\u201d the entire app in the Markdown instructions file?<\/p>\n For my latest pet project \u2014 GitHub Brain MCP Server<\/a> \u2014 I tried exactly that by writing the app code in Markdown and letting GitHub Copilot compile it into actual Go code. As a result, I rarely edit or view the app\u2019s Go code directly.\u00a0<\/p>\n This process should work with any AI coding agent and programming language, though I\u2019ll use VS Code, GitHub Copilot, and Go as examples. GitHub Brain MCP Server<\/a> will be my example app throughout this post.<\/p>\n Let\u2019s jump in.\u00a0<\/p>\n Setup: What I used to get started<\/p>\n There are four key files:<\/p>\n . At a high level, I edit README.md or main.md to develop the app, invoke compile.prompt.md to let the AI coding agent generate main.go, then build and run main.go like any other Go app. Next, I\u2019ll break down each file and the workflow.<\/p>\n README.md: User-facing documentation<\/p>\n The example app, GitHub Brain MCP Server<\/a>, is a command-line tool. Its README.md provides clear, user-facing instructions for installation and usage. If you write libraries, this file should contain API documentation. Below is a condensed excerpt from the example app\u2019s README.md<\/a>:<\/p>\n # GitHub Brain MCP Server<\/p>\n **GitHub Brain** is an experimental MCP server for summarizing GitHub discussions, issues, and pull requests.<\/p>\n ## Usage<\/p>\n “`sh **Workflow:**<\/p>\n 1. Populate the local database with the `pull` command. ### `pull`<\/p>\n Populate the local database with GitHub data.<\/p>\n Example:<\/p>\n “`sh Arguments:<\/p>\n – `-t`: Your GitHub personal access token. **Required.** ### `mcp`<\/p>\n Start the MCP server using the local database.<\/p>\n …README.md continues…<\/p>\n Nothing special here\u200a, \u200ajust regular documentation. But it gets interesting when this file is included in main.md.<\/p>\n main.md: AI coding agent specification<\/p>\n main.md is the actual source code of the app: the Markdown instructions file. Whenever I need to add features or fix bugs, I edit this file. Here\u2019s the opening of the example app\u2019s main.md<\/a>:<\/p>\n # GitHub Brain MCP Server<\/p>\n AI coding agent specification. User-facing documentation in [README.md](README.md).<\/p>\n ## CLI<\/p>\n Implement CLI from [Usage](README.md#usage) section. Follow exact argument\/variable names. Support only `pull` and `mcp` commands.<\/p>\n ## pull<\/p>\n – Resolve CLI arguments and environment variables into `Config` struct: …main.md continues…<\/p>\n Notice how the user-facing documentation from README.md is embedded in the specification. This keeps documentation and implementation in sync. If I want to add an alias for the -o argument, I just update README.md<\/a> with no extra steps required.<\/p>\n Here\u2019s another snippet from the example app\u2019s main.md<\/a>:<\/p>\n ### Discussions<\/p>\n – Query discussions for each repository with `has_discussions_enabled: true` “`graphql – If repository doesn’t exist, remove the repository, and all associated items from the database and continue …main.md continues…<\/p>\n This is effectively programming in Markdown and plain English: storing variables, loops, and logical conditions. You get all the usual keywords \u2014 if, foreach, or continue. It\u2019s a blend of structural and declarative styles, with Markdown links []() for imports.<\/p>\n The database schema is also coded in Markdown:<\/p>\n ## Database<\/p>\n SQLite database in `{Config.DbDir}\/{Config.Organization}.db` (create folder if needed). Avoid transactions. Save each GraphQL item immediately.<\/p>\n ### Tables<\/p>\n #### table:repositories<\/p>\n – Primary key: `name` – `name`: Repository name (e.g., `repo`), without organization prefix …main.md continues…<\/p>\n compile.prompt.md: AI coding agent prompt<\/p>\n compile.prompt.md uses GitHub Copilot\u2019s prompt file<\/a> format. This repeatable prompt tells the agent to compile main.md into main.go. Here\u2019s compile.prompt.md<\/a> from the example app:<\/p>\n — – Update the app to follow [the specification](..\/..\/main.md)
\n\u251c\u2500\u2500 .github\/
\n\u2502 \u2514\u2500\u2500 prompts\/
\n\u2502 \u2514\u2500\u2500 compile.prompt.md
\n\u251c\u2500\u2500 main.go
\n\u251c\u2500\u2500 main.md
\n\u2514\u2500\u2500 README.md<\/p>\n
\ngo run main.go []
\n“`<\/p>\n
\n2. Start the MCP server with the `mcp` command.<\/p>\n
\ngo run main.go pull -o my-org
\n“`<\/p>\n
\n– `-o`: The GitHub organization to pull data from. **Required.**
\n– `-db`: Path to the SQLite database directory. Default: `db` folder in the current directory.<\/p>\n
\n – `Organization`: Organization name (required)
\n – `GithubToken`: GitHub API token (required)
\n – `DBDir`: SQLite database path (default: `.\/db`)
\n– Use `Config` struct consistently, avoid multiple environment variable reads
\n– Pull items: Repositories, Discussions, Issues, Pull Requests, Teams
\n– Use `log\/slog` custom logger for last 5 log messages with timestamps in console output<\/p>\n
\n– Record most recent repository discussion `updated_at` timestamp from database before pulling first page<\/p>\n
\n{
\n repository(owner: “”, name: “”) {
\n discussions(first: 100, orderBy: { field: UPDATED_AT, direction: DESC }) {
\n nodes {
\n url
\n title
\n body
\n createdAt
\n updatedAt
\n author {
\n login
\n }
\n }
\n }
\n }
\n}
\n“`<\/p>\n
\n– Query discussions ordered by most recent `updatedAt`
\n– Stop pulling when hitting discussions with `updatedAt` older than recorded timestamp
\n– Save or update by primary key `url`
\n– Preserve the discussion markdown body<\/p>\n
\n– Index: `updated_at`<\/p>\n
\n– `has_discussions_enabled`: Boolean indicating if the repository has discussions feature enabled
\n– `has_issues_enabled`: Boolean indicating if the repository has issues feature enabled
\n– `updated_at`: Last update timestamp<\/p>\n
\nmode: agent
\n—<\/p>\n
\n– Build the code with the VS Code tasks. Avoid asking me to run `go build` or `go test` commands manually.
\n– Fetch the GitHub home page for each used library to get a documentation and examples.<\/p>\n
![\"Screenshot](\"https:\/\/www.newsbeep.com\/uk\/wp-content\/uploads\/2025\/10\/image-2.png\")
<\/p>\n![\"Screenshot](\"https:\/\/www.newsbeep.com\/uk\/wp-content\/uploads\/2025\/10\/image-2_87448b.png\")
<\/p>\n![\"Screenshot](\"https:\/\/www.newsbeep.com\/uk\/wp-content\/uploads\/2025\/10\/image-4.png\")
<\/p>\n![\"Screenshot](\"https:\/\/www.newsbeep.com\/uk\/wp-content\/uploads\/2025\/10\/image-3_bc6205.png\")
<\/p>\n