markdown workflow for ai-assisted coding
flaitron
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.
Flaitron 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 flaitron 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 flaitron 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. Flags add debug, loop, micro, fast, and unattended modes.
/ft-open-epicFile 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-refactorPlan a behavior-preserving refactor as a sequenced epic — read-only analysis, then filed children.
/ft-file-taskFile a follow-up from inside an active tasknote — a one-line park, a rich-context starter, or an unattended filing.
Audit family
Capped, prioritized reviews that file tickets back to PLAN.md.
/ft-auditPrincipal-engineer audit by domain — general, backend, frontend, security, performance, docs, structure, context.
/ft-audit-repoFirst-contact holistic repo audit for a freshly adopting project.
Utilities
Bootstrap and maintain the workflow itself.
/ft-adoptBootstrap 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-seed-unattendedMark the PLAN.md rows safe to run unattended, in one reviewed pass.
/ft-releaseCut a flaitron release — version bump, doc sweep, tagged commit (flaitron-self only).
Deliberately omitted
What flaitron 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 flaitron 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. Flaitron 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. Flaitron'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.