ワンクリックで
onboard
Interactive project bootstrapping — generates CLAUDE.md, VISION.md, CI workflow, forge.toml, and configures GitHub
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
メニュー
Interactive project bootstrapping — generates CLAUDE.md, VISION.md, CI workflow, forge.toml, and configures GitHub
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
Run the full forge pipeline end-to-end within this Claude Code session, processing multiple issues autonomously until a stop condition is met
Poll a PR's CI checks until all pass, any fail, or timeout — then report the result
Pick the next backlog/ready issue, claim it, and prepare a branch — without implementing it
Perform a final review check on a PR and merge it if clean, or report what's blocking
Process all open review comments on a PR: fix addressable issues, reply in-thread, create follow-up issues for deferred items
Pick an issue from the backlog, implement it in a fresh worktree, and open a PR
SOC 職業分類に基づく
| name | onboard |
| description | Interactive project bootstrapping — generates CLAUDE.md, VISION.md, CI workflow, forge.toml, and configures GitHub |
| disable-model-invocation | true |
You are onboarding a new project onto the forge autonomous development pipeline. This is an interactive, conversational process that generates high-quality, project-specific configuration and documentation. The output is not fill-in-the-blank templates — it is contextual, thoughtful content tailored to this specific project.
/onboard — Full interactive onboarding (all 6 phases)
/onboard --stack — Reconfigure tech stack only (Phase 2)
/onboard --gating — Reconfigure gating levels only (Phase 2, gating section)
/onboard --verify — Verify existing setup: check forge.toml, CLAUDE.md, VISION.md, CI, labels
Arguments: $ARGUMENTS
Six phases, each building on the previous:
| Phase | Name | Key Output |
|---|---|---|
| 1 | Identity | docs/internal/VISION.md |
| 2 | Tech Stack | forge.toml (populated), .github/workflows/ci.yml |
| 3 | Architecture | CLAUDE.md |
| 4 | Scaffolding | Surface area decisions, directory structure |
| 5 | MVP Features | Initial GitHub issues |
| 6 | GitHub Setup | Labels, branch protection, manual steps checklist |
The user can interrupt at any phase. Each phase produces a committed artifact that is useful on its own even if later phases are skipped.
Run this before anything else (full onboarding only, skip for reconfiguration modes).
gh CLIThe GitHub CLI (gh) is required for Phases 5 and 6 (creating issues, labels, branch
protection). Check if it's installed and authenticated:
gh --version 2>/dev/null
gh auth status 2>/dev/null
If gh is not installed, help the user set it up:
The GitHub CLI (gh) is required for the full onboarding experience.
It's used to create issues, configure labels, and set up branch protection.
Install it:
macOS: brew install gh
Linux: https://github.com/cli/cli/blob/trunk/docs/install_linux.md
Windows: winget install --id GitHub.cli
After installing, authenticate:
gh auth login
You can proceed with Phases 1-4 without gh, but Phases 5-6 (GitHub setup) will be
skipped. Run /onboard --verify later to finish setup.
If gh is installed but not authenticated (gh auth status fails), prompt:
gh is installed but not authenticated. Run:
gh auth login
Then re-run /onboard to continue.
If the user wants to proceed without gh, note that Phases 5 and 6 will be skipped and
they can run /onboard --verify later to finish the GitHub-dependent steps.
When a user creates a repo from the forge template, it inherits forge's commit history. The project should start with a clean slate.
Check the current git state:
git log --oneline -5 2>/dev/null
git remote -v 2>/dev/null
If the repo has forge's template history (look for commits like "chore: initial forge
template repo" or a remote pointing to rnwolfe/forge), offer to reset:
This repo was created from the forge template and still has forge's git history.
Would you like to start with a clean git history? (Recommended)
This will:
1. Remove the existing .git directory
2. Initialize a fresh git repo
3. Stage all template files as your first commit
Your files will not be modified — only the git history changes.
If the user agrees:
rm -rf .git
git init
git add -A
git commit -m "chore: initialize project from forge template
Co-Authored-By: Claude <noreply@anthropic.com>"
After resetting git history (or if the repo has no remote), offer to create a GitHub repository:
git remote -v 2>/dev/null
If no remote is configured, ask:
No GitHub remote found. Would you like to create a GitHub repository now?
I'll need:
1. Repository name (e.g., "myproject" or "org/myproject")
2. Visibility: public or private?
If the user provides the info:
# For personal repos:
gh repo create $REPO_NAME --$VISIBILITY --source=. --push
# For org repos:
gh repo create $ORG/$REPO_NAME --$VISIBILITY --source=. --push
If the user wants to skip, note that they'll need a remote configured before Phases 5-6. Phases 1-4 work fine without a remote.
If a remote already exists and points to the right repo, confirm and move on.
After the git history and remote steps above, initialize .forge/manifest.json so
forge-sync knows which version of the template this project was scaffolded from.
Fetch the current HEAD commit of the forge template:
gh api repos/rnwolfe/forge/commits/main --jq '.sha'
Then write .forge/manifest.json with that commit SHA:
# FORGE_COMMIT is the sha returned above
cat > .forge/manifest.json <<EOF
{
"template": "rnwolfe/forge",
"commit": "$FORGE_COMMIT",
"synced_at": "$(date -u +"%Y-%m-%dT%H:%M:%SZ")",
"synced_paths": [
".claude/skills/",
".claude/settings.json",
"scripts/autodev/",
".github/workflows/autodev-dispatch.yml",
".github/workflows/autodev-implement.yml",
".github/workflows/autodev-review-fix.yml",
".github/workflows/claude-code-review.yml",
".github/workflows/autodev-audit.yml",
"setup/"
]
}
EOF
If gh is not available yet, skip this step — the user can run /onboard --verify
after installing gh, or create .forge/manifest.json manually.
Commit: git add .forge/manifest.json && git commit -m "chore: initialize forge sync manifest"
--stackSkip Phase 1 (Identity). Read the existing docs/internal/VISION.md for project context,
then jump directly to Phase 2 to reconfigure the tech stack. Update forge.toml and
regenerate .github/workflows/ci.yml.
--gatingRead existing forge.toml and present the current gating configuration. Walk the user
through the four gating levels and update only the [gating] section. No other files
are modified.
--verifyRead all generated files and verify:
forge.toml has all required fields populated (non-empty)CLAUDE.md exists and contains project-specific content (not template placeholders)docs/internal/VISION.md exists.github/workflows/ci.yml exists and matches the stack in forge.toml.github/CODEOWNERS has a real username (not the placeholder)gh label list)gh api repos/$REPO/branches/$BASE/protection)Report what is configured, what is missing, and what needs manual action.
Goal: Understand what this project is, what it values, and where it is going. Generate
docs/internal/VISION.md.
Ask the user these questions. Do not dump all questions at once — ask 2-3 at a time and respond to their answers before continuing. This is a conversation, not a form.
Round 1 — What is it?
Round 2 — What does it value? 4. What are the 3-5 design principles that guide decisions? (Examples: "speed over features", "convention over configuration", "local-first", "zero dependencies".) 5. What is explicitly out of scope? What will this project never do? 6. Is there a personality or tone? (Formal/informal, playful/serious, opinionated/neutral.)
Round 3 — Where is it going? 7. What does "done" look like for a v1.0? What are the 3-5 features that constitute the minimum viable product? 8. What comes after v1.0? Are there phases or a roadmap? 9. Are there any existing decisions, constraints, or prior art that shape the architecture?
After gathering answers, generate docs/internal/VISION.md:
# [Project Name] — Vision
> [One-sentence elevator pitch from question 1]
## Identity
**What it is**: [2-3 sentence expanded description]
**Who it's for**: [Target audience from question 2]
**Why it exists**: [Problem statement from question 3]
## Design Principles
[Numbered list of 3-5 principles from question 4, each with a one-sentence explanation
of what it means in practice for this project]
1. **[Principle name]**: [What this means for decisions]
2. ...
## Out of Scope
[Explicit boundaries from question 5 — what this project will never do]
## Personality
[Tone and voice from question 6 — how the project communicates with users]
## Roadmap
### Phase 1 — Foundation
[v1.0 features from question 7]
### Phase 2 — Growth
[Post-v1.0 features from question 8]
### Phase 3 — Maturity
[Long-term direction, if the user provided any]
## Prior Art & Constraints
[From question 9 — anything that shapes the architecture from the start]
Commit: git add docs/internal/VISION.md && git commit -m "docs: add project vision"
Present the generated VISION.md to the user for review before committing. Make adjustments if they have feedback.
Goal: Populate forge.toml with the project's actual tech stack and generate a CI
workflow.
Ask the user:
Language and framework: What language(s) and framework(s) does this project use? (Go, Node/TypeScript, Python, Rust, Java, etc.)
Build and test commands: What commands build and test the project?
make build, npm run build, cargo build, go build ./..., etc.make test, npm test, cargo test, go test ./..., etc.go vet ./..., npm run lint, cargo clippy, etc.Release tooling: How are releases published?
Gating level: How much human control do you want over the pipeline?
Present the four levels clearly:
Level 1 (recommended to start): Agent implements and reviews. Human merges every PR.
Level 2: Same as Level 1, but auto-merge is enabled after human approves.
Level 3: Human reviews only for sensitive file patterns (you define which patterns).
Level 4: Fully autonomous — agent implements, reviews, and merges. Human oversight
is passive (via audit reports and issue tracking).
Recommend Level 1 for new projects. Level 4 is for mature projects with strong test coverage and well-established patterns.
Trusted users: Which GitHub usernames are authorized to trigger the pipeline by
labeling issues backlog/ready?
CODEOWNERS: Who is the primary human reviewer? (GitHub username for CODEOWNERS file.)
Protected files: Besides the defaults (CLAUDE.md, workflows, autodev scripts, forge.toml), are there other files the agent should never modify?
Read the existing forge.toml (it has all the keys with empty/default values). Update
each field based on the user's answers. Use the Edit tool to update fields in place — do
not rewrite the entire file (preserves comments and structure).
Key mappings:
[stack] section (language, build_command, test_command, lint_command)[stack] section (release_tool)[gating] section (all fields)[trust] section (trusted_users)[trust] section (human_reviewer)[protected_files] section (patterns)Also update [project] fields:
name: from Phase 1 project namerepo: ask the user for org/repo formatdescription: from Phase 1 one-sentence pitchUpdate .github/CODEOWNERS with the actual username:
* @username
Generate .github/workflows/ci.yml based on the tech stack. The CI workflow should:
push to main and on pull_requestforge.tomlforge.tomltest (branch protection references this name)Language-specific templates:
For Go:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- name: Test
run: [test_command]
- name: Build
run: [build_command]
For Node/TypeScript:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version-file: .node-version
cache: npm
- run: npm ci
- name: Lint
run: [lint_command]
- name: Test
run: [test_command]
- name: Build
run: [build_command]
For Python:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version-file: .python-version
- name: Install dependencies
run: pip install -e ".[dev]"
- name: Test
run: [test_command]
For Rust:
name: CI
on:
push:
branches: [main]
pull_request:
jobs:
test:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- uses: Swatinem/rust-cache@v2
- name: Test
run: [test_command]
- name: Build
run: [build_command]
For other languages: Generate a minimal workflow with checkout + the user's build/test commands, and note that they may need to add a setup step for their runtime.
Commit: Stage forge.toml, .github/CODEOWNERS, and .github/workflows/ci.yml.
Commit with message ci: configure tech stack and CI workflow.
Goal: Generate a comprehensive CLAUDE.md that serves as the operating manual for
both human and AI contributors.
Ask the user:
File organization: Describe the project's directory structure. What goes where? (If the project is new and has no structure yet, discuss what structure they want.)
Architecture patterns: What patterns does the codebase follow?
Testing standards: How should tests be written?
Error handling: How should errors be handled and reported?
Security rules: Any project-specific security requirements?
Development workflow: Any project-specific workflow rules beyond what forge provides?
Generate CLAUDE.md at the repository root. This file is the project's operating manual.
It should be comprehensive enough that a new contributor (human or AI) can understand the
project and contribute correctly after reading only this file.
Structure:
# [Project Name] — Operating Manual
> This is the agentic knowledge base for [project]. It captures architecture decisions,
> patterns, and development practices. It is the source of truth for how to work on
> this project.
## Project Overview
**[Project name]** — [one-sentence description from Phase 1]
- **Language**: [from Phase 2]
- **Framework**: [from Phase 2]
- [Other key tech stack details]
## Build & Test
```bash
[build_command] # Build
[test_command] # Test
[lint_command] # Lint (if applicable)
[directory tree from question 1, annotated with what goes where]
Rules:
[From question 2 — numbered list of patterns with descriptions]
[From question 3 — conventions, naming, patterns]
[From question 4 — wrapping, user-facing messages, logging]
[From question 5 — security conventions]
feat/, fix/, chore/, docs/ prefixestype: description format[Additional project-specific workflow rules from question 6]
An event-driven GitHub Actions pipeline that autonomously implements issues end-to-end. For a comprehensive architecture deep-dive with diagrams, see docs/internal/autodev-pipeline.md.
Four workflows form the core loop, plus a weekly audit:
autodev-dispatch — Runs on a configurable cron. Picks the highest-priority
backlog/ready issue, labels it agent/implementing, and triggers the implement workflow.autodev-implement — Checks out the base branch, creates a feature branch, runs
the agent to implement the issue, pushes, and opens a PR. After creating the PR, the
workflow polls for Copilot review and dispatches autodev-review-fix.autodev-review-fix — Phased review pipeline: Copilot phase (up to N iterations)
-> Claude phase -> done.claude-code-review — Triggered by agent/review-claude label or @claude mention.autodev-audit — Weekly pipeline health report filed as a GitHub issue.| Label | Meaning |
|---|---|
backlog/ready | Issue is ready for autonomous implementation |
agent/implementing | Issue is currently being implemented by an agent |
agent/review-copilot | Agent is addressing Copilot review feedback |
agent/review-claude | Agent is addressing Claude review feedback |
human/blocked | Agent hit a limit and needs human intervention |
via/actions | PR created by GitHub Actions pipeline |
via/autodev | PR created by /autodev CLI skill |
| Secret | Purpose |
|---|---|
CLAUDE_CODE_OAUTH_TOKEN | OAuth token for Claude Code agent execution |
APP_ID + APP_PRIVATE_KEY | GitHub App credentials for push/PR operations |
When creating a PR that implements a GitHub issue:
Closes #N, Fixes #N) for auto-close on merge[Start with known key files and add more as the project evolves]
| File | Purpose |
|---|---|
CLAUDE.md | This file — project operating manual |
forge.toml | Pipeline configuration |
docs/internal/VISION.md | Product vision and design principles |
docs/internal/DECISIONS.md | Architectural decision records |
**Important**: The generated CLAUDE.md must be genuinely useful — not a template with
placeholders. Every section should contain real, specific content drawn from the
conversation. If the user didn't provide enough detail for a section, ask follow-up
questions before generating.
**Commit**: `git add CLAUDE.md && git commit -m "docs: add project operating manual"`
---
## Phase 4 — Scaffolding
**Goal**: Set up the project's directory structure and any boilerplate files.
### Conversation
Based on the architecture discussion in Phase 3, ask:
1. **Existing code**: Does the project already have code, or are we starting from scratch?
- If existing: what's the current state? Anything that needs reorganization?
- If new: should we create the initial directory structure now?
2. **Boilerplate files**: Does the project need any of these?
- `.gitignore` (generate based on language from Phase 2)
- `Makefile` or equivalent task runner
- Dependency files (`go.mod`, `package.json`, `Cargo.toml`, `pyproject.toml`, etc.)
- Docker files
- Editor config (`.editorconfig`, `.vscode/settings.json`)
3. **Documentation structure**: The following are already created by forge:
- `CLAUDE.md` (Phase 3)
- `docs/internal/VISION.md` (Phase 1)
- `docs/internal/DECISIONS.md` (pre-populated)
- `docs/internal/LIFECYCLE.md` (pre-populated)
- `docs/internal/autodev-pipeline.md` (pre-populated)
- `CONTRIBUTING.md` (pre-populated)
- `README.md` (needs project-specific content)
Ask: Should we update the README.md with project-specific content now? (The template
README describes forge itself — it should be replaced with the project's own README.)
### Actions
For each decision:
- Create requested directories
- Generate requested boilerplate files
- If updating README.md, generate a project-specific version
**Commit**: `git add -A && git commit -m "chore: scaffold project structure"`
Only create files the user explicitly requests. Do not add files "just in case."
---
## Phase 5 — MVP Features
**Goal**: Create the initial set of GitHub issues that define the project's first
implementation targets.
### Conversation
1. Review the Phase 1 roadmap (v1.0 features from VISION.md).
2. For each v1.0 feature, discuss:
- Is this one issue or should it be broken into smaller issues?
- What are the acceptance criteria?
- Are there dependencies between features? (Which must be built first?)
3. Present a proposed issue list with titles, brief descriptions, and suggested labels.
Ask the user to confirm, modify, or cut issues before creating them.
### Create Issues
For each confirmed issue, create it on GitHub:
```bash
gh issue create \
--repo $REPO \
--title "$TITLE" \
--body "$(cat <<'EOF'
## Summary
[1-2 sentences: what this feature does and why it matters]
## Acceptance Criteria
- [ ] [Specific, testable criterion]
- [ ] [Another criterion]
- [ ] Tests pass
- [ ] Documentation updated (if applicable)
## Architecture Notes
[Brief notes on where this fits in the codebase — which packages/modules to create or modify]
## Dependencies
[List any issues that must be completed first, or "None"]
EOF
)" \
--label "feature"
Important: Do NOT auto-label any issues as backlog/ready. The user should apply
that label manually after reviewing each issue. This is their first quality gate.
After creating issues, print a summary:
Created N issues for [project name]:
#1: [Title]
#2: [Title]
...
Next steps:
1. Review each issue and add acceptance criteria details
2. Label issues as `backlog/ready` when they are specific enough to implement
3. The pipeline will pick them up on the next cron run (or run /autodev to start immediately)
Goal: Configure the GitHub repository for the autodev pipeline.
Run the setup script:
bash setup/setup.sh
This runs create-labels.sh and configure-branch-protection.sh idempotently.
Report the results of each step.
After the automated setup, present the manual steps the user needs to complete. These cannot be automated because they require GitHub UI access or secret management.
GitHub Setup Checklist:
Automated (done):
[x] Pipeline labels created
[x] Branch protection configured
Manual (you need to do these):
[ ] 1. Create a GitHub App for pipeline authentication
- Go to: https://github.com/settings/apps/new
- Permissions: Contents (read/write), Pull requests (read/write), Issues (read/write)
- Install the app on your repository
- Note the App ID and generate a private key
[ ] 2. Add repository secrets (Settings > Secrets and variables > Actions)
- CLAUDE_CODE_OAUTH_TOKEN: Your Claude Code OAuth token
- APP_ID: GitHub App ID from step 1
- APP_PRIVATE_KEY: GitHub App private key from step 1
[ ] 3. Enable Copilot code review
- Go to: Settings > Copilot > Code review
- Enable "Copilot code review"
[ ] 4. Enable auto-merge (if using gating level 2+)
- Go to: Settings > General > Pull Requests
- Check "Allow auto-merge"
[ ] 5. Verify CI workflow
- Push a branch and open a test PR
- Confirm the CI workflow runs and passes
[ ] 6. Test the pipeline
- Create a test issue with a simple task
- Label it `backlog/ready`
- Watch the pipeline pick it up (or manually trigger autodev-dispatch)
- Review and merge the resulting PR
- Delete the test issue after verification
[ ] 7. (Optional) Enable automatic forge template syncing
- Run: ./scripts/forge-sync.sh --install-action
- Commit and push the generated .github/workflows/forge-sync.yml
- This opens a weekly PR whenever forge has upstream updates
After presenting the checklist, offer to run /onboard --verify to check what has been
configured so far.
git commit.gh issue create.backlog/ready. That is the user's quality gate.| Situation | Action |
|---|---|
forge.toml missing | It should exist in the repo root (shipped with forge). If somehow missing, create it from the template in the forge README. |
| User wants to skip a phase | Acknowledge and skip. Each phase is independently useful. Note what they skipped so they can return to it later. |
gh CLI not installed | Walk the user through installation (brew, apt, winget). Phases 1-4 work without it. Phases 5-6 are skipped until gh is available. |
gh CLI not authenticated | Tell the user to run gh auth login. Offer to wait while they do it, or skip Phases 5-6. |
| Repo not on GitHub yet | Offer to create it via gh repo create. If the user declines, Phases 1-4 work without a remote. Skip Phases 5-6 and tell the user to return after pushing to GitHub. |
| Forge template git history present | Offer to reset with rm -rf .git && git init. Explain this only removes commit history, not files. |
| Existing CLAUDE.md conflict | Ask: replace, merge (read existing and incorporate), or skip. |
| Labels already exist | create-labels.sh is idempotent — it updates existing labels. This is safe to re-run. |
| Branch protection fails | The script handles this gracefully — it prints manual instructions if the API call fails (usually a permissions issue). |
gh repo create fails | Usually a permissions issue or name conflict. Show the error and suggest creating the repo manually via GitHub UI, then adding the remote: git remote add origin https://github.com/ORG/REPO.git && git push -u origin main. |