Tasks as Code

A new "Tasks as Code" workflow proposes storing development tasks as Markdown files inside Git repositories so AI coding agents can read requirements and code in one place, with every task change versioned and reviewable like a commit. The approach, modeled on the existing Docs as Code practice and related to Spec-Driven Development, uses a five-step loop in which an agent describes, analyzes and plans a task, a developer reviews and approves the plan, and the agent implements the change and appends an implementation report to the same file. The author runs three separate Git repositories for code, documentation and tasks so that sensitive task data can have different access controls from public documentation.

Tasks as Code: Move Your Tickets into the Repository AI coding agents work best when everything they need lives in the repository, since the code is their source of truth. Yet most teams still track tasks and requirements in tools like Jira or Redmine that sit outside it. Storing tasks as simple Markdown files changes that: agents can read the requirements and the code in one place, and every task change is versioned and reviewable like any other commit. The Docs as Code approach already offers the blueprint for this evolution, and a web interface that syncs with Git can keep technical writers and product owners in the loop without forcing them into the command line. Docs as Code Documentation has already made the transition from separate documentation software to Markdown files in a Git repository. Today, it often lives in a /docs folder inside the code repository. This practice is known as Docs as Code or Docs Like Code https://typemill.net/knowledge-hub/docs-as-code . With AI coding agents, this approach becomes even more useful. Agents can read documentation to understand a system, make changes to the code, and update the relevant documentation as part of the same workflow. Documentation becomes an integral part of software development rather than a separate activity that must be completed afterward. Tasks as Code The same principles apply to development tasks. When tasks are stored as Markdown files, agents can read them directly, use them to plan their work, and record the results in the same files. Git keeps the task history accessible alongside the history of the software and documentation. This idea is already reflected in the Spec-Driven Development SDD https://martinfowler.com/articles/exploring-gen-ai/sdd-3-tools.html . SDD uses specifications in Markdown to define intended behavior before an AI agent implements it. A task file can serve a similar purpose, although the level of detail depends on the work. A small maintenance task may need only a short description, while a complex feature may require acceptance criteria, technical decisions, dependencies, and testing requirements. SDD is often supported by dedicated tools such as Spec Kit, but a simpler approach is enough to start: treat the task file itself as the specification. That makes the transition easier, because it needs nothing beyond Git and an agent. Here is a simple workflow with five steps: 1. Describe the task. Write a short description of the change or feature that needs to be implemented. 2. Analyze the requirements. The agent reads the task and examines the relevant code and documentation. 3. Create an implementation plan. The agent adds a proposed solution and identifies the changes it intends to make. 4. Review and approve. A developer reviews the plan and authorizes implementation. 5. Implement and report. The agent changes the code, updates the documentation where necessary, and appends an implementation report to the task file. The task description, implementation plan, and report remain together in one file. This makes it easy to review the original requirements, understand the planned approach, and see what the agent actually changed. The approval step keeps people in control. The agent does not proceed directly from the task description to implementation; the plan can be reviewed and corrected first. An example setup In my own setup, I use three separate Git repositories: - Code - Documentation - Tasks Documentation and tasks often have different access requirements. Documentation may be public, while tasks can contain sensitive information about unfinished security fixes, internal planning, or features that have not yet been announced. Separate repositories let you configure access independently and keep tasks private. Locally, a developer clones the documentation and task repositories into folders inside the code repository. Both folders are listed in the code repository's .gitignore file, so the parent repository does not track their contents. Each cloned repository retains its own Git history and can be committed, pushed, and synchronized independently. /code-repo /src /tests /docs Separate documentation repository /user-guides /admin-manuals /developer-docs /tasks Separate private task repository /release-123 task-551-something-descriptive.md task-552-something-descriptive.md .gitignore Excludes docs and tasks All information is now available to a local coding assistant such as Claude Code or OpenCode. When implementing a task, the agent reads the task, analyzes the code, implements the change, and updates the relevant documentation. The implementation report stays with the task, while the actual code changes are recorded in the code repository. Referencing the task filename in a Git commit helps connect the implementation to the original requirements. When tasks are organized into release folders, the agent can use completed tasks and Git history to draft the changelog and release notes. The same information can help identify documentation that needs updating. Adding an Interface Git and an AI coding agent are sufficient to run this workflow. A browser-based interface adds another way to browse, edit, and organize the files without replacing Git as the underlying version control system. Typemill can synchronize content with Git repositories. Because it supports multiple repositories, you can configure a separate project for private tasks alongside the documentation project. This allows you to manage both through the same interface even though the content lives in separate repositories. Tasks: Documentation: The same files are accessible through three interfaces: - In an IDE: Developers and AI agents work directly with the local repositories. - On GitHub: Contributors can review changes and edit files through the repository interface. - In a browser: Typemill provides an interface for reading and managing tasks and documentation. Each interface serves a different purpose. The IDE supports implementation, GitHub provides repository-level collaboration, and the CMS offers a content interface and publishing platform for non-technical users such as product owners and technical writers. Git remains responsible for version history and synchronization. This setup illustrates an important distinction: the interface does not have to own the data. It provides a convenient way to work with files that remain portable and accessible to other tools. Local, Private, and File-Based Typemill and a flat-file CMS are only one quick option to experiment with this workflow. Any setup that keeps Markdown files in Git and gives agents access to them will work, and you can start with nothing more than a folder of task files. The more interesting question is what happens next. Once tasks follow documentation into the repository, we will see new software and interfaces designed for this model. Developers, product owners, and technical writers will need a shared place to work, and agents will be part of that workflow. It is also an open question which features of current ticket systems are still needed: assignments, comments, kanban boards, sprints? Probably not all of them if agents do most of the work. Based on the setup above, these are the properties I would look for: - Git-native: Tasks and specifications are readable files managed through Git and connected to the code and documentation. - Docs and tasks together: One interface provides access to both documentation and task management. - File-based: Markdown remains readable, portable, and independent of a particular platform. - Self-hosted: Teams retain control over their data, privacy, and infrastructure. - Open to AI services: Developers can choose their preferred AI provider, and the interface should offer generic integrations rather than lock users into a single service.