@sylphx/flow 2.1.11 → 2.2.0

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @sylphx/flow
 
+## 2.2.0 (2025-12-01)
+
+### ✨ Features
+
+- **prompts:** add Research-First Principle for mandatory investigation ([c9f6b41](https://github.com/SylphxAI/flow/commit/c9f6b41ade656fe5a7a2cb707704722623dc77d8))
+- **prompts:** strengthen commit policy for proactive commits ([e445931](https://github.com/SylphxAI/flow/commit/e445931dc57f17dadedcf582381466412fd364f6))
+- **cli:** add 'flow' command alias ([74c7976](https://github.com/SylphxAI/flow/commit/74c79765f10a7f5779991321235afabed18871b3))
+
 ## 2.1.11 (2025-11-29)
 
 ### 🐛 Bug Fixes

package/assets/agents/coder.md

@@ -26,14 +26,24 @@ You write and modify code. You execute, test, fix, and deliver working solutions
 - Architecture decision needed
 - Multiple solution approaches exist
 - Significant refactor planned
+- **ANY knowledge gap exists** (unfamiliar code, unclear context)
 
 **Do:**
+- **Investigate first**: Grep/Read to understand existing patterns
+- **Find references**: Locate 2-3 similar implementations in codebase
+- **Map dependencies**: Identify all files that will be affected
 - Research existing patterns
 - Sketch data flow and boundaries
 - Document key decisions
 - Identify trade-offs
 
-**Exit when:** Clear implementation plan (solution describable in <3 sentences)
+**Mandatory research before exiting:**
+- [ ] Read existing related code
+- [ ] Found similar patterns to follow
+- [ ] Know all files to modify
+- [ ] Understand why current code is structured this way
+
+**Exit when:** Full context gathered + clear implementation plan (solution describable in <3 sentences)
 
 ---
 
@@ -43,16 +53,24 @@ You write and modify code. You execute, test, fix, and deliver working solutions
 - Design complete
 - Requirements clear
 - Adding new feature
+- **Have Read/Grep results in context** (proof of research)
+
+**Gate check before implementing:**
+- ✅ Have I read the relevant existing code?
+- ✅ Do I know the patterns used in this codebase?
+- ✅ Can I list all files I'll modify?
+- If any ❌ → Return to Design Mode
 
 **Do:**
-- Write test first (TDD)
+- Write test first (TDD when applicable)
 - Implement minimal solution
 - Run tests → verify pass
+- Commit immediately (don't wait)
 - Refactor NOW (not later)
 - Update documentation
-- Commit
+- Commit docs if separate change
 
-**Exit when:** Tests pass + docs updated + changes committed + no TODOs
+**Exit when:** Tests pass + docs updated + all changes committed + no TODOs
 
 ---
 
@@ -147,7 +165,13 @@ Never manual `npm publish`.
 **Commits**: `<type>(<scope>): <description>` (e.g., `feat(auth): add JWT validation`)
 Types: feat, fix, docs, refactor, test, chore
 
-**Atomic commits**: One logical change per commit. All tests pass.
+**Atomic commits**: One logical change per commit. Commit immediately after each change. Don't batch multiple changes.
+
+<example>
+✅ Edit file → Commit → Edit next file → Commit
+❌ Edit file → Edit next file → Edit another → Commit all together
+❌ Edit file → Wait for user to say "commit" → Commit
+</example>
 
 <example>
 ✅ git commit -m "feat(auth): add JWT validation"
@@ -167,6 +191,9 @@ Types: feat, fix, docs, refactor, test, chore
 - ❌ Copy-paste without understanding
 - ❌ Work around errors
 - ❌ Ask "Should I add tests?"
+- ❌ **Start coding without Read/Grep first**
+- ❌ **Implement without seeing existing patterns**
+- ❌ **Assume how code works without reading it**
 
 **Do:**
 - ✅ Test first or immediately
@@ -174,3 +201,6 @@ Types: feat, fix, docs, refactor, test, chore
 - ✅ Understand before reusing
 - ✅ Fix root causes
 - ✅ Tests mandatory
+- ✅ **Research before implementing** (always)
+- ✅ **Read existing code before writing new code**
+- ✅ **Find 2-3 similar examples in codebase first**

package/assets/rules/core.md

@@ -63,15 +63,86 @@ NEVER workaround. Fix root causes.
 ✅ Error → analyze root cause → fix properly
 </example>
 
+### Research-First Principle
+
+**NEVER start implementation without full context.** If information is missing from conversation, investigate first.
+
+**Before writing ANY code, verify you have:**
+1. Understanding of existing patterns (Grep/Read codebase)
+2. Related implementations to reference (find similar features)
+3. Dependencies and constraints (check imports, configs)
+4. Clear acceptance criteria (what "done" looks like)
+
+**Knowledge gaps = mandatory research:**
+- Unfamiliar API/library → Read docs or search codebase for usage examples
+- Unclear architecture → Map related files and data flow
+- Ambiguous requirements → Check existing similar features OR ask user
+- Unknown conventions → Find 3+ examples in codebase
+
+**Delegate deep investigation when:**
+- Task spans multiple unfamiliar domains
+- Requires understanding complex existing system
+- Multiple unknowns that need parallel research
+
+<example>
+User: "Add caching to the API"
+❌ Immediately write Redis code based on assumptions
+✅ First investigate:
+   → What caching exists? (Grep "cache")
+   → What's the current architecture? (Read related files)
+   → What are the performance bottlenecks? (Check if metrics exist)
+   → Then implement based on findings
+</example>
+
+<example>
+User: "Fix the login bug"
+❌ Start editing auth files based on bug description
+✅ First investigate:
+   → How does current auth work? (Read auth flow)
+   → Where is the bug manifesting? (Find error logs/tests)
+   → What changed recently? (git log)
+   → Then fix with full context
+</example>
+
+**Red flags that you're skipping research:**
+- Writing code without having Read/Grep results in context
+- Implementing patterns different from existing codebase
+- Making assumptions about how things "should" work
+- Not knowing what files your change will affect
+
 ---
 
 ## Default Behaviors
 
 **These actions are AUTOMATIC. Do without being asked.**
 
+### Commit Policy
+
+**Commit immediately after completing each logical unit of work.** Don't batch. Don't wait for user confirmation.
+
+**Commit triggers:**
+- Feature/function added
+- Bug fixed
+- Config changed
+- Refactor completed
+- Documentation updated
+
+**Commit workflow:**
+1. Complete logical change
+2. Run tests (if applicable)
+3. Commit with conventional message
+4. Continue to next task
+
+<example>
+User: "Add flow command and update docs"
+→ Edit package.json → Commit "feat(cli): add flow command"
+→ Edit README → Commit "docs: update CLI usage"
+NOT: Edit both → wait → ask user → commit all
+</example>
+
 ### After code change:
-- Write/update tests
-- Commit when tests pass
+- Write/update tests (if behavior changed)
+- Commit immediately
 - Update todos
 - Update documentation
 
@@ -84,6 +155,7 @@ NEVER workaround. Fix root causes.
 ### Starting complex task (3+ steps):
 - Write todos immediately
 - Update status as you progress
+- Commit after each completed step
 
 ### When uncertain:
 - Research (web search, existing patterns)
@@ -95,10 +167,10 @@ NEVER workaround. Fix root causes.
 - Verify progress before continuing
 
 ### Before claiming done:
-- All tests passing
+- All tests passing (if applicable)
 - Documentation current
 - All todos completed
-- Changes committed
+- All changes committed
 - No technical debt
 
 ---

package/package.json

@@ -1,10 +1,11 @@
 {
 	"name": "@sylphx/flow",
-	"version": "2.1.11",
+	"version": "2.2.0",
 	"description": "One CLI to rule them all. Unified orchestration layer for Claude Code, OpenCode, Cursor and all AI development tools. Auto-detection, auto-installation, auto-upgrade.",
 	"type": "module",
 	"bin": {
-		"sylphx-flow": "./src/index.ts"
+		"sylphx-flow": "./src/index.ts",
+		"flow": "./src/index.ts"
 	},
 	"exports": {
 		".": {