wize-dev-kit 0.4.1 → 0.5.0

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)."

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

@@ -8,92 +8,79 @@ status: ready
 
 # Sprint Planning
 
-**Goal.** Pick what enters this sprint. Capacity-honest, priority-honest, risk-honest. The sprint is a commitment about a small slice of the future, not a wish list.
+**Goal.** Pick what enters this sprint. Capacity-honest, priority-honest, risk-honest.
 
-Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk on stories. Shuri commits to the load.
+Maria Hill chairs. Tony advises on slicing. Hawkeye flags risk. Shuri commits to the load.
 
 ## Inputs
 
 - Story backlog: `.wize/solutioning/stories/`
-- Velocity history: `.wize/implementation/sprint-status.md` (previous sprints) — when present.
+- Previous sprint state: `.wize/implementation/sprint-status.yaml`
 - `.wize/implementation/tea/risk-profile.md`
-- Open `tea-gate` outcomes from last sprint.
-- Team availability for the next interval (vacations, on-call rotation, planned meetings).
+- Team availability for the next interval.
 
 ## Output
 
-- New sprint block appended to `.wize/implementation/sprint-status.md`.
-- Story files updated `priority: 1` for chosen stories.
-
-## Rules
-
-1. **Capacity = min(history velocity, declared availability).** Not the average of optimistic estimates.
-2. **High-risk stories** (linked to `R-x` HIGH in risk profile) get TEA design done in the planning meeting, not at story start.
-3. **Stretch goals** are explicit, named, not silent. If a stretch ships, great. If not, the sprint isn't a failure.
-4. **Don't carry over without reason.** A carried-over story gets a one-line "why" in the sprint log.
+- Updated `.wize/implementation/sprint-status.yaml`.
+- Story files updated with `priority: 1` for chosen stories.
 
 ## Steps
 
-### 1. Look back (3 min)
-
-Last sprint: what shipped, what slipped, what surprised. Don't relitigate; observe.
-
-### 2. Refresh capacity
-
-- Person-days available this sprint = sum(working days) × (1 - meetings load).
-- Subtract on-call burden, oncall handoff time, planned reviews.
-
-### 3. Pull stories (in priority order)
-
-Default selection algorithm:
-- Always pull continuation stories (in-flight from last sprint) first.
-- Then highest-priority stories that fit the capacity.
-- Then risk-driven: high-risk stories (R-HIGH) preferred over more low-risk ones when capacity is tight.
-
-For each pulled story, confirm INVEST still holds; re-slice if needed.
-
-### 4. Reserve buffer
-
-10–15% buffer for unknowns (bug fixes, support escalations). Don't fill the sprint to 100% — you'll always pay.
-
-### 5. Walk the gate plan
-
-For each story pulled, what's the TEA gate cadence? Most stories: design at start, trace + review + gate at end. High-risk: include NFR re-check at epic close.
-
-### 6. Commit (verbal + written)
-
-Each engineer reads back the stories they're owning. Hill writes them into the sprint block. Sprint starts.
-
-## Sprint block template (appended to `sprint-status.md`)
-
-```markdown
-## Sprint 7 — 2026-06-12 → 2026-06-25
-
-**Capacity:** 24 person-days (3 engineers × 10 days × 0.8 utilization)
-**Carry-over:** E01-S05 (90% done; Shuri); E03-S01 (TEA review pending)
-**Pulled:**
-- E01-S06 — M — owner: Shuri — gate cadence: design+gate
-- E02-S02 — L — owner: Shuri — gate cadence: design+trace+review+gate (R-3)
-- E03-S02 — M — owner: Aaliyah — gate cadence: design+trace+review+gate (R-1)
-- E04-S01 — S — owner: Shuri — gate cadence: smoke (quick-dev pattern)
-- E02-S03 — S — stretch
-
-**Out (deferred to Sprint 8):**
-- E03-S03 — reason: depends on E03-S02 ADR
-- E05-S01 — reason: out of NFR-cost budget; revisit
-
-**Risks flagged:**
-- E02-S02 — auth refresh story; high-risk; TEA design done at planning.
+1. **Look back** — what shipped, what slipped, what surprised.
+2. **Refresh capacity** — person-days × utilization − overhead.
+3. **Pull stories** — continuation first, then priority, then risk.
+4. **Reserve 10–15% buffer** for unknowns.
+5. **Walk the gate plan** — design/trace/review/gate per story.
+6. **Commit** — verbal + written into YAML.
+
+## Status state machine
+
+- Epic: `backlog` → `in-progress` → `done`
+- Story: `backlog` → `ready-for-dev` → `in-progress` → `review` → `done`
+- Retrospective: `optional` ↔ `done`
+
+## Sprint block template
+
+```yaml
+# generated: YYYY-MM-DD
+# last_updated: YYYY-MM-DD
+# project: {project_name}
+# project_key: {project_key}
+# tracking_system: file-system
+# story_location: .wize/solutioning/stories
+
+generated: YYYY-MM-DD
+last_updated: YYYY-MM-DD
+project: {project_name}
+project_key: {project_key}
+tracking_system: file-system
+story_location: .wize/solutioning/stories
+
+development_status:
+  epic-1: backlog
+  1-1-story-one: backlog
+  1-2-story-two: backlog
+  epic-1-retrospective: optional
 ```
 
-## Anti-patterns Hill rejects
+## Anti-patterns
 
-- **"Optimistic" velocity that ignores history.** Use observed velocity.
-- **Stories pulled without owners.** Don't aspire; commit.
-- **Stretch goals so big they're really plan.** Stretch = optional, not "we hope we can."
-- **Pulling a story when its dependency hasn't shipped.** It will sit blocked.
-- **No buffer.** Real sprints have surprises.
+- Optimistic velocity.
+- Stories without owners.
+- Stretch goals that are really plan.
+- Pulling blocked dependencies.
+- Zero buffer.
 
 ## Hand-off
 
-> Sprint 7 committed at `.wize/implementation/sprint-status.md`. Shuri owns most; Aaliyah picks up E03-S02. Hawkeye, NFR gate due on E03 at sprint end. Wizer, retro on the 25th.
+> Sprint committed at `.wize/implementation/sprint-status.yaml`. Stories in `ready-for-dev` are now eligible for the dev loop.
+>
+> **Recommended next loop:**
+>
+> ```
+> /loop /wize-dev-story
+> ```
+>
+> `/loop /wize-dev-story` drives one story at a time: TDD red-green-refactor, AC IDs in commits, `tea-design.md` contract, knowledge update on the 5 baseline axes, and a clean gate at the end. `/loop` keeps it going across the sprint's `ready-for-dev` queue until the user pauses.
+>
+> Next: `/wize-sprint-status` (Maria Hill) to acompanhar o progresso.