hydraflow CLAUDE.md

CLAUDE.md

HydraFlow — Intent in. Software out. A multi-agent orchestration system that automates the full GitHub issue lifecycle via git issues and labels.

This file is a table of contents. Operational knowledge lives in the wiki at docs/wiki/; architectural decisions live at docs/adr/. Look up the relevant entry — do not try to hold all of it in context.

Quick rules (always apply)

• Never commit to main. The branch is protected; all changes go through a worktree branch and a pull request. No exceptions, not even for one-line fixes. Look up "Worktree" in docs/wiki/gotchas.md. Create worktrees with scripts/hf_worktree.sh <name> <branch> (or make worktree DIR=<name> BRANCH=<branch>) — never a bare git worktree add. A bare <name> is created under the agent worktree root (HYDRAFLOW_AGENT_WORKTREE_ROOT, default <repo>/.claude/worktrees) so WorkspaceGCLoop can reap it; a value containing / is honoured verbatim. The script echoes the resolved absolute path as its final stdout line — cd to that, not to the name you passed: wt="$(scripts/hf_worktree.sh mywork my/branch | tail -1)" && cd "$wt". Before #11729 the creator took <dir> verbatim while the collector swept a hardcoded list, and 47 of 100 worktrees (37 GB) were unreachable. Reason for the helper: when the directory already exists, add fails but a chained cd/merge still runs against the stale branch (#11501).
• PRs target staging, not main (per ADR-0042, active when HYDRAFLOW_STAGING_ENABLED=true). main only advances via auto-promoted rc/YYYY-MM-DD-HHMM PRs cut by StagingPromotionLoop every rc_cadence_hours (default 4h). Default for new PRs: gh pr create --base staging. Only RC promotion PRs use --base main. Check the active default: python -c "from config import HydraFlowConfig; print(HydraFlowConfig().base_branch())".
• Never use git commit --no-verify or --no-hooks. Fix code issues first.
• Always run make quality before declaring work complete. Look up "Quality" in docs/wiki/patterns.md.
• Always write unit tests before committing. See docs/wiki/testing.md.
• Load-bearing features ship the full test pyramid: unit + MockWorld scenario + sandbox e2e. Skipping a layer is a procedural failure, not a judgment call — see docs/standards/testing/README.md. Unit tests are blind to real-API behavior; MockWorld scenarios catch loop integration; sandbox e2e catches docker/UI/wiring. Don't ship a feature where any layer is "too small to need it."
• Always read docs/wiki/gotchas.md before editing Pydantic models, test imports, or mocks — recurring mistakes live there.
• Look at the System Map before exploring code blind. The Functional Area Map shows what every loop and Port belongs to; click through to ADRs from there.
• Always verify subagent DONE claims with git status --porcelain and git log -1 --stat. Subagents sometimes report DONE with edits applied but not committed.
• Always verify branch identity after creating a worktree — run git rev-parse --abbrev-ref HEAD inside it before editing or merging. Same class as verifying subagent DONE claims: never trust that a step did what it said. A reused worktree directory name silently lands you on the wrong branch (#11501).
• Subprocess-spawning runners MUST call reraise_on_credit_or_bug(exc) in their broad except block. Without it, CreditExhaustedError is silently eaten and the loop burns attempt budget against an exhausted billing signal. See docs/wiki/dark-factory.md §2.2.
• For substantial features, plan for 2–3 fresh-eyes review iterations before merge. Convergence = next pass finds nothing material. See docs/wiki/dark-factory.md §3.
• Run a code review after every PR you create, not only substantial features. Standard workflow: build → quality → PR → review → merge. After gh pr create, run a fresh-eyes pass (feature-dev:code-reviewer, code-quality-enforcer, or the /code-review skill) on the branch diff and fix findings before enabling auto-merge. /code-review ultra is user-triggered and billed — use an inline review agent instead. See docs/wiki/memory-feedback/feedback-code-review-after-each-pr.md.
• Act on tractable + reversible fixes; ask only on high-blast-radius work. Running make arch-regen and pushing on a stale-artifacts CI fail, retargeting a PR's base branch when a ruleset change broke the merge target, adding Skip-ADR: for implementation-level touchpoints, filing hydraflow-find issues for recurring patterns — these are factory work, not permission gates. Bottlenecking on the human is the bottleneck the factory exists to remove. Force-push to main, deletion, data drops, repo permissions still need explicit consent. Full directive + classification table in docs/standards/factory_autonomy/README.md.
• Code-cleanup PRs (defensive-guard removal, dead-code drops) MUST be verified with full make quality, not file-targeted test subsets. PR #8460 over-pruned getattr(self, "_X", None) checks where _X was set conditionally in subclasses or __new__-bypassed test scaffolding; the implementer ran 211 tests in three targeted files (all green) and shipped — but tests/test_audit_prompts.py and tests/test_repo_wiki_loop_pr.py had 7 failures the subset missed. Hotfix PR #8463 followed. Cleanup work has higher blast radius than its diff suggests.
• A finding whose needle is a pattern (regex/AST shape recurring at multiple sites) sweeps all sites and files ONE class issue, folding later siblings into it — never one issue per site. Run python scripts/find_class_check.py --check --source ... --needle ... --title ... before filing (see .claude/commands/hf.issue.md Phase 3); the matching engine is src/find_class_key.py. Board-growth analysis found three defect families each spawning 3-4 sibling issues for one class (#11292) before this existed.