wize-dev-kit 0.16.0 → 0.17.0

package/src/method-skills/1-analysis/wize-document-project/templates/project-overview-template.md

@@ -0,0 +1,110 @@
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: {{date}}
+last_refreshed: {{date}}
+---
+
+# {{project_name}} - Project Overview
+
+**Date:** {{date}}
+**Type:** {{project_type}}
+**Architecture:** {{architecture_type}}
+
+## Executive Summary
+
+{{executive_summary}}
+
+## Project Classification
+
+- **Repository Type:** {{repository_type}}
+- **Project Type(s):** {{project_types_list}}
+- **Primary Language(s):** {{primary_languages}}
+- **Architecture Pattern:** {{architecture_pattern}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project consists of {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+### {{part_name}}
+
+- **Type:** {{project_type}}
+- **Location:** `{{root_path}}`
+- **Purpose:** {{purpose}}
+- **Tech Stack:** {{tech_stack}}
+{{/each}}
+
+### How Parts Integrate
+
+{{integration_description}}
+{{/if}}
+
+## Technology Stack Summary
+
+{{#if is_single_part}}
+{{technology_table}}
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}} Stack
+
+{{technology_table}}
+{{/each}}
+{{/if}}
+
+## Key Features
+
+{{key_features}}
+
+## Architecture Highlights
+
+{{architecture_highlights}}
+
+## Development Overview
+
+### Prerequisites
+
+{{prerequisites}}
+
+### Getting Started
+
+{{getting_started_summary}}
+
+### Key Commands
+
+{{#if is_single_part}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+- **Build:** `{{build_command}}`
+- **Test:** `{{test_command}}`
+{{else}}
+{{#each project_parts}}
+
+#### {{part_name}}
+
+- **Install:** `{{install_command}}`
+- **Dev:** `{{dev_command}}`
+{{/each}}
+{{/if}}
+
+## Repository Structure
+
+{{repository_structure_summary}}
+
+## Documentation Map
+
+For detailed information, see:
+
+- [index.md](./index.md) - Master documentation index
+- [architecture.md](./architecture{{#if is_multi_part}}-{{part_id}}{{/if}}.md) - Detailed architecture
+- [source-tree-analysis.md](./source-tree-analysis.md) - Directory structure
+- [development-guide.md](./development-guide{{#if is_multi_part}}-{{part_id}}{{/if}}.md) - Development workflow
+
+---
+
+_Generated using Wize Dev Kit `document-project` workflow_

package/src/method-skills/1-analysis/wize-document-project/templates/project-scan-report-schema.json

@@ -0,0 +1,159 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://qwize.io/wize-dev-kit/schemas/project-scan-report.schema.json",
+  "title": "Project Scan Report",
+  "description": "State tracking file for wize-document-project resumability",
+  "type": "object",
+  "required": ["workflow_version", "timestamps", "mode", "scan_level", "completed_steps", "current_step"],
+  "properties": {
+    "workflow_version": {
+      "type": "string",
+      "description": "Version of document-project workflow"
+    },
+    "timestamps": {
+      "type": "object",
+      "required": ["started", "last_updated"],
+      "properties": {
+        "started": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow started"
+        },
+        "last_updated": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp of last state update"
+        },
+        "completed": {
+          "type": "string",
+          "format": "date-time",
+          "description": "ISO 8601 timestamp when workflow completed"
+        }
+      }
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["initial_scan", "full_rescan", "deep_dive", "quick"],
+      "description": "Workflow execution mode"
+    },
+    "scan_level": {
+      "type": "string",
+      "enum": ["quick", "deep", "exhaustive"],
+      "description": "Scan depth level"
+    },
+    "project_root": {
+      "type": "string",
+      "description": "Absolute path to project root directory"
+    },
+    "project_knowledge": {
+      "type": "string",
+      "description": "Absolute path to project knowledge folder"
+    },
+    "completed_steps": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["step", "status"],
+        "properties": {
+          "step": {
+            "type": "string",
+            "description": "Step identifier"
+          },
+          "status": {
+            "type": "string",
+            "enum": ["completed", "partial", "failed"]
+          },
+          "timestamp": {
+            "type": "string",
+            "format": "date-time"
+          },
+          "outputs": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Files written during this step"
+          },
+          "summary": {
+            "type": "string",
+            "description": "1-2 sentence summary of step outcome"
+          }
+        }
+      }
+    },
+    "current_step": {
+      "type": "string",
+      "description": "Current step identifier for resumption"
+    },
+    "findings": {
+      "type": "object",
+      "description": "High-level summaries only",
+      "properties": {
+        "project_classification": {
+          "type": "object",
+          "properties": {
+            "repository_type": { "type": "string" },
+            "parts_count": { "type": "integer" },
+            "primary_language": { "type": "string" },
+            "architecture_type": { "type": "string" }
+          }
+        },
+        "technology_stack": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "part_id": { "type": "string" },
+              "tech_summary": { "type": "string" }
+            }
+          }
+        },
+        "batches_completed": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "path": { "type": "string" },
+              "files_scanned": { "type": "integer" },
+              "summary": { "type": "string" }
+            }
+          }
+        }
+      }
+    },
+    "outputs_generated": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "List of all output files generated"
+    },
+    "resume_instructions": {
+      "type": "string",
+      "description": "Instructions for resuming from current_step"
+    },
+    "validation_status": {
+      "type": "object",
+      "properties": {
+        "last_validated": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "validation_errors": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
+    "deep_dive_targets": {
+      "type": "array",
+      "description": "Track deep-dive areas analyzed",
+      "items": {
+        "type": "object",
+        "properties": {
+          "target_name": { "type": "string" },
+          "target_path": { "type": "string" },
+          "files_analyzed": { "type": "integer" },
+          "output_file": { "type": "string" },
+          "timestamp": { "type": "string", "format": "date-time" }
+        }
+      }
+    }
+  }
+}

package/src/method-skills/1-analysis/wize-document-project/templates/source-tree-template.md

@@ -0,0 +1,142 @@
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: {{date}}
+last_refreshed: {{date}}
+---
+
+# {{project_name}} - Source Tree Analysis
+
+**Date:** {{date}}
+
+## Overview
+
+{{source_tree_overview}}
+
+{{#if is_multi_part}}
+
+## Multi-Part Structure
+
+This project is organized into {{parts_count}} distinct parts:
+
+{{#each project_parts}}
+
+- **{{part_name}}** (`{{root_path}}`): {{purpose}}
+{{/each}}
+{{/if}}
+
+## Complete Directory Structure
+
+```
+{{complete_source_tree}}
+```
+
+## Critical Directories
+
+{{#each critical_folders}}
+
+### `{{folder_path}}`
+
+{{description}}
+
+**Purpose:** {{purpose}}
+**Contains:** {{contents_summary}}
+{{#if entry_points}}**Entry Points:** {{entry_points}}{{/if}}
+{{#if integration_note}}**Integration:** {{integration_note}}{{/if}}
+
+{{/each}}
+
+{{#if is_multi_part}}
+
+## Part-Specific Trees
+
+{{#each project_parts}}
+
+### {{part_name}} Structure
+
+```
+{{source_tree}}
+```
+
+**Key Directories:**
+{{#each critical_directories}}
+
+- **`{{path}}`**: {{description}}
+{{/each}}
+
+{{/each}}
+
+## Integration Points
+
+{{#each integration_points}}
+
+### {{from_part}} → {{to_part}}
+
+- **Location:** `{{integration_path}}`
+- **Type:** {{integration_type}}
+- **Details:** {{details}}
+{{/each}}
+
+{{/if}}
+
+## Entry Points
+
+{{#if is_single_part}}
+
+- **Main Entry:** `{{main_entry_point}}`
+{{#if additional_entry_points}}
+- **Additional:**
+{{#each additional_entry_points}}
+  - `{{path}}`: {{description}}
+{{/each}}
+{{/if}}
+{{else}}
+{{#each project_parts}}
+
+### {{part_name}}
+
+- **Entry Point:** `{{entry_point}}`
+- **Bootstrap:** {{bootstrap_description}}
+{{/each}}
+{{/if}}
+
+## File Organization Patterns
+
+{{file_organization_patterns}}
+
+## Key File Types
+
+{{#each file_type_patterns}}
+
+### {{file_type}}
+
+- **Pattern:** `{{pattern}}`
+- **Purpose:** {{purpose}}
+- **Examples:** {{examples}}
+{{/each}}
+
+## Asset Locations
+
+{{#if has_assets}}
+{{#each asset_locations}}
+
+- **{{asset_type}}**: `{{location}}` ({{file_count}} files, {{total_size}})
+{{/each}}
+{{else}}
+No significant assets detected.
+{{/if}}
+
+## Configuration Files
+
+{{#each config_files}}
+
+- **`{{path}}`**: {{description}}
+{{/each}}
+
+## Notes for Development
+
+{{development_notes}}
+
+---
+
+_Generated using Wize Dev Kit `document-project` workflow_

package/src/method-skills/1-analysis/wize-document-project/workflow.md

@@ -1,36 +1,229 @@
 ---
+
 code: wize-document-project
+description: "Use quando o kit for instalado em um repositório existente (brownfield) e precisar documentar o estado atual do projeto."
 name: Document Project (brownfield baseline)
 phase: 1-analysis
-owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter)
-status: stub
+owner: wize-agent-analyst   # Pepper Potts (paired with Peggy Carter and Tony Stark)
+status: ready
 ---
 
 # Document Project — Brownfield Baseline
 
-**Goal.** When the kit is installed in an existing codebase, baseline the current state so subsequent planning isn't blind. Produces an "as-is" snapshot that Tony reads before drawing the "to-be."
+**Goal.** When the kit is installed in an existing repo, baseline the **as-is** state so the rest of the lifecycle isn't blind. Produces a structured snapshot Tony can read before designing the *to-be*, and a knowledge base Wizer can answer questions from.
+
+Pepper drives discovery. Peggy edits prose. Tony validates architecture interpretation. Output lands in `.wize/knowledge/document-project/`.
 
 ## When to run
-- Installer detected `package.json` / `pubspec.yaml` / `Cargo.toml` / `go.mod` + non-trivial `src/` history.
-- User explicitly requests `/wize-document-project`.
+
+- The installer detected brownfield signals (`package.json`, `src/`, history) and offered to run this. ✓
+- The team is onboarding to a codebase nobody fully owns. ✓
+- A previous re-platforming decision left the docs stale. ✓
+
+Skip:
+- Greenfield (nothing to document yet).
+- Repos < 200 LOC.
 
 ## Inputs
-- The target repo (root)
-- `git log --oneline -50`
-- Existing READMEs / ARCHITECTURE / docs
+
+- The target repo (root).
+- `git log --since="1 year ago" --oneline | wc -l` to scope.
+- Any prior README / ARCHITECTURE / docs that exist.
+
+## CLI usage
+
+```bash
+wize-dev-kit document-project                # quick baseline (default)
+wize-dev-kit document-project quick          # same as default
+wize-dev-kit document-project initial_scan   # pattern-only initial scan
+wize-dev-kit document-project initial_scan deep       # reads critical directories
+wize-dev-kit document-project initial_scan exhaustive  # reads all source files in batches
+wize-dev-kit document-project full_rescan    # archives old state, re-runs initial_scan
+wize-dev-kit document-project deep_dive --target src/tools/installer
+```
+
+## Modes
+
+| Mode | What it does | Scan levels |
+|---|---|---|
+| `quick` | Writes the 6 baseline files. Does not read source files. | `quick` only |
+| `initial_scan` | Classifies project type, writes index + overview + source tree + conditional docs. | `quick`, `deep`, `exhaustive` |
+| `full_rescan` | Archives `project-scan-report.json` and re-runs `initial_scan`. | `quick`, `deep`, `exhaustive` |
+| `deep_dive` | Exhaustive analysis of a specific folder/file/feature. | `exhaustive` |
 
 ## Outputs
-- `.wize/knowledge/document-project/overview.md`
-- `.wize/knowledge/document-project/architecture-snapshot.md`
-- `.wize/knowledge/document-project/conventions.md`
-- `.wize/knowledge/document-project/open-questions.md`
+
+- `.wize/knowledge/document-project/overview.md` — what the project is, who uses it, how big it is.
+- `.wize/knowledge/document-project/architecture-snapshot.md` — current components, integrations, data flow.
+- `.wize/knowledge/document-project/conventions.md` — coding/test/folder conventions actually used.
+- `.wize/knowledge/document-project/dependencies.md` — runtime deps + dev deps + their roles.
+- `.wize/knowledge/document-project/risk-spots.md` — areas of concentrated complexity, undocumented behavior, or known fragility.
+- `.wize/knowledge/document-project/open-questions.md` — things the code doesn't answer; route to humans.
+- `.wize/knowledge/document-project/index.md` — master navigation with `_(To be generated)_` markers for missing conditional docs.
+- `.wize/knowledge/document-project/project-scan-report.json` — resume state.
 
 ## Steps
-1. **Inventory.** List packages, top-level modules, infra files, entry points.
-2. **Architecture snapshot.** Components and integrations as currently exist. Diagrams welcome.
-3. **Conventions.** Coding/test/folder conventions surfaced from a sample of files.
-4. **Open questions.** Things the code doesn't answer; route to humans.
-5. **Hand off.** Pepper to Wizer: "baseline ready." Then Wizer decides next agent.
-
-## Pairing
-Peggy Carter edits prose for clarity and structure. Tony Stark may be looped in to confirm architecture interpretation.
+
+### 1. Inventory (Pepper, mechanical)
+
+A first pass that requires no judgment, just listing.
+
+```
+ls -la                                  # top-level layout
+cat package.json | jq '.dependencies, .devDependencies, .scripts'
+git log --since="3 months ago" --oneline | wc -l
+git log --pretty=format:"%an" | sort | uniq -c | sort -rn | head
+find . -name "*.test.*" -o -name "*.spec.*" | wc -l
+find . -type f -name "*.md" | head
+```
+
+Write what you found in `overview.md` (no opinions yet).
+
+### 2. Architecture snapshot (Pepper + Tony)
+
+Walk the repo top-down. Identify:
+- **Entry points** (CLI, server, worker, build).
+- **Components** (where the boundaries are — by folder, by package, by feature).
+- **Integrations** (databases, queues, external APIs, third-party SDKs).
+- **Data flow** for at least one end-to-end critical path (e.g., a typical user request).
+
+Draw or describe. Diagrams in ASCII or Mermaid are fine — the point is shared mental model.
+
+Tony validates. If the snapshot misnames a pattern, fix it.
+
+### 3. Conventions (Peggy)
+
+Sample 5–10 files across the repo. Note:
+- Naming (camelCase / snake_case / kebab-case).
+- Folder structure (feature-first / layer-first).
+- Test placement (co-located / `__tests__` / `test/`).
+- Comment style (JSDoc / TSDoc / inline).
+- Import ordering (alphabetical / by source).
+- Logging / error handling patterns.
+- Linter / formatter config (eslint, prettier, etc.).
+
+Write the convention found, not the convention you'd prefer.
+
+### 4. Dependencies (Pepper)
+
+For each runtime dep, write one line:
+- Name, version, what it does in this repo, whether it's load-bearing.
+
+Flag:
+- Deps without a clear role.
+- Deps with known CVEs (run `npm audit --omit=dev` and capture).
+- Multiple deps doing the same job (`lodash` + `ramda`, both date libs, etc.).
+- Deps not maintained in > 2 years (link to last release).
+
+### 5. Risk spots (Pepper + Tony)
+
+For each, name the area + the symptom + the likely cause + how confident you are:
+
+| Area | Symptom | Likely cause | Confidence |
+|---|---|---|---|
+| `src/legacy/billing/` | 2k-line file with no tests | rushed migration in 2024 | high |
+| Webhooks handler | Silent retries | no idempotency layer | medium |
+| Auth middleware | Custom JWT parsing | predates the library that handles it | high |
+
+This is *not* a refactor backlog. It's a map. Tony decides what to fix; this just makes the choices visible.
+
+### 6. Open questions (everyone)
+
+Things the code does NOT answer:
+- Why was this choice made?
+- What's the SLA?
+- Who's the owner of feature X?
+- Are there secret configs we're missing?
+
+Each question gets an owner (a human Pepper will ask). Route back via Wizer.
+
+### 7. Hand-off
+
+- Mark all docs `status: baseline`.
+- Tell Wizer: *"Baseline complete. Tony can read it before architecture work; Hill can read it before scoping."*
+
+## Conventions doc — template
+
+```markdown
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: YYYY-MM-DD
+sampled: 8 files across src/, tests/, scripts/
+---
+
+# Conventions (observed, not prescribed)
+
+## Naming
+- Files: kebab-case (e.g., `user-profile.ts`).
+- Classes: PascalCase.
+- Functions: camelCase, verb-led.
+- Constants: UPPER_SNAKE_CASE.
+
+## Folder structure
+Feature-first: `src/features/<feature>/{index.ts, api.ts, ui.tsx, *.spec.ts}`.
+Shared utilities in `src/shared/`.
+
+## Tests
+Co-located with the file under test. `.spec.ts` for unit; `.e2e.ts` for end-to-end (separate runner).
+
+## Lint/format
+`eslint.config.mjs` with `airbnb-base` + custom rules in `eslint.local.cjs`. Prettier with 2-space indent.
+
+## Observed deviations
+- `src/legacy/billing/` doesn't follow feature-first; it predates the convention.
+- Some files use `_test.ts` suffix instead of `.spec.ts` — older code.
+```
+
+## Update mode (how the baseline stays alive)
+
+The first run of this workflow produces the **baseline**. Two complementary mechanisms keep it current after:
+
+### 1. Inline updates per story (the daily cadence)
+
+Every `wize-dev-story` ends with a Knowledge Update step (step 8). If the story touched any of the 5 axes (architecture, conventions, risk-spots, dependencies, overview), Shuri appends 1–3 dated bullets to the matching `document-project/*.md` file **in the same PR**. Hawkeye verifies in `tea-review`; a touched-but-not-updated story gets a `KN-NN` finding at gate.
+
+`wize-quick-dev` has a lighter version: only when a dep bump or a public rename actually shifts the baseline.
+
+This produces dated bullets like:
+
+```markdown
+## 2026-06-12 — E01-S03
+- Conventions: `data-testid="invite-*"` published as public contract.
+- Risk: R-1 (mailer) mitigation confirmed.
+```
+
+### 2. Sprint-end refresh (the narrative cadence)
+
+`wize-refresh-knowledge` runs at sprint end (triggered by `wize-help next` when it detects the sprint emptied). Pepper + Peggy consolidate the inline bullets into the narrative prose of each axis file, demote stale claims to a "Deprecated" section, freeze a sprint snapshot in `_history/{YYYY-Qn}/sprint-{N}.md`, and stamp `last_refreshed` in each file.
+
+Result: the baseline reads like a single coherent document, not a chronological log. New devs can read it linearly and form a mental model. Forensics readers (six months later, asking "when did X change?") consult `_history/`.
+
+### File frontmatter convention
+
+Each `document-project/*.md` file ships with:
+
+```yaml
+---
+status: baseline
+owner: Pepper Potts + Peggy Carter
+created: 2026-04-02
+last_refreshed: 2026-06-25
+sampled: "wkly + sprint refresh"
+---
+```
+
+`last_refreshed` tells the reader how much to trust the file vs the inline bullets accumulating since.
+
+## Anti-patterns Pepper rejects
+
+- "TODO: document later." The baseline IS the documentation pass; later doesn't come.
+- Romanticizing the code ("clean, modular"). Describe what you see; let Tony judge.
+- Architecture diagrams that show what the team *wishes* exists. Diagram the real state.
+- Risk-spot table with no confidence label. Without confidence, readers can't act.
+- Open questions with no owner. They never get answered.
+- Treating the baseline as one-shot. The mode + refresh exist precisely because point-in-time docs lie within weeks.
+
+## Hand-off
+
+> Baseline is in `.wize/knowledge/document-project/`. Three risk spots flagged. Five open questions routed to the humans named per question. Tony can read this before drawing `architecture.md`; Hill can scope the PRD knowing what's already there.

package/src/method-skills/1-analysis/wize-domain-research/customize.toml

@@ -0,0 +1,14 @@
+# Wize Dev Kit — overrides for the built-in workflow "wize-domain-research".
+# DO NOT EDIT in the installed kit; copy to .wize/custom/workflows/wize-domain-research/
+# for project-level overrides.
+
+[workflow]
+
+activation_steps_prepend = []
+activation_steps_append = []
+
+persistent_facts = [
+  "file:{project-root}/.wize/planning/brief.md",
+]
+
+on_complete = ""