new-project
Stand up a new multi-repo project's PRIVATE CTO home (<project>-cto) from this template's mechanism, and either scaffold its dev repos (greenfield) or wire it to a fleet that already exists (adopt — e
SKILL.md.claude/skills/new-project/SKILL.md
GitHubNew Project / CTO Home: $ARGUMENTS
Scaffolds a private <project>-cto operating home from this template's mechanism, then
either creates new dev repos (greenfield) or registers an existing fleet (--adopt).
Local-only + print-commands: this skill writes files on disk and prints the gh/git
commands to publish — it never deletes, pushes, or creates a GitHub repo itself.
Scaffold
set -uo pipefail
[ -n "${ZSH_VERSION:-}" ] && setopt sh_word_split
ARGS="$ARGUMENTS"
PROJECT=""; REPOS=""; ADOPT=0; ORG="<your-gh-org-or-user>"
# FLAG RULE (2026-10-19): `--x v` or `--x=v`; unknown flag or stray word refuses (see /handoff).
EXPECT=""
for tok in $ARGS; do
if [ -n "$EXPECT" ]; then
case "$EXPECT" in repos) REPOS="$tok" ;; org) ORG="$tok" ;; esac
EXPECT=""; continue
fi
case "$tok" in
--repos=*) REPOS="${tok#--repos=}" ;;
--repos) EXPECT=repos ;;
--org=*) ORG="${tok#--org=}" ;;
--org) EXPECT=org ;;
--adopt) ADOPT=1 ;;
--*) echo "ERROR: unknown flag '$tok' — refusing rather than guessing. Usage: see argument-hint." >&2; exit 2 ;;
*) if [ -z "$PROJECT" ]; then PROJECT="$tok"; else echo "ERROR: unexpected extra argument '$tok' (project already '$PROJECT') — refusing." >&2; exit 2; fi ;;
esac
done
[ -n "$EXPECT" ] && { echo "ERROR: --$EXPECT needs a value — refusing." >&2; exit 2; }
if [ -z "$PROJECT" ]; then
echo "ERROR: usage /new-project <project> [--repos=a,b] [--adopt] [--org=<gh-org>]"
echo " greenfield: /new-project acme --repos=acme-core,acme-web --org=acme-inc"
echo " adopt: /new-project acme --adopt (wires <project>-cto to repos in projects.yaml)"
exit 1
fi
TPL=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
PARENT=$(dirname "$TPL")
HOME_DIR="$PARENT/${PROJECT}-cto"
MODE="greenfield"; [ "$ADOPT" -eq 1 ] && MODE="adopt-existing"
echo "project : $PROJECT"
echo "mode : $MODE"
echo "template (src) : $TPL"
echo "CTO home (dst) : $HOME_DIR"
echo "repos : ${REPOS:-<none given>}"
echo ""
if [ -e "$HOME_DIR" ]; then
echo "ERROR: $HOME_DIR already exists — refusing to overwrite. Remove it or pick another name."
exit 1
fi
# --- 1. Scaffold the private CTO home from the template mechanism (local copy) ---
echo "== scaffolding CTO home =="
mkdir -p "$HOME_DIR"
rsync -a \
--exclude='.git/' --exclude='.DS_Store' --exclude='__pycache__/' --exclude='*.pyc' \
--exclude='.claude/settings.json' --exclude='.claude/settings.local.json' \
--exclude='.claude/scheduled_tasks.lock' --exclude='.claude/current-session.id' \
--exclude='.claude/*.id' --exclude='.claude/.permissions-asked' \
--exclude='.cto/projects.yaml' --exclude='README.md' \
"$TPL"/ "$HOME_DIR"/
# Adapt CLAUDE.md title (the genericized template's CTO-home detection already covers any -cto repo)
perl -CSD -i -pe "s/^# CTO Agent .*/# CTO Agent \x{2014} ${PROJECT}-cto (${PROJECT} fleet CTO home)/ if \$. == 1" "$HOME_DIR/CLAUDE.md"
# IP dirs (the place project intellectual property lives — kept out of the public template)
mkdir -p "$HOME_DIR/docs/roadmap/prds" "$HOME_DIR/docs/architecture/decisions" "$HOME_DIR/docs/ideation" "$HOME_DIR/docs/handoff"
cat > "$HOME_DIR/README.md" <<EOF
# ${PROJECT}-cto
Private CTO operating home for the **${PROJECT}** fleet. Holds the project's IP (PRDs,
FLEET-ADRs, strategy/research, IDEO sessions, CTO decisions) under \`docs/\`, plus a copy of
the orchestration mechanism (skills, hooks, personas, scripts, templates) and the live
\`.cto/projects.yaml\`. Run the ${PROJECT} CTO from here. This repo is PRIVATE and never
holds the public template's job — it is the IP side of the public/private split.
EOF
# --- 2. Seed .cto/projects.yaml ---
mkdir -p "$HOME_DIR/.cto"
{
echo "# CTO Project Registry for ${PROJECT}"
echo "# Gitignored (local filesystem paths). One entry per repo in the fleet."
echo "projects:"
} > "$HOME_DIR/.cto/projects.yaml"
REG_REPOS="$REPOS"
# In adopt mode with no --repos, inherit the active repos from the template's own registry if present
if [ "$ADOPT" -eq 1 ] && [ -z "$REG_REPOS" ] && [ -f "$TPL/.cto/projects.yaml" ]; then
REG_REPOS=$(grep -E '^\s*- name:' "$TPL/.cto/projects.yaml" | sed 's/.*- name:[[:space:]]*//' | paste -sd, -)
echo "(adopt) inherited repos from template registry: $REG_REPOS"
fi
if [ -n "$REG_REPOS" ]; then
OLDIFS="$IFS"; IFS=','
for r in $REG_REPOS; do
r=$(echo "$r" | tr -d '[:space:]'); [ -z "$r" ] && continue
RPATH="$PARENT/$r"
printf ' - name: %s\n path: %s\n description: TODO\n language: TODO\n active: true\n' "$r" "$RPATH" >> "$HOME_DIR/.cto/projects.yaml"
done
IFS="$OLDIFS"
else
echo " # - name: ${PROJECT}-core" >> "$HOME_DIR/.cto/projects.yaml"
echo " # path: $PARENT/${PROJECT}-core" >> "$HOME_DIR/.cto/projects.yaml"
echo " # active: true" >> "$HOME_DIR/.cto/projects.yaml"
fi
echo " wrote $HOME_DIR/.cto/projects.yaml"
# --- 3a. Greenfield: scaffold each new dev repo locally ---
DEV_SCAFFOLD=""
if [ "$ADOPT" -eq 0 ] && [ -n "$REPOS" ]; then
echo ""
echo "== scaffolding dev repos (greenfield, local) =="
OLDIFS="$IFS"; IFS=','
for r in $REPOS; do
r=$(echo "$r" | tr -d '[:space:]'); [ -z "$r" ] && continue
RD="$PARENT/$r"
if [ -e "$RD" ]; then echo " SKIP $r (exists)"; continue; fi
mkdir -p "$RD/.claude/hooks" "$RD/docs/sprints" "$RD/docs/architecture/decisions" "$RD/scripts"
cp "$TPL/CLAUDE.devteam.md" "$RD/CLAUDE.md"
cp -r "$TPL/docs/personas" "$RD/docs/personas" 2>/dev/null || true
cp -r "$TPL/docs/sprints/_templates" "$RD/docs/sprints/_templates" 2>/dev/null || true
cp -r "$TPL/scripts/agentic" "$RD/scripts/agentic" 2>/dev/null || true
[ -f "$TPL/.gitignore" ] && cp "$TPL/.gitignore" "$RD/.gitignore"
cp "$TPL/.claude/settings.permissive.json" "$RD/.claude/settings.permissive.json" 2>/dev/null || true
[ -d "$TPL/.claude/hooks" ] && cp "$TPL/.claude/hooks/"* "$RD/.claude/hooks/" 2>/dev/null || true
chmod +x "$RD/.claude/hooks/"*.sh 2>/dev/null || true
# settings.json with the three dev-team session-tracking hooks already wired
# (from settings.devteam.json.template, _comment fields stripped) so the repo
# is tracked from its first session — /handoff also self-heals this at dispatch.
python3 -c "import json; d=json.load(open('$TPL/.claude/settings.devteam.json.template')); d.pop('_comment',None); h=d.get('hooks',{});
[h.pop(k) for k in list(h) if k.startswith('_comment')]; open('$RD/.claude/settings.json','w').write(json.dumps(d, indent=2) + '\n')" 2>/dev/null \
|| cp "$TPL/.claude/settings.devteam.json.template" "$RD/.claude/settings.json"
# Review engine: provisional seed only. The CEO is asked for the project's choice in
# "Your task as CTO" below, and set-review-engine.sh then rewrites this across the CTO
# home + every dev repo. Written through that script so the value is validated and
# lands at the repo ROOT (resolve-review-engine.sh never reads a .claude/ copy).
bash "$TPL/scripts/agentic/set-review-engine.sh" "$RD" "$(bash "$TPL/scripts/agentic/set-review-engine.sh" --fleet-default)" >/dev/null 2>&1
# The project's review-engine FALLBACK, if its CTO home has one (none by default).
[ -f "$TPL/.review-engine-fallback" ] && cp "$TPL/.review-engine-fallback" "$RD/.review-engine-fallback"
echo " scaffolded $RD"
DEV_SCAFFOLD="$DEV_SCAFFOLD $r"
done
IFS="$OLDIFS"
fi
# --- 4. Print the publish commands (nothing irreversible ran above) ---
echo ""
echo "================================================================"
echo " SCAFFOLD COMPLETE (local only). Run these to PUBLISH:"
echo "================================================================"
echo ""
echo "# 1) CTO home — PRIVATE (holds IP):"
echo "(cd $HOME_DIR && git init && git add -A && \\"
echo " git commit -m 'init ${PROJECT}-cto (CTO home)' && \\"
echo " gh repo create ${ORG}/${PROJECT}-cto --private --source=. --remote=origin --push)"
echo ""
if [ "$ADOPT" -eq 0 ] && [ -n "$DEV_SCAFFOLD" ]; then
echo "# 2) New dev repos (PRIVATE; pick visibility per your needs):"
for r in $DEV_SCAFFOLD; do
echo "(cd $PARENT/$r && git init && git add -A && \\"
echo " git commit -m 'scaffold ${r} (dev team)' && \\"
echo " gh repo create ${ORG}/${r} --private --source=. --remote=origin --push)"
done
elif [ "$ADOPT" -eq 1 ]; then
echo "# 2) ADOPT — the existing repos are registered in projects.yaml above."
echo "# To push the dev-team mechanism into an EXISTING repo (run per repo, review first):"
echo "# cp $TPL/CLAUDE.devteam.md <repo>/CLAUDE.md"
echo "# cp -r $TPL/docs/personas <repo>/docs/personas"
echo "# cp -r $TPL/docs/sprints/_templates <repo>/docs/sprints/_templates"
echo "# mkdir -p <repo>/.claude && cp $TPL/.claude/settings.permissive.json <repo>/.claude/"
echo "# printf 'subagent\\n' > <repo>/.review-engine # repo ROOT, not .claude/"
echo "# (or run /new-project's dev-scaffold against a copy first to diff before committing.)"
echo ""
echo "# If this project's IP currently lives in a PUBLIC repo, scrub it: move IP to ${PROJECT}-cto,"
echo "# then DELETE+RECREATE the public repo (force-push leaves old commits fetchable by SHA)."
fi
echo ""
echo "# 3) Then author the first PRD under $HOME_DIR/docs/roadmap/prds/ and run the CTO from ${PROJECT}-cto."
echo "MODE=$MODE HOME_DIR=$HOME_DIR"
Your task as CTO
First, settle the review engine — a project-start choice, like the permissions posture.
Every VP review, sprint fan-out and accept-gate runs through it, so it is worth one question
now rather than a surprise at the first accept gate. Run
bash scripts/agentic/set-review-engine.sh --menu for the live menu, then ask via
AskUserQuestion (header: "Review engine"), offering:
- kimi (recommended) — OpenRouter
moonshotai/kimi-k2.6. Cross-family reviewer, so a VP verdict is genuinely independent of the model that wrote the work. Metered but non-Anthropic (pennies per review); needsOPENROUTER_API_KEY. - subagent — in-session Agent calls. Free, no API key, no external CLI. Same-family: Claude reviewing Claude, which is a weaker accept-gate.
- handoff — the review runs in its own interactive Claude window. Free, slowest; use when a review needs tools.
State the tradeoff plainly — independence versus pennies — and recommend kimi for any
project whose accept gates matter. Then apply the answer to the CTO home and every
scaffolded dev repo:
bash scripts/agentic/set-review-engine.sh <repo-path> <engine> # once per repo, + the CTO home
Setting it on the CTO home is what makes it the project default: push-to-repos.sh reads that
file to seed and heal every dev repo from then on. Changing it later is the same one command.
Then summarize for the CEO. The CTO home (and, in greenfield mode, the dev repos) are scaffolded on disk — nothing has been pushed or created on GitHub:
- Headline: "Scaffolded
<project>-cto(mode: greenfield|adopt-existing) — local only." 1a. Review engine: the chosen engine, and that it is now the project default for syncs. - What's on disk: the CTO-home path, that its CLAUDE.md is title-adapted (the
-ctodetection is already generic), the seeded.cto/projects.yaml, and (greenfield) the dev-repo dirs. - The publish commands printed above — present them as the CEO's explicit next step (the skill deliberately does NOT create/push repos; that's irreversible + outward-facing). Remind them the CTO home must be private.
- Next: author the first PRD under
docs/roadmap/prds/, then run the project's CTO from<project>-cto. For adopt mode, note the optional "push mechanism into existing repos" steps and (if IP leaked into a public repo) the scrub-and-recreate remediation.
Sign as: — CTO