trace-first-starter

Trace-First Workflow (TFW) — Canonical Starter

“The thought process and the instructions are more valuable than the immediate result.”

Most work with AI happens in dialogue — and then the chat ends. Tomorrow you re-explain the project from scratch. Context evaporates across sessions, models, and teams. TFW solves this: a single ritual that captures intent, structures decisions, and makes any project resumable by any agent or human.

For the full philosophy, thesis, and design rationale → .tfw/README.md

Who This Is For

TFW is domain-agnostic. It works for:

Software engineering — architecture decisions, codebase development, debugging sessions
Data and analytics — ETL pipelines, SQL analysis, reporting with human-in-the-loop
Writing and publishing — blog posts, reports, contracts, academic papers
Education — course development, assignment creation, research projects
Product management — specs, roadmaps, decision logs

If your work involves AI-assisted iteration and you need continuity across sessions — TFW is for you.

Quick Start

New project

Fork or clone this repository
Follow .tfw/init.md to configure your project
Choose your tool adapter (Claude Code, Cursor, Antigravity, or plain chat)
Start with .tfw/workflows/plan.md to create your first task

Mid-conversation

Already deep in a chat and realize it’s time to get structured?

Paste this repo link: https://github.com/saubakirov/trace-first-starter
The agent reads README → AGENTS, harvests your existing context, and bootstraps TFW files
Review the drafts, pick a mode, continue — now with traces

What’s Inside

Root Files (your project)

File	Purpose
`README.md`	Project guide + Task Board
`AGENTS.md`	AI agent role and behavior
`KNOWLEDGE.md`	Architecture, decisions, legacy index
`TECH_DEBT.md`	Tech debt registry
`RELEASE.md`	Release strategy and context (optional)

.tfw/ (TFW core — tool-agnostic)

Path	Contents
`.tfw/README.md`	Philosophy, thesis, lifecycle, anti-patterns, evolution
`.tfw/conventions.md`	Formal rules, statuses, naming, scope budgets
`.tfw/glossary.md`	Terminology
`.tfw/templates/`	Canonical templates (HL, TS, RF, ONB, REVIEW)
`.tfw/workflows/`	Process workflows (plan, handoff, resume, release, update)
`.tfw/adapters/`	Tool adapter templates
`.tfw/init.md`	Setup instructions
`.tfw/PROJECT_CONFIG.yaml`	Project parameters
`.tfw/VERSION`	Current framework version (semver)
`.tfw/CHANGELOG.md`	Version history

Tool Adapters

TFW works with any development tool. Templates in .tfw/adapters/:

Tool	Adapter	Project entry point
Claude Code	`.tfw/adapters/claude-code/`	`CLAUDE.md` (project root)
Cursor	`.tfw/adapters/cursor/`	`.cursor/rules/tfw.mdc`
Antigravity	`.tfw/adapters/antigravity/`	`.agent/rules/tfw.md`
Plain chat	—	Read `.tfw/README.md` directly

Setup details in .tfw/init.md.

Key Concepts

Task lifecycle: ⬜ TODO → 📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT → 🟠 ONB → 🟢 RF → 🔍 REV → ✅ DONE (RES optional) — details
Execution modes: CL (Chat Loop, default) / AG (Autonomous) — details
Scope budgets: configurable per phase — see tfw.scope_budgets in PROJECT_CONFIG — details
Conduct: no sycophancy, no placeholders — full rules
Versioning: semver in .tfw/VERSION, changelog in .tfw/CHANGELOG.md — details
Current version: see .tfw/VERSION — changelog · evolution

Task Board

ID	Task	Status	HL	TS	ONB	RF	REV
TFW-1	Formalize success criteria	✅ DONE	—	✅	—	✅	—
TFW-2	Upgrade to TFW v3	✅ DONE	—	✅	—	✅	—
TFW-3	Root README public-readiness	🟢 RF	✅	✅	—	✅
TFW-4	Framework cleanup	🟡 TS	✅	✅
TFW-5	KNOWLEDGE.md + tfw-docs workflow	✅ DONE	✅	✅	—	✅	✅
TFW-6	Versioning, changelog, tfw-update workflow	✅ DONE	✅	✅	A B C	A B C	A B C
TFW-7	Resolve all open tech debt	✅ DONE	✅	✅	✅	✅	✅
TFW-8	Reviewer role + /tfw-review workflow	✅ DONE	✅	✅	✅	A B	A B
TFW-9	Update source mechanism for tfw-update	✅ DONE	✅	✅	✅	✅	✅
TFW-10	Replace stale “TFW v3” labels with semver	✅ DONE	✅	✅	✅	✅	✅
TFW-11	RESEARCH stage in pipeline	✅ DONE	✅	✅	✅	A B C	A B C
TFW-12	Centralize config params in PROJECT_CONFIG	✅ DONE	✅	✅	✅	✅	✅
TFW-13	tfw-init workflow (replace init.md)	✅ DONE	✅	A B	A B	A B	A B
TFW-14	Research interaction model (briefing + handoff)	✅ DONE	✅	✅	✅	✅	✅
TFW-15	Pipeline rename: separate statuses from documents (HL_DRAFT → RES → TS_DRAFT)	✅ DONE	✅	✅	✅	✅	✅
TFW-16	tfw-doctor: analyze user behavior, chats, KI, tasks — find missed workflows, knowledge gaps, hidden flows	⬜ TODO
TFW-17	Research depth + coordinator quality (skip-bias, external tools, rush-bias)	✅ DONE	✅	✅	✅	✅	✅
TFW-18	Knowledge consolidation: fact candidates, dream-like docs, mandatory gate	✅ DONE	✅ ✅	✅	✅ ✅	✅ ✅	✅ ✅
TFW-19	tfw-config: propagate PROJECT_CONFIG.yaml changes to workflows/adapters automatically	✅ DONE	✅	✅	✅	✅	✅
TFW-20	tfw-user-tune: personal preferences pipeline (.user_preferences.md lifecycle, gitignored, user-specific)	⬜ TODO
TFW-21	Compress research.md: 2397→1145 words (-52%), deduplicate, remove inline templates	✅ DONE	✅	✅	✅	✅	✅
TFW-22	Coordinator & Research enrichment: result visualization in HL, research justification, structured thinking algorithms	✅ DONE	✅	✅	✅	✅	✅
TFW-23	Templates English standardization: eliminate mixed RU/EN, pure English templates + content_language config	✅ DONE	✅	✅	✅	✅	✅
TFW-24	RES State Machine: Researcher role, subfolder state machine, resume protocol, HL Vision/Impact, Working Backwards	✅ DONE	✅	✅	A B	A B	A B	A B
TFW-25	Values & Principles consolidation: enrich README Values, prune KNOWLEDGE.md, clean knowledge/ facts	✅ DONE	✅	✅	✅	✅	✅	✅

Statuses: ⬜ TODO → 📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT → 🟠 ONB → 🟢 RF → 🔍 REV → ✅ DONE ❌ BLOCKED

This site is open source. Improve this page.