"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
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.
- Fork or clone this repository
- Follow
.tfw/init.mdto configure your project - Choose your tool adapter (Claude Code, Cursor, Antigravity, or plain chat)
- Start with
.tfw/workflows/plan.mdto create your first task
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
| 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/init.md |
Setup instructions |
.tfw/PROJECT_CONFIG.yaml |
Project parameters |
.tfw/VERSION |
Current framework version (semver) |
.tfw/CHANGELOG.md |
Version history |
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.
- Task lifecycle:
⬜ TODO → 🔵 HL → 🟡 TS → 🟠 ONB → 🟢 RF → 🔍 REV → ✅ DONE— details - Execution modes: CL (Chat Loop, default) / AG (Autonomous) — details
- Scope budgets: ≤7 files, ≤600 LOC per phase — details
- Conduct: no sycophancy, no placeholders — full rules
- Versioning: semver in
.tfw/VERSION, changelog in.tfw/CHANGELOG.md— details - Current version: 0.4.2 — changelog · evolution
- 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 | ✅ | ✅ | ✅ | ✅ | ✅ |
Statuses: ⬜ TODO → 🔵 HL → 🟡 TS → 🟠 ONB → 🟢 RF → 🔍 REV → ✅ DONE | ❌ BLOCKED