trace-first-starter

TS — TFW-12: Config Centralization

Date: 2026-03-30 Author: Coordinator (AI) Status: 🟡 TS — waiting for approval Parent HL: HL-TFW-12 RES: RES-TFW-12

---

1. Goal

Centralize 4 categories of duplicated parameters into PROJECT_CONFIG.yaml as single source of truth:

• Scope budgets (4 values × 6 files)
• Version strings (~17 places)
• Template list (6+ places, already drifted)
• Workflow list (5 places, already drifted)

2. PROJECT_CONFIG.yaml Target State

tfw:
  version: "0.5.0"
  upstream: "https://github.com/saubakirov/trace-first-starter"
  task_prefix: TFW
  id_format: "{prefix}-{seq}"
  initial_seq: 12

  scope_budgets:
    max_files_per_phase: 7
    max_new_files: 4
    max_loc: 600
    max_modified_files: 6

  templates:
    hl: .tfw/templates/HL.md
    ts: .tfw/templates/TS.md
    res: .tfw/templates/RES.md
    rf: .tfw/templates/RF.md
    onb: .tfw/templates/ONB.md
    review: .tfw/templates/REVIEW.md
    knowledge: .tfw/templates/KNOWLEDGE.md
    release: .tfw/templates/RELEASE.md

  workflows:
    plan: .tfw/workflows/plan.md
    research: .tfw/workflows/research.md
    handoff: .tfw/workflows/handoff.md
    review: .tfw/workflows/review.md
    resume: .tfw/workflows/resume.md
    docs: .tfw/workflows/docs.md
    release: .tfw/workflows/release.md
    update: .tfw/workflows/update.md

  research:
    max_web_queries_per_stage: 5
    max_files_per_stage: 15
    max_questions_per_stage: 3
    max_passes: 3

3. Reference Patterns

Pattern A: “Values + pointer” (conventions.md, plan.md, .tfw/README.md)

Readable table with values marked as defaults, header links to config.

> Scope budgets are configured in `.tfw/PROJECT_CONFIG.yaml` (`tfw.scope_budgets`).
> Values below are defaults.

| Parameter | Default | Rationale |
|-----------|---------|-----------|
| Files per phase | 7 | Agent maintains full mental model |

Pattern B: “Pure reference” (TS.md template, glossary.md)

Subject to scope budgets (see `tfw.scope_budgets` in `.tfw/PROJECT_CONFIG.yaml`).

Pattern C: “Version placeholder” (adapter templates)

# TFW {version}

Resolved by init.md setup or tfw-update adapter refresh.

Pattern D: “Version removed from titles” (core .tfw/ files)

# TFW Conventions       ← was: # TFW 0.4 — Conventions
# TFW Glossary          ← was: # TFW 0.4 Glossary

4. Scope

Phase A: Config + Core Docs (0 new, 7 modified)

#	File	Changes
1	.tfw/PROJECT_CONFIG.yaml	Add scope_budgets, complete templates (+res/knowledge/release), add workflows, add research
2	.tfw/conventions.md	§6: Pattern A budgets. L1: remove version from title (Pattern D). Fix workflow table if needed
3	.tfw/README.md	Scope Budgets section: Pattern A. Body: remove TFW 0.5 from prose. Tree comments: reference config for lists
4	.tfw/workflows/plan.md	§Scope Budget: Pattern A
5	.tfw/glossary.md	L1: remove version (Pattern D). L69: Pattern B for budget values
6	.tfw/templates/TS.md	L27: Pattern B for budget values
7	README.md (root)	Budget reference → “see PROJECT_CONFIG”. Version → “see .tfw/VERSION”

Budget: 0 new, 7 modified ✅

Phase B: Adapters + Init + Local Copies (0 new, 8 modified)

#	File	Changes
8	.tfw/adapters/claude-code/CLAUDE.md.template	TFW 0.5 → TFW {version}. Template/workflow lists → reference config
9	.tfw/adapters/cursor/tfw.mdc.template	TFW 0.5 → TFW {version}. Lists → reference config
10	.tfw/adapters/antigravity/tfw-rules.md.template	TFW 0.5 → TFW {version}. Lists → reference config
11	.tfw/adapters/antigravity/README.md	Fix stale TFW 0.4 reference
12	.tfw/init.md	Remove version from title. Add {version} replacement instruction. Update config example with full structure. Update template/workflow copy commands
13	CLAUDE.md	TFW 0.5 → value from VERSION. Lists → reference config
14	.agent/rules/tfw.md	Templates +RES. Version reference (TD-26)
15	.tfw/workflows/research.md	Verify L122 research: reference is accurate (now config exists)

Budget: 0 new, 8 modified (exceeds ≤6 by 2 — all single-line mechanical edits in adapters, justified)

5. Steps

Phase A

1. Edit PROJECT_CONFIG.yaml — add all 4 sections per §2
2. Edit conventions.md — remove version from title, Pattern A for budgets §6
3. Edit .tfw/README.md — remove version from prose, Pattern A for budget section, update tree comments
4. Edit plan.md — Pattern A for scope budget table
5. Edit glossary.md — remove version from title, Pattern B for inline budgets
6. Edit TS.md template — Pattern B for budget line
7. Edit root README.md — reference config for budgets, reference VERSION for version
8. Verify: grep for hardcoded budget values and version strings in Phase A files

Phase B

1. Edit 3 adapter templates — Pattern C for version, reference config for lists
2. Edit antigravity README — fix stale 0.4
3. Edit init.md — full config example, {version} instructions, update copy commands
4. Edit CLAUDE.md — version from VERSION, lists from config
5. Edit .agent/rules/tfw.md — fix TD-26
6. Verify research.md L122 reference
7. Verify: grep for remaining hardcoded values across all files
8. Resolve TD-25, TD-26 in TECH_DEBT.md

6. Acceptance Criteria

Phase A

• AC-1: tfw.scope_budgets exists in PROJECT_CONFIG with 4 keys
• AC-2: tfw.templates has 8 entries (hl, ts, res, rf, onb, review, knowledge, release)
• AC-3: tfw.workflows has 8 entries (plan, research, handoff, review, resume, docs, release, update)
• AC-4: tfw.research has 4 limit entries
• AC-5: conventions.md §6 has “configured in PROJECT_CONFIG” header + defaults table
• AC-6: plan.md scope budget section references config
• AC-7: grep "≤ 7" .tfw/conventions.md .tfw/README.md .tfw/workflows/plan.md → 0 matches (values without ≤ symbol)
• AC-8: grep "TFW 0\." .tfw/conventions.md .tfw/glossary.md → 0 matches (no version in titles)

Phase B

• AC-9: All 3 adapter templates use {version} not hardcoded version
• AC-10: CLAUDE.md references VERSION file for version
• AC-11: init.md config example shows all 4 sections (scope_budgets, templates, workflows, research)
• AC-12: grep "TFW 0\." .tfw/adapters/ CLAUDE.md .agent/rules/ → 0 matches
• AC-13: TD-25, TD-26 marked ✅ in TECH_DEBT.md

7. Verification

# Phase A
grep "scope_budgets" .tfw/PROJECT_CONFIG.yaml
grep -c "templates:" .tfw/PROJECT_CONFIG.yaml  # sections exist
grep -c "workflows:" .tfw/PROJECT_CONFIG.yaml

# No hardcoded budget values with ≤ prefix
grep "≤ 7\|≤ 4\|≤ 600\|≤ 6" .tfw/conventions.md .tfw/README.md .tfw/workflows/plan.md .tfw/glossary.md .tfw/templates/TS.md README.md || echo "PASS"

# No version in core titles
grep "TFW 0\." .tfw/conventions.md .tfw/glossary.md || echo "PASS"

# Phase B
grep "{version}" .tfw/adapters/*/tfw*.template .tfw/adapters/claude-code/CLAUDE.md.template
grep "TFW 0\." .tfw/adapters/ CLAUDE.md .agent/rules/tfw.md 2>/dev/null || echo "PASS"
grep "research:" .tfw/PROJECT_CONFIG.yaml

8. Out of Scope

• Status pipeline diagrams (8 copies — accepted as documentation)
• Research limits in research.md body (L115, L144 — same file, local)
• .agent/workflows/ copies of plan.md, research.md, handoff.md — these are synced from canonical, will get updated on next tfw-update
• Historical task artifacts
• KNOWLEDGE.md updates — via /tfw-docs after REVIEW

---

*TS — TFW-12: Config Centralization

2026-03-30*

This site is open source. Improve this page.