@jakkrichm/create-nexus-devflow 2.0.19 → 2.0.21

package/template/.agents/skills/python-patterns/SKILL.md

@@ -1,441 +0,0 @@
----
-name: python-patterns
-description: "[Devflow] Python development principles and decision-making. Framework selection, async patterns, type hints, project structure. Teaches thinking, not copying."
-allowed-tools: Read, Write, Edit, Glob, Grep
----
-
-# Python Patterns
-
-> Python development principles and decision-making for 2025.
-> **Learn to THINK, not memorize patterns.**
-
----
-
-## ⚠️ How to Use This Skill
-
-This skill teaches **decision-making principles**, not fixed code to copy.
-
-- ASK user for framework preference when unclear
-- Choose async vs sync based on CONTEXT
-- Don't default to same framework every time
-
----
-
-## 1. Framework Selection (2025)
-
-### Decision Tree
-
-```
-What are you building?
-│
-├── API-first / Microservices
-│   └── FastAPI (async, modern, fast)
-│
-├── Full-stack web / CMS / Admin
-│   └── Django (batteries-included)
-│
-├── Simple / Script / Learning
-│   └── Flask (minimal, flexible)
-│
-├── AI/ML API serving
-│   └── FastAPI (Pydantic, async, uvicorn)
-│
-└── Background workers
-    └── Celery + any framework
-```
-
-### Comparison Principles
-
-| Factor | FastAPI | Django | Flask |
-|--------|---------|--------|-------|
-| **Best for** | APIs, microservices | Full-stack, CMS | Simple, learning |
-| **Async** | Native | Django 5.0+ | Via extensions |
-| **Admin** | Manual | Built-in | Via extensions |
-| **ORM** | Choose your own | Django ORM | Choose your own |
-| **Learning curve** | Low | Medium | Low |
-
-### Selection Questions to Ask:
-1. Is this API-only or full-stack?
-2. Need admin interface?
-3. Team familiar with async?
-4. Existing infrastructure?
-
----
-
-## 2. Async vs Sync Decision
-
-### When to Use Async
-
-```
-async def is better when:
-├── I/O-bound operations (database, HTTP, file)
-├── Many concurrent connections
-├── Real-time features
-├── Microservices communication
-└── FastAPI/Starlette/Django ASGI
-
-def (sync) is better when:
-├── CPU-bound operations
-├── Simple scripts
-├── Legacy codebase
-├── Team unfamiliar with async
-└── Blocking libraries (no async version)
-```
-
-### The Golden Rule
-
-```
-I/O-bound → async (waiting for external)
-CPU-bound → sync + multiprocessing (computing)
-
-Don't:
-├── Mix sync and async carelessly
-├── Use sync libraries in async code
-└── Force async for CPU work
-```
-
-### Async Library Selection
-
-| Need | Async Library |
-|------|---------------|
-| HTTP client | httpx |
-| PostgreSQL | asyncpg |
-| Redis | aioredis / redis-py async |
-| File I/O | aiofiles |
-| Database ORM | SQLAlchemy 2.0 async, Tortoise |
-
----
-
-## 3. Type Hints Strategy
-
-### When to Type
-
-```
-Always type:
-├── Function parameters
-├── Return types
-├── Class attributes
-├── Public APIs
-
-Can skip:
-├── Local variables (let inference work)
-├── One-off scripts
-├── Tests (usually)
-```
-
-### Common Type Patterns
-
-```python
-# These are patterns, understand them:
-
-# Optional → might be None
-from typing import Optional
-def find_user(id: int) -> Optional[User]: ...
-
-# Union → one of multiple types
-def process(data: str | dict) -> None: ...
-
-# Generic collections
-def get_items() -> list[Item]: ...
-def get_mapping() -> dict[str, int]: ...
-
-# Callable
-from typing import Callable
-def apply(fn: Callable[[int], str]) -> str: ...
-```
-
-### Pydantic for Validation
-
-```
-When to use Pydantic:
-├── API request/response models
-├── Configuration/settings
-├── Data validation
-├── Serialization
-
-Benefits:
-├── Runtime validation
-├── Auto-generated JSON schema
-├── Works with FastAPI natively
-└── Clear error messages
-```
-
----
-
-## 4. Project Structure Principles
-
-### Structure Selection
-
-```
-Small project / Script:
-├── main.py
-├── utils.py
-└── requirements.txt
-
-Medium API:
-├── app/
-│   ├── __init__.py
-│   ├── main.py
-│   ├── models/
-│   ├── routes/
-│   ├── services/
-│   └── schemas/
-├── tests/
-└── pyproject.toml
-
-Large application:
-├── src/
-│   └── myapp/
-│       ├── core/
-│       ├── api/
-│       ├── services/
-│       ├── models/
-│       └── ...
-├── tests/
-└── pyproject.toml
-```
-
-### FastAPI Structure Principles
-
-```
-Organize by feature or layer:
-
-By layer:
-├── routes/ (API endpoints)
-├── services/ (business logic)
-├── models/ (database models)
-├── schemas/ (Pydantic models)
-└── dependencies/ (shared deps)
-
-By feature:
-├── users/
-│   ├── routes.py
-│   ├── service.py
-│   └── schemas.py
-└── products/
-    └── ...
-```
-
----
-
-## 5. Django Principles (2025)
-
-### Django Async (Django 5.0+)
-
-```
-Django supports async:
-├── Async views
-├── Async middleware
-├── Async ORM (limited)
-└── ASGI deployment
-
-When to use async in Django:
-├── External API calls
-├── WebSocket (Channels)
-├── High-concurrency views
-└── Background task triggering
-```
-
-### Django Best Practices
-
-```
-Model design:
-├── Fat models, thin views
-├── Use managers for common queries
-├── Abstract base classes for shared fields
-
-Views:
-├── Class-based for complex CRUD
-├── Function-based for simple endpoints
-├── Use viewsets with DRF
-
-Queries:
-├── select_related() for FKs
-├── prefetch_related() for M2M
-├── Avoid N+1 queries
-└── Use .only() for specific fields
-```
-
----
-
-## 6. FastAPI Principles
-
-### async def vs def in FastAPI
-
-```
-Use async def when:
-├── Using async database drivers
-├── Making async HTTP calls
-├── I/O-bound operations
-└── Want to handle concurrency
-
-Use def when:
-├── Blocking operations
-├── Sync database drivers
-├── CPU-bound work
-└── FastAPI runs in threadpool automatically
-```
-
-### Dependency Injection
-
-```
-Use dependencies for:
-├── Database sessions
-├── Current user / Auth
-├── Configuration
-├── Shared resources
-
-Benefits:
-├── Testability (mock dependencies)
-├── Clean separation
-├── Automatic cleanup (yield)
-```
-
-### Pydantic v2 Integration
-
-```python
-# FastAPI + Pydantic are tightly integrated:
-
-# Request validation
-@app.post("/users")
-async def create(user: UserCreate) -> UserResponse:
-    # user is already validated
-    ...
-
-# Response serialization
-# Return type becomes response schema
-```
-
----
-
-## 7. Background Tasks
-
-### Selection Guide
-
-| Solution | Best For |
-|----------|----------|
-| **BackgroundTasks** | Simple, in-process tasks |
-| **Celery** | Distributed, complex workflows |
-| **ARQ** | Async, Redis-based |
-| **RQ** | Simple Redis queue |
-| **Dramatiq** | Actor-based, simpler than Celery |
-
-### When to Use Each
-
-```
-FastAPI BackgroundTasks:
-├── Quick operations
-├── No persistence needed
-├── Fire-and-forget
-└── Same process
-
-Celery/ARQ:
-├── Long-running tasks
-├── Need retry logic
-├── Distributed workers
-├── Persistent queue
-└── Complex workflows
-```
-
----
-
-## 8. Error Handling Principles
-
-### Exception Strategy
-
-```
-In FastAPI:
-├── Create custom exception classes
-├── Register exception handlers
-├── Return consistent error format
-└── Log without exposing internals
-
-Pattern:
-├── Raise domain exceptions in services
-├── Catch and transform in handlers
-└── Client gets clean error response
-```
-
-### Error Response Philosophy
-
-```
-Include:
-├── Error code (programmatic)
-├── Message (human readable)
-├── Details (field-level when applicable)
-└── NOT stack traces (security)
-```
-
----
-
-## 9. Testing Principles
-
-### Testing Strategy
-
-| Type | Purpose | Tools |
-|------|---------|-------|
-| **Unit** | Business logic | pytest |
-| **Integration** | API endpoints | pytest + httpx/TestClient |
-| **E2E** | Full workflows | pytest + DB |
-
-### Async Testing
-
-```python
-# Use pytest-asyncio for async tests
-
-import pytest
-from httpx import AsyncClient
-
-@pytest.mark.asyncio
-async def test_endpoint():
-    async with AsyncClient(app=app, base_url="http://test") as client:
-        response = await client.get("/users")
-        assert response.status_code == 200
-```
-
-### Fixtures Strategy
-
-```
-Common fixtures:
-├── db_session → Database connection
-├── client → Test client
-├── authenticated_user → User with token
-└── sample_data → Test data setup
-```
-
----
-
-## 10. Decision Checklist
-
-Before implementing:
-
-- [ ] **Asked user about framework preference?**
-- [ ] **Chosen framework for THIS context?** (not just default)
-- [ ] **Decided async vs sync?**
-- [ ] **Planned type hint strategy?**
-- [ ] **Defined project structure?**
-- [ ] **Planned error handling?**
-- [ ] **Considered background tasks?**
-
----
-
-## 11. Anti-Patterns to Avoid
-
-### ❌ DON'T:
-- Default to Django for simple APIs (FastAPI may be better)
-- Use sync libraries in async code
-- Skip type hints for public APIs
-- Put business logic in routes/views
-- Ignore N+1 queries
-- Mix async and sync carelessly
-
-### ✅ DO:
-- Choose framework based on context
-- Ask about async requirements
-- Use Pydantic for validation
-- Separate concerns (routes → services → repos)
-- Test critical paths
-
----
-
-> **Remember**: Python patterns are about decision-making for YOUR specific context. Don't copy code—think about what serves your application best.

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

@@ -1,143 +0,0 @@
----
-name: research
-description: "[Devflow] Deep codebase or web research with source-backed citations to support discovery and spec stages."
----
-
----
-description: Codebase and evidence research. Transitional compatibility path for the Research companion command in DevFlow 2.0.
----
-
-# Research - Codebase And Evidence Exploration
-
-## Topic: $ARGUMENTS
-
-This file keeps its old numeric path for migration compatibility.
-
-In DevFlow 2.0, `Research` is a companion command, not a numbered mainline workflow. The operational behavior remains detailed so it can still function like the original research workflow.
-
-## Purpose
-
-Use `Research` to answer complex questions with code evidence, source material, and structured findings.
-
-Use it when:
-
-- facts are missing
-- source material must be collected
-- the codebase or external docs need deeper investigation
-- Discover, Define, or Spec cannot proceed confidently without evidence
-
-Use `prototype` when the fastest reliable evidence is a runnable throwaway experiment rather than more reading.
-
-Preferred DevFlow 2.0 pairing:
-
-- from `00-discover`
-- from `10-define`
-- from `20-spec`
-- from `50-verify` when validating a claim or implementation choice
-
-When invoked with a Discovery ID, link the research report to that discovery and return to `00-discover {discovery_id}` so Discover can synthesize the evidence and make the decision. Research must not allocate a Running ID.
-
----
-
-## Internal Process
-
-You are an orchestrator. Your goal is to perform deep technical or evidence research while preserving the richer research UX from the original workflow.
-
-Apply prompt addon patterns when the topic matches:
-
-| Topic | Addon pattern | Output |
-| :--- | :--- | :--- |
-| External libraries, APIs, SDKs, services | `spec_researcher` | validated integration notes with sources and implementation constraints |
-| Competitors, alternatives, market gaps | `competitor_analysis` | competitor list, pain points, differentiator opportunities |
-| Completed implementation lessons | `insight_extractor` | reusable patterns, gotchas, file insights, recommendations |
-| API/database/browser validation | `mcp_tools/*` | available validation steps for the current IDE/tooling |
-
-### Phase 1: Query Decomposition
-
-- clarify the research question
-- classify whether the work is mainly codebase research, external research, or both
-- identify the evidence needed to answer it
-
-### Phase 2: Exploration
-
-- locate relevant code with file and line references
-- trace data flows, architecture, and integration points
-- gather external documentation and source material when needed
-- prioritize "what is" over "what should be"
-
-### Phase 3: Synthesis And Documentation
-
-- summarize key findings
-- separate facts from inference
-- record constraints, risks, and unanswered questions
-- save the durable research note to disk
-
-### Phase 4: Knowledge Management
-
-- if significant patterns or durable lessons are discovered, recommend recording them in `devflow/lessons.md` or `Wiki`
-
-## Output Format
-
-Save the full research note to `devflow/research/{date}-{slug}.md`.
-
-Before generating the report:
-
-1. Inspect `.agent/resources/schemas/research.template.md`
-2. Preserve its required headings and tables
-3. Replace placeholder text with concrete evidence
-4. Re-check the output against `research.template.md`, ensure required headings remain, and remove all placeholders before completion
-
-Return a concise chat summary plus a persistent report with:
-
-```markdown
-## Research Summary: [Topic]
-
-### Question
-[What needed to be answered]
-
-### Findings
-- [Finding 1]
-- [Finding 2]
-
-### Evidence
-- [file:line, source, or doc link]
-
-### Constraints And Risks
-- [Constraint]
-
-### Open Questions
-- [Question still unanswered]
-
-### Recommended Next Step
-- [What to do with this research]
-```
-
-## Examples
-
-```text
-Research auth patterns in the current codebase
-Research Stripe webhook handling constraints
-Research competitor onboarding flows
-Research whether this API version is compatible
-```
-
-## Relationship To DevFlow 2.0
-
-- Classification: Companion command
-- Mainline status: Not a numbered stage
-- Typical entry points: `00-discover`, `10-define`, `20-spec`, `30-plan`
-- Typical handoff targets: return to the stage that asked for the evidence
-
-## Sources
-
-- `AGENTS.md`
-- `.agent/resources/schemas/research.template.md`
-- Related commands: `00-discover`, `10-define`, `20-spec`, `30-plan`, `Spec-Research`, `Agent`
-- Support skills: `prototype`, `spec-research`, `competitor-analysis`, `insight-capture`
-
-## Next Workflow Recommendation
-
-- Default: return to the stage that asked for evidence; for discovery-owned research this is `00-discover {discovery_id}`
-- Common routes: `10-define`, `20-spec`, `30-plan`, or `50-verify`
-- Alternate: `Brainstorm` if the research opens multiple strategic options
-

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

@@ -1,71 +0,0 @@
----
-name: review
-description: "[Devflow] Multi-axis code and PR review. Reviews diffs against standards, specs, correctness, security, performance, and 9arm scrutinize discipline."
----
-
-# Code Review, Quality & PR Analysis
-
-## Overview
-
-This is the comprehensive review master skill for Nexus-DevFlow. It evaluates code modifications, local diffs, branches, and pull requests across multiple dimensions before merging or releasing. Every change gets reviewed before merge — no exceptions.
-
-**The approval standard**: Approve a change when it definitely improves overall code health and satisfies the specification, even if it isn't perfect.
-
----
-
-## 1. The Scrutinize Discipline (9arm Review Pattern)
-
-Before jumping into line-by-line comments, apply the 4-step Scrutiny check:
-1. **Intent Check**: What problem is this change truly trying to solve? Is this the right problem?
-2. **Safer / Smaller Alternative**: Could this be achieved with fewer lines, zero new dependencies, or less complexity?
-3. **Runtime Path Trace**: Trace the execution path through inputs, error handling, async boundaries, and state mutations.
-4. **Precision & Evidence**: Does the code contain unproven assumptions or missing test evidence?
-
----
-
-## 2. The Five-Axis Review Framework
-
-Every review evaluates code across these 5 core axes:
-
-```text
-┌──────────────────────────────────────────────────────────┐
-│                 FIVE-AXIS CODE REVIEW                    │
-├──────────────┬───────────────────────────────────────────┤
-│ 1. Correctness│ Logic, edge cases, error paths, races     │
-│ 2. Simplicity │ Readable, concise, no dead code, DAMP/DRY │
-│ 3. Architecture│ Boundaries, dependencies, design patterns │
-│ 4. Security   │ Input validation, auth, no secrets/XSS    │
-│ 5. Performance│ No N+1 queries, async I/O, memoization    │
-└──────────────┴───────────────────────────────────────────┘
-```
-
----
-
-## 3. Review Lenses & Finding Severities
-
-Categorize all findings into actionable severities:
-
-- **P0 (Critical Blocker)**: Security vulnerability, data loss, runtime crash, broken main functionality. (Blocks `70-release`)
-- **P1 (Major Blocker)**: Spec mismatch, broken error handling, severe regression risk. (Blocks `70-release`)
-- **P2 (Normal Improvement)**: Readability, missing edge-case test, minor performance optimization.
-- **P3 (Nit / Suggestion)**: Naming polish, optional refactor, comment clarity.
-
----
-
-## 4. PR Review Process
-
-1. **Load Context**: Pin fixed point (merge-base with `main`), read spec (`20-spec.md`) and coding standards.
-2. **Review Standards vs. Spec**: Check adherence to project instructions (`AGENTS.md`) and acceptance criteria.
-3. **Validate Findings**: Ensure every finding is reproducible and points to specific files and line numbers.
-4. **Generate Report**: Save substantial review reports under:
-   ```text
-   devflow/runs/{ID}-{slug}/pr_review.md
-   ```
-
----
-
-## Relationship To DevFlow 2.0
-
-- **Classification**: Companion command & Verification support
-- **Mainline stages**: `50-verify` (QA & Code Review lane), `70-release` (Pre-merge review)
-- **Handoff**: `40-execute` (for fixes), `50-verify`, `70-release`