BFM-decomp/HOW_WE_WORK.md

How we work — bfm-decomp

Project

bfm-decomp. Constitution PROJECT_CONTEXT.md; roadmap GENERATION_PLAN.md; rules rules/INDEX.md; techniques cookbook/INDEX.md; ops detail docs/ops/INDEX.md.

Developer

Who: . Experience: . Domain: . Preferences: recommendations, not questions. Plain-English recaps at phase end. A notification whenever anything waits on them. Autonomy: . Notification channel: . The developer pushes; agents never do. They ratify rules at the next planner session.

• drew-working-preferences: Drew's working style on BFM-decomp — autonomous-within-phases, ultracode effort, accepts recommended options, wants WSL/tooling decisions surfaced plainly

Rhythm

autonomous Gates: plan approval (planner session) and the milestone (verified by the closer expert).

Tools

PY = /usr/bin/python3

Name	Command	Purpose
launch	PY tools/launch.py --seed-only	the pa-session's state detector; writes .run/seed.md; never typed by the developer
plan_edit	PY tools/plan_edit.py	the only writer of PHASE_PLAN.md (status, Changes, add/reopen)
status	PY tools/status.py	.run/status.json for the statusline; INBOX consume; waiting flags
task_log	PY tools/task_log.py	lint and finish a task summary (Verified: required)
research_add	PY tools/research_add.py	allocate a report id, write the index line
rules_add	PY tools/rules_add.py	add, supersede, promote, retire a rule
skill_add	PY tools/skill_add.py	turn a workflow: gotcha into .claude/skills/<name>/SKILL.md
cookbook_add	bash tools/cookbook_add.sh	add a cookbook entry and its index line
phaseend_index	PY tools/phaseend_index.py	assemble, lint and archive a PhaseEnd
genend_index	PY tools/genend_index.py	assemble and lint a GenerationEnd
commit_task	bash tools/commit_task.sh	the only commit path; explicit paths, no trailers, never pushes
run	bash tools/run.sh	any command that may print >40 lines; --bg / --wait for long compute
Every script under tools/ (plus the two report make-targets), grouped by purpose — one line each. Deep HOW-TO is **not	Every script under tools/ (plus the two report make-targets), grouped by purpose — one line each. Deep HOW-TO is **not	Every script under tools/ (plus the two report make-targets), grouped by purpose — one line each. Deep HOW-TO is **not

Skills

• —

Paths

• Oracles (the ground truth X3 names):
• Data: docs/decision-log.md
• Generated (never hand-edited, H1):
• Hand-edited:
• Scratch: .run/ (gitignored; never the system temp)

Build / run / test

• Build: make
• Run: <!-- TODO RUN_COMMAND: no source found -->
• Test / the gate: make test — green means
• Modes: Long gates go through tools/run.sh with a raised timeout, never a poll loop.

Conventions & house style

• • Document disabled logic. When disabling or commenting out any logic based on evidence, leave a structured comment:

Environment

• OS / shells: Linux / bash
• Python: /usr/bin/python3 (3.12.3)
• Pins: — detail in docs/ops/INDEX.md
• Harness gotchas that bite here:

Docs map

• docs/ops/INDEX.md — setup, env, pins, per-topic ops notes
• cookbook/INDEX.md — techniques, grep by tag
• rules/INDEX.md — full rule texts
• phase-ends/TASK_INDEX.md, phase-ends/RESEARCH_INDEX.md — what was done and what was learned
• docs/research-archive/ — migrated legacy reports
• docs/retired/ — everything moved out of the load order