Project Onboard: Brownfield Onboarding

Purpose

Guide a developer through brownfield project onboarding by combining codebase discovery with conversation. Analyze what exists (structure, conventions, components), ask what code can't tell us (vision, goals, intent), then fill governance templates with parser-compatible content. Final gate: rai memory build produces 30+ governance nodes, making /rai-session-start immediately useful.

Key difference from /rai-project-create: This skill starts from WHAT EXISTS (discovery), then asks WHY. /rai-project-create starts from WHAT YOU WANT (pure conversation).

Mastery Levels (ShuHaRi)

Shu (守): Walk through every step with explanations. Show discovery results in detail. Confirm each governance doc before writing.

Ha (破): Run discovery, present summary, collect missing info in one exchange. Write all docs. Confirm before graph build.

Ri (離): Run discovery, collect intent in 1 exchange. Write all docs. Build graph. Done.

Context

When to use:

•After rai init --detect on an existing (brownfield) project
•When governance/ exists and guardrails.md has detected conventions
•When onboarding a project that already has source code

When to skip:

•Greenfield project with no source code → use /rai-project-create instead
•Project not yet initialized → run rai init --detect first
•Project already has filled governance docs (non-placeholder content)

Inputs required:

•A project with rai init --detect already completed
•The existing codebase to analyze

Output:

•6 governance docs filled with discovery + conversational content
•Knowledge graph with 30+ governance nodes
•Project ready for /rai-session-start

Steps

Step 1: Verify Prerequisites (Poka-Yoke)

Check that the project is ready for brownfield onboarding.

bash

# Verify manifest exists (raise init was run)
ls .raise/manifest.yaml 2>/dev/null || echo "MISSING: manifest"

# Verify governance templates exist
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

# Verify conventions were detected (--detect flag was used)
# guardrails.md should have non-placeholder content from raise init --detect
grep -c "must-\|should-" governance/guardrails.md 2>/dev/null || echo "0"

Decision:

•Manifest + 6 governance files + guardrails with conventions → Continue
•No manifest → STOP. Tell the user: "Run rai init --detect first."
•Manifest but guardrails are placeholders → Suggest: "Run rai init --detect (with --detect flag) to analyze your conventions first."
•No source code found → Suggest: "This looks like a greenfield project. Consider /rai-project-create instead."

Verification: Manifest exists, governance templates exist, conventions detected.

If you can't continue: No manifest → Run rai init --detect first. Always.

Step 2: Run Discovery Pipeline

Analyze the codebase structure using the discovery CLI.

bash

# Scan for code symbols
rai discover scan . -o json > /tmp/scan-result.json

# Analyze with confidence scoring and module grouping
rai discover analyze -i /tmp/scan-result.json -o json > /tmp/analysis-result.json

# Also get summary for presentation
rai discover analyze -i /tmp/scan-result.json -o summary

What you get:

•Modules with file counts, classes, functions
•Confidence scores per component
•Category groupings (core, api, models, tests, etc.)

Also load detected conventions:

bash

# Read the guardrails already generated by raise init --detect
cat governance/guardrails.md

Verification: Discovery scan and analysis completed successfully.

If you can't continue: Scan fails → Check if source files exist. Try rai discover scan . -o summary to diagnose.

Step 3: Present Discovery Summary

Present what was discovered to the user for confirmation and correction.

Display:

code

## Codebase Analysis: {project_name}

**Project type:** Brownfield ({file_count} code files)

**Detected Modules:**
| Module | Files | Classes | Functions |
|--------|-------|---------|-----------|
| {module} | {N} | {N} | {N} |

**Detected Conventions** (from `rai init --detect`):
- {convention 1 — e.g., "Type hints: 78% coverage"}
- {convention 2 — e.g., "Testing: pytest, 65% coverage"}
- {convention 3 — e.g., "Linting: ruff configured"}

**Architecture signals:**
- {signal 1 — e.g., "FastAPI app with SQLAlchemy models"}
- {signal 2 — e.g., "CLI with Typer"}

Does this look right? Anything to add or correct?

Architecture signals are inferred from discovery data — look for:

•Web frameworks (FastAPI, Flask, Django, Express, Next.js)
•ORM/database patterns (SQLAlchemy, Prisma, TypeORM)
•CLI frameworks (Typer, Click, Commander)
•Testing frameworks (pytest, jest, vitest)
•Build tools, CI patterns, deployment signals

Verification: User confirms or corrects discovery summary.

If you can't continue: User disagrees significantly → Re-run discovery with different options, or note corrections for manual inclusion.

Step 4: Collect Missing Context (What Code Can't Tell Us)

Discovery reveals structure, but not intent. Ask for what's missing.

Ask:

"I can see WHAT you built. Now tell me WHY:

•One-paragraph description — what is {project_name} for, who uses it, why it exists?

•3-5 core capabilities — what does it DO? (I'll cross-reference with what I found in the code)

•What success looks like — how do you know it's working well?"

What you need from this:

•Description paragraph (goes into vision.md Identity section)
•Core capabilities → become RF-XX requirements in prd.md (cross-referenced with discovered modules)
•Success criteria → PRD Goals section
•Key outcomes → vision.md Outcomes table

Verification: You have a description, 3-5 capabilities, and success criteria.

If you can't continue: User gives vague answer → Ask: "Who uses this? What problem does it solve for them?"

Step 5: Collect Architecture Refinements

Discovery found the components. Ask the user to confirm the bigger picture.

Ask:

"Based on the code, I see these components: {list from discovery}. Let me confirm the full picture:

•Who/what uses {project_name}? (users, other systems, APIs)

•What external systems does it talk to? (databases, APIs, services)

•Anything I missed? Components or patterns not visible in the code?"

What you need:

•External actors and systems (system-context.md)
•External interfaces with direction and protocol (system-context.md table)
•Confirmation/correction of internal components (system-design.md table — enriched with discovery data)

Verification: You have external actors, interfaces, and confirmed component list.

If you can't continue: User hasn't thought about external boundaries → Help: "If someone drew a box around {project_name}, what arrows go in and out?"

Step 5.5: Collect Branch Configuration

Ask about the project's branch model. This is stored in .raise/manifest.yaml and used by all workflow skills.

Ask:

"What's your branch model?

•Main/stable branch name — e.g., main, master

•Development/integration branch name — e.g., main, develop, dev

If you work directly on main with no separate development branch, both are main."

Defaults: If the user is unsure, default both to main (simplest model).

What you need:

•branches.main — the stable branch (default: main)
•branches.development — the integration branch (default: main)

Update manifest:

bash

# The manifest was created by rai init. Update it with branch config.
# Add to .raise/manifest.yaml:
# branches:
#   development: {dev_branch}
#   main: {main_branch}

Verification: Branch names captured. Manifest updated.

If you can't continue: User unsure → Default both to main. Can change later.

Step 6: Generate and Write Governance Docs

Write all 6 governance docs using combined discovery + conversation data. CRITICAL: Follow the exact format for each doc — the graph parsers use regex patterns to extract nodes.

IMPORTANT: For brownfield, guardrails.md was already generated by rai init --detect. In Step 6c, MERGE detected conventions with any additional guardrails from the conversation rather than overwriting.

6a: Write `governance/vision.md`

markdown

# Solution Vision: {project_name}

> Solution vision

## Identity

### Description

{One-paragraph description from Step 4}

## Outcomes

| **Outcome** | **Description** |
|-------------|-----------------|
| **{Outcome 1 Name}** | {Description from Step 4} |
| **{Outcome 2 Name}** | {Description from Step 4} |
| **{Outcome 3 Name}** | {Description from Step 4} |

IMPORTANT — Parser contract for vision.md:

•Outcomes table MUST have | **Outcome** | as header (bold first column)
•Each data row MUST be | **{Bold Name}** | {description} |
•Parser regex: \|\s*\*\*([^*]+)\*\*\s*\|\s*(.+?)\s*\|
•Aim for 3-5 outcome rows

6b: Write `governance/prd.md`

markdown

# PRD: {project_name}

> Product Requirements Document

---

## Problem

{Problem description — 2-3 sentences, informed by what you see in the code AND user's stated intent}

## Goals

{Success criteria from Step 4 — bullet list}

---

## Requirements

### RF-01: {Requirement 1 Title}

{2-3 sentence description. Cross-reference with discovered modules/components.}

### RF-02: {Requirement 2 Title}

{2-3 sentence description}

### RF-03: {Requirement 3 Title}

{2-3 sentence description}

IMPORTANT — Parser contract for prd.md:

•Each requirement MUST be ### RF-XX: Title (### heading, RF- prefix, dash-digits, colon, space, title)
•Parser regex: ^### (RF-\d+):\s*(.+)$
•Content below the heading is captured as the requirement body (up to next ### or 20 lines)
•Aim for 5-8 requirements (RF-01 through RF-08), decomposing user's 3-5 capabilities into specific requirements

6c: Write `governance/guardrails.md`

For brownfield: guardrails.md was already generated by rai init --detect with detected conventions. Read the existing content and MERGE:

•Keep all guardrails detected from conventions (they reflect actual codebase standards)
•Add any additional guardrails from the conversation (Step 4 of /rai-project-create equivalent, if user mentioned quality concerns)
•Ensure the file has proper YAML frontmatter and parser-compatible format

If the existing guardrails.md from --detect already has proper format, you may only need minor additions. Don't overwrite detected conventions.

markdown

---
type: guardrails
version: "1.0.0"
---

# Guardrails: {project_name}

> Code and architecture guardrails

---

## Guardrails Activos

### Code Quality

| ID | Level | Guardrail | Verification | Derived from |
|----|-------|-----------|--------------|--------------|
| must-code-001 | MUST | {from detected conventions} | {command} | RF-01 |
| must-code-002 | MUST | {from detected conventions} | {command} | RF-01 |

### Testing

| ID | Level | Guardrail | Verification | Derived from |
|----|-------|-----------|--------------|--------------|
| must-test-001 | MUST | {from detected conventions} | {command} | RF-01 |

IMPORTANT — Parser contract for guardrails.md:

•MUST have YAML frontmatter with type: guardrails
•Table under ### {Section Name} heading
•Table MUST have header: | ID | Level | Guardrail | Verification | Derived from |
•ID format: {level}-{category}-{NNN} (e.g., must-code-001, should-perf-001)
•Level: MUST or SHOULD
•Aim for 5-10 guardrails across 2-4 sections

6d: Write `governance/backlog.md`

markdown

# Backlog: {project_name}

> **Status**: Draft

## Epics

| ID | Epic | Status | Scope | Priority |
|----|------|--------|-------|----------|
| E1 | {First epic name} | Draft | — | P1 |
| E2 | {Second epic name} | Draft | — | P2 |

IMPORTANT — Parser contract for backlog.md:

•Header MUST be # Backlog: {project_name} (exact format)
•Epic table rows: | E{N} | Name | Status | Scope | Priority |
•Parser regex for header: ^# Backlog:\s*(.+)$
•Parser regex for epics: ^\|\s*(E\d+)\s*\|
•Aim for 2-4 epics derived from the requirements

6e: Write `governance/architecture/system-context.md`

markdown

# System Context: {project_name}

> C4 Level 1 — System Context diagram and description

## Overview

{High-level description — what is this system and who uses it? Informed by discovery + conversation.}

## Context Diagram

┌──────────┐ ┌──────────────┐ ┌──────────┐ │ {Actor} │──────►│ {project_name} │◄──────│ {System} │ │ │ │ │ │ │ └──────────┘ └──────────────┘ └──────────┘

code


## External Interfaces

| System | Direction | Protocol | Description |
|--------|-----------|----------|-------------|
| {System 1} | {Inbound/Outbound/Both} | {HTTP/CLI/SQL/etc} | {What it does} |
| {System 2} | {Direction} | {Protocol} | {Description} |

6f: Write `governance/architecture/system-design.md`

For brownfield: This doc is ENRICHED by discovery data. Components come from actual modules found in the code, not just user description.

markdown

# System Design: {project_name}

> C4 Level 2 — Container/component decomposition

## Architecture Overview

{Architecture description — synthesized from discovery analysis and user confirmation from Step 5}

## Components

| Component | Responsibility | Technology |
|-----------|---------------|------------|
| {Discovered Module 1} | {Responsibility from analysis + user} | {Detected tech} |
| {Discovered Module 2} | {Responsibility} | {Tech} |

## Key Decisions

- {Any architectural decisions from conversation or visible in code structure}

Verification: All 6 governance docs written with project-specific content. No HTML comment placeholders remain.

If you can't continue: Write fails → Check file permissions. Governance dir should be writable.

Step 7: Build Graph and Verify (Gate)

Run the graph builder and verify the 30+ node gate.

bash

rai memory build

Expected output: The build should show governance nodes extracted from each doc.

Verification gate:

bash

rai memory query "requirement outcome guardrail" --types requirement,outcome,guardrail --limit 50

Count the governance nodes. You need 30+ total across these types:

•Requirements (from prd.md): ~5-8 nodes (RF-01 through RF-08)
•Outcomes (from vision.md): ~3-5 nodes (bold-pipe table rows)
•Guardrails (from guardrails.md): ~5-13 nodes (table rows across sections)
•Project (from backlog.md): 1 node
•Epics (from backlog.md): ~2-4 nodes (table rows)
•Architecture docs don't produce individual nodes but enrich the graph context

Decision:

•30+ nodes → Gate passed. Continue to summary.
•<30 nodes → Investigate which docs didn't parse. Check format against parser contract in Step 6. Fix and rebuild.

Verification: rai memory build succeeds and produces 30+ governance nodes.

If you can't continue: Nodes too low → Most common cause is format mismatch. Check RF-XX headings, bold-pipe tables, guardrail IDs, backlog header. Fix the specific doc and rebuild.

Step 8: Summary and Next Steps

Present what was created and what to do next.

Display:

code

## Project Onboarded: {project_name}

**Discovery:**
- {N} modules analyzed, {N} components detected
- {N} conventions detected and encoded as guardrails

**Governance docs filled:**
- governance/vision.md — {N} outcomes
- governance/prd.md — {N} requirements
- governance/guardrails.md — {N} guardrails (from detected conventions + conversation)
- governance/backlog.md — {N} epics
- governance/architecture/system-context.md — context diagram + interfaces
- governance/architecture/system-design.md — {N} components (from discovery)

**Graph:** {total} governance nodes extracted

**Next steps:**
1. Run `/rai-session-start` to begin your first working session
2. Review the generated governance docs and refine as needed
3. Start your first epic with `/rai-epic-design`

Verification: Summary displayed with node counts.

If you can't continue: Everything should be done by now. If graph is still <30 nodes after fixes, proceed anyway with a warning — the user can refine docs later.

Output

Item	Destination
Filled governance docs	`governance/` (prd.md, vision.md, guardrails.md, backlog.md, architecture/)
Knowledge graph	`.raise/rai/memory/index.json` (via `rai memory build`)
Summary	Displayed to user

Notes

Parser Contract

Generated content MUST match parser regex patterns exactly. The graph parsers extract nodes from specific Markdown structures — if the format is wrong, nodes won't be extracted and the 30+ gate will fail. The contracts are identical to /rai-project-create.

Idempotency

The skill checks for existing non-placeholder content before writing. For brownfield, guardrails.md likely already has real content from --detect — merge, don't overwrite.

Brownfield vs Greenfield

This skill is for brownfield projects — existing codebases with source files. It asks "what do you already have?" first (discovery), then "what's your intent?" (conversation). For greenfield projects starting from scratch, use /rai-project-create.

Discovery Data Flow

code

rai init --detect
  → .raise/manifest.yaml (project type, file count)
  → governance/guardrails.md (detected conventions)
  → CLAUDE.md (project context)

rai discover scan + analyze
  → Modules, classes, functions, components
  → Architecture signals (frameworks, patterns)

Conversation
  → Vision, goals, requirements, success criteria
  → Architecture confirmation/refinement

Combined → 6 governance docs → rai memory build → 30+ nodes

References

•Prerequisite: rai init --detect (convention detection from S7.1)
•Discovery: rai discover scan, rai discover analyze
•Next: /rai-session-start
•Sibling: /rai-project-create (greenfield)
•Parser sources: src/rai_cli/governance/parsers/*.py
•Template sources: src/rai_cli/rai_base/governance/*.md

Project Onboard: Brownfield Onboarding

Purpose

Mastery Levels (ShuHaRi)

Context

Steps

Step 1: Verify Prerequisites (Poka-Yoke)

Step 2: Run Discovery Pipeline

Step 3: Present Discovery Summary

Step 4: Collect Missing Context (What Code Can't Tell Us)

Step 5: Collect Architecture Refinements

Step 5.5: Collect Branch Configuration

Step 6: Generate and Write Governance Docs

6a: Write governance/vision.md

6b: Write governance/prd.md

6c: Write governance/guardrails.md

6d: Write governance/backlog.md

6e: Write governance/architecture/system-context.md

6f: Write governance/architecture/system-design.md

Step 7: Build Graph and Verify (Gate)

Step 8: Summary and Next Steps

Output

Notes

Parser Contract

Idempotency

Brownfield vs Greenfield

Discovery Data Flow

References

6a: Write `governance/vision.md`

6b: Write `governance/prd.md`

6c: Write `governance/guardrails.md`

6d: Write `governance/backlog.md`

6e: Write `governance/architecture/system-context.md`

6f: Write `governance/architecture/system-design.md`