@jakkrichm/create-nexus-devflow 2.0.6 → 2.0.9

package/lib/starter-templates.js

@@ -0,0 +1,111 @@
+const starterTemplates = {
+  projectOverview: `# Project Overview
+
+> **DevFlow Context Source of Truth.**
+> Single AI-facing source of truth for project architecture, stack, and shipped capabilities.
+> Run \`/onboard\` (for fresh projects) or \`/adopt\` (for existing codebases) to populate this file automatically.
+
+## 1. Project Summary
+
+- **Name**: [Project Name]
+- **Description**: [One-line summary of project purpose]
+- **Primary Stack**: [Framework / Language / Runtime]
+
+## 2. Architecture & Modules
+
+- \`src/\` - Core application source code
+
+## 3. Shipped Capabilities
+
+- None recorded yet. Run \`/onboard\` or \`/adopt\` to initialize.
+`,
+
+  codingStandards: `# Coding Standards
+
+> Project conventions and rules to follow during development.
+> Run \`/onboard\` (or \`/adopt\` for existing codebases) to tune these standards to your specific stack.
+
+## Architecture and Conventions
+
+- Write clean, modular, and maintainable code with clear single responsibilities.
+- Prefer TypeScript and explicit interfaces where available.
+- Keep dependencies lean and justified.
+
+## Code Organization & Style
+
+- Structure source code following framework-native conventions.
+- Keep functions focused and avoid deeply nested logic.
+- Use consistent naming conventions (camelCase for functions/variables, PascalCase for components/types).
+
+## Error Handling & Security
+
+- Handle errors explicitly and provide meaningful error messages.
+- Never hardcode credentials, secrets, or API keys in source code.
+- Sanitize and validate all user inputs.
+
+## Testing & Quality
+
+- Follow the TDD workflow for behavior-changing code units.
+- Run tests and linting before completing features or fixes.
+`,
+
+  currentStage: `# Current DevFlow Run Status
+
+- **Active Discovery ID**: None
+- **Active Running ID**: None
+- **Current Stage**: Idle
+- **Last Completed Run**: None
+- **Last Updated**: -
+`,
+
+  findings: `# Findings Ledger
+
+> Review findings raised by \`/security-review\` or QA audits.
+> Resolved findings are tracked with durable IDs.
+
+- **Total Open P0/P1**: 0
+- **Total Tracked**: 0
+
+_No findings recorded._
+`,
+
+  aiInteraction: `# AI Interaction Guidelines for DevFlow
+
+> **DevFlow is an agentic workflow layer**, overlaying on top of scaffolded or existing codebases.
+
+## Communication & Interaction
+
+- Be concise and direct in communication.
+- Explain technical trade-offs and non-obvious design decisions briefly.
+- Always confirm before performing major refactors or destructive operations.
+- Maintain markdown-first evidence for all stage activities.
+
+## Artifact Language
+
+- Default language for user-facing artifacts and summaries is Thai (\`th\`), while code, paths, and identifiers remain in English.
+- Use exact schema headings when validators check for specific contract sections.
+
+## Output Formatting
+
+- Use GitHub-style markdown for clean scanning.
+- Use lists for steps, options, and findings.
+- Use tables for comparative matrices or stage summaries.
+- Use backticks for paths, filenames, identifiers, and CLI commands.
+
+## DevFlow Timeline Lifecycle
+
+\`\`\`text
+/00-Discover -> /10-Define -> /20-Spec -> /30-Plan -> /40-Implement -> /50-Verify -> /60-Report -> /70-Release
+\`\`\`
+
+- Run \`/00-Discover\` to explore requests under a Discovery ID.
+- Run \`/10-Define\` to set delivery boundaries and allocate Running IDs.
+- Run \`/20-Spec\` and \`/30-Plan\` to establish formal delivery specifications and execution plans.
+- Run \`/40-Implement\` for step-by-step code implementation with evidence.
+- Run \`/50-Verify\`, \`/60-Report\`, and \`/70-Release\` for quality verification, reporting, and release packaging.
+`
+};
+
+module.exports = {
+  starterTemplates
+};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jakkrichm/create-nexus-devflow",
-  "version": "2.0.6",
-  "description": "Install or update the agent-ready DevFlow 2.0 workflow layer into a scaffolded or existing project.",
+  "version": "2.0.9",
+  "description": "Installer package for Nexus-DevFlow agentic workflow layer.",
   "license": "MIT",
   "author": "Jakkrich",
   "homepage": "https://github.com/Jakkrich/nexus-devflow#readme",

package/template/.agents/skills/00-discover/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 00-discover
 
-description: Discover stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID.
+description: "[Devflow] Discover stage in DevFlow 2.0 - explore a request, route supporting inquiry, and decide whether delivery work should begin without allocating a running ID."
 argument-hint: "{title, request, or discovery-id}"
 ---
 

package/template/.agents/skills/10-define/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 10-define
 
-description: Define stage in DevFlow 2.0 - turn an approved discovery into one or more bounded delivery runs with stable scope.
+description: "[Devflow] Define stage in DevFlow 2.0 - turn an approved discovery into one or more bounded delivery runs with stable scope."
 argument-hint: "{approved discovery-id, discovery path, running-id, or run path}"
 ---
 

package/template/.agents/skills/20-spec/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 20-spec
 
-description: Spec stage in DevFlow 2.0 - write the formal markdown-first specification from a stable definition.
+description: "[Devflow] Spec stage in DevFlow 2.0 - write the formal markdown-first specification from a stable definition."
 argument-hint: "{running-id or workspace path}"
 ---
 

package/template/.agents/skills/30-plan/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 30-plan
 
-description: Plan implementation in DevFlow 2.0 - transform `20-spec.md` into a markdown-first executable plan.
+description: "[Devflow] Plan stage in DevFlow 2.0 - transform 20-spec.md into an executable task breakdown with test decisions."
 ---
 # Phase 30: Plan Implementation
 

package/template/.agents/skills/40-implement/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 40-implement
 
-description: Implement code in DevFlow 2.0 - execute one planned unit at a time with markdown-first implementation evidence.
+description: "[Devflow] Implement stage in DevFlow 2.0 - execute planned tasks incrementally with evidence and unit tests."
 ---
 # Phase 40: Implement Code
 

package/template/.agents/skills/50-verify/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 50-verify
 
-description: Verify quality in DevFlow 2.0 - perform senior QA review, record evidence, and decide pass or return-to-implement.
+description: "[Devflow] Verify stage in DevFlow 2.0 - perform senior QA review, record evidence, and decide pass or return-to-implement."
 ---
 # Phase 50: Verify Quality
 

package/template/.agents/skills/60-report/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 60-report
 
-description: Report stage in DevFlow 2.0 - produce the final standardized markdown and HTML summary for the full running flow.
+description: "[Devflow] Report stage in DevFlow 2.0 - produce standardized markdown and HTML summary report for the completed run."
 argument-hint: "{running-id or workspace path}"
 ---
 

package/template/.agents/skills/70-release/SKILL.md

@@ -1,6 +1,6 @@
 ---name: 70-release
 
-description: Release stage in DevFlow 2.0 - package verified work for delivery, merge, PR, deployment, or handoff.
+description: "[Devflow] Release stage in DevFlow 2.0 - package verified work for delivery, git merge, PR, or deployment."
 argument-hint: "{running-id or workspace path}"
 ---
 

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

@@ -0,0 +1,95 @@
+---
+name: adopt
+description: "[Devflow] Survey existing brownfield codebase and bootstrap DevFlow context files."
+---
+
+# adopt - Bootstrap Nexus-DevFlow from an Existing Codebase
+
+Where this sits in the workflow:
+
+```text
+existing codebase  ->  [adopt]  ->  project-overview + coding-standards  ->  /00-discover or /10-define
+(already has code)     (survey +    (seeded from the real code;               (first feature / refactoring
+                        interview)   shipped architecture documented)          delivery lifecycle)
+```
+
+Standard onboarding assumes a freshly scaffolded, near-empty app. That does not fit a codebase that already has thousands of lines of working code.
+
+`/adopt` is the brownfield on-ramp for Nexus-DevFlow: it reads what is already there, asks only for what the code cannot reveal (the *intent*, the *why*, and the *upcoming roadmap*), and produces the exact context files the rest of the DevFlow lifecycle expects (`project-overview.md`, `coding-standards.md`, `AGENTS.md` commands).
+
+---
+
+## Input
+
+A description of what the project is, if provided. Otherwise, inspect the repository directly. No argument is required.
+
+---
+
+## Step 0 - Confirm Brownfield Safety
+
+Inspect `devflow/context/project-overview.md` and `devflow/context/coding-standards.md`:
+
+- If they contain default placeholders or empty templates, proceed.
+- If they already hold rich, user-owned content, stop and inform the user; offer to refresh specific sections rather than overwriting existing context without confirmation.
+
+Never run a framework scaffolder (DevFlow is an overlay, never a generator).
+
+---
+
+## Step 1 - Survey the Codebase (Read-Only)
+
+Read the repository to establish the facts. Change nothing in this step:
+
+- **Stack & Tooling**: Languages, frameworks, and versions from manifest files (`package.json`, `requirements.txt`, `pyproject.toml`, `go.mod`, `Cargo.toml`, etc.). Note the active package manager from lockfiles.
+- **Commands**: Real dev, build, test, lint, and verify scripts.
+- **Conventions in Practice**: Directory layout, component naming, state management, styling, data-fetching, error handling, validation. Read what the code *actually does*.
+- **Testing Reality**: Inspect existing test suites, runners, and coverage. Be honest about test status.
+- **Shipped Capabilities & Architecture**: Inferred from routes, pages, controllers, database schemas, and entry points.
+
+Keep structured notes for generation in Step 3.
+
+---
+
+## Step 2 - Interview for Intent
+
+The code reveals *what* and *how*, but not *why* or *what next*. Ask a short set of 3-4 questions to fill the gaps:
+
+1. **Purpose & Users**: What is the core problem this project solves, and who are the target users?
+2. **Architecture Status**: Is the current structure and stack intentional, or are there legacy parts/technical debt the team wants to change or refactor?
+3. **Upcoming Roadmap**: What are the top priorities to build, fix, or refactor next?
+4. **Clarifications**: Anything the survey got wrong or missed?
+
+*(If the user already provided this context in the prompt, skip questions that are already answered).*
+
+---
+
+## Step 3 - Generate the Context Artifacts
+
+Write the baseline context files drawn from the survey (facts) and interview (intent):
+
+1. **`devflow/context/project-overview.md`**:
+   - Project Name, Purpose, and Target Users
+   - Architecture summary and directory layout
+   - Shipped capabilities and existing major modules
+   - Key technical stack components and verified commands
+   - Known technical debt or architectural focus areas
+
+2. **`devflow/context/coding-standards.md`**:
+   - Rewrite defaults to reflect the project's *actual* conventions discovered in Step 1
+   - Framework patterns, state management, error handling, styling, and test rules based on real code
+
+3. **`AGENTS.md` Commands Section**:
+   - Fill in the real dev, build, test, lint, and verify commands found during survey.
+
+---
+
+## Step 4 - Review Gate and Handoff
+
+Present the adoption summary for review:
+
+- Shipped features and architectural baseline recorded
+- Inferred conventions and coding standards
+- Available verified commands in `AGENTS.md`
+- Recommended next step:
+  - Run `00-discover` (or `/00-discover`, `$00-discover`) to explore the next major initiative or feature
+  - Run `10-define` (or `/10-define`, `$10-define`) to immediately scope a delivery run for known roadmap items

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

@@ -1,6 +1,6 @@
 ---name: agent
 
-description: Invoke Agent - Run a specialist persona on a file, folder, stage artifact, or codebase concern.
+description: "[Devflow] Invoke specialist persona or role-based agent on a target file, folder, stage artifact, or concern."
 ---
 # Phase 90: Invoke Agent
 

package/template/.agents/skills/api-and-interface-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: api-and-interface-design
-description: Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend.
+description: "[Devflow] Guides stable API and interface design. Use when designing APIs, module boundaries, or any public interface. Use when creating REST or GraphQL endpoints, defining type contracts between modules, or establishing boundaries between frontend and backend."
 ---
 
 # API and Interface Design

package/template/.agents/skills/app-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: app-builder
-description: Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents.
+description: "[Devflow] Main application building orchestrator. Creates full-stack applications from natural language requests. Determines project type, selects tech stack, coordinates agents."
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash, Agent
 ---
 

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

@@ -1,6 +1,6 @@
 ---
 name: architecture
-description: Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design.
+description: "[Devflow] Architectural decision-making framework. Requirements analysis, trade-off evaluation, ADR documentation. Use when making architecture decisions or analyzing system design."
 allowed-tools: Read, Glob, Grep
 ---
 

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

@@ -0,0 +1,175 @@
+---
+name: autopilot
+description: "[Devflow] Optional explicit mode for one bounded spec/plan/implement/verify/report pass with checkpoint commits and review packet."
+---
+
+# autopilot - Autonomous Bounded DevFlow Loop
+
+Where this sits in the workflow:
+
+```text
+/devflow  ->  [autopilot]  ->  review packet  ->  /70-release
+(where        (spec, plan,     (human review,     (package, PR,
+ are we?)      build, verify,   walkthrough)       merge with approval)
+               report)
+```
+
+Autopilot is an explicit opt-in execution skill for Nexus-DevFlow 2.0. It runs a single bounded loop across the delivery lifecycle (**`20-spec` -> `30-plan` -> `40-implement` -> `50-verify` -> `60-report`**) without requiring human confirmation between every sub-step.
+
+It does **not** replace the normal step-by-step workflow. Mainline commands (`/20-spec`, `/30-plan`, `/40-implement`, `/50-verify`, `/60-report`, `/70-release`) remain the conservative default.
+
+Do not suggest Autopilot as the default next action. Use it only when the user explicitly asks for it.
+
+The explicit Autopilot request is permission to create checkpoint commits on the feature or fix branch after passing implementation steps. It is **not** permission to merge into `main`, push to remote, deploy, publish, delete data, or run destructive actions.
+
+## Input
+
+Common forms:
+
+- **No argument**: resume the active run in `devflow/context/current-stage.md`, or target the next planned run/feature in `devflow/context/project-overview.md`.
+- **Running ID or feature name**: target that run, e.g. `/autopilot RUN-004` or `/autopilot "add user authentication"`.
+- **`fix "<issue>"`**: write and execute an ad-hoc fix run.
+- **`resume`**: continue the current active run on its existing branch.
+
+If the requested target conflicts with a run already in progress, stop and ask which one should win. Do not overwrite active stage artifacts silently.
+
+> [!IMPORTANT]
+> Rollback is intentionally excluded from Autopilot. If the request is a rollback or the stage is marked Rollback, stop and direct the user to `/rollback` and reviewed `/40-implement`. Reversing completed work requires explicit dependency and human review gates.
+
+---
+
+## Step 1 - Preflight & Safety Check
+
+Read the project state:
+
+- `AGENTS.md` & `CLAUDE.md`
+- `devflow/context/project-overview.md`
+- `devflow/context/current-stage.md`
+- `devflow/context/coding-standards.md`
+- `devflow/context/ai-interaction.md`
+- `devflow/context/findings.md`
+- git branch, status, and recent log
+
+Stop before changing files when:
+
+1. The repo is not a git repository.
+2. The working tree is dirty with uncommitted changes unrelated to this run.
+3. `current-stage.md` has an active run and the user requested a different target without resolving conflict.
+4. The task requires architectural, financial, auth, billing, or destructive decisions not documented in the context.
+
+---
+
+## Step 2 - Choose or Write Specification (`20-spec`)
+
+1. If `devflow/runs/{running-id}-{slug}/20-spec.md` already exists, resume it.
+2. If no spec exists:
+   - Ensure `10-define.md` exists with locked scope and allocated Running ID.
+   - Write `20-spec.md` following the DevFlow specification schema.
+   - Critique and red-team the spec (edge cases, unhappy paths, testable criteria).
+   - Apply fixes to the spec.
+
+---
+
+## Step 3 - Branch Setup & Implementation Plan (`30-plan`)
+
+1. **Branch Management**:
+   - Feature: `feature/{slug}-{running-id}`
+   - Fix: `fix/{slug}-{running-id}`
+   - Switch to or create the working branch. Never run Autopilot directly on `main` or `master`.
+2. **Planning**:
+   - Write `devflow/runs/{running-id}-{slug}/30-plan.md`.
+   - Seed `checklists/implementation-checklist.md` and `checklists/verification-checklist.md`.
+
+---
+
+## Step 4 - Implement in Small Increments (`40-implement`)
+
+Work through the implementation checklist in order. Each step must remain reviewable.
+
+For every subtask:
+
+1. Implement only that scoped unit.
+2. Run relevant verification (unit tests, typecheck, lint, build).
+3. If UI is involved, inspect behavior, verify console errors and network calls.
+4. Self-review diff against `coding-standards.md`.
+5. Fix issues and rerun failed checks.
+6. Mark the task checked `[x]` in `checklists/implementation-checklist.md`.
+7. **Create a Checkpoint Commit** on the feature/fix branch for the passing step:
+   ```bash
+   git add <modified-files> devflow/runs/{running-id}-{slug}/checklists/implementation-checklist.md
+   git commit -m "feat({running-id}): checkpoint <concise step description>"
+   ```
+8. Write `devflow/runs/{running-id}-{slug}/40-implement.md`.
+
+---
+
+## Step 5 - Senior QA Verification (`50-verify`)
+
+1. Execute full project verification commands:
+   - Framework integrity (`npm run check` or equivalent)
+   - Static contracts (`npm run check:static` when applicable)
+   - Project test suite (Unit tests, integration tests)
+   - Build / Package smoke tests
+2. Update `checklists/verification-checklist.md` with concrete evidence.
+3. Write `devflow/runs/{running-id}-{slug}/50-verify.md` with QA verdict (`PASS` / `FAIL`).
+
+---
+
+## Step 6 - Targeted Quality Audit & Repair
+
+Review diffs and inspect `devflow/context/findings.md`:
+
+1. **Repair confirmed P0 and P1 findings** within the current run scope.
+2. Update finding status in `devflow/context/findings.md`.
+3. Rerun verification tests after repairs.
+4. Create a checkpoint commit for the fix.
+5. If a P0/P1 finding cannot be repaired within scope or fails twice consecutively, stop immediately and report.
+
+---
+
+## Step 7 - Delivery Digest & Review Packet (`60-report`)
+
+1. Write `devflow/runs/{running-id}-{slug}/60-report.md`.
+2. Render standalone HTML dashboard `devflow/runs/{running-id}-{slug}/60-report.html` (via `md2html` or report generator).
+3. Update `devflow/context/current-stage.md` to indicate ready for `/70-release`.
+4. Stop with a concise **Review Packet Dashboard** for human approval.
+
+---
+
+## 🛑 Strict Hard Stops (Never Exceed)
+
+Stop immediately and report to the user instead of continuing when Autopilot would need to:
+
+- Commit directly to `main` or `master`, merge branches, delete branches, or force push.
+- Run `git push` to remote repositories.
+- Deploy to staging/production or publish packages to npm/registries.
+- Delete data, drop databases, or run irreversible destructive migrations.
+- Make product, business, or architecture decisions not specified in the context.
+- Continue after two failed attempts to fix the same issue (Two-attempt hard stop).
+
+---
+
+## Output Review Packet Format
+
+When Autopilot finishes successfully, output a scannable review packet:
+
+```markdown
+### 🛸 Autopilot Execution Summary: [{running-id}]
+
+- **Branch**: `{branch-name}`
+- **Target Run**: `{running-id} - {title}`
+- **Artifacts Generated**:
+  - Spec: `devflow/runs/{id}/20-spec.md`
+  - Plan: `devflow/runs/{id}/30-plan.md`
+  - Implement Evidence: `devflow/runs/{id}/40-implement.md`
+  - QA Verify Report: `devflow/runs/{id}/50-verify.md`
+  - Digest Report: `devflow/runs/{id}/60-report.md`
+  - HTML Dashboard: `devflow/runs/{id}/60-report.html`
+- **Validation & Tests**: `All Passed (Green)`
+- **Checkpoint Commits**: `{count} commits created on {branch-name}`
+- **Manual QA Walkthrough**: Run `/try {running-id}` for human review guide
+
+---
+👉 **Next Recommended Action**:
+Inspect diffs and `/try` walkthrough, then run `/70-release {running-id}` to package, merge, or create PR.
+```

package/template/.agents/skills/bash-linux/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: bash-linux
-description: Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems.
+description: "[Devflow] Bash/Linux terminal patterns. Critical commands, piping, error handling, scripting. Use when working on macOS or Linux systems."
 allowed-tools: Read, Write, Edit, Glob, Grep, Bash
 ---
 

package/template/.agents/skills/behavioral-modes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: behavioral-modes
-description: AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type.
+description: "[Devflow] AI operational modes (brainstorm, implement, debug, review, teach, ship, orchestrate). Use to adapt behavior based on task type."
 allowed-tools: Read, Glob, Grep
 ---
 

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

@@ -1,6 +1,6 @@
 ---name: brainstorm
 
-description: Structured brainstorming for projects and features. Transitional compatibility path for the Brainstorm companion command in DevFlow 2.0.
+description: "[Devflow] Structured divergent and convergent ideation for features and ideas without allocating running IDs."
 ---
 
 # Brainstorm - Structured Idea Exploration

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

@@ -0,0 +1,77 @@
+---
+name: brief
+description: "[Devflow] Read-only scope, dependency, and risk pre-briefing before speccing a run."
+---
+
+# brief - Scope, Dependency & Risk Pre-Check
+
+Where this sits in the workflow:
+
+```text
+10-define or project-overview.md  ->  [brief]  ->  /20-spec  ->  /30-plan  ->  /40-implement
+(proposed scope & context)            (read-only   (write        (break down)  (build it)
+                                      explainer)    contract)
+```
+
+This skill answers one essential question: ***"What does this upcoming feature or run actually involve before I commit to writing a full specification?"***
+
+It inspects the relevant context files and provides a concise briefing so the team can decide whether to spec it now, split it into smaller runs, reorder priorities, or clear an architectural blocker first.
+
+It is **strictly read-only 100%**. It never writes specs, creates directories, branches, or commits code.
+
+## Input
+
+- **no argument**: briefs the active run in `devflow/context/current-stage.md` (or the first planned feature in `devflow/context/project-overview.md`).
+- **running ID or feature name**: e.g. `/brief RUN-003`, `/brief "OAuth Login"`.
+- **topic / concern**: e.g. `/brief "database migration"`.
+
+If there is no active run and the overview does not list planned features, plainly report that context is needed and recommend `/00-discover` or `/10-define`.
+
+## Step 1 - Read Context (Read-Only)
+
+Gather and synthesize:
+
+1. **Active/Target Scope**: Target Running ID, `10-define.md`, or roadmap feature item.
+2. **Project Context**: `devflow/context/project-overview.md` (Data models, architecture layout, primary stack, existing shipped capabilities).
+3. **Existing Codebase State**: Inspect existing directory structures, schemas, and routes touching this feature.
+4. **Dependencies**: What previously completed runs (`devflow/runs/`) or modules must be in place first.
+
+## Step 2 - Analyze & Assess
+
+Evaluate:
+
+- **What It Is**: Core capability and user-visible or system-visible outcome.
+- **Depends On**: Required upstream models, tables, APIs, environment variables, or sibling runs.
+- **Unblocks**: Downstream features or workflows that this run enables.
+- **Touches**: Files, modules, API routes, database tables, or UI components likely to change.
+- **Estimated Size**: Small (S), Medium (M), Large (L), or Extra-Large (XL - recommend splitting in `/10-define`).
+- **Open Questions & Risks**: Ambiguous requirements, missing external APIs, or complex migrations.
+
+## Step 3 - Output Structured Briefing
+
+Produce a short, scannable briefing:
+
+```markdown
+### 📋 Feature Briefing: [Feature / Run Name]
+
+- **What**: Brief summary of the core outcome.
+- **Depends On**: Prerequisite modules, runs, or infrastructure.
+- **Unblocks**: Downstream capabilities enabled by this feature.
+- **Touches**: Anticipated files, schemas, endpoints, and UI views.
+- **Estimated Scope & Size**: `[S / M / L / XL]` (and split recommendation if XL).
+- **Key Risks & Open Questions**: Technical or product unknowns that must be settled in `/20-spec`.
+
+---
+👉 **Next Recommended Action**: `/20-spec {running-id}` (or resolve prerequisite blocker first).
+```
+
+## Rules
+
+- **Always Read-Only**: Never edit any workspace file, never allocate running IDs, never commit or execute scripts.
+- **Explain, Don't Spec**: Focus on scope, architectural dependencies, and size estimation. The formal delivery contract is the responsibility of `/20-spec`.
+- **Ground In Reality**: Trace all assertions back to `project-overview.md` or actual codebase facts. Do not invent non-existent packages or fictional architecture.
+- **Highlight Blockers Early**: Flagging a missing prerequisite before speccing is the primary value of this command.
+
+## Output Formatting
+
+Follow the project conventions in `devflow/context/ai-interaction.md`: concise, scannable markdown with bold labels and actionable bullet points.

package/template/.agents/skills/browser-testing-with-devtools/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: browser-testing-with-devtools
-description: Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP.
+description: "[Devflow] Tests in real browsers. Use when building or debugging anything that runs in a browser. Use when you need to inspect the DOM, capture console errors, analyze network requests, profile performance, or verify visual output with real runtime data via Chrome DevTools MCP."
 ---
 
 # Browser Testing with DevTools

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

@@ -1,6 +1,6 @@
 ---name: changelog
 
-description: Update CHANGELOG.md - Automatically gather changes from specs, git history, or current state to update the project changelog.
+description: "[Devflow] Update CHANGELOG.md automatically from specs, git commits, and stage report history."
 ---
 # Phase 53: Update Changelog