@cliangdev/flux-plugin 0.2.0-dev.dc5e2c4 → 0.2.0-dev.f718bcf

package/README.md

@@ -36,7 +36,7 @@ The installer automatically:
 | Command | Purpose |
 |---------|---------|
 | `/flux` | Smart entry point - shows status and guides you to the next step |
-| `/flux:prd` | Create product requirements through guided interview |
+| `/flux:prd` | Create PRDs through discovery, research, and guided writing |
 | `/flux:breakdown` | Break PRDs into epics and tasks with acceptance criteria |
 | `/flux:implement` | Implement tasks with TDD workflow |
 
@@ -143,7 +143,7 @@ Check your current version:
 
 ```bash
 rm -rf ~/.claude/commands/flux.md ~/.claude/commands/flux
-rm -rf ~/.claude/skills/agent-creator ~/.claude/skills/epic-template ~/.claude/skills/flux-orchestrator ~/.claude/skills/prd-template
+rm -rf ~/.claude/skills/agent-creator ~/.claude/skills/epic-template ~/.claude/skills/flux-orchestrator ~/.claude/skills/prd-writer
 rm -f ~/.claude/flux-version
 # Edit ~/.claude.json and remove the "flux" entry from "mcpServers"
 ```
@@ -152,7 +152,7 @@ rm -f ~/.claude/flux-version
 
 ```bash
 rm -rf .claude/commands/flux.md .claude/commands/flux
-rm -rf .claude/skills/agent-creator .claude/skills/epic-template .claude/skills/flux-orchestrator .claude/skills/prd-template
+rm -rf .claude/skills/agent-creator .claude/skills/epic-template .claude/skills/flux-orchestrator .claude/skills/prd-writer
 rm -f .claude/flux-version
 # Edit .claude.json and remove the "flux" entry from "mcpServers"
 ```

package/agents/coder.md

@@ -20,30 +20,41 @@ You receive only:
 
 This keeps your context clean for high-quality code output.
 
-## Step 1: Detect Project Type & Apply Skill
+## Step 1: Apply Project Skill
 
-Before coding, detect the project type and apply the matching skill:
+The orchestrator should provide a **Project Skill** section in your prompt with patterns to follow. If provided, strictly follow those patterns for:
+- Code structure and organization
+- Error handling conventions
+- Testing patterns
+- Naming conventions
+
+### Fallback: Discover Skill Yourself
+
+If no skill was provided in your prompt, discover and load it:
 
 ```bash
-# Check for project indicators
+# 1. Detect project type
 ls -la | head -20
+
+# 2. Check for matching skill in .claude/skills/
+ls .claude/skills/ 2>/dev/null
 ```
 
-| File Found | Project Type | Skill to Apply |
-|------------|--------------|----------------|
-| `pom.xml` | Java/Spring Boot | `springboot-patterns` |
-| `build.gradle` | Java/Gradle | `springboot-patterns` |
-| `tsconfig.json` | TypeScript | `typescript-patterns` |
-| `package.json` + `react` | React | `ui-patterns` |
-| `go.mod` | Go | Go idioms |
-| `Cargo.toml` | Rust | Rust idioms |
-| `requirements.txt` / `pyproject.toml` | Python | Python idioms |
+| File Found | Project Type | Skill Search Pattern |
+|------------|--------------|---------------------|
+| `go.mod` | Go | `golang*`, `go-*` |
+| `tsconfig.json` | TypeScript | `typescript*`, `ts-*` |
+| `pom.xml` / `build.gradle` | Java/Spring | `java*`, `spring*` |
+| `package.json` + react | React | `react*`, `ui-*` |
+| `Cargo.toml` | Rust | `rust*` |
+| `requirements.txt` | Python | `python*`, `py-*` |
 
-**Apply the skill mentally** - follow its patterns for:
-- Code structure and organization
-- Error handling conventions
-- Testing patterns
-- Naming conventions
+```bash
+# 3. Read matching skill
+cat .claude/skills/{matched-skill}/SKILL.md
+```
+
+**Apply the loaded skill patterns** - if no matching skill exists, use general best practices for that language.
 
 ## Step 2: Understand the Task
 
@@ -61,10 +72,11 @@ Acceptance Criteria:
 
 ## Step 3: Write Tests First (TDD)
 
+### 3.1 Tests for Acceptance Criteria
+
 For each `[auto]` criterion, write a failing test:
 
 ```typescript
-// Example for TypeScript
 describe('Login API', () => {
   it('returns 401 for invalid credentials', async () => {
     const response = await api.post('/login', {
@@ -82,6 +94,34 @@ describe('Login API', () => {
 });
 ```
 
+### 3.2 Tests for Critical Components
+
+Beyond acceptance criteria, also test:
+
+- **Core business logic**: Functions that make important decisions
+- **Data transformations**: Parsing, validation, mapping functions
+- **Error paths**: Edge cases and failure scenarios
+- **Integration points**: API handlers, database operations
+- **Utilities used in multiple places**: Shared helpers and utils
+
+```typescript
+describe('SessionManager', () => {
+  it('expires sessions after TTL', async () => {
+    const session = await sessionManager.create(userId);
+    await advanceTime(SESSION_TTL + 1000);
+    expect(await sessionManager.isValid(session.id)).toBe(false);
+  });
+
+  it('handles concurrent session creation', async () => {
+    const results = await Promise.all([
+      sessionManager.create(userId),
+      sessionManager.create(userId),
+    ]);
+    expect(results[0].id).not.toBe(results[1].id);
+  });
+});
+```
+
 Run tests to confirm they fail:
 ```bash
 bun test login.test.ts
@@ -103,6 +143,81 @@ Write minimal code to make tests pass:
 bun test
 ```
 
+## Code Quality Standards
+
+### Write Clean, Modular, Testable Code
+
+**Modularity**
+- Small, focused functions that do one thing well
+- Clear separation of concerns (business logic vs I/O vs presentation)
+- Dependencies injected, not hardcoded - makes testing easy
+- Extract reusable logic into well-named helper functions
+
+```typescript
+// ✅ Good: Modular, testable
+function validateCredentials(email: string, password: string): ValidationResult {
+  if (!isValidEmail(email)) return { valid: false, error: 'Invalid email' };
+  if (password.length < 8) return { valid: false, error: 'Password too short' };
+  return { valid: true };
+}
+
+async function login(credentials: Credentials, userRepo: UserRepository) {
+  const validation = validateCredentials(credentials.email, credentials.password);
+  if (!validation.valid) throw new ValidationError(validation.error);
+  return userRepo.findByEmail(credentials.email);
+}
+
+// ❌ Bad: Monolithic, hard to test
+async function login(email: string, password: string) {
+  // validation mixed with business logic mixed with database calls
+  const db = getDatabase();
+  if (!email.includes('@')) throw new Error('bad email');
+  const user = await db.query('SELECT * FROM users WHERE email = ?', [email]);
+  // ... more mixed concerns
+}
+```
+
+**Testability**
+- Pure functions where possible (same input → same output)
+- Side effects isolated and explicit
+- Avoid global state
+- Use interfaces/types for dependencies
+
+### No Unnecessary Comments
+
+Let code be self-documenting. Comments should explain **why**, not **what**.
+
+```typescript
+// ❌ Bad: Comments that restate the code
+// Check if user is admin
+if (user.role === 'admin') {
+  // Grant admin access
+  grantAdminAccess(user);
+}
+
+// ✅ Good: Code explains itself
+if (user.role === 'admin') {
+  grantAdminAccess(user);
+}
+
+// ✅ Good: Comment explains non-obvious "why"
+// Rate limit bypass for internal services to prevent cascade failures
+if (request.source === 'internal') {
+  skipRateLimit = true;
+}
+```
+
+**When to comment:**
+- Non-obvious business rules or edge cases
+- Workarounds for external bugs/limitations
+- Performance optimizations that sacrifice readability
+- Public API documentation (JSDoc for library interfaces)
+
+**Never comment:**
+- What the code does (let naming convey this)
+- Obvious operations
+- Commented-out code (delete it, git has history)
+
 ## Step 5: Handle Manual Criteria
 
 For `[manual]` criteria, add a comment or doc noting verification steps:
@@ -174,13 +289,23 @@ Needs:
 
 ## Boundaries
 
-- **DO** focus only on the assigned task
-- **DO** write tests before implementation
-- **DO** follow detected skill patterns
-- **DON'T** refactor unrelated code
-- **DON'T** add features not in acceptance criteria
-- **DON'T** skip tests for `[auto]` criteria
-- **DON'T** make commits without running tests
+**DO:**
+- Focus only on the assigned task
+- Apply project skill patterns from your prompt (or discover them from `.claude/skills/`)
+- Write tests before implementation
+- Test critical components beyond just acceptance criteria
+- Write clean, modular, testable code
+- Use clear naming that makes code self-documenting
+
+**DON'T:**
+- Ignore provided skill patterns - they contain project-specific conventions
+- Refactor unrelated code
+- Add features not in acceptance criteria
+- Skip tests for `[auto]` criteria
+- Make commits without running tests
+- Add comments that restate what code does
+- Add unnecessary JSDoc/docstrings for simple functions
+- Leave commented-out code
 
 ## Context Escalation
 

package/commands/breakdown.md

@@ -16,12 +16,26 @@ Check if arguments were provided:
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-   - If not initialized, tell user: "Run `/flux` first to initialize the project."
+1. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+   - If error with `code: "PROJECT_NOT_INITIALIZED"`, tell user: "Run `/flux` first to initialize the project." and exit.
 
-2. If no ref provided, call `query_entities` with type=prd, status=APPROVED
+2. If query successful but no approved PRDs found:
    - If no approved PRDs, tell user: "No approved PRDs found. Approve a PRD first or run `/flux:prd` to create one."
-   - If multiple approved PRDs, use AskUserQuestion to let user select which one
+   - If multiple approved PRDs, use AskUserQuestion to let user select:
+     ```json
+     {
+       "questions": [{
+         "question": "Which PRD would you like to break down?",
+         "header": "Select PRD",
+         "options": [
+           {"label": "{PRD-1 title}", "description": "{ref} - {brief description}"},
+           {"label": "{PRD-2 title}", "description": "{ref} - {brief description}"}
+         ],
+         "multiSelect": false
+       }]
+     }
+     ```
+     Note: Dynamically populate options from the query results.
 
 3. If ref provided, call `get_entity` with the ref
    - Verify status is APPROVED
@@ -78,9 +92,21 @@ Which approach do you prefer?
 
 1. Get PRD entity with `get_entity` including `include: ['epics']`
 2. Read full PRD content from `folder_path + '/prd.md'` using Read tool
-3. If PRD already has epics, inform user:
-   - "This PRD already has {count} epics. Continue adding more or start fresh?"
-   - Use AskUserQuestion with options: "Add more epics", "View existing", "Start fresh (delete existing)"
+3. If PRD already has epics, inform user and use AskUserQuestion:
+   ```json
+   {
+     "questions": [{
+       "question": "This PRD already has {count} epics. What would you like to do?",
+       "header": "Epics",
+       "options": [
+         {"label": "Add more epics", "description": "Keep existing epics and add new ones"},
+         {"label": "View existing", "description": "See current epic structure before deciding"},
+         {"label": "Start fresh", "description": "Delete existing epics and recreate from scratch"}
+       ],
+       "multiSelect": false
+     }]
+   }
+   ```
 
 ### Step 2: Analyze & Identify Epics
 
@@ -142,9 +168,20 @@ Ready to create these epics?
 ```
 
 Use AskUserQuestion only when uncertain:
-- Create all epics (Recommended)
-- Modify structure first
-- Add/remove epics
+```json
+{
+  "questions": [{
+    "question": "Ready to create these epics?",
+    "header": "Confirm",
+    "options": [
+      {"label": "Create all epics (Recommended)", "description": "Proceed with the proposed structure"},
+      {"label": "Modify structure first", "description": "Adjust epic boundaries or dependencies"},
+      {"label": "Add/remove epics", "description": "Change the number of epics"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
 
 ### Step 4: Create Epics
 

package/commands/flux.md

@@ -6,27 +6,78 @@ allowed-tools: mcp__plugin_flux_flux__*, AskUserQuestion, Read, Write
 
 # Flux Command
 
-You are the Flux orchestrator. Detect project state and guide the user to the appropriate next action.
+You are the Flux orchestrator - the main entry point for all Flux operations. Your job is to:
+1. Detect project state and guide users to the appropriate next action
+2. Route to specialized commands based on user input
+3. Provide intelligent suggestions based on workflow state
+
+## Available Commands
+
+| Command | Description |
+|---------|-------------|
+| `/flux` | Show project status and suggest next action |
+| `/flux:prd` | Create or refine PRDs through guided interview |
+| `/flux:breakdown` | Break approved PRD into dependency-ordered epics and tasks |
+| `/flux:implement` | Implement tasks with TDD workflow using specialized coding agents |
+| `/flux:linear` | Connect Flux project to Linear for issue tracking |
+
+## Subcommand Routing
+
+When user provides arguments, route to the appropriate command:
+
+| User Input | Action |
+|------------|--------|
+| `/flux` | Show status (see Main Flow) |
+| `/flux version` | Call `get_version` and display result |
+| `/flux status` | Call `render_status` with `{view: "full"}` |
+| `/flux prd` or `/flux prd ...` | Delegate to `/flux:prd` with any additional args |
+| `/flux breakdown` or `/flux breakdown ...` | Delegate to `/flux:breakdown` with any additional args |
+| `/flux implement` or `/flux implement ...` | Delegate to `/flux:implement` with any additional args |
+| `/flux linear` | Delegate to `/flux:linear` |
+| `/flux help` | Show available commands and their purposes |
+
+## Available MCP Tools
+
+These tools are available for programmatic access:
+
+**Entity Management:**
+- `create_prd`, `create_epic`, `create_task` - Create entities
+- `update_entity`, `update_status`, `delete_entity` - Modify entities
+- `get_entity`, `query_entities` - Retrieve entities
+
+**Project:**
+- `init_project` - Initialize new Flux project
+- `get_stats` - Get entity counts by status
+- `get_version` - Get plugin version
+- `render_status` - Visual project status with progress bars
+
+**Relationships:**
+- `add_dependency`, `remove_dependency` - Task/epic dependencies
+- `add_criteria`, `mark_criteria_met` - Acceptance criteria
+
+**Integration:**
+- `configure_linear` - Connect to Linear (interactive mode supported)
 
-## Subcommands
+## Main Flow
 
-- `/flux version` - Show plugin version (call `get_version`)
-- `/flux linear` - Connect to Linear (delegate to `/flux:linear`)
+### Step 0: Check for Subcommands
 
-## Main Flow
+First, check if the user provided arguments (e.g., `/flux prd`, `/flux implement FP-T1`).
+If so, route to the appropriate command as described in Subcommand Routing above.
 
-### Step 1: Get Project Context
+### Step 1: Check Project State
 
-Call `get_project_context` to check project state.
+If no subcommand, call `render_status` with `{view: "summary"}` to show current state.
 
-### Step 2: Route Based on State
+### Step 2: Route Based on Response
 
-**If `initialized: false`:**
+**If error with `code: "PROJECT_NOT_INITIALIZED"`:**
 → Guide through initialization (see Initialization Flow below)
 
-**If `initialized: true`:**
-→ Call `render_status` with `{view: "summary"}` to show current state
-→ Determine next action based on workflow state (see Workflow States)
+**If success:**
+→ Display the rendered status
+→ Analyze workflow state and suggest the most appropriate next action (see Workflow States)
+→ If multiple actions are possible, use AskUserQuestion to let user choose
 
 ## Initialization Flow
 
@@ -148,9 +199,38 @@ When determining actions:
 | 50-80% | Suggest action, wait for confirmation |
 | < 50% | Ask clarifying question |
 
+## Help Output
+
+When user runs `/flux help`, display:
+
+```
+Flux - AI-first workflow orchestration
+
+Commands:
+  /flux              Show project status and next action
+  /flux:prd          Create or refine PRDs
+  /flux:breakdown    Break PRD into epics and tasks
+  /flux:implement    Implement tasks with TDD
+  /flux:linear       Connect to Linear
+
+Shortcuts:
+  /flux prd          Same as /flux:prd
+  /flux breakdown    Same as /flux:breakdown
+  /flux implement    Same as /flux:implement
+  /flux status       Show detailed project status
+  /flux version      Show plugin version
+
+Workflow:
+  1. /flux           Initialize project (first time)
+  2. /flux:prd       Create your first PRD
+  3. /flux:breakdown Break PRD into tasks
+  4. /flux:implement Start coding with TDD
+```
+
 ## Guidelines
 
 - Use `AskUserQuestion` tool for all user choices during initialization
 - Be concise - show status and one clear next action
 - Use `render_status` for visual project overview
 - Apply confidence-based autonomy for decisions
+- When user input matches a subcommand pattern, delegate immediately without calling render_status first

package/commands/implement.md

@@ -53,8 +53,7 @@ The orchestrator resolves all refs to tasks, builds a dependency-ordered queue,
 
 ## Pre-checks
 
-1. Call `get_project_context` to ensure Flux is initialized
-2. Parse arguments and resolve to tasks:
+1. Parse arguments and resolve to tasks (if any tool returns `PROJECT_NOT_INITIALIZED` error, tell user: "Run `/flux` first to initialize the project." and exit):
    - No args: Query for next PENDING task with no blockers
    - PRD ref(s): Expand to all epics → all tasks
    - Epic ref(s): Expand to all tasks
@@ -62,8 +61,100 @@ The orchestrator resolves all refs to tasks, builds a dependency-ordered queue,
    - Mixed refs: Resolve each, deduplicate, merge
    - `tag:{name}`: Query PRDs by tag → expand all
 
+2. Git state check (REQUIRED before any implementation):
+   - Run `git status` to check for uncommitted changes
+   - If dirty working tree: Ask user whether to commit, stash, or abort
+   - Never proceed with uncommitted changes
+
 ## Workflow
 
+### Step 0: Git Branch Setup
+
+**Always start from latest main with a fresh branch.** This ensures clean PRs and avoids merge conflicts.
+
+#### 0.1 Ensure Clean State
+
+```bash
+# Check for uncommitted changes
+git status --porcelain
+```
+
+If output is non-empty, use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "You have uncommitted changes. How would you like to proceed?",
+    "header": "Git Status",
+    "options": [
+      {"label": "Commit them first", "description": "Stage and commit current changes before starting"},
+      {"label": "Stash them", "description": "Stash changes temporarily, restore after implementation"},
+      {"label": "Abort implementation", "description": "Stop here and handle changes manually"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+#### 0.2 Create Feature Branch from Latest Main
+
+```bash
+# Fetch latest and create branch
+git fetch origin main
+git checkout -b {branch-name} origin/main
+```
+
+#### 0.3 Branch Naming Convention
+
+| Scope | Branch Name | Example |
+|-------|-------------|---------|
+| `tag:xxx` | `feat/tag-{tag}` | `feat/tag-phase-3` |
+| Single PRD | `feat/{prd-ref}` | `feat/FLUX-P3` |
+| Multiple PRDs | `feat/{first-prd-ref}` | `feat/FLUX-P3` |
+| Single Epic | `feat/{epic-ref}` | `feat/FLUX-E14` |
+| Multiple Epics | `feat/{first-epic-ref}` | `feat/FLUX-E14` |
+| Single Task | `feat/{task-ref}` | `feat/FLUX-T31` |
+| Multiple Tasks | `feat/{first-task-ref}` | `feat/FLUX-T31` |
+| No args (next task) | `feat/{task-ref}` | `feat/FLUX-T42` |
+| Mixed refs | `feat/{highest-level-ref}` | `feat/FLUX-P3` (PRD > Epic > Task) |
+
+**Priority for mixed refs**: Use the highest-level entity (PRD > Epic > Task). If multiple of the same level, use the first one alphabetically.
+
+#### 0.4 Handle Existing Branch
+
+If the branch already exists:
+```bash
+# Check if branch exists
+git rev-parse --verify feat/FLUX-P3 2>/dev/null
+```
+
+If branch exists, use AskUserQuestion:
+```json
+{
+  "questions": [{
+    "question": "Branch 'feat/FLUX-P3' already exists. What would you like to do?",
+    "header": "Branch",
+    "options": [
+      {"label": "Continue on existing (Recommended)", "description": "Resume work on the existing branch"},
+      {"label": "Delete and recreate", "description": "Start fresh from latest main"},
+      {"label": "Use different name", "description": "Create a new branch with a different name"}
+    ],
+    "multiSelect": false
+  }]
+}
+```
+
+#### Example Output
+
+```
+Git Setup:
+✓ Working tree clean
+✓ Fetched origin/main
+✓ Created branch: feat/tag-phase-3
+  └── Based on: origin/main (abc1234)
+
+Ready to implement 3 PRDs (tag: phase-3)
+```
+
 ### Step 1: Gather Context
 
 Resolve all refs to a unified task list:
@@ -185,31 +276,87 @@ When spawning a coding subagent, provide this context:
 - Epic: {epic.ref} - {epic.title}
 - PRD: {prd.ref} (read if more context needed)
 
+## Project Skill (APPLY THESE PATTERNS)
+{skillContent || "No project-specific skill found. Use general best practices for this language."}
+
 ## Workflow
-1. Auto-detect project type and apply matching skill
+1. Apply the project skill patterns above (if provided)
 2. Write tests for each [auto] criterion FIRST
-3. Implement until all tests pass
-4. For [manual] criteria, document verification steps
-5. Commit with message: "{task.ref}: {brief description}"
-6. Report back: COMPLETED or BLOCKED (with reason)
+3. Write tests for critical components (business logic, data transformations, error paths)
+4. Implement until all tests pass
+5. For [manual] criteria, document verification steps
+6. Commit with message: "{task.ref}: {brief description}"
+7. Report back: COMPLETED or BLOCKED (with reason)
+
+## Code Quality Requirements
+- Write clean, modular, testable code
+- Small focused functions with clear separation of concerns
+- Inject dependencies for testability
+- NO unnecessary comments - let code be self-documenting
+- Comments only for non-obvious "why", never for "what"
+- No commented-out code
 
 ## Files to Focus On
 {relevantFiles}
 ```
 
-## Skill Auto-Detection
+**Note:** The orchestrator MUST discover and include skill content before spawning. See "Skill Discovery & Application" section above.
+
+## Skill Discovery & Application
+
+Before spawning a coding subagent, discover and load relevant project skills.
+
+### Step 1: Detect Project Type
+
+Check for project indicator files:
+
+```bash
+ls -la | head -20
+```
+
+| File Found | Project Type |
+|------------|--------------|
+| `go.mod` | Go |
+| `tsconfig.json` | TypeScript |
+| `pom.xml` / `build.gradle` | Java/Spring |
+| `package.json` + react | React |
+| `Cargo.toml` | Rust |
+| `requirements.txt` / `pyproject.toml` | Python |
+
+### Step 2: Search for Matching Skills
+
+Check `.claude/skills/` for project-specific skills:
+
+```bash
+# List available skills
+ls .claude/skills/ 2>/dev/null || echo "No skills directory"
+```
+
+**Skill matching patterns:**
+
+| Project Type | Skill Search Patterns |
+|--------------|----------------------|
+| Go | `golang*`, `go-*`, `go_*` |
+| TypeScript | `typescript*`, `ts-*`, `ts_*` |
+| Java/Spring | `java*`, `spring*`, `springboot*` |
+| React | `react*`, `ui-*`, `frontend*` |
+| Rust | `rust*` |
+| Python | `python*`, `py-*` |
+
+### Step 3: Load Skill Content
+
+If a matching skill is found, read its content:
+
+```bash
+# Read skill content
+cat .claude/skills/{skill-name}/SKILL.md
+```
 
-The coding subagent detects project type and applies matching skills:
+### Step 4: Pass Skill to Subagent
 
-| Detection | Skill | Patterns Applied |
-|-----------|-------|------------------|
-| `pom.xml` | `springboot-patterns` | DDD, transactions, Java style |
-| `tsconfig.json` | `typescript-patterns` | Async/await, typed errors |
-| `package.json` + React | `ui-patterns` | Components, Tailwind, dark mode |
-| `go.mod` | Go patterns | Error handling, interfaces |
-| `Cargo.toml` | Rust patterns | Result types, ownership |
+Include the skill content in the coding subagent prompt (see template below).
 
-Detection happens at subagent spawn time by checking project root files.
+**Important:** If no matching skill is found, the subagent falls back to general best practices for that language.
 
 ## Status Management
 
@@ -313,3 +460,5 @@ Action needed: Resolve blockers, then run `/flux:implement FP-T45`
 - **Fail fast**: Report blockers immediately
 - **One commit per task**: Keep history clean
 - **TDD always**: Tests before implementation
+- **Test critical components**: Not just acceptance criteria - test business logic, transformations, error paths
+- **Clean code**: Modular, testable, self-documenting - no unnecessary comments