markdown workflow for ai-assisted coding
flowtron
The markdown workflow that planned and shipped this site — self-contained four-phase tasknotes, a relevance gate that kills stale work before it starts, and context windows small enough to hold a whole task.
Why it exists
Running a handful of side projects with an AI coding assistant, I kept re-inventing a workflow per repo — and watching each one rot into a snowflake of stale plans and half-finished conventions. The assistant would confidently execute tasks that no longer mattered, on context so bloated it lost the plot.
Flowtron is what survived: one markdown source of truth per project, pulled in as a git submodule, driving self-contained tasknotes that keep the assistant's context small and every task honest. No scripts, no daemons, no database — just the workflow pattern that outlasted three concurrent projects, with every piece of infrastructure that didn't earn its weight thrown away. It planned and shipped this very site.
Principles
Six rules that stayed.
Everything else was cut. What's left is the smallest workflow contract that still keeps scope drift out and context windows small.
Markdown over JSON
Plans and tasknotes are plain markdown — human-editable, AI-scannable in diffs, safe to update in part. Nothing here parses JSON, so nothing needs it.
Zero scripts
Every operation is cp, mv, or editing markdown. No flowtron new, no validator, no daemon — skills just wrap the commands you'd run by hand.
One task per context window
Tasknotes are sized so the assistant holds the whole scope in working memory: plan entry, checklist, files touched, tradeoffs. Anything larger becomes an epic.
Relevance before action
Every tasknote opens with a Proceed / Re-scope / De-scope gate. Plans go stale faster than they're updated — killing zombie work is cheaper than executing it.
Versioned and pinned
Adopting projects pin a specific flowtron commit via submodule and bump deliberately. No force-upgrades; every task rides the version it was written against.
Extension-first
Prefer extending an existing pattern — a sibling skill, a parallel doc convention — over inventing a parallel shape. The pattern survey is a per-task contract step.
How it works
Every task, four phases.
A tasknote is driven in strict serial order — the same lifecycle the hero pipeline streams through. No skipping ahead.
Discovery
Relevance gate, read the code, skim the archive for prior decisions, drift-check the plan, then populate concrete subtasks.
Execution
Survey neighboring code for a pattern to extend, implement the minimal solution, add tests for non-trivial behavior. Stay tightly scoped.
Testing & Linting
Run targeted tests and lint/type-check on the changed code; confirm frontend changes visually. Full suite only for cross-cutting work.
Closure
Sweep the docs for drift, flip the PLAN.md line to a Completed stub, and archive the tasknote as the canonical record of the work.
Skills
A slash command for every move.
The workflow ships as agent skills — invoked by name, they wrap the same cp / mv / edit-markdown operations you'd run by hand. Every slug carries the reserved ft- prefix.
Tasknote runners
Start and drive a task through the four phases.
/ft-taskThe core runner — scaffold a tasknote and drive it through all four phases.
/ft-epic-discoveryFile a new epic and drive its Discovery child in one motion.
/ft-close-epicClose an epic via its terminal audit subtask, then flip the parent.
/ft-debugHypothesis-first debugging tasknote: expected vs. observed, ranked hypotheses, minimal repro.
/ft-goal-taskGoal loop — repeat execute→verify against a fixed acceptance target until it's met.
/ft-micro-taskStart and finish a small task in one shot, below the full four-phase ceremony.
/ft-starter-taskFile a rich-context task discovered mid-flow that isn't ready to start.
/ft-file-followupFile a one-line follow-up from inside an active tasknote.
Audit family
Capped, prioritized reviews that file tickets back to PLAN.md.
/ft-auditGeneral principal-engineer audit — five passes, capped findings.
/ft-audit-repoFirst-contact holistic repo audit for a freshly adopting project.
/ft-audit-securitySecrets, input handling, auth, network boundaries, dependencies.
/ft-audit-frontendBundle, accessibility, render perf, browser hygiene, component health.
/ft-audit-backendInput contracts, error lifecycle, persistence, async correctness, observability.
/ft-audit-performanceHot paths, payload, data access, memory, caching.
/ft-audit-docsClaims-vs-code, cross-doc consistency, cross-references, currency.
/ft-audit-contextBloat, redundancy, namespace, and drift across the AI-context files.
Utilities
Bootstrap, maintain, and inspect the workflow itself.
/ft-new-projectBootstrap a fresh repo — add the submodule, wire the skills, drop the skeleton.
/ft-updateBump an adopter's pinned submodule to the latest released tag.
/ft-releaseCut a flowtron release — version bump, doc sweep, tagged commit (flowtron-self only).
/ft-qualityRun lint + type-check + test in sequence, fail-fast, stack-detected.
/ft-statsModel distribution, completion velocity, and per-area volume from PLAN.md.
/ft-flowtronShow the flowtron version, principles, and the full skill roster.
/ft-worktree-startIsolate an independent epic child in its own git worktree + branch.
/ft-worktree-endMerge, archive, and clean up an epic-child worktree.
Deliberately omitted
What flowtron won't become.
Staying thin is a feature. Contributions — AI-suggested or human — get filtered against this list, and these are rejected on purpose.
Schema validators
Markdown is the schema and the assistant catches drift. A runtime checker reintroduces the friction flowtron exists to remove.
Premature abstractions
A helper is only canonical once two projects need the same shape. Three similar lines beat an abstraction that fits none of them.
Cross-project query layers
Each project owns its history. The read-only Kanban visualizer is the one aggregated surface — anything richer is out of scope.
Team features
It's a solo system. No assignment fields, reviewer queues, approval workflows, or role-based access — teams have different tools.
Audit daemons
The control is the human at the gate, not a risk-scorer. Deterministic enforcement belongs in per-project permission hooks.
Loop runtimes
The runner, scheduler, and session lifetime belong to Claude Code's /loop. Flowtron ships only the markdown contract a loop reports to.
Agent memory
The state lives on disk.
Autonomous agents need memory that survives the context window. Flowtron's markdown already is that layer — no vector store, no server, nothing to enable.
PLAN.mddurable intentPriorities, open tasks, and the whole Completed history in one scannable, git-versioned file.
tasknote/<ID>.mdworking stateGoal, acceptance criteria, subtasks, and the phase log. A fresh session reads one file and picks up where the last stopped.
archive/<area>/long-term memoryOne file per completed task — decisions, regressions, and rationale. The Discovery archive-skim is the recall step.
git historyprovenanceTime-travel for all of the above. The memory is diffable, revertable, and reviewable like any other source.
Open source, MIT all the way down.
Read the contract, adopt it in your own repo, or open an issue. The same workflow that scoped every card in this portfolio.