Tonkinai

I'm a builder.

My Profitable Projects

Products that earn their keep.

My daily driver

AGENTS.md

Below is the AGENTS.md that drives my workflow. It omits low-level details like npm commands and code style guidelines, because the agents no longer need to be babysat. The focus now is on how they work with me.

File

AGENTS.md

  1. 1# Tonkinai Workflow
  2. 2 
  3. 3## Purpose
  4. 4 
  5. 5This repository uses an iteration-based execution workflow designed to keep planning light, execution focused, and documentation useful.
  6. 6 
  7. 7## Core Operating Rules
  8. 8 
  9. 91. Project hierarchy: iteration → slice → task.
  10. 102. Plan at the iteration level, not at the task-list level.
  11. 113. Focus on the active iteration and active slice only.
  12. 124. Handle only the single next task.
  13. 135. Never invent a full task breakdown for a slice.
  14. 146. Complete one task at a time.
  15. 157. Verify each completed task before treating it as done.
  16. 168. Record outcomes, not implementation details.
  17. 179. Never make technical or product decisions without discussion.
  18. 18 
  19. 19## Project Documentation Structure
  20. 20 
  21. 21```text
  22. 22.building/
  23. 23 product.md
  24. 24 design.md
  25. 25 iterations.md
  26. 26 i1-mvp/
  27. 27 spec.md
  28. 28 plan.md
  29. 29 changelog.md
  30. 30 i2-internal-beta/
  31. 31 i3-ga/
  32. 32```
  33. 33 
  34. 34### `.building/product.md`
  35. 35 
  36. 36Defines product context, goals, and business intent.
  37. 37 
  38. 38### `.building/design.md`
  39. 39 
  40. 40Defines design philosophy and UI guidelines.
  41. 41 
  42. 42Must include: layout, typography, and colors.
  43. 43 
  44. 44### `.building/iterations.md`
  45. 45 
  46. 46Tracks iteration status across the project.
  47. 47 
  48. 48### `.building/<iteration>/spec.md`
  49. 49 
  50. 50Defines what the iteration must achieve.
  51. 51 
  52. 52Must include:
  53. 53 
  54. 54- objective
  55. 55- user or business outcome
  56. 56- constraints
  57. 57- non-goals
  58. 58- success criteria
  59. 59 
  60. 60This is the source of truth for iteration scope.
  61. 61 
  62. 62### `.building/<iteration>/plan.md`
  63. 63 
  64. 64Defines the implementation approach for the iteration.
  65. 65 
  66. 66Must include:
  67. 67 
  68. 68- overview
  69. 69- iteration decisions
  70. 70- slice status list
  71. 71- slice definitions
  72. 72- slice-specific decisions when needed
  73. 73 
  74. 74Do not predefine implementation tasks for slices.
  75. 75 
  76. 76### `.building/<iteration>/changelog.md`
  77. 77 
  78. 78A record of execution for the iteration.
  79. 79 
  80. 80Purpose:
  81. 81 
  82. 82- preserve meaningful implementation history
  83. 83- keep the current state obvious
  84. 84- help determine the next task
  85. 85 
  86. 86Add one entry for each completed task-sized unit of work, ordered newest first.
  87. 87 
  88. 88Write each entry as a direct, concise outcome, not the mechanical change.
  89. 89 
  90. 90## Execution Flow
  91. 91 
  92. 92When executing work, always follow this sequence:
  93. 93 
  94. 941. Identify the active iteration.
  95. 952. Read `spec.md`, `plan.md`, and recent `changelog.md` entries for that iteration.
  96. 963. Identify the active slice.
  97. 974. Assess progress against the slice exit criteria.
  98. 985. Propose the single next task.
  99. 996. Wait for user confirmation before implementing.
  100. 1007. Implement the task.
  101. 1018. Verify the result.
  102. 1029. Update the changelog.
  103. 10310. If the slice is complete, advance the slice state.
  104. 10411. If the iteration is complete, update `.building/iterations.md`.
  105. 10512. Wait for the user's acceptance test result before committing.
  106. 106 
  107. 107## Task Proposal
  108. 108 
  109. 109When asked, `What next?`, propose exactly one task that moves the active slice toward its exit criteria.
  110. 110 
  111. 111Write task proposals in plain English. Use concise, direct sentences that are easy to skim.
  112. 112 
  113. 113Task documentation:
  114. 114 
  115. 115- Save the task plan to a file under `docs/` for review.
  116. 116- After completing the task, create a short, skimmable UAT checklist.
  117. 117 
  118. 118## Double-Check
  119. 119 
  120. 120When prompted with `Double-check!`, review the work from the current session for completeness.
  121. 121 
  122. 122For a task proposal, review the plan with fresh eyes and identify anything that should be clarified or decided before implementation begins.
  123. 123 
  124. 124## Status Values
  125. 125 
  126. 126Allowed statuses for iterations and slices:
  127. 127 
  128. 128- `[ ]` todo
  129. 129- `[.]` in progress
  130. 130- `[x]` done
  131. 131- `[?]` blocked
  132. 132- `[-]` cancelled
  133. 133 
  134. 134## ID Formats
  135. 135 
  136. 136- Iteration: `I1`, `I2`, `I3`
  137. 137- Slice: `S1`, `S2`, `S3`
  138. 138- Task: `01`, `02`, `03`
  139. 139- Work ID: `I1/S1/01`, `I1/S1/02`
  140. 140 
  141. 141## Commit Rule
  142. 142 
  143. 143Remove temporary documents, including the task proposal and the UAT checklist, before committing.
  144. 144 
  145. 145Commit format:
  146. 146 
  147. 147```text
  148. 148build(I1/S2/03): enforce auth redirect
  149. 149```
  150. 150 
  151. 151## Project Document Templates
  152. 152 
  153. 153### `.building/iterations.md`
  154. 154 
  155. 155```md
  156. 156# Iteration Status
  157. 157
  158. 158- [.] [I1 MVP](i1-mvp/plan.md) - Optional short notes
  159. 159- [ ] [I2 Internal Beta](i2-internal-beta/plan.md)
  160. 160- [ ] [I3 GA](i3-ga/plan.md)
  161. 161```
  162. 162 
  163. 163### `.building/<iteration>/plan.md`
  164. 164 
  165. 165```md
  166. 166# I1 MVP Plan
  167. 167
  168. 168## Overview
  169. 169
  170. 170## Iteration Decisions
  171. 171
  172. 172## Slice Status
  173. 173
  174. 174- [x] [S1 Repository Foundation](#s1-repository-foundation) - Base scaffold complete
  175. 175- [.] [S2 Auth and Workspace Shell](#s2-auth-and-workspace-shell) - Optional short note
  176. 176- [ ] [S3 Core CRUD](#s3-core-crud)
  177. 177
  178. 178## S1 Repository Foundation
  179. 179### Goal
  180. 180### Scope
  181. 181### Non-goals
  182. 182### Dependencies
  183. 183### Exit Criteria
  184. 184### Slice Decisions
  185. 185```
  186. 186 
  187. 187### `.building/<iteration>/changelog.md`
  188. 188 
  189. 189```md
  190. 190# I1 MVP Changelog
  191. 191
  192. 192## I1/S2/03 — 2026-03-25
  193. 193Unauthenticated users are redirected to sign-in before accessing the workspace.
  194. 194```
  195. 195 
  196. 196### Task Proposal
  197. 197 
  198. 198```md
  199. 199# Title
  200. 200## Goal
  201. 201## Scope
  202. 202## Done when
  203. 203## Decisions
  204. 204## Approach
  205. 205```
  206. 206 

How I build

Just ask: “What next?”

tl;dr: I don’t manage tasks. I define scope. The agent figures out execution. I just keep asking “What next?”

I used to manage task backlogs and review code.

That’s not how I build anymore with AI agents since Opus 4.5 and Codex 5.3.

My job is to define what should be built. The agent figures out how.

Everything starts with a product definition.

I write down what I want in product.md. Not features, not tickets—just the product: what it is, why it exists, and what outcome it should create.

From there, I move to design.md. This takes a few iterations. It’s where I shape how the product should feel—layout, typography, colors, interaction patterns. I don’t rush this part. Once design is clear, everything downstream gets easier.

Then comes the first iteration.

I define a tight, deliberate scope in spec.md. Objective, constraints, success criteria, and—equally important—non-goals. This becomes the boundary the agent operates within. If the scope is loose, everything degrades. If it’s sharp, everything accelerates.

At this point, I ask the agent to create a plan—not a task list.

The plan is structured into slices—vertical chunks of functionality with clear exit criteria. This is critical. Progress is measured by completing slices, not checking off tasks.

Once the plan feels right, execution begins.

From here on, the workflow becomes almost trivial.

I just ask:

“What next?”

The agent proposes exactly one task. That task is designed to move the current slice closer to its exit criteria.

I read the task proposal:

  • What is the goal?
  • What approach is being taken?
  • What decisions are being made?

If something feels off, I push back. If it’s aligned, I approve.

This is the highest leverage point. It’s much easier to steer intent than to review implementation.

The agent executes, then gives me a UAT checklist.

I verify outcomes, not implementation. If something is wrong, we adjust. If it’s good, we move forward.

I usually don’t read the code.

Every completed task updates the changelog. Not with technical details, but with outcomes. This keeps the current state obvious and gives the agent context for what comes next.

Over time, the changelog becomes memory. Not just for me, but for the system.

There are a few rules I’ve learned the hard way.

If a task is well-scoped, the code is usually excellent.

If a task is vague, the agent starts inventing decisions. That’s when quality drops.

So I don’t try to control execution. I control scope and decisions.

Also, I never plan too far ahead. The system works because it’s always focused on:

  • the current iteration
  • the current slice
  • the single next task

Anything beyond that is noise.

This workflow is lightweight by design.

There’s no backlog. No long task lists. No pretending we know everything upfront.

Just:

  • define the iteration
  • agree on the plan
  • execute one step at a time

It turns out this is also the easiest way to multitask.

I can jump between projects without losing context. Each one just needs a quick “What next?” and the agent picks up from the current state.

So, what next?