devflow-kit 1.8.2 → 2.0.0

package/src/assets/commands/self-review.mds

@@ -0,0 +1,156 @@
+---
+description: Self-review workflow - Simplify agent (code clarity) then Scrutinize agent (9-pillar quality gate)
+output-dir: dist/commands
+---
+@import { knowledge_load, knowledge_writeback } from "./_partials/_knowledge.mds"
+@import { decisions_load } from "./_partials/_decisions.mds"
+
+# Self-Review Command
+
+Run Simplify agent and Scrutinize agent sequentially on changed files for post-implementation quality refinement.
+
+## Usage
+
+/self-review              (auto-detect changed files from git)
+/self-review <file>...    (review specific files)
+
+## Phases
+
+### Phase 0: Context Gathering
+
+**Produces:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT, FEATURE_KNOWLEDGE
+
+Detect changed files and build context:
+
+1. If arguments provided, use those as FILES_CHANGED
+2. Else run `git diff --name-only HEAD` + `git diff --name-only --cached` to get staged + unstaged
+3. If no changes found, report "No changes to review" and exit
+4. Build TASK_DESCRIPTION from recent commit messages or branch name
+{decisions_load()}
+
+Pass `DECISIONS_CONTEXT` to Scrutinize agent — the compact index lists active ADR/PF entries; Scrutinize agent uses `devflow:apply-decisions` to Read full entry bodies on demand. Known pitfalls help identify reintroduced issues, prior decisions help validate architectural consistency. (Simplify agent does not consume decisions — it operates at code-shape level and Scrutinize agent runs after to catch any architectural drift.)
+
+{knowledge_load()}
+
+Pass `FEATURE_KNOWLEDGE` to Scrutinize agent.
+
+**Extract:** FILES_CHANGED (list), TASK_DESCRIPTION (string), DECISIONS_CONTEXT (string, optional), FEATURE_KNOWLEDGE (string, optional)
+
+### Phase 1: Simplify agent (Code Refinement)
+
+**Produces:** SIMPLIFY_COMMITS
+**Requires:** FILES_CHANGED, TASK_DESCRIPTION
+
+Spawn Simplify agent to refine code for clarity and consistency:
+
+Agent(subagent_type="Simplify", run_in_background=false):
+"TASK_DESCRIPTION: \{task_description\}
+FILES_CHANGED: \{files_changed\}
+Simplify and refine the code for clarity and consistency while preserving functionality."
+
+**Wait for completion.** Simplify agent commits changes directly.
+
+### Phase 2: Scrutinize agent (9-Pillar Quality Gate)
+
+**Produces:** SCRUTINIZE_STATUS, SCRUTINIZE_CHANGES
+**Requires:** FILES_CHANGED, TASK_DESCRIPTION, DECISIONS_CONTEXT
+
+Spawn Scrutinize agent for quality evaluation and fixing:
+
+Agent(subagent_type="Scrutinize", run_in_background=false):
+"TASK_DESCRIPTION: \{task_description\}
+FILES_CHANGED: \{files_changed\}
+DECISIONS_CONTEXT: \{decisions_context\}
+FEATURE_KNOWLEDGE: \{feature_knowledge\}
+Evaluate against 9-pillar framework. Fix P0/P1 issues. Return structured report.
+Follow devflow:apply-decisions to scan DECISIONS_CONTEXT and Read full ADR/PF bodies on demand. Skip if (none).
+Follow devflow:apply-feature-knowledge for FEATURE_KNOWLEDGE. Skip if (none)."
+
+**Wait for completion.** Extract: STATUS (PASS|FIXED|BLOCKED), changes_made (bool)
+
+### Phase 3: Conditional Validation
+
+**Produces:** VALIDATION_RESULT
+**Requires:** SCRUTINIZE_CHANGES
+
+If Scrutinize agent made changes (STATUS == FIXED):
+
+Agent(subagent_type="Validate", run_in_background=false):
+"FILES_CHANGED: \{scrutinize_modified_files\}
+VALIDATION_SCOPE: changed-only
+Run build, typecheck, lint, test on modified files"
+
+**If FAIL:** Report validation failures to user and halt
+**If PASS:** Continue to report
+
+### Phase 4: Report
+
+**Requires:** SCRUTINIZE_STATUS, VALIDATION_RESULT
+
+Display summary:
+
+## Self-Review Complete
+
+**Files Reviewed**: \{n\}
+**Status**: \{PASS|FIXED|BLOCKED\}
+
+### Simplify agent
+- \{n\} files refined for clarity
+
+### Scrutinize agent (9-Pillar Evaluation)
+| Pillar | Status |
+|--------|--------|
+| Design | \{status\} |
+| Functionality | \{status\} |
+| Security | \{status\} |
+| Complexity | \{status\} |
+| Error Handling | \{status\} |
+| Tests | \{status\} |
+| Naming | \{status\} |
+| Consistency | \{status\} |
+| Documentation | \{status\} |
+
+### Commits Created
+- \{sha\} \{message\}
+
+\{If BLOCKED: ### Blocking Issue\n\{description\}\}
+
+{knowledge_writeback()}
+
+## Architecture
+
+/self-review (orchestrator)
+│
+├─ Phase 0: Context gathering
+│  ├─ Git diff for changed files
+│  └─ Read index.md → DECISIONS_CONTEXT
+│
+├─ Phase 1: Simplify agent
+│  └─ Code refinement (commits directly)
+│
+├─ Phase 2: Scrutinize agent
+│  └─ 9-pillar quality gate (may fix and commit)
+│
+├─ Phase 3: Validate agent (conditional)
+│  └─ If Scrutinize agent made changes, verify tests pass
+│
+└─ Phase 4: Report
+   └─ Display summary with pillar status
+
+## Edge Cases
+
+| Case | Handling |
+|------|----------|
+| No changes | Report "No changes to review" and exit |
+| Simplify agent finds nothing | Normal, continue to Scrutinize agent |
+| Scrutinize agent BLOCKED | Report blocking issue, halt workflow |
+| Validation fails | Report failures, halt (don't create broken state) |
+| Not in git repo | Report error, suggest running in git repo |
+
+## Principles
+
+1. **Orchestration only** - Command spawns agents, doesn't do the work
+2. **Sequential execution** - Simplify agent must complete before Scrutinize agent
+3. **Validation gate** - If Scrutinize agent changes code, must pass validation
+4. **Honest reporting** - Display actual agent outputs
+5. **Fail fast** - Stop on BLOCKED or validation failure

package/src/assets/rules/accessibility.md

@@ -0,0 +1,11 @@
+---
+paths: ["**/*.tsx", "**/*.jsx", "**/*.css", "**/*.scss"]
+---
+# Accessibility
+
+**Every interaction must work without a mouse.**
+
+- Semantic HTML first — ARIA only when native elements won't do
+- Focus management on route changes and dynamic content
+- Color is never the only indicator — use text, icons, or patterns
+- All images need alt text; decorative images get `alt=""`

package/src/assets/rules/compliance.md

@@ -0,0 +1,15 @@
+---
+paths: []
+---
+# Compliance
+
+**No regulated data leaves a controlled path — classify, minimize, encrypt, and audit by default.**
+
+- Never write PII, PHI, payment data, or secrets to logs, error messages, or analytics events
+- State-changing operations on regulated data get an append-only audit entry: actor, timestamp, action, purpose
+- Encrypt regulated data in transit (TLS 1.2+) and at rest — no plaintext exports, dumps, or backups
+- Collect the minimum: every stored field needs a purpose, a retention period, and a deletion path
+- Least privilege and segregation of duties — no shared accounts, no self-approval of changes
+<!-- Stamped at install time: RULE_BULLETS (per-framework "Apply ..." bullets) and FRAMEWORKS (active-framework clause) below. Keep the two ${DEVFLOW_COMPLIANCE_...} placeholder lines so `devflow compliance --set` keeps the rule current. Remove them and your shadow owns those lines entirely. -->
+${DEVFLOW_COMPLIANCE_RULE_BULLETS}
+- ${DEVFLOW_COMPLIANCE_FRAMEWORKS}

package/src/assets/rules/engineering.md

@@ -0,0 +1,13 @@
+---
+paths: []
+---
+# Engineering Principles
+
+**Never throw in business logic.**
+
+- Return Result types for all fallible operations
+- Inject dependencies — constructors accept interfaces, not implementations
+- Immutable by default — return new objects, never mutate parameters
+- Parse at boundaries, trust internally — use schemas (Zod, io-ts) at entry points
+- Compose with pipes — readable, testable transformation chains
+- Explicit over implicit — no magic behaviors or hidden side effects

package/src/assets/rules/go.md

@@ -0,0 +1,12 @@
+---
+paths: ["**/*.go"]
+---
+# Go
+
+**Errors are values — never ignore them.**
+
+- Small interfaces defined at the consumer, not the producer
+- Channels for communication, mutexes for state — never both
+- No bare goroutines — always handle lifecycle and cancellation
+- Accept interfaces, return structs
+- No `**T` (pointer-to-pointer) — single indirection only; prefer value receivers

package/src/assets/rules/java.md

@@ -0,0 +1,12 @@
+---
+paths: ["**/*.java"]
+---
+# Java
+
+**Composition over inheritance — favor delegation and interfaces.**
+
+- Records for data transfer objects — immutable by default
+- Sealed classes for restricted type hierarchies
+- Optional over null — never return null from public methods
+- Streams for collection pipelines — no manual iteration for transforms
+- Pool heavy resources (connections, threads, buffers) — no allocation in hot loops

package/src/assets/rules/python.md

@@ -0,0 +1,12 @@
+---
+paths: ["**/*.py"]
+---
+# Python
+
+**Type-hint every function signature — no untyped public APIs.**
+
+- Dataclasses over raw dicts for structured data
+- Protocols for structural typing — avoid deep inheritance
+- Explicit `__all__` exports in every module
+- Context managers for resource lifecycle
+- Cap retries, pagination, and iteration — every loop needs max_iterations or itertools.islice

package/src/assets/rules/quality.md

@@ -0,0 +1,14 @@
+---
+paths: []
+---
+# Code Quality
+
+**Match existing patterns — consistency beats cleverness.**
+
+- Single responsibility: one reason to change per module
+- No regressions: every change must pass existing tests
+- Behavior-focused tests: assert outcomes, not implementation details
+- If you can't explain it in 5 minutes, it's too complex — simplify first
+- Delete dead code — commented-out code is not version control
+- Leave the end-state, not the transition — after removing or renaming, strip the residue: tombstone comments ("no longer does X"), `*_old`/`v2` names, guards for now-impossible states, leftover migration scaffolding. Git holds the history.
+- Zero warnings policy — treat all compiler and linter warnings as errors

package/src/assets/rules/react.md

@@ -0,0 +1,11 @@
+---
+paths: ["**/*.tsx", "**/*.jsx"]
+---
+# React
+
+**Composition over prop drilling — lift state only as high as needed.**
+
+- Hooks at top level, never inside conditions or loops
+- Complete useEffect dependency arrays + cleanup functions
+- Key props on list items — never use array index as key
+- Memoize expensive computations, not everything

package/src/assets/rules/reliability.md

@@ -0,0 +1,12 @@
+---
+paths: []
+---
+# Reliability
+
+**Every loop, retry, and resource has an explicit bound.**
+
+- All loops and retries must have a fixed upper bound — no unbounded while(true) or infinite pagination
+- Assert preconditions and invariants in production code — not just tests
+- Minimize allocation after initialization — prefer pools, arenas, or pre-sized collections
+- Limit indirection depth — no pointer-to-pointer, Box<Box<T>>, or triple-nested references
+- Restrict metaprogramming to simple constructs — no reflection-heavy magic, multi-level macros, or recursive generics

package/src/assets/rules/rust.md

@@ -0,0 +1,12 @@
+---
+paths: ["**/*.rs"]
+---
+# Rust
+
+**Make illegal states unrepresentable — encode invariants in types.**
+
+- Prefer borrowing over cloning — measure before you allocate
+- `?` operator for error propagation — no `.unwrap()` outside tests
+- Small, focused traits — one capability per trait
+- `#[must_use]` on functions with important return values
+- debug_assert! for invariants in hot paths — assert! at module boundaries

package/src/assets/rules/security.md

@@ -0,0 +1,12 @@
+---
+paths: []
+---
+# Security
+
+**Assume all input is malicious.**
+
+- Parameterized queries for all database access — no string concatenation
+- Escape output for its context (HTML, URL, SQL, shell)
+- No hardcoded secrets, tokens, or credentials — use environment variables
+- Validate and sanitize at every trust boundary
+- Defense in depth: never rely on a single security control

package/src/assets/rules/typescript.md

@@ -0,0 +1,12 @@
+---
+paths: ["**/*.ts", "**/*.tsx"]
+---
+# TypeScript
+
+**Type safety is non-negotiable — `unknown` over `any`, always.**
+
+- Exhaustive switch statements via `never` in default case
+- Discriminated unions for state machines and variants
+- Branded types for domain identifiers (UserId, OrderId)
+- Strict mode always — no escape hatches
+- Cap retries and pagination — every while loop and recursive fetch needs a maxAttempts guard

package/src/assets/rules/ui-design.md

@@ -0,0 +1,11 @@
+---
+paths: ["**/*.tsx", "**/*.jsx", "**/*.css", "**/*.scss"]
+---
+# UI Design
+
+**Every aesthetic choice must have intent — no decoration without purpose.**
+
+- Design tokens over magic numbers — spacing, color, typography from system
+- 4.5:1 minimum contrast ratio for text (WCAG AA)
+- 8px grid for spacing consistency
+- Mobile-first responsive: start small, enhance upward

package/src/assets/scripts/hooks/assets/orchestrator-charter.md

@@ -0,0 +1,21 @@
+<!-- Maintenance: model-tier names (haiku/sonnet/opus) and the plan-handoff prefix
+`Implement the following plan:` are cross-referenced with src/assets/scripts/hooks/preamble.
+Update both together if Claude Code changes the handoff format or model names shift. -->
+--- ORCHESTRATOR CHARTER ---
+You are the orchestrator of this session: you coordinate, agents produce.
+
+Never do work-product mainline: no file edits, no builds, no multi-file reads, no codebase orientation, no debug loops. Delegate all of it.
+
+Routing (Agent tool, model-tiered):
+- haiku — mechanical, no-thinking runs: renames, moves, boilerplate, single-command executions, bulk file listing (Explore or general-purpose agents).
+- sonnet — defined execution against a spec: Code agent (write code to a plan; also fixes pre-classified review issues in issue-fix mode), Skim agent (codebase orientation).
+- opus — analysis, design, research: Design agent, Research agent, Review agent, Triage agent (validate review issues against blast-radius matrix), open-ended investigation.
+- Real-scale work that matches a workflow: invoke the full skill instead — devflow:implement, devflow:plan, devflow:research, devflow:explore, devflow:debug, devflow:code-review, devflow:resolve.
+
+Stays mainline (judgment work): conversation, decisions, routing, synthesizing agent reports, answers already in loaded context, one targeted Read to scope a delegation.
+
+Operating rules:
+- Decompose mainline. Subagents cannot spawn subagents — you own task breakdown, then delegate leaf tasks.
+- Parallelize independent delegations in one message. Git operations stay sequential.
+- Feature knowledge (direct delegations only — workflow skills handle their own): before delegating non-trivial code work, match the task area against .devflow/features/index.md and pass matching KNOWLEDGE.md content as FEATURE_KNOWLEDGE; after delegated changes to a covered area, spawn Knowledge (sonnet) to refresh that KB.
+- Plan handoff: if the user's first message begins with `Implement the following plan:`, say so in one sentence, then immediately invoke devflow:implement via the Skill tool with the full plan. Do not pause to ask.