From ensemble-vnext
Initialize project with vendored ensemble runtime for AI-augmented development
How this command is triggered — by the user, by Claude, or both
Slash command
/ensemble-vnext:init-projectplugin-only/Files this command reads when invoked
The summary Claude sees in its command listing — used to decide when to auto-load this command
> **Usage:** Invoke `/init-project` from the project root to scaffold AI-augmented development infrastructure. > Optional hints: "minimal" (skip prompts, use defaults), "force" (overwrite existing) --- ## CRITICAL: Steps 1-14 Must Be Completed (Steps 15-16 are Optional) **DO NOT exit early. DO NOT skip steps. This command REQUIRES steps 1-14 to complete successfully.** The initialization is NOT complete until: - Step 9 (Deploy Configuration Files) creates `router-rules.json` - Step 12 (Update CLAUDE.md) updates placeholders with project information - Step 13 (Validation) confirms ALL re...
Usage: Invoke
/init-projectfrom the project root to scaffold AI-augmented development infrastructure. Optional hints: "minimal" (skip prompts, use defaults), "force" (overwrite existing)
DO NOT exit early. DO NOT skip steps. This command REQUIRES steps 1-14 to complete successfully.
The initialization is NOT complete until:
router-rules.jsonSteps 15-16 are optional enhancements that improve routing but are not required for a functional installation.
Common failure point: Exiting after Step 8 (Deploy Hooks) leaves the project in an incomplete state without CLAUDE.md updated. YOU MUST CONTINUE through Steps 9-14.
$ARGUMENTS
Examples:
Inline Configuration (optional): When provided after flags, use these values instead of prompting:
/init-project minimal
---
name: my-project
description: Brief project description
methodology: flexible|tdd|characterization
coverage: standard|high|minimal
approvals: [architecture, dependencies, schema, breaking-api, deployments, security]
skills: [skill1, skill2] # optional: pre-select skills
CRITICAL: When "minimal" flag is present (with or without inline config):
.claude/ directory with project-tailored components.trd-state/ directory with current.json.gitignore for proper trackinggenerate-project-router-rules for project-specific routingCheck for existing installation:
If .claude/ directory exists:
If docs/standards/constitution.md exists (legacy location):
.claude/rules/ structureIf .specify/ directory exists:
If .agent-os/ directory exists:
Current Feature Pointer Housekeeping (if .trd-state/current.json exists):
.trd-state/current.jsonbranch field matches current git branchcurrent.json to reflect current branchcurrent.jsoncurrent.json (start fresh)Agentic Repository Analysis
This is a fully agentic LLM function. You (Claude) must explore the project comprehensively using your tools to understand its structure. DO NOT rely on a predefined checklist of files - instead, discover and reason about what you find.
Phase 1: Discover Project Structure
Use Glob to discover the entire file structure:
**/*
This gives you visibility into all directories and files. Pay attention to:
src/, lib/, app/, packages/, etc.).github/, .vercel/, docker/, etc.)Phase 2: Read and Reason About What You Find
Based on the Glob results, read files that might indicate the technology stack. These are NOT limited to a predefined list - use your judgment:
Phase 3: Reason and Infer
As you read files, build understanding through reasoning:
Primary Language(s): What languages are used? Look at file extensions, dependency files, and source code.
Framework(s): What frameworks or libraries are central to the project? Reason about:
pages/ suggests Next.js or Nuxt)Testing Setup: What testing approach is used?
Database/Data Layer: What data storage is used?
Infrastructure: How is the project deployed/run?
Architecture Style: What patterns does the codebase follow?
Handle Edge Cases Agentically:
Output: Detected Stack Summary
After your agentic exploration, synthesize your findings:
Primary Language: <language>
Framework: <framework>
Testing: <unit framework>, <integration framework>, <e2e framework>
Database: <database> via <orm/driver>
Infrastructure: <hosting>, <ci-cd>
Architecture: <pattern>
Confidence: <High/Medium/Low with reasoning>
If confidence is low for any component, note what additional information would help and prepare to ask in Step 2.
If "minimal" flag is present: SKIP THIS ENTIRE STEP. Proceed directly to Step 3 using defaults from Step 1.
Otherwise, use AskUserQuestion tool to gather project-specific information:
Questions:
- "What is the project name?"
Default: <directory name>
- "Brief project description (1-2 sentences)?"
Default: <inferred from README or package.json>
Question: "What development methodology should be enforced?"
Options:
- "TDD (Test-Driven Development)" - Tests before code, RED-GREEN-REFACTOR
- "Flexible" - No strict ordering, trust developer judgment
- "Characterization-first" - For brownfield, add tests without changing code
Default: "Flexible" for existing projects, "TDD" for new projects
Question: "What test coverage targets?"
Options:
- "High (80% unit, 70% integration)" - Recommended for production systems
- "Standard (60% unit, 50% integration)" - Balanced coverage
- "Minimal (40% unit)" - Prototypes and MVPs
- "Custom" - Specify your own targets
Default: "Standard" for existing projects, "High" for new projects
Question: "What changes should require explicit approval?"
MultiSelect: true
Default: All selected
Options:
- "Architecture changes"
- "New dependencies"
- "Database schema changes"
- "Breaking API changes"
- "Production deployments"
- "Security-sensitive code"
Question: "What verification level does this project need?"
Options:
- "Unit Only" - Standard unit/integration tests are sufficient
- "Live Required" - verify-app must start services and test against running instances
- "E2E Required" - Full end-to-end testing with browser/UI automation
- "Manual Required" - Pause for user sign-off before approving
Default: "Unit Only" for libraries/CLI tools, "Live Required" for web apps
Map to constitution.md verification_level:
unit-onlylive-requirede2e-requiredmanual-requiredExecute the scaffold script using Bash tool:
Find the plugin path and run the scaffold script. The plugin path can be determined by:
ENSEMBLE_PLUGIN_DIR (if set)packages/full directory within the ensemble-vnext project~/.claude/plugins/installed_plugins.jsonRun the scaffold script:
# Determine plugin path (adjust based on context)
# For ensemble-vnext development: packages/full
# For installed plugin: check ~/.claude/plugins/installed_plugins.json
PLUGIN_DIR="/path/to/packages/full" # Set this to the actual plugin path
# Run scaffold script
"${PLUGIN_DIR}/scripts/scaffold-project.sh" --plugin-dir "$PLUGIN_DIR" .
The scaffold script is located at packages/core/scripts/scaffold-project.sh (symlinked from packages/full/scripts/).
The scaffold script creates:
.claude/ subdirectories (agents, rules, skills, commands, hooks)docs/ subdirectories (PRD, TRD, standards).trd-state/ directoryCLAUDE.md, .claude/router-rules.json, .claude/settings.json, .trd-state/current.json.claude/agents/.claude/commands/.claude/hooks/ (including permitter with lib dependencies)Verify all directories and these files exist before proceeding:
CLAUDE.md.claude/router-rules.json.claude/settings.json.trd-state/current.json.claude/agents/*.md (12 files).claude/commands/*.md (8 files).claude/hooks/ (permitter/, router.py, formatter.sh, status.js, wiggum.js, learning.sh)Using the detected stack from Step 1, generate .claude/rules/stack.md using the template at @packages/core/templates/stack.md.template.
Fill in all placeholders with detected values:
{{PROJECT_NAME}} - from user input or directory name{{PRIMARY_PLATFORM}} - detected platform{{LANGUAGES}} - detected languages with purposes{{FRAMEWORKS}} - detected frameworks{{TESTING}} - detected testing setup{{GENERATED_DATE}} - current dateUsing user selections from Step 2 and the template at @packages/core/templates/constitution.md.template, generate .claude/rules/constitution.md.
Fill in all placeholders:
{{PROJECT_NAME}} - from user input{{PROJECT_DESCRIPTION}} - from user input{{UNIT_COVERAGE}} - from quality gates selection{{INTEGRATION_COVERAGE}} - from quality gates selection{{VERIFICATION_LEVEL}} - from verification level selection (default: unit-only){{REQUIRES_APPROVAL}} - from approval requirements selection{{GENERATED_DATE}} - current dateCopy and customize the template from @packages/core/templates/process.md.template to .claude/rules/process.md.
Fill in coverage placeholders from user selections.
Copy and Customize All 12 Subagents
For each agent in @packages/full/agents/:
.claude/agents/<agent-name>.mdAgents to deploy:
product-manager.md - PRD creation/refinementtechnical-architect.md - TRD creation/refinementspec-planner.md - Execution planningfrontend-implementer.md - UI/componentsbackend-implementer.md - APIs/servicesmobile-implementer.md - Mobile appsverify-app.md - Test executioncode-simplifier.md - Post-verification refactoringcode-reviewer.md - Security/quality reviewapp-debugger.md - Debug failuresdevops-engineer.md - Infrastructurecicd-specialist.md - Pipeline configurationCustomization Guidelines:
CRITICAL - Frontmatter Format Requirements:
tools: line - agents have all tools enabled by defaultskills: must be a YAML array - one skill per line
skills:\n - pytest\n - jest\n - developing-with-pythonskills: pytest, jest, developing-with-pythonAgentic Skill Selection
This is a reasoning task, not a lookup table. You must analyze the detected stack and reason about which skills would genuinely help this specific project.
Phase 1: Discover Available Skills
First, explore the skill library to understand what's available:
@packages/skills/*/SKILL.mdPhase 2: Reason About Skill Relevance
For each available skill, consider:
Direct Match: Does the detected stack explicitly use this technology?
prisma/schema.prisma → using-prisma is directly relevantComplementary Value: Would this skill help even if not explicitly used yet?
styling-with-tailwind might be valuablemanaging-railway or managing-vercel could helpEcosystem Fit: Does this skill fit the project's ecosystem?
pytest is a natural fit even if not configured yetdeveloping-with-typescript provides foundational patternsFuture Needs: Based on project structure, what will likely be needed?
using-celery or similar may helpPhase 3: Categorize by Confidence
Group your selections:
Phase 4: Handle Special Cases
Phase 5: Write Selection and Copy
.claude/selected-skills.txt (one skill per line):developing-with-python
pytest
using-prisma
managing-railway
PLUGIN_PATH="${ENSEMBLE_PLUGIN_DIR:-${CLAUDE_PLUGIN_ROOT:-$(cat /tmp/.ensemble-test/plugin-path 2>/dev/null || jq -r '.plugins | to_entries[] | select(.key | contains("ensemble")) | .value[0].installPath' ~/.claude/plugins/installed_plugins.json 2>/dev/null)}}"; "${PLUGIN_PATH}/scripts/scaffold-project.sh" --plugin-dir "$PLUGIN_PATH" --copy-skills .Phase 6: Report to User
Output your reasoning:
## Skills Selected
### High Confidence (Direct Match)
- `developing-with-python` - Python 3.11 detected in pyproject.toml
- `using-prisma` - prisma/schema.prisma found
### Medium Confidence (Ecosystem Fit)
- `pytest` - Python project, standard testing approach
### Considered but Not Included
- `using-celery` - No background job patterns detected
- `managing-railway` - No deployment config found; can add later with `/add-skill`
Commands were copied by scaffold script in Step 3. Verify they exist:
Check that these commands exist in .claude/commands/:
create-prd.mdrefine-prd.mdcreate-trd.mdrefine-trd.mdimplement-trd.mdupdate-project.mdcleanup-project.mdfold-prompt.mdIf any are missing, re-run the scaffold (use --force to overwrite existing files):
PLUGIN_PATH="${ENSEMBLE_PLUGIN_DIR:-${CLAUDE_PLUGIN_ROOT:-...}}"; "${PLUGIN_PATH}/scripts/scaffold-project.sh" --plugin-dir "$PLUGIN_PATH" --force .
Hooks were copied by scaffold script in Step 3. Verify they exist:
Check these hooks in .claude/hooks/:
.claude/hooks/permitter/permitter.js and lib/ directory.claude/hooks/router.py.claude/hooks/formatter.sh.claude/hooks/status.js.claude/hooks/wiggum.js.claude/hooks/learning.shIf any are missing, re-run the scaffold (use --force to overwrite existing files):
PLUGIN_PATH="${ENSEMBLE_PLUGIN_DIR:-${CLAUDE_PLUGIN_ROOT:-...}}"; "${PLUGIN_PATH}/scripts/scaffold-project.sh" --plugin-dir "$PLUGIN_PATH" --force .
CHECKPOINT: Steps 1-8 complete. DO NOT STOP HERE. Continue with Steps 9-15.
Deploy settings.json:
Copy @packages/core/templates/claude-directory/settings.json to .claude/settings.json
Deploy router-rules.json:
Copy @packages/core/templates/claude-directory/router-rules.json to .claude/router-rules.json
Initialize current.json:
Copy @packages/core/templates/trd-state/current.json.template to .trd-state/current.json
Based on detected tech stack, install missing formatters:
| Detected Language | Formatter | Install Command |
|---|---|---|
| JavaScript/TypeScript | Prettier | npm install -D prettier |
| Python | Ruff | pip install ruff or uv add --dev ruff |
| Go | goimports | go install golang.org/x/tools/cmd/goimports@latest |
| Rust | rustfmt | (included with Rust) |
| Shell | shfmt | brew install shfmt or go install mvdan.cc/sh/v3/cmd/shfmt@latest |
| PHP | PHP-CS-Fixer | composer require --dev friendsofphp/php-cs-fixer |
| Ruby | RuboCop | gem install rubocop |
| Java | google-java-format | Manual download required |
| C# | CSharpier | dotnet tool install csharpier |
| Swift | swift-format | brew install swift-format |
| Lua | StyLua | cargo install stylua |
For each detected language:
which <formatter>).prettierrc for Prettierruff.toml for RuffAppend to .gitignore if not already present:
Read content from @packages/core/templates/gitignore-additions.txt and append to project's .gitignore.
Ensure these patterns are added:
# Ensemble Runtime - Local Settings
.claude/settings.local.json
*.local.*
*.local.json
# Environment files with secrets
.env
.env.local
.env.*.local
Important: Do NOT add .claude/ or .trd-state/ to gitignore - these should be tracked.
CHECKPOINT: Steps 9-11 complete. DO NOT STOP HERE. Continue with Steps 12-14.
Agentic CLAUDE.md Customization
The scaffolding script created CLAUDE.md from a template. You must now UPDATE it with project-specific information by reasoning about what context would be most valuable for future development sessions.
Phase 1: Gather Context
Synthesize what you learned during initialization:
Phase 2: Replace Placeholders with Reasoned Content
Read the existing CLAUDE.md and replace placeholders:
| Placeholder | How to Fill |
|---|---|
{{PROJECT_NAME}} | Use actual project name - infer from directory, package.json name, or README title |
{{PROJECT_DESCRIPTION}} | Synthesize a clear 1-2 sentence description that captures what the project does |
{{STACK_SUMMARY}} | Craft a useful summary that highlights the key technologies, not just a list |
Phase 3: Add Project-Specific Context
Go beyond simple placeholder replacement. If the template has sections for:
Phase 4: Verify Completeness
After updating:
{{...}} placeholders remainQuality Check:
A good CLAUDE.md should let a future session:
CRITICAL: Verify ALL required files exist before proceeding to Step 14.
Required Files Checklist - ALL must exist:
| File/Directory | Created In Step | Required |
|---|---|---|
.claude/agents/ (12 files) | Step 5 | YES |
.claude/rules/constitution.md | Step 4 | YES |
.claude/rules/stack.md | Step 4 | YES |
.claude/rules/process.md | Step 4 | YES |
.claude/skills/ (1+ skill folders) | Step 6 | YES |
.claude/commands/ (8 files) | Step 7 | YES |
.claude/hooks/permitter.js | Step 8 | YES |
.claude/hooks/router.py | Step 8 | YES |
.claude/hooks/formatter.sh | Step 8 | YES |
.claude/hooks/status.js | Step 8 | YES |
.claude/hooks/learning.js | Step 8 | YES |
.claude/settings.json | Step 3 (scaffold) | YES |
.claude/router-rules.json | Step 3 (scaffold) | YES |
.trd-state/current.json | Step 3 (scaffold) | YES |
CLAUDE.md | Step 3 (scaffold), Step 12 (update) | YES |
Validation Procedure:
.claude/settings.json, .claude/router-rules.json, .trd-state/current.json).gitignore includes local settings patterns{{...}} placeholders remainIf validation fails:
Only when ALL files exist: Proceed to Step 14 (Completion Report)
FINAL REQUIRED STEP: You MUST complete Step 14 to finish initialization.
Output comprehensive summary:
Project initialized for AI-augmented development
Vendored Runtime Created:
.claude/
agents/ - 12 project-tailored subagents
rules/ - constitution.md, stack.md, process.md
skills/ - [N] stack-relevant skills
commands/ - 8 workflow commands
hooks/ - 5 hook scripts
settings.json - Permissions and hook configuration
router-rules.json - Project-specific routing
Documentation:
docs/PRD/ - Product Requirements Documents
docs/TRD/ - Technical Requirements Documents
State Management:
.trd-state/ - Implementation tracking
current.json - Current feature pointer
Tech Stack Detected:
[summary of detected stack]
Skills Selected:
[list of skills with confidence levels]
Next Steps:
1. Review .claude/rules/constitution.md and customize if needed
2. Review .claude/rules/stack.md for accuracy
3. Create a PRD with /create-prd for new features
4. Generate TRD with /create-trd from approved PRD
5. Implement with /implement-trd
Commands Available:
/create-prd - Generate PRD from story/idea
/refine-prd - Iterate on existing PRD
/create-trd - Generate TRD from PRD
/refine-trd - Iterate on existing TRD
/implement-trd - Execute staged implementation
/update-project - Capture learnings, update governance
/cleanup-project - Prune CLAUDE.md and artifacts
/fold-prompt - Optimize context for continued work
OPTIONAL ENHANCEMENTS: Steps 15-16 improve routing but are not required.
Note: Steps 15-16 are optional enhancements. If the session ends here, the project initialization is still complete and functional.
After all critical setup is complete, run generate-project-router-rules:
Invoke /generate-project-router-rules to create project-specific routing patterns.
This command analyzes the project structure and creates routing rules in .claude/router-rules.json that help the Router hook route prompts to appropriate commands, skills, and agents.
Note: This step is optional. If skipped, there is no impact on functionality.
If router-rules.json was generated in Step 15, output a summary showing:
Keywords that route to specific agents:
"database" → backend-implementerKeywords that trigger specific skills:
"railway deploy" → managing-railwayProject-specific patterns detected:
frontend-implementer)using-prisma skill)Example Output Format:
Keyword Mapping Summary:
Agent Routing:
"api", "endpoint", "database" → backend-implementer
"component", "ui", "style" → frontend-implementer
"deploy", "ci", "pipeline" → cicd-specialist
Skill Triggers:
"prisma", "schema" → using-prisma
"railway", "deploy" → managing-railway
"react", "component" → developing-with-react
Project-Specific Patterns:
- Next.js detected: "page", "layout" → frontend-implementer
- PostgreSQL detected: "migration" → using-prisma skill
Present user with options:
Prompt: "Existing ensemble installation detected. What would you like to do?"
Options:
1. "Replace All" - Replace entire vendored runtime with current plugin version
2. "Preserve Rules" - Replace agents, skills, commands, hooks; keep rules/ untouched
3. "Preserve Agents" - Replace skills, commands, hooks, rules; keep customized agents
4. "Cancel" - Abort initialization
On "Replace All":
.claude.backup.<timestamp>/.claude/ directory (or use --force flag with scaffold)Important: If you cannot delete the directory first, use --force:
"${PLUGIN_DIR}/scripts/scaffold-project.sh" --plugin-dir "$PLUGIN_DIR" --force .
On "Preserve Rules":
.claude/rules/ to .claude.rules.backup.<timestamp>/.claude/rules/On "Preserve Agents":
.claude/agents/ to .claude.agents.backup.<timestamp>/.claude/agents/On "Cancel":
| Condition | Action |
|---|---|
| Not a git repository | Warn but continue - state tracking still works |
| No package files found | Prompt for manual tech stack entry |
| Write permission denied | Report and suggest running with appropriate permissions |
| Existing .claude/ directory | Show migration prompt (see Migration Prompt Flow) |
| Formatter not installed | Show install command, continue without formatter |
| Validation fails | Report issues, suggest fixes, do not mark complete |
| Network error during skill copy | Retry 3 times, then continue without that skill |
| Invalid JSON in templates | Report error, abort initialization |
This command implements TRD tasks: TRD-C001 through TRD-C009
npx claudepluginhub fortiumpartners/ensemble-vnext --plugin full/init-projectInitializes a new Task Master project via task-master init. Accepts PRD path, --name, --description, -y quick mode; sets up structure, verifies git/AI configs, suggests next steps.
/init-projectInitializes new project with essential directory structure, git repo, README, framework-specific configs (React/Vue/Angular/Express/FastAPI/etc.), TypeScript/linting/testing/build tools, and GitHub Actions CI/CD.
/init-projectInitializes new project with essential directory structure, git repo, README, framework-specific configs (React/Vue/Angular/Express/FastAPI/etc.), TypeScript/linting/testing/build tools, and GitHub Actions CI/CD.
/init-projectInitializes project by interactively generating CLAUDE.md (overview, stack, structure), spec.md (feature specs), and prompt_plan.md (phased implementation plan). Auto-detects tech stack; supports [name] [--type next|vite|go|python|rust].
/init-projectScans current codebase to auto-generate project-level CLAUDE.md with detected stack, conventions, domain context, team rules, and clarifying questions.