Skip to content

TFW Conventions

1) Purpose

TFW turns work (analytics, documents, code, research) into a reproducible process: - context is captured, - decisions are traced, - results are repeatable, - any agent can continue the project in a new session.

2) Required Artifacts (project root)

3) Artifact Types (canonical)

See also: glossary.md for terminology, README.md for philosophy.

HL (High Level)

Context/frame. Not a task — a "map of meaning". Format: strictly follows .tfw/templates/HL.md.

RES (Research Report)

Structured investigation artifact. Produced via Briefing → Gather → Extract → Challenge stages in research/ subfolder. RES file = synthesis (Decisions, Hypotheses, HL Recommendations, Conclusion). Stage files = raw investigation. Created between HL and TS (pipeline) or standalone for any research. Format: strictly follows .tfw/templates/RES.md.

TS (Task Spec)

Task definition. Always self-contained: inputs/outputs/constraints/DoD. Format: strictly follows .tfw/templates/TS.md.

RF (Result File)

Results/facts/data/final text. RF has priority as source of truth. Contains mandatory Observations table (structured, typed). Format: strictly follows .tfw/templates/RF.md.

ONB (Onboarding Report)

Structured executor report before starting: understanding, questions, risks, inconsistencies. Coordinator/human answers directly in the file (Q&A format). Format: strictly follows .tfw/templates/ONB.md.

REVIEW (Review Report)

Formal coordinator report after reviewing RF: checklist, verdict, tech debt. Format: strictly follows .tfw/templates/REVIEW.md.

Fact Candidates (section in RF, REVIEW, RES)

Raw observations about the project recorded during work. Cognitive mode: pure reporting — record factual without interpretation. NOT verified facts — they become facts after /tfw-knowledge consolidation. Each artifact has a Fact Candidates section with a structured table (Category, Candidate, Source, Confidence). Quality filter: "Would the next agent decide differently knowing this?"

Visual Sections (per-template)

Decision criterion: "Does the cognitive mode CHANGE between templates?" If yes → per-template naming. If no → unified. Visual sections trigger different cognitive modes per template context (empirically validated: RES3 D22, RES4 Exp1+Exp2).

Template Section Cognitive Mode What it produces
HL §3.1 Result Visualization Narrative / Outcome Outcome preview — Working Backwards style ("imagine it's done")
HL §3.2 Value Flow Strategic / Value-oriented Value streams, INPUT→PROCESSING→OUTCOME, transformation tables
RF §8 Diagrams Technical / Engineering Architecture, ERD, sequence diagrams, component diagrams
RES Findings Map Analytical / Research Root cause analysis, hypothesis trees, priority matrices
REVIEW — — No visual section (checklist artifact, not result)

Knowledge Capture Sections (unified naming)

Section Name Templates Cognitive Mode
§6 Fact Candidates RF, RES, REVIEW Pure reporting: record without interpretation
§7/§11 Strategic Insights + qualifier HL (Planning), RF (Execution), RES (Research) Deep analytical synthesis: capture + add implications

Knowledge Input Sections (unified naming)

Section Name Templates Cognitive Mode
§7.2 Knowledge Citations HL Input tracing: cite what was read from PV Index with links
§7 Knowledge Citations ONB Input tracing: confirm read of HL §7.2 citations, add new items
(section) Knowledge Citations Verified review/verify.md Verification: check that citation links resolve to real items

Unified naming rationale (D43/D28/D39): cognitive mode is the same across all three — "report what you read and how it applies." Same mode = same name. Scan scope differs by role: Coordinator + Reviewer do full PV scan, Executor references coordinator's citations. See glossary.md → Project Values (PV).

4) Task Numbering

ID format is defined in .tfw/project_config.yaml (field tfw.task_prefix).

File naming:

Artifact Format Example
Master HL HL-{PREFIX}-{N}__{title}.md HL-PROJ-3__tfw-setup.md
Single-phase RES RES__{PREFIX}-{N}__{title}.md RES__PROJ-3__tfw-setup.md
Single-phase TS TS__{PREFIX}-{N}__{title}.md TS__PROJ-3__tfw-setup.md
Single-phase RF RF__{PREFIX}-{N}__{title}.md RF__PROJ-3__tfw-setup.md
Single-phase ONB ONB__{PREFIX}-{N}__{title}.md ONB__PROJ-3__tfw-setup.md
Single-phase REVIEW REVIEW__{PREFIX}-{N}__{title}.md REVIEW__PROJ-3__tfw-setup.md
Phase RES RES__phase-{x}__{title}.md RES__phase-a__conventions.md
Phase TS TS__phase-{x}__{title}.md TS__phase-a__conventions.md
Phase RF RF__phase-{x}__{title}.md RF__phase-a__conventions.md
Phase ONB ONB__phase-{x}__{title}.md ONB__phase-a__conventions.md
Phase REVIEW REVIEW__phase-{x}__{title}.md REVIEW__phase-a__conventions.md

Rule: ALL artifact filenames MUST include the task ID ({PREFIX}-{N}) or Phase identifier. A filename without either is an error.

Task folder: tasks/{PREFIX}-{N}__{title}/

Research subfolder

Research artifacts live in a single research/ container at task root. Each iteration gets its own numbered subfolder:

tasks/{ID}/research/
  iterations.yaml              ← control file
  iter1/
    1_briefing.md              ← numbered stage files
    2_gather.md
    3_extract.md
    4_challenge.md
    RES.md                     ← synthesis co-located with stages
  iter2/
    1_briefing.md
    2_gather.md
    3_extract.md
    4_challenge.md
    RES.md

File existence = stage completion. Stage file format: see .tfw/templates/research/ (1_briefing.md, 2_gather.md, 3_extract.md, 4_challenge.md).

Multi-iteration research

When research spans multiple iterations, each iteration gets its own subfolder and RES:

Iteration Stage files folder RES file
1 research/iter1/ research/iter1/RES.md
2 research/iter2/ research/iter2/RES.md
N research/iterN/ research/iterN/RES.md

Trace rule: Iteration folders accumulate — never delete or overwrite previous iteration's files. Each research/iterN/ folder is a trace. Deleting them = deleting reasoning.

Control file: research/iterations.yaml tracks iteration state. Created by coordinator in plan.md Step 6 before launching research. Format:

task_id: PROJ-N
title: research focus description
min_iterations: 2       # from tfw.research.min_iterations or coordinator override
max_iterations: 5       # soft ceiling
iterations:
  - number: 1
    focus: "initial investigation of H1-H3"
    hypotheses: [H1, H2, H3]
    status: complete     # pending | in_progress | complete
    res_file: research/iter1/RES.md
    # agent: antigravity           # optional — which tool/agent ran this iteration
    # sources: [external, codebase] # optional — what sources were consulted
  - number: 2
    focus: "deepen findings from iter 1, test H4"
    hypotheses: [H4]
    status: pending
    res_file: research/iter2/RES.md

The agent field records which tool or agent conducted the iteration — for traceability, not dispatch. The sources field records what source categories were consulted. Both fields are optional; simple single-agent tasks can omit them.

Coordinator updates research/iterations.yaml after each iteration (marks status, adds next iteration if needed). Researcher reads it at start to understand predecessor context and assigned hypotheses.

Review subfolder

Review stage files (review/map.md, review/verify.md, review/judge.md) — intermediate review traces written during the review process. Created in task phase directory. Parallels research stage files (research/iterN/1_briefing.md, etc.). The REVIEW artifact synthesizes these files. Stage file format: see .tfw/templates/review/ (map.md, verify.md, judge.md).

Multi-phase folder structure

For multi-phase tasks, master artifacts (HL, RES) stay at task root. Each phase gets a subfolder:

tasks/PROJ-5__query_redesign/
  HL-PROJ-5__query_redesign.md        ← Master HL
  research/                           ← Master research (if any)
  phase-a/
    HL__phase-a__data_model.md
    TS__phase-a__data_model.md
    ONB__phase-a__data_model.md
    RF__phase-a__data_model.md
    REVIEW__phase-a__data_model.md
  phase-b/
    HL__phase-b__api_layer.md
    ...

5) Task Statuses

⬜ TODO → 📝 HL_DRAFT → 🔬 RES → 🟡 TS_DRAFT → 🟠 ONB → (develop) → 🟢 RF → 🔍 REV → 📚 KNW → ✅ DONE
                                                                              │
                                                                    ┌─────────┴─────────┐
                                                                    🔄 REVISE          ❌ REJECT
                                                                 (back to dev)    (user decides)
                    (skip: 📝 HL_DRAFT ··· 🟡 TS_DRAFT)        ↓
                                                           ❌ BLOCKED
Status Meaning
⬜ TODO Task planned, HL not started
📝 HL_DRAFT HL being drafted, awaiting review/approval
🔬 RES Research in progress (optional — user can skip to TS_DRAFT)
🟡 TS_DRAFT TS written, awaiting approval for execution
🟠 ONB Onboarding: executor studying the task
🟢 RF Execution complete, RF written
🔍 REV Review: reviewer checking RF
📚 KNW Knowledge capture: tfw-docs + tfw-knowledge applied (optional — reviewer can pre-close with N/A)
✅ DONE Task closed, traces updated
❌ BLOCKED Blocked by dependency

Task Board format — ID column must be a relative link to the task folder: 

| [PROJ-1](tasks/PROJ-1__title/) | Description | Status | ... |

Review verdicts: - ✅ APPROVE — all ok → 📚 KNW (run tfw-docs + tfw-knowledge), then ✅ DONE - 🔄 REVISE — specific issues → back to execution (same task) - ❌ REJECT → 🛑 User decides: (a) 📝 HL_DRAFT (rework HL), (b) 🔬 RES (new research), (c) 🟡 TS_DRAFT (rewrite TS)

6) Scope Budgets (per Phase)

Configured in .tfw/project_config.yaml (tfw.scope_budgets). Values below are defaults. Override in project_config.yaml for your project.

Parameter Default Rationale Config key
Files per phase 14 Agent maintains full context of changed files max_files_per_phase
New files per phase 8 Limits blast radius of new abstractions max_new_files
LOC per phase 1200 Keeps changes reviewable in one pass max_loc
Modified files 12 Prevents scattered, hard-to-review diffs max_modified_files

7) Execution Modes

CL (Chat Loop) — default

  • AI proposes steps, human approves/executes.
  • AI does NOT execute external actions without approval.

AG (Autonomous) — explicit request only

  • AI works independently within approved TS scope.
  • Makes incremental commits.
  • Stops when encountering issues not covered by TS.

8) Workflows

TFW defines the following canonical workflows in .tfw/workflows/:

Workflow Role Purpose
init.md Coordinator Discover project → interview → knowledge → setup → verify
plan.md Coordinator Research → HL → RESEARCH gate → scope decision → TS
research/base.md Researcher Structured investigation → RES artifact (pipeline or standalone)
handoff.md Executor Context load → ONB → execute → RF
review.md Reviewer Read RF → checklist → verdict → tech debt → traces
resume.md Coordinator Locate task → status matrix → decide next phase
docs.md Coordinator Update KNOWLEDGE.md and TECH_DEBT.md after task completion
knowledge.md Coordinator Consolidate fact candidates into verified project knowledge (Orient → Gather → Consolidate → Prune)
release.md Coordinator Read RELEASE.md → scope release → version bump → CHANGELOG → tag
update.md Coordinator Fetch upstream → compare versions → categorize changes → update checklist → re-sync adapters
config.md Coordinator Interactive config change → propagate to all inline values

9) Tool Adapter Pattern

.tfw/ is the tool-agnostic core — one copy per project. Each development tool reads its own entry point, which references .tfw/:

CLAUDE.md ──→ "Read .tfw/README.md, follow .tfw/conventions.md"
.cursor/rules ──→ "Read .tfw/README.md, follow .tfw/conventions.md"
.agent/rules ──→ "Read .tfw/README.md, follow .tfw/conventions.md"

Adapters are chosen at project init. See .tfw/quickstart.md for setup.

10) Context Loading Order (new session, strict)

  1. AGENTS.md
  2. .tfw/conventions.md, .tfw/glossary.md
  3. KNOWLEDGE.md (if exists)
  4. Relevant HL/TS/RF for the current task

10.1) Fact Categories

Universal categories for Fact Candidates. Open list — agents can use custom categories when none fit.

Category Scope Examples
environment Where the work lives servers, tools, platforms, classrooms, labs, hosting
process How work gets done, business processes schedules, approvals, reporting cadence, grading cycles
stakeholder Who needs what priorities, pain points, expectations, quotes, key decisions
constraint What limits exist contractual obligations, regulatory deadlines, resource caps, technical limits
convention Agreed standards naming, style, format, language, tone
domain Subject matter knowledge revenue patterns, client segments, market metrics, business rules, curriculum
context Background that shapes decisions market conditions, competitive landscape, regulatory changes, prior decisions
risk Known dangers client concentration, market dependency, knowledge silos, fragile dependencies
philosophy Values, principles, vision design rationale, methodology beliefs, north star decisions, "why we do it this way"

10.2) Knowledge Infrastructure

File Purpose
knowledge/ Project root folder for topic files (per-category verified facts)
knowledge/{category}.md Topic file — verified facts for a category. Template: .tfw/templates/topic_file.md
.tfw/knowledge_state.yaml Consolidation tracking: last seq, date, statistics
.tfw/workflows/knowledge.md 4-phase consolidation workflow (Orient → Gather → Consolidate → Prune)
tfw.knowledge in project_config.yaml Configurable limits: interval, gate_mode, max_index_lines, max_facts_per_topic, max_topic_files

10.3) File Classification in .tfw/

.tfw/ contains three categories of files with different lifecycle rules:

Category Files Init Update Owner
Framework workflows/, templates/, conventions.md, glossary.md, README.md, CHANGELOG.md, VERSION, compilable_contract.md, quickstart.md, adapters/ Copy from upstream Overwrite/merge from upstream Upstream repo
State knowledge_state.yaml Create from template NEVER overwrite Project (tfw-knowledge)
Config project_config.yaml Create from template → fill project values Merge: framework sections update, project sections preserve Project + upstream

Templates for state and config files: .tfw/templates/knowledge_state.yaml, .tfw/templates/project_config.yaml.

Rule: init.md and update.md MUST respect these categories. State files are NEVER sourced from upstream — only from templates.

10.4) YAML File Naming Convention

All YAML configuration and state files in .tfw/ use lower_snake_case naming: - project_config.yaml (not PROJECT_CONFIG.yaml) - knowledge_state.yaml (not KNOWLEDGE_STATE.yaml)

Markdown templates in .tfw/templates/ also follow lower_snake_case: - topic_file.md (not TOPIC_FILE.md)

Uppercase names are reserved for project-root documents (KNOWLEDGE.md, TECH_DEBT.md, AGENTS.md) and .tfw/ framework docs (CHANGELOG.md, VERSION).

11) Quality Standard (no compromises)

  • No placeholders.
  • Results must be usable without manual edits.
  • If a result is wrong — fix the prompt/context and retry until quality is met.
  • Tasks are atomic and human-verifiable.
  • Content Language: Template structure (headings, labels, field names) is always English. Artifact content is filled in the language specified by tfw.content_language in project_config.yaml. Default: en. Agent MUST check this value before writing artifacts.

Design Rules

  • Token density: workflow instructions ≤1200 words. Templates own format; workflows reference templates
  • Inline enforcement: enforcement-critical values MUST be inline (Pattern A: defaults + config key). Pure refs (Pattern B) = broken
  • DNA/Library: Role Lock + Mindset = always inline. Reference data = via ref-inside-step. Step self-contained, ref adds precision
  • Progressive Disclosure: agent loads only what it needs now. Mode files loaded at Step 2, not at start

12) Safety and Execution Honesty

  • In CL mode, never claim something was "run" or "tested" outside the session.
  • Never request secrets in plain text. Use environment variables.

13) Trace Discipline

Every task produces an RF file with results, decisions, and observations. The Task Board in README.md tracks all task statuses. Together, these form the project's memory across sessions.

14) Anti-patterns (prohibited)

  • Executor starts coding before all blocking questions resolved
  • Executor skips reading HL and goes straight to code
  • Coordinator skips review and closes without REVIEW file
  • RF file doesn't mention test results or observations
  • TS is written without an approved HL
  • Executor modifies Master HL without coordinator approval
  • Executor makes architectural decisions not in HL
  • Executor modifies files outside TS scope (even "obvious fixes")
  • Executor does "bonus fixes" without documenting in RF deviations
  • Executor writes RF before build/lint passes
  • Executor sees tech debt / dead code but doesn't report in Observations
  • Coordinator ignores executor Observations — must triage to TECH_DEBT.md
  • Coordinator writes ONB, RF, or implements code → Role Lock violation
  • Executor writes HL, TS, or changes scope → Role Lock violation
  • Executor writes REVIEW file → Role Lock violation
  • Reviewer approves without opening any files — Step 2 (Verify) requires spot-checking RF claims against actual artifacts
  • Executor omits RF §6-8 (Fact Candidates, Strategic Insights, Diagrams) — sections are mandatory; empty content ("No X.") is valid, absent section is not
  • Researcher omits Findings Map in RES — section is mandatory; "No findings map." is valid if genuinely no visualization relevant
  • Coordinator reads KNOWLEDGE.md in context loading but never cites relevant items in HL §4 — "read but don't use" pattern breaks cross-task knowledge flow
  • TS contains ready-made implementation — TS §5 must contain acceptance criteria (WHAT), not code or steps (HOW); implementation belongs to executor
  • Coordinator reads own TS instead of RF when planning next phase — before writing TS for Phase N, read RF of the latest completed phase; plan ≠ fact
  • Executor writes RF without opening template — RF template must be opened before writing; writing from memory drifts from required structure
  • Coordinator answers ONB questions without source — when uncertain, present options and context, not decisions on behalf of the stakeholder

14.1 Terminology Origin (maintainer reference)

The following terms used in research stage templates are TFW-native and intentionally avoid methodology names:

TFW Term Meaning Origin
Dimension An independent decision factor (degree of freedom) in the problem Zwicky's GMA: "parameter"
Alternative One valid value for a Dimension Zwicky's GMA: "parameter value"
Configuration Space The full cross-product of all Dimension alternatives Zwicky's GMA: "morphological box"
Consistency Check Pairwise incompatibility analysis eliminating invalid combinations Zwicky's GMA: "cross-consistency assessment (CCA)"
Surviving Configuration A configuration that passed all pairwise checks Zwicky's GMA: "compatible solution"

Scope: This note is for framework maintainers only. The terms "Zwicky", "GMA", "General Morphological Analysis", "morphological box", and "cross-consistency assessment" MUST NOT appear in any researcher-facing template or workflow instruction.

15) Role Lock Protocol

Each workflow declares a 🔒 ROLE LOCK at the top. The agent MUST refuse any action outside the locked role.

Workflow Role Lock Permitted Artifacts Forbidden Artifacts
init.md Coordinator RES, RF, project config files HL, TS, code
plan.md Coordinator HL, TS ONB, RF, RES, REVIEW, code
research/base.md Researcher RES, research/ stage files HL, TS, ONB, RF, REVIEW, code
handoff.md Executor ONB, RF, code HL, TS, RES, REVIEW
review.md Reviewer review stage files (map.md, verify.md, judge.md), REVIEW ONB, RF, HL, TS, code
resume.md Coordinator Status matrix, Phase HL, Phase TS ONB, RF, RES, REVIEW, code
docs.md Coordinator KNOWLEDGE.md, TECH_DEBT.md code
release.md Coordinator VERSION, CHANGELOG.md code
update.md Coordinator .tfw/ files, adapter copies code
config.md Coordinator project_config.yaml, workflow files, convention files, adapter copies code

Hard Stop Rule

When a Coordinator reaches the end of planning (TS approved), the correct action is: 1. Inform the user that planning is complete 2. Instruct: "Start /tfw-handoff to begin execution" 3. Do NOT continue into execution

When an Executor finishes RF, the correct action is: 1. Inform the user that execution is complete 2. Instruct: "Start /tfw-review to review the results" 3. Do NOT write a REVIEW file

When a Researcher finishes RES, the correct action is: 1. Inform the user that research is complete 2. Instruct: "Continue with /tfw-plan to apply research findings" 3. Do NOT write HL or TS

16) Compilable Contract

Build-time specification for deterministic compilation of TFW artifacts into documentation. Defines the Source Manifest, Reference Format, and Output Structure. Full contract: compilable_contract.md