new-repo

name	new-repo
description	Use when the user says "new repo", starts a fresh repository, asks to initialize/scaffold a repo, wants project intake, wants stack decisions captured, wants repo-local Codex/Claude AGENTS files installed, or wants a new app/agent repo prepared with the user's GitHub rules before implementation.
metadata	{"short-description":"Deterministic new repo intake and scaffold workflow"}

New Repo

This skill is a deterministic repo-start workflow. Do not improvise a generic scaffold. Ground in the filesystem, ask only the missing product/stack questions, install the required agent instruction files, then route implementation through the right build skills.

Hard Rules

• Work on main by default.
• Do not create or continue on codex/* branches unless the user explicitly asks.
• Do not work from detached branches, generated Codex branches, temporary worktrees, or orphaned feature branches when the real repo/default branch should be used.
• If the current branch is not main or the repository's counted default branch, stop and tell the user before committing unless the user has already approved that branch.
• For normal solo/local project work, prefer direct commits on main.
• If the user approves a feature branch, use feature/<short-topic>, never codex/<topic>.
• All commits must use Shane Coy <[e-mail]>.
• Do not overwrite existing project files without reading them first.
• Do not invent production data, credentials, external state, policies, or deployment facts.
• Populate repo-specific instructions only from the user's intake answers or inspected repo files.
• Mark unknown repo facts as TBD - ask the user before implementing this area.

Workflow

0. No work until agent instructions exist

Before scaffold/build work begins, the repository must have:

• ./.codex/AGENTS.md
• ./.claude/AGENTS.md

Both files must preserve /Users/sc/.codex/AGENTS.md as the top preamble and include a repo-specific guide. Installing and verifying these files is a gate, not an optional setup task.

1. Ground in the filesystem

Run these before changing files:

pwd
git status --short --branch
git branch --show-current
git remote -v
find . -maxdepth 2 -type f \( -name 'package.json' -o -name 'pnpm-lock.yaml' -o -name 'package-lock.json' -o -name 'yarn.lock' -o -name 'pyproject.toml' -o -name 'requirements.txt' -o -name 'go.mod' -o -name 'Cargo.toml' -o -name '.env.example' -o -name 'README.md' \) -print
find . -maxdepth 3 \( -name AGENTS.md -o -name CLAUDE.md \) -print

Confirm:

• target repo path
• whether .git exists
• current branch and remote default if available
• existing package manifests, lockfiles, env examples, README, and framework files
• existing .codex/AGENTS.md, .claude/AGENTS.md, root AGENTS.md, or CLAUDE.md

If .git does not exist and the user wants a real repo, initialize with:

git init -b main
git config user.name "Shane Coy"
git config user.email "[e-mail]"

If .git exists, set repo-local identity:

git config user.name "Shane Coy"
git config user.email "[e-mail]"

2. Run intake

Ask the user for missing decisions only. Do not ask questions already answered by files or the prompt.

Required intake:

• product goal: what this repo is supposed to accomplish
• target users: user/admin/customer/internal operator/agent/user-facing visitor
• repo type: frontend, backend, full-stack, agent system, mobile, CLI, library, automation, docs
• frontend stack, if any
• backend stack, if any
• database/storage choice
• auth model
• deployment target
• package manager/runtime
• integrations: APIs, MCP, webhooks, background jobs, queues, RAG/retrieval, external services
• testing expectation: smoke, unit, integration, browser, API, CI
• GitHub target: local only, new remote, existing remote, private/public

If the user says "use defaults", choose conservative defaults that fit the repo purpose and state them before editing.

3. Install repo guidance

Use agent-copy for this step when available.

Always create these repo-local instruction files unless the user explicitly opts out:

• ./.codex/AGENTS.md
• ./.claude/AGENTS.md

Both files must start with a direct copy of:

• /Users/sc/.codex/AGENTS.md

Then append a repo-specific guide for other agents working in this repository.

Implementation rule:

• Create ./.codex/ and ./.claude/ if missing.
• Copy /Users/sc/.codex/AGENTS.md directly into both target files as the first section.
• Do not paraphrase, summarize, or partially copy the global AGENTS file.
• Append a clearly separated repo-specific section after the copied global content.
• If target files already exist, read them first and tell the user before replacing them unless the user already approved replacement.
• Do not create root ./AGENTS.md by default unless the user asks for root-level compatibility.
• Do not create root ./CLAUDE.md by default unless the user asks for Claude root compatibility.

The appended repo-specific section must be titled:

## Repo-Specific Guide

Include these subsections when known from intake or filesystem inspection:

• Product Goal
• Audience / Users
• Stack
• Architecture
• Key Directories
• Run / Test Commands
• Environment Variables
• Data and Secrets Boundaries
• Integrations
• Implementation Notes
• Definition of Done

If a subsection is not known yet, write TBD - ask the user before implementing this area. Do not invent details.

Also include these additional subsections:

• Decisions
• Boundaries / Do Not Touch

Use Decisions to record durable choices and why they were made. Examples: selected framework, database, auth, deployment, agent SDK, package manager, testing level, or why a simpler local-first default was chosen.

Use Boundaries / Do Not Touch to prevent future agents from undoing the user's intent. Examples:

• Do not change the selected framework without the user.
• Do not replace the database/storage layer without the user.
• Do not add mock/demo data to production paths unless the user explicitly accepts it.
• Do not introduce a second frontend/backend framework.
• Do not change deployment target, auth model, or outbound behavior without the user.

After writing, verify the global preamble is preserved at the top:

head -n "$(wc -l < /Users/sc/.codex/AGENTS.md)" ./.codex/AGENTS.md | cmp /Users/sc/.codex/AGENTS.md -
head -n "$(wc -l < /Users/sc/.codex/AGENTS.md)" ./.claude/AGENTS.md | cmp /Users/sc/.codex/AGENTS.md -
rg -n "Repo-Specific Guide|Product Goal|Stack|Run / Test Commands|Definition of Done" ./.codex/AGENTS.md ./.claude/AGENTS.md

Root compatibility:

• Do not create root ./AGENTS.md by default.
• If the active toolchain only auto-discovers root AGENTS.md, ask the user whether to create a root compatibility copy.
• If approved, root ./AGENTS.md should match ./.codex/AGENTS.md unless the user requests a different root-level file.

4. Add base files only when needed

Add these only if the selected stack or repo state requires them:

• README.md when it helps run, test, deploy, or understand the repo
• .gitignore for dependencies, build outputs, caches, logs, and local env files
• .env.example with variable names only, never real secrets
• package/runtime scripts such as dev, build, lint, typecheck, test

Do not add CI, Docker, database migrations, generated app shells, or demo data unless the user's intake answers require them.

For larger repos or multi-session builds, create or update docs/HANDOFF.md only when it materially helps continuation. Keep AGENTS.md stable as operating rules; use docs/HANDOFF.md for current status, next steps, known risks, and validation state.

5. Route implementation

After intake and repo guidance are complete, route implementation through existing skills:

• agent-build-orchestrator: agent systems or broad app builds
• front-end-agent: web UI implementation
• backend-agent-infra: backend/API/service scaffolding
• agent-stack-testing or test-driven-development: validation setup
• stack skills when the user chooses LangGraph, OpenAI Agents, PydanticAI, Expo, Redis, retrieval, MCP, Cloudflare Codemode, or other specialized lanes

Do not hand-roll a substitute workflow when an existing skill matches the chosen stack.

6. Verify

Run package install only when needed for the chosen stack and repo setup.

Run available checks:

git status --short --branch
npm run lint
npm run build
npm test

Use the equivalent commands for non-Node stacks. Skip commands that do not exist and say they were unavailable.

Confirm before handoff:

• target branch is main or user-approved branch
• Git identity is Shane Coy <[e-mail]>
• .codex/AGENTS.md and .claude/AGENTS.md exist, preserve /Users/sc/.codex/AGENTS.md as their top preamble, and include the repo-specific guide
• generated files match the selected stack and intake answers
• no unrelated files were overwritten

New repo setup is complete only when:

• repo is on main or a user-approved branch
• repo-local Git identity is Shane Coy <[e-mail]>
• .codex/AGENTS.md and .claude/AGENTS.md are installed and verified
• repo-specific guide is filled from intake/filesystem truth or marked TBD
• selected stack and run/test commands are documented
• necessary base files exist and unnecessary files were not added
• validation commands were run or explicitly reported unavailable
• git status --short --branch has been checked for final handoff

7. Handoff

Final handoff must include:

• chosen stack
• product goal captured
• files generated or updated
• run commands
• tests/checks run
• remaining decisions
• current git status

Also include a short user-facing review:

• why each selected stack component was chosen
• how the stack supports the product goal and target users
• how the choices optimize for the repo's objective, speed, maintainability, performance, and operational risk
• what tradeoffs were accepted
• what should not be changed casually later

Keep this review plain and practical. The point is to help the user and future agents understand why the repo was set up this way, not to write a sales pitch.

Commit directly on main only when the user asked for commit/push or the current task explicitly includes publishing.