tomevault-io Establish Project
Generate project-tuned configuration and skills by detecting the project's tech stack, structure, and conventions.
Skill Asset Paths
All templates and reference files for this plugin are located under:
SKILL_BASE=!`echo "${CLAUDE_PLUGIN_ROOT:-$HOME/.claude}/skills"`
Throughout this document, SKILL_BASE refers to the resolved path printed above.
When instructions say to read a file at SKILL_BASE/..., substitute the actual resolved path.
When spawning Task subagents, pass the resolved SKILL_BASE value so they can locate template and reference files.
Arguments
/establish-project— generate all missing artifacts/establish-project refresh— regenerate all artifacts (backs up existing files first)/establish-project <artifact>— regenerate only one:agents-md,claude-md,task,plan,pr-review,commit,settings
Phase 1: Detect
Scan the project root silently. Do NOT ask questions yet.
Find project root
git rev-parse --show-toplevel 2>/dev/null || pwd
Store as PROJECT_ROOT.
Tech stack
| File/Pattern | Stack | Version hint |
|---|---|---|
*.csproj, *.sln, global.json |
.NET | <TargetFramework> in csproj |
package.json |
Node.js | dependencies: next, react, vue, angular |
Cargo.toml |
Rust | edition field |
go.mod |
Go | go directive |
pyproject.toml, requirements.txt |
Python | requires-python |
Gemfile |
Ruby | ruby version |
Dockerfile, docker-compose.yml |
Containerized | — |
*.tf, terraform/ |
IaC/Terraform | — |
Build, test, lint commands
| Stack | Build | Test | Lint |
|---|---|---|---|
| .NET | dotnet build |
dotnet test |
dotnet format --verify-no-changes |
| Node.js | package.json scripts → build |
scripts → test |
scripts → lint |
| Rust | cargo build |
cargo test |
cargo clippy |
| Go | go build ./... |
go test ./... |
golangci-lint run |
| Python | — | pytest / unittest / tox | ruff / flake8 / mypy |
Architecture
Look for layered directories: Core, Domain, Application, Infrastructure, Api, Web, Presentation, Services, Handlers, Controllers, Repositories.
Check: src/ vs flat, test directories (Tests, tests, __tests__, spec, test), monorepo indicators (packages/, apps/, libs/, workspace configs).
Task tracking
- Directories:
docs/tasks/,specs/,issues/,.github/ISSUE_TEMPLATE/ - Markdown with "Acceptance Criteria", "Requirements", "Scope"
- Naming convention (TASK-XX, issue-NNN, etc.)
- MCP configs:
.mcp.json— note task management MCPs (Linear, Jira, etc.)
Plan tracker adapters
Scan for available plan tracker adapters:
ls -d SKILL_BASE/*-plan/ 2>/dev/null
Replace SKILL_BASE with the actual resolved path from above.
Extract adapter names (directory basenames, e.g., gh-plan, local-plan). Store as DETECTED_PLAN_ADAPTERS.
Conventions
- Read AGENTS.md, CLAUDE.md, CONTRIBUTING.md if they exist
git log --oneline -10for commit message format- Config files:
.editorconfig,.eslintrc*,.prettierrc*,rustfmt.toml, etc. - CI:
.github/workflows/,.gitlab-ci.yml,Jenkinsfile
Collect all findings into a compact detection summary.
Phase 2: Confirm
Present what you detected as a summary. Use AskUserQuestion only for what you couldn't confidently detect:
- Tech stack — "I detected [X]. Correct?"
- Architecture — "I see [pattern]. Is this the structure to follow?"
- Task tracking — "How do you track tasks?" (file-based, Linear, Jira, GitHub Issues, freeform?)
- Commit convention — "I see commits like [format]. Follow this?"
- Existing artifacts — if AGENTS.md/CLAUDE.md already exist AND the user didn't pass "refresh", ask whether to regenerate.
- Plan tracker — if DETECTED_PLAN_ADAPTERS is non-empty: "Want to set up
/planwith a tracker? Options: [list detected adapter names], none."- If
gh-plan: ask "GitHub Project number to add issues to? (optional, press enter to skip)" - If
local-plan: ask "Task directory path? (default:docs/tasks)" - Store the chosen adapter as PLAN_TRACKER and any config as PLAN_TRACKER_CONFIG.
- If no adapters detected, skip this question silently.
- If
If everything is clear from detection, present the summary and ask for a single confirmation.
Phase 3: Determine artifacts to generate
ALL_ARTIFACTS = [agents-md, claude-md, task, plan, pr-review, commit, settings]
- Argument is "refresh": generate all. Back up each existing file to
<name>.establish-backup. - Argument is a specific name: generate only that one. Back up if it exists.
- No argument: generate only artifacts that don't already exist. Warn about skipped ones.
Phase 4: Validate prerequisites
Run checks only for artifacts and adapters that are in the generation list. Skip silently for artifacts not being generated.
| Condition | Check | Remediation |
|---|---|---|
| Any artifact selected | git rev-parse --git-dir 2>/dev/null |
"Not a git repo. Initialize with git init?" |
commit or pr-review |
git log -1 2>/dev/null |
"No commits yet — commit and PR commands need git history. Skipping for now." |
pr-review |
gh auth status 2>/dev/null |
"gh CLI not authenticated. Run gh auth login to enable PR reviews." |
PLAN_TRACKER = gh-plan |
command -v gh >/dev/null 2>&1 |
"gh CLI not found. Install from https://cli.github.com" |
PLAN_TRACKER = gh-plan |
gh auth status 2>/dev/null |
"gh CLI not authenticated. Run gh auth login." |
PLAN_TRACKER = gh-plan |
gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null |
"No GitHub remote detected. Push to GitHub first, or switch to local-plan." |
PLAN_TRACKER = gh-plan + PROJECT_NUMBER set |
gh api graphql -f query='query($n:Int!){viewer{projectV2(number:$n){id}}}' -F n=<N> 2>/dev/null |
"GitHub Project #N not found or not accessible. Continuing without project integration." |
Handling failures
- Hard failures (no git, no gh CLI when gh-plan selected): ask the user whether to fix now, skip the affected artifact, or abort.
- Soft failures (no git history, project number not found): warn and degrade gracefully — skip the affected feature but continue generating the artifact without it.
- If the user chose
gh-planand gh auth fails, offer to fall back tolocal-planornoneinstead of just skippingplanentirely.
Update PLAN_TRACKER and the artifact list based on any fallback decisions before proceeding.
Phase 5: Generate
For each artifact, spawn a Task subagent. Pass the detection summary as compact text in the prompt. Always include the resolved SKILL_BASE path in every subagent prompt so it can locate templates and references. Run independent subagents in parallel.
AGENTS.md
- model: sonnet
- subagent_type: general-purpose
- prompt: Include the detection summary AND instruct the subagent to read
SKILL_BASE/establish-project/references/generate-agents-md.mdfor generation instructions. Target:{PROJECT_ROOT}/AGENTS.md. If refreshing, include current file content so the subagent can preserve intentional customizations.
CLAUDE.md
- model: haiku
- subagent_type: general-purpose
- prompt: Include basic project info (name, stack, build/test/lint commands) AND instruct
the subagent to read
SKILL_BASE/establish-project/references/generate-claude-md.md. Target:{PROJECT_ROOT}/CLAUDE.md.
Task command
- model: sonnet
- subagent_type: general-purpose
- prompt: Include the full detection summary AND instruct the subagent to read both:
SKILL_BASE/establish-project/references/generate-task-command.md(instructions)SKILL_BASE/establish-project/assets/templates/task-command-template.md(template) Fill in all{PLACEHOLDERS}, resolve{IF}/{END IF}blocks, and write the result to{PROJECT_ROOT}/.claude/commands/task.md. Include task tracking details (format, location, MCP tools).
PR review agent
- model: haiku
- subagent_type: general-purpose
- prompt: Include detection summary (conventions, linters, test commands) AND instruct
the subagent to read
SKILL_BASE/establish-project/references/generate-pr-review.md. Target:{PROJECT_ROOT}/.claude/agents/pr-review.md.
Commit command
- model: haiku
- subagent_type: general-purpose
- prompt: Include commit convention (format description + 3-5 example messages from
git log) AND instruct the subagent to read the template atSKILL_BASE/establish-project/assets/templates/commit-command-template.md. Fill in all{PLACEHOLDERS}, resolve{IF}/{END IF}blocks, and write the result to{PROJECT_ROOT}/.claude/commands/commit.md. Include pre-commit check commands if the project has them (lint, format, etc.).
Plan command
- model: haiku
- subagent_type: general-purpose
- prompt: Include the full detection summary AND instruct the subagent to read both:
SKILL_BASE/establish-project/references/generate-plan-command.md(instructions)SKILL_BASE/establish-project/assets/templates/plan-command-template.md(template) Fill in all{PLACEHOLDERS}, resolve{IF}/{END IF}blocks, and write the result to{PROJECT_ROOT}/.claude/commands/plan.md. Include:- Tracker adapter name (
PLAN_TRACKERfrom Phase 2, or empty if none) - Tracker config (
PLAN_TRACKER_CONFIG— project number, task dir, etc.) - Architecture layers detected
- SKILL_BASE — so the generated plan command can reference plan templates and tracker adapter skills at the correct path
Settings (.claude/settings.json)
Generate this inline — no subagent needed. It's a deterministic mapping from detected stack.
Write {PROJECT_ROOT}/.claude/settings.json with permissions based on the detected stack:
| Stack | Allow rules |
|---|---|
| .NET | Bash(dotnet *), Bash(git *) |
| Node.js | Bash(npm *), Bash(npx *), Bash(node *), Bash(git *) |
| Rust | Bash(cargo *), Bash(git *) |
| Go | Bash(go *), Bash(git *) |
| Python | Bash(python *), Bash(pip *), Bash(uv *), Bash(pytest *), Bash(git *) |
Combine rules if multiple stacks are detected. Always include Bash(git *).
If .claude/settings.json already exists, merge — add missing allow rules without removing existing ones. Show the user the diff before writing.
Auto-format hook (conditional)
Only add if a formatter is confidently detected — meaning a config file or explicit dependency exists, not just a guess from the stack. Skip silently otherwise.
Evidence required:
| Formatter | Confident signal |
|---|---|
| Prettier | .prettierrc* exists OR prettier in package.json devDependencies |
| rustfmt | rustfmt.toml exists OR project uses Rust (rustfmt ships with toolchain) |
| gofmt | Project uses Go (gofmt ships with toolchain) |
| dotnet format | Project uses .NET 6+ |
| Ruff | ruff in pyproject.toml dependencies or ruff.toml exists |
| Black | black in pyproject.toml or [tool.black] section exists |
If confident, add to settings under hooks. The hook receives JSON on stdin with the tool input; use jq to extract the file path.
Example for Prettier:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path // .tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true"
}
]
}
]
}
}
Adapt the command for the detected formatter:
| Formatter | Command |
|---|---|
| Prettier | jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null || true |
| rustfmt | jq -r '.tool_input.file_path' | xargs rustfmt 2>/dev/null || true |
| gofmt | jq -r '.tool_input.file_path' | xargs gofmt -w 2>/dev/null || true |
| dotnet format | jq -r '.tool_input.file_path' | xargs -I {} dotnet format --include {} 2>/dev/null || true |
| Ruff | jq -r '.tool_input.file_path' | xargs ruff format 2>/dev/null || true |
| Black | jq -r '.tool_input.file_path' | xargs black 2>/dev/null || true |
The || true ensures a formatter failure on a non-applicable file doesn't block Claude.
.gitignore (always, inline)
Check if {PROJECT_ROOT}/.gitignore exists. If it does, check whether .claude/ entries are present.
If not, ask the user: "Should .claude/ be committed (team sharing) or gitignored (personal only)?"
If gitignored, append:
# Claude Code local config
.claude/settings.json
.claude/plans/
Note: skills and commands are NOT gitignored by default — the user likely wants to share /task, /commit, and the PR review agent with the team.
Phase 6: Summary
After all subagents complete, report:
- Created: list each file with its absolute path
- Skipped: already existed (if any)
- Usage:
AGENTS.md— automatically picked up by compatible AI coding toolsCLAUDE.md— automatically picked up by Claude Code/plan <feature>— invoke to plan a feature, decompose into tasks, and sync to tracker/task <reference>— invoke to implement a task/commit— invoke to create a well-formatted commit- PR review — used when Claude reviews PRs
settings.json— pre-approved tool permissions, active immediately
- Reminder: commit AGENTS.md, CLAUDE.md, and
.claude/commands/+.claude/agents/to share with team.
Converted and distributed by TomeVault — claim your Tome and manage your conversions.