@jakkrichm/create-nexus-devflow 2.0.0 → 2.0.1

package/template/.agents/skills/silent-failure-audit/SKILL.md

@@ -1,73 +1,73 @@
----
-name: silent-failure-audit
-description: Audits error handling, logging, fallbacks, and observability for silent failures. Use after adding catch blocks, fallback logic, retry handling, optional chaining, or user-facing failure paths.
----
-
-# Silent Failure Audit
-
-Use this skill to find errors that disappear, get logged without user impact, or fall back in ways that make failures hard to debug.
-
-## Core Rule
-
-Every important failure must be visible to the right audience: logged with context for maintainers, surfaced with actionable guidance for users, or intentionally propagated to a caller that can handle it.
-
-## When To Use
-
-- Code adds or changes try/catch, `.catch`, callbacks, result handling, or retry logic.
-- A fallback, default value, mock, optional chaining, or null coalescing branch could hide a failure.
-- A reviewer needs to assess whether error handling is observable and actionable.
-- A production incident involved confusing, missing, or misleading errors.
-
-## Audit Scope
-
-Review:
-
-- Empty or broad catch blocks.
-- Logs that omit operation, identifiers, input shape, or original error.
-- User-facing failures with vague or unactionable messages.
-- Fallbacks that silently substitute data or behavior.
-- Retry exhaustion paths.
-- Optional chaining or default values that mask required data.
-
-## Failure Patterns
-
-| Pattern | Severity | Why it matters |
-|---|---|---|
-| Empty catch block | Critical | The failure vanishes completely. |
-| Log and continue with no user signal | High | Operators may see logs, but users think the action worked. |
-| Silent default/null return | High | Callers cannot distinguish no data from failed data. |
-| Broad catch-all around unrelated work | High | Unexpected bugs are converted into normal control flow. |
-| Fallback without explicit visibility | Medium | Users and maintainers cannot tell degraded mode is active. |
-| Generic message only | Medium | Users cannot recover and maintainers lack breadcrumbs. |
-
-## Output Format
-
-```markdown
-## Silent Failure Audit: [Scope]
-
-### Scope
-- **Reviewing**: [PR diff / file / feature]
-- **Error handlers found**: [count]
-- **Files**: [files]
-
-### Findings
-#### [Severity] [Title]
-**Location**: `path/file.ts:45`
-**Pattern**: [Empty catch / silent fallback / generic message]
-**Problem**: [What is hidden]
-**User or operator impact**: [Concrete impact]
-**Required fix**: [Specific behavior/logging/message/propagation change]
-
-### Positive Patterns
-- `path/file.ts:88` logs operation context and surfaces an actionable user message.
-
-### Verdict
-[Pass / Needs fixes / Critical issues]
-```
-
-## Verification
-
-- Every critical or high finding identifies the hidden failure and concrete user/operator impact.
-- Required fixes preserve useful context from the original error.
-- Fallbacks are documented, observable, and intentional.
-- Passing audits mention the positive patterns that justify the pass.
+---
+name: silent-failure-audit
+description: Audits error handling, logging, fallbacks, and observability for silent failures. Use after adding catch blocks, fallback logic, retry handling, optional chaining, or user-facing failure paths.
+---
+
+# Silent Failure Audit
+
+Use this skill to find errors that disappear, get logged without user impact, or fall back in ways that make failures hard to debug.
+
+## Core Rule
+
+Every important failure must be visible to the right audience: logged with context for maintainers, surfaced with actionable guidance for users, or intentionally propagated to a caller that can handle it.
+
+## When To Use
+
+- Code adds or changes try/catch, `.catch`, callbacks, result handling, or retry logic.
+- A fallback, default value, mock, optional chaining, or null coalescing branch could hide a failure.
+- A reviewer needs to assess whether error handling is observable and actionable.
+- A production incident involved confusing, missing, or misleading errors.
+
+## Audit Scope
+
+Review:
+
+- Empty or broad catch blocks.
+- Logs that omit operation, identifiers, input shape, or original error.
+- User-facing failures with vague or unactionable messages.
+- Fallbacks that silently substitute data or behavior.
+- Retry exhaustion paths.
+- Optional chaining or default values that mask required data.
+
+## Failure Patterns
+
+| Pattern | Severity | Why it matters |
+|---|---|---|
+| Empty catch block | Critical | The failure vanishes completely. |
+| Log and continue with no user signal | High | Operators may see logs, but users think the action worked. |
+| Silent default/null return | High | Callers cannot distinguish no data from failed data. |
+| Broad catch-all around unrelated work | High | Unexpected bugs are converted into normal control flow. |
+| Fallback without explicit visibility | Medium | Users and maintainers cannot tell degraded mode is active. |
+| Generic message only | Medium | Users cannot recover and maintainers lack breadcrumbs. |
+
+## Output Format
+
+```markdown
+## Silent Failure Audit: [Scope]
+
+### Scope
+- **Reviewing**: [PR diff / file / feature]
+- **Error handlers found**: [count]
+- **Files**: [files]
+
+### Findings
+#### [Severity] [Title]
+**Location**: `path/file.ts:45`
+**Pattern**: [Empty catch / silent fallback / generic message]
+**Problem**: [What is hidden]
+**User or operator impact**: [Concrete impact]
+**Required fix**: [Specific behavior/logging/message/propagation change]
+
+### Positive Patterns
+- `path/file.ts:88` logs operation context and surfaces an actionable user message.
+
+### Verdict
+[Pass / Needs fixes / Critical issues]
+```
+
+## Verification
+
+- Every critical or high finding identifies the hidden failure and concrete user/operator impact.
+- Required fixes preserve useful context from the original error.
+- Fallbacks are documented, observable, and intentional.
+- Passing audits mention the positive patterns that justify the pass.

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

@@ -3,77 +3,77 @@ name: simplify
 description: Simplify workflow
 ---
 
----
-description: Simplify code for clarity and maintainability while preserving behavior.
----
-
-# Simplify - Code Simplification And Refactoring
-
-Invoke the `code-simplification` skill.
-
-Primary behavior already lives in:
-
-```text
-.agents/skills/code-simplification/SKILL.md
-```
-
-Treat this workflow file as a wrapper around that skill.
-
-Use this workflow when the code works but has grown harder to read, harder to change, or more general than necessary.
-
-In DevFlow 2.0, `Simplify` is a supporting implementation workflow. It usually pairs with `/40-Implement` and should end in `/50-Verify`.
-
-## Process
-
-1. Read project instructions and study local conventions.
-2. Identify the target code: recent changes unless a broader scope is specified.
-3. Understand purpose, callers, edge cases, and test coverage before touching it.
-4. Scan for simplification opportunities:
-   - deep nesting to guard clauses or extracted helpers
-   - long functions to responsibility-based splits
-   - nested ternaries to clearer control flow
-   - vague names to descriptive names
-   - duplicated logic to shared helpers
-   - dead code to removal after confirmation
-   - speculative abstraction to simpler concrete flow
-5. Inspect `.agent/resources/schemas/refactoring.template.md` before generating a report.
-6. Apply each simplification incrementally and run verification after each meaningful change.
-7. Save the refactoring report to:
-
-```text
-devflow/reports/{date}-refactoring-{slug}.md
-```
-
-8. Verify tests pass, the build succeeds, and the diff stays behavior-preserving.
-
-If tests fail after a simplification, revert that specific change and reconsider.
-
-## Output
-
-Return:
-
-- what was simplified
-- what was intentionally left alone
-- validation evidence
-- remaining risks or debt
-
-## Relationship To DevFlow 2.0
-
-- Classification: Companion command
-- Mainline status: Not a numbered stage
-- Typical entry points: `/40-Implement`, `/50-Verify`, `PR-Review`, `Agent`
-- Typical handoff targets: `/40-Implement`, `/50-Verify`, `PR-Review`
-
-## Sources
-
-- `AGENTS.md`
-- `.agents/skills/code-simplification/SKILL.md`
-- `.agent/resources/schemas/refactoring.template.md`
-- Related commands: `/40-Implement`, `/50-Verify`, `PR-Review`, `Agent`
-
-## Next Workflow Recommendation
-
-- **Primary**: `/50-Verify`
-- **Why**: simplification should finish with explicit proof that behavior did not regress
-- **Alternative**: `/40-Implement` when simplification exposed a deeper implementation change rather than a pure refactor
-
+---
+description: Simplify code for clarity and maintainability while preserving behavior.
+---
+
+# Simplify - Code Simplification And Refactoring
+
+Invoke the `code-simplification` skill.
+
+Primary behavior already lives in:
+
+```text
+.agents/skills/code-simplification/SKILL.md
+```
+
+Treat this workflow file as a wrapper around that skill.
+
+Use this workflow when the code works but has grown harder to read, harder to change, or more general than necessary.
+
+In DevFlow 2.0, `Simplify` is a supporting implementation workflow. It usually pairs with `/40-Implement` and should end in `/50-Verify`.
+
+## Process
+
+1. Read project instructions and study local conventions.
+2. Identify the target code: recent changes unless a broader scope is specified.
+3. Understand purpose, callers, edge cases, and test coverage before touching it.
+4. Scan for simplification opportunities:
+   - deep nesting to guard clauses or extracted helpers
+   - long functions to responsibility-based splits
+   - nested ternaries to clearer control flow
+   - vague names to descriptive names
+   - duplicated logic to shared helpers
+   - dead code to removal after confirmation
+   - speculative abstraction to simpler concrete flow
+5. Inspect `.agent/resources/schemas/refactoring.template.md` before generating a report.
+6. Apply each simplification incrementally and run verification after each meaningful change.
+7. Save the refactoring report to:
+
+```text
+devflow/reports/{date}-refactoring-{slug}.md
+```
+
+8. Verify tests pass, the build succeeds, and the diff stays behavior-preserving.
+
+If tests fail after a simplification, revert that specific change and reconsider.
+
+## Output
+
+Return:
+
+- what was simplified
+- what was intentionally left alone
+- validation evidence
+- remaining risks or debt
+
+## Relationship To DevFlow 2.0
+
+- Classification: Companion command
+- Mainline status: Not a numbered stage
+- Typical entry points: `/40-Implement`, `/50-Verify`, `PR-Review`, `Agent`
+- Typical handoff targets: `/40-Implement`, `/50-Verify`, `PR-Review`
+
+## Sources
+
+- `AGENTS.md`
+- `.agents/skills/code-simplification/SKILL.md`
+- `.agent/resources/schemas/refactoring.template.md`
+- Related commands: `/40-Implement`, `/50-Verify`, `PR-Review`, `Agent`
+
+## Next Workflow Recommendation
+
+- **Primary**: `/50-Verify`
+- **Why**: simplification should finish with explicit proof that behavior did not regress
+- **Alternative**: `/40-Implement` when simplification exposed a deeper implementation change rather than a pure refactor
+

package/template/.agents/skills/skill-development/SKILL.md

@@ -1,86 +1,86 @@
----
-name: skill-development
-description: Guides the creation and maintenance of agent skills. Use when building new skills or modifying existing ones to ensure they follow the PRP framework standards.
----
-
-# Skill Development (Skill Anatomy)
-
-## Overview
-
-This skill defines the standard structure and format of agent-skills skill files. It serves as the "source of truth" for creating new capabilities within the PRP framework.
-
-## When to Use
-- When contributing or creating a new skill.
-- When refactoring existing skills to match the standard.
-- When you need to understand the structural requirements of a `SKILL.md` file.
-
----
-
-## 🏗️ Skill Structure (Anatomy)
-
-Every skill lives in its own directory under `skills/`:
-
-```text
-skills/
-  skill-name/
-  ├── SKILL.md           # Required: The skill definition
-  └── supporting-file.md # Optional: Reference material loaded on demand
-```
-
-### 1. Frontmatter (Required)
-
-```yaml
----
-name: skill-name-with-hyphens
-description: Brief statement of what the skill does. Use when [specific trigger conditions].
----
-```
-
-**Rules:**
-- `name`: Lowercase, hyphen-separated. Must match the directory name.
-- `description`: Starts with what the skill does (third person), followed by trigger conditions. Maximum 1024 characters.
-
-### 2. Standard Sections
-
-A `SKILL.md` should contain these sections:
-
-| Section | Purpose |
-|:---|:---|
-| **# Skill Title** | Clear, descriptive title. |
-| **## Overview** | One-two sentences explaining what this skill does and why it matters. |
-| **## When to Use** | Triggers (symptoms/task types) and when NOT to use. |
-| **## Core Process** | The main workflow, broken into numbered steps or phases. |
-| **## Patterns/Techniques**| Detailed guidance, code examples, or templates. |
-| **## Rationalizations** | A table of excuses agents use to skip steps vs. the reality. |
-| **## Red Flags** | Signs that the skill is being violated. |
-| **## Verification** | Checklist of exit criteria with evidence requirements. |
-
----
-
-## ✍️ Writing Principles
-
-1. **Process over knowledge**: Skills are workflows, not reference docs. Focus on steps, not facts.
-2. **Specific over general**: "Run `npm test`" is better than "verify the tests".
-3. **Evidence over assumption**: Every verification checkbox requires proof (logs, output).
-4. **Anti-rationalization**: pair common agent excuses with factual counter-arguments.
-5. **Token-conscious**: If a section doesn't change agent behavior, remove it.
-
----
-
-## 🚫 Common Rationalizations
-
-| Rationalization | Reality |
-|:---|:---|
-| "This is a simple change, I can skip the spec." | Simple changes often have hidden side effects. The spec prevents regressions. |
-| "I'll add tests after the implementation." | TDD ensures the code is testable from the start and prevents "forgetting" tests. |
-| "I don't need to read the explorer findings, I know the code." | Assumed knowledge is the primary source of bugs. Always verify patterns. |
-
----
-
-## ✅ Verification Checklist
-
-- [ ] Directory name matches `name` in frontmatter.
-- [ ] `SKILL.md` is all uppercase.
-- [ ] All mandatory sections (Overview, Process, Rationalizations, Verification) are present.
-- [ ] Verification steps are objective and require evidence.
-- [ ] Language is imperative and actionable.
+---
+name: skill-development
+description: Guides the creation and maintenance of agent skills. Use when building new skills or modifying existing ones to ensure they follow the PRP framework standards.
+---
+
+# Skill Development (Skill Anatomy)
+
+## Overview
+
+This skill defines the standard structure and format of agent-skills skill files. It serves as the "source of truth" for creating new capabilities within the PRP framework.
+
+## When to Use
+- When contributing or creating a new skill.
+- When refactoring existing skills to match the standard.
+- When you need to understand the structural requirements of a `SKILL.md` file.
+
+---
+
+## 🏗️ Skill Structure (Anatomy)
+
+Every skill lives in its own directory under `skills/`:
+
+```text
+skills/
+  skill-name/
+  ├── SKILL.md           # Required: The skill definition
+  └── supporting-file.md # Optional: Reference material loaded on demand
+```
+
+### 1. Frontmatter (Required)
+
+```yaml
+---
+name: skill-name-with-hyphens
+description: Brief statement of what the skill does. Use when [specific trigger conditions].
+---
+```
+
+**Rules:**
+- `name`: Lowercase, hyphen-separated. Must match the directory name.
+- `description`: Starts with what the skill does (third person), followed by trigger conditions. Maximum 1024 characters.
+
+### 2. Standard Sections
+
+A `SKILL.md` should contain these sections:
+
+| Section | Purpose |
+|:---|:---|
+| **# Skill Title** | Clear, descriptive title. |
+| **## Overview** | One-two sentences explaining what this skill does and why it matters. |
+| **## When to Use** | Triggers (symptoms/task types) and when NOT to use. |
+| **## Core Process** | The main workflow, broken into numbered steps or phases. |
+| **## Patterns/Techniques**| Detailed guidance, code examples, or templates. |
+| **## Rationalizations** | A table of excuses agents use to skip steps vs. the reality. |
+| **## Red Flags** | Signs that the skill is being violated. |
+| **## Verification** | Checklist of exit criteria with evidence requirements. |
+
+---
+
+## ✍️ Writing Principles
+
+1. **Process over knowledge**: Skills are workflows, not reference docs. Focus on steps, not facts.
+2. **Specific over general**: "Run `npm test`" is better than "verify the tests".
+3. **Evidence over assumption**: Every verification checkbox requires proof (logs, output).
+4. **Anti-rationalization**: pair common agent excuses with factual counter-arguments.
+5. **Token-conscious**: If a section doesn't change agent behavior, remove it.
+
+---
+
+## 🚫 Common Rationalizations
+
+| Rationalization | Reality |
+|:---|:---|
+| "This is a simple change, I can skip the spec." | Simple changes often have hidden side effects. The spec prevents regressions. |
+| "I'll add tests after the implementation." | TDD ensures the code is testable from the start and prevents "forgetting" tests. |
+| "I don't need to read the explorer findings, I know the code." | Assumed knowledge is the primary source of bugs. Always verify patterns. |
+
+---
+
+## ✅ Verification Checklist
+
+- [ ] Directory name matches `name` in frontmatter.
+- [ ] `SKILL.md` is all uppercase.
+- [ ] All mandatory sections (Overview, Process, Rationalizations, Verification) are present.
+- [ ] Verification steps are objective and require evidence.
+- [ ] Language is imperative and actionable.