teamcraft-jcg:init-project

---
name: teamcraft-jcg:init-project
description: Set up .teamcraft/project.md, CLAUDE.md, .claude/rules/, and .github/workflows/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__sooperset-mcp-atlassian__jira_get_all_projects
  - mcp__sooperset-mcp-atlassian__jira_search
  - mcp__sooperset-mcp-atlassian__jira_get_issue
  - mcp__sooperset-mcp-atlassian__confluence_search
  - mcp__sooperset-mcp-atlassian__confluence_get_page
---

## Goal

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

1. `.teamcraft/project.md` — the minimal project index: GitHub repo (owner/repo), Jira site URL, Jira project key, Jira project ID, and Confluence page IDs for key artifacts. 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. `.github/workflows/ci.yml` — a baseline quality-gate pipeline appropriate to the project's tech stack, using GitHub Actions format. After the file is written, attempt to set branch protection via `gh api` — fall back to manual UI instructions if the call fails.

## 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, GitHub repo (owner/repo), Jira site URL, Jira project key, Jira project ID (numeric), and Confluence page IDs for PRD, tech decisions, and conventions. Leave rows blank where documents don't exist. Nothing else.
- `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.
- **Brownfield CI/CD detection:** If `.github/workflows/ci.yml` already exists, do not replace it. Inspect it for the three quality-gate jobs (test, quality, security). Offer to extend it with any missing jobs only. Get confirmation before writing.
- **GitHub-hosted runners:** GitHub Actions uses GitHub-hosted runners by default — there is no runner registration prerequisite like GitLab CE. Self-hosted runner setup is out of scope and not a blocking issue.
- **Branch protection via gh api — attempt, then fall back:** Use `gh api repos/{owner}/{repo}/branches/{branch}/protection -X PUT` with a JSON body that requires status checks to pass before merging. If this fails, do not attempt other approaches. Instead, tell the developer to set it manually: Settings → Branches → Branch protection rules → Require status checks to pass before merging.
- **CI/CD is Claude Code only.** This capability reads the local filesystem to detect the tech stack and writes `.github/workflows/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.

## 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/`, `.github/workflows/`, 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 project.** This is the one thing the developer must answer before anything else — which project is this?

- **Empty directory:** Use `gh repo list` via Bash or ask the developer for the owner/repo directly. Also use `mcp__sooperset-mcp-atlassian__jira_get_all_projects` to surface Jira projects. Ask the developer to confirm both the GitHub repo and the Jira project.
- **Has `.git`:** Check `git remote -v` to identify the GitHub repo. Use `gh repo view` via Bash to confirm accessibility. Identify the Jira project from `.teamcraft/project.md` if present, otherwise search Jira. Confirm with the developer.

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

- **Confluence artifacts:** Ask the developer if they have Confluence artifact URLs or page IDs (PRD, tech decisions, conventions) to link. If they can point at them, use `mcp__sooperset-mcp-atlassian__confluence_get_page` to load them directly. If not, offer to search Confluence using `mcp__sooperset-mcp-atlassian__confluence_search`. When found, read them. They reveal tech stack decisions, scaffolding approaches, and conventions already established by the team.
- **Jira issues:** For greenfield projects (empty directory), use `mcp__sooperset-mcp-atlassian__jira_search` with JQL to read the current sprint'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 Confluence artifacts and Jira issues — not in the developer's head.

**Step 4: Present what you found and confirm.** Now — with context from Confluence and Jira — 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 Confluence artifacts and/or the Jira issues. Then confirm:
  > "Based on [source — tech decisions doc / issue KEY-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 Confluence artifacts or Jira 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 Confluence 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), GitHub 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. Confirm the Jira project.

For **brownfield**: Confirm the GitHub repo from git remote context. Confirm the Jira project. 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 `.github/workflows/ci.yml` that uses GitHub Actions format and includes:
- A `test` job running the project's actual test suite using the stack-appropriate command
- A `quality` job running lint or format checking appropriate to the detected stack
- A `security` job using a secret scanning step — `trufflesecurity/trufflehog-actions-scan` action or GitHub's native secret scanning configuration

Use GitHub Actions syntax: `on:`, `jobs:`, `steps:`, `uses:`, `run:`. Use the appropriate GitHub-hosted runner (`runs-on: ubuntu-latest` or the stack-appropriate runner). Generate real quality gates, not placeholder echo jobs.

For brownfield projects: inspect the existing `.github/workflows/` directory first. If `ci.yml` already exists, add only the jobs that are absent. Do not alter existing jobs.

After writing `.github/workflows/ci.yml` locally (or confirming the brownfield extension), attempt to set branch protection via `gh api` 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, `.github/workflows/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, GitHub makes that feature branch the default, which breaks the entire PR 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-jcg:sync-claude-md` skill handles ongoing maintenance.