wicked-garden 12.27.0

package/skills/wickedizer/refs/structure.md

@@ -0,0 +1,282 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Structure: Document Architecture
+
+How you organize content determines whether readers find what they need. Structure is invisible when done well—readers just "get it."
+
+## The Dependency Rule for Writing
+
+**Information flows from general to specific, from decision to detail.**
+
+```
+// BAD: Bottom-up (reader must hold context)
+We analyzed 47 metrics across 3 quarters.
+The data showed a 23% decline in engagement.
+User surveys confirmed the trend.
+Therefore, we recommend redesigning the onboarding flow.
+
+// GOOD: Top-down (reader gets point first)
+We recommend redesigning the onboarding flow.
+Engagement dropped 23% over 3 quarters.
+User surveys confirm new users abandon at step 3.
+```
+
+**Rule:** If the reader can't state your point after the first paragraph, restructure.
+
+---
+
+## Vertical Organization
+
+### Inverted Pyramid (News Style)
+
+Most important information first, details descend in importance.
+
+```
+[Lead: What happened, why it matters]
+[Key details: Who, when, how]
+[Background: Context, history]
+[Additional: Nice-to-know]
+```
+
+**Use for:** Exec summaries, announcements, status updates, any doc readers might not finish.
+
+### Problem-Solution-Benefit
+
+```
+[Problem: What's broken, what pain exists]
+[Solution: What we're doing about it]
+[Benefit: What improves, for whom]
+```
+
+**Use for:** Proposals, PRDs, business cases, change requests.
+
+### Situation-Complication-Resolution (SCR)
+
+```
+[Situation: Current state, shared context]
+[Complication: What changed, what's the tension]
+[Resolution: What to do about it]
+```
+
+**Use for:** Strategy docs, recommendation memos, persuasive writing.
+
+### Chronological
+
+```
+[First: What happened first]
+[Then: What happened next]
+[Now: Current state]
+[Next: What happens next]
+```
+
+**Use for:** Incident reports, project updates, historical documentation.
+
+---
+
+## Horizontal Layering
+
+### The Three Layers of a Document
+
+```
+Layer 1: NAVIGATION (scannable in 10 seconds)
+├── Title tells you what this is
+├── Headings show structure
+├── Bold text marks key points
+└── Bullets list scannable items
+
+Layer 2: SUMMARY (readable in 2 minutes)
+├── Opening paragraph states the point
+├── Section leads summarize each part
+└── Conclusion restates decision/action
+
+Layer 3: DETAIL (full read when needed)
+├── Supporting evidence
+├── Technical specifics
+└── Background context
+```
+
+**Rule:** A reader at Layer 1 should know if they need Layer 2. A reader at Layer 2 should know if they need Layer 3.
+
+---
+
+## Heading Architecture
+
+### Headings Should Work as an Outline
+
+```
+// BAD: Headings that don't standalone
+1. Background
+2. Analysis
+3. Discussion
+4. Conclusion
+
+// GOOD: Headings that tell the story
+1. Auth system needs replacement by Q2
+2. JWT outperforms sessions on all metrics
+3. Migration requires 2 sprints + testing
+4. Approve budget for contractor support
+```
+
+### Heading Levels
+
+| Level | Purpose | Example |
+|-------|---------|---------|
+| H1 | Document title | One per document |
+| H2 | Major sections | 3-7 per document |
+| H3 | Subsections | 2-5 per H2 |
+| H4+ | Avoid if possible | Indicates need to split |
+
+**Rule:** If you need H4, consider whether that section should be its own document.
+
+---
+
+## Section Boundaries
+
+### When to Create a New Section
+
+- Topic changes completely
+- Audience might skip to this part
+- Content could be read independently
+- Length exceeds comfortable scroll
+
+### When NOT to Create a New Section
+
+- You have only one paragraph to put in it
+- The heading restates what the content says
+- You're creating symmetry for aesthetics
+
+```
+// BAD: Section for one sentence
+## Timeline
+The project will complete in Q2.
+
+## Budget
+The budget is $50,000.
+
+// GOOD: Combined when brief
+## Timeline and Budget
+The project completes in Q2 with a $50,000 budget.
+```
+
+---
+
+## Lists vs. Prose
+
+### Use Lists When
+
+- Items are parallel (same type of thing)
+- Order matters (steps, priority)
+- Reader needs to scan quickly
+- Items will be referenced later ("see item 3")
+
+### Use Prose When
+
+- Ideas need connection and flow
+- Nuance matters more than speed
+- Narrative builds an argument
+- List would have only 2 items
+
+```
+// BAD: Prose that should be a list
+The system supports three authentication methods.
+First, users can log in with email and password.
+Second, they can use SSO through Okta.
+Third, they can authenticate via API key.
+
+// GOOD: List for parallel items
+The system supports three auth methods:
+- Email/password
+- SSO (Okta)
+- API key
+
+// BAD: List that should be prose
+- The feature was requested by customers
+- It aligns with our Q2 goals
+- Engineering confirmed feasibility
+
+// GOOD: Prose for connected argument
+Customers requested this feature, it aligns with Q2 goals,
+and engineering confirmed it's feasible within the sprint.
+```
+
+---
+
+## Document Length
+
+### Right-Sizing by Type
+
+| Type | Target Length | Max Before Split |
+|------|---------------|------------------|
+| Exec summary | 5-12 lines | 1 page |
+| Email | 3-5 paragraphs | 1 scroll |
+| PRD | 2-5 pages | 10 pages |
+| Technical doc | As needed | When sections exceed 3 pages |
+| Work item | Fits in view | When scrolling required |
+
+### Signals You Need to Split
+
+- Table of contents would help
+- Readers need different sections for different purposes
+- Sections could have different owners
+- Updates to one part don't affect others
+
+### Signals to Keep Together
+
+- Context from early sections needed throughout
+- Reader must understand A before B makes sense
+- Splitting creates duplication
+
+---
+
+## Structural Anti-Patterns
+
+### The Intro-Body-Conclusion Trap
+
+```
+// BAD: School essay structure
+Introduction: This document will discuss...
+Body: [content]
+Conclusion: In conclusion, this document discussed...
+
+// GOOD: Get to it
+[Point]
+[Support]
+[Action/Decision]
+```
+
+### The Symmetric Sections Trap
+
+Don't force sections to match length or structure. If one section needs 5 paragraphs and another needs 2 sentences, that's fine.
+
+### The Nested List Trap
+
+```
+// BAD: Over-nested
+- Category A
+  - Subcategory A1
+    - Item A1a
+    - Item A1b
+  - Subcategory A2
+    - Item A2a
+
+// GOOD: Flatten or use headings
+## Category A
+
+**Subcategory A1:** Item A1a, Item A1b
+
+**Subcategory A2:** Item A2a
+```
+
+---
+
+## Quick Reference
+
+| Principle | Application |
+|-----------|-------------|
+| Point first | Lead with the conclusion |
+| Scannable layers | Title → Headings → Bold → Body |
+| Headings as outline | Should tell story without body |
+| Right-size sections | Split when purpose diverges |
+| Lists for parallel | Prose for connected |

package/skills/wickedizer/refs/voice-profile.md

@@ -0,0 +1,125 @@
+---
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+# Voice Profile: Team Writing Style
+
+This reference defines the default voice for wickedizer output. Apply these characteristics unless the context requires a different tone (e.g., marketing copy, legal docs). Teams can customize this profile in their local settings.
+
+## Core Attributes
+
+**Direct** - Lead with the point, not the setup. No throat-clearing.
+
+**Practical** - Focus on what to do, not abstract possibilities.
+
+**Outcome-driven** - Every paragraph should move toward a decision, action, or answer.
+
+**Scannable** - Structure for readers who skim first, read second.
+
+## Opening Stance
+
+Start with **one direct sentence** stating what this is and why it matters.
+
+**Do:**
+- Bold **1-3 key words** (nouns, not verbs) in the opening sentence only
+- State the what and why in the same breath
+- Get to the point in the first line
+
+**Don't:**
+- Bold random acronyms or technical terms without context
+- Open with context or background
+- Use "This document describes..." or similar meta-openers
+
+### Examples
+
+**Before:**
+> In today's rapidly evolving digital landscape, organizations are increasingly recognizing the critical importance of implementing robust authentication mechanisms to protect sensitive data and ensure compliance with regulatory requirements.
+
+**After:**
+> **JWT authentication** replaces session tokens across all public APIs, reducing auth latency by 40% and eliminating session storage costs.
+
+## Tone Calibration
+
+### What to Avoid
+
+| Pattern | Why It Fails |
+|---------|--------------|
+| "Journey" | Vague, no destination |
+| "Exciting" | Performative, not informative |
+| "Pivotal" / "Transformative" | Inflation without evidence |
+| "Leverage" | Verb that hides the action |
+| "Drive" / "Enable" | Same - what specifically? |
+| "Comprehensive" / "Robust" | Claims need proof |
+
+### What Works
+
+| Instead of | Use |
+|------------|-----|
+| "Leverage our platform" | "Use X to do Y" |
+| "Drive engagement" | "Send 3 follow-up emails" |
+| "Enable teams" | "Teams can now..." |
+| "Comprehensive solution" | List what it actually covers |
+| "Robust architecture" | "Handles 10k rps, auto-scales" |
+
+## Preference Stack
+
+When choosing between options, prefer in this order:
+
+1. **Specific recommendations** over hypothetical explorations
+2. **Solutions** over "platforms" (unless source requires "platform")
+3. **Concrete verbs** over vague ones
+4. **Numbers** over adjectives
+5. **Next steps** over generic optimism
+
+## Sentence Structure
+
+**Vary cadence** - Mix short punchy sentences with longer explanatory ones. Avoid the AI trap of making every sentence the same rhythm.
+
+**Front-load meaning** - Put the subject and verb early. Don't bury the point in a subordinate clause.
+
+**One idea per sentence** - If you need "and" twice, split it.
+
+## Paragraph Shape
+
+- 2-4 sentences typical
+- Longer paragraphs need a reason (complex argument, narrative flow)
+- Single-sentence paragraphs work for emphasis but use sparingly
+
+## Ending Strong
+
+**Close with substance**, not sentiment.
+
+**Good closers:**
+- Decision required + deadline
+- Next steps with owners
+- Open question that blocks progress
+- Measurable outcome or success criteria
+
+**Avoid:**
+- "Looking forward to..."
+- "Excited about the future..."
+- "This is just the beginning..."
+- Any sentence that could end any document
+
+## Adapting Voice by Medium
+
+The core voice stays constant but intensity adjusts:
+
+| Medium | Adaptation |
+|--------|------------|
+| Exec summary | Maximum compression, decisions prominent |
+| Technical doc | Rigor matters, precision over brevity |
+| Work item | Scannable, constraints explicit |
+| Slack message | Conversational but still direct |
+| Code comment | Terse, explain why not what |
+
+## When to Break These Rules
+
+Voice guidelines are defaults, not laws. Override when:
+
+- **Source material is intentionally casual** - match it
+- **Audience expects formal tone** - legal, compliance, external
+- **Marketing context** - energy and enthusiasm appropriate
+- **Creative content** - narrative or persuasive writing
+
+The goal is credibility and clarity, not rigid adherence.

package/skills/workflow/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: workflow
+description: |
+  Reference for how the wicked-crew workflow engine operates — phase catalog, gate enforcement,
+  rigor tiers, and facilitator rubric. Use when understanding or troubleshooting crew phase
+  mechanics (gate config, CONDITIONAL resolution, phase dependencies).
+  NOT for starting a project (use crew:start) or proposing a process plan (use propose-process).
+context: fork
+
+**Plain:** wicked-crew v6 — propose-process rubric picks phases and rigor tier;
+gates are hard enforcement; two interaction modes (normal / yolo).
+phase_relevance: ["*"]
+archetype_relevance: ["*"]
+---
+
+# Workflow Skill (v6)
+
+Facilitator-rubric orchestration with hard quality gates.
+
+## Decision Engine — `wicked-garden:propose-process`
+
+```
+User project description
+        │
+        ▼
+propose-process facilitator
+  ├── Score 9 risk factors (0-3 each)
+  ├── Read agents/**/*.md frontmatter → pick specialists
+  ├── Pick phases from phases.json catalog
+  ├── Set rigor_tier (minimal / standard / full)
+  └── Emit process-plan.md + full task chain
+```
+
+All phase selection is judgment-driven by the facilitator, not rule-based.
+
+## Interaction Modes
+
+| Mode | How | Effect |
+|------|-----|--------|
+| **normal** | Default | Each phase gate requires explicit user approval before advancing |
+| **yolo** | `/wicked-garden:crew:auto-approve` | Auto-advance through gates; gates still run, findings still logged |
+
+## Rigor Tiers
+
+| Tier | Complexity | Gates | Reviewers |
+|------|-----------|-------|-----------|
+| **minimal** | 0-2 | Advisory — gate findings logged but do not block | Single reviewer |
+| **standard** | 3-5 | Enforced — REJECT blocks advancement | Single reviewer |
+| **full** | 6-7 | Enforced — REJECT blocks; multi-reviewer | 2+ reviewers |
+
+Security or compliance signals override to **full** regardless of complexity.
+
+## Phase Plan
+
+```
+clarify → design → [challenge?] → [test-strategy?] → build → test → review
+```
+
+Brackets = optional phases. The facilitator picks which phases apply based on
+factor readings. `phases.json` defines gate config per phase (min_gate_score,
+valid_skip_reasons, depends_on).
+
+### Phase Summary
+
+| Phase | Goal | Key deliverable |
+|-------|------|-----------------|
+| **clarify** | Define success criteria | Outcome statement + success criteria |
+| **design** | Architect solution | Architecture docs + approach |
+| **challenge** | Adversarial stress-test | Challenge findings + revised design |
+| **test-strategy** | Define test approach pre-build | Test scenarios + risk assessment |
+| **build** | Implement | Working implementation |
+| **test** | Verify | Test results + convergence evidence |
+| **review** | Multi-perspective validation | Review findings + sign-off |
+
+## Gate Enforcement (v2.5.0+)
+
+Gates are hard enforcement — not advisory — at standard and full rigor.
+
+| Verdict | Effect |
+|---------|--------|
+| **APPROVE** | Phase advances |
+| **CONDITIONAL** | `conditions-manifest.json` written; verify before next phase |
+| **REJECT** | Blocks advancement; mandatory rework |
+
+CONDITIONAL auto-resolution (AC-4.4): spec gap conditions → fixed inline.
+Intent-changing conditions → escalate to user or council.
+
+Gate reviewer assignment happens at approve time, not at phase start. Banned
+reviewer values: `just-finish-auto`, `fast-pass`, `auto-approve-*`.
+
+Build depends on design (`depends_on: ["clarify", "design"]`). To migrate
+legacy beta.3 projects: the `adopt-legacy` migration guide was removed in v9 — v6 is the baseline.
+
+## Specialist Discovery
+
+Crew discovers specialists by reading `agents/**/*.md` frontmatter directly at
+runtime. No static `enhances` map. Fallback agents (facilitator, researcher,
+implementer, reviewer) handle phases when no specialist matches.
+
+## Convergence Tracking (build/test phases)
+
+Artifact states: `Designed → Built → Wired → Tested → Integrated → Verified`.
+The `convergence-verify` gate flips REJECT → APPROVE only when every tracked
+artifact reaches `Integrated`. Stalls at threshold 3 sessions surface as findings.
+
+## Commands Reference
+
+| Command | Purpose |
+|---------|---------|
+| `/wicked-garden:crew:start` | Begin project — invokes propose-process |
+| `/wicked-garden:crew:status` | View current phase and engaged specialists |
+| `/wicked-garden:crew:execute` | Run current phase |
+| `/wicked-garden:crew:approve` | Advance phase after gate |
+| `/wicked-garden:crew:just-finish` | Autonomous completion (yolo-equivalent) |
+| `/wicked-garden:crew:gate` | Run a specific quality gate |
+| `/wicked-garden:crew:evidence` | Query evidence for a task |
+| `/wicked-garden:crew:auto-approve` | Switch to auto-advance mode |
+
+## Storage
+
+| Store | What |
+|-------|------|
+| Native tasks | TaskCreate/TaskUpdate with validated `metadata` (see `scripts/_event_schema.py`) |
+| `wicked-brain:memory` | Cross-session learning at project completion and gate failures |
+| Local JSON | DomainStore fallback; always available |
+
+## Refs (load on demand)
+
+- [Evidence Tracking](refs/evidence.md) — evidence tiers L1-L4, artifact naming
+- [Integration Details](refs/integration.md) — mem, search, wicked-bus usage
+- [Scoring Rubric](refs/scoring-rubric.md) — **HISTORICAL v5 only**; see propose-process for v6
+- [Risk Dimension Signals](refs/risk-dimension-signals.md) — signal keywords per factor