raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-epic-run/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: rai-epic-run
+description: >
+  Execute epic lifecycle phases (start → design → AR → plan → close),
+  pausing at story iteration for human-driven /rai-story-run execution.
+  Resumes from last completed phase. Delegation profile controls pause
+  behavior at natural gates.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: epic
+  raise.frequency: per-epic
+  raise.fase: ""
+  raise.prerequisites: ""
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - epic_id: string, required, argument (e.g. "E325")
+    - epic_slug: string, optional, argument (inferred from scope or prompted)
+  raise.outputs: |
+    - merge_commit: string, git
+    - retrospective: file_path (work/epics/e{N}-{name}/retrospective.md)
+---
+
+# Epic Run
+
+## Purpose
+
+Execute the epic lifecycle phases (start → design → AR → plan → close), pausing at delegation gates and at story iteration for human-driven `/rai-story-run` execution. Resumes automatically from the last completed phase.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Show phase progress, explain each skill's output, pause at both gates
+- **Ha**: Brief progress between phases, pause only when delegation says REVIEW
+- **Ri**: Minimal output, AUTO delegation, gates stop only on failure
+
+## Context
+
+**When to use:** Starting or resuming any epic. Replaces manual sequential skill and story invocation.
+
+**When to skip:** Single-phase work (e.g., only closing an already-completed epic). Individual skills remain independently invocable.
+
+## Steps
+
+### Step 0: Detect Phase
+
+Resolve the epic path from `epic_id`. Check artifacts in **reverse order** — take the most advanced phase:
+
+| Check | Condition | Resume at |
+|:-----:|-----------|-----------|
+| 4 | `### Progress Tracking` exists AND all rows Status = "Done" | **close** |
+| 3 | `### Progress Tracking` exists AND any row Status != "Done" | **stories** |
+| 2 | `scope.md` exists, no `### Progress Tracking` heading | **plan** |
+| 1 | epic directory exists, no `scope.md` | **design** |
+| 0 | (nothing) | **start** |
+
+Present: "Phase detection: resuming at **{phase}**" with context (e.g., "3/5 stories done, 2 remaining").
+
+<verification>
+Phase identified. Epic path resolved.
+</verification>
+
+### Step 1: Resolve Delegation
+
+Load developer profile from `~/.rai/developer.yaml`. Resolve delegation level:
+
+| Source | Resolution |
+|--------|-----------|
+| `delegation.overrides.rai-epic-run` | Per-skill override (highest priority) |
+| `delegation.default_level` | Explicit default |
+| `experience_level` ShuHaRi | Shu→REVIEW, Ha→NOTIFY, Ri→AUTO |
+| No profile | Default to REVIEW |
+
+Present: "Delegation: **{level}**"
+
+<verification>
+Delegation level resolved.
+</verification>
+
+### Step 2: Execute Epic Skill Chain
+
+Run each epic skill from the detected phase forward. Show `── Phase {N}/6: {skill_name} ──` between phases.
+
+| Phase | Skill | Gate after? |
+|:-----:|-------|:-----------:|
+| 1 | `/rai-epic-start {epic_id}` | — |
+| 2 | `/rai-epic-design {epic_id}` | **POST-DESIGN** |
+| 3 | `/rai-architecture-review {epic_id} epic` | **POST-AR** |
+| 4 | `/rai-epic-plan {epic_id}` | **POST-PLAN** |
+| 5 | Story iteration (see Step 3) | — |
+| 6 | `/rai-epic-close {epic_id}` | — |
+
+**Full execution rule:** For each phase, you MUST:
+1. Load the skill's SKILL.md (read the file, don't rely on memory)
+2. Execute every step in the skill's SKILL.md sequentially — no compression, no skipping
+3. Produce all artifacts the skill specifies
+4. Only then move to the next phase
+
+The orchestrator delegates — it does not summarize, compress, or shortcut individual skill behavior. A skill invoked through the orchestrator must produce the same output as when invoked standalone.
+
+<if-blocked>
+Skill fails → STOP immediately. Report which phase failed and why. Developer re-invokes `/rai-epic-run` after fixing — phase detection resumes automatically.
+</if-blocked>
+
+### Step 3: Hand Off Stories
+
+When reaching phase 5 (story iteration), read the `### Progress Tracking` table from `scope.md`:
+
+1. Parse rows — columns: Story, Size, Status, Actual, Velocity, Notes
+2. Filter rows where Status != "Done"
+3. Present in table order (plan already resolved dependencies)
+
+> **Quality rule — epic-run NEVER executes story-run.**
+> Each `/rai-story-run` must run in a fresh session/context so it can
+> fork its heavy phases via Agent tool with full context budget.
+> Running story-run inside epic-run would accumulate context across
+> stories, degrading quality in later stories — the exact problem
+> Checkpoint & Fork (ADR-043) was designed to eliminate.
+> We never operate at known lower quality levels.
+
+**Present the pending stories and STOP:**
+
+```markdown
+## Stories Ready for Execution
+
+| # | Story | Size | Status |
+|:-:|-------|:----:|--------|
+| 1 | S{N}.1 — {name} | S | Pending |
+| 2 | S{N}.2 — {name} | M | Pending |
+
+**Next:** Run each story independently with `/rai-story-run {story_id}`
+**Resume:** Re-invoke `/rai-epic-run {epic_id}` when all stories are Done → resumes at close
+```
+
+**STOP here.** Do not proceed to phase 6. Do not invoke story-run.
+The developer runs each story in a separate session with fresh context.
+When all stories are Done, re-invoking `/rai-epic-run` detects phase=close and proceeds.
+
+<verification>
+Pending stories presented. Execution paused for human-driven story iteration.
+</verification>
+
+### Step 4: Apply Delegation Gates
+
+After **phase 2 (design)**, **phase 3 (AR)**, and **phase 4 (plan)**, apply the delegation gate:
+
+| Level | Behavior |
+|-------|----------|
+| REVIEW | Present summary. Wait for explicit approval. |
+| NOTIFY | Present summary. Continue unless user intervenes. |
+| AUTO | Continue immediately. AR SIMPLIFY verdict stops regardless. |
+
+**Post-design summary:** Story count, sizes, key architectural decisions.
+**Post-AR summary:** Verdict (PASS/PASS WITH QUESTIONS/SIMPLIFY), proportionality findings, systemic heuristics (H13-H16).
+**Post-plan summary:** Milestones, story sequence, estimated timeline.
+
+If AR verdict is SIMPLIFY, STOP regardless of delegation level. Design must be revised before planning.
+
+Story iteration is a mandatory STOP — stories run in separate sessions (see Step 3).
+
+<verification>
+Gate applied. Approval received (REVIEW) or notification shown (NOTIFY/AUTO).
+</verification>
+
+### Step 5: Complete & Report
+
+After all phases, present summary: phases executed, stories completed/total, delegation level, merge target. Confirm epic merged and branch cleaned up.
+
+<verification>
+All phases complete. Epic merged.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| All epic + story artifacts | `work/epics/e{N}-{name}/` |
+| Merge commit | Development branch |
+| Patterns | `.raise/rai/memory/patterns.jsonl` |
+| Next | Next epic or release |
+
+## Quality Checklist
+
+- [ ] Phase detection checked in reverse order (most advanced first)
+- [ ] `### Progress Tracking` heading used as plan presence marker
+- [ ] Story iteration filters Status != "Done" (handles spikes naturally)
+- [ ] Each skill's SKILL.md was loaded (read from file) before execution
+- [ ] Every step in each skill executed — no compression or shortcuts
+- [ ] Gates applied at post-design, post-AR, and post-plan
+- [ ] Failure stops immediately — no cascading
+- [ ] NEVER create a state file — phase detection is git-derived only
+- [ ] NEVER skip stories or reorder them — table order is plan order
+- [ ] NEVER compress a skill's steps into a summary — execute each step fully
+- [ ] NEVER invoke story-run from epic-run — present list and STOP (ADR-043 quality rule)
+- [ ] Stories run in separate sessions with fresh context
+
+## References
+
+- Epic skills: `/rai-epic-start`, `/rai-epic-design`, `/rai-architecture-review`, `/rai-epic-plan`, `/rai-epic-close`
+- Story orchestrator: `/rai-story-run` (S325.6)
+- Delegation: `~/.rai/developer.yaml`, S325.2
+- BacklogHook: S325.4 (fires on `rai signal emit-work` in start/close)
+- Design: `s325.7-design.md` (decisions D1-D2-D3-D4)
+- F5 constraint & checkpoint protocol: E353 (ADR-043), S353.2, S353.3

raise_cli/skills_base/rai-epic-start/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: rai-epic-start
+description: >
+  Initialize an epic with scope artifacts and tracker entry.
+  Epics are logical containers — no epic branch is created.
+  Story branches are created directly from the development branch.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: epic
+  raise.frequency: per-epic
+  raise.fase: "2"
+  raise.prerequisites: ""
+  raise.next: epic-design
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "3.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - epic_id: string, required, argument
+    - epic_slug: string, required, argument
+    - dev_branch: string, required, config
+  raise.outputs: |
+    - brief: file_path, next_skill
+    - scope: file_path, next_skill
+---
+
+# Epic Start
+
+## Purpose
+
+Initialize an epic with scope artifacts and a tracker entry. Epics are logical containers (directory + tracker), not branches. Story branches are created directly from the development branch.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, verify each before proceeding
+- **Ha**: Streamline scope for well-understood epics
+- **Ri**: Integrate with release workflows and automated setup
+
+## Context
+
+**When to use:** Starting a new body of work (3-10 stories), beginning a planned epic from the backlog.
+
+**When to skip:** Small fixes or single stories (no epic needed). Continuation of existing epic.
+
+**Inputs:** Epic number (E{N}), epic name/slug, high-level objective.
+
+**Branch config:** Read `branches.development` from `.raise/manifest.yaml` for `{dev_branch}`. Default: `main`.
+
+## Steps
+
+### Step 1: Verify Development Branch
+
+Ensure on `{dev_branch}` (for creating scope artifacts):
+
+```bash
+git branch --show-current
+```
+
+| Condition | Action |
+|-----------|--------|
+| On `{dev_branch}` | Continue |
+| On other branch | `git checkout {dev_branch} && git pull` |
+
+<verification>
+On `{dev_branch}`, up to date with remote.
+</verification>
+
+### Step 2: Define Scope & Commit
+
+Create TWO artifacts:
+
+1. `work/epics/e{N}-{name}/brief.md` using `templates/brief.md` — hypothesis, success metrics, appetite, rabbit holes.
+2. `work/epics/e{N}-{name}/scope.md` — objective, in/out scope, planned stories, done criteria.
+
+Commit:
+
+```bash
+git add -A
+git commit -m "epic(e{N}): initialize {epic-name}
+
+Objective: {1-line}
+
+In scope:
+- {item 1}
+- {item 2}
+
+Co-Authored-By: Rai <rai@humansys.ai>"
+```
+
+Register epic in the backlog tracker via CLI:
+
+- **If Jira issue exists:** `rai backlog transition {JIRA_KEY} "In Progress" -a jira`
+- **If new epic (no Jira key):** `rai backlog create "{title}" -p RAISE -t Epic -l epic`
+- **Fallback (no adapter):** Edit `governance/backlog.md` directly — add or update the row with status `In Progress`.
+
+<verification>
+Scope commit on `{dev_branch}`. Epic visible in backlog.
+</verification>
+
+<if-blocked>
+Backlog file missing → create it. Row already exists → update status only.
+</if-blocked>
+
+### Step 3: Present Next Steps
+
+Show the developer:
+- Commit hash and epic directory path
+- Quick scope summary (objective + story count)
+- **Next:** `/rai-epic-design` to formalize scope and stories
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Epic Brief | `work/epics/e{N}-{name}/brief.md` |
+| Scope | `work/epics/e{N}-{name}/scope.md` |
+| Scope commit | On `{dev_branch}` |
+| Backlog entry | Tracker (Jira via `rai backlog`) or `governance/backlog.md` fallback |
+| Next | `/rai-epic-design` |
+
+## Quality Checklist
+
+- [ ] Epic Brief created from `templates/brief.md`
+- [ ] Scope commit includes objective and boundaries
+- [ ] Epic registered in tracker (`rai backlog`) or `governance/backlog.md` fallback
+- [ ] No epic branch created — epics are logical containers only
+- [ ] NEVER create epic branches — story branches go directly from `{dev_branch}`
+
+## References
+
+- Next: `/rai-epic-design`
+- Stories: `/rai-story-start` (branches from `{dev_branch}`)
+- Close: `/rai-epic-close`
+- Branch model: `CLAUDE.md` § Branch Model

raise_cli/skills_base/rai-epic-start/templates/brief.md

@@ -0,0 +1,34 @@
+---
+epic_id: "{EPIC_ID}"
+title: "{title}"
+status: "draft"
+created: "YYYY-MM-DD"
+---
+
+# Epic Brief: {title}
+
+## Hypothesis
+For [target users] who [need/pain],
+the [solution] is a [category]
+that [delivers this value].
+Unlike [current state], our solution [key differentiator].
+
+## Success Metrics
+- **Leading:** [early signal measurable in first story]
+- **Lagging:** [outcome measurable after epic complete]
+
+## Appetite
+[S/M/L] — [S=2-4 stories, M=5-7, L=8-10]
+
+## Scope Boundaries
+### In (MUST)
+- [non-negotiable 1]
+
+### In (SHOULD)
+- [nice-to-have 1]
+
+### No-Gos
+- [explicit exclusion with rationale]
+
+### Rabbit Holes
+- [attractive trap to avoid]

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

@@ -0,0 +1,176 @@
+---
+name: rai-mcp-add
+description: >
+  Guided MCP server registration. Collects intent conversationally,
+  resolves package details, and delegates to `rai mcp install` or
+  `rai mcp scaffold`. Human never constructs CLI commands.
+
+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_intent: string, optional, argument (e.g. "Context7", "GitHub MCP")
+  raise.outputs: |
+    - config_path: file_path (.raise/mcp/<name>.yaml)
+---
+
+# MCP Add
+
+## Purpose
+
+Guide a developer through MCP server registration without requiring CLI knowledge. Collect intent, resolve details conversationally, delegate to CLI.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Ask each question individually, explain what each answer means
+- **Ha**: Batch questions when context is clear, suggest defaults
+- **Ri**: One-shot if intent is unambiguous (e.g. "add Context7" → install directly)
+
+## Context
+
+**When to use:** Developer wants to add an MCP server to their project.
+
+**When to skip:** Developer already knows the exact CLI command and prefers to run it directly.
+
+## Steps
+
+### Step 1: Understand Intent
+
+Ask the developer what MCP server they want to add. Accept free-text descriptions:
+- "Context7 for documentation lookups"
+- "GitHub MCP server"
+- "a Snyk security scanner"
+- "I have a custom server running locally"
+
+If the developer provides a name as an argument (e.g. `/rai-mcp-add context7`), skip this question.
+
+<verification>
+Server intent captured.
+</verification>
+
+### Step 2: Resolve Package Details
+
+Based on the intent, determine:
+
+1. **Package type** — ask: "Is this an npm package (npx), a Python package (uvx/pip), or a locally running server?"
+2. **Package identifier** — ask for the exact package name (e.g. `@upstash/context7-mcp`, `mcp-github`)
+3. **Server name** — suggest a slug derived from the package name, let the developer override
+4. **Environment variables** — ask: "Does this server need any API keys or tokens? (e.g. GITHUB_TOKEN)"
+5. **Python module** (pip only) — ask: "What's the Python module name to run? (e.g. mcp_server_fetch)"
+
+**For known servers, read `.raise/mcp/catalog.yaml`:**
+
+If the developer's intent matches a server name in the catalog, pre-fill all fields (package, type, env, module) from the catalog entry. No need to ask questions already answered by governance data.
+
+If the catalog is missing or the server isn't in it, ask the developer for each field individually.
+
+If uncertain, ask. Never guess package names.
+
+<verification>
+All required fields collected: type, package, name, env (if any), module (if pip).
+</verification>
+
+### Step 3: Confirm Before Installing
+
+Present a summary of what will be installed:
+
+```
+I'll set up the following MCP server:
+
+  Name:    {name}
+  Package: {package}
+  Type:    {type}
+  Env:     {env_vars or "none"}
+  Config:  .raise/mcp/{name}.yaml
+
+Proceed?
+```
+
+Wait for confirmation.
+
+<verification>
+Developer confirmed installation.
+</verification>
+
+### Step 4: Install
+
+Run the appropriate CLI command:
+
+```bash
+rai mcp install {package} --type {type} --name {name} [--env {env}] [--module {module}]
+```
+
+If the config file already exists, ask whether to overwrite (adds `--force`).
+
+For a locally running server (no package to install), use scaffold instead:
+
+```bash
+rai mcp scaffold {name} --command {command} --args "{args}" [--env {env}]
+```
+
+<verification>
+CLI command executed successfully. Config file created.
+</verification>
+
+### Step 5: Report Result
+
+After installation, report:
+- Config file location
+- Health check result (healthy/unhealthy)
+- Number of tools discovered
+- List of available tools
+
+If health check failed, suggest troubleshooting:
+- Check if the package is installed correctly
+- Verify environment variables are set
+- Try `rai mcp health {name}` manually
+
+```
+✓ MCP server '{name}' added successfully!
+
+  Config:  .raise/mcp/{name}.yaml
+  Health:  healthy
+  Tools:   {count} available
+           - {tool1}
+           - {tool2}
+
+  Use `rai mcp call {name} <tool> --args '{{...}}'` to invoke tools.
+```
+
+<verification>
+Result reported. Developer knows the server is ready (or what to fix).
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| MCP config | `.raise/mcp/{name}.yaml` |
+| Next | Use the server via `rai mcp call` or reference via `server.ref` in adapters |
+
+## Quality Checklist
+
+- [ ] Intent captured before asking technical details
+- [ ] Catalog read from `.raise/mcp/catalog.yaml` for known server defaults
+- [ ] Confirmation shown before running install
+- [ ] Health check result reported
+- [ ] Available tools listed after successful install
+- [ ] NEVER require the human to know CLI syntax
+- [ ] NEVER guess package names — ask when uncertain
+
+## References
+
+- CLI: `rai mcp install`, `rai mcp scaffold`, `rai mcp health`, `rai mcp tools`
+- Catalog: `.raise/mcp/catalog.yaml` (governance — known servers + package details)
+- Complement: `/rai-mcp-remove`, `/rai-mcp-status`
+- Pattern: PAT-E-608 (CLI = agent tools, Skills = human interface)
+- Epic: E338 MCP Platform

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

@@ -0,0 +1,120 @@
+---
+name: rai-mcp-remove
+description: >
+  Safe MCP server removal with adapter dependency checking.
+  Shows registered servers, warns about references, deletes config.
+
+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 (e.g. "context7")
+  raise.outputs: |
+    - removed: boolean
+---
+
+# MCP Remove
+
+## Purpose
+
+Safely remove an MCP server from the project, checking for adapter dependencies before deletion.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Show each check step, explain dependencies found
+- **Ha**: Skip listing if server name provided, streamline confirmation
+- **Ri**: Remove immediately if no dependencies, warn only when needed
+
+## Context
+
+**When to use:** Developer wants to remove a registered MCP server.
+
+**When to skip:** Developer prefers to delete the YAML file manually.
+
+## Steps
+
+### Step 1: Identify Server
+
+If no server name provided as argument:
+
+1. List registered servers using `rai mcp list`
+2. Ask: "Which server would you like to remove?"
+
+If server name provided, verify it exists in `.raise/mcp/`.
+
+<verification>
+Target server identified and exists.
+</verification>
+
+### Step 2: Check Dependencies
+
+Search for references to this server in declarative adapter configs:
+
+```bash
+grep -rl "ref:.*{server_name}" .raise/adapters/ 2>/dev/null
+```
+
+If references found, present them:
+
+```
+⚠ Found adapters referencing '{server_name}':
+  - .raise/adapters/{adapter1}.yaml
+  - .raise/adapters/{adapter2}.yaml
+
+Removing this server will break these adapters.
+```
+
+If no references found: "No adapter dependencies found."
+
+<verification>
+Dependencies checked and reported.
+</verification>
+
+### Step 3: Confirm and Remove
+
+If dependencies exist, ask for explicit confirmation: "Remove anyway? This will break the listed adapters."
+
+If no dependencies (or confirmed), delete the config:
+
+```bash
+rm .raise/mcp/{server_name}.yaml
+```
+
+Report: "Removed .raise/mcp/{server_name}.yaml"
+
+If dependencies were found, add: "Update the listed adapters to use inline config or reference another server."
+
+<verification>
+Config file deleted. Developer informed of any follow-up actions.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Deleted config | `.raise/mcp/{name}.yaml` removed |
+| Next | Update dependent adapters if any |
+
+## Quality Checklist
+
+- [ ] Server existence verified before attempting removal
+- [ ] Adapter dependencies checked via grep
+- [ ] Explicit confirmation required when dependencies exist
+- [ ] Follow-up guidance provided for broken adapters
+- [ ] NEVER delete without checking dependencies first
+
+## References
+
+- CLI: `rai mcp list`
+- Complement: `/rai-mcp-add`, `/rai-mcp-status`
+- Adapter config: `.raise/adapters/*.yaml` (`server.ref` field)
+- Epic: E338 MCP Platform