Project Onboarding

Turn vague project ideas into locked specifications through structured AI-assisted dialogue.

Tech-agnostic by design — works with any framework or stack.

A technology-neutral skill for AI coding agents that transforms a rough idea into production-ready engineering documents — before any code is written. Asks the right questions. Never invents requirements. Never assumes your stack. Produces a traceable, locked specification that works with any framework — JavaScript, Python, Go, Rust, or anything else.

The skill asks — you decide.

Quick Install

Option 1: npx (Recommended — all platforms)

npx project-onboarding-skill

Interactive installer — choose which AI agents to install for.

Option 2: curl (Unix / macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/raindragon14/project-onboarding/v3.0.3/install.sh | bash

Option 3: PowerShell (Windows)

iwr -useb https://raw.githubusercontent.com/raindragon14/project-onboarding/v3.0.3/install.ps1 | iex

Option 4: Manual

Copy SKILL.md and references/ to your agent's skill directory:

| Agent | Global Path | Project Path | |-------|-------------|--------------| | Qwen Code | ~/.qwen/skills/project-onboarding/ | .qwen/skills/project-onboarding/ | | Claude Code | ~/.claude/skills/project-onboarding/ | .claude/skills/project-onboarding/ | | OpenCode | ~/.config/opencode/AGENTS.md | AGENTS.md | | Aider | ~/.aider.conf.yml + ~/CONVENTIONS.md | .aider.conf.yml + CONVENTIONS.md | | Cursor | — (project only) | .cursor/rules/project-onboarding.mdc |

CLI Flags (non-interactive)

# npx
npx project-onboarding-skill --all          # install for all detected agents globally
npx project-onboarding-skill --local        # install in current project only
npx project-onboarding-skill --qwen --claude # specific agents

# curl
curl -fsSL <url> | bash -s -- --all --non-interactive

# PowerShell
iwr -useb <url> | iex -Args "--all", "--non-interactive"

How It Works

  Your Idea ──► Track Selection ──► Elicitation ──► Documents ──► Validation ──► Locked Spec
     (?)           (Full/Light/     (Ask Qs,        (Generate   (Stress-     (Read-only
                    Code-only)        mirror back)    PRD, ARCH,   test)        docs)
                                                         etc.)

Three Tracks

The skill calibrates to your project's complexity:

| | Full | Light | Code-only | |---|---|---|---| | For | Production systems, multi-user, long-lived | Prototypes, internal tools, weekend projects | "Just scaffold it" | | Documents | 5 (GLOSSARY, PRD, ARCHITECTURE, BACKLOG, DECISIONS) | 2 (PRD, BACKLOG) | None | | Questions | 16 + companion skills | 6-8 | 0 | | Gates | 3 | 1 | 0 | | Validation | Adversarial (4 checks) | None | None |

The Process

1. Track Selection — Choose Full, Light, or Code-only based on project complexity
2. Elicitation — Agent asks questions, human decides. One domain at a time. Mirror back before advancing. Real-time contradiction detection catches conflicts as you answer.
3. Document Synthesis — Generate ground truth documents in order: GLOSSARY → PRD → ARCHITECTURE → BACKLOG → DECISIONS
4. Adversarial Validation (Full only) — Stress-test for contradictions, ambiguities, scope creep, and missing edge cases
5. Lock & Handoff — Documents locked via frontmatter. constraints.json generated as machine-readable ground truth.

Closed-Loop Workflow

v3.0.0 introduces a closed-loop system that bridges the gap between spec and code:

Phase 1: Elicitation ──► Phase 2: Documents ──► Phase 3: Generate ──► Phase 4: Scaffold ──► Phase 5: Validate
   (Q&A)                  (PRD, ARCH,             (constraints.json)     (project structure)   (code vs docs)
                            BACKLOG)

CLI Commands

# Install the skill
npx project-onboarding-skill

# Generate constraints.json from drafted documents
npx project-onboarding-skill generate              # auto-detects docs in cwd
npx project-onboarding-skill generate --prd=path   # explicit paths
npx project-onboarding-skill generate --docs-dir=path

# Scaffold project structure from constraints.json
npx project-onboarding-skill scaffold

# Validate code against locked documents
npx project-onboarding-skill validate              # check all
npx project-onboarding-skill validate --strict     # also naming conventions
npx project-onboarding-skill validate --json       # JSON output

# Check constraint engine
npx project-onboarding-skill engine --contradictions  # detect conflicts
npx project-onboarding-skill engine                    # dump constraints.json

Features

Constraint Engine (lib/engine.js)

• Machine-readable ground truth of all elicitation answers and decisions
• Declarative contradiction rules with runtime evaluation
• Built-in consistency checks: scale vs complexity, free tier vs paid, deadline vs stack complexity
• Custom rules can be added per project

Auto-scaffold (lib/scaffold.js)

• Tech-agnostic: Works with ANY framework (built-in examples: Next.js, Express, FastAPI, Hono, Django, React, Vue)
• Extensible template system — add custom templates for your preferred stack
• Auto-generates package.json with correct dependencies per stack
• Database schema files from ARCHITECTURE.md data schemas
• API route stubs from ARCHITECTURE.md API contracts
• Zero-logic starter files: types, signatures, test stubs
• TODO markers linking each file to its BACKLOG task

Tech Neutrality: This tool is framework-agnostic by design. Built-in templates are examples, not endorsements. See TECH-AGNOSTIC.md for details.

Continuous Validation (lib/validate.js)

• Checks: API contracts, data schemas, dependencies, folder structure, backlog stubs
• TECH_ALIASES mapping: human-readable tech names → npm package names
• Catches drift mid-sprint, not at review
• Text and JSON output formats

Constraint Generator (lib/generate-constraints.js)

• Parses PRD.md → project info, users, metrics, kill conditions, NFRs
• Parses ARCHITECTURE.md → stack table, API contracts, data schemas, trade-offs
• Parses BACKLOG.md → tasks with files, "Done when" assertions
• Auto-detects document paths or accepts explicit paths
• Runs contradiction check after generation

Trigger Phrases

Say any of these to activate the skill:

• "Start a new project"
• "Help me plan my project"
• "Let's build X"
• "I have an idea for..."
• "Initialize a project"
• "New project setup"

Documents Produced

| Document | Purpose | Status | |----------|---------|--------| | GLOSSARY.md | Shared vocabulary — prevents terminology drift | Locked | | PRD.md | Requirements, user journeys, success metrics | Locked | | ARCHITECTURE.md | Stack decisions, system design, data schemas | Locked | | BACKLOG.md | Atomic task breakdown with "Done when" assertions | Living | | DECISIONS.md | Rationale log — why we chose X over Y | Locked | | constraints.json | Machine-readable ground truth for scaffold + validate | Living | | CONTEXT.md | Session state, open decisions, technical debt | Living | | AGENT_BRIEF.md | Per-session brief for execution agents | Regenerated each session |

Companion Skills

Automatically detected domain signals load additional elicitation questions:

| Signal | Companion | Extra Questions | |--------|-----------|-----------------| | Frontend, UI, dashboard | DESIGN.md | 4 (devices, design system, complexity, a11y) | | Model serving, inference | ML/Inference | 6 (training vs inference, models, latency, infra) | | Payments, billing | Payments | 5 (processor, currencies, PCI, disputes) | | Real-time, WebSockets | Real-Time | 4 (events, connections, ordering, reconnection) |

Max 2 companions active simultaneously (Full track) or 1 (Light track).

Key Principles

• The agent asks — the human decides. No injected requirements.
• Never fill in [UNRESOLVED] items. Unresolved = human decision required.
• One domain at a time. Cognitive load management.
• Mirror back before advancing. Assumed understanding is the root of project failures.
• Surface contradictions immediately. They get more expensive every phase they survive.
• Gate skipping is track-dependent. Full track: no skips (offer downgrade). Light track: skip with acknowledgment.

Example Session

User: "Let's build a URL shortener for our marketing team."

Agent: ┌─────────────────────────────────────────────────────┐
       │  PROJECT ONBOARDING — ACTIVE                        │
       │                                                     │
       │  My role:   Lead Developer + Requirements Analyst   │
       │  Your role: Architect + Final Decision Authority    │
       │                                                     │
       │  I ask. You decide. I draft. You approve.           │
       │  Nothing is locked until you sign off.              │
       └─────────────────────────────────────────────────────┘

       Before we begin: how should I calibrate this session?

         [Full track]   — Production system, multi-user, long-lived.
         [Light track]  — Prototype, internal tool, weekend project.
         [Code-only]    — Just scaffold the boilerplate.

User: "Light track"

Agent: Great — Light track it is. Before I ask questions:
       Do you have existing notes, sketches, or documents about this project?

User: "No, fresh start."

Agent: Q1: What are we building and why?

User: "A URL shortener so our marketing team can create branded short links
       without depending on Bitly."

Agent: Got it. Q2: Who uses it?

User: "Just our marketing team — 5 people. Non-technical."

Agent: Q3: What's explicitly out of scope?

User: "Analytics dashboard, A/B testing, and API access for other teams."

Agent: Q4: Any hard constraints?

User: "Must launch before our campaign on May 1st. We're on Vercel already."

Agent: Q5: What does "done" look like?

User: "Marketing team can paste a long URL, get a short link, and it
       redirects correctly. That's it."

Agent: Q6: Open to suggestions on stack, or do you have preferences?

User: "Open to suggestions."

Agent: Based on what you've told me — internal tool, 5 users, simple CRUD,
       already on Vercel, 6 weeks to launch — I'd recommend:

       - Next.js 15 (App Router) — you're already on Vercel, zero config deploy
       - PostgreSQL (Neon) — serverless, free tier, relational for link mapping
       - Drizzle ORM — lightweight, type-safe, works great with Next.js
       - Vercel KV (Redis) — for fast redirect lookups, eliminates DB hit

       Does that align with your comfort level?

User: "Perfect, let's go."

Agent: [Mirrors back full picture → confirms → drafts PRD.md + BACKLOG.md]
       [Generates constraints.json → scaffolds project structure]
       [Runs validation → all checks pass]

Project Structure

project-onboarding/
├── SKILL.md                          # Core skill definition (v3.0.3)
├── references/
│   ├── documents.md                  # Document templates (Full + Light track)
│   └── companions.md                 # Companion skill integration guide
├── lib/
│   ├── engine.js                     # Constraint engine + contradiction detection
│   ├── scaffold.js                   # Auto-scaffold from BACKLOG
│   ├── validate.js                   # Continuous validation CLI
│   └── generate-constraints.js       # Parse docs → constraints.json
├── bin/
│   └── cli.js                        # Interactive installer + subcommands
├── install.sh                        # Unix/macOS one-liner installer
├── install.ps1                       # Windows PowerShell one-liner installer
├── AGENTS.md                         # AI agent context (auto-loaded by agents)
├── package.json                      # npm package metadata + npx entry
├── LICENSE                           # MIT
├── .gitignore
└── README.md                         # This file

For Contributors

Development

git clone https://github.com/raindragon14/project-onboarding.git
cd project-onboarding

# Test the interactive installer
node bin/cli.js

# Test individual subcommands
node bin/cli.js help
node bin/cli.js scaffold --constraints=path/to/constraints.json
node bin/cli.js validate --constraints=path/to/constraints.json
node bin/cli.js generate --docs-dir=path/to/docs
node bin/cli.js engine --contradictions --file=path/to/constraints.json

Releasing

Releases are automated via GitHub Actions. Push a tag:

git tag v3.0.3
git push origin v3.0.3

This triggers the CI workflow which:

1. Validates the skill structure
2. Publishes to npm (if configured with NPM_TOKEN secret)
3. Creates a GitHub Release with changelog

Adding Companion Skills

See references/companions.md for the pattern. Each companion defines:

1. Detection signals (keywords that trigger it)
2. Additional elicitation questions
3. Document sections it contributes to

Why This Exists

Most AI coding sessions fail because the problem isn't clear before coding starts. The agent assumes, the human doesn't correct, and three hours later you have working code for the wrong thing.

This skill inverts that dynamic:

• 20 minutes of structured onboarding saves hours of rework
• Documents are outputs of conversation, not speculative writing
• Every requirement traces back to something the human said
• Contradictions surface in onboarding, not in production
• Closed-loop validation keeps code aligned with spec as you build

A contradiction found in onboarding costs a conversation. Found in production, it costs a sprint. Found by a customer, it costs trust.

License

MIT

Credits

Built with a "agent asks, human decides" philosophy. Inspired by product management best practices, engineering RFC processes, and the painful reality that most code is built without clear requirements.