Use when setting up a project for AI-driven development with astra. Detects stack, reads user insights, generates CLAUDE.md + AGENTS.md + GOAL.md + astra.yaml, installs hooks, skills, MCP servers, and agents. Do NOT use for ongoing development — use /astra-run instead.
Initialize a project for AI-driven development with astra.
$ARGUMENTS — optional project path (defaults to current directory)PROJECT_DIR = $ARGUMENTS or current working directory
cd $PROJECT_DIR
Run the detection script to identify the project's stack, test command, build command, and structure.
bash ${CLAUDE_PLUGIN_ROOT}/src/scripts/detect.sh $PROJECT_DIR
Parse the JSON output into . Save to .
detection.json${PROJECT_DIR}/.claude/detection.jsonIf ~/.claude/usage-data/report.html exists, extract friction patterns:
bash ${CLAUDE_PLUGIN_ROOT}/src/scripts/read-insights.sh
Parse output into insights.json. These drive personalized CLAUDE.md rules.
Present detected stack, test command, build command. Ask user to confirm or adjust.
HITL Gate: confirm_detection — User must confirm before generation proceeds.
Use Python generators to create files. For each file, use smart_merge to handle re-runs:
from src.core.generators import generate_claude_md, generate_agents_md, generate_goal_md, generate_astra_yaml, smart_merge
Generate these files:
CLAUDE.md — stack-aware, ≤200 lines, with friction rules from insightsAGENTS.md — universal context for all AI toolsGOAL.md — mission + priorities + success criteriaastra.yaml — plugin configuration with detection defaultsFor each:
smart_merge(path, content, hashes_path) to check if update is safeaction == "create": write the fileaction == "update": write the file (user didn't modify it)action == "skip": log and skipaction == "conflict": show diff and ask userUse the installers module to scaffold .claude/agents/:
from src.core.installers import install_agents
This installs agent templates with placeholder substitution based on detection.
Generate .mcp.json with stack-appropriate MCP servers:
from src.core.installers import generate_mcp_json, merge_mcp_json
If rulesync is installed, suggest running rulesync generate to create cross-tool config files.
Write SHA256 hashes of all generated files to .claude/agents/.hashes for idempotent re-runs.
Output a summary of what was created/updated/skipped.