@curdx/flow 3.0.0 → 3.2.0

package/knowledge/karpathy-guidelines.md

@@ -1,219 +0,0 @@
-# Karpathy Guidelines — Detailed Version
-
-> Source: Andrej Karpathy's observations on X about LLM coding pitfalls. This is CurdX-Flow's L1 behavior baseline — all agents inherit from it.
->
-> Agents reference this file via `@${CLAUDE_PLUGIN_ROOT}/knowledge/karpathy-guidelines.md`.
-
----
-
-## Core Insight
-
-LLMs have 4 systemic failure modes in coding. Each can be countered with a clear principle.
-
----
-
-## Principle 1: Think Before Coding
-
-### Failure mode
-LLMs silently make wrong assumptions and execute, hiding confusion and failing to surface trade-offs.
-
-### Counter rules
-- **Explicitly state assumptions** — "I'm assuming X, Y, Z. Correct me if that's wrong."
-- **Present multiple interpretations** — "export data" could mean CSV / JSON / SQL dump. List options for the user.
-- **Push back when warranted** — tell the user when their idea is clearly off, don't blindly follow
-- **Stop when confused** — ask rather than guess
-
-### Good vs Bad
-
-**❌ Bad**:
-> User: "Export user data"
-> Agent: *directly writes code to export all users as CSV*
-
-**✓ Good**:
-> User: "Export user data"
-> Agent: "I need to confirm a few things:
-> - Export **all** users or a filtered subset?
-> - Format: CSV / JSON / SQL dump?
-> - Which fields? Should sensitive fields (email, phone) be masked?
-> - One-off script or scheduled job?"
-
-### Triggers
-
-- Task has multiple reasonable interpretations → **must** ask
-- Operation affects data → **must** confirm
-- Simple local utility script → reasonable assumptions are OK, but state them
-
----
-
-## Principle 2: Simplicity First
-
-### Failure mode
-LLMs tend to "do more than asked", producing 1000-line complex solutions instead of 100-line simple ones. Over-abstraction, premature optimization, excessive defensiveness.
-
-### Counter rules
-- **Minimize code** — write only the minimum needed for the task
-- **No features beyond the request** — if the user asks for `calculate_discount`, don't also implement `calculate_tax`
-- **No single-use abstractions** — Strategy pattern for one strategy? Just write a function
-- **No unnecessary flexibility** — don't leave hooks for "maybe future needs"
-
-### Good vs Bad
-
-**❌ Bad** (200 lines):
-```python
-class DiscountStrategy(ABC):
-    @abstractmethod
-    def calculate(self, amount): ...
-
-class PercentageDiscount(DiscountStrategy):
-    def __init__(self, percent):
-        self.percent = percent
-    def calculate(self, amount):
-        return amount * (1 - self.percent / 100)
-
-class DiscountFactory:
-    @staticmethod
-    def create(type, **kwargs):
-        if type == 'percentage':
-            return PercentageDiscount(**kwargs)
-        # ... more types ...
-
-# Usage:
-factory = DiscountFactory()
-discount = factory.create('percentage', percent=10)
-result = discount.calculate(100)
-```
-
-**✓ Good** (1 line):
-```python
-def calculate_discount(amount, percent):
-    return amount * (1 - percent / 100)
-```
-
-### When abstraction is allowed
-- 3+ real repetitions (not "imagined maybe-future")
-- Post-abstraction code is **shorter and clearer**, not more complex
-- Tests become **easier** to write, not harder
-
-### Famous quote
-> "A little copying is better than a little dependency." — Rob Pike
-
----
-
-## Principle 3: Surgical Changes
-
-### Failure mode
-While editing, AI "also" improves, refactors, reformats, and fixes lint warnings. It touches code it shouldn't.
-
-### Counter rules
-- **Only change required lines** — task says change A, only change A
-- **Match the existing style** — project uses single quotes, you use single quotes
-- **Don't delete pre-existing dead code** — unless user explicitly asks
-- **Only clean up orphan code you created** — variables you added that are unused, delete; leave others alone
-
-### Good vs Bad
-
-**Task**: "Fix the bug where email can be empty on user registration"
-
-**❌ Bad** (10 lines changed):
-```diff
-- def register(email, password):
-+ def register(email: str, password: str) -> User:
-+    """Register a new user with email validation."""
-+    if not email:
-+        raise ValueError("Email is required")
-+    if not EMAIL_REGEX.match(email):  # also added format validation
-+        raise ValueError("Invalid email format")
-+    if len(password) < 8:  # also added password length
-+        raise ValueError("Password too short")
--    user = User(email=email, password=password)
-+    user = User(email=email.lower().strip(), password=hash_password(password))  # also lowercased
-     db.save(user)
-     return user
-```
-
-**✓ Good** (2 lines changed):
-```diff
-  def register(email, password):
-+    if not email:
-+        raise ValueError("Email is required")
-     user = User(email=email, password=password)
-     db.save(user)
-     return user
-```
-
-### Why it matters
-- PR does one thing → easy to review, easy to revert, git blame stays accurate
-- Side changes introduce **untested** variations
-- Doing only what was asked → trust is built
-
-### Only exceptions
-- User explicitly says "clean up while you're at it"
-- Orphans you yourself just created
-
----
-
-## Principle 4: Goal-Driven Execution
-
-### Failure mode
-Vague instructions ("make it work", "fix authentication") lead to aimless changes. The LLM cannot autonomously decide when it's done.
-
-### Counter rules
-- **Define success criteria first** — before starting, make "done" explicit
-- **Translate into verifiable goals** — not "fix auth", but "after password change, old sessions become invalid"
-- **Test first** — write tests that express the goal; passing = done
-- **Verifiable > explainable** — show evidence, not "should work"
-
-### Good vs Bad
-
-**Vague instruction**: "Fix the authentication system"
-
-**❌ Bad**:
-> Agent: *modifies authController.js, middleware.js, session.js, user.model.js*
-> Agent: "I improved several aspects of the auth system."
-> [Later discovered: bug still exists, none of the changes are relevant]
-
-**✓ Good**:
-> Agent: "'Auth system' is too broad. Let me ask: what is the specific symptom?
-> - Login failing?
-> - Sessions expiring too fast?
-> - CSRF vulnerability?"
-> User: "After password change, old sessions still work"
-> Agent: "OK, success criteria are:
-> 1. User changes password
-> 2. All other sessions are invalidated immediately
-> 3. Verify: two browsers, A changes password, B refresh should redirect to login
->
-> I'll write this integration test first (it will fail), then find the fix."
-
-### Forbidden vocabulary (without evidence)
-
-- "should"
-- "probably"
-- "seems"
-- "done"
-- "fixed"
-
-These may only be used **with supporting evidence**. Evidence = command output / test passing / curl response / screenshot.
-
----
-
-## Integration: How to Self-Check
-
-Before emitting output, the agent asks 4 questions:
-
-1. **Think**: Where did I make an unstated assumption?
-2. **Simplicity**: Is there code beyond the task? How much can I delete?
-3. **Surgery**: Did I touch code I shouldn't have?
-4. **Goal**: What is my evidence for claiming "done"?
-
-Only output when all 4 answers are "clear and evidenced".
-
----
-
-## Trade-off Statement (Caution vs Speed)
-
-These 4 principles **reduce speed to improve accuracy**. For trivial tasks (rename a variable, write a doc) you can pragmatically skip strict flow. For complex tasks or production-affecting changes, **enforce every one**.
-
----
-
-_Source: Andrej Karpathy's observations on LLM coding pitfalls, distilled for CurdX-Flow._

package/knowledge/planning-reviews.md

@@ -1,211 +0,0 @@
-# Planning Reviews — 4-Dimension Planning Review
-
-> After design is complete and before tasks are generated, review the design from 4 independent angles. Originally from gstack.
->
-> Agents reference this via `@${CLAUDE_PLUGIN_ROOT}/knowledge/planning-reviews.md`.
-
----
-
-## Why
-
-`design.md` is produced by flow-architect, but the architect perspective has blind spots:
-- They look at "technical feasibility", not "business value"
-- They look at "architectural elegance", not "user experience"
-- They look at "current implementation", not "future maintenance"
-
-The 4 Planning Reviews **examine the same design from different angles**:
-
-```
-design.md
-  ↓ multi-perspective review
-  ├── CEO Review     business: strategy, scope, ROI
-  ├── Engineering    technical: architecture lock-in, risk
-  ├── Design Review  UX: user usability, design system
-  └── DevEx Review   maintenance: the next person who picks this up
-```
-
-Each review is dispatched independently (different agent / context) to avoid perspective convergence.
-
-Finally `/curdx-flow:spec --review=all` ties them together: runs all 4 reviews in one pass.
-
----
-
-## Review 1: CEO Review
-
-### Angle: strategy / business
-
-**Question**: Is this worth doing? Is the scope right? Could it undercut next quarter's strategy?
-
-### Checklist
-
-- [ ] **Scope is appropriate**: not too large (over-engineering), not too small (doesn't deliver value)
-- [ ] **Timeline is reasonable**: relative to the overall roadmap
-- [ ] **ROI is quantifiable**: the business value this feature brings
-- [ ] **Opportunity cost**: doing this means not doing what
-- [ ] **Strategic alignment**: does it support company OKRs / product roadmap
-- [ ] **Stakeholders**: who benefits, who is impacted
-
-### Typical findings
-
-- "This design is complete, but the MVP needs only 30%. Suggest trimming."
-- "This will take 3 months, but project XX is more urgent right now. Suggest deferring."
-- "Scope is too small — users still won't convert after it ships. Suggest extending to include Y."
-- "This decision locks us in for 2 years. Are you sure?"
-
-### Dispatch
-
-Dispatch `flow-architect` (switching perspective to CEO), or create a new agent `flow-ceo-reviewer`.
-
-Phase 5 implementation: reuse `flow-architect` with a prompt instructing "switch to CEO perspective".
-
----
-
-## Review 2: Engineering Review
-
-### Angle: technical architecture
-
-**Question**: Will this architecture work? Is it maintainable long-term? Are risks identified comprehensively?
-
-### Checklist
-
-- [ ] **Architecture lock-in**: each AD-NN has explicit trade-off notes
-- [ ] **Scalable**: what happens at 10x users / data
-- [ ] **Dependencies reasonable**: is the chosen library / service the right one
-- [ ] **Data flow diagram clear**: mermaid reflects the real flow
-- [ ] **Error paths covered**: not just the happy path
-- [ ] **Test strategy explicit**: unit / integration / E2E ratio
-- [ ] **Deployment feasible**: CI/CD / monitoring / rollback considered
-
-### Typical findings
-
-- "AD-03 picks Redis but doesn't specify the fallback on failure"
-- "Data flow diagram shows 3 services hitting DB directly — recommend adding a layer"
-- "Test strategy says 'add E2E' but doesn't specify which scenarios"
-- "Dependency library X has known performance issues (see GitHub issue #123)"
-
-### Dispatch
-
-Essentially runs `flow-architect` again — but this time not to generate the design, but to **review** it.
-
----
-
-## Review 3: Design Review
-
-### Angle: UI/UX / design system
-
-**Question**: Can users use this? Is it visually consistent? Is accessibility sufficient?
-
-### Checklist
-
-- [ ] **User flow**: main scenario completes in ≤ 3 steps
-- [ ] **Error states**: users know what to do on failure
-- [ ] **Loading states**: long operations give feedback
-- [ ] **Empty states**: no data does not mean a blank page
-- [ ] **Accessibility**: color contrast / keyboard operation / screen reader
-- [ ] **Design system**: uses existing tokens / component library, doesn't reinvent
-- [ ] **Mobile adaptation**: usable at the narrowest viewport
-- [ ] **Internationalization**: copy can be translated / RTL compatible
-
-### Typical findings
-
-- "On login failure, the user only sees an error toast that disappears — can't see the specific reason"
-- "Input has no focus ring — keyboard users don't know where they are"
-- "New Button doesn't use the project's Button component — visually inconsistent"
-- "Mobile button is < 44pt — hard to tap"
-
-### Dispatch
-
-`flow-ux-designer` switches into review mode.
-
----
-
-## Review 4: DevEx Review
-
-### Angle: the next maintainer
-
-**Question**: Can the person (maybe you) picking up this code 6 months from now get up to speed quickly?
-
-### Checklist
-
-(See the 8 dimensions in `gates/devex-gate.md`)
-
-- [ ] Clear naming
-- [ ] Intent comments
-- [ ] File structure
-- [ ] Error messages
-- [ ] Easy setup
-- [ ] Clear types
-- [ ] Tests as documentation
-- [ ] Fast dev loop
-
-### Typical findings
-
-- "Function named `doStuff(x, y)` — no idea what it does"
-- "Test named `test('calls validateEmail')` — should describe behavior"
-- "Setting up a new env requires 7 manual configuration steps — no docker / script"
-- "Error 'Failed to process' — failed how?"
-
-### Dispatch
-
-A new agent `flow-devex-reviewer`, or reuse `flow-reviewer` by passing in the devex-gate.
-
-Phase 5 implementation: reuse `flow-reviewer` + `@${CLAUDE_PLUGIN_ROOT}/gates/devex-gate.md`.
-
----
-
-## /curdx-flow:spec --review=all — Run All 4 at Once
-
-```bash
-/curdx-flow:spec --review=all
-```
-
-Workflow:
-1. In parallel (single-message multi-Agent), dispatch 4 reviews
-2. Wait for all to return
-3. Merge findings, sort by priority
-4. Present to the user for decision
-
-Output:
-```markdown
-# Auto Plan Review: <spec-name>
-
-## Summary
-- CEO Review:  3 findings
-- Engineering: 5 findings
-- Design:      2 findings
-- DevEx:       4 findings
-
-## Blockers (fix first)
-1. [Engineering] AD-03 Redis fallback missing
-2. [CEO] Scope too large (suggest MVP 30%)
-
-## Warnings
-...
-
-## Recommendations
-1. Return to /curdx-flow:spec --phase=design to fix blockers
-2. Record warnings in STATE.md, address in tasks phase
-```
-
----
-
-## When to Skip Planning Reviews
-
-- **MVP / prototype**: time-pressured, run /curdx-flow:spec --phase=tasks first, review after launch
-- **Tiny changes**: a single file < 50 lines doesn't warrant a 4-dimension review
-- **Similar work done before**: reuse prior review conclusions
-
-But for production-grade features, running through is strongly recommended.
-
----
-
-## Difference from /curdx-flow:review
-
-- **/curdx-flow:review**: review **after code is finished** — Stage 1 compliance + Stage 2 quality
-- **/curdx-flow:spec --review**: review **before code starts** — targets design.md
-
-The two don't overlap. Plan Review prevents "doing the wrong thing", Code Review ensures "the thing was done right".
-
----
-
-_source: gstack's 4 maps review system. CurdX-Flow simplifies to 4 independent commands + one aggregated command._

package/knowledge/poc-first-workflow.md

@@ -1,223 +0,0 @@
-# POC-First Workflow — 5 Phases
-
-> Step-by-step methodology for the execution phase: get it running → clean up → add tests → pass quality gates → hand off review-ready evidence.
->
-> Agents reference this file via `@${CLAUDE_PLUGIN_ROOT}/knowledge/poc-first-workflow.md`.
-
----
-
-## Core Idea
-
-**Don't scaffold, test, and optimize in the same round.** Each phase focuses on one thing.
-
-```
-Phase 1: Make It Work    → end-to-end running; hard-coding allowed
-Phase 2: Refactoring     → clean up structure, behavior unchanged
-Phase 3: Testing (TDD)   → red-green-yellow loop to backfill tests
-Phase 4: Quality Gates   → tsc + lint + test all green
-Phase 5: Evidence Handoff → verify, review, prepare PR/release evidence
-```
-
----
-
-## Phase 1: Make It Work (POC)
-
-### Goal
-Get the whole flow **end-to-end running**. The user can see output / call the API / run the command.
-
-### Allowed
-- ✓ Hard-coded constants (TODO: configurize)
-- ✓ Ignore error handling (happy path only)
-- ✓ Skip unit tests
-- ✓ Duplicate code (don't DRY yet)
-
-### Not allowed
-- ✗ Claim "done" (this is only a POC)
-- ✗ Skip end-to-end verification (must truly run)
-
-### Done criteria
-- Manual `curl` / click / call returns the expected result
-- At least one happy path scenario works end-to-end
-
-### Pitfalls
-- **Over-hardcoded** → the refactor later becomes a rewrite. Compromise: use variables at key extension points.
-- **Forgot the real implementation** → left `throw new NotImplemented`. A POC must **really** implement the core path.
-
----
-
-## Phase 2: Refactoring
-
-### Goal
-Clean up the hasty code from Phase 1. **Behavior must not change.**
-
-### Typical actions
-- Extract repeated logic into functions
-- Split "god functions" into smaller ones
-- Name things sensibly (replace Phase 1 temporary names like `doStuff` with `validateUserInput`)
-- Remove unnecessary intermediate variables
-- Apply project style (indentation, quotes, naming)
-
-### Done criteria
-- Readability visibly improves
-- Phase 1's manual test still passes when re-run
-- `git diff --stat` shows cleanup, not a rewrite
-
-### Pitfalls
-- **Slip in new features** → violates surgical-changes principle. New features go in a new phase / new task.
-- **Over-refactor** → 2 hours to polish 50 lines for "elegance". Good-enough is enough.
-
----
-
-## Phase 3: Testing (TDD red-green-yellow)
-
-### Goal
-Backfill test coverage, ensuring behavior stability and regression detection.
-
-### TDD loop
-
-```
-RED → GREEN → YELLOW → (next test)
-```
-
-#### RED: write a failing test
-```bash
-# Expect the test to be red
-npm test -- --run specific-test
-# ✗ FAIL — ReferenceError: ... is not defined
-```
-
-**Key**: you must actually see a failure. If the test goes green immediately, something's wrong with the test (it's not actually testing the core behavior).
-
-Commit: `test(scope): red - <describe the scenario being tested>`
-
-#### GREEN: minimal implementation
-Write the **least** code that makes the test pass. Forget elegance.
-
-Commit: `feat(scope): green - <implementation that satisfies the test>`
-
-#### YELLOW: refactor / clean up
-Test already passes — now tidy the implementation.
-
-Commit: `refactor(scope): yellow - <what was cleaned up>`
-
-### Test layers
-- **Unit**: pure functions, utility classes → `vitest`
-- **Integration**: inter-component, DB interactions → `vitest` + `supertest`
-- **E2E**: full user flow → `playwright` or `chrome-devtools` MCP
-
-### Coverage targets
-- Core business logic ≥ 80%
-- Utility functions 100%
-- UI components: snapshots + key interactions
-- Error paths must have tests (not just happy path)
-
-### Pitfalls
-- **Code first, tests after** → not TDD, this is post-hoc testing. Easily misses edge cases.
-- **Tests only cover happy path** → no error handling coverage; the common cause of production issues.
-- **Too much mocking** → tests disconnected from real behavior. Keep primary evidence anchored to real integrations at system boundaries.
-
----
-
-## Phase 4: Quality Gates
-
-### Goal
-Full local checks to ensure CI will be green.
-
-### Standard checks
-
-```bash
-# 1. TypeScript strict mode
-npx tsc --strict --noEmit
-
-# 2. Lint
-npx eslint src/
-
-# 3. All tests
-npm test
-
-# 4. Coverage (optional)
-npm test -- --coverage
-```
-
-### Done criteria
-Each item produces **0 errors, 0 warnings** (warnings are not tolerated since they proliferate).
-
-### Additional checks (project-dependent)
-- Security scan (npm audit / OWASP)
-- Bundle size (bundlewatch)
-- Performance baseline (benchmark)
-
-### Pitfalls
-- **`// eslint-disable` everywhere** → this hides problems, doesn't solve them. Only use with strong justification and an explanatory comment.
-- **Skip quality gate and open PR** → CI goes red, wastes reviewer time. Run locally first, then PR.
-
----
-
-## Phase 5: Evidence Handoff
-
-### Goal
-Feature is verified, reviewed, and ready for a human PR/release decision.
-
-### Steps
-
-1. **Tidy git history**
-   - One commit per task (atomic)
-   - Commit message follows conventional format
-   - Squash if there are too many WIP commits
-
-2. **Prepare PR/release evidence**
-   - Clear title (< 70 chars)
-   - Summary 3-5 lines covering why & what
-   - Include a test plan (checklist)
-   - Link spec / issue
-
-3. **Respond to review**
-   - Reply to every comment ("fixed" or "won't fix because X")
-   - Request re-review after fixes — don't change silently
-   - Push back politely when you disagree, with evidence
-
-4. **Keep CI green**
-   - Wait for CI green after every push
-   - Fix red immediately — don't pile up
-
-5. **Hand off**
-   - Squash vs merge vs rebase: per project convention
-   - Use the host project's normal PR, merge, and release process
-
-### Pitfalls
-- **PR too large** → reviewer gives up. Split anything > 500 changed lines.
-- **Empty PR description** → reviewer has no idea what they're looking at. At minimum provide a Summary.
-- **Force-push during review** → reviewer loses context. Use new commits; squash at merge time.
-
----
-
-## When to Skip Phases
-
-### Sketch mode (prototype exploration)
-- Phase 1 (POC) is enough
-- Skip Refactoring / Testing / Quality Gates
-
-### Fast mode (one-off task)
-- Only Phase 1 + Phase 5 (handoff evidence stays lightweight)
-- Suitable for: fixing a typo, adding a log, changing a constant
-
-### Standard mode (default)
-- All 5 phases
-
-### Enterprise mode
-- 5 phases + multi-agent review (flow-adversary / flow-edge-hunter) + Security gate
-
----
-
-## Relationship to the TDD Iron Rule
-
-**TDD iron rule**: "NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST"
-
-**POC-First's compromise**: Phase 1 allows skipping tests because the purpose of POC is to validate the idea, not to deliver.
-
-**Reconciliation**:
-- POC phase: allow getting things running first (feasibility check)
-- Starting at Phase 2+: revert to strict TDD
-- Newly added **production code**: must be covered by Phase 3 TDD loop
-
-The two don't conflict: POC is not production code; production code starts at Phase 2.