diff --git a/CLAUDE.md b/CLAUDE.md index 5dfd1af..da23594 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -50,7 +50,7 @@ Commands with Teams Variant ship as `{name}.md` (parallel subagents) and `{name} ``` devflow/ -├── shared/skills/ # 39 skills (single source of truth) +├── shared/skills/ # 37 skills (single source of truth) ├── shared/agents/ # 10 shared agents (single source of truth) ├── plugins/devflow-*/ # 17 plugins (8 core + 9 optional language/ecosystem) ├── docs/reference/ # Detailed reference documentation diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 75e8e87..0020f99 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -24,7 +24,7 @@ After setup, DevFlow commands (`/code-review`, `/implement`, etc.) are available ``` devflow/ -├── shared/skills/ # 35 skills (single source of truth) +├── shared/skills/ # 37 skills (single source of truth) ├── shared/agents/ # 10 shared agents (single source of truth) ├── plugins/devflow-*/ # 17 plugins (8 core + 9 optional) ├── scripts/hooks/ # Working Memory hooks diff --git a/README.md b/README.md index b3e4ce2..384b40f 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# DevFlow: The Most Advanced Agentic Development Toolkit for Production-Grade Code +# DevFlow [![npm version](https://img.shields.io/npm/v/devflow-kit)](https://www.npmjs.com/package/devflow-kit) [![CI](https://github.com/dean0x/devflow/actions/workflows/ci.yml/badge.svg)](https://github.com/dean0x/devflow/actions/workflows/ci.yml) @@ -6,355 +6,134 @@ [![Node.js 18+](https://img.shields.io/badge/node-18%2B-brightgreen.svg)](https://nodejs.org/) [![Website](https://img.shields.io/badge/Website-dean0x.github.io%2Fx%2Fdevflow-blue)](https://dean0x.github.io/x/devflow/) -**The most advanced toolkit for generating production-grade code with Claude Code. 18 parallel code reviewers. Working memory that never forgets. Self-learning that gets smarter every session.** -

DevFlow init demo

-## Why DevFlow - -Claude Code is powerful. DevFlow makes it extraordinary. - -**18 parallel code reviewers.** Not a linter. Not a single-pass review. DevFlow deploys up to 18 specialized reviewers simultaneously: security, architecture, performance, complexity, consistency, regression, testing, plus conditional reviewers for TypeScript, React, accessibility, Go, Python, Java, Rust, database, dependencies, and documentation. Each reviewer has domain-specific expertise. Findings include confidence scores, and false positives are tracked and penalized. - -**Working memory that never forgets.** Three shell hooks preserve session context across restarts, `/clear`, and context compaction. Zero ceremony. Your AI remembers what it was doing, what decisions were made, and what files were modified. Every session picks up exactly where the last one left off. - -**Long-term project knowledge.** Architectural decisions (ADRs) and known pitfalls persist across sessions in `.memory/knowledge/`. Reviewers automatically check if changes reintroduce known pitfalls or violate prior architectural decisions. +## The problem with AI-assisted development -**Self-learning workflows.** DevFlow watches how you work and auto-creates slash commands and skills from repeated patterns. It literally gets smarter the more you use it, detecting workflow patterns across sessions and generating reusable artifacts. +Claude Code is powerful. But every session starts from scratch. Context evaporates between conversations. Code reviews are single-pass and shallow. Quality depends entirely on what you remember to ask for. -39 quality skills. 10 shared agents. Full lifecycle from specification to PR. One `npx devflow-kit init`. +DevFlow fixes this. Install once, forget about it. Your code gets better automatically. -## Features +It watches every prompt, classifies intent, and orchestrates the right workflow — plan, implement, review, debug — loading the relevant skills. Simple questions get zero overhead. Complex tasks get an advanced TDD and EDD harness with quality gates at every step. -- **18 parallel code reviewers** with security, architecture, performance, complexity, consistency, regression, testing, plus conditional language and framework reviewers -- **Working memory** that survives restarts, `/clear`, and context compaction. Zero ceremony. -- **Self-learning** that detects repeated workflows and auto-creates slash commands and skills -- **Long-term project knowledge** with architectural decisions and known pitfalls that persist and inform reviews -- **Full-lifecycle implementation** from spec to explore to plan to code to validate to refine in one command -- **Parallel debugging** with competing hypotheses investigated simultaneously -- **39 quality skills** with 9 auto-activating core, 8 language/ecosystem, plus specialized review and orchestration skills -- **Ambient mode** that classifies intent and loads proportional skill sets automatically -- **Model strategy** with explicit model assignments — Opus for analysis agents (reviewer, scrutinizer, shepherd), Sonnet for execution agents (coder, resolver, simplifier), Haiku for I/O agents (git, synthesizer, validator) -- **Fully composable plugin system** where every feature is a plugin. Install only what you need. No bloat, no take-it-or-leave-it bundles. +## See it work -## Quick Start - -```bash -npx devflow-kit init ``` - -Then in Claude Code: +you: add rate limiting to the /api/upload endpoint + +DevFlow: Ambient: IMPLEMENT/ORCHESTRATED + → Created branch feat/42-rate-limit-upload + → Exploring codebase... Planning... Coding... + → Validator: build ✓ typecheck ✓ lint ✓ tests ✓ + → Simplifier: cleaned up 3 files + → Scrutinizer: 9-pillar quality check passed + → Shepherd: implementation matches request ✓ +``` ``` -/code-review +/code-review → 18 reviewers examine your changes in parallel +/resolve → all issues validated and fixed automatically ``` -## Commands - -| Plugin | Command | Description | -|--------|---------|-------------| -| `devflow-specify` | `/specify` | Interactive feature specification with clarification gates | -| `devflow-implement` | `/implement` | Complete task lifecycle — explore, plan, code, validate, refine | -| `devflow-code-review` | `/code-review` | Multi-perspective code review with severity classification | -| `devflow-resolve` | `/resolve` | Process review issues — fix or defer to tech debt | -| `devflow-debug` | `/debug` | Parallel hypothesis debugging | -| `devflow-self-review` | `/self-review` | Self-review workflow (Simplifier + Scrutinizer) | -| `devflow-ambient` | (hook) | Ambient mode — intent classification with agent orchestration | -| `devflow-core-skills` | (auto) | Auto-activating quality enforcement skills | - -## Command Details - -### /specify - -Guides you through defining a feature with three mandatory gates: - -1. **Understanding Gate** - Confirm the feature idea is understood -2. **Scope Gate** - Validate priorities and boundaries -3. **Acceptance Gate** - Confirm success criteria - -Creates a GitHub issue with well-defined requirements ready for `/implement`. - -### /implement - -Executes a single task through the complete development lifecycle: +## What you get -1. **Exploration** — analyze codebase for relevant patterns and dependencies -2. **Planning** — design the implementation approach -3. **Implementation** — write code on a feature branch -4. **Validation** — run build, typecheck, lint, and tests -5. **Refinement** — simplify and review for quality -6. **Alignment Check** — verify implementation matches the original request +**Ambient intelligence.** DevFlow classifies every prompt into three tiers — QUICK (zero overhead), GUIDED (skill loading + main session), ORCHESTRATED (full agent pipelines). You never invoke it manually. Init and forget. -Creates a PR when complete. +**Memory that persists.** Session context survives restarts, `/clear`, and context compaction. Your AI picks up exactly where it left off. Architectural decisions and known pitfalls accumulate in `.memory/knowledge/` and inform every future session. No manual bookkeeping. -### /code-review +**It learns how you work.** A self-learning mechanism detects repeated workflows and procedural patterns across sessions, then creates reusable slash commands and skills automatically. -Multi-perspective code review with specialized reviewers: +**18 parallel code reviewers.** Security, architecture, performance, complexity, consistency, regression, testing, and more. Each produces findings with severity, confidence scoring, and concrete fixes. Conditional reviewers activate when relevant (TypeScript for `.ts` files, database for schema changes). Every finding gets validated and resolved automatically. -- **Core**: Security, Architecture, Performance, Quality -- **Conditional** (activated when relevant): TypeScript, React, Accessibility, Go, Python, Java, Rust, Database, Dependencies, Documentation -- Findings classified as must-fix, should-fix, or nit with severity and confidence levels +**34 skills grounded in expert material.** Every skill is backed by peer-reviewed papers, canonical books, and industry standards — security (OWASP, Shostack), architecture (Parnas, Evans, Fowler), performance (Brendan Gregg), testing (Beck, Meszaros), design (Wlaschin, Hickey). 200+ sources total. -Provides actionable feedback with specific file locations and suggested fixes. +**Skill shadowing.** Override any built-in skill with your own version. Drop a file into `~/.devflow/skills/{name}/` and the installer uses yours instead of the default — same activation, your rules. -### /debug +**Full lifecycle.** `/implement` takes a task from exploration through planning, coding, validation, and refinement. `/specify` defines features with clarification gates. `/debug` investigates bugs with competing hypotheses in parallel. `/self-review` runs Simplifier + Scrutinizer quality passes. -Investigates bugs using competing hypotheses: +**Everything is composable.** 17 plugins (8 core + 9 language/ecosystem). Install only what you need. Six commands cover the entire development lifecycle. -1. **Hypothesis Generation** — identify 3-5 plausible explanations -2. **Parallel Investigation** — each hypothesis investigated independently -3. **Evidence Evaluation** — hypotheses ranked by supporting evidence -4. **Root Cause** — the best-supported explanation with fix recommendation +**HUD.** A persistent status line updates on every prompt — project, branch, diff stats, context usage, model, session duration, cost, and configuration counts at a glance. -Produces a root cause analysis report with confidence level. - -### /resolve - -Processes issues from `/code-review`: - -- Validates each issue is real (not false positive) -- Standard fixes applied directly, careful fixes (public API, shared state) get test-first treatment -- Only defers to tech debt when complete architectural overhaul is needed - -## Auto-Activating Skills - -The `devflow-core-skills` plugin provides quality enforcement skills that activate automatically: - -| Skill | Triggers When | -|-------|---------------| -| `software-design` | Implementing business logic, error handling | -| `docs-framework` | Creating documentation artifacts in .docs/ | -| `git` | Git operations, commits, PRs, GitHub API | -| `test-driven-development` | Implementing new features (RED-GREEN-REFACTOR) | -| `testing` | Writing or modifying tests | -| `boundary-validation` | Creating API endpoints | -| `search-first` | Adding utilities, helpers, or infrastructure code | - -## Language & Ecosystem Plugins - -Optional plugins for language-specific patterns. Install only what you need: - -| Plugin | Skill | Triggers When | -|--------|-------|---------------| -| `devflow-typescript` | `typescript` | Working in TypeScript codebases | -| `devflow-react` | `react` | Working with React components | -| `devflow-accessibility` | `accessibility` | Creating UI components, forms | -| `devflow-frontend-design` | `ui-design` | Working with CSS, styling | -| `devflow-go` | `go` | Working in Go codebases | -| `devflow-python` | `python` | Working in Python codebases | -| `devflow-java` | `java` | Working in Java codebases | -| `devflow-rust` | `rust` | Working in Rust codebases | - -```bash -# Install specific language plugins -npx devflow-kit init --plugin=typescript,react -npx devflow-kit init --plugin=go ``` - -## Requirements - -- [Claude Code](https://claude.ai/download) (latest) -- Node.js 18+ - -## Installation - -### Install All Plugins - -```bash -npx devflow-kit init +devflow · feat/auth-middleware* · 3↑ · v1.8.3 +5 · 12 files · +234 -56 +Current Session ████░░░░ 42% · Session 5h ██░░░░░░ 18% · 7d █░░░░░░░ 8% +Opus 4.6 [1m] · 23m · $1.24 · 2 CLAUDE.md · 4 MCPs · 8 hooks · 34 skills ``` -The interactive wizard walks through plugin selection, feature configuration (ambient mode, working memory, HUD, safe-delete), and security settings. In user scope, it discovers all projects Claude has worked on and batch-installs `.claudeignore` across them. +**Security.** Deny lists block dangerous tool patterns out of the box — configurable during init. -### Install Specific Plugins +## Quick Start ```bash -# List available plugins -npx devflow-kit list - -# Install specific plugin(s) -npx devflow-kit init --plugin=implement -npx devflow-kit init --plugin=implement,code-review +npx devflow-kit init ``` -### Scopes - -- `--scope user` (default) - Install for all projects (`~/.claude/`) -- `--scope local` - Install for current project only (`.claude/`) - -## Working Memory - -DevFlow automatically preserves session context across restarts, `/clear`, and context compaction — zero ceremony required. - -Three shell hooks run behind the scenes: - -| Hook | When | What | -|------|------|------| -| **Stop** | After each response | Updates `.memory/WORKING-MEMORY.md` with current focus, decisions, and progress. Throttled — skips if updated <2 min ago. | -| **SessionStart** | On startup, `/clear`, resume, compaction | Injects previous working memory + fresh git state as system context. Warns if memory is >1h stale. | -| **PreCompact** | Before context compaction | Backs up git state to JSON. Bootstraps a minimal working memory from git if none exists yet. | +That's it. The interactive wizard handles plugin selection, feature configuration, and security settings. Ambient mode, working memory, and self-learning are on by default. -Working memory is **per-project** — scoped to each repo's `.memory/` directory. Multiple sessions across different repos don't interfere. - -## Self-Learning - -DevFlow detects repeated workflows and procedural knowledge across your sessions and automatically creates slash commands and skills. - -A background agent runs on session end, batching every 3 sessions (5 at 15+ observations) to analyze transcripts for patterns. When a pattern is observed enough times (3 observations with 24h+ temporal spread for both types), it creates an artifact: - -- **Workflow patterns** become slash commands at `.claude/commands/self-learning/` -- **Procedural patterns** become skills at `.claude/skills/{slug}/` +## Commands -| Command | Description | +| Command | What it does | |---------|-------------| -| `devflow learn --enable` | Register the learning SessionEnd hook | -| `devflow learn --disable` | Remove the learning hook | -| `devflow learn --status` | Show learning status and observation counts | -| `devflow learn --list` | Show all observations sorted by confidence | -| `devflow learn --configure` | Interactive configuration (model, throttle, daily cap, debug) | -| `devflow learn --clear` | Reset all observations | -| `devflow learn --purge` | Remove invalid/corrupted entries from learning log | +| `/specify` | Define a feature with clarification gates → GitHub issue | +| `/implement` | Full lifecycle: explore → plan → code → validate → refine → PR | +| `/code-review` | Multi-perspective parallel code review | +| `/resolve` | Validate and fix all review issues | +| `/debug` | Competing hypothesis investigation | +| `/self-review` | Simplifier + Scrutinizer quality pass | -Observations accumulate in `.memory/learning-log.jsonl` with confidence scores and temporal decay. You can edit or delete any generated artifacts — they are never overwritten. - -## Documentation Structure - -DevFlow creates project documentation in `.docs/` and working memory in `.memory/`: - -``` -.docs/ -├── reviews/{branch}/ # Review reports per branch -└── design/ # Implementation plans - -.memory/ -├── WORKING-MEMORY.md # Auto-maintained by Stop hook -├── backup.json # Pre-compact git state snapshot -├── learning-log.jsonl # Learning observations (JSONL) -├── learning.json # Project-level learning config -├── .learning-runs-today # Daily run counter -├── .learning-session-count # Session IDs pending batch (one per line) -├── .learning-batch-ids # Session IDs for current batch run -├── .learning-notified-at # New artifact notification marker -└── knowledge/ - ├── decisions.md # Architectural decisions (ADR-NNN, append-only) - └── pitfalls.md # Known pitfalls (area-specific gotchas) - -~/.devflow/logs/{project-slug}/ -├── .learning-update.log # Background learning agent log -└── .working-memory-update.log # Background memory updater log -``` +See [docs/commands.md](docs/commands.md) for detailed usage. -## Workflow Examples +## Language Support -### Implementing a Feature -```bash -/specify # Define the feature with clarification gates -/implement # Execute the full lifecycle -``` +Optional plugins add language-specific patterns for TypeScript, React, Go, Python, Java, Rust, accessibility, and frontend design. -### Debugging an Issue ```bash -/debug "login fails after session timeout" -/debug #42 # Investigate from GitHub issue +npx devflow-kit init --plugin=typescript,react ``` -### Before Creating a PR -```bash -/code-review # Multi-perspective code review -/resolve # Fix low-risk issues, defer high-risk to backlog -``` +## How it works -### Session Continuity +DevFlow is a plugin system for Claude Code. Each plugin installs commands, agents, and skills into your Claude Code environment. Skills are tiny markdown files that activate automatically based on context. Agents are specialized workers (reviewer, coder, resolver, etc.) with explicit model assignments — Opus for analysis, Sonnet for execution, Haiku for I/O. Commands orchestrate agent pipelines. -Session context is saved and restored automatically via Working Memory hooks — no manual steps needed. +For deep dives: [Working Memory](docs/working-memory.md) | [Self-Learning](docs/self-learning.md) | [CLI Reference](docs/cli-reference.md) | [Commands](docs/commands.md) ## CLI Reference -| Command | Description | -|---------|-------------| -| `npx devflow-kit init` | Install all plugins | -| `npx devflow-kit init --plugin=` | Install specific plugin(s) | -| `npx devflow-kit list` | List available plugins | -| `npx devflow-kit ambient --enable` | Enable always-on ambient mode | -| `npx devflow-kit ambient --disable` | Disable ambient mode | -| `npx devflow-kit learn --enable` | Enable self-learning | -| `npx devflow-kit learn --disable` | Disable self-learning | -| `npx devflow-kit uninstall` | Remove DevFlow | - -### Init Options - -| Option | Description | -|--------|-------------| -| `--plugin ` | Comma-separated plugin names (e.g., `implement,code-review`) | -| `--scope ` | Installation scope (default: user) | -| `--teams` / `--no-teams` | Enable/disable Agent Teams (experimental, default: off) | -| `--ambient` / `--no-ambient` | Enable/disable ambient mode (default: on) | -| `--memory` / `--no-memory` | Enable/disable working memory (default: on) | -| `--learn` / `--no-learn` | Enable/disable self-learning (default: on) | -| `--hud` / `--no-hud` | Enable/disable HUD status line (default: on) | -| `--hud-only` | Install only the HUD (no plugins, hooks, or extras) | -| `--verbose` | Show detailed output | - -### HUD Options - -| Command | Description | -|---------|-------------| -| `npx devflow-kit hud --status` | Show current HUD config | -| `npx devflow-kit hud --enable` | Enable HUD | -| `npx devflow-kit hud --disable` | Disable HUD (version notifications still appear) | -| `npx devflow-kit hud --detail` | Show tool/agent descriptions | -| `npx devflow-kit hud --no-detail` | Hide tool/agent descriptions | - -### Skill Shadowing - -Override any DevFlow skill with your own version. Shadowed skills survive `devflow init` — your version is copied to the install target on each init instead of DevFlow's. - ```bash -# Create a personal override (copies current version as reference) -npx devflow-kit skills shadow software-design - -# Edit your override -vim ~/.devflow/skills/software-design/SKILL.md - -# List all overrides -npx devflow-kit skills list-shadowed - -# Remove override (next init restores DevFlow's version) -npx devflow-kit skills unshadow software-design +npx devflow-kit init # Install (interactive wizard) +npx devflow-kit init --plugin=implement # Install specific plugin +npx devflow-kit list # List available plugins +npx devflow-kit ambient --enable # Toggle ambient mode +npx devflow-kit learn --enable # Toggle self-learning +npx devflow-kit uninstall # Remove DevFlow ``` -### Uninstall Options - -| Option | Description | -|--------|-------------| -| `--scope ` | Uninstall scope (default: user) | -| `--plugin ` | Comma-separated plugin names to uninstall selectively | -| `--keep-docs` | Preserve .docs/ directory | -| `--dry-run` | Show what would be removed without deleting anything | -| `--verbose` | Show detailed uninstall output | +See [docs/cli-reference.md](docs/cli-reference.md) for all options. ## Part of the AI Development Stack | Tool | Role | What It Does | |------|------|-------------| -| **[Skim](https://github.com/dean0x/skim)** | Context Optimization | Code-aware AST parsing across 12 languages, command rewriting, test/build/git output compression | -| **DevFlow** | Quality Orchestration | 18 parallel reviewers, working memory, self-learning, composable plugin system | -| **[Backbeat](https://github.com/dean0x/backbeat)** | Agent Orchestration | Orchestration at scale. Karpathy optimization loops, multi-agent pipelines, DAG dependencies, autoscaling | - -Skim optimizes what your AI sees. DevFlow enforces how it works. Backbeat scales everything across agents. No other stack covers all three. +| **[Skim](https://github.com/dean0x/skim)** | Context Optimization | Code-aware AST parsing, command rewriting, output compression | +| **DevFlow** | Quality Orchestration | Parallel reviewers, working memory, self-learning, composable plugins | +| **[Backbeat](https://github.com/dean0x/backbeat)** | Agent Orchestration | Karpathy optimization loops, multi-agent pipelines, DAG dependencies | ## Building from Source ```bash git clone https://github.com/dean0x/devflow.git -cd devflow -npm install -npm run build +cd devflow && npm install && npm run build node dist/cli.js init ``` +## Requirements + +- [Claude Code](https://claude.ai/download) (latest) +- Node.js 18+ + ## License MIT diff --git a/docs/cli-reference.md b/docs/cli-reference.md new file mode 100644 index 0000000..39f5cb9 --- /dev/null +++ b/docs/cli-reference.md @@ -0,0 +1,116 @@ +# CLI Reference + +## Installation + +```bash +npx devflow-kit init +``` + +The interactive wizard offers two modes: +- **Recommended** (default) — Sensible defaults, quick setup +- **Advanced** — Full interactive flow with all options + +Use `--recommended` or `--advanced` flags for non-interactive setup. + +### Init Options + +| Option | Description | +|--------|-------------| +| `--plugin ` | Comma-separated plugin names (e.g., `implement,code-review`) | +| `--scope ` | Installation scope (default: user) | +| `--teams` / `--no-teams` | Enable/disable Agent Teams (default: off) | +| `--ambient` / `--no-ambient` | Enable/disable ambient mode (default: on) | +| `--memory` / `--no-memory` | Enable/disable working memory (default: on) | +| `--learn` / `--no-learn` | Enable/disable self-learning (default: on) | +| `--hud` / `--no-hud` | Enable/disable HUD status line (default: on) | +| `--hud-only` | Install only the HUD (no plugins, hooks, or extras) | +| `--verbose` | Show detailed output | + +### Scopes + +- `--scope user` (default) — Install for all projects (`~/.claude/`) +- `--scope local` — Install for current project only (`.claude/`) + +## Plugin Management + +```bash +npx devflow-kit list # List available plugins +npx devflow-kit init --plugin=implement # Install specific plugin +npx devflow-kit init --plugin=implement,code-review # Install multiple +``` + +### Available Plugins + +| Plugin | Type | Description | +|--------|------|-------------| +| `devflow-specify` | Core | Feature specification workflow | +| `devflow-implement` | Core | Complete task implementation lifecycle | +| `devflow-code-review` | Core | Comprehensive code review | +| `devflow-resolve` | Core | Review issue resolution | +| `devflow-debug` | Core | Competing hypothesis debugging | +| `devflow-self-review` | Core | Simplifier + Scrutinizer | +| `devflow-ambient` | Core | Ambient mode (always-on intent classification) | +| `devflow-core-skills` | Core | Auto-activating quality skills | +| `devflow-typescript` | Language | TypeScript patterns | +| `devflow-react` | Language | React patterns | +| `devflow-accessibility` | Language | Web accessibility patterns | +| `devflow-frontend-design` | Language | Frontend design patterns | +| `devflow-go` | Language | Go patterns | +| `devflow-python` | Language | Python patterns | +| `devflow-java` | Language | Java patterns | +| `devflow-rust` | Language | Rust patterns | + +## Ambient Mode + +```bash +npx devflow-kit ambient --enable # Enable always-on ambient mode +npx devflow-kit ambient --disable # Disable ambient mode +npx devflow-kit ambient --status # Show current status +``` + +## Self-Learning + +```bash +npx devflow-kit learn --enable # Register the learning hook +npx devflow-kit learn --disable # Remove the learning hook +npx devflow-kit learn --status # Show status and observation counts +npx devflow-kit learn --list # Show all observations by confidence +npx devflow-kit learn --configure # Interactive config (model, throttle, caps) +npx devflow-kit learn --clear # Reset all observations +npx devflow-kit learn --purge # Remove invalid/corrupted entries +``` + +## HUD (Status Line) + +```bash +npx devflow-kit hud --status # Show current HUD config +npx devflow-kit hud --enable # Enable HUD +npx devflow-kit hud --disable # Disable HUD +npx devflow-kit hud --detail # Show tool/agent descriptions +npx devflow-kit hud --no-detail # Hide tool/agent descriptions +``` + +## Skill Shadowing + +Override any DevFlow skill with your own version. Shadowed skills survive `devflow init` — your version is installed instead of DevFlow's. + +```bash +npx devflow-kit skills shadow software-design # Create override (copies current as reference) +vim ~/.devflow/skills/software-design/SKILL.md # Edit your override +npx devflow-kit skills list-shadowed # List all overrides +npx devflow-kit skills unshadow software-design # Remove override +``` + +## Uninstall + +```bash +npx devflow-kit uninstall +``` + +| Option | Description | +|--------|-------------| +| `--scope ` | Uninstall scope (default: user) | +| `--plugin ` | Selective uninstall by plugin name | +| `--keep-docs` | Preserve `.docs/` directory | +| `--dry-run` | Show what would be removed | +| `--verbose` | Show detailed output | diff --git a/docs/commands.md b/docs/commands.md new file mode 100644 index 0000000..47d28a5 --- /dev/null +++ b/docs/commands.md @@ -0,0 +1,113 @@ +# Commands + +DevFlow provides six commands that orchestrate specialized agents. Commands spawn agents — they never do the work themselves. + +## /specify + +Interactive feature specification with three mandatory gates: + +1. **Understanding Gate** — Confirm the feature idea is understood +2. **Scope Gate** — Validate priorities and boundaries +3. **Acceptance Gate** — Confirm success criteria + +Creates a well-defined GitHub issue ready for `/implement`. + +``` +/specify # Start interactive specification +``` + +## /implement + +Executes a single task through the complete development lifecycle: + +1. **Setup** — Auto-create feature branch (detects repo naming conventions) +2. **Exploration** — Analyze codebase for relevant patterns and dependencies +3. **Planning** — Design the implementation approach +4. **Implementation** — Write code on the feature branch +5. **Validation** — Build, typecheck, lint, and test +6. **Refinement** — Simplifier (code clarity) + Scrutinizer (9-pillar quality) +7. **Alignment** — Shepherd verifies implementation matches the original request + +Creates a PR when complete. + +``` +/implement add JWT auth # From description +/implement #42 # From GitHub issue +/implement # From conversation context +``` + +## /code-review + +Multi-perspective code review with up to 18 specialized reviewers running in parallel: + +**Always active:** Security, Architecture, Performance, Complexity, Consistency, Regression, Testing + +**Conditionally active** (when relevant files detected): TypeScript, React, Accessibility, Go, Python, Java, Rust, Database, Dependencies, Documentation + +Each reviewer produces findings with: +- **Category**: Blocking (must-fix), Should-Fix, Pre-existing (informational) +- **Severity**: CRITICAL, HIGH, MEDIUM, LOW +- **Location**: Exact file:line reference +- **Fix**: Specific code solution + +Supports multi-worktree auto-discovery — one command reviews all active branches. + +``` +/code-review # Review current branch (or all worktrees) +/code-review #42 # Review specific PR +``` + +## /resolve + +Processes all issues from `/code-review` reports: + +1. **Parse** — Extract all issues from the latest unresolved review +2. **Batch** — Group by file/function for efficient resolution +3. **Resolve** — Parallel resolver agents validate each issue, then: + - **Fix** standard issues directly + - **Fix carefully** (public API, shared state, core logic) with systematic test-first refactoring + - **Won't Fix** impractical issues (e.g., micro-optimizing startup code) + - **Defer** only genuine architectural overhauls to tech debt +4. **Simplify** — Clean up all modified files +5. **Report** — Write resolution summary with full decision audit trail + +``` +/resolve # Resolve latest review (or all worktrees) +/resolve #42 # Resolve specific PR's review +/resolve --review 2026-03-28_0900 # Resolve specific review run +``` + +## /debug + +Investigates bugs using competing hypotheses: + +1. **Hypothesis Generation** — Identify 3-5 plausible explanations +2. **Parallel Investigation** — Each hypothesis investigated independently by separate agents +3. **Evidence Evaluation** — Hypotheses ranked by supporting evidence +4. **Root Cause** — Best-supported explanation with fix recommendation + +``` +/debug "login fails after session timeout" +/debug #42 # Investigate from GitHub issue +``` + +## /self-review + +Self-review workflow that runs two sequential quality passes: + +1. **Simplifier** — Code clarity, reuse opportunities, efficiency +2. **Scrutinizer** — 9-pillar quality evaluation (correctness, security, performance, etc.) + +``` +/self-review # Review recent changes +``` + +## Ambient Mode + +Not a command — an always-on hook that classifies every prompt and loads proportional skill sets: + +| Depth | When | What happens | +|-------|------|-------------| +| **QUICK** | Chat, git ops, trivial edits | Zero overhead — respond normally | +| **GUIDED** | Small implementations, focused debugging | Skills loaded, main session implements | +| **ORCHESTRATED** | Complex tasks, multi-file changes | Full agent pipeline (same as slash commands) | diff --git a/docs/self-learning.md b/docs/self-learning.md new file mode 100644 index 0000000..bdab432 --- /dev/null +++ b/docs/self-learning.md @@ -0,0 +1,56 @@ +# Self-Learning + +DevFlow detects repeated workflows and procedural knowledge across sessions and automatically creates slash commands and skills. + +## How it works + +A background agent runs on session end, batching every 3 sessions (5 at 15+ observations) to analyze transcripts for patterns. When a pattern is observed enough times (3 observations with 24h+ temporal spread), it creates an artifact: + +- **Workflow patterns** become slash commands at `.claude/commands/self-learning/` +- **Procedural patterns** become skills at `.claude/skills/{slug}/` + +Observations accumulate in `.memory/learning-log.jsonl` with confidence scores and temporal decay. Generated artifacts are never overwritten — you can edit or delete them freely. + +## CLI Commands + +```bash +npx devflow-kit learn --enable # Register the learning SessionEnd hook +npx devflow-kit learn --disable # Remove the learning hook +npx devflow-kit learn --status # Show status and observation counts +npx devflow-kit learn --list # Show all observations sorted by confidence +npx devflow-kit learn --configure # Interactive config (model, throttle, daily cap, debug) +npx devflow-kit learn --clear # Reset all observations +npx devflow-kit learn --purge # Remove invalid/corrupted entries +``` + +## Configuration + +Use `devflow learn --configure` for interactive setup, or edit `.memory/learning.json` directly: + +| Setting | Default | Description | +|---------|---------|-------------| +| Model | `haiku` | Model for background analysis | +| Batch size | 3 sessions (5 at 15+ obs) | Sessions accumulated before analysis | +| Daily cap | 5 runs | Maximum learning runs per day | +| Debug | `false` | Enable verbose logging | + +## Observation Lifecycle + +1. **Accumulate** — Each session end appends the session ID to `.memory/.learning-session-count` +2. **Batch** — When count reaches threshold, session IDs are moved to `.learning-batch-ids` +3. **Analyze** — Background agent reads batch transcripts, extracts patterns +4. **Score** — Observations get confidence scores based on frequency and temporal spread +5. **Create** — When confidence threshold met (3 observations, 24h+ spread), artifact is generated +6. **Reinforce** — Existing observations are reinforced locally (no LLM) on each session end + +## Files + +| File | Purpose | +|------|---------| +| `.memory/learning-log.jsonl` | All observations (one JSON per line) | +| `.memory/learning.json` | Project-level configuration | +| `.memory/.learning-runs-today` | Daily run counter (date + count) | +| `.memory/.learning-session-count` | Session IDs pending batch | +| `.memory/.learning-batch-ids` | Session IDs for current batch | +| `.memory/.learning-notified-at` | Artifact notification marker | +| `~/.devflow/logs/{project-slug}/.learning-update.log` | Background agent log | diff --git a/docs/working-memory.md b/docs/working-memory.md new file mode 100644 index 0000000..be1c491 --- /dev/null +++ b/docs/working-memory.md @@ -0,0 +1,81 @@ +# Working Memory + +DevFlow automatically preserves session context across restarts, `/clear`, and context compaction — zero ceremony required. + +## How it works + +Three shell hooks run behind the scenes: + +| Hook | When | What | +|------|------|------| +| **Stop** | After each response | Updates `.memory/WORKING-MEMORY.md` with current focus, decisions, and progress. Throttled — skips if updated <2 min ago. | +| **SessionStart** | On startup, `/clear`, resume, compaction | Injects previous working memory + fresh git state as system context. Warns if memory is >1h stale. | +| **PreCompact** | Before context compaction | Backs up git state to JSON. Bootstraps a minimal working memory from git if none exists yet. | + +Working memory is **per-project** — scoped to each repo's `.memory/` directory. Multiple sessions across different repos don't interfere. + +## Enable / Disable + +```bash +npx devflow-kit init --memory # Enable during install +npx devflow-kit init --no-memory # Disable during install +devflow memory --enable # Toggle on +devflow memory --disable # Toggle off +devflow memory --status # Check current state +``` + +## File Structure + +``` +.memory/ +├── WORKING-MEMORY.md # Auto-maintained by Stop hook (overwritten each session) +├── backup.json # Pre-compact git state snapshot +├── learning-log.jsonl # Learning observations (JSONL, one entry per line) +├── learning.json # Project-level learning config +├── .learning-runs-today # Daily run counter (date + count) +├── .learning-session-count # Session IDs pending batch (one per line) +├── .learning-batch-ids # Session IDs for current batch run +├── .learning-notified-at # New artifact notification marker (epoch timestamp) +└── knowledge/ + ├── decisions.md # Architectural decisions (ADR-NNN, append-only) + └── pitfalls.md # Known pitfalls (PF-NNN, area-specific gotchas) +``` + +Debug logs are stored at `~/.devflow/logs/{project-slug}/`. + +## Working Memory Sections + +The Stop hook maintains these sections in `WORKING-MEMORY.md`: + +| Section | Purpose | +|---------|---------| +| `## Now` | Current focus and immediate next steps | +| `## Progress` | What's done, what remains, blockers | +| `## Decisions` | Architectural and design decisions made this session | +| `## Modified Files` | Files changed with status | +| `## Context` | Repository state, build status, test results | +| `## Session Log` | Timestamped log of significant actions | + +## Long-term Knowledge + +Beyond session memory, DevFlow persists architectural decisions and known pitfalls: + +- **`decisions.md`** — ADR-numbered entries (append-only). Reviewers check if changes violate prior decisions. +- **`pitfalls.md`** — PF-numbered entries scoped by area. Reviewers check if changes reintroduce known pitfalls. + +These files are read by reviewers automatically during `/code-review`. + +## Documentation Structure + +DevFlow creates project documentation in `.docs/`: + +``` +.docs/ +├── reviews/{branch-slug}/ # Review reports per branch +│ ├── .last-review-head # HEAD SHA for incremental reviews +│ └── {timestamp}/ # Timestamped review directory +│ ├── {focus}.md # Reviewer reports +│ ├── review-summary.md # Synthesizer output +│ └── resolution-summary.md # Written by /resolve +└── design/ # Implementation plans +``` diff --git a/plugins/devflow-resolve/commands/resolve-teams.md b/plugins/devflow-resolve/commands/resolve-teams.md index 3108d11..2d30da5 100644 --- a/plugins/devflow-resolve/commands/resolve-teams.md +++ b/plugins/devflow-resolve/commands/resolve-teams.md @@ -68,19 +68,16 @@ Read review reports from `{TARGET_DIR}/*.md` and extract: - `review-summary.md` (synthesizer output, not individual findings) - `resolution-summary.md` (if it exists from a previous partial run) -**Include only:** -- Blocking issues (CRITICAL, HIGH) -- Should-Fix issues (HIGH, MEDIUM) +**Include:** ALL issues from all categories and severities, including Suggestions. -**Skip:** -- Pre-existing issues (belong in tech debt, not resolution) -- LOW severity (informational only) +Issues are extracted from `{TARGET_DIR}` only — never cross-reference reviews from other worktrees. **Extract per issue:** - `id`: Generated from file:line:type - `file`: Full path - `line`: Line number -- `severity`: CRITICAL/HIGH/MEDIUM +- `severity`: CRITICAL/HIGH/MEDIUM/LOW +- `category`: blocking/should-fix/pre-existing - `type`: Issue type from review - `description`: Problem statement - `suggested_fix`: From review report @@ -113,41 +110,37 @@ Create a resolution team for cross-validated fixes: ``` Create a team named "resolve-{branch-slug}" to resolve review issues. -Spawn resolver teammates with self-contained prompts (one per independent batch): +#### Resolver Teammate Prompt Template + +Each resolver teammate receives the following instructions (only the issue list varies per batch): -- Name: "resolver-batch-1" - Prompt: | You are resolving review issues on branch {branch} (PR #{pr_number}). WORKTREE_PATH: {worktree_path} (omit if cwd) 1. Read your skill: `Read ~/.claude/skills/devflow:implementation-patterns/SKILL.md` 2. Your issues to resolve: - {batch 1 issues — full structured list with id, file, line, severity, type, description, suggested_fix} + {BATCH_ISSUES} 3. For each issue: a. Read the code context around file:line (use WORKTREE_PATH prefix if provided) b. Validate: is this a real issue or false positive? - c. If real: assess risk (LOW → FIX now, HIGH → defer to TECH_DEBT) + c. If real: assess risk: + - Standard (null checks, validation, docs, logging, isolated security) → FIX directly + - Careful (public API, shared state, >3 files, core logic) → systematic refactoring: understand 50+ lines context → plan → test at all call sites → implement → verify → commit + - Architectural overhaul (complete redesign, multi-service DB migrations) → TECH_DEBT (LAST RESORT — avoided at almost all costs) d. If FIX: implement the fix, commit with descriptive message e. If TECH_DEBT: document why it's deferred 4. Report completion: SendMessage(type: "message", recipient: "team-lead", - summary: "Batch 1: {n} fixed, {n} deferred, {n} false positive") + summary: "Batch {N}: {n} fixed, {n} deferred, {n} false positive") + +#### Spawn teammates using the template above (one per independent batch): + +- Name: "resolver-batch-1" + Prompt: Use Resolver Teammate Prompt Template with BATCH_ISSUES = + {batch 1 issues — full structured list with id, file, line, severity, category, type, description, suggested_fix} - Name: "resolver-batch-2" - Prompt: | - You are resolving review issues on branch {branch} (PR #{pr_number}). - WORKTREE_PATH: {worktree_path} (omit if cwd) - 1. Read your skill: `Read ~/.claude/skills/devflow:implementation-patterns/SKILL.md` - 2. Your issues to resolve: - {batch 2 issues — full structured list with id, file, line, severity, type, description, suggested_fix} - 3. For each issue: - a. Read the code context around file:line (use WORKTREE_PATH prefix if provided) - b. Validate: is this a real issue or false positive? - c. If real: assess risk (LOW → FIX now, HIGH → defer to TECH_DEBT) - d. If FIX: implement the fix, commit with descriptive message - e. If TECH_DEBT: document why it's deferred - 4. Report completion: - SendMessage(type: "message", recipient: "team-lead", - summary: "Batch 2: {n} fixed, {n} deferred, {n} false positive") + Prompt: Use Resolver Teammate Prompt Template with BATCH_ISSUES = + {batch 2 issues} (Additional resolvers for additional batches — same pattern) @@ -266,7 +259,7 @@ In multi-worktree mode, report results per worktree with aggregate summary. │ └─ Step 0c: Target latest review directory per worktree │ ├─ Phase 1: Parse issues from TARGET_DIR -│ └─ Extract Blocking + Should-Fix (skip Pre-existing, exclude summaries) +│ └─ Extract ALL issues (including Suggestions, exclude summaries) │ ├─ Phase 2: Analyze dependencies │ └─ Build dependency graph @@ -281,7 +274,7 @@ In multi-worktree mode, report results per worktree with aggregate summary. │ └─ Cross-validation debate → consensus on conflicts │ ├─ Phase 5: Collect results -│ └─ Aggregate fixed, false positives, deferred, blocked +│ └─ Aggregate fixed, false positives, deferred │ ├─ Phase 6: Record Pitfalls (SEQUENTIAL across worktrees) │ @@ -302,7 +295,7 @@ In multi-worktree mode, report results per worktree with aggregate summary. | All false positives | Normal completion, report shows 0 fixes | | Fix attempt fails | Revert changes, mark BLOCKED, continue others | | Issue dependencies | Sequential chain, skip dependents if predecessor blocked | -| No actionable issues | Report "No issues to resolve" (all were pre-existing or LOW) | +| No actionable issues | Report "No issues to resolve" | | Incomplete review directory | Skip — resolve only targets complete reviews | | Latest review already resolved | Skip worktree, suggest /code-review first | | Legacy flat layout | Read flat *.md files directly (backwards compatible) | diff --git a/plugins/devflow-resolve/commands/resolve.md b/plugins/devflow-resolve/commands/resolve.md index 72dd6cb..dde8259 100644 --- a/plugins/devflow-resolve/commands/resolve.md +++ b/plugins/devflow-resolve/commands/resolve.md @@ -68,19 +68,16 @@ Read review reports from `{TARGET_DIR}/*.md` and extract: - `review-summary.md` (synthesizer output, not individual findings) - `resolution-summary.md` (if it exists from a previous partial run) -**Include only:** -- Blocking issues (CRITICAL, HIGH) -- Should-Fix issues (HIGH, MEDIUM) +**Include:** ALL issues from all categories and severities, including Suggestions. -**Skip:** -- Pre-existing issues (belong in tech debt, not resolution) -- LOW severity (informational only) +Issues are extracted from `{TARGET_DIR}` only — never cross-reference reviews from other worktrees. **Extract per issue:** - `id`: Generated from file:line:type - `file`: Full path - `line`: Line number -- `severity`: CRITICAL/HIGH/MEDIUM +- `severity`: CRITICAL/HIGH/MEDIUM/LOW +- `category`: blocking/should-fix/pre-existing - `type`: Issue type from review - `description`: Problem statement - `suggested_fix`: From review report @@ -115,6 +112,11 @@ WORKTREE_PATH: {worktree_path} (omit if cwd) Validate, decide FIX vs TECH_DEBT, implement fixes" ``` +> Resolvers follow a 3-tier risk approach: +> - **Standard fixes** (null checks, validation, docs, logging, isolated security): applied directly +> - **Careful fixes** (public API, shared state, >3 files, core logic): systematic refactoring — understand broader context, plan changes, test at all call sites, implement, verify, commit +> - **Architectural overhaul** (complete system redesign, multi-service DB migrations): defer to tech debt — LAST RESORT, avoided at almost all costs + For dependent batches, spawn sequentially and wait for completion before spawning dependents. ### Phase 5: Collect Results @@ -203,7 +205,7 @@ In multi-worktree mode, report results per worktree with aggregate summary. │ └─ Step 0c: Target latest review directory per worktree │ ├─ Phase 1: Parse issues from TARGET_DIR -│ └─ Extract Blocking + Should-Fix (skip Pre-existing, exclude summaries) +│ └─ Extract ALL issues (including Suggestions, exclude summaries) │ ├─ Phase 2: Analyze dependencies │ └─ Build dependency graph @@ -217,7 +219,7 @@ In multi-worktree mode, report results per worktree with aggregate summary. │ └─ Resolver: Batch 3 (waits if depends on 1 or 2) │ ├─ Phase 5: Collect results -│ └─ Aggregate fixed, false positives, deferred, blocked +│ └─ Aggregate fixed, false positives, deferred │ ├─ Phase 6: Record Pitfalls (SEQUENTIAL across worktrees) │ @@ -238,7 +240,7 @@ In multi-worktree mode, report results per worktree with aggregate summary. | All false positives | Normal completion, report shows 0 fixes | | Fix attempt fails | Revert changes, mark BLOCKED, continue others | | Issue dependencies | Sequential chain, skip dependents if predecessor blocked | -| No actionable issues | Report "No issues to resolve" (all were pre-existing or LOW) | +| No actionable issues | Report "No issues to resolve" | | Incomplete review directory (no review-summary.md) | Skip — resolve only targets complete reviews | | Latest review already resolved | Skip worktree, report suggestion to run /code-review first | | Legacy flat layout (no subdirectories) | Read flat *.md files directly (backwards compatible) | diff --git a/shared/agents/git.md b/shared/agents/git.md index 223fa7f..f1cb287 100644 --- a/shared/agents/git.md +++ b/shared/agents/git.md @@ -38,7 +38,7 @@ Pre-flight checks and fixes for `/code-review`. Ensures branch is ready for code **Input:** `WORKTREE_PATH` (optional) **Process:** -1. Verify on feature branch (not main/master/develop/release/*/staging/production) - error if not +1. Verify on feature branch (not main/master/develop/integration/trunk/release/*/staging/production) - error if not 2. Check for uncommitted changes - if any, create atomic commit using `devflow:git` patterns 3. Check if branch pushed to remote - if not, push with `-u` flag 4. Check if PR exists - if not, create PR using `devflow:git` patterns @@ -73,7 +73,7 @@ Pre-flight validation for `/resolve`. Checks branch state without modifications. **Input:** `WORKTREE_PATH` (optional) **Process:** -1. Verify on feature branch (not main/master/develop/release/*/staging/production) - error if not +1. Verify on feature branch (not main/master/develop/integration/trunk/release/*/staging/production) - error if not 2. Verify working directory is clean - error if uncommitted changes 3. Get current branch name 4. Derive branch-slug (replace `/` with `-`) @@ -112,14 +112,22 @@ Set up task environment: derive branch name, create feature branch, and optional **Process:** 1. Record current branch as BASE_BRANCH for later PR targeting -2. **Derive branch name:** +2. **Detect branch naming convention** from existing branches: + ```bash + git branch -r --format='%(refname:short)' | head -50 + ``` + - Count prefixes: `feature/` vs `feat/`, `bugfix/` vs `fix/`, `hotfix/` vs `fix/` + - If existing branches consistently use a prefix style (>2 instances), adopt it + - Detect separator style: hyphens vs underscores + - If no clear convention or empty repo, use defaults (`feature/`, `fix/`, `docs/`, `refactor/`, `chore/`) +3. **Derive branch name** (using detected convention): - If `ISSUE_INPUT` provided: fetch issue via GitHub API first, then derive branch name as `{type}/{number}-{slug}` where: - `type` is inferred from issue labels: `bug` → `fix`, `documentation` or `docs` → `docs`, `refactor` → `refactor`, `chore` or `maintenance` → `chore`, default → `feature` - `slug` is the issue title: lowercased, non-alphanumeric replaced with hyphens, consecutive hyphens collapsed, trimmed, max 40 characters - If `TASK_DESCRIPTION` provided (no issue): infer type from description keywords (e.g., "fix login bug" → `fix`, "refactor auth" → `refactor`, "add JWT" → `feature`, "update docs" → `docs`, "chore: cleanup" → `chore`), then slugify description as `{type}/{slug}` (max 40 chars) - If neither: fallback to `task-{YYYY-MM-DD_HHMM}` -3. Create and checkout feature branch: `git checkout -b {derived-branch-name}` -4. Return setup summary with branch name and BASE_BRANCH recorded +4. Create and checkout feature branch: `git checkout -b {derived-branch-name}` +5. Return setup summary with branch name and BASE_BRANCH recorded **Output:** ```markdown diff --git a/shared/agents/resolver.md b/shared/agents/resolver.md index ecb3b98..61cbc29 100644 --- a/shared/agents/resolver.md +++ b/shared/agents/resolver.md @@ -32,7 +32,7 @@ You receive from orchestrator: 3. **Assess risk for valid issues**: Apply risk criteria to decide FIX vs TECH_DEBT. -4. **Implement low-risk fixes**: Make changes following existing patterns. One logical change per commit. +4. **Implement fixes**: Make changes following existing patterns. One logical change per commit. 5. **Document all decisions**: Record reasoning for every classification and risk assessment. @@ -58,7 +58,13 @@ You receive from orchestrator: - Multi-service interface changes - Auth flow changes -For careful fixes: write tests first covering current behavior → apply fix → verify tests still pass → commit. +For careful fixes, follow the systematic refactoring protocol: +1. **Understand** — Read broader context (50+ lines around change, callers/consumers), identify all affected sites +2. **Plan** — Document what changes, what stays the same, what could break +3. **Test** — Write comprehensive tests at all affected call sites covering current behavior +4. **Implement** — Apply fix per plan +5. **Verify** — Run tests, diagnose any failures +6. **Commit** — Atomic commit with clear message **Architectural overhaul** (defer to tech debt — LAST RESORT): - Requires complete system redesign (e.g., fundamentally different architecture) @@ -79,8 +85,10 @@ For each issue: └─ Risk Assessment: ├─ Requires complete architectural redesign? → TECH_DEBT (last resort) ├─ Changes public API / shared state / >3 files / core logic? → CAREFUL FIX - │ ├─ Write tests covering current behavior first - │ ├─ Apply fix + │ ├─ Understand (50+ lines context, callers, consumers) + │ ├─ Plan (what changes, what stays, what could break) + │ ├─ Test (comprehensive tests at all affected call sites) + │ ├─ Implement fix per plan │ ├─ Verify tests pass │ └─ Commit └─ Otherwise → STANDARD FIX → implement directly diff --git a/shared/agents/reviewer.md b/shared/agents/reviewer.md index 64fd530..8291ced 100644 --- a/shared/agents/reviewer.md +++ b/shared/agents/reviewer.md @@ -46,7 +46,7 @@ The orchestrator provides: 1. **Load focus skill** - Read the pattern skill file for your focus area from the table above. This gives you detection rules and patterns specific to your review type. 2. **Check known pitfalls** - If `.memory/knowledge/pitfalls.md` exists, read it. Check if any pitfall Areas overlap with files in the current diff. Verify the Resolution was applied. Flag if a known pitfall pattern is being reintroduced. -3. **Identify changed lines** - Get diff against base branch (main/master/develop) +3. **Identify changed lines** - Get diff against base branch (main/master/develop/integration/trunk) 4. **Apply 3-category classification** - Sort issues by where they occur 5. **Apply focus-specific analysis** - Use pattern skill detection rules from the loaded skill file 6. **Assign severity** - CRITICAL, HIGH, MEDIUM, LOW based on impact diff --git a/shared/skills/git/SKILL.md b/shared/skills/git/SKILL.md index 6e5d622..4765b1b 100644 --- a/shared/skills/git/SKILL.md +++ b/shared/skills/git/SKILL.md @@ -70,7 +70,7 @@ Only use `--amend` when ALL conditions are met: ### Branch Safety -Never force push to: `main`, `master`, `develop`, `release/*`, `staging`, `production` +Never force push to: `main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production` **Branch naming**: `feat/`, `fix/`, `release/`, `hotfix/` prefixes with short descriptions. diff --git a/shared/skills/git/references/patterns.md b/shared/skills/git/references/patterns.md index 1a87f91..a1a8b5f 100644 --- a/shared/skills/git/references/patterns.md +++ b/shared/skills/git/references/patterns.md @@ -52,7 +52,7 @@ fi ### Protected Branch Check ```bash -PROTECTED_BRANCHES="main master develop staging production" +PROTECTED_BRANCHES="main master develop integration trunk staging production" check_protected_branch() { local branch="$1" diff --git a/shared/skills/implementation-orchestration/SKILL.md b/shared/skills/implementation-orchestration/SKILL.md index a474fad..d64fa95 100644 --- a/shared/skills/implementation-orchestration/SKILL.md +++ b/shared/skills/implementation-orchestration/SKILL.md @@ -2,7 +2,7 @@ name: implementation-orchestration description: Agent orchestration for IMPLEMENT intent — pre-flight, Coder, quality gates user-invocable: false -allowed-tools: Read, Grep, Glob, Bash, Task, AskUserQuestion +allowed-tools: Read, Grep, Glob, Bash, Task --- # Implementation Orchestration @@ -26,8 +26,19 @@ This is a lightweight variant of `/implement` for ambient ORCHESTRATED mode. Exc Detect branch type before spawning Coder: - **Work branches** (`feat/`, `fix/`, `chore/`, `refactor/`, `docs/` prefix): proceed on current branch. -- **Protected branches** (`main`, `master`, `develop`, `release/*`, `staging`, `production`): ask user via AskUserQuestion with 2-3 suggested branch names following `{type}/{ticket}-{slug}` convention. Include ticket number if available from conversation context. -- **If user declines branch creation**: proceed on the protected branch. Respect the user's choice. +- **Protected branches** (`main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production`): record current branch as `BASE_BRANCH`, then spawn Git agent to auto-create a feature branch: + +``` +Task(subagent_type="Git"): +"OPERATION: setup-task +BASE_BRANCH: {current branch name} +ISSUE_INPUT: {issue number if ticket mentioned in conversation, otherwise omit} +TASK_DESCRIPTION: {task description from conversation context} +Derive branch name from issue or description, create feature branch, and fetch issue if specified. +Return the branch setup summary." +``` + +Capture `branch name` and `BASE_BRANCH` from Git agent output for use throughout the pipeline. ## Phase 2: Plan Synthesis diff --git a/shared/skills/resolve-orchestration/SKILL.md b/shared/skills/resolve-orchestration/SKILL.md index d24aea9..51b4650 100644 --- a/shared/skills/resolve-orchestration/SKILL.md +++ b/shared/skills/resolve-orchestration/SKILL.md @@ -35,11 +35,11 @@ Extract branch slug from the directory path. Read all `{focus}.md` files in the timestamped directory (exclude `review-summary.md` and `resolution-summary.md`). -Extract issues at **Blocking** and **Should-Fix** severity only. Skip Pre-existing and Suggestions. +Extract **ALL** issues from all categories and severities, including Suggestions. -For each issue, extract: id (generated), file, line, severity, type (from focus), description, suggested_fix. +For each issue, extract: id (generated), file, line, severity, category (blocking/should-fix/pre-existing), type (from focus), description, suggested_fix. -If no actionable issues found: "Review is clean — no blocking or should-fix issues to resolve." → stop. +If no actionable issues found: "Review is clean — no issues to resolve." → stop. ## Phase 3: Analyze & Batch @@ -61,8 +61,8 @@ Each receives: Resolvers follow a 3-tier risk approach: - **Standard fixes**: Applied directly -- **Careful fixes** (public API, shared state, >3 files): Test-first — write tests covering current behavior, apply fix, verify tests pass -- **Architectural overhaul**: Defer to tech debt (LAST RESORT — only when complete system redesign required) +- **Careful fixes** (public API, shared state, >3 files): Systematic refactoring — understand context, plan, test, implement, verify +- **Architectural overhaul**: Defer to tech debt (LAST RESORT — avoided at almost all costs, only when complete system redesign required) ## Phase 5: Collect & Simplify diff --git a/shared/skills/review-methodology/SKILL.md b/shared/skills/review-methodology/SKILL.md index b8d7e0d..726ea19 100644 --- a/shared/skills/review-methodology/SKILL.md +++ b/shared/skills/review-methodology/SKILL.md @@ -40,6 +40,8 @@ Get the diff to understand what changed. Identify base branch and extract change | **2. Issues in Code You Touched** | Same file/function, but not your line | HIGH | Should fix while here | | **3. Pre-existing Issues** | Lines you didn't touch at all | INFORMATIONAL | Fix in separate PR | +**Note:** All categories and severities — including suggestions — are reported for resolution. Categories affect PR merge-blocking, not whether issues get resolved. The resolve workflow evaluates everything. + ### Step 3: Analyze with Domain Expertise Apply your specialized lens (security, performance, tests, etc.) to each category: diff --git a/shared/skills/review-methodology/references/patterns.md b/shared/skills/review-methodology/references/patterns.md index 35857e1..96e3989 100644 --- a/shared/skills/review-methodology/references/patterns.md +++ b/shared/skills/review-methodology/references/patterns.md @@ -33,7 +33,7 @@ Correct patterns for effective code reviews. ```bash # Get the base branch BASE_BRANCH="" -for branch in main master develop; do +for branch in main master develop integration trunk; do if git show-ref --verify --quiet refs/heads/$branch; then BASE_BRANCH=$branch break @@ -72,7 +72,7 @@ echo "Current branch: $(git branch --show-current)" ```bash # Detect base branch (in priority order) -for branch in main master develop; do +for branch in main master develop integration trunk; do if git show-ref --verify --quiet refs/heads/$branch; then BASE_BRANCH=$branch break diff --git a/shared/skills/worktree-support/SKILL.md b/shared/skills/worktree-support/SKILL.md index 41b158d..b79c231 100644 --- a/shared/skills/worktree-support/SKILL.md +++ b/shared/skills/worktree-support/SKILL.md @@ -50,7 +50,7 @@ Extract: `worktree {path}`, `HEAD {sha}`, `branch refs/heads/{name}` Exclude: - **Bare worktrees** (no branch) - **Detached HEAD** (no named branch) -- **Protected branches**: `main`, `master`, `develop`, `release/*`, `staging`, `production` +- **Protected branches**: `main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production` - **Mid-rebase or mid-merge**: check `git -C {path} status` for "rebase in progress" or "merging" ### Step 4: Check for Work @@ -73,7 +73,7 @@ Return list of reviewable worktrees with path, branch, HEAD SHA. ## Protected Branches (Canonical List) -`main`, `master`, `develop`, `release/*`, `staging`, `production` +`main`, `master`, `develop`, `integration`, `trunk`, `release/*`, `staging`, `production` All components (agents, commands, skills) must use this exact list when checking for protected branches.