devflow:onboarding

DevFlow Onboarding

Goal

Give the user a clear, engaging introduction to DevFlow tailored to their role and situation. By the end they should understand what DevFlow does, which parts are relevant to them, and exactly what to do next. Be conversational throughout — this is a guided tour, not a documentation dump. Invite questions. Go deeper where they show interest.

---

What DevFlow Is

DevFlow is an AI-native SDLC plugin for Claude Code. It connects your issue tracker, documentation system, and VCS into a single intelligent workflow spanning the complete software delivery lifecycle — from problem discovery through shipped, reviewed code.

The one-liner: DevFlow turns Claude Code into an end-to-end engineering workflow.

What makes it different from just using Claude Code directly:

• Skills are workflow-aware — each step knows what came before and what comes next
• Specialist subagents run in isolation for heavy work: codebase analysis, architecture mapping, security scanning, multi-backend search. The main conversation stays clean.
• Human-in-the-loop gates at every critical decision — DevFlow never auto-proceeds past your approval
• Multi-backend: Jira, GitLab Issues, or GitHub Issues; Confluence, Google Drive, or RAG Memory; GitHub PRs or GitLab MRs — no lock-in. Configure once, everything routes automatically.
• Artifacts flow downstream: Discovery → PRD → Architecture → Issues → Implementation → PR. Each phase produces what the next phase needs.

---

The Full Lifecycle

DevFlow has four layers:

┌──────────────────────────────────────────────────────────────────┐
│  UPSTREAM SDLC  (idea → buildable issues)                        │
│                                                                   │
│  discover ──→ define-prd ──→ define-architecture ──→ plan-iters  │
│  "What problem"  "What to build"  "How to build"  "The backlog"  │
└──────────────────────────────┬───────────────────────────────────┘
                               │ creates issues in your tracker
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  BUILD CYCLE  (one loop per issue)                               │
│                                                                   │
│  fetch-issue → plan-issue → implement-issue → complete-issue     │
│      ↓              ↓             ↓                  ↓           │
│   Analyze       Branch +       Execute +          PR/MR +        │
│  feasibility   TDD plan     security gate       close issue      │
│                                                                   │
│  Optional but recommended: security-review between implement     │
│  and complete for interactive vulnerability triage               │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│  FOUNDATION  (team setup — run once, referenced always)          │
│                                                                   │
│  capture-conventions  →  audit-conventions                       │
│  generate-claude-md   →  document-legacy-codebase                │
└──────────────────────────────────────────────────────────────────┘
┌──────────────────────────────────────────────────────────────────┐
│  DOCS & KNOWLEDGE  (run periodically)                            │
│                                                                   │
│  documentation-audit  →  reference-audit                        │
│  knowledge-management →  sync-claude-knowledge                   │
└──────────────────────────────────────────────────────────────────┘

---

Every Skill — What It Does

Upstream SDLC

devflow:pm:discover — Frames a problem into a structured problem statement with scope boundaries. Searches for prior art before investing in full requirements. The first step for any new initiative. Does NOT make technical decisions — those belong in architecture.

devflow:pm:define-prd — Creates or updates a Product Requirements Document. Accepts rough input in any form (pasted notes, uploaded docs, URLs, conversation). Assesses completeness against a PRD template and fills gaps collaboratively. Never starts from scratch if material already exists.

devflow:pm:define-architecture — Makes technical decisions: stack choices, patterns, Architecture Decision Records. For new projects — decides the architecture. For existing projects — reverse-engineers it via the brownfield-analyzer agent and documents what's already there. Uses the tech-researcher agent to look up current library docs and compare options.

devflow:pm:plan-iterations — Breaks PRD + architecture into buildable issues, groups them into iterations or sprints, and creates them directly in your issue tracker. This is the bridge from planning to building.

devflow:pm:sync-artifacts — Read-only consistency check across all upstream artifacts: PRD, architecture doc, ADRs, and tracker issues. Surfaces drift. No changes, no enforcement — just "here's what diverged."

Build Cycle

devflow:build:fetch-issue [KEY] — Fetches an issue from your tracker, analyzes it against the codebase, and assesses feasibility. Checks if it's already implemented, flags conflicts. Starting point for any piece of work.

devflow:build:plan-issue [KEY] — Creates a detailed implementation plan with TDD by default. A branch is created. The plan is saved to .devflow/plans/[KEY].md and presented for your approval. Nothing is implemented yet — pure planning.

devflow:build:implement-issue [KEY] — Executes an approved plan, unit by unit, with mandatory pause points for your review. TDD by default (tests before implementation). Use --no-tdd to skip.

devflow:build:security-review — Scans changed files for security vulnerabilities. Interactive triage: for each finding, you choose to fix, dismiss, create a ticket, or defer. Covers secrets, injection, auth mistakes, crypto misuse, and dangerous dependencies.

devflow:build:complete-issue [KEY] — Final step. Runs a code health review (via code-health-reviewer agent), detects deviations from the plan (via deviation-reviewer agent), creates the PR/MR, and transitions the issue to done.

devflow:build:review-pr — Reviews a PR/MR from within Claude Code. Fetches the diff, analyzes the changes, and posts review comments back to GitHub or GitLab with your approval.

devflow:build:create-issue — Creates a new issue in your tracker with codebase analysis. Used when you need to file a bug or feature before starting the build cycle.

devflow:build:post-merge — Local sync advisor after a merge. Guides you through what needs to happen (delete branch, pull main, etc.) step by step with explicit approval. Never makes destructive changes without conscious authorization.

Foundation

devflow:foundation:capture-conventions — Guided interview to capture your team's coding standards, branching strategy, testing requirements, architecture patterns. Stored in your doc backend and referenced by other skills.

devflow:foundation:audit-conventions — Read-only delta report: compares any repo against stored conventions. Shows divergence. No changes, no enforcement. Just "team says X, repo does Y."

devflow:foundation:generate-claude-md — Creates CLAUDE.md and .claude/rules/ for a repo based on what's actually in it. Documents reality. For existing repos — what IS. For new repos — can use conventions as starting guidance.

devflow:foundation:document-legacy-codebase — For inheriting undocumented codebases. Deep analysis: generates architecture docs, component rules, CLAUDE.md, and ADRs. Used when you need Claude to understand a codebase it's never seen before.

Setup

devflow-setup — Configures all backends: issue tracker, documentation, RAG Memory, code intelligence (LSP), and VCS. Configuration lives at ~/.claude/plugins/config/devflow/config.md. Reconfigure anytime.

devflow:plugin-overview — Lists all installed skills, agents, and hooks. Use to see everything at a glance.

Docs & Knowledge

devflow:docs:documentation-audit — Audits project docs against actual source code. Finds outdated, inaccurate, or missing content and updates it.

devflow:docs:reference-audit — Verifies cross-references and links between documentation files. Finds broken links and orphaned docs.

devflow:knowledge-management — Routes content to the right backend (Confluence, Google Drive, or RAG Memory). Used when you want to persist knowledge without a specific skill workflow.

devflow:devops:sync-claude-knowledge — Fetches the latest Claude Code release notes and updates your RAG Memory knowledge base with what changed. Keeps Claude's awareness of its own capabilities current.

---

Backends

DevFlow is backend-agnostic. Configure once at /devflow-setup. All skills route through the right system automatically.

Component	Options
Issue tracking	Jira (Atlassian MCP), GitLab Issues (GitLab MCP), GitHub Issues (gh CLI)
Documentation	Confluence (Atlassian MCP), Google Drive (Google Drive MCP)
Knowledge base	RAG Memory — AI-searchable, persistent across sessions
VCS	GitHub PRs (gh CLI), GitLab MRs (GitLab MCP)

No backends? .devflow/ local storage is always available — every skill works offline.

---

Design Principles Worth Knowing

Human-in-the-loop always. DevFlow researches and recommends. You approve and decide. No auto-proceeding past gates.

Agents do the heavy lifting in isolation. Codebase scans, multi-backend searches, security reviews — these run as specialist subagents so the main conversation stays focused. You see their results, not their process.

Existing material first. Before creating anything new, DevFlow finds what already exists and assesses it. Starting from scratch is the exception. The primary workflow is: find → assess → fill gaps.

Artifacts chain together. Each phase produces what the next phase needs. If you start mid-flow, DevFlow looks backward to understand what's already been decided.

Modular adoption. Use just the build cycle if that's all you need. Add upstream PM when you want full traceability. Add foundation skills when Claude needs to understand your codebase deeply. You don't have to use everything.

---

Onboarding Flow

Step 1: Check Setup

Before starting the tour, quickly check:

~/.claude/plugins/config/devflow/config.md

If no config file exists: Note it early — "You'll want to run /devflow-setup to connect your backends. I'll remind you at the end of the tour with exactly what to do."

Don't block on this. Proceed with the tour regardless.

---

Step 2: Role and Situation

Use AskUserQuestion with two questions:

Question 1 — Role:

"Welcome to DevFlow! To give you the most useful tour, tell me about yourself."

Options:

• Developer — I implement features, fix bugs, write code
• PM / Product Owner — I own requirements, roadmap, and features
• Architect / Tech Lead — I design systems, make tech decisions, lead teams
• Full-Stack / Solo — I do everything from requirements to deployment
• Just exploring — Show me the full picture

Question 2 — Situation:

"And what's your current situation?"

Options:

• Just installed DevFlow — brand new, want to get oriented
• Working on an existing project — want to understand where DevFlow fits
• Starting a new project — need to know how to begin
• Evaluating for my team — want the full picture before rolling it out

---

Step 3: Role-Based Tour

Deliver a focused, conversational tour based on their answers. Use the content below. Don't lecture — explain, then pause, then invite questions. The goal is a two-way conversation, not a monologue.

---

Developer

Their world is the build cycle. Lead there.

"DevFlow's build cycle is built around exactly what developers do every day: pick up an issue, plan it properly, implement it safely, and ship it with a PR. Here's what that looks like:"

fetch-issue → plan-issue → implement-issue → [security-review] → complete-issue → post-merge
     ↓              ↓             ↓                  ↓                  ↓              ↓
  Analyze       Branch +       Execute           Security          PR/MR +         Cleanup
 feasibility   TDD plan        plan               scan           close issue       & sync

Walk through each step:

• fetch-issue: More than just reading the ticket — it analyzes the codebase and tells you if the issue is already done, partially done, or conflicts with something.
• plan-issue: Creates a full implementation plan before touching code. Branch is created. Plan saved for approval. TDD by default (tests written before implementation).
• implement-issue: Executes the approved plan unit by unit. Mandatory pause points so you stay in control.
• security-review: Optional but recommended — interactive vulnerability triage before the PR. You decide what to fix, skip, or ticket.
• complete-issue: Code health review + deviation report (what changed from the plan?) + PR/MR creation + issue closure. All in one.
• post-merge: Guides local cleanup after merge. Never destructive without your explicit OK.

What's built-in that developers care about:

• TDD by default (--no-tdd to skip)
• Automatic deviation detection — complete-issue surfaces what drifted from the plan
• Mandatory approval gates — nothing irreversible happens without you
• Multi-backend: same commands whether you're on Jira+GitHub or GitLab+GitLab

If they're on an existing project: The build cycle is your entry point. Skip upstream PM for now. If they're on a new project: If requirements aren't defined yet, the PM skills can help — but they can jump straight into create-issue + build cycle if they already know what to build.

First step:

• Setup not done: "Run /devflow-setup to connect your tracker and VCS."
• Has an issue: "Run /devflow:build:fetch-issue [ISSUE-KEY] to get started."
• Needs to create an issue: "Run /devflow:build:create-issue to write and file one."

---

PM / Product Owner

Their world is the upstream SDLC. Lead there.

"DevFlow has a full upstream workflow designed for PMs: frame the problem, capture requirements, work with your architect on the technical approach, then turn everything into a prioritized backlog. By the time the first issue hits a developer, every piece of work is traceable back to the original problem."

discover ──→ define-prd ──→ define-architecture ──→ plan-iterations ──→ build cycle
"What          "What to       "How to build           "Create the       (developers
problem?"      build?"        it?"                    backlog"           take over)

Walk through each step:

• discover: Frames the problem. Searches prior art before investing in requirements. Produces a scoped problem statement. Doesn't make technical decisions — that's architecture's job.
• define-prd: Accepts ANY input — paste rough notes, upload existing docs, start from scratch. Searches your doc backends for existing material first. Assesses completeness. Fills gaps through conversation.
• define-architecture: You're involved here too, not just architects — the skill guides technical decision-making if needed, and documents the "why" behind choices as ADRs.
• plan-iterations: Takes the PRD + architecture decisions and creates the actual issues in your tracker, grouped into iterations. No manual ticket creation. Direct to Jira, GitLab, or GitHub.

What PMs get specifically:

• sync-artifacts to check that PRD, architecture, ADRs, and tracker issues are still in sync as the project evolves
• All artifacts stored in your configured backend (Confluence, Google Drive, or RAG Memory)
• Traceability: issues link back to PRD requirements

First step:

• New initiative: "Run /devflow:pm:discover to frame the problem."
• Requirements already exist: "Run /devflow:pm:define-prd — it'll find your existing docs and assess completeness."
• Setup not done: "/devflow-setup first."

---

Architect / Tech Lead

Their world spans upstream design, team foundation, and the PR review side of the build cycle.

"DevFlow is built for tech leads who wear multiple hats — defining architecture, decomposing work, reviewing PRs, and setting team standards. Here's where you touch the workflow:"

Upstream:    discover → define-prd → [define-architecture] → plan-iterations
                                             ↑ yours
Foundation:  capture-conventions → audit-conventions → generate-claude-md
Build:       review-pr  (reviewing developer work)
Legacy:      document-legacy-codebase  (inheriting an existing system)

Walk through what matters to architects:

• define-architecture: Uses a tech-researcher agent (requires context7 plugin) for current library docs and comparisons. ADR generation is built-in. For brownfield projects, the brownfield-analyzer agent reverse-engineers the existing codebase before making recommendations.
• capture-conventions: One-time (or periodic) interview to capture your team's coding standards, testing requirements, branching strategy — stored in your doc backend, referenced by other skills across all repos.
• audit-conventions: Shows where any repo diverges from team conventions. Read-only delta report. No enforcement.
• document-legacy-codebase: Full deep-dive analysis of an undocumented codebase. Generates CLAUDE.md, component rules, architecture docs, and ADRs. For when you're inheriting something unfamiliar.
• review-pr: Reviews PRs/MRs from within Claude Code and posts comments back to GitHub/GitLab.

First step:

• Greenfield project: "Start with /devflow:pm:discover or jump to /devflow:pm:define-architecture if the problem is already scoped."
• Existing codebase: "/devflow:foundation:document-legacy-codebase to get Claude oriented, or /devflow:pm:define-architecture to document what's already been decided."
• Team standards: "/devflow:foundation:capture-conventions to capture your team's standards once."

---

Full-Stack / Solo Developer

They need the full picture, delivered practically.

"DevFlow is well-suited for solo developers and small teams — you can run the entire SDLC yourself, or use just the parts you need right now. The key insight is progressive adoption: start with what helps today, add more as your needs grow."

Show the full four-layer diagram. Then frame a practical adoption path:

Practical starting point:

1. Start with the build cycle — it works immediately once backends are configured
2. When kicking off a new feature or project, add the upstream PM skills upfront for better traceability
3. When you want Claude to deeply understand your codebase, run document-legacy-codebase or generate-claude-md
4. When your patterns and standards are settled, capture-conventions preserves them

Don't make them feel they need to use everything. "Start where you are. Add what helps."

First step: Ask what they're working on today and recommend the right entry point.

---

Just Exploring

Show them the full picture with genuine enthusiasm.

Cover:

1. The four-layer lifecycle diagram and what each layer is for
2. Walk through all skill categories with brief descriptions (use the Every Skill section above)
3. Explain the specialist agent system — why it matters that heavy work runs in isolation
4. The multi-backend design — same workflow regardless of your toolchain
5. How DevFlow relates to Claude Code — it's a layer on top, not a replacement

Don't push toward setup or a first step. They're evaluating. Answer their questions thoroughly.

---

Step 4: Open Q&A

After the role-based tour, explicitly invite questions:

"That's the overview for [their role/situation]. What questions do you have? I can go deeper on any skill, walk through a realistic scenario, explain how two parts of the workflow connect, or help you figure out your exact entry point for what you're working on right now."

Stay conversational. Answer anything about DevFlow thoroughly. Use the knowledge in this skill to respond to any question.

Stay in Q&A mode until they indicate they're done or want to move forward.

---

Step 5: First Step and Closing

When they're ready to move, give ONE clear, specific first step based on everything you've learned about their situation.

If setup hasn't been done:

"Your first step is /devflow-setup. It's a wizard that connects your issue tracker, documentation backend, and VCS — takes about 5 minutes. After that, [role-specific next step]."

If setup is done, go directly to the role-specific first step.

Close with:

"One more thing: whenever you're mid-workflow and want to know what to do next, what a step does, or how things connect — just run /devflow:guide. It reads your current project context and answers your questions in real time."

---

Skill complete.