wize-dev-kit 0.4.0 → 0.5.0

package/src/method-skills/2-plan-workflows/wize-edit-prd/workflow.md

@@ -0,0 +1,108 @@
+---
+code: wize-edit-prd
+name: Edit PRD
+phase: 2-plan-workflows
+owner: wize-agent-pm   # Maria Hill
+status: ready
+---
+
+# Edit PRD
+
+**Goal.** Update `.wize/planning/prd.md` without rewriting from scratch. Every change is recorded in `.wize/planning/prd-changelog.md` so the team can see *what* changed, *when*, *why*, and *by whom*.
+
+Maria Hill drives. Peggy polishes prose on the diff. Wizer is on call for cross-cutting impacts (architecture, NFR, scope).
+
+## When to run
+
+- A new AC is needed (new requirement from the user, market shift, regulator).
+- An AC is no longer correct (validated learning, scoping mistake).
+- An item moves in-scope ↔ out-of-scope.
+- A non-goal is added or removed.
+- A new decision is made that affects the PRD (e.g., cut a feature).
+
+## When NOT to run
+
+- Rewriting the PRD from scratch → use `/wize-create-prd`.
+- Validating the PRD → use `/wize-validate-prd`.
+
+## Inputs
+
+- `.wize/planning/prd.md` (current)
+- A free-form change request from the user.
+
+## Output
+
+- Updated `.wize/planning/prd.md`.
+- New row in `.wize/planning/prd-changelog.md` (one row per change).
+
+## Steps
+
+### 1. Read the current PRD
+
+Parse the PRD frontmatter (`status`, `owner`, `created`, `last_updated`) and the body. Confirm the change is in scope of "edit" (not a rewrite). If the change touches > 25% of the PRD, route to `/wize-create-prd` instead.
+
+### 2. Classify the edit
+
+Pick exactly one type:
+
+- **A** — Add or change an AC.
+- **B** — Move item in-scope ↔ out-of-scope.
+- **C** — Add or remove a non-goal.
+- **D** — Register a decision that affects the PRD (link to ADR or sprint decision).
+
+One edit per run. Re-run for additional edits.
+
+### 3. Apply the edit
+
+Make the change in `prd.md`. Mark the changed section with a trailing note: `(edited 2026-06-15, see changelog row 4)`.
+
+Update frontmatter: `last_updated` to today; `status` stays the same (only `/wize-validate-prd` flips it to `validated`).
+
+### 4. Append to changelog
+
+Add a row to `prd-changelog.md`:
+
+```markdown
+| Date | Type | Section | Change | Author |
+|---|---|---|---|---|
+| 2026-06-15 | A | AC-04-2 | Added: "rate limit per team" | Hill |
+| 2026-06-15 | B | Out of scope | Removed "bulk invite" (now in scope per E04-S02) | Hill |
+```
+
+### 5. Cross-cutting check
+
+Wizer flags any downstream impact:
+
+- New AC → check that the epic + stories covering it exist. If not, route to `/wize-create-epics-and-stories`.
+- New non-goal → check that no in-flight story assumes the opposite. If yes, flag the story.
+- In-scope move → trigger a fresh `/wize-sprint-planning` consideration.
+
+### 6. Hand off
+
+Notify the next workflow:
+
+- If AC changed → `/wize-validate-prd` to confirm consistency.
+- If epic + stories need refresh → `/wize-create-epics-and-stories`.
+- If sprint needs re-prioritization → `/wize-sprint-planning`.
+
+## Output template — `prd-changelog.md`
+
+```markdown
+# PRD changelog
+
+| # | Date | Type | Section | Change | Author |
+|---|---|---|---|---|---|
+| 1 | 2026-06-15 | A | AC-04-2 | Added: "rate limit per team" | Hill |
+| 2 | 2026-06-15 | B | Out of scope | Removed "bulk invite" | Hill |
+```
+
+## Anti-patterns Hill rejects
+
+- Editing the PRD without recording the change in the changelog. (Source-of-truth drift.)
+- Bundling 4 edits in one run. (One edit per run keeps blame clean.)
+- Editing the PRD without checking downstream impact. (Wizer’s cross-cutting step is mandatory.)
+- Re-running `/wize-create-prd` to "keep things tidy." The changelog exists for that.
+
+## Hand-off
+
+> "PRD updated at `.wize/planning/prd.md`. Changelog row N appended. Next: `/wize-validate-prd` (re-validate) or `/wize-create-epics-and-stories` (refresh stories)."

package/src/method-skills/3-solutioning/wize-project-context/workflow.md

@@ -0,0 +1,118 @@
+---
+code: wize-project-context
+name: Project Context
+phase: 3-solutioning
+owner: wize-agent-architect   # Tony Stark
+status: ready
+---
+
+# Project Context
+
+**Goal.** Consolidate the 5 foundational artifacts (brief, PRD, UX, architecture, risk profile) into a single `.wize/knowledge/project-context.md` so other agents (Shuri, Hawkeye, Mantis, Wizer) can read the project in one shot instead of stitching it from 5 files.
+
+Tony drives. Peggy polishes prose. Wizer is on call for cross-cutting drift.
+
+## When to run
+
+- After Phase 3 closeout (architecture + ADRs + risk profile all exist).
+- After any major change to brief / PRD / architecture (rerun).
+- Before sprint planning if context feels stale.
+
+## When NOT to run
+
+- During greenfield with no artifacts yet (run only after brief + PRD exist).
+- As a CI step (manual; expensive to run on every commit).
+
+## Inputs
+
+- `.wize/planning/brief.md` — Vision, Audience.
+- `.wize/planning/prd.md` — Goals, scope.
+- `.wize/planning/ux/ux-design/index.md` — UX stack, key screens.
+- `.wize/solutioning/architecture.md` — Tech stack, components.
+- `.wize/solutioning/adrs/*.md` — Key decisions.
+- `.wize/implementation/tea/risk-profile.md` — Active risks.
+
+## Output
+
+- `.wize/knowledge/project-context.md` (5 sections, YAML frontmatter, `last_updated` date).
+
+## Steps
+
+### 1. Vision and Audience
+
+Copy from `brief.md` (or `prd.md` if brief is missing). One paragraph each. Mark the source file in a comment.
+
+### 2. Tech stack
+
+From `architecture.md`, list: runtime, framework, database, key libraries, build tool. One bullet per item. Skip items that are "TBD".
+
+### 3. Key ADRs
+
+List the 5 most recent ADRs from `.wize/solutioning/adrs/`. For each: title, decision, why. Older ADRs are out of scope; refer to `adrs/index.md` for the full list.
+
+### 4. Active risks
+
+Copy from `risk-profile.md` the top 5 risks (highest prob × impact). One bullet per risk with the mitigation. Defer the rest.
+
+### 5. Active sprint
+
+Read `.wize/implementation/sprint-status.yaml` and include: sprint number, capacity, in-progress stories. Skip if no active sprint.
+
+### 6. Hand off
+
+Output is a markdown file. Wizer uses this file to seed `/wize-help`, `/wize-dev-story`, and `/wize-onboarding` reads.
+
+## Output template
+
+```markdown
+---
+generated: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+sources:
+  - .wize/planning/brief.md
+  - .wize/planning/prd.md
+  - .wize/planning/ux/ux-design/index.md
+  - .wize/solutioning/architecture.md
+  - .wize/solutioning/adrs/
+  - .wize/implementation/tea/risk-profile.md
+---
+
+# Project Context — {project_name}
+
+## Vision
+{paragraph from brief.md}
+
+## Audience
+{paragraph from brief.md or prd.md}
+
+## Tech stack
+- Runtime: {value}
+- Framework: {value}
+- Database: {value}
+- Key libraries: {value}
+- Build: {value}
+
+## Key ADRs
+1. **{title}** — {decision}. Why: {why}.
+2. ...
+
+## Active risks
+1. **{R-id}** — {description}. Mitigation: {mitigation}.
+2. ...
+
+## Active sprint
+- Sprint: {N}
+- Capacity: {days}
+- In-progress: {stories}
+```
+
+## Anti-patterns Tony rejects
+
+- Reading all 6 sources in full and dumping them. Summarize in 5 sections.
+- Editing the project-context.md by hand. (Always re-run the workflow to keep `last_updated` honest.)
+- Skipping the frontmatter. Other agents parse it.
+- Including items marked "TBD". Surface them in the `Open questions` section instead.
+
+## Hand-off
+
+> "Project context updated at `.wize/knowledge/project-context.md`. {N} sources, 5 sections, {date}. Next: `/wize-onboarding` (Wizer) reads this for first contact."

package/src/method-skills/4-implementation/wize-checkpoint-preview/workflow.md

@@ -0,0 +1,115 @@
+---
+code: wize-checkpoint-preview
+name: Checkpoint Preview
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri (+ wize-agent-architect Tony on call)
+status: ready
+---
+
+# Checkpoint Preview
+
+**Goal.** Pause mid-story to validate direction before continuing. For M/L stories where the cost of going off-rail is high, a quick checkpoint catches drift before it becomes rework.
+
+Shuri drives. Tony on call for architectural drift. Hawkeye on call for test design drift.
+
+## When to run
+
+- Manually, when a story is taking longer than expected.
+- After the first 2-3 commits of an M or L story.
+- When a new constraint is mentioned (security review, perf budget, vendor change).
+
+## When NOT to run
+
+- Quick-dev / S stories (overhead exceeds the value).
+- When the story is < 50% done and no surprise has come up yet.
+
+## Inputs
+
+- The current story file: `.wize/solutioning/stories/{epic}/{story}.md`
+- The git diff: uncommitted + committed since story start
+- The `tea-design.md` for the story
+- The `design-system/` tokens used so far
+
+## Output
+
+- `.wize/implementation/checkpoints/{story_id}.md` (one file per checkpoint, append over time)
+- A decision: continue / pivot / stop
+
+## Steps
+
+### 1. Pause
+
+Stop writing code. Do not commit any pending work until the checkpoint is recorded.
+
+### 2. Snapshot
+
+Write 5 lines:
+
+- Files touched: (list, max 10)
+- ACs done vs. remaining: (X / Y)
+- Tests added: (count, by split)
+- New dependencies: (list)
+- Time spent: (estimate)
+
+### 3. Sanity check (3 questions)
+
+- **Are we solving the right problem?** Compare the implementation with the story's Context and ACs. If the story's intent was misunderstood, pivot.
+- **Is the design holding?** Compare the code with the architecture. If a new pattern emerged without an ADR, flag it.
+- **Any new constraints?** Did anything new appear (security finding, perf regression, vendor change, new stakeholder)?
+
+### 4. Decide
+
+One of three:
+
+- **Continue** — the path is right. Record the snapshot; resume.
+- **Pivot** — change scope or approach. Open a follow-up story with `wize-create-story`; do not edit the current story's ACs.
+- **Stop** — the story is no longer worth it. Move it to `backlog` via `wize-correct-course`.
+
+One decision per checkpoint. Re-run for additional decisions.
+
+### 5. Hand off
+
+Notify the next workflow:
+
+- Continue → `/wize-dev-story` (resume).
+- Pivot → `/wize-create-story` (new story for the pivot).
+- Stop → `/wize-correct-course` (defer the original).
+
+## Output template
+
+```markdown
+---
+story_id: E04-S02
+checkpoint: 1
+date: 2026-06-16
+author: Shuri
+---
+
+# Checkpoint — E04-S02
+
+## Snapshot
+- Files touched: src/...
+- ACs done vs. remaining: 1 / 4
+- Tests added: 2 unit, 1 integration
+- New dependencies: none
+- Time spent: ~3h
+
+## Sanity check
+- Right problem? Yes.
+- Design holding? Yes.
+- New constraints? Vendor X deprecated their API; need a different client lib.
+
+## Decision
+**Pivot** — see follow-up E04-S04 (client lib migration).
+```
+
+## Anti-patterns Shuri rejects
+
+- Skipping the snapshot to "save time" — the snapshot is the artifact.
+- Auto-pivoting (changing scope without an explicit checkpoint).
+- Recording "continue" without the sanity check answers.
+- Bundling multiple pivots in one checkpoint (one decision per run).
+
+## Hand-off
+
+> "Checkpoint recorded for **{story_id}** (decision: {continue|pivot|stop}). Next: `/wize-dev-story` / `/wize-create-story` / `/wize-correct-course`."

package/src/method-skills/4-implementation/wize-correct-course/workflow.md

@@ -0,0 +1,89 @@
+---
+code: wize-correct-course
+name: Correct Course
+phase: 4-implementation
+owner: wize-agent-pm   # Maria Hill, with wize-orchestrator
+status: ready
+---
+
+# Correct Course
+
+**Goal.** React when a sprint drifts. Detect the deviation, classify the cause, propose one of three corrective moves (cut scope, re-route, escalate), and update `sprint-status.yaml` after the user confirms.
+
+Maria Hill chairs. Wizer is on call for cross-cutting decisions. The human always confirms the action.
+
+## When to run
+
+- `wize-sprint-status` flagged a risk: “slipping” or “at risk”.
+- The team says "we won’t make it" during a stand-up.
+- A story’s TEA gate came back as `FAIL` mid-sprint.
+- An external event (incident, vendor outage) consumed capacity.
+
+## Inputs
+
+- `.wize/implementation/sprint-status.yaml`
+- `.wize/implementation/tea/{epic}/{story}/gate.md` (when a gate failed)
+- `.wize/knowledge/document-project/risk-spots.md` (for context on known risks)
+- A free-form reason from the user: chat message, stand-up note, or incident link.
+
+## Output
+
+- Updated `.wize/implementation/sprint-status.yaml` (statuses changed, items deferred).
+- One-line entry in `.wize/implementation/course-corrections.md` with date, cause, action, owner.
+
+## Steps
+
+### 1. Detect
+
+Wizer pulls the latest status file. If `last_updated` is older than 2 days, the sprint is stale. Mark this as risk #0: stale signal.
+
+### 2. Classify
+
+Pick exactly one cause:
+
+- **Cut scope.** Story is bigger than estimated, or a non-essential AC can be deferred.
+- **Re-route.** Story needs a different agent (e.g., Mantis for UX) or skill (e.g., `wize-investigate` for a regression).
+- **Escalate.** Story needs more hands, or a decision outside the team.
+
+A sprint can have multiple causes; the workflow handles one per run. Re-run for additional causes.
+
+### 3. Propose
+
+For each cause, propose 1–3 specific actions. Each action is bounded: a story ID to move, a date to defer to, or a person to page. No vague "communicate more" — that’s not an action.
+
+### 4. Confirm with the human
+
+List the actions; the human picks which to apply. Apply only what the human approved.
+
+### 5. Update the sprint
+
+For each approved action:
+
+- Change `sprint-status.yaml` statuses (e.g., story from `in-progress` → `backlog` if deferred).
+- Append a row to `course-corrections.md` with `date`, `cause`, `action`, `owner`.
+
+### 6. Hand off
+
+Notify the next workflow that should run (usually `wize-sprint-status` to confirm the new state, or `wize-dev-story` to continue the remaining work).
+
+## Output template — `course-corrections.md`
+
+```markdown
+# Course corrections
+
+| Date | Sprint | Cause | Action | Owner |
+|---|---|---|---|---|
+| 2026-06-15 | 4 | cut scope | E04-S02 split into S02a + S02b; S02b deferred to S5 | Hill |
+| 2026-06-15 | 4 | escalate | Paged Tony to unblock E04-S01 (waiting on ADR-010) | Wizer |
+```
+
+## Anti-patterns Hill rejects
+
+- Cutting scope without confirming the trade-off with the user.
+- Moving a story to `done` to "stop tracking it" when it isn’t actually done.
+- Re-routing to an agent who doesn’t have the context (always include a 3-sentence brief).
+- Escalating without naming a specific decision blocker.
+
+## Hand-off
+
+> "Course correction applied at `.wize/implementation/course-corrections.md`. Sprint {N} updated. Run `/wize-sprint-status` to confirm the new state."

package/src/method-skills/4-implementation/wize-investigate/workflow.md

@@ -0,0 +1,121 @@
+---
+code: wize-investigate
+name: Investigate
+phase: 4-implementation
+owner: wize-agent-dev   # Shuri (+ wize-agent-test-architect Hawkeye on call)
+status: ready
+---
+
+# Investigate
+
+**Goal.** Structured root-cause analysis for a failed test, regression, or unexpected behavior. Produces a written report so the team (and future-you) can retrace the steps.
+
+Shuri drives. Hawkeye on call for test-specific analysis. Wizer is on call for cross-cutting impact.
+
+## When to run
+
+- A test fails and the cause is not obvious from the diff.
+- A regression appears in production or CI.
+- A user reports a bug with unclear repro steps.
+- An incident triggers post-mortem.
+
+## When NOT to run
+
+- The cause is obvious from the diff → use `wize-quick-dev` to fix directly.
+- A new feature is needed (use `wize-create-story`).
+- A security finding is suspected (escalate immediately; do not investigate solo).
+
+## Inputs
+
+- The failing test, error log, or user report.
+- The commit range since the last known-good state.
+- The relevant story file (if any).
+- A free-form description of the symptoms.
+
+## Output
+
+- `.wize/implementation/investigations/{YYYY-MM-DD}-{short-slug}.md` — a written report.
+
+## Steps
+
+### 1. Frame
+
+One paragraph: what broke, when it was first noticed, who reported it, and how serious. If you cannot write this in 3 sentences, the report is too broad.
+
+### 2. Reproduce
+
+Step-by-step: how to reproduce locally. Include environment (OS, Node version, branch), commands, expected vs. actual output. If unreproducible, mark "not reproducible after N attempts" and stop.
+
+### 3. Hypothesize
+
+List 3 root causes, ranked by likelihood. For each:
+- What would explain the symptoms.
+- A 1-line test to confirm or refute.
+- Confidence: low / medium / high.
+
+### 4. Verify
+
+For each hypothesis, run the 1-line test. Record: confirmed / refuted / inconclusive. If all refuted, return to step 3 and re-rank.
+
+### 5. Conclude
+
+Pick the surviving root cause. State:
+- **Root cause:** {description}.
+- **Fix path:** {one paragraph: what to change and why}.
+- **Effort:** S / M / L.
+- **Risk of fix:** low / medium / high.
+- **Recommended next step:** open a quick-dev, open a story, or escalate.
+
+### 6. Hand off
+
+Notify the next workflow:
+- S / low risk → `/wize-quick-dev` (Shuri fixes directly).
+- M+ or higher risk → `/wize-create-story` (new story for the fix).
+- Escalation → `/wize-correct-course` (involve PM + Wizer).
+
+## Output template
+
+```markdown
+---
+date: 2026-06-16
+author: Shuri
+severity: high
+related_story: E04-S02
+related_test: test/document-project-classify.test.js
+status: concluded
+---
+
+# Investigation — {short-slug}
+
+## Frame
+{one paragraph}
+
+## Reproduce
+1. ...
+2. ...
+**Expected:** {x}
+**Actual:** {y}
+
+## Hypotheses
+1. **{hypothesis}** — Confidence: high. Test: {1-liner}. Result: confirmed.
+2. ...
+
+## Conclude
+- **Root cause:** {description}
+- **Fix path:** {one paragraph}
+- **Effort:** M
+- **Risk of fix:** low
+- **Next:** /wize-create-story (E04-S05)
+```
+
+## Anti-patterns Shuri rejects
+
+- Skipping the hypothesis ranking. (Ranking forces you to consider alternatives.)
+- Stopping at "I think it's X" without the verification test. (Confirmation bias.)
+- Mixing the investigation with the fix. (Investigate, then propose; do not edit code yet.)
+- One-paragraph reports. (If it's a real investigation, it's at least 5 sections.)
+- Sharing the report only in chat. (Always write to disk for archival.)
+
+## Hand-off
+
+> "Investigation concluded. Root cause: {summary}. Next: `/wize-create-story` (M+ fix) or `/wize-quick-dev` (S fix)."