devflow: Instructions file for Claude Code

Devflow Development Guide

Instructions for developers and AI agents working on Devflow. For user docs, see README.md.

Purpose

Devflow enhances Claude Code with intelligent development workflows. Modifications must:

• Maintain brutal honesty in review outputs (no sycophancy)
• Preserve context across sessions
• Enhance developer empowerment without replacing judgment
• Ensure all commands are self-documenting

Architecture Overview

Registry-driven CLI tool with 21 plugins (12 core + 9 optional). Plugins are entries in DEVFLOW_PLUGINS in src/core/plugins.ts — each entry declares its commands, agents, skills, and rules arrays. All assets live once in src/assets/; most install directly, and .mds sources compile via npm run build:mds — command hosts to dist/commands/, agent generator hosts to dist/agents/, and reference modules in src/assets/mds/ to dist/skills/git/references/.

Invariants:

1. LLM-vs-plumbing: the LLM does all detection, matching and curation. Shell and TypeScript hold no detection or judgment logic.
2. Read and write curation data only through the curation ops. Never edit those files. Never read the old .devflow/learning/ folder as a ledger. Only move it.
3. Ledger IDs are machine-local. Committed and posted text states a decision in words, never by ID.
4. One install per machine, no install scope. DEVFLOW_DIR is ignored. init --scope local exits 1.
5. devflow never writes project.json or policy.json. The team commits them.
6. A git-tracked .devflow/config.json counts as absent, with a warning (D-PERSONAL-UNTRACKED).
7. Repo files only narrow the memory, curation and knowledge switches (D-FEATURES-NARROW-ONLY).
8. features.behavior is off unless set (D-BEHAVIOR-OPT-IN).
9. Prompts never read project.json or config.json. They take the resolve-settings.cjs line (_partials/_settings.mds).
10. Learn conventions.md only when APPLY_CONVENTIONS is true.
11. Uninstall keeps ~/.devflow/tracker/{provider}.md. It is user content.
12. The Knowledge agent commits only features/index.md and {slug}/KNOWLEDGE.md (commit --only). Never git add -A, push or force.
13. ensure-root-gitignore and ensureDevflowGitignore write the same bytes.
14. KNOWLEDGE gates write-back only. Explore and debug do not load up-front. Freshness: write-through and verify-on-read only.
15. Rules install only for selected plugins and keep paths: [] frontmatter.
16. The compliance skill and rule and the behavior rule are feature-owned. No plugin lists them.
17. Skills install for selected plugins and their requires:. Never install or delete a dormant shadow.
18. The compliance lens is the union of all layers. A branch never removes a framework; an unreadable file never lowers it (D-LENS-UNION).
19. The compliance directive goes into a spawn prompt only when the lens is on. No agent body names the compliance skill (D-COMPLIANCE-INJECT).
20. Enabled compliance, or a repo compliance key (never HEAD), makes required the evidence floor. The lens never decides evidence. With compliance off no posting step is installed; under required each command prints one local TRACEABILITY: DEGRADED line.
21. Flag --enable/--disable are boolean-only. Narrow with isEnvBooleanFlag. Never display 'unset'.
22. Disable and uninstall remove only devflow's exact value. Init adopts a user's own value as off (D-ADOPT-RESPECTS-USER).
23. TRACKER_MODEL and the memory hook fallbacks equal their shipped rows.
24. Where compliance is on, PR-comment publication is visibility-gated and fails closed to a stub (D10). project.json only caps it. required turns off into stub.
25. Where compliance is on, the test-plan comment makes no visibility probe: STUB under auto, FULL under full, none under off.
26. Every posted body passes the scrubber (D11). If it fails, post nothing and emit TRACEABILITY: DEGRADED (redaction unavailable).
27. File sinks chain the scrubber with &&. Tool-call sinks use --emit and check the byte count [DR-06].
28. Review-cycle convergence warnings never block.
29. Evidence policy comes only from the default branch's project.json (D-OFFLINE-ORIGIN-HEAD). Failures resolve required.
30. Never parse policy.json. Its presence resolves required (D-POLICY-JSON-RETIRED).
31. Operations see only ISSUE_REQUIRED, APPLY_CONVENTIONS and REQUIRE_NON_AUTHOR_APPROVAL. No prompt restates the mapping.
32. Only pr-evidence.cjs and verify-evidence.cjs assign test-plan states.
33. /code-review and /bug-analysis carry no ticket gate.
34. Every install carries every tracker provider. session-start-context Section 3 always installs and gates at runtime.
35. requires: lists used, unowned skills. The closure guard has one exception: Review's focus reference.
36. Tracker settings come from the settings line. config.json only narrows them.
37. A tracker spawn reads _contract.md once, and _mcp.md once off GitHub. A PR-host spawn reads neither.
38. Two or more qualifying servers: degraded run, no call.
39. Release evidence matches the project key, never a bare number.
40. A refusal reports TRACEABILITY: DEGRADED (<reason>). On Linear, post the back-link with the dedup warning.
41. tracker --set changes only the machine default.
42. The Tracker agent claims first, then writes its conventions file once or not at all, scrub-gated.
43. The manifest keeps the curation switch in curation and learning. Every write sets both. False wins.
44. When git tracks the curation or memory folder, or does not answer, that feature reads and writes no file there.
45. The machine switch alone picks the posting variant; a repo key never restores it, and the lens stays the run-time union. One converge, convergeVariantAxes, serves init, curation and compliance. With compliance off it fails closed unless the prompts are proved free of posting.