teamcraft-glgd:init-project

---
name: teamcraft-glgd:init-project
description: Set up .teamcraft/project.md, CLAUDE.md, .claude/rules/, and .gitlab-ci.yml for a project. Works for any project state — brand new empty repo, existing codebase with no teamcraft files, or existing project mid-sprint. Creates files that don't exist; audits and proposes updates to files that do.
argument-hint: "(no arguments)"
disable-model-invocation: true
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Glob
  - Bash
  - mcp__gitlab__get_project
  - mcp__gitlab__list_projects
  - mcp__gitlab__list_issues
  - mcp__gitlab__get_issue
  - mcp__gitlab__execute_graphql
  - mcp__google-drive__list_accounts
  - mcp__google-drive__list_folder
  - mcp__google-drive__search_files
  - mcp__google-drive__download_file
---

## Goal

Produce four artifacts that enable Claude Code and the GitLab project to work effectively together from any starting point:

1. `.teamcraft/project.md` — the minimal project index: GitLab project ID and Drive artifact URLs. Never grows beyond this.
2. `CLAUDE.md` — a living team file committed to the repo. Starts with `@.teamcraft/project.md` to import the manifest into every session automatically. Contains only what Claude Code cannot discover from the environment and what no build skill already loads.
3. `.claude/rules/` — starter rule files for domain-specific conventions that only load when Claude Code touches relevant files.
4. `.gitlab-ci.yml` — a baseline quality-gate pipeline appropriate to the project's tech stack, with three stages: `test` (stack-appropriate test suite), `quality` (lint/format check for the detected stack), and `security` (GitLab CE secret detection template — language-agnostic). After the file is written, attempt to set merge protection via the GraphQL MCP tool — fall back to manual UI instructions if the mutation fails on this GitLab CE version.

## Hard Constraints

- No presuppositions about project state. The repo may be empty, mid-sprint, or a 30,000-line legacy codebase with no teamcraft files. Work with what exists.
- `.teamcraft/project.md` contains exactly: project name, GitLab namespace, numeric project ID, and Drive URLs for PRD, tech decisions, and conventions. Leave rows blank where documents don't exist. Nothing else — no milestone data, no sprint history, no team notes.
- `CLAUDE.md` is a team file committed to the repo. Not gitignored. Not per-developer. `CLAUDE.local.md` is the per-developer file — mention it to the developer as the place for personal additions.
- `CLAUDE.md` starts with `@.teamcraft/project.md` so the manifest loads automatically in every session. Its remaining content is only what Claude Code would get wrong that it cannot discover from the environment and that no skill already provides.
- `.claude/rules/` files with a `paths` frontmatter field load only when Claude Code reads matching files — use for domain-specific rules that should not load on every session. Rules files without `paths` load at session start alongside CLAUDE.md.
- Never overwrite an existing CLAUDE.md without showing exactly what changes and getting explicit confirmation.
- If a Drive file operation fails with a path error, read the error message to identify a valid accessible host path and retry with it.
- **Brownfield CI/CD detection:** If `.gitlab-ci.yml` already exists, do not replace it. Inspect it for the three quality-gate stages (test, quality, security). Offer to extend it with any missing stages only. Get confirmation before writing.
- **Runner prerequisite:** Without at least one registered GitLab Runner, pipelines sit as pending forever. Detect whether a runner is likely configured by checking if any pipelines have run on the project. If there is no evidence of a runner, surface this clearly: explain what the team needs to do (install and register a runner), what will happen without one (pipelines pending indefinitely), and that runner setup is outside TeamCraft's scope. Do not leave the team without direction.
- **Merge protection via GraphQL — attempt, then fall back:** Use `mcp__gitlab__execute_graphql` to call the `projectUpdate` mutation and set `onlyAllowMergeIfPipelineSucceeds: true`. This mutation is not available on all GitLab CE versions — if the call fails, do not attempt curl or REST fallbacks. Instead, tell the developer to set it manually in the GitLab UI: Settings → General → Merge requests → enable "Pipelines must succeed". Explain what it does and why it matters.
- **CI/CD is Claude Code only.** This capability reads the local filesystem to detect the tech stack and writes `.gitlab-ci.yml` locally. It cannot run in Cowork without filesystem access.
- **Stack detection covers common cases.** Node (package.json), Go (go.mod), Rust (Cargo.toml), Python (requirements.txt or pyproject.toml), Java (pom.xml or build.gradle). Monorepos and exotic setups may need manual adjustment — say so and offer guidance.

## Resolve Drive Account

Call `mcp__google-drive__list_accounts` before any other Drive operation:
- **No accounts** — Drive is not configured for this user. Tell them and skip Drive operations.
- **One account** — Use it. Pass `account_email` explicitly on every Drive tool call this session.
- **Multiple accounts** — Present the list, ask which account to use for this session. Pass that `account_email` on every Drive tool call.

If any Drive call returns a permission error, surface it: the active account may not have access to that file or folder. Offer to try another account if one is available.

## Orient and Interview

Before touching anything — before `git init`, before creating files — look around, read what the team has already decided, and then talk to the developer.

**Step 1: Observe the local directory silently.** Check what exists: `.git/`, `.teamcraft/project.md`, `CLAUDE.md`, `.claude/rules/`, `.gitlab-ci.yml`, and any project config files (package.json, go.mod, Cargo.toml, requirements.txt, pyproject.toml, etc.). Do not run `git init` yet. Do not create anything. Just observe.

**Step 2: Identify the GitLab project.** This is the one thing the developer must answer before anything else — which project is this?

- **Empty directory:** Use `mcp__gitlab__list_projects` to surface visible projects. Ask the developer which one this directory belongs to.
- **Has `.git`:** Check `git remote -v` to identify the project. Confirm with the developer. If no remote resolves, fall back to `mcp__gitlab__list_projects`.

**Step 3: Read what the team has already decided.** With the GitLab project identified, gather context from existing sources before asking the developer anything else:

- **Drive artifacts:** Ask the developer if they have Drive artifact URLs (PRD, tech decisions, conventions) to link — if they can point at them, load them directly; if not, ask whether to search Drive. When found, read them. They reveal tech stack decisions, scaffolding approaches, and conventions already established by the team.
- **GitLab issues:** For greenfield projects (empty directory), use `mcp__gitlab__list_issues` to read the current milestone's issues — especially the first issue, which typically defines the scaffolding approach. Read the issue descriptions; they often specify which tools to use, what the project structure should look like, and what the tech stack is.

This step is critical. The tech lead or PM may have already decided whether a scaffolding tool is required, which one, and how the project should be structured. Those decisions live in Drive artifacts and GitLab issues — not in the developer's head.

**Step 4: Present what you found and confirm.** Now — with context from Drive and GitLab — present your understanding to the developer. What you present depends on the directory state:

- **Empty directory (greenfield):** Summarize the tech decisions and scaffolding approach you found in Drive artifacts and/or the GitLab issues. Then confirm:
  > "Based on [source — tech decisions doc / issue #N / both], this project uses [tech stack]. [If scaffolding tool identified:] The plan calls for [tool, e.g., Vite] for scaffolding, which needs an empty directory — so I'll hold off on creating any files until you've run it. [If no scaffolding tool identified:] I didn't find any scaffolding tool specified — are you building the structure by hand, or is there a scaffolding tool I should know about? [If sources were unavailable:] I wasn't able to read Drive artifacts or GitLab issues, so I need your guidance: will you be using a scaffolding tool that needs a clean directory (e.g., cookiecutter, create-react-app, Vite, cargo init)?"

  The developer confirms or overrides. They may know something has changed since the documents were written — follow their lead.

- **Has `.git` but no teamcraft files (brownfield):** This is an existing repo, first time using TeamCraft. No scaffolding question needed — there's already code here. Summarize what you found in Drive artifacts and the codebase, then proceed.

- **Has `.teamcraft/project.md` and/or `CLAUDE.md` (audit/update):** Read what exists, assess what's current, and propose updates. Ask the developer what prompted them to re-run init-project.

**Step 5: Act on what you learned.**

For **greenfield with a scaffolding tool**: Do NOT run `git init`. Do NOT create any files. Explain that you'll wait for them to run their scaffolding tool first, then come back to you — or they can run it right now in this session and tell you when it's done. Once scaffolding is complete, proceed with git init (if the scaffolding tool didn't already create one), GitLab remote setup, and all TeamCraft file creation. Everything gets committed together as the first commit.

For **greenfield without a scaffolding tool**: Run `git init`. Add the remote with `git remote add origin <url>`. Confirm the remote is set before continuing.

For **brownfield**: Confirm the GitLab project from git remote context. Never assume.

## CLAUDE.md Content

The question that determines what belongs: **what would Claude Code likely get wrong about this project that it cannot figure out by reading the environment, and that no skill already brings into context?**

For a fresh scaffold with no code yet: tech decisions that aren't yet visible in the code belong here — the commitment choices that would cause real implementation mistakes if Claude Code guessed wrong. As the codebase grows, these entries get revisited and trimmed when the code makes them obvious.

For an existing codebase: the code reveals most things. CLAUDE.md content is likely short — deprecated patterns to avoid, infrastructure constraints invisible in code, architectural decisions that look like bugs without historical context, non-obvious conventions the team has established.

**Multi-level CLAUDE.md:** For mono repos and large poly repos where multiple services each have their own stack root (their own package.json, go.mod, etc.), each service root may benefit from its own CLAUDE.md alongside the repo-root CLAUDE.md. Analyze the directory structure. If distinct service roots exist, guide the developer accordingly — each per-service CLAUDE.md focuses on what is non-obvious in that service's context; the repo-root CLAUDE.md covers what applies across all services.

The file always begins with `@.teamcraft/project.md`. Everything after that is only what passes the question above.

See `references/example-claude-md.md` for correct examples and what does not belong.

## .claude/rules/ Content

Ask the developer what domains have specific conventions worth capturing: API design, testing approach, database patterns, security requirements, frontend component structure. Create one rules file per relevant domain using `paths` frontmatter to scope loading. Rules that apply across all work go in rules files without `paths`.

See `references/example-claude-md.md` for correct rules file format.

## CI/CD Baseline

Detect the tech stack from the local codebase. Generate a `.gitlab-ci.yml` that includes:
- A `test` stage running the project's actual test suite using the stack-appropriate command
- A `quality` stage running lint or format checking appropriate to the detected stack
- A `security` stage using the GitLab CE secret detection template

Generate pipeline content from knowledge of each stack's tooling — do not hardcode specific YAML inline here. The goal is real quality gates, not placeholder echo jobs.

For brownfield projects: inspect the existing `.gitlab-ci.yml` first. Add only the stages that are absent. Do not alter existing stages.

After writing `.gitlab-ci.yml` locally (or confirming the brownfield extension), attempt to set merge protection via GraphQL as described in Hard Constraints. Report whether it succeeded or fell back to manual steps.

## Confirm Before Writing

Show all proposed file content before creating or modifying anything. For existing files, show what changes. Write nothing without confirmation.

## Commit the Files

These files are team artifacts that belong in the repo — not gitignored, not left uncommitted. After writing them, offer to commit everything that was created or updated:

- Stage the specific files: `.teamcraft/project.md`, `CLAUDE.md`, any `.claude/rules/` files written, `.gitlab-ci.yml` if created or modified
- Present the proposed commit message for confirmation before committing — something like: `chore: add TeamCraft project files (CLAUDE.md, project manifest, rules, CI pipeline)`
- Commit only after the developer confirms

## Push Main to Remote

After the commit, push `main` to the remote: `git push -u origin main`. This is critical for greenfield repos — if a feature branch gets pushed before `main` exists on the remote, GitLab makes that feature branch the default, which breaks the entire MR workflow.

If the push fails due to auth, follow the guidance in `references/git-push-guidance.md` exactly — detect, stop, guide the developer, and wait.

## Done

Confirm what was committed and pushed. Note that `CLAUDE.md` is a living document maintained for the life of the project — updated as lessons are learned, new conventions emerge, and codebase patterns make old entries redundant. The `teamcraft-glgd:sync-claude-md` skill handles ongoing maintenance.