"The thinking is the product. Everything else is output."
Imagine a product that knows more about itself than just its code — its purpose, its decisions, its rejected alternatives, its technical debt.
Most products can't explain themselves. The reasoning lives in expired chats, in someone's head, in meetings nobody documented. A new team member or a new AI session starts from zero.
Now imagine that every task — code, research, analysis, business process — automatically captures this knowledge as a byproduct of working.
That's TFW. A team methodology where traces replace documentation. Every decision is traceable. Any team member — human or AI — reads the traces and resumes from the last checkpoint. Knowledge compounds across tasks instead of evaporating between sessions.
Because knowledge is power.
For the full philosophy, thesis, and design rationale → .tfw/README.md
Teams and individuals who can't afford to lose context. TFW works for code, analytics, writing, education, and business processes — the same lifecycle, the same artifacts, the same knowledge compounding.
|
Your decisions don't propagate. Strategy discussed in one session doesn't reach the person implementing it. When team members change, institutional knowledge walks out the door. TFW makes every decision traceable — who made it, why, what was rejected. Any team member reads the traces and picks up where the previous one left off. |
|
Your previous analysis isn't discoverable. Research iterations lose context. Reports don't reference the decisions that drove them. TFW preserves every research iteration with structured findings, hypotheses tested, and decisions made. Knowledge compounds instead of resetting. |
|
"Why was this built this way?" Nobody knows. The person who decided left. The chat session expired. The reasoning died with the context window. TFW captures architecture decisions, rejected alternatives, and constraints alongside the code. A new developer reads the traces, not just the codebase. |
For humans: read the philosophy — 5 minutes that explain why TFW works. Everything else is handled by your AI agent.
Copy this into your AI agent (Claude Code, Cursor, or any chat):
I want to start a new project using Trace-First Workflow (TFW) —
a methodology that preserves decisions, reasoning, and knowledge across AI sessions.
Clone https://github.com/saubakirov/trace-first-starter to a temp directory,
then read .tfw/quickstart.md and follow it step by step.
My project is about: <describe your project in a few sentences>
I want to add Trace-First Workflow (TFW) to this existing project.
Clone https://github.com/saubakirov/trace-first-starter to a temp directory,
copy the .tfw/ directory into my project root, then delete the temp clone.
Then read .tfw/quickstart.md and follow it step by step.
My project is about: <describe your project>
Read AGENTS.md for project context.
This project uses TFW slash commands for all workflows:
/tfw-plan — create a new task
/tfw-handoff — execute an approved task
/tfw-review — review completed work
/tfw-resume — continue interrupted work
Start with: /tfw-plan
Task: <describe what you want to do>
Do I need to read the documentation?
No. The .tfw/ files are designed for AI agents. You only need the philosophy.
Which AI tools work with TFW? Any tool that can read files. Adapters exist for Claude Code, Cursor, and Antigravity — your agent sets them up during init.
Can I use TFW for non-code work? Yes — analytics, writing, education, business processes. TFW is about structuring decisions, not about code.
How is TFW different from Confluence/Notion? Confluence and Notion are knowledge storage tools — they hold what someone decides to write. TFW is a knowledge generation methodology — it captures decisions, reasoning, and alternatives as a byproduct of working. You don't document your decisions; your decisions document themselves.
Is TFW only for software engineering? No. TFW is a methodology for structuring decisions and preserving knowledge. The same lifecycle works for product management, data analytics, academic research, content creation, and business operations.
Where can I learn more visually? Try the interactive FAQ — ask any question about TFW and get answers grounded in the actual documentation. There are also onboarding slides and a video overview for a quick visual introduction.
| Principle | What it means | |
|---|---|---|
| 🧠 | Self-aware product | TFW captures intent, decisions, constraints, and rejected alternatives — not just code. The project explains itself |
| 🔄 | Resume from any checkpoint | When a chat ends, context doesn't die. The next agent reads the Task Board and picks up exactly where the previous one left off |
| 📈 | Knowledge compounds | Unlike Confluence/Notion, TFW captures knowledge as a byproduct of work. No manual documentation to maintain |
| 🤖 | AI agents are team members | Your AI assistants read the same traces your humans read, follow the same lifecycle, contribute to the same knowledge base |
| 🌐 | One ritual, any domain | Code, analytics, writing, education, business processes — same lifecycle, same artifacts |
| 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) |
| 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/quickstart.md |
Quick start for AI agents |
.tfw/project_config.yaml |
Project parameters |
.tfw/VERSION |
Current framework version (semver) |
.tfw/CHANGELOG.md |
Version history |
| tfw.saubakirov.kz | Documentation site (auto-generated from artifacts) |
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/quickstart.md.
⬜ TODO → 📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT → 🟠 ONB → 🟢 RF → 🔍 REV → 📚 KNW → ✅ DONE
| Concept | Summary | Reference |
|---|---|---|
| Task lifecycle | 9 statuses, RES and KNW optional | philosophy |
| Execution modes | CL (Chat Loop, default) / AG (Autonomous) | philosophy |
| Scope budgets | Configurable per phase | project_config.yaml |
| Conduct | No sycophancy, no placeholders | conventions |
| Versioning | Semver in .tfw/VERSION |
changelog |
TFW uses semantic versioning. Check your installed version in .tfw/VERSION.
To update to a new version, ask your AI agent:
/tfw-update
The agent will fetch the latest .tfw/ from upstream, compare versions, categorize changes (🟢 safe / 🟡 merge / 🔴 breaking), and apply them while preserving your project customizations.
Full process → .tfw/workflows/update.md · Version history → CHANGELOG
| 🤖 Interactive FAQ | NotebookLM — ask questions about TFW |
| 🎓 Onboarding Slides | NotebookLM |
| 🎬 Video Overview | NotebookLM |
| 📖 Getting Started | .tfw/quickstart.md |
| 💡 Philosophy | .tfw/README.md |
| 🌐 Docs site | tfw.saubakirov.kz |
| 🔗 Repository | github.com/saubakirov/trace-first-starter |
| 👤 Author | saubakirov.kz |
| ⚖️ License | MIT |
| 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: self-diagnosis of TFW meta-state — verify knowledge_state.yaml matches project, detect stale refs after update, analyze user behavior, find missed workflows, knowledge gaps | ⬜ 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 |
| TFW-25 | Values & Principles consolidation: enrich README Values, prune KNOWLEDGE.md, clean knowledge/ facts | ✅ DONE | ✅ | ✅ | ✅ | ✅ | ✅ |
| TFW-26 | Documentation as Output: compilable contract, MkDocs gen-files, docs site from TFW artifacts | ✅ DONE | ✅ | ✅ | FC A B | FC A B | FC A B |
| TFW-27 | Wiki polish & brand: logo, brand identity, link resolution, landing page, deploy to GitHub Pages | ✅ DONE | ✅ | A✅ B✅ C✅ | A✅ B✅ C✅ | A✅ B✅ C✅ | A✅ B✅ C✅ |
| — | |||||||
| TFW-29 | Consistency audit: glossary, conventions, workflows — redundancy, compression, reading flows | ✅ DONE | ✅ | ✅ | ✅ | ✅ | ✅ |
| TFW-30 | Antigravity adapter audit: thin adapters, Skills, Planning Mode strategy | 📝 HL_DRAFT | 📝 | ||||
| TFW-31 | Quick Start agent-first rewrite: quickstart.md, starter prompts, init.md domain-agnostic | ✅ DONE | ✅ | ✅ | ✅ | ✅ | ✅ |
| TFW-32 | Methodology refinement & product positioning: docs/knowledge fix, KNW status, terminology, multi-iter research, audience personas | ✅ DONE | ✅ | A B C D | A B C D | A B C D | A B C D |
| TFW-33 | Thinking traces as first-class TFW artifacts (capture AI <think> blocks as project knowledge) |
⬜ TODO | |||||
| TFW-34 | Knowledge pipeline automation: plugin-based fact capture, handoff manifest (task_state.yaml) | ⬜ TODO | |||||
| TFW-35 | Analytical review template: lighter checklist for non-code phases (positioning, specs, documentation) | ⬜ TODO | |||||
| TFW-36 | Content marketing blog series: 7 Medium posts targeting different audiences via SEO, problem-first with real cases | 📚 KNW (A) | 📝 | 🔬 | 🟡 | 🟠 | 🔍 |
| — | |||||||
| TFW-38 | Quality enforcement: staged review (Map→Verify→Judge→Decide), handoff §6-8 mandate, knowledge citation table | ✅ DONE | ✅ | ✅ | A✅ A.2✅ B✅ | A🟠 A.2🟠 B🟠 | A🟢 A.2🟢 B🟢 |
| TFW-39 | Visual Knowledge System: process/architecture diagram registry with naming convention, mandatory creation criteria, staleness tracking, domain index. Born from TFW-38 Phase B redesign | ⬜ TODO | |||||
| TFW-40 | State/framework separation: knowledge_state.yaml contamination fix, project_config template, naming normalization | ✅ DONE | ✅ | A B | A B | A B | |
| TFW-41 | Execution quality gates: Requirements-first TS, Execution Loops, Pre-TS/Pre-RF gates, principles enforcement, embedded dimensional analysis | ✅ DONE | ✅ | 1 2 | A🟡 B🟡 C🟡 D🟡 | A🟠 B🟠 C🟠 D🟠 | A🟢 B🟢 C🟢 D🟢 |
| TFW-42 | Research cycle restructure: unified research/ container, numbered stages, kebab-case phases, iterations.yaml enrichment, multi-agent support | ✅ DONE | ✅ | 1 2 | A🟡 B🟡 C🟡 | A🟠 B🟠 C🟠 | A🟢 B🟢 C🟢 |
| TFW-43 | Research stage protocol: copy-on-enter, per-stage mindset blocks, STOP gates between stages | ✅ DONE | ✅ | 1 | 🟡 | 🟠 | 🟢 |
Statuses: ⬜ TODO → 📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT → 🟠 ONB → 🟢 RF → 🔍 REV → 📚 KNW → ✅ DONE | ❌ BLOCKED