raise-cli 2.2.1__py3-none-any.whl

raise_cli/skills_base/rai-discover/SKILL.md

@@ -0,0 +1,167 @@
+---
+name: rai-discover
+description: >
+  Run the full codebase discovery pipeline: detect languages, extract symbols,
+  describe components, generate architecture docs, and build the knowledge graph.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: discovery
+  raise.frequency: per-project
+  raise.fase: ""
+  raise.prerequisites: "rai init --detect"
+  raise.next: "session-start"
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "1.0.0"
+  raise.visibility: public
+  raise.inputs: |
+    - project_root: path, required, argument
+    - language: string, optional, argument (auto-detected if omitted)
+  raise.outputs: |
+    - context_yaml: file_path (work/discovery/context.yaml)
+    - components_validated: file_path (work/discovery/components-validated.json)
+    - module_docs: file_path[] (governance/architecture/modules/*.md)
+    - system_docs: file_path[] (governance/architecture/*.md)
+    - graph: side_effect (rai graph build)
+---
+
+# Discover
+
+## Purpose
+
+Run the full discovery pipeline in one pass: detect languages, extract and describe components, generate architecture docs, and build the knowledge graph.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Show each phase, explain results, pause after describe + document
+- **Ha**: Auto-run detect + extract, pause at describe, auto-document if <10 modules
+- **Ri**: Full pipeline with inline approve, minimal pauses
+
+## Context
+
+**When to use:** After `rai init --detect` on an existing codebase, or when architecture changes significantly.
+
+**When to skip:** Graph is current and no structural changes since last discovery.
+
+**Inputs:** Project root with source code. Optionally specify language to limit scan.
+
+| Condition | Action |
+|-----------|--------|
+| `rai init --detect` done | Continue |
+| No `.raise/manifest.yaml` | Stop: run `rai init --detect` first |
+| Only updating docs | Use `/rai-docs-update` instead |
+
+## Steps
+
+### Step 1: Detect (auto)
+
+```bash
+rai discover scan . --output summary
+```
+
+From summary, extract languages, source directories, entry points. Write `work/discovery/context.yaml` with project name (from `pyproject.toml` → `package.json` → directory), languages, root_dirs, entry_points, detected_at.
+
+<verification>
+`work/discovery/context.yaml` created.
+</verification>
+
+### Step 2: Extract (auto)
+
+For each detected language and root directory:
+
+```bash
+rai discover scan {root_dir} --language {language} --output json | rai discover analyze --output human
+```
+
+Produces `work/discovery/analysis.json` with confidence scores, auto-categorization, and module grouping.
+
+<verification>
+`work/discovery/analysis.json` exists.
+</verification>
+
+### Step 3: Describe (HITL)
+
+Handle components by confidence tier:
+
+| Confidence | Action |
+|-----------|--------|
+| High (≥70) | Accept `auto_purpose` and `auto_category` silently — no human review |
+| Medium (40-69) | Present by module batch with LLM-suggested descriptions |
+| Low (<40) | Scale gate first, then review |
+
+**Medium flow:** Present table per module (name, kind, category, suggested purpose, score). Ask: "Approve batch? [Approve all / Edit specific]"
+
+**Low scale gate (all low AND >50):** Offer modes: A) by layer/namespace, B) user nominates key components + bulk-skip, C) auto-accept by naming pattern (`*Handler`, `*Repository`). Otherwise review individually.
+
+Write `components-draft.yaml` and export to `components-validated.json` (graph node format).
+
+<verification>
+All components described. `components-validated.json` created.
+</verification>
+
+<if-blocked>
+No symbols extracted → verify language is supported and path is correct.
+</if-blocked>
+
+### Step 4: Document (HITL)
+
+**Module docs:** For each module, write `governance/architecture/modules/{name}.md` with YAML frontmatter (type, name, purpose, status, depends_on, depended_by, components) and body (Purpose, Architecture, Key Files, Dependencies, Conventions). Detect modules by language: Python (`__init__.py`), C# (`.csproj` + namespaces), PHP (`composer.json` PSR-4).
+
+**System docs:** Generate 4 docs from governance + discovery data:
+- `system-context.md` — what, who, why, external systems (from `vision.md`)
+- `system-design.md` — layers, data flows, constraints (from `guardrails.md` + module deps)
+- `domain-model.md` — bounded contexts, context map (from module deps + components)
+- `index.md` — compact overview <2K tokens (system overview, module map, key constraints)
+
+Present for review.
+
+<verification>
+Module docs + system docs generated. Prose explains WHY, not just WHAT.
+</verification>
+
+### Step 5: Build (auto)
+
+```bash
+rai graph build
+rai graph query "module dependencies"
+```
+
+Verify module nodes in graph, no stale references. Present summary: project, components by tier, modules, graph node/edge counts.
+
+<verification>
+Graph built. Module nodes present.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Context file | `work/discovery/context.yaml` |
+| Component catalog | `work/discovery/components-validated.json` |
+| Module docs | `governance/architecture/modules/*.md` |
+| System docs | `governance/architecture/*.md` |
+| Knowledge graph | `.raise/rai/memory/index.json` |
+| Next | `/rai-session-start` or `/rai-project-onboard` |
+
+## Quality Checklist
+
+- [ ] All supported languages detected (not just primary)
+- [ ] High-confidence components auto-accepted (no unnecessary HITL)
+- [ ] Medium-confidence presented by module batch (not per-component)
+- [ ] Scale gate applied for all-low large codebases (>50 components)
+- [ ] Module frontmatter includes all required fields
+- [ ] Module prose explains WHY, not just WHAT (new contributor test)
+- [ ] Index under 2K tokens for session-loadable context
+- [ ] Graph built and verified as final step
+- [ ] NEVER include generated/build directories in root_dirs
+- [ ] NEVER generate placeholder docs for modules with no real code
+
+## References
+
+- CLI: `rai discover scan --help`, `rai discover analyze --help`
+- Graph: `rai graph build`, `rai graph query`
+- Categories: service, model, utility, handler, parser, builder, schema, command, test
+- Confidence tiers: high ≥70, medium 40-69, low <40
+- Replaces: `/rai-discover-start`, `/rai-discover-scan`, `/rai-discover-validate`, `/rai-discover-document`

raise_cli/skills_base/rai-discover-document/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: rai-discover-document
+description: >
+  Generate architecture documentation from discovery data. Produces
+  system-level docs (C4 Context + Container), per-module docs with
+  YAML frontmatter, and a compact index for AI context loading.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: discovery
+  raise.frequency: per-project
+  raise.fase: "5"
+  raise.prerequisites: discover-validate
+  raise.next: ""
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Discover Document
+
+> **Deprecated:** Use `/rai-discover` instead, which runs the full pipeline (detect → extract → describe → document → build) in one pass. This skill is kept for backward compatibility.
+
+## Purpose
+
+Generate architecture documentation from discovery data: system-level C4 docs, per-module docs with YAML frontmatter, domain model, and a compact index for AI context loading.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Generate all levels, explain each section
+- **Ha**: Targeted updates for changed modules only
+- **Ri**: Incremental regeneration, preserve human-written sections
+
+## Context
+
+**When to use:** After discover-scan + discover-validate pipeline completes, or when architecture changes significantly.
+
+**When to skip:** Minor code changes that don't affect module structure.
+
+**Inputs:** `work/discovery/components-validated.json`, source tree, governance docs (`guardrails.md`, `vision.md`, optionally `constitution.md`).
+
+## Steps
+
+### Step 1: Analyze Module Structure
+
+Check `work/discovery/context.yaml` for detected language, then for each module:
+
+| Language | Module marker | Strategy |
+|----------|--------------|----------|
+| Python | `__init__.py` | Read docstring, scan `from pkg.X import` |
+| C# | `.csproj` + namespaces | Group by top-level layer directory |
+| PHP | `composer.json` PSR-4 | Group by namespace segment |
+
+Per module: count components, build dependency map, identify entry points, list public API.
+
+<verification>
+All modules identified with dependency data.
+</verification>
+
+### Step 2: Generate Module Docs
+
+Write `governance/architecture/modules/{name}.md` per module:
+
+**YAML frontmatter:** type, name, purpose, status, depends_on, depended_by, components.
+
+**Body sections:** Purpose (2-3 sentences), Architecture, Key Files, Dependencies table, Conventions.
+
+Write genuine explanatory prose — a new contributor should understand the module's role.
+
+<verification>
+All modules have docs with valid YAML frontmatter.
+</verification>
+
+### Step 3: Generate System Docs & Index
+
+**System Context** (`system-context.md`): From `governance/vision.md` — what, who, why, external systems, non-goals.
+
+**System Design** (`system-design.md`): From `governance/guardrails.md` + module deps — layers, data flows, constraints, drift detection.
+
+**Domain Model** (`domain-model.md`): From module deps + component catalog — bounded contexts, context map, design decision guidance.
+
+**Index** (`index.md`): System overview, module map table, data flow diagram, key constraints. Target: <2K tokens.
+
+<verification>
+All 4 system-level docs exist. Index under 2K tokens.
+</verification>
+
+### Step 4: Validate & Rebuild Graph
+
+- All modules documented, frontmatter parses cleanly
+- Dependency map matches actual imports
+- Guardrails/constitution references are current
+
+```bash
+rai graph build
+rai graph query "module dependencies"
+```
+
+<verification>
+Module nodes appear in graph. No stale references.
+</verification>
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Module docs | `governance/architecture/modules/*.md` |
+| System context | `governance/architecture/system-context.md` |
+| System design | `governance/architecture/system-design.md` |
+| Domain model | `governance/architecture/domain-model.md` |
+| Index | `governance/architecture/index.md` |
+
+## Quality Checklist
+
+- [ ] Module frontmatter includes all required fields (type, name, purpose, depends_on)
+- [ ] Prose explains WHY, not just WHAT (new contributor test)
+- [ ] Index under 2K tokens for session-loadable context
+- [ ] On re-run, preserve human-edited sections (append, don't overwrite)
+- [ ] NEVER generate placeholder docs for modules with no real code
+
+## References
+
+- Previous: `/rai-discover-validate`
+- Graph builder: `src/raise_cli/context/builder.py` (`load_architecture()`)
+- Components: `work/discovery/components-validated.json`
+- Governance: `governance/guardrails.md`, `governance/vision.md`

raise_cli/skills_base/rai-discover-scan/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: rai-discover-scan
+description: >
+  Extract symbols from codebase using rai discover scan, then synthesize
+  meaningful descriptions for each component. Creates draft for human validation.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: discovery
+  raise.frequency: per-project
+  raise.fase: "2"
+  raise.prerequisites: discover-start
+  raise.next: discover-validate
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Discovery Scan
+
+> **Deprecated:** Use `/rai-discover` instead, which runs the full pipeline (detect → extract → describe → document → build) in one pass. This skill is kept for backward compatibility.
+
+## Purpose
+
+Extract symbols from the codebase and synthesize meaningful descriptions for each component. Produces a draft component catalog ready for human validation.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, synthesize descriptions for all public symbols
+- **Ha**: Filter to public APIs only; skip internal helpers automatically
+- **Ri**: Custom synthesis prompts for domain-specific codebases
+
+## Context
+
+**When to use:** After `/rai-discover-start` has created context, or for targeted scan of a specific directory.
+
+**When to skip:** `work/discovery/components-draft.yaml` exists and is current.
+
+**Inputs:** `work/discovery/context.yaml` from `/rai-discover-start`, OR explicit path argument.
+
+## Steps
+
+### Step 1: Extract Symbols
+
+```bash
+rai discover scan {root_dir} --language {language} --output json
+```
+
+<verification>
+JSON output received with symbols array.
+</verification>
+
+<if-blocked>
+Scan fails → check path exists and language is supported.
+</if-blocked>
+
+### Step 2: Run Analysis
+
+```bash
+rai discover scan {root_dir} --language {language} --output json | rai discover analyze --output human
+```
+
+Produces `work/discovery/analysis.json` with:
+- Confidence scores per component (high ≥70 / medium 40-69 / low <40)
+- Auto-categorization from path conventions and naming patterns
+- Hierarchical folding (methods grouped under parent classes)
+- Module grouping (for parallel AI synthesis batches)
+
+<verification>
+`work/discovery/analysis.json` exists with components and module_groups.
+</verification>
+
+### Step 3: Synthesize Descriptions
+
+| Confidence | Action |
+|-----------|--------|
+| High (≥70) | Use `auto_purpose` and `auto_category` — no AI synthesis needed |
+| Medium/Low | Synthesize per module group batch |
+
+**Per component synthesis:**
+1. **Purpose** — What does it do? Why does it exist? (1-2 sentences, focus on reuse value)
+2. **Category** — Verify or correct auto_category
+3. **Dependencies** — Key types from signature (specific, not generic)
+
+### Step 4: Generate IDs & Write Draft
+
+**ID pattern:** `comp-{module}-{name}` (lowercase, hyphens for underscores).
+
+Write `work/discovery/components-draft.yaml`:
+
+```yaml
+generated_at: {ISO_TIMESTAMP}
+symbol_count: {N}
+components:
+  - id: comp-scanner-symbol
+    name: Symbol
+    kind: class
+    file: src/raise_cli/discovery/scanner.py
+    line: 44
+    signature: "class Symbol(BaseModel)"
+    purpose: "Represents a code symbol extracted from source files."
+    category: model
+    depends_on: [pydantic.BaseModel]
+    internal: false
+    validated: false
+```
+
+<verification>
+File created at `work/discovery/components-draft.yaml`.
+</verification>
+
+### Step 5: Display Summary
+
+```markdown
+## Discovery Scan Complete
+
+**Scanned:** {path} | **Language:** {language} | **Symbols:** {total}
+**Categories:** Models: {N}, Services: {N}, Utilities: {N}
+**Output:** `work/discovery/components-draft.yaml`
+
+**Next:** `/rai-discover-validate`
+```
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Analysis | `work/discovery/analysis.json` |
+| Draft catalog | `work/discovery/components-draft.yaml` |
+| Next | `/rai-discover-validate` |
+
+## Quality Checklist
+
+- [ ] Synthesis focuses on reuse value (what/why, not how)
+- [ ] Categories match symbol roles (see category table below)
+- [ ] Dependencies are specific types, not generic packages
+- [ ] Large codebases (>100 symbols): scan in chunks by directory
+- [ ] NEVER describe implementation details in purpose ("Uses a loop to...")
+
+## References
+
+- Previous: `/rai-discover-start`
+- Next: `/rai-discover-validate`
+- CLI: `rai discover scan --help`, `rai discover analyze --help`
+- Categories: service, model, utility, handler, parser, builder, schema, command, test

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

@@ -0,0 +1,145 @@
+---
+name: rai-discover-start
+description: >
+  Initialize codebase discovery by detecting project type, languages, and
+  key directories. Creates context file for subsequent discovery skills.
+
+license: MIT
+
+metadata:
+  raise.work_cycle: discovery
+  raise.frequency: per-project
+  raise.fase: "1"
+  raise.prerequisites: ""
+  raise.next: discover-scan
+  raise.gate: ""
+  raise.adaptable: "true"
+  raise.version: "2.0.0"
+  raise.visibility: public
+---
+
+# Discovery Start
+
+> **Deprecated:** Use `/rai-discover` instead, which runs the full pipeline (detect → extract → describe → document → build) in one pass. This skill is kept for backward compatibility.
+
+## Purpose
+
+Initialize codebase discovery by detecting languages, key directories, and entry points. Creates the context file that all subsequent discovery skills depend on.
+
+## Mastery Levels (ShuHaRi)
+
+- **Shu**: Follow all steps, detect all languages, create complete context file
+- **Ha**: Focus on primary language only for targeted discovery
+- **Ri**: Integrate with monorepo structures or custom conventions
+
+## Context
+
+**When to use:** Starting discovery on a new or significantly changed codebase.
+
+**When to skip:** `work/discovery/context.yaml` already exists and is current. For targeted re-scan, use `/rai-discover-scan` directly with path.
+
+**Inputs:** Access to project root directory.
+
+## Steps
+
+### Step 1: Detect Languages
+
+Scan for source files by extension (exclude `.raise/`, `node_modules/`, `.git/`, `obj/`, `bin/`):
+
+```bash
+find . -type f -name "*.py" ! -path "./.raise/*" ! -path "./node_modules/*" ! -path "./.git/*" | wc -l
+# Repeat for: *.ts/*.tsx, *.js/*.jsx, *.cs/*.csproj, *.php, *.dart
+```
+
+| Language | Extensions |
+|----------|-----------|
+| python | `.py` |
+| typescript | `.ts`, `.tsx` |
+| javascript | `.js`, `.jsx` |
+| csharp | `.cs`, `.csproj` |
+| php | `.php` |
+| dart | `.dart` |
+
+<verification>
+At least one supported language detected.
+</verification>
+
+<if-blocked>
+No supported languages → discovery not applicable to this codebase.
+</if-blocked>
+
+### Step 2: Identify Directories & Entry Points
+
+**Directories:** Check for `src/`, `lib/`, `app/`, `packages/`.
+
+**Entry points** by language:
+
+| Language | Entry points |
+|----------|-------------|
+| python | `src/*/cli/main.py`, `src/*/__main__.py`, `main.py` |
+| typescript/js | `src/index.ts`, `src/main.ts`, `package.json` main field |
+| csharp | `Program.cs`, `Startup.cs`, `*.sln` |
+| php | `public/index.php`, `bin/console` |
+| dart | `lib/main.dart` |
+
+<verification>
+At least one scannable directory identified.
+</verification>
+
+<if-blocked>
+No clear source directory → ask user to specify.
+</if-blocked>
+
+### Step 3: Create Context File
+
+Write `work/discovery/context.yaml`:
+
+```yaml
+project:
+  name: {from pyproject.toml/package.json/directory name}
+  languages: [python]
+  root_dirs: [src/raise_cli]
+  entry_points: [src/raise_cli/cli/main.py]
+  detected_at: {ISO_TIMESTAMP}
+status: initialized
+```
+
+Project name priority: `pyproject.toml` → `package.json` → directory name.
+
+<verification>
+File created at `work/discovery/context.yaml`.
+</verification>
+
+### Step 4: Display Summary
+
+```markdown
+## Discovery Initialized
+
+**Project:** {name}
+**Languages:** {list}
+**Directories:** {list}
+**Entry Points:** {list}
+**Context file:** `work/discovery/context.yaml`
+
+**Next:** `/rai-discover-scan`
+```
+
+## Output
+
+| Item | Destination |
+|------|-------------|
+| Context file | `work/discovery/context.yaml` |
+| Next | `/rai-discover-scan` |
+
+## Quality Checklist
+
+- [ ] All supported languages detected (not just primary)
+- [ ] Generated directories exclude build/vendor paths
+- [ ] Context file is valid YAML with all required fields
+- [ ] Monorepo: each package listed as separate root_dir
+- [ ] NEVER include generated/build directories in root_dirs
+
+## References
+
+- Next: `/rai-discover-scan`
+- Pipeline: discover-start → discover-scan → discover-validate → discover-document