@jakkrichm/create-nexus-devflow 2.0.0

package/template/.agents/skills/code-simplification/SKILL.md

@@ -0,0 +1,331 @@
+---
+name: code-simplification
+description: Simplifies code for clarity. Use when refactoring code for clarity without changing behavior. Use when code works but is harder to read, maintain, or extend than it should be. Use when reviewing code that has accumulated unnecessary complexity.
+---
+
+# Code Simplification
+
+> Inspired by Anthropic's Claude Code Simplifier plugin. Adapted here as a model-agnostic, process-driven skill for any AI coding agent.
+
+## Overview
+
+Simplify code by reducing complexity while preserving exact behavior. The goal is not fewer lines — it's code that is easier to read, understand, modify, and debug. Every simplification must pass a simple test: "Would a new team member understand this faster than the original?"
+
+## When to Use
+
+- After a feature is working and tests pass, but the implementation feels heavier than it needs to be
+- During code review when readability or complexity issues are flagged
+- When you encounter deeply nested logic, long functions, or unclear names
+- When refactoring code written under time pressure
+- When consolidating related logic scattered across files
+- After merging changes that introduced duplication or inconsistency
+
+**When NOT to use:**
+
+- Code is already clean and readable — don't simplify for the sake of it
+- You don't understand what the code does yet — comprehend before you simplify
+- The code is performance-critical and the "simpler" version would be measurably slower
+- You're about to rewrite the module entirely — simplifying throwaway code wastes effort
+
+## The Five Principles
+
+### 1. Preserve Behavior Exactly
+
+Don't change what the code does — only how it expresses it. All inputs, outputs, side effects, error behavior, and edge cases must remain identical. If you're not sure a simplification preserves behavior, don't make it.
+
+```
+ASK BEFORE EVERY CHANGE:
+→ Does this produce the same output for every input?
+→ Does this maintain the same error behavior?
+→ Does this preserve the same side effects and ordering?
+→ Do all existing tests still pass without modification?
+```
+
+### 2. Follow Project Conventions
+
+Simplification means making code more consistent with the codebase, not imposing external preferences. Before simplifying:
+
+```
+1. Read CLAUDE.md / project conventions
+2. Study how neighboring code handles similar patterns
+3. Match the project's style for:
+   - Import ordering and module system
+   - Function declaration style
+   - Naming conventions
+   - Error handling patterns
+   - Type annotation depth
+```
+
+Simplification that breaks project consistency is not simplification — it's churn.
+
+### 3. Prefer Clarity Over Cleverness
+
+Explicit code is better than compact code when the compact version requires a mental pause to parse.
+
+```typescript
+// UNCLEAR: Dense ternary chain
+const label = isNew ? 'New' : isUpdated ? 'Updated' : isArchived ? 'Archived' : 'Active';
+
+// CLEAR: Readable mapping
+function getStatusLabel(item: Item): string {
+  if (item.isNew) return 'New';
+  if (item.isUpdated) return 'Updated';
+  if (item.isArchived) return 'Archived';
+  return 'Active';
+}
+```
+
+```typescript
+// UNCLEAR: Chained reduces with inline logic
+const result = items.reduce((acc, item) => ({
+  ...acc,
+  [item.id]: { ...acc[item.id], count: (acc[item.id]?.count ?? 0) + 1 }
+}), {});
+
+// CLEAR: Named intermediate step
+const countById = new Map<string, number>();
+for (const item of items) {
+  countById.set(item.id, (countById.get(item.id) ?? 0) + 1);
+}
+```
+
+### 4. Maintain Balance
+
+Simplification has a failure mode: over-simplification. Watch for these traps:
+
+- **Inlining too aggressively** — removing a helper that gave a concept a name makes the call site harder to read
+- **Combining unrelated logic** — two simple functions merged into one complex function is not simpler
+- **Removing "unnecessary" abstraction** — some abstractions exist for extensibility or testability, not complexity
+- **Optimizing for line count** — fewer lines is not the goal; easier comprehension is
+
+### 5. Scope to What Changed
+
+Default to simplifying recently modified code. Avoid drive-by refactors of unrelated code unless explicitly asked to broaden scope. Unscoped simplification creates noise in diffs and risks unintended regressions.
+
+## The Simplification Process
+
+### Step 1: Understand Before Touching (Chesterton's Fence)
+
+Before changing or removing anything, understand why it exists. This is Chesterton's Fence: if you see a fence across a road and don't understand why it's there, don't tear it down. First understand the reason, then decide if the reason still applies.
+
+```
+BEFORE SIMPLIFYING, ANSWER:
+- What is this code's responsibility?
+- What calls it? What does it call?
+- What are the edge cases and error paths?
+- Are there tests that define the expected behavior?
+- Why might it have been written this way? (Performance? Platform constraint? Historical reason?)
+- Check git blame: what was the original context for this code?
+```
+
+If you can't answer these, you're not ready to simplify. Read more context first.
+
+### Step 2: Identify Simplification Opportunities
+
+Scan for these patterns — each one is a concrete signal, not a vague smell:
+
+**Structural complexity:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Deep nesting (3+ levels) | Hard to follow control flow | Extract conditions into guard clauses or helper functions |
+| Long functions (50+ lines) | Multiple responsibilities | Split into focused functions with descriptive names |
+| Nested ternaries | Requires mental stack to parse | Replace with if/else chains, switch, or lookup objects |
+| Boolean parameter flags | `doThing(true, false, true)` | Replace with options objects or separate functions |
+| Repeated conditionals | Same `if` check in multiple places | Extract to a well-named predicate function |
+
+**Naming and readability:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Generic names | `data`, `result`, `temp`, `val`, `item` | Rename to describe the content: `userProfile`, `validationErrors` |
+| Abbreviated names | `usr`, `cfg`, `btn`, `evt` | Use full words unless the abbreviation is universal (`id`, `url`, `api`) |
+| Misleading names | Function named `get` that also mutates state | Rename to reflect actual behavior |
+| Comments explaining "what" | `// increment counter` above `count++` | Delete the comment — the code is clear enough |
+| Comments explaining "why" | `// Retry because the API is flaky under load` | Keep these — they carry intent the code can't express |
+
+**Redundancy:**
+
+| Pattern | Signal | Simplification |
+|---------|--------|----------------|
+| Duplicated logic | Same 5+ lines in multiple places | Extract to a shared function |
+| Dead code | Unreachable branches, unused variables, commented-out blocks | Remove (after confirming it's truly dead) |
+| Unnecessary abstractions | Wrapper that adds no value | Inline the wrapper, call the underlying function directly |
+| Over-engineered patterns | Factory-for-a-factory, strategy-with-one-strategy | Replace with the simple direct approach |
+| Redundant type assertions | Casting to a type that's already inferred | Remove the assertion |
+
+### Step 3: Apply Changes Incrementally
+
+Make one simplification at a time. Run tests after each change. **Submit refactoring changes separately from feature or bug fix changes.** A PR that refactors and adds a feature is two PRs — split them.
+
+```
+FOR EACH SIMPLIFICATION:
+1. Make the change
+2. Run the test suite
+3. If tests pass → commit (or continue to next simplification)
+4. If tests fail → revert and reconsider
+```
+
+Avoid batching multiple simplifications into a single untested change. If something breaks, you need to know which simplification caused it.
+
+**The Rule of 500:** If a refactoring would touch more than 500 lines, invest in automation (codemods, sed scripts, AST transforms) rather than making the changes by hand. Manual edits at that scale are error-prone and exhausting to review.
+
+### Step 4: Verify the Result
+
+After all simplifications, step back and evaluate the whole:
+
+```
+COMPARE BEFORE AND AFTER:
+- Is the simplified version genuinely easier to understand?
+- Did you introduce any new patterns inconsistent with the codebase?
+- Is the diff clean and reviewable?
+- Would a teammate approve this change?
+```
+
+If the "simplified" version is harder to understand or review, revert. Not every simplification attempt succeeds.
+
+## Language-Specific Guidance
+
+### TypeScript / JavaScript
+
+```typescript
+// SIMPLIFY: Unnecessary async wrapper
+// Before
+async function getUser(id: string): Promise<User> {
+  return await userService.findById(id);
+}
+// After
+function getUser(id: string): Promise<User> {
+  return userService.findById(id);
+}
+
+// SIMPLIFY: Verbose conditional assignment
+// Before
+let displayName: string;
+if (user.nickname) {
+  displayName = user.nickname;
+} else {
+  displayName = user.fullName;
+}
+// After
+const displayName = user.nickname || user.fullName;
+
+// SIMPLIFY: Manual array building
+// Before
+const activeUsers: User[] = [];
+for (const user of users) {
+  if (user.isActive) {
+    activeUsers.push(user);
+  }
+}
+// After
+const activeUsers = users.filter((user) => user.isActive);
+
+// SIMPLIFY: Redundant boolean return
+// Before
+function isValid(input: string): boolean {
+  if (input.length > 0 && input.length < 100) {
+    return true;
+  }
+  return false;
+}
+// After
+function isValid(input: string): boolean {
+  return input.length > 0 && input.length < 100;
+}
+```
+
+### Python
+
+```python
+# SIMPLIFY: Verbose dictionary building
+# Before
+result = {}
+for item in items:
+    result[item.id] = item.name
+# After
+result = {item.id: item.name for item in items}
+
+# SIMPLIFY: Nested conditionals with early return
+# Before
+def process(data):
+    if data is not None:
+        if data.is_valid():
+            if data.has_permission():
+                return do_work(data)
+            else:
+                raise PermissionError("No permission")
+        else:
+            raise ValueError("Invalid data")
+    else:
+        raise TypeError("Data is None")
+# After
+def process(data):
+    if data is None:
+        raise TypeError("Data is None")
+    if not data.is_valid():
+        raise ValueError("Invalid data")
+    if not data.has_permission():
+        raise PermissionError("No permission")
+    return do_work(data)
+```
+
+### React / JSX
+
+```tsx
+// SIMPLIFY: Verbose conditional rendering
+// Before
+function UserBadge({ user }: Props) {
+  if (user.isAdmin) {
+    return <Badge variant="admin">Admin</Badge>;
+  } else {
+    return <Badge variant="default">User</Badge>;
+  }
+}
+// After
+function UserBadge({ user }: Props) {
+  const variant = user.isAdmin ? 'admin' : 'default';
+  const label = user.isAdmin ? 'Admin' : 'User';
+  return <Badge variant={variant}>{label}</Badge>;
+}
+
+// SIMPLIFY: Prop drilling through intermediate components
+// Before — consider whether context or composition solves this better.
+// This is a judgment call — flag it, don't auto-refactor.
+```
+
+## Common Rationalizations
+
+| Rationalization | Reality |
+|---|---|
+| "It's working, no need to touch it" | Working code that's hard to read will be hard to fix when it breaks. Simplifying now saves time on every future change. |
+| "Fewer lines is always simpler" | A 1-line nested ternary is not simpler than a 5-line if/else. Simplicity is about comprehension speed, not line count. |
+| "I'll just quickly simplify this unrelated code too" | Unscoped simplification creates noisy diffs and risks regressions in code you didn't intend to change. Stay focused. |
+| "The types make it self-documenting" | Types document structure, not intent. A well-named function explains *why* better than a type signature explains *what*. |
+| "This abstraction might be useful later" | Don't preserve speculative abstractions. If it's not used now, it's complexity without value. Remove it and re-add when needed. |
+| "The original author must have had a reason" | Maybe. Check git blame — apply Chesterton's Fence. But accumulated complexity often has no reason; it's just the residue of iteration under pressure. |
+| "I'll refactor while adding this feature" | Separate refactoring from feature work. Mixed changes are harder to review, revert, and understand in history. |
+
+## Red Flags
+
+- Simplification that requires modifying tests to pass (you likely changed behavior)
+- "Simplified" code that is longer and harder to follow than the original
+- Renaming things to match your preferences rather than project conventions
+- Removing error handling because "it makes the code cleaner"
+- Simplifying code you don't fully understand
+- Batching many simplifications into one large, hard-to-review commit
+- Refactoring code outside the scope of the current task without being asked
+
+## Verification
+
+After completing a simplification pass:
+
+- [ ] All existing tests pass without modification
+- [ ] Build succeeds with no new warnings
+- [ ] Linter/formatter passes (no style regressions)
+- [ ] Each simplification is a reviewable, incremental change
+- [ ] The diff is clean — no unrelated changes mixed in
+- [ ] Simplified code follows project conventions (checked against CLAUDE.md or equivalent)
+- [ ] No error handling was removed or weakened
+- [ ] No dead code was left behind (unused imports, unreachable branches)
+- [ ] A teammate or review agent would approve the change as a net improvement

package/template/.agents/skills/codebase-design/DEEPENING.md

@@ -0,0 +1,24 @@
+# Deepening
+
+Use this reference when a cluster of shallow modules may need to become one deeper module.
+
+## Dependency Categories
+
+| Category | Meaning | Testing strategy |
+| :--- | :--- | :--- |
+| In-process | Pure computation or in-memory state | Test through the new interface directly. |
+| Local-substitutable | Dependency has a local test stand-in | Test the deep module with the local stand-in. |
+| Remote but owned | Internal service across a network boundary | Define a port at the seam; use production and in-memory adapters. |
+| True external | Third-party service you do not control | Inject a port and use a mock adapter at the system boundary. |
+
+## Seam Discipline
+
+- One adapter means a hypothetical seam; two adapters means a real one.
+- A deep module may have internal seams, but callers should not need to know them.
+- Do not add ports only to make tests easier when the real design does not vary there.
+
+## Testing Strategy
+
+- Replace tests of shallow internals with tests at the deepened module's interface.
+- Assert observable behavior through the interface.
+- Keep tests resilient to internal refactors.

package/template/.agents/skills/codebase-design/DESIGN-IT-TWICE.md

@@ -0,0 +1,28 @@
+# Design It Twice
+
+Use this reference when a stage needs alternative module or interface designs before committing to one.
+
+## Process
+
+1. Frame the problem space.
+   - Name constraints.
+   - Name dependencies and classify them with `DEEPENING.md`.
+   - Sketch only enough code to make the constraints concrete.
+
+2. Produce at least three different designs.
+   - Minimal interface: 1-3 entry points.
+   - Flexible interface: supports more use cases and extension.
+   - Common-case interface: makes the dominant caller trivial.
+   - Ports-and-adapters interface: use only when cross-seam dependencies justify it.
+
+3. Compare designs.
+   - Interface depth.
+   - Locality of future change.
+   - Seam placement.
+   - Test surface.
+   - Adapter strategy.
+
+4. Recommend one design.
+   - Be opinionated.
+   - Mention any useful hybrid.
+   - Record rejected alternatives only when future readers would otherwise re-open the same debate.

package/template/.agents/skills/codebase-design/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: codebase-design
+description: Shared vocabulary for designing deep modules. Use when a DevFlow stage needs module/interface design, seam placement, testability review, or architecture simplification.
+---
+
+# Codebase Design
+
+Use this support skill when `/20-Spec`, `/30-Plan`, `/40-Implement`, or `/50-Verify` needs better module shape.
+
+Design deep modules: a lot of behavior behind a small interface, placed at a clean seam, and testable through that interface. The aim is leverage for callers, locality for maintainers, and behavior-focused tests.
+
+## DevFlow Placement
+
+- `/20-Spec`: use when requirements depend on a stable module or interface contract.
+- `/30-Plan`: use when planning needs file-level architecture, seams, or dependency strategy.
+- `/40-Implement`: use when implementation reveals shallow modules or awkward test seams.
+- `/50-Verify`: use when review finds code that is hard to test, hard to change, or too spread out.
+
+## Vocabulary
+
+Use these words consistently:
+
+- **Module**: anything with an interface and an implementation.
+- **Interface**: everything a caller must know to use the module correctly, including invariants, ordering constraints, error modes, configuration, and performance characteristics.
+- **Implementation**: what sits inside the module.
+- **Depth**: leverage at the interface. A module is deep when a large amount of behavior sits behind a small interface.
+- **Seam**: a place where behavior can change without editing the caller.
+- **Adapter**: a concrete thing that satisfies an interface at a seam.
+- **Leverage**: capability callers get per unit of interface they learn.
+- **Locality**: how much change, debugging, and verification concentrate in one place.
+
+## Principles
+
+- Depth is a property of the interface, not line count.
+- The interface is the test surface.
+- One adapter means a hypothetical seam; two adapters means a real one.
+- Do not expose internal seams through the public interface just because tests use them.
+- If deleting a module removes no complexity, it is probably a pass-through.
+
+## Process
+
+1. Identify the module, callers, and behavior the active stage is trying to stabilize.
+2. Name the current interface, implementation, seams, and adapters.
+3. Ask whether the interface is smaller than the behavior it unlocks.
+4. Classify dependencies using `DEEPENING.md` when a module needs restructuring.
+5. Use `DESIGN-IT-TWICE.md` when multiple viable interface shapes exist.
+6. Record the result in the owning stage artifact. Use ADRs only for hard-to-reverse decisions.
+
+## Output
+
+Return:
+
+- current module/interface shape
+- proposed seam or interface change
+- dependency strategy
+- test surface
+- risks and rejected alternatives
+- recommended owning DevFlow stage

package/template/.agents/skills/commit/SKILL.md

@@ -0,0 +1,63 @@
+---name: commit
+
+description: Smart Commit (Git Orchestration) - Stage files intelligently and write a concise, imperative commit message according to project standards.
+---
+# ๐Ÿ’พ Smart Commit (Git Orchestration)
+
+## Target: $ARGUMENTS
+
+Stage files intelligently and write a concise, imperative commit message according to project standards.
+
+Primary behavior now lives in:
+
+```text
+.agents/skills/release-git-operations/SKILL.md
+```
+
+Treat this workflow file as a compatibility wrapper around that skill in `commit` mode.
+
+---
+
+## ๐Ÿ› ๏ธ Internal Process
+
+You are an orchestrator. Your goal is to call the specialized Git Committer agent to perform a high-quality commit.
+
+### Phase 1: Assessment & Staging
+**Call Agent**: `prp-core-git-committer`
+- Provide the target description (e.g., "all", "backend only", "staged").
+- The agent will:
+  - Check the current Git status and branch.
+  - **MANDATORY BRANCH RULE:** Use the user's current branch as-is. Do not create, switch, or checkout a branch automatically. Only create or switch branches when the user explicitly asks for that exact branch action in the current request.
+  - If the current branch appears risky for the intended commit (for example `main`/`master` or a protected branch), warn the user and ask whether they want to continue on the current branch or explicitly create/switch to another branch.
+  - Interpret your description to stage the correct files.
+  - Review the staged changes to understand the context.
+
+### Phase 2: Message Generation & Commit
+- Ensure the agent generates an imperative commit message (e.g., `feat: Add user auth`).
+- The agent will execute the commit and capture the result.
+
+### Phase 3: Result Summary
+- Verify the agent reports:
+  - Commit Hash.
+  - Final Commit Message.
+  - Statistics (Files changed, additions, deletions).
+
+---
+
+๐Ÿ“Œ **Next Step**: Run `PR` to create a Pull Request.
+
+## Relationship To DevFlow 2.0
+
+- Classification: Companion command
+- Mainline status: Release support command, not a numbered stage
+- Typical entry points: `/70-Release` after the report is aligned and release execution is ready
+- Typical handoff targets: `PR`, `Deploy`, `/70-Release`
+
+## Sources
+
+- `AGENTS.md`
+- `.agents/skills/release-git-operations/SKILL.md`
+- `.agents/skills/git-workflow-and-versioning/SKILL.md`
+- Related commands: `/70-Release`, `PR`, `Deploy`, `Merge`
+
+

package/template/.agents/skills/competitor-analysis/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: competitor-analysis
+description: Research competitors, market alternatives, user pain points, and differentiation opportunities. Use when product framing, roadmap decisions, or strategic positioning need source-backed external context.
+---
+
+# Competitor Analysis
+
+## Overview
+
+This skill gathers market context and converts it into usable product insight for PRD, Define, Spec, or Roadmap work.
+
+## When to Use
+
+- The team needs to understand competitors or substitutes
+- Product framing needs real external context
+- Roadmap decisions need evidence about gaps or opportunities
+- A feature idea needs differentiation, not just implementation detail
+
+## Process
+
+### 1. Load Product Context
+
+- read the user request, PRD, Define, Spec, or Roadmap context
+- identify target users, use case, and known alternatives
+
+### 2. Gather Evidence
+
+- find direct and indirect competitors
+- inspect public docs, reviews, forums, comparisons, issue trackers, and discussion surfaces when available
+- cite sources and separate evidence from inference
+
+### 3. Analyze Opportunities
+
+For each competitor or market segment, summarize:
+
+- positioning
+- strengths
+- recurring pain points
+- opportunity for the current project
+
+### 4. Produce Reusable Output
+
+If the result is reusable, write it under:
+
+```text
+devflow/research/{date}-{slug}-competitor-analysis.md
+```
+
+Use `.agent/resources/schemas/competitor_analysis.template.md` when saving a reusable report.
+
+### 5. Route Back
+
+- `PRD` for product framing
+- `/10-Define` for scope and decision shaping
+- `Roadmap` for prioritization
+- `/20-Spec` when a selected opportunity becomes actionable
+
+## Output
+
+Return:
+
+- competitors researched
+- market gaps
+- evidence-backed opportunities
+- source links
+- recommended return stage or command