@phuthuycoding/kanban-flow 0.3.0

package/kanban-flow/review/stacks/java.md

@@ -0,0 +1,38 @@
+# Java Review Rules
+
+## Error Handling
+- No empty `catch` blocks and no `catch (Exception e)` that swallows — handle or rethrow with cause
+- Wrapped exceptions preserve the original via the `cause` constructor — no lost stack traces
+- No `throws Exception`/`Throwable` on public APIs — declare specific exception types
+- Exceptions not used for expected control flow; `Optional`/empty results for normal absence
+
+## Null Safety & API
+- `null` never returned where `Optional` or an empty collection expresses absence
+- Nullability contracts explicit (`@Nullable`/`Objects.requireNonNull`) at public boundaries
+- `equals`/`hashCode` implemented together or via records/Lombok — never one without the other
+- Reference comparison with `equals`, never `==` on Strings or boxed types
+- Immutability preferred — `final` fields, `List.copyOf` on returns, records for value types
+
+## Resources & Concurrency
+- Try-with-resources for every `AutoCloseable` — no manual `close()` in `finally`
+- Shared mutable state guarded (locks, concurrent collections) — no unsynchronized lazy init
+- `ExecutorService` over raw `Thread`; pools are sized, named, and shut down on lifecycle end
+- Interrupted status restored (`Thread.currentThread().interrupt()`) or propagated, not swallowed
+- No `Future.get()` without a timeout on blocking waits
+
+## Security
+- JDBC via `PreparedStatement`/parameterized APIs — no string-concatenated SQL
+- No Java native deserialization (`ObjectInputStream`) of untrusted bytes
+- `Runtime.exec`/`ProcessBuilder` never interpolate user input into commands
+- File paths validated against traversal (`normalize` + root check) before access
+
+## Dependencies & Build
+- `pom.xml`/`build.gradle` changes reviewed — versions pinned, scopes correct, no unused deps
+- No SNAPSHOT versions on release branches; wrapper scripts kept consistent with the build
+- Secrets and environment config externalized — nothing sensitive in committed properties/YAML
+
+## Performance
+- No N+1 via JPA — entity graphs/`JOIN FETCH`/batch fetching for associations in loops
+- `StringBuilder` for concatenation in loops — no `+` on hot paths
+- No boxing (`Integer`/`Long`) in hot loops where primitives suffice
+- Caches and pools bounded with eviction configured — no unbounded map-as-cache

package/kanban-flow/review/stacks/node.md

@@ -0,0 +1,28 @@
+# Node.js / TypeScript Review Rules
+
+## Async & Errors
+- No floating promises — every promise is awaited, returned, or explicitly handled
+- No `.catch(() => {})` or `try/catch` that swallows errors
+- Reject with `Error` objects, never strings or bare values
+- Async work outside a request uses a dedicated context, not the request context
+
+## Module & Types
+- Imports match the module system (ESM `import` vs CJS `require`) — no mixing
+- No `any` leaks across public boundaries; narrow types at the edge
+- Serialization fields have explicit types/validators at the API boundary
+- No circular imports between modules
+
+## Dependencies & Config
+- New dependencies are justified, pinned, and reviewed (license + maintenance)
+- No secrets in code, `.env` files, or committed config
+- Config read from environment once at startup, not scattered through code
+
+## Resource & Performance
+- No sync fs/IO (`readFileSync`, `execSync`) on the request hot path
+- Streams/buffers bounded — no unbounded `readFile` of user-controlled size
+- HTTP/gRPC calls have explicit timeouts and a closed failure path
+- DB queries are parameterized; no string-interpolated SQL
+
+## Testing
+- Tests do not depend on execution order, wall-clock time, or env state
+- No `console.log` noise left in committed code — use the project logger

package/kanban-flow/review/stacks/php.md

@@ -0,0 +1,30 @@
+# PHP Review Rules
+
+## Errors & Strictness
+- `declare(strict_types=1)` at the top of every new file
+- No `@` error suppression operator and no empty `catch` blocks — handle or rethrow
+- Catch specific exception types; `Throwable` only at the application boundary handler
+- Warnings/notices treated as bugs — no reliance on implicit null-to-type coercion
+
+## Types & API
+- Parameter, return, and property types declared — no `mixed` leaking past boundaries unvalidated
+- Nullable contracts explicit (`?Type`); no silent `null` defaults where a value is required
+- Enums and `readonly` used for fixed value sets and immutable data over loose arrays
+- No `extract()`, variable-variables (`$$x`), or dynamic property access on user-controlled keys
+
+## Security
+- DB access via PDO prepared statements or ORM bindings — no string-concatenated SQL
+- Output escaped for context (`htmlspecialchars`, template autoescape) — no raw `echo` of user data
+- No `eval`, `unserialize` on untrusted input, or `include`/`require` of dynamic paths
+- Uploads validated (MIME, extension, size) and stored outside web root or under renamed files
+- CSRF tokens on state-changing requests; passwords via `password_hash`/`password_verify` only
+
+## Dependencies & Config
+- `composer.json`/`composer.lock` committed together; `composer audit` clean for new deps
+- Deploy installs with `--no-dev` — no dev-only packages reachable in production
+- Secrets and config from environment — nothing sensitive committed in `.env` or config files
+
+## Performance
+- No N+1 queries — eager loading/joins at the repository layer for loops over associations
+- No `array_merge` or string concatenation inside loops over unbounded data
+- No per-request filesystem scans or reflection recomputation in hot paths — cache at bootstrap

package/kanban-flow/review/stacks/python.md

@@ -0,0 +1,34 @@
+# Python Review Rules
+
+## Error Handling
+- No bare `except:` or `except Exception: pass` — catch specific exception types only
+- Exceptions re-raised or wrapped with `raise ... from e` preserving the original cause
+- No exceptions used for control flow where a membership check or `.get()` is clearer
+- Errors logged once at the layer with most context — no log-and-rethrow at every level
+
+## Types & API
+- Public functions have type hints; no `Any` leaking across module boundaries
+- No mutable default arguments (`def f(x=[])`) — use `None` sentinel and init in body
+- Dataclasses or typed models for structured data at boundaries, not raw dict bags
+- No `*args/**kwargs` pass-through hiding the real signature on public APIs
+
+## Concurrency
+- No blocking calls (`time.sleep`, sync HTTP) inside `async def` — use awaitable equivalents
+- Tasks/futures have a defined lifecycle — awaited, joined, or cancelled; no fire-and-forget
+- Shared state guarded by locks or confined to one task; no unguarded mutation across threads
+
+## Security
+- SQL via parameterized queries or ORM bindings — no f-string or `%`-formatted SQL
+- No `eval`/`exec`/`pickle.loads`/`yaml.load` on untrusted input (`yaml.safe_load` only)
+- Subprocess calls use arg lists with `shell=False`; no user input in shell commands
+- Secrets from env/vault only — nothing sensitive in code or committed config
+
+## Dependencies & Resources
+- Files/sockets/connections managed with `with` — no unclosed `.open()` handles
+- Lockfile committed (`requirements.txt`, `poetry.lock`, `uv.lock`) with pinned or bounded versions
+- New dependencies justified — stdlib (pathlib, itertools, dataclasses) preferred first
+
+## Performance
+- No N+1 ORM queries — `select_related`/`prefetch_related`/batched fetches
+- Membership tests in loops use `set`, not repeated `in` scans of a list
+- Unbounded inputs streamed via generators — no `read()` of user-controlled size

package/kanban-flow/review/stacks/ruby.md

@@ -0,0 +1,32 @@
+# Ruby Review Rules
+
+## Error Handling
+- No bare `rescue` or `rescue Exception` — rescue specific error classes only
+- No `rescue` that returns `nil`/`false` to hide failures — handle, wrap, or re-raise
+- `raise` uses typed error classes with context, not generic strings where a type exists
+- Cleanup in `ensure`/block forms — no manual close paths that exceptions can bypass
+
+## Rails & Data Access
+- Strong params on all mass assignment — no `params.permit!` or unfiltered `Model.new(params)`
+- No N+1 — `includes`/`preload` verified for every association rendered in a loop
+- Transactions wrap multi-write operations; uniqueness handled by constraints, not check-then-act
+- No `update_column`/`update_attribute` skipping validations without a comment justifying it
+- Migrations reversible and deploy-safe — no rename-and-drop in a single release
+
+## Code Quality
+- `rubocop` (project config) clean on changed files — inline disables carry a comment why
+- No monkey-patching core or third-party classes; refinements/wrappers where unavoidable
+- `frozen_string_literal` respected — no mutation of string literals
+- Predicate methods end in `?`; bang (`!`) reserved for raising/dangerous variants
+- `respond_to_missing?` defined alongside any `method_missing`
+
+## Security
+- No `constantize`/`send`/`public_send` on user-controlled strings — explicit allowlist dispatch
+- SQL fragments (`where`, `order`, `joins` strings) use bind params — no interpolation of input
+- `system`/backticks/`Open3` never interpolate user input into commands
+- Secrets via credentials/env — no keys in code, fixtures, or committed config
+
+## Performance
+- No `Model.all.each` on unbounded tables — `find_each`/`in_batches` for iteration
+- `pluck`/`select` used over full model instantiation when only columns are needed
+- Memoization (`||=`) only for stable values — never keyed on mutable or per-request state

package/kanban-flow/review/stacks/rust.md

@@ -0,0 +1,33 @@
+# Rust Review Rules
+
+## Error Handling
+- No `.unwrap()` / `.expect()` outside tests and `main` — propagate with `?` or map to typed errors
+- Library crates expose typed errors (`thiserror` or manual enum); `anyhow` only at the binary/application edge
+- No silently dropped `Result` — `let _ =` on a `Result` requires a comment why it is safe
+- Panics never cross the public API as a control-flow mechanism
+
+## Safety
+- `unsafe` blocks are minimal, justified by a `// SAFETY:` comment, and reviewed individually
+- No `unsafe` to work around ownership — restructure instead
+- `clippy::pedantic`-level warnings justified or fixed; `cargo clippy` and `cargo fmt --check` clean
+- No integer overflow risk on user input — use `checked_`/`saturating_` ops where values are untrusted
+
+## Ownership & API Design
+- Prefer borrowing (`&T`, `&mut T`) over `.clone()` in hot paths; clones must be justified
+- Public types own their invariants — invalid states are unrepresentable (newtypes, enums), not validated per call
+- `#[must_use]` on Results/values whose discard is a bug; `Drop` types clean up on all paths
+- No `Rc`/`RefCell`/`Arc<Mutex>` leaks into API signatures without reason — keep them internal
+
+## Concurrency
+- Shared state via `Arc<Mutex>`/`RwLock` or channels — no `static mut`, no lazy globals with mutation
+- `Send`/`Sync` bounds are correct, not circumvented; async tasks have a defined join/abort path
+- Lock scope is minimal — no `.await` while holding a `Mutex` guard (use `tokio::sync` primitives in async)
+
+## Dependencies & Code Quality
+- `Cargo.lock` committed for binaries; dependency features reviewed — no default-features pulled blindly
+- No `.unwrap()` on env/config parsing at runtime — fail fast with context at startup
+- Tests live in `#[cfg(test)]` modules or `tests/`; doc examples compile via `cargo test --doc`
+
+## Performance
+- No accidental quadratic copies — `&str` slices, iterators, `Vec::with_capacity`
+- Serialization/deserialization derives are explicit; no `serde_json::Value` bags in hot paths

package/kanban-flow/templates/phase-1-bug-report.md

@@ -0,0 +1,76 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+kind: bug
+status: pending
+severity: {severity}
+---
+
+# Bug Report
+
+## Bug Summary
+{bug_summary}
+
+## Problem Statement
+{problem_statement}
+
+## Severity
+{severity}
+
+## Environment
+{environment}
+
+## Steps to Reproduce
+1. {reproduction_step}
+
+## Actual Result
+{actual_result}
+
+## Expected Result
+{expected_result}
+
+## Scope
+### In Scope
+- {in_scope_item}
+
+### Out of Scope
+- {out_of_scope_item}
+
+## Related Feature
+
+| Field | Value |
+|---|---|
+| Feature / context | {related_feature} |
+| Existing requirement / use case | {related_docs} |
+
+Use `N/A` with a reason when no related feature can be identified.
+
+## Constraints
+- {constraint}
+
+## Assumptions
+- {assumption}
+
+## Acceptance Criteria
+- [ ] {acceptance_criterion}
+
+## Edge Cases
+- {edge_case}
+
+## Suspected Root Cause
+{suspected_root_cause}
+
+## Regression Test Strategy
+- Test Level: {test_level}
+- Tools: {test_tools}
+- Coverage Target: {coverage_target}%
+
+## Documentation Impact
+
+| Update needed? | Affected docs | Reason / intended update |
+|---|---|---|
+| {docs_update_needed} | {affected_docs} | {docs_update_reason} |
+
+## Open Questions
+- {open_question}

package/kanban-flow/templates/phase-1-spec-requirement.md

@@ -0,0 +1,67 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+kind: feature
+status: pending
+---
+
+# Spec Requirement
+
+## Feature
+{feature_name}
+
+## Objective
+{objective}
+
+## Problem Statement
+{problem_statement}
+
+## Scope
+### In Scope
+- {in_scope_item}
+
+### Out of Scope
+- {out_of_scope_item}
+
+## Actors
+- {actor}
+
+## Functional Requirements
+### FR-001
+- Requirement: {fr_001_description}
+- Priority: {priority}
+- Notes: {fr_001_notes}
+
+### FR-002
+- Requirement: {fr_002_description}
+- Priority: {priority}
+- Notes: {fr_002_notes}
+
+## Non-Functional Requirements
+- {nfr}
+
+## Main Use Cases
+- UC-001 {use_case_name_001}
+- UC-002 {use_case_name_002}
+
+## Constraints
+- {constraint}
+
+## Assumptions
+- {assumption}
+
+## Acceptance Criteria
+- [ ] {acceptance_criterion}
+
+## Edge Cases
+- {edge_case}
+
+## Open Questions
+- {open_question}
+
+## Test Strategy
+- Level: {test_level}
+- UI Tests: {ui_test_scope}
+- Tools: {test_tools}
+- Coverage Target: {coverage_target}%

package/kanban-flow/templates/phase-2-implementation-plan.md

@@ -0,0 +1,85 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+status: planning
+---
+
+# Implementation Plan
+
+## Feature
+{feature_name}
+
+## Objective
+{objective}
+
+## Implementation Scope
+### Implement Now
+- {implement_now_item}
+
+### Supporting Features
+- {supporting_feature}
+
+### Future Features
+- {future_feature}
+
+### Explicitly Not Implemented
+- {not_implemented_item}
+
+## Task Breakdown
+
+| Task | Description | Area | Dependencies | Expected output | FR / UC references |
+|---|---|---|---|---|---|
+| TASK-001 | {task_description} | {area} | {dependencies} | {expected_output} | {requirement_reference} |
+
+Add one row per task. Track execution progress separately in `tasks.md` so the approved plan remains unchanged.
+
+## Complexity
+- Level: {complexity_level}
+- Reason: {complexity_reason}
+
+## Impact Analysis
+
+| Area | Impact |
+|---|---|
+| Backend | {backend_impact} |
+| Frontend | {frontend_impact} |
+| Database | {database_impact} |
+| API | {api_impact} |
+| Infrastructure | {infrastructure_impact} |
+| Security | {security_impact} |
+| Performance | {performance_impact} |
+| Regression | {regression_impact} |
+| Dependencies | {dependencies_impact} |
+
+## Risks and Mitigation
+
+| Risk | Impact | Mitigation / rollback |
+|---|---|---|
+| {risk} | {risk_impact} | {risk_mitigation} |
+
+## Architecture Constraints
+- {architecture_constraint}
+
+## Implementation Constraints
+- {implementation_constraint}
+
+## Testing Strategy
+- Unit: {unit_strategy}
+- Integration: {integration_strategy}
+- E2E: {e2e_strategy}
+- Coverage target: >= {coverage_target}%
+
+## Documentation Impact
+- {documentation_impact}
+
+## Definition of Done
+- [ ] Implementation complete
+- [ ] Unit tests
+- [ ] Integration tests where applicable
+- [ ] Coverage meets the agreed target
+- [ ] E2E tests when required by the agreed Test Level
+- [ ] All test cases pass
+- [ ] Review passes
+- [ ] Documentation updated
+- [ ] Feature report generated

package/kanban-flow/templates/phase-2-test-case.md

@@ -0,0 +1,68 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+status: planning
+---
+
+# Test Plan
+
+Test Strategy from `phase-1-spec-requirement.md` decides the depth:
+`unit` → Unit; `unit+integration` → Unit + Integration; `full` → Unit + Integration + UI/E2E.
+
+Extend the tables and repeat `## TC-###` for every planned test. Remove unused sample rows. Counts must match the detailed cases; use `0` with a reason for excluded test types. This is the planned contract: execution outcomes belong in the testing-result report.
+
+## Feature Test Summary
+
+| Field | Value |
+|---|---|
+| Feature | {feature_name} |
+| Context | {context} |
+| Test level | {test_level} |
+| UI scope | {ui_test_scope} |
+| Tools / commands | {test_tools} |
+| Coverage target | {coverage_target}% |
+
+## Overall Case Counts
+
+| Test type | Planned | Must pass | Notes |
+|---|---:|---:|---|
+| Unit | {unit_total} | {unit_required} | {unit_scope} |
+| Integration | {integration_total} | {integration_required} | {integration_scope} |
+| UI / E2E | {e2e_total} | {e2e_required} | {e2e_scope} |
+| **Total** | **{total_cases}** | **{total_required}** | **{overall_scope}** |
+
+## Use Case Coverage Matrix
+
+| Use case | Requirement(s) | Test cases | Planned | Pass criteria |
+|---|---|---|---:|---|
+| UC-001 | FR-001 | TC-001 | {uc_001_case_count} | {uc_001_pass_criteria} |
+| UC-002 | FR-002 | TC-002 | {uc_002_case_count} | {uc_002_pass_criteria} |
+
+## Requirement Coverage Matrix
+
+| Requirement | Use case(s) | Test case(s) | Covered? | Gap / note |
+|---|---|---|---|---|
+| FR-001 | UC-001 | TC-001 | {fr_001_covered} | {fr_001_note} |
+| FR-002 | UC-002 | TC-002 | {fr_002_covered} | {fr_002_note} |
+
+## TC-001
+
+| Field | Detail |
+|---|---|
+| Test case ID | TC-001 |
+| Requirement reference | FR-001 |
+| Use case reference | UC-001 |
+| Test type | Unit / Integration / UI / E2E |
+| Priority | High / Medium / Low |
+| Preconditions | {precondition} |
+| Input | {input} |
+| Steps | See steps table below |
+| Expected outcome | {expected_outcome} |
+| Status | PENDING |
+
+### Steps
+
+| Step | Action | Expected result |
+|---|---|---|
+| 1 | {step} | {step_expected_result} |

package/kanban-flow/templates/phase-2-use-case-diagram.md

@@ -0,0 +1,18 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+status: planning
+---
+
+# Use Case Diagram
+
+```mermaid
+flowchart LR
+  A[{actor}] --> UC1[UC-001 {use_case_001_name}]
+  A --> UC2[UC-002 {use_case_002_name}]
+```
+
+- Actors: {actors}
+- Use cases: {use_cases}
+- Relationships: {relationships}

package/kanban-flow/templates/phase-2-use-case-specification.md

@@ -0,0 +1,33 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+status: planning
+---
+
+# Use Case Index
+
+Every use case is its own file under `use-cases/`. Do not write a combined narrative here.
+
+## Use Case Files
+
+| ID | Name | File | Primary Actor | Status |
+|---|---|---|---|---|
+| UC-001 | {use_case_name_001} | [UC-001](use-cases/UC-001.md) | {primary_actor_001} | planned |
+| UC-002 | {use_case_name_002} | [UC-002](use-cases/UC-002.md) | {primary_actor_002} | planned |
+
+## Use Case Coverage
+
+| UC ID | FR references | TC references | Acceptance coverage |
+|---|---|---|---|
+| UC-001 | FR-001 | TC-001 | {uc_001_coverage} |
+| UC-002 | FR-002 | TC-002 | {uc_002_coverage} |
+
+## Totals
+
+| Metric | Total |
+|---|---:|
+| Use cases | {total_use_cases} |
+| Actors | {total_actors} |
+| Functional requirements covered | {total_requirements} |
+| Test cases linked | {total_linked_test_cases} |

package/kanban-flow/templates/phase-2-use-case.md

@@ -0,0 +1,60 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+created: "{timestamp}"
+status: planning
+---
+
+# Use Case
+
+## Overview
+
+| Field | Value |
+|---|---|
+| ID | {use_case_id} |
+| Name | {use_case_name} |
+| Requirement reference | {requirement_reference} |
+| Goal | {goal} |
+| Primary actor | {primary_actor} |
+
+## Supporting Actors
+- {supporting_actor}
+
+## Preconditions
+- {precondition}
+
+## Trigger
+{trigger}
+
+## Main Flow
+
+| Step | Actor / system | Action | Outcome |
+|---|---|---|---|
+| 1 | {step_actor} | {main_flow_step} | {step_outcome} |
+
+## Alternative Flows
+### A1
+- Trigger: {alternative_trigger}
+
+| Step | Action | Outcome / return to main flow |
+|---|---|---|
+| A1.1 | {alternative_step} | {alternative_outcome} |
+
+## Exception Flows
+### E1
+
+| Trigger | Handling | Resulting state / message |
+|---|---|---|
+| {exception_trigger} | {exception_handling} | {exception_outcome} |
+
+## Postconditions
+- {postcondition}
+
+## Business Rules
+- {business_rule}
+
+## Data
+- {data_entity}: {data_description}
+
+## Acceptance Criteria
+- [ ] {acceptance_criterion}

package/kanban-flow/templates/phase-4-testing-result.md

@@ -0,0 +1,63 @@
+---
+feature: "{feature_name}"
+context: "{context}"
+tested: "{timestamp}"
+execution: "{execution_id}"
+status: BLOCKED
+---
+
+# Testing Result
+
+## Feature
+{feature_name}
+
+## Environment
+- OS: {os}
+- Runtime: {runtime}
+- Tooling: {tooling}
+
+## Execution Time
+{execution_time}
+
+## Summary
+| Metric | Result |
+|---|---:|
+| Total | {total} |
+| Passed | {passed} |
+| Failed | {failed} |
+| Rejected | {rejected} |
+| Blocked | {blocked} |
+
+## Test Results
+
+| Case / test name | Type | Status | Expected | Actual | Evidence |
+|---|---|---|---|---|---|
+| TC-001 | {test_type} | {tc_status} | {expected_outcome} | {actual_outcome} | {evidence} |
+
+Use the approved TC IDs for features; use reproduction/regression test names for bugs. Include every required test, including blocked or unexecuted tests.
+
+## Commands and Evidence
+
+| Command / tool | Exit code | Evidence / output |
+|---|---:|---|
+| {tool} | {exit_code} | {command_evidence} |
+
+## Failures and Blockers
+
+| Case / test name | Error / blocker | Impact | Next action |
+|---|---|---|---|
+| {affected_test} | {error} | {failure_impact} | {next_action} |
+
+## Coverage
+
+| Metric / scope | Target | Measured | Evidence |
+|---|---:|---:|---|
+| Overall code coverage | {coverage_target}% | {overall_coverage}% | {coverage_evidence} |
+
+Do not equate test pass rate with code coverage. Use `N/A` with a reason for an unrequired metric; required but unmeasured coverage blocks PASS.
+
+## Regression
+{regression}
+
+## Conclusion
+- {conclusion}