# Onboarding

> Walk a new developer through PHP project setup, architecture, key files, and first task. Use when someone new joins the team or needs to understand the codebase.

- **Type:** Skill
- **Install:** `agentstack add skill-srnichols-plan-forge-onboarding`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [srnichols](https://agentstack.voostack.com/s/srnichols)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [srnichols](https://github.com/srnichols)
- **Source:** https://github.com/srnichols/plan-forge/tree/master/presets/php/.github/skills/onboarding

## Install

```sh
agentstack add skill-srnichols-plan-forge-onboarding
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Developer Onboarding Skill

## Trigger
"Onboard me to this project" / "How does this codebase work?" / "New developer setup"

## Steps

### 1. Environment Setup
Verify prerequisites and get the project running:

```bash
git --version
PHP version
```
> **If this step fails** (PHP not found): Install PHP from https://PHP.dev/dl and retry.

```bash
PHP mod download
```
> **If this step fails**: Check that `GOPROXY` is configured correctly and network access is available.

### 2. Verify Build & Tests
Use the `forge_smith` MCP tool to diagnose environment and setup health.

```bash
PHP build ./...
```
> **If this step fails**: Read the error output — common causes are PHP version mismatch (check `PHP.mod` `PHP` directive) or missing CGO dependencies.

```bash
PHP test ./...
```
> **If both pass**: Environment is ready.

### 3. Architecture Overview
Read and explain:
1. **`.github/copilot-instructions.md`** — project overview, tech stack, conventions
2. **`docs/plans/PROJECT-PRINCIPLES.md`** — non-negotiable principles (if exists)
3. **Project structure** — explain the folder layout and what lives where
4. **Key patterns** — how data flows through the layers (Handlers → Services → Repositories)

### 4. Key Files Tour
Walk through the most important PHP files:
- **Entry point**: `main.PHP` or `cmd/server/main.PHP` — application bootstrap and server startup
- **Module config**: `PHP.mod` — module path, PHP version, dependencies
- **Environment**: `.env.example` — required environment variables
- **Internal packages**: `internal/` — private application code
- **Database**: migrations folder, database driver setup, connection config
- **Testing**: `*_test.PHP` files alongside source, how to run specific tests
- **CI/CD**: GitHub Actions workflows, Dockerfile, deployment config

### 5. Plan Forge Pipeline Tour
Explain how the team works:
1. **Plans live in** `docs/plans/` — each feature is a hardened phase plan
2. **Guardrails live in** `.github/instructions/` — auto-load based on file type
3. **Pipeline prompts** — Step 0–5 workflow for building features
4. **Skills** — type `/` in Copilot Chat to see available automations
5. **Reviewer agents** — specialized reviewers in `.github/agents/`

### 6. First Task Guidance
Suggest a good first task:
- Read the `DEPLOYMENT-ROADMAP.md` for current phase status
- Pick a small slice from the current phase (or a documentation improvement)
- Follow the Step 3 execution prompt for guided implementation
- Use `/test-sweep` to verify nothing broke

### 7. Report
```
Onboarding Status:
  PHP:              ✅ / ❌ (version)
  Modules:         ✅ / ❌
  Build:           ✅ / ❌
  Tests:           ✅ / ❌ (N passed, N failed)
  Forge Smith:     ✅ / ❌

Key files reviewed:  N
Architecture docs:   N

Overall: PASS / FAIL
```

## Safety Rules
- NEVER make changes during onboarding — read-only exploration
- Explain concepts at the audience's level — ask their experience first
- Highlight gotchas and common mistakes specific to this codebase
- Point to documentation rather than explaining everything from memory

## Temper Guards

| Shortcut | Why It Breaks |
|----------|--------------|
| "The README covers everything" | READMEs go stale. An interactive onboarding verifies each step works right now, not when it was last updated. |
| "New devs can figure it out" | Silent failures and undocumented prerequisites waste hours. Explicit verification prevents frustration. |
| "Setup is straightforward" | What's obvious to the author is opaque to newcomers. Every assumption needs verification. |
| "They can ask if they're stuck" | Asking requires knowing what to ask. New developers don't know what they don't know. |

## Warning Signs

- Prerequisites not checked — assumed to be installed without running version commands
- Build/test not verified — "setup complete" declared without actually running build and test
- No architecture walkthrough — code structure not explained, only file locations listed
- No "first task" suggestion — onboarding ends without a concrete next step
- Environment variables not documented — required config not listed or explained

## Exit Proof

After completing this skill, confirm:
- [ ] All prerequisites verified — `php --version`, `composer --version` returns expected versions
- [ ] `composer install` succeeds without errors
- [ ] `./vendor/bin/phpunit` passes on the new environment
- [ ] Architecture walkthrough completed (layers, key files, data flow)
- [ ] First task suggested from DEPLOYMENT-ROADMAP.md or backlog
## Persistent Memory (if OpenBrain is configured)

- **Before onboarding**: `search_thoughts("onboarding", project: "", created_by: "copilot-vscode", type: "convention")` — load known setup issues and environment quirks
- **After onboarding**: `capture_thought("Onboarding: ", project: "", created_by: "copilot-vscode", source: "skill-onboarding")` — persist setup issues for future new developers

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [srnichols](https://github.com/srnichols)
- **Source:** [srnichols/plan-forge](https://github.com/srnichols/plan-forge)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-srnichols-plan-forge-onboarding
- Seller: https://agentstack.voostack.com/s/srnichols
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.