raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-mcp-status/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: rai-mcp-status
+description: >
+  Health overview of all registered MCP servers plus stack-aware
+  recommendations for missing capabilities. Lists servers, runs
+  health checks, detects project stack, and suggests relevant
+  servers from the governance catalog.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: on-demand
+  raise.fase: ""
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "1.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - server_name: string, optional, argument (check single server)
+  raise.outputs: |
+    - status_report: text (markdown table)
+---
+
+# MCP Status
+
+## Purpose
+
+Show the health and availability of all registered MCP servers in one view.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Explain each server's status and what it means
+- **Ha**: Show summary table, explain only issues
+- **Ri**: Table only, no explanation unless problems found
+
+## Context
+
+**When to use:** Developer wants to check if their MCP servers are working.
+
+**When to skip:** Checking a single server — use `rai mcp health <name>` directly.
+
+## Steps
+
+### Step 1: Discover Servers
+
+Run `rai mcp list` to get all registered servers.
+
+If no servers registered: "No MCP servers registered. Use `/rai-mcp-add` to add one."
+
+<verification>
+Server list retrieved (or empty state handled).
+</verification>
+
+### Step 2: Health Check Each Server
+
+For each registered server, run `rai mcp health <name>`.
+
+Collect: status (healthy/unhealthy), tool count, latency, error message (if any).
+
+<verification>
+All servers checked.
+</verification>
+
+### Step 3: Present Summary
+
+Present a markdown table:
+
+```
+MCP Server Status:
+
+| Server   | Status    | Tools | Latency | Notes        |
+|----------|-----------|-------|---------|--------------|
+| context7 | ✓ healthy | 2     | 1.2s    |              |
+| github   | ✗ error   | —     | —       | timeout      |
+
+{healthy_count}/{total_count} servers healthy.
+```
+
+If all healthy: "{count} servers, all healthy."
+
+If any unhealthy, suggest: "Run `/rai-mcp-add` to reinstall problematic servers, or check environment variables."
+
+<verification>
+Summary presented with actionable guidance for issues.
+</verification>
+
+### Step 4: Recommend Missing Capabilities
+
+Read the governance catalog at `.raise/mcp/catalog.yaml`. If catalog is missing, skip this step gracefully.
+
+**Detect project languages:**
+1. Read `work/discovery/analysis.json` if it exists — derive languages from file extensions in `components[].file`
+2. If no analysis artifact, glob for source files: `**/*.py`, `**/*.ts`, `**/*.js`, `**/*.php`, `**/*.cs`, `**/*.dart`
+3. Map extensions to languages using scanner's `EXTENSION_TO_LANGUAGE`
+
+**Filter recommendations:**
+1. For each catalog server, check `recommended_for` (note: value is either the string `all` or a list):
+   - String `all` → always recommend regardless of detected languages
+   - List of languages (e.g. `[python, typescript]`) → recommend if any detected language matches
+   - Empty list `[]` → never recommend (opt-in only, must use `/rai-mcp-add` explicitly)
+2. Exclude servers already registered in `.raise/mcp/`
+3. If no recommendations remain: skip section silently
+
+**Present recommendations:**
+
+```
+Recommended for your stack ({detected_languages}):
+
+| Server | Description                  | Add with              |
+|--------|------------------------------|-----------------------|
+| github | GitHub repository operations | /rai-mcp-add github   |
+| fetch  | HTTP fetch for web content   | /rai-mcp-add fetch    |
+
+Use /rai-mcp-add <name> to install.
+```
+
+<verification>
+Recommendations shown (or skipped if none). Already-registered servers excluded.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Status report | Displayed inline |
+| Next | Fix unhealthy servers via `/rai-mcp-add` or manual troubleshooting |
+
+## Quality Checklist
+
+- [ ] All registered servers checked (not just a subset)
+- [ ] Unhealthy servers show error details
+- [ ] Actionable guidance provided for issues
+- [ ] Empty state handled gracefully
+- [ ] Catalog read from `.raise/mcp/catalog.yaml` (graceful if missing)
+- [ ] Already-registered servers excluded from recommendations
+- [ ] Languages detected from discovery artifact or file glob fallback
+
+## References
+
+- CLI: `rai mcp list`, `rai mcp health`
+- Catalog: `.raise/mcp/catalog.yaml` (governance — known servers + stack mapping)
+- Discovery: `work/discovery/analysis.json` (stack detection source)
+- Complement: `/rai-mcp-add`, `/rai-mcp-remove`
+- Epic: E338 MCP Platform

raise_cli/skills_base/rai-problem-shape/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: rai-problem-shape
+description: >
+  Guided problem definition at portfolio level. Takes a vague business idea
+  and shapes it into a well-formed problem statement before it enters the
+  epic pipeline. Produces a Problem Brief that feeds /rai-epic-design.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: per-initiative
+  raise.fase: "0"
+  raise.prerequisites: ""
+  raise.next: "rai-epic-design"
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Problem Shape
+
+## Purpose
+
+Guide a stakeholder from a vague initiative to a well-formed problem statement in ≤10 minutes. Produces a Problem Brief that feeds `/rai-epic-design`.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all 6 steps in sequence with multiple-choice options
+- **Ha**: Adapt option labels to project domain from memory context
+- **Ri**: Facilitate multi-stakeholder problem-shaping workshops
+
+## Context
+
+**When to use:** A stakeholder has a vague initiative or idea that hasn't entered `/rai-epic-design` yet.
+
+**When to skip:** Problem is already well-defined (go to `/rai-epic-design`), or this is story-level (use `/rai-story-design`).
+
+**Inputs:** Project name (required), rough business idea.
+
+**Pipeline:** `[vague idea]` → `/rai-problem-shape` → `/rai-epic-design` → `/rai-epic-plan` → `[stories]`
+
+**Frameworks:** Impact Mapping (Adzic), Lean UX Canvas (Gothelf), SAFe Epic Hypothesis, Toyota 5 Whys.
+
+## Steps
+
+### Step 1: APUESTA — Anchor the Domain (~30s)
+
+Present multiple choice (Spanish-first):
+> "¿Qué tipo de problema crees que estás resolviendo?"
+> A) Velocidad de entrega  B) Calidad / retrabajo  C) Visibilidad / control  D) Otro
+
+If "Otro": accept free text, summarize back in one sentence, confirm.
+
+<verification>
+Domain anchored.
+</verification>
+
+### Step 2: PARA QUIÉN — Identify Stakeholder (~60s)
+
+> "¿Quién experimenta este problema directamente?"
+> A) Equipo de desarrollo  B) Área de negocio  C) Portafolio / liderazgo  D) Cliente final
+
+If multiple apply: ask which suffers most, pick one.
+
+<verification>
+Primary stakeholder identified.
+</verification>
+
+### Step 3: ESTADO ACTUAL — Describe the Gap
+
+> "Completa: **[quién] no puede [hacer qué] porque [razón]**"
+
+**Anti-solution gate:** Scan for solution-shaped language ("queremos construir", "necesitamos implementar", "la solución es", etc.). If triggered, challenge **once**:
+> "Eso suena a una solución. ¿Qué está pasando hoy sin eso?"
+
+If second response also solution-shaped: accept it, add warning flag to Brief. Do not challenge twice.
+
+<verification>
+Gap described (observable, not solution-shaped).
+</verification>
+
+### Step 4: 3 WHYS — Find Root Cause
+
+Ask exactly 3 sequential "why" questions, then name the root cause:
+> "La raíz que identificamos es: **[síntesis]**. ¿Correcto?"
+
+Confirm with stakeholder before continuing.
+
+<verification>
+Root cause named and confirmed.
+</verification>
+
+### Step 5: EARLY SIGNAL — Leading Indicator (~30s)
+
+> "¿Qué cambiaría primero en **4 semanas**?"
+> A) Métrica que mejora  B) Comportamiento que cambia  C) Proceso que desaparece  D) Queja que deja de escucharse
+
+4-week horizon forces leading indicators, not lagging KPIs.
+
+<verification>
+Concrete early signal identified.
+</verification>
+
+### Step 6: HIPÓTESIS & Save Brief
+
+Draft SAFe hypothesis: `Si [estado actual], entonces [early signal] para [stakeholder], medido por [métrica].`
+
+Present to stakeholder for corrections. Save to `work/problem-briefs/{slug}-{YYYY-MM-DD}.md` with all 6 sections.
+
+<verification>
+Brief saved. Stakeholder confirmed hypothesis.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Problem Brief | `work/problem-briefs/{slug}-{YYYY-MM-DD}.md` |
+| Next | `/rai-epic-design` (loads Brief at Step 0.7) |
+
+## Quality Checklist
+
+- [ ] Project name confirmed before starting (gate)
+- [ ] Anti-solution gate applied in Step 3 (challenge once, max)
+- [ ] Exactly 3 Whys executed (not 2, not 5)
+- [ ] Root cause confirmed by stakeholder before continuing
+- [ ] Early signal is 4-week horizon (leading, not lagging)
+- [ ] Hypothesis uses SAFe format (Si/entonces/para/medido por)
+- [ ] NEVER challenge solution language more than once — trust damages outweigh precision
+
+## References
+
+- Pipeline next: `/rai-epic-design` (Step 0.7 loads Brief)
+- Output directory: `work/problem-briefs/`
+- Frameworks: Impact Mapping, Lean UX, SAFe Hypothesis, Toyota 5 Whys
+- Research: `work/research/RES-problem-definition-frameworks/`

raise_cli/skills_base/rai-project-create/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: rai-project-create
+description: >
+  Guide greenfield project setup through conversation. Fills governance templates
+  with project-specific content and builds the knowledge graph. Use after rai init
+  on a new project.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: on-demand
+  raise.fase: ""
+  raise.prerequisites: ""
+  raise.next: "session-start"
+  raise.gate: "rai graph build produces 30+ governance nodes"
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Project Create
+
+## Purpose
+
+Guide a developer through greenfield project setup via conversation. Collect project identity, requirements, constraints, and architecture, then fill 6 governance templates. Gate: `rai graph build` produces 30+ governance nodes.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Walk through every step with explanations, confirm each doc before writing
+- **Ha**: Collect info conversationally, confirm full set before writing
+- **Ri**: Collect all info in 1-2 exchanges, write all docs, build graph
+
+## Context
+
+**When to use:** After `rai init` on a new (greenfield) project with placeholder governance templates.
+
+**When to skip:** Brownfield project with existing code → use `/rai-project-onboard`. Project not initialized → run `rai init` first.
+
+**Inputs:** Project with `rai init` completed (`governance/` exists). Developer's knowledge of what they're building.
+
+## Steps
+
+### Step 1: Verify Prerequisites
+
+```bash
+ls governance/prd.md governance/vision.md governance/guardrails.md governance/backlog.md governance/architecture/system-context.md governance/architecture/system-design.md 2>/dev/null | wc -l
+```
+
+| Result | Action |
+|--------|--------|
+| 6 files | Continue |
+| 0 files | Stop: "Run `rai init` first." |
+| Source code exists | Suggest `/rai-project-onboard` instead |
+
+Check for existing non-placeholder content — ask before overwriting.
+
+<verification>
+Governance templates exist and ready to fill.
+</verification>
+
+### Step 2: Collect Project Info (Conversational)
+
+Ask in sequence, adapting to ShuHaRi level:
+
+1. **Identity:** Project name + one-paragraph description (who, what, why)
+2. **Capabilities:** 3-5 core things it must do → decompose into 5-8 RF-XX requirements
+3. **Quality:** Testing, code quality, security, performance constraints → 5+ guardrails
+4. **Architecture:** External actors/systems, internal components, protocols
+5. **Branches:** Main branch name, development branch name (default both to `main`)
+
+<verification>
+All governance fields covered from conversation.
+</verification>
+
+### Step 3: Write 6 Governance Docs
+
+Write all docs following parser contracts exactly. Graph parsers use regex — format must match.
+
+**Parser contracts (critical):**
+- `vision.md`: Outcomes table with `| **{Bold Name}** | {description} |`. Regex: `\|\s*\*\*([^*]+)\*\*\s*\|\s*(.+?)\s*\|`
+- `prd.md`: Requirements as `### RF-XX: Title`. Regex: `^### (RF-\d+):\s*(.+)$`
+- `guardrails.md`: YAML frontmatter `type: guardrails`. Table with `| ID | Level | Guardrail | Verification | Derived from |`. ID format: `{level}-{category}-{NNN}`
+- `backlog.md`: Header `# Backlog: {name}`. Epic rows `| E{N} | ... |`
+- `system-context.md`: External interfaces table
+- `system-design.md`: Components table with responsibility and technology
+
+Update `.raise/manifest.yaml` with branch configuration.
+
+<verification>
+All 6 docs written. No placeholder content remains.
+</verification>
+
+### Step 4: Build Graph & Verify Gate
+
+```bash
+rai graph build
+rai graph query "requirement outcome guardrail" --types requirement,outcome,guardrail --limit 50
+```
+
+Need 30+ governance nodes total: requirements (~5-8), outcomes (~5-7), guardrails (~10-13), project (1), epics (~3-5).
+
+| Result | Action |
+|--------|--------|
+| 30+ nodes | Gate passed → Step 5 |
+| <30 nodes | Check format against parser contracts, fix specific doc, rebuild |
+
+<verification>
+Graph build succeeds. 30+ governance nodes extracted.
+</verification>
+
+### Step 5: Summary
+
+```
+## Project Created: {project_name}
+Governance: {N} outcomes, {N} requirements, {N} guardrails, {N} epics
+Graph: {total} governance nodes
+Next: /rai-session-start
+```
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Governance docs | `governance/` (6 files) |
+| Knowledge graph | `.raise/rai/memory/index.json` |
+| Next | `/rai-session-start` |
+
+## Quality Checklist
+
+- [ ] Prerequisites verified before collecting info (poka-yoke)
+- [ ] Parser contracts followed exactly (regex-compatible format)
+- [ ] 30+ governance nodes gate passed
+- [ ] Branch configuration saved to manifest
+- [ ] Brownfield signals detected → suggest `/rai-project-onboard`
+- [ ] NEVER overwrite existing non-placeholder governance content without asking
+
+## References
+
+- Prerequisite: `rai init`
+- Sibling: `/rai-project-onboard` (brownfield)
+- Parser sources: `src/raise_cli/governance/parsers/*.py`
+- Template sources: `src/raise_cli/rai_base/governance/*.md`
+- Next: `/rai-session-start`

raise_cli/skills_base/rai-project-onboard/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: rai-project-onboard
+description: >
+  Guide brownfield project onboarding through discovery and conversation. Analyzes
+  existing codebase, detects conventions, fills governance templates with discovered
+  and conversational content, and builds the knowledge graph. Use after rai init --detect
+  on an existing project.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: utility
+  raise.frequency: on-demand
+  raise.fase: ""
+  raise.prerequisites: "rai init --detect"
+  raise.next: "session-start"
+  raise.gate: "4-dimensional coverage gate"
+  raise.adaptable: "true"
+  raise.version: "3.0.0"
+  raise.inputs: |
+    - project_root: path, required, argument
+  raise.outputs: |
+    - governance_docs: file_path[] (governance/*.md)
+    - knowledge_graph: file_path (.raise/rai/memory/index.json)
+  raise.visibility: public
+---
+
+# Project Onboard
+
+## Purpose
+
+Guide brownfield project onboarding by combining codebase discovery with conversation. Analyze what exists, ask what code can't tell us, fill 6 governance templates. Gate: 4-dimensional coverage check.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Walk through every step, show discovery results, confirm each doc
+- **Ha**: Run discovery, present summary, collect gaps in one exchange
+- **Ri**: Discovery + 1 exchange + write all docs + build graph
+
+## Context
+
+**When to use:** After `rai init --detect` on an existing project with source code.
+
+**When to skip:** Greenfield project → `/rai-project-create`. Not initialized → `rai init --detect` first. Governance already filled.
+
+**Key difference from `/rai-project-create`:** Starts from WHAT EXISTS (discovery), then asks WHY. Create starts from WHAT YOU WANT.
+
+**Inputs:** Project with `rai init --detect` completed, existing codebase.
+
+## Steps
+
+### Step 1: Verify Prerequisites
+
+```bash
+ls .raise/manifest.yaml 2>/dev/null || echo "MISSING"
+ls governance/prd.md governance/vision.md governance/guardrails.md 2>/dev/null | wc -l
+grep -ciE "must-|should-" governance/guardrails.md 2>/dev/null || echo "0"
+```
+
+| Result | Action |
+|--------|--------|
+| Manifest + 6 files + conventions detected | Continue |
+| No manifest | Stop: "Run `rai init --detect` first." |
+| No conventions in guardrails | Suggest re-running with `--detect` flag |
+| No source code | Suggest `/rai-project-create` instead |
+
+<verification>
+Manifest exists, governance templates exist, conventions detected.
+</verification>
+
+### Step 2: Run Discovery
+
+If `/rai-discover` has not been run yet (no `work/discovery/components-validated.json`), run it now. It handles the full pipeline: detect → extract → describe → document → build graph.
+
+If already run, skip to Step 3 — discovery data is available.
+
+Also auto-read existing project documentation (README, ARCHITECTURE, CONTRIBUTING, etc.) to pre-populate governance fields. No need to ask — always read what's available.
+
+<verification>
+Discovery complete. Existing docs read.
+</verification>
+
+### Step 3: Fill Governance Gaps
+
+Present what discovery + docs already covered. Ask ONLY for unfilled fields:
+- **Vision:** description, who uses it, why it exists
+- **Capabilities:** 3-5 core things it does → 5-8 RF-XX requirements
+- **Architecture gaps:** external actors/systems, interfaces, branch model
+
+<verification>
+All governance fields covered (from discovery + docs + conversation).
+</verification>
+
+### Step 4: Write 6 Governance Docs
+
+Same parser contracts as `/rai-project-create`:
+- `vision.md`: `| **{Bold Name}** | {description} |`
+- `prd.md`: `### RF-XX: Title`
+- `guardrails.md`: MERGE detected conventions (don't overwrite), YAML frontmatter `type: guardrails`
+- `backlog.md`: `# Backlog: {name}`, `| E{N} | ... |`
+- `system-context.md`: external interfaces table
+- `system-design.md`: components from DISCOVERED modules (enriched by discovery)
+
+Update `.raise/manifest.yaml` with branch configuration.
+
+<verification>
+All 6 docs written. Detected conventions preserved in guardrails.
+</verification>
+
+### Step 5: 4-Dimensional Coverage Gate
+
+```bash
+rai graph build
+```
+
+| Gate | Check | Pass criteria |
+|------|-------|---------------|
+| G1: Governance structure | Parser-extractable content per doc | ≥2 outcomes, ≥3 RF-XX, ≥3 guardrails, ≥1 epic |
+| G2: Module coverage | Discovered modules in governance | ≥80% modules referenced |
+| G3: Doc coverage | Docs read → governance elements | 100% of docs read contributed |
+| G4: Traceability | Guardrails→RF-XX, RF-XX→body text | ≥80% linked |
+
+Present gate results. If PARTIAL (1-2 items): fix specific items. If FAIL: fix docs, rebuild.
+
+<verification>
+All 4 gate dimensions pass (or user accepts documented exceptions).
+</verification>
+
+### Step 6: Summary
+
+```
+## Project Onboarded: {project_name}
+Discovery: {N} modules, {N} components, {N} conventions
+Governance: {N} outcomes, {N} requirements, {N} guardrails, {N} epics
+Graph: {total} governance nodes
+Next: /rai-session-start
+```
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Governance docs | `governance/` (6 files) |
+| Knowledge graph | `.raise/rai/memory/index.json` |
+| Next | `/rai-session-start` |
+
+## Quality Checklist
+
+- [ ] Discovery run before asking questions (code-first, not conversation-first)
+- [ ] Existing docs checked before asking user (minimize redundant questions)
+- [ ] Detected conventions MERGED into guardrails (not overwritten)
+- [ ] Parser contracts followed exactly (same as `/rai-project-create`)
+- [ ] 4-dimensional gate checked (not just node count)
+- [ ] NEVER overwrite `guardrails.md` conventions from `--detect`
+
+## References
+
+- Prerequisite: `rai init --detect`
+- Sibling: `/rai-project-create` (greenfield)
+- Discovery: `/rai-discover` (unified pipeline)
+- Parser sources: `src/raise_cli/governance/parsers/*.py`
+- Next: `/rai-session-start`