| D1 |
v2→v3 migration: .tfw/ as standalone core |
Tool-agnostic, forkable, no coupling to specific AI tool |
RF TFW-2 |
| D2 |
Content distribution: root README = landing, .tfw/README.md = paper |
Separation of concerns — GitHub visitors vs framework users |
RF TFW-3 |
| D3 |
Remove STEPS.md |
Replaced by RF files + Task Board. Modern tools (KI, conversation logs) handle continuity |
HL-TFW-4 §2.1 |
| D4 |
Remove TASK.md |
Scope/DoD lives in TS files, backlog in Task Board |
HL-TFW-4 |
| D5 |
Replace Summary Discipline with Trace Discipline |
RF + Task Board = project memory. No separate log needed |
HL-TFW-4 §3.1 |
| D6 |
YAML frontmatter in .tfw/workflows/ |
Antigravity requires description field for slash-command registration |
TFW-4 Phase A |
| D7 |
KNOWLEDGE.md = optional artifact |
Greenfield = overhead, brownfield = must-have |
RF TFW-5 |
| D8 |
tfw-docs triage gate |
Minor tasks skip knowledge update (1-second decision: N/A) |
HL-TFW-5 §3.2 |
| D9 |
Semver (MAJOR.MINOR.PATCH) for TFW versioning |
Industry standard, easy to communicate breaking vs compatible changes |
TFW-6 HL §3 |
| D10 |
tfw-release as canonical workflow, RELEASE.md as project context |
Separation: general process in workflow, specific context in per-project file |
TFW-6 HL §3, discussion |
| D11 |
tfw-update with 🟢🟡🔴 change categorization |
Prevents overwriting project customizations during framework upgrades |
TFW-6 HL §3 |
| D12 |
RELEASE.md optional (like KNOWLEDGE.md) |
Avoids file inflation for projects that don't release |
TFW-6 discussion |
| D13 |
Separate review from handoff — Reviewer role with 🔒 ROLE LOCK |
Executor models self-review when review is embedded in handoff; structural fix via separate workflow + role |
TFW-8 HL §2.3, §3 |
| D14 |
RESEARCH as optional pipeline gate (🔬 RES) between HL and TS |
HL→TS gap loses questions, alternatives, blind spots. RES artifact preserves investigation. Optional skip-path for trivial tasks |
TFW-11 HL §1-§3 |
| D15 |
Claude Code slash commands as thin adapters — role lock + workflow reference, no logic duplication |
Each command sets role, loads context, points to canonical .tfw/workflows/ file. Single source of truth |
TFW-11/C RF §2 Key Decision #2 |
| D16 |
Centralize scope budgets, template/workflow lists, and version to PROJECT_CONFIG.yaml |
Drift proven across TFW-5/8/9/11 — each new template/workflow caused multi-file desyncs. Single YAML source eliminates this class of tech debt |
TFW-12 RES §Gather, HL §1 |
| D17 |
~~Pattern B (pure reference) over Pattern A~~ Superseded by D24 |
~~Budget values exist ONLY in config~~ → Pattern B broke agent enforcement. Reverted to Pattern A. See D24 |
TFW-12 RF §Key Decisions #2, superseded by TFW-19 |
| D18 |
tfw-init as AI-first workflow replacing manual init.md |
Agent discovers, interviews, researches, sets up — human init.md was inverted (90% mechanical, 10% valuable) |
TFW-13 HL §2-§3 |
| D19 |
HL update = mandatory output of RESEARCH; Briefing + Closure protocols |
Research exists to refine HL, not to jump to TS. Closure writes HL recommendations; coordinator applies. Skip-bias fix: pros/cons format, user decides |
TFW-14 HL §7, RES §Closure |
| D20 |
Decouple pipeline statuses from document types: 🔵 HL→📝 HL_DRAFT, 🟡 TS→🟡 TS_DRAFT. Centralized status registry in PROJECT_CONFIG.yaml with role field. Concept Taxonomy (5 concepts). REJECT = user branching point |
Same status count (8), self-documenting _DRAFT suffix for AI agents. Implicit approval = transition to next status. Registry = single source of truth for automation |
TFW-15 HL §2, RES (Variant D) |
| D21 |
Coordinator Mindset section in plan.md + Hard Rule #8 (external tool mandate) in research.md + stage-level mindset reminders + depth self-check in checkpoints |
Root cause: plan.md framed coordination as pipeline (HL→TS→handoff), not as quality gate. Agents exhibited skip-bias, rush-bias, and internal-only research. Fix: dual-lever — mindset at coordinator level + enforcement at research stage level |
TFW-17 HL §1, §7 |
| D22 |
Knowledge consolidation: Fact Candidates in all artifacts (RF/REVIEW/RES), /tfw-knowledge 4-phase workflow (Orient→Gather→Consolidate→Prune), topic files in knowledge/, configurable Knowledge Gate in plan.md Phase 0. Settings = PROJECT_CONFIG, state = knowledge_state.yaml |
21 RF files analyzed — zero project facts recorded. Knowledge drift proven: facts lost between tasks (RES-12 R3, RF-11A). Design validated against Zettelkasten, LangMem, Claude Code Dream |
TFW-18 HL §3, RES R1-R12 |
| D23 |
Workflow compression: research.md 2397→1145 words (-52%). Remove inline templates (checkpoint/sufficiency formats) → reference templates/RES.md. Remove duplicate anti-patterns (3 blocks → 1 MUST/NEVER). Remove Example Flow (template + rules = sufficient calibration). Preserve: Mindset, stage reminders, Briefing, Closure, Hard Rules |
Agents on new projects skipped research stages — workflow too long for attention budget. External research confirmed: "principles > procedures", "templates > examples", "don’t repeat standard behavior" |
TFW-21 HL, RES (external best practices) |
| D24 |
Restore Pattern A (inline defaults + config key) for enforcement-critical values. Supersedes D17. Config Sync Registry in /tfw-config workflow maps YAML keys → file locations. Interactive edit/verify modes. No scripts — AI agent is the sync engine |
Pattern B (D17) broke agent enforcement of scope budgets — agents stopped reading indirection. RESEARCH-12 warned (R3/C1); user override proved costly. research.md Limits table (already Pattern A) = working proof. External research: inline = only enforcement for AI prompts |
TFW-19 HL §3, RES R1-R7 |
| D25 |
Research modular architecture: monolithic research.md → research/{base,focused,deep}.md. base.md = core algorithm (~500 words), mode files = settings (~100-170 words). Sum < monolith (650-800 vs 1165). YAML-configurable: tfw.research.default_mode, modes.{focused,deep} |
Monolithic file exceeded attention budget. Tiered modes prevent overhead for simple tasks. Progressive Disclosure = agent loads only needed mode. Validated by word count analysis + industry best practices (modular instruction stack) |
TFW-22 RES D2, D6, D9, D12 |
| D26 |
OODA Stage Loop in research: each stage runs Observe→Orient→Decide→Act, up to loops_per_stage (YAML hard limit). Decide = Sufficiency Verdict (2-level: generic + mode-specific criteria). Checkpoint criteria = SOFT (report, not block). Exceeded limit → force exit + report |
One-pass research = surface-level. Hard loop limit prevents stall. Soft criteria prevent blocking on unachievable conditions. ClearThought OODA + Ulysses Protocol hybrid |
TFW-22 RES D7, D8, D11, Challenge #3 |
| D27 |
Trust Protocol: 4-tier trust levels for user input. Business/domain = trust. Tech approach = verify externally. Numbers/claims = verify empirically. "I tried this" = trust outcome, verify reason |
User answers on tech = unverified hypotheses. Agent must cross-check externally, not accept at face value. Prevents confirmation bias |
TFW-22 RES D3, HL §7 |
| D28 |
Naming > Explanation: right terminology creates right associations in AI agents. Small prompt + precise terms > long prompt with explanations. Adopted terms: OODA, Sufficiency Verdict, Trust Protocol, Progressive Disclosure. Claude "dreaming" pattern = proof |
User observation: Claude Code used 1 word ("dreaming") to trigger complex memory consolidation behavior where paragraphs of explanation failed |
TFW-22 RES D4, user insight |
| D29 |
English-only templates + tfw.content_language config. Template structure (headings, labels, field names) = always English. Artifact content filled in language from tfw.content_language (default: en). D28 applied to all 32 heading terms. §3.1 rewritten domain-agnostic (not code-specific) |
Templates = code, code = English. Industry standard for AI prompt frameworks. Mixed RU/EN wasted ~1000 tokens/cycle and confused agents |
TFW-23 RES D1-D7, HL §7 |
| D30 |
Researcher = 4th standalone role (after Coordinator, Executor, Reviewer). Extracted from Coordinator following TFW-8 pattern. Own Role Lock (🔒 RESEARCHER), own permitted/forbidden artifacts. Coordinator plans → hands off → Researcher investigates → hands back |
One role + two functions = role confusion. TFW-23 crash: 6/6 gates violated. After crash recovery, "Coordinator" skipped stages and wrote HL/TS directly. Same root cause as TFW-8 (Reviewer extraction) |
TFW-24 RES D3, HL §1 |
| D31 |
Filesystem-as-state-machine: research/ subfolder with stage files (briefing.md, gather.md, extract.md, challenge.md). File existence = stage completion. Step 0 (Resume Protocol): check filesystem → resume from first missing file. No chat history dependency |
State Table in RES file = fragile (partial writes, format compliance). File existence = deterministic, zero-parsing, crash-resilient. External validation: artifact-based validation pattern |
TFW-24 RES D1, Challenge C5 |
| D32 |
RES = synthesis document (not stage aggregation). Stage sections removed from RES template — those live in research/ subfolder. RES structure (Decisions, Hypotheses, HL Recommendations, Fact Candidates, Conclusion) intentionally different from stage files to prevent copy-paste |
Mechanical aggregation = no insight. Different structure forces synthesized thinking. Researcher must re-process findings through analytical lens |
TFW-24 RES D2, HL §7 P3 |
| D33 |
HL §1 Vision: Amazon Working Backwards elements. Narrative ("write as if done") + Impact field + stakeholder-perspective Quote (press release pattern). §10 "Why Not Just...?" section (internal FAQ pattern). §2/§5 domain-agnostic |
Press release forces user/stakeholder thinking. "Why Not Just" forces alternatives before research. Domain-agnostic instructions prevent code-only bias |
TFW-24 TS Step 5, session discussion |
| D34 |
Compilable Contract (compilable_contract.md): Source Manifest (14 entries), Reference Format (9 patterns), Resolution Rules, Frontmatter Convention, Output Nav Structure. Agents write text references ([RF TFW-18](tasks/TFW-18__knowledge_consolidation/RF__PhaseB__knowledge_quality.md)), build-time script resolves to hyperlinks. .tfw/ = what (contract), docs/ = how (scripts). 445 LOC gen_docs.py, 42 tests |
Primary output = navigable knowledge graph. Agents reference, scripts resolve — no tokens wasted on markdown links. Contract isolates tool choice (MkDocs swappable). tasks/ mandatory in output (user: "excludes = destroys traceability") |
TFW-26 HL §7, RES D1-D9, Phase A/B RF |
| D35 |
TFW-27 brand identity + wiki polish + deploy: two-color discipline (charcoal #1a1a2e + teal #0d9488), tagline "The thinking is the product", business-first README, .tfw/README.md stripped to pure philosophy paper (353→138 LOC), gen_docs.py link rewriter + bare ID resolver + table anchors + literate-nav (681 LOC, 68 tests), GitHub Pages deploy at tfw.saubakirov.kz. TFW-28 absorbed |
Brand = protocol-grade, not startup-grade. README positions for business/ops first. .tfw/README.md = thesis only, no duplicated reference. Deploy = one-push CI. Closes TD-69..74, TD-77, TD-78 |
TFW-27 HL, Phase A/B/C RF |
| D36 |
Agent-first onboarding: separate learning (.tfw/quickstart.md) from execution (.tfw/workflows/init.md). quickstart.md = strict reading list (philosophy → glossary → conventions → init). README Quick Start = 3 self-contained copy-paste prompts. .tfw/init.md pointer file deleted. init.md Phase 1 rewritten domain-agnostic. Star CTA after value delivery (Phase 5) |
Bootstrap paradox: init.md assumed AGENTS.md context that doesn't exist at init time. Separation resolves chicken-and-egg. Self-contained prompts because agent doesn't see README context around the copied text |
TFW-31 RES, HL, RF |
| D37 |
docs/knowledge separation + 📚 KNW status: tfw-docs owns KNOWLEDGE.md §1-§3 (Combination: explicit→explicit). tfw-knowledge owns knowledge/*.md + §4 index (Externalization: tacit→explicit). 📚 KNW = 9th pipeline status between REV and DONE. REVIEW markers (tfw-docs: Applied/N/A, tfw-knowledge: Applied/N/A). review.md Step 7 orchestrates KNW transition. KNOWLEDGE.md §0 removed (verified: all principles in knowledge/philosophy.md) |
Root cause: tfw-knowledge Phase 4 wrote to §1/§2 of KNOWLEDGE.md — same sections as tfw-docs → collision (agent refused work). SECI model validation: Combination ≠ Externalization (Nonaka-Takeuchi). 21 RF files with zero facts = invisible knowledge step |
TFW-32 HL §2-§3, RES1 D1/D3/D6-D8, RF TFW-32/A |
| D38 |
Multi-iteration research: iterations.yaml control file, min_iterations config (default: 2), coordinator hard gate in plan.md Step 6c, researchN/ subfolder accumulation (never delete/overwrite), Iteration Status block in RES template, iter2+ briefing protocol in research/base.md |
Single-iteration research = shallow. Structural enforcement (YAML + gate) prevents premature closure. Subfolder accumulation preserves all findings. Organic Iteration Status pattern (RES3-4) formalized |
TFW-32 HL §2.5, RES1 D14, Phase C RF/TS |
| D39 |
Naming-as-Prompting + per-template visual sections: HL §3.1 Value Flow (renamed from Result Visualization), RF §8 Diagrams, RES Findings Map. Per-template criterion ("what would THIS artifact's reader draw on a whiteboard?"). Convention cross-ref table in conventions.md §6. Two visual concepts: Value Flow (before→after) and Findings Map (network of decisions) |
Naming = prompting for AI agents. Visual sections must match artifact purpose, not be uniform. Value Map rejected ("карта ценностей" ≠ Value Flow). Arc42 complexity unnecessary for methodology docs |
TFW-32 HL, RES2-4, Phase B RF/TS |
| D40 |
Product positioning: 3-tier audience hierarchy (product leaders > analysts > product-minded engineers). "Generates vs stores" differentiator vs Confluence/Notion. Team methodology frame (AI agents = team members). README rewrite with interleave opening (imagine→reality→imagine→TFW). .tfw/README.md team dimension + "How TFW Compares" section + team-centric Success Criteria |
RES1 D5/D9 + VLM-3 RES3 competitive analysis (8 unique features, Knowledge Pipeline survived sycophancy demolition). Shape Up pain-point framing, DORA translation table pattern |
TFW-32 Phase D specs + user README session |
| D41 |
4-stage review flow: Map → Verify → Judge → Decide. Each stage = separate template file in .tfw/templates/review/. Stage files = evidence trail. Mindset-based identity (Student/Auditor/Judge/Decision-maker) per stage. Self-check gate at end of each stage. Mode selection (code/docs/spec) with 🛑 WAIT gate |
Single-pass review = trust-based, no evidence. 4 stages force cognitive mode transitions (proven in research flow). Stage files = traceable, reviewable. Trust Protocol (7-row table) standardizes how to handle RF claims |
TFW-38 HL, RES iter1-4, Phase A/A.2 RF |
| D42 |
Review mode files: .tfw/workflows/review/{code,docs,spec}.md. Mode-specific checklists (2-4 items) loaded at Step 2. Progressive Disclosure — agent loads only needed mode. Universal checklist (6 items) + mode-specific = hybrid |
Code review ≠ docs review. 44% of old checklist was code-only. Mode files prevent irrelevant checks. Token density: mode files ~100 words each |
TFW-38 Phase A TS, RF |
| D43 |
Knowledge Citation Table + cascade model: Coordinator does full PV scan → HL §7.2. Executor reads HL §7.2 → ONB §7 (confirms/extends). Reviewer verifies links → verify.md (anti-hallucination gate). Unified name "Knowledge Citations" (one cognitive mode = one name per D28/D39). Not everyone scans — cascade saves tokens and prevents duplication |
Agent says "per D28" without link — could be hallucinated. Proven 4/4 times in this session: coordinator wrote specs without checking PV, user had to remind each time. Citation table with verifiable links = structural enforcement of P6 |
TFW-38 HL §7 P6, RES iter4 D14-D15, Phase B TS |
| D44 |
Project Values (PV): unified term for all accumulated project context that guides decisions. PV Index = 7 sources with scan priority (README Values → philosophy.md → KNOWLEDGE.md §1 → conventions.md → knowledge/*.md). Defined in glossary.md. Replaces ambiguous "check values/knowledge/experience" |
User says "ценности" (values) meaning values + decisions + conventions + anti-patterns + facts. 7 places, 100+ items, no unified term. PV Index = concrete scan list with priority order |
TFW-38 Phase B session discussion |
| D45 |
§7.2 placement in HL (next to Principles, not §4.1 inside Phases): citations and principles = same cognitive space ("what guides this task"). §7 ONB (standalone, not §6.1 inside Inconsistencies): citations ≠ inconsistencies. Bootstrap note for new projects: "No applicable knowledge items — project in bootstrap phase" |
§4.1 = semantically wrong (citations ≠ phase deliverables). §6.1 = semantically wrong (input knowledge ≠ output findings). Verified through PV gate during this session |
TFW-38 Phase B TS §5 Design Rationale |
| D46 |
Reviewer Identity: overall identity statement ("Quality guardian, not rubber stamp") + per-stage mindsets. Trust Protocol table (7 rows mapping claim types to verification strategies). 🛑 WAIT gate in review Step 0 (mode selection) prevents agent drift into verification before choosing mode |
Identity anchoring proven more effective than instruction volume. Trust Protocol = codified version of D27 for review context. WAIT gate prevents the most common reviewer failure: jumping straight to checklist |
TFW-38 Phase A.2, RES iter4 D21/D27/D28 |
| D47 |
State/framework separation: .tfw/templates/knowledge_state.yaml (zeroed state) + .tfw/templates/project_config.yaml (annotated # ← PROJECT/# ← FRAMEWORK). conventions.md §10.3 File Classification (Framework/State/Config). init.md creates from templates. update.md ⚫ STATE = never overwrite, 🟡 CONFIG = merge framework sections only |
init/update copied live state (seq=38, 66 facts) to new projects → contamination. Template-based instantiation = clean state for new projects, preserved state for existing. Dual identity constraint (D47 in constraint.md F6) |
TFW-40 HL, RF Phase A |
| D48 |
Naming normalization: PROJECT_CONFIG.yaml → project_config.yaml, TOPIC_FILE.md → topic_file.md. conventions.md §10.4 YAML File Naming Convention — lower_snake_case for config/state YAML, uppercase reserved for root docs (README, KNOWLEDGE) and artifact templates (HL, TS, RF). git mv for history-preserving rename. 36 files updated (28 source + 8 adapter copies) |
User: «у нас то большие буквы, то маленькие. плохо» — naming consistency = design principle (convention.md F19). One casing rule per file type, no exceptions |
TFW-40 HL, RF Phase B |
| D49 |
Requirements-first TS + execution quality gates + embedded dimensional analysis. 4-phase refactoring: (A) TS template: §4 Detailed Steps → §5 Acceptance Criteria (requirements-first with [depends: AC-X]), +§3 Principles Check, +§6 Technical Guidance, +§7 Definition of Failure, +§9 Cross-Phase Modifications. HL template: +Phase Dependencies. conventions.md: +4 anti-patterns. (B) Workflow gates: Pre-TS Gate (read RF before writing TS), Pre-RF Gate (open template before writing), Execution Loops ([depends]-triggered), ONB answer protocol, Judge §7 principles check, Session Naming Step 0. (C) Research templates: embedded dimensional analysis (Dimensions → Configuration Space → Consistency Check) via cross-stage structural dependency, no Zwicky/GMA terminology in researcher-facing text. (D) Glossary +15 terms, adapter sync |
Systemic quality drift: code-in-TS → copy-paste execution (HD-16), decorative principles without enforcement (HD-18), first-viable-option research bias. Gates > guidelines. Requirements > implementation. Verify against fact > plan. Natural enforcement > named methodology compliance |
TFW-41 HL, RES iter1-2, Phase A-D RF |
| D50 |
Research cycle restructure: unified research/ container with research/iterN/ subfolders (replaces researchN/), numbered stage files (1_briefing.md..4_challenge.md), co-located research/iterN/RES.md (replaces root-level RES__iterN__*.md), research/iterations.yaml (moved from task root) with optional agent + sources fields, kebab-case phase folders (phase-a/ replaces PhaseA/). Agent selection guidance table removed post-implementation (tautological). 3 phases: A (conventions + templates), B (workflow updates), C (glossary + adapters). Version 0.8.6 |
Production usage (AFD-2: 8 iterations, 3 agents) proved structure improvements. User feedback: alphabetical stage files confusing, researchN/ scatters artifacts. Principles: locality > scattering, sort order = execution order, container > proliferation |
TFW-42 HL, RES iter1-2, Phase A-C RF |
| D51 |
Research stage protocol: copy-on-enter + per-stage Mindset blocks (Strategist/Explorer/Analyst/Critic) + 🛑 STOP gates between stages. Templates get 3-layer verification: h1 guiding question (task orientation) / Mindset+Test blockquote (cognitive identity) / Checkpoint (task completion). Copy-on-enter restores D31 (file existence = stage completion). Mindset instruction formula: {situational framing}. {action directive}. {constraint}. Test questions: existential external with stage-output reference. Briefing gets h1 "What should we investigate?". Version 0.8.7 |
D41 review pattern (Map/Verify/Judge with per-stage identity) transferred to research. HD-28 production observation: batch copy broke D31, files appeared instantly (no observable progress). Role-nouns validated non-overlapping on 2 axes (convergent↔divergent, build↔break). H4 partially refuted: h1 and Mindset are complementary, not substitute. Test ≠ Checkpoint (identity vs task verification) |
TFW-43 HL, RES iter1, RF |