feature-init

name: feature-init description: Initialize feature-workflow for a project, or refresh CI files with --update. Creates docs/features/, .feature-workflow.yml, and optional GitHub Actions review setup. user-invocable: true

Initialize Feature Workflow

You are executing the FEATURE INIT workflow — either a one-time setup for a new project, or an update that refreshes CI files in an existing project.

Modes

Init — first time setup. Creates docs/features/, .feature-workflow.yml, and (if chosen) the GitHub Actions review workflow + prompts + API key secret.
Update — existing project. Refreshes .github/workflows/feature-review.yml and .github/review-prompt-*.md from the current plugin templates. Does not touch .feature-workflow.yml, the API key secret, or docs/features/. Use this after upgrading the plugin to pull in improved workflow/prompt logic.
Workspace — scaffold a multi-repo workspace repo (manifest + members + topology) instead of a single project. See "Workspace mode" below.

If the user said /feature-init --update or asked to "update" / "refresh" the CI files, jump to Step 3: Run Init Script with --update and skip the config gathering.

Workspace mode (`/feature-init --workspace`)

If the user invokes /feature-init --workspace (or asks to "set up a multi-repo workspace"), scaffold a workspace repo instead of a single-project init:

Ask for the GitHub org and the member repos (each as dir=owner/repo). If they're unsure, list the org's repos with gh repo list <org>.

Run the scaffolder:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/feature-init/scripts/init.py" . --workspace \
  --org <org> \
  --member <dir>=<owner/repo> [--member <dir>=<owner/repo> ...]

Tell the user to run ./scripts/clone-members.sh to pull the members in, then launch Claude from the workspace directory — every member is then in-tree, so cross-repo edits don't prompt.

The workspace is identified by its .feature-workspace.yml manifest, not its name. Single-repo features live in each member's docs/features/; cross-repo work is an epic in the workspace docs/features/. See docs/designs/2026-06-08-multi-repo-workspace.md for the full model.

Step 1: Check for Existing Setup

Check if .feature-workflow.yml exists in the project root. If it does, read it and show the current config:

"Feature workflow is already configured:

Branch prefix: <prefix>
Target branch: <target>
Reviewer:      <reviewer>

Would you like to (a) change settings, (b) refresh CI files from the latest templates (--update), or (c) do nothing?"

(a) → continue to Step 2 to gather new config.
(b) → run with --update (skip Step 2).
(c) → stop.

Step 2: Gather Configuration

$ARGUMENTS

If arguments were provided, parse them as <branch-prefix> <target-branch> (e.g., /feature-init feat/ main).

If no arguments, ask the user:

Branch prefix — what prefix do feature branches use?
- Examples: feature/, feat/, fix/, topic/
- Default: feature/
Target branch — what branch do feature PRs merge into?
- Examples: dev, develop, main, staging
- Default: dev
External reviewer — which AI reviewer should review PRs via GitHub Actions?
- gemini — uses Google's Gemini CLI via google-github-actions/run-gemini-cli
- codex — uses OpenAI's Codex CLI via openai/codex-action
- oci — calls OCI Generative AI's OpenAI-compatible chat/completions endpoint directly (no agentic CLI). Use when the reviewer must run on an OCI-served model (e.g. openai.gpt-4.1) with an OCI GenAI API key.
- none — skip CI review setup (can be added later by re-running init)
- Default: none
API key (only if reviewer is gemini, codex, or oci) — the API key for the chosen reviewer.
- For Gemini: a Google API key from https://aistudio.google.com/apikey
- For Codex: an OpenAI API key from https://platform.openai.com/api-keys
- For OCI: an OCI Generative AI API key (sk-…) from OCI Console → Analytics & AI → Generative AI → API keys.
- The key is uploaded as a GitHub repo secret (GOOGLE_API_KEY / OPENAI_API_KEY / OCI_GENAI_API_KEY) via gh secret set — it is never stored locally.
- OCI also reads two optional repo variables: OCI_GENAI_BASE_URL (default …us-ashburn-1…/openai/v1) and OCI_GENAI_MODEL (default openai.gpt-4.1). Set with gh variable set if your region/model differs.

Step 3: Run Init Script

Init mode

python3 "${CLAUDE_PLUGIN_ROOT}/skills/feature-init/scripts/init.py" . \
  --prefix "<prefix>" \
  --target "<target>" \
  --reviewer "<reviewer>" \
  --api-key "<api-key>"

The script creates:

docs/features/ directory with initial DASHBOARD.md
.feature-workflow.yml config file (includes reviewer: setting)
If reviewer configured:
- .github/workflows/feature-review.yml — GitHub Actions workflow
- .github/review-prompt-plan.md — plan review prompt
- .github/review-prompt-impl.md — implementation review prompt
- Uploads the API key as a GitHub repo secret
- Enables the repo-level "Allow GitHub Actions to approve pull requests" setting so bot approvals actually land

Update mode

python3 "${CLAUDE_PLUGIN_ROOT}/skills/feature-init/scripts/init.py" . --update

The script reads the existing reviewer from .feature-workflow.yml and refreshes only:

.github/workflows/feature-review.yml
.github/review-prompt-plan.md
.github/review-prompt-impl.md
Re-applies the bot-approval repo setting (idempotent)

It does not touch .feature-workflow.yml, the API key secret, docs/features/, or any feature documents. After it finishes, commit and push the refreshed files to the default branch so the new workflow is live.

--update overwrites the workflow YAML unconditionally. If you've customized .github/workflows/feature-review.yml locally, those edits will be replaced by the current template. Diff before committing if you have local customizations.

When to run --update: any time you upgrade the feature-workflow plugin. The workflow template carries bug fixes (e.g., v9.7.3 added a concurrency: block that prevents duplicate review comments) that only reach your project via this refresh. Plugin upgrade alone does NOT propagate to your .github/.

Step 4: Confirm

## Feature Workflow Initialized

Config: .feature-workflow.yml
  Branch prefix: <prefix>
  Target branch: <target>
  Reviewer:      <reviewer>

Feature branches will be named: <prefix><feature-id>
PRs will target: <target>

### CI Review Setup (if reviewer configured)
- Workflow: .github/workflows/feature-review.yml
- API secret: GOOGLE_API_KEY or OPENAI_API_KEY (uploaded)
- IMPORTANT: Commit and push the .github/ files to your default branch
  before creating your first feature PR.

### Next Steps
- `/feature-capture` to create your first feature
- Edit .feature-workflow.yml anytime to change settings