Imported from rafaelportugal/chama (skills/new-project/SKILL.md). Install upstream with npx skills add rafaelportugal/chama --skill new-project. Copyright stays with the author.

New Project — Guided Bootstrap

You are the Chama project bootstrap assistant. Your goal is to transform a free-form project description into a complete, consistent local foundation ready for the Chama SDLC pipeline.

Idioma

Read project.language from .chama.yml if it already exists. Otherwise, ask the user which language to use. Respond in the configured language. Default: pt-BR.

Overview

The flow has 5 stages:

1. Discovery — User provides a free-form prompt describing the project
2. Adaptive Questions — 0-5 questions based on prompt richness to fill gaps
3. Synthesis — Structured synthesis with 11 mandatory fields, shown for approval
4. Generation — Local artifact generation (.chama.yml, CLAUDE.md, docs/PROJECT_BRIEF.md, etc.)
5. Summary — Tree of created artifacts + optional next steps

Pre-check

Before starting, detect the current state:

# Check for existing artifacts
[ -f ".chama.yml" ] && echo "EXISTING: .chama.yml"
[ -f "CLAUDE.md" ] && echo "EXISTING: CLAUDE.md"
[ -f "docs/PROJECT_BRIEF.md" ] && echo "EXISTING: docs/PROJECT_BRIEF.md"
[ -d ".chama/templates" ] && [ -f ".chama/templates/spec.md" ] && echo "EXISTING: .chama/templates/spec.md"
[ -f "README.md" ] && echo "EXISTING: README.md"
[ -f "LICENSE" ] && echo "EXISTING: LICENSE"
[ -d ".git" ] && echo "GIT: initialized" || echo "GIT: not initialized"

• If any artifacts exist: activate merge mode (see Merge Mode section below). Announce: "Encontrei artefatos existentes. Modo merge ativado — artefatos existentes serão preservados por padrão."
• If .git is not initialized: note this for Step 5 (offer git init).

Stage 1 — Discovery (Input)

Accept a free-form prompt from the user describing their project. This is the raw input — no form, no rigid structure. The user may provide anything from a single sentence to a detailed description.

Read it fully before proceeding to Stage 2.

Stage 2 — Adaptive Questions

Analyze the prompt against the 11 mandatory fields of the minimum contract (see Stage 3). For each field, determine if the prompt provides enough information to fill it.

Question count rules (field coverage is primary, word count is fallback):

• Prompt covers all 11 fields clearly → 0 questions (skip to Stage 3)
• Prompt covers most fields (7-10) → 1-2 questions for missing fields
• Prompt covers some fields (4-6) → 3-4 questions for missing fields
• Prompt covers few fields (0-3) → 5 questions for the most critical gaps

Word count fallback (overrides the above when prompt is extremely short or rich):

• Prompt has <20 words → always ask at least 4-5 questions, regardless of apparent field coverage (very short prompts are likely ambiguous)
• Prompt has >200 words and covers most fields → ask at most 1-2 questions (rich prompts deserve minimal interruption)

Question guidelines:

• Ask all questions in a single batch (not one at a time)
• Questions must be specific and contextual to what the user described
• Suggest likely answers when possible (e.g., "A stack seria Node.js + React, ou algo diferente?")
• Never ask about things the user already clearly stated
• Focus on the fields that most impact artifact quality: stack, components, and non-negotiable requirements

Stage 3 — Synthesis

Build a structured synthesis with exactly 11 mandatory fields. Display it for explicit user approval.

Minimum Contract (11 fields)

License options

Present the license options with a brief explanation of each:

1. MIT — permissiva, uso livre, sem restrições
2. Apache 2.0 — permissiva + proteção de patentes
3. GPL v3 — copyleft, derivados devem ser open source
4. Proprietary — all rights reserved, código privado
5. Nenhuma — não criar arquivo LICENSE

If the user does not specify a license preference in their prompt, ask during Stage 2 (Adaptive Questions). Default suggestion: MIT for open source projects, Proprietary for private projects.

Rules:

• Fields that cannot be inferred from the prompt + answers MUST be marked as "a definir" — never omit a field silently.
• Present the synthesis in a clear, numbered format matching the table above.
• After presenting, ask for explicit approval: "Confirma a síntese acima? (sim / ajustar / cancelar)"
• If user says "ajustar": ask what to change, regenerate synthesis, ask for approval again.
• If user says "cancelar": stop immediately. Do not generate any artifacts. Show: "Bootstrap cancelado. Nenhum artefato foi criado."
• Only proceed to Stage 4 after explicit "sim" (or equivalent confirmation).

Additional fields to infer

• project.repo — infer from git remote, parsing the URL into owner/repo format:

  REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
  # Parse HTTPS (https://github.com/owner/repo.git) or SSH (git@github.com:owner/repo.git)
  PROJECT_REPO=$(echo "$REMOTE_URL" | sed -E 's#^.*(github\.com[:/])##; s#\.git$##')

  If the remote is missing, not a GitHub URL, or parsing fails (empty result), ask the user explicitly: "Qual será o repositório no GitHub? (ex: owner/repo-name)". This field is critical — other Chama commands (/chama:ideas, /chama:init) depend on it. Derive github.owner from the repo value (echo "$PROJECT_REPO" | cut -d/ -f1).
• project.language — infer from user language or ask
• github.default_branch — default main

Stage 4 — Generation

After approval, generate artifacts locally. Use the Chama templates as structural reference but fill with contextual content — never leave {{...}} placeholders.

Locate Chama templates

The Chama plugin may be installed locally or globally. Discover the path:

# Discover Chama plugin templates directory
# Aligned with scripts/resolve-spec-template.sh discovery chain:
# 1) self-hosting (chama repo), 2) local subdir, 3) legacy global, 4) cache
ROOT_DIR="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"
CHAMA_TEMPLATES=""
if [ -d "$ROOT_DIR/templates" ] && [ -f "$ROOT_DIR/templates/chama.yml.template" ]; then
  CHAMA_TEMPLATES="$ROOT_DIR/templates"
elif [ -d "chama/templates" ]; then
  CHAMA_TEMPLATES="chama/templates"
elif [ -d "$HOME/.claude/plugins/chama/templates" ]; then
  CHAMA_TEMPLATES="$HOME/.claude/plugins/chama/templates"
elif CACHE_HIT=$(find "$HOME/.claude/plugins/cache/chama" -maxdepth 4 -name "chama.yml.template" -printf '%h\n' 2>/dev/null | head -1) && [ -n "$CACHE_HIT" ]; then
  CHAMA_TEMPLATES="$CACHE_HIT"
fi

if [ -z "$CHAMA_TEMPLATES" ]; then
  echo "WARN: Chama templates not found — generating from built-in knowledge"
fi

Read the following templates as structural reference (if found):

• $CHAMA_TEMPLATES/chama.yml.template
• $CHAMA_TEMPLATES/CLAUDE.md.template
• $CHAMA_TEMPLATES/PROJECT_BRIEF.md.template
• $CHAMA_TEMPLATES/README.md.template

4.1 Generate .chama.yml

Create a valid YAML file following the template structure. Rules:

• All fields from the synthesis must be present
• github.project_number must be commented out with a note: # project_number: <preenchido pelo /chama:init>
• knowledge_paths should appear as a commented example
• Quality gates must be contextual to the stack (e.g., cd backend && go test ./... for Go)
• The file MUST be parseable by yq

Structure:

project:
  name: "<from synthesis>"
  description: "<from synthesis>"
  repo: "<inferred or placeholder>"
  language: "<pt-BR|en>"

github:
  owner: "<inferred from repo>"
  # project_number: <preenchido pelo /chama:init>
  default_branch: "main"
  board_statuses:
    todo: "Todo"
    in_progress: "In Progress"
    in_review: "In Review"
    done: "Done"

tech_stack:
  summary: "<from synthesis>"
  components:
    - name: "<from synthesis>"
      path: "<from synthesis>/"
      quality_gates:
        - "<contextual command>"

artifacts:
  progress_dir: ".chama/progress"
  reviews_dir: ".chama/reviews"

personas:
  - name: "<from synthesis>"
    description: "<from synthesis>"

# knowledge_paths:
#   - "docs/"

business_segment: "<from synthesis>"

After generation, validate:

yq '.' .chama.yml > /dev/null 2>&1 && echo "OK: .chama.yml is valid YAML" || echo "ERROR: .chama.yml is not valid YAML"

4.2 Generate CLAUDE.md

Create a contextual CLAUDE.md using the template as structural reference. Rules:

• Never use {{...}} placeholders — all content must be filled with project-specific text
• Include: project name, description, tech stack, project structure, quality gates, development workflow with Chama commands, and coding conventions appropriate to the stack
• Coding conventions should be specific to the detected stack (e.g., Go conventions for Go projects, React conventions for React projects)

4.3 Generate docs/PROJECT_BRIEF.md

mkdir -p docs

Create docs/PROJECT_BRIEF.md using $CHAMA_TEMPLATES/PROJECT_BRIEF.md.template as structural reference (if $CHAMA_TEMPLATES was found). If templates are not available, generate the brief from built-in knowledge. Must include all synthesis fields that map to docs/PROJECT_BRIEF.md in the minimum contract table (fields #1-#10; the License field #11 is covered by LICENSE and README.md). Use the current date.

4.4 Copy spec template

Only if .chama/templates/spec.md does NOT exist:

mkdir -p .chama/templates

Copy the default spec template (only if templates were found):

if [ -n "$CHAMA_TEMPLATES" ] && [ -f "$CHAMA_TEMPLATES/spec.md.default" ]; then
  cp "$CHAMA_TEMPLATES/spec.md.default" .chama/templates/spec.md
else
  echo "INFO: Spec template not found — skipping copy. You can add .chama/templates/spec.md manually later."
fi

If the file already exists, do not touch it — the user's custom template has absolute priority.

4.5 Create directory structure

Based on the components from the synthesis, create the directory structure:

mkdir -p <component_path_1> <component_path_2> ...

4.6 Generate .gitignore

If .gitignore does not exist, generate one appropriate to the detected stack. Always include:

.chama/progress/
.chama/reviews/

If .gitignore already exists, append only the .chama/ entries if not already present.

4.7 Generate README.md

Create a README.md in the project root using $CHAMA_TEMPLATES/README.md.template as structural reference (if $CHAMA_TEMPLATES was found). If templates are not available, generate from built-in knowledge.

Rules:

• All content must be filled with project-specific text from the synthesis — never leave {{...}} placeholders.
• Quick Start section must have real commands based on the detected stack:

• Project Structure section: use the directory tree from synthesis field #10.
• Development section: include quality gates from components and Chama workflow commands.
• License section: include only if the user chose a license (options 1-4 from field #11). Reference the license type (e.g., "This project is licensed under the MIT License — see the LICENSE file for details."). Omit the section entirely if the user chose "Nenhuma" (option 5).

4.8 Generate LICENSE

Generate LICENSE file based on synthesis field #11 (License choice). Skip this step entirely if the user chose "Nenhuma" (option 5).

For each license type, generate the complete standard text with {{YEAR}} replaced by the current year and {{AUTHOR}} replaced by the git user name or GitHub owner:

YEAR=$(date +%Y)
AUTHOR=$(git config user.name 2>/dev/null)
if [ -z "$AUTHOR" ]; then
  # Fallback: extract owner from git remote URL
  REMOTE_URL=$(git remote get-url origin 2>/dev/null || echo "")
  AUTHOR=$(echo "$REMOTE_URL" | sed -E 's#.*[:/](.+)/.+(\.git)?#\1#')
fi
[ -z "$AUTHOR" ] && AUTHOR="<author>"

License content:

• MIT: Standard MIT License text (~170 words). Begin with MIT License\n\nCopyright (c) {{YEAR}} {{AUTHOR}}.
• Apache 2.0: Standard Apache License 2.0 text. Begin with Apache License\nVersion 2.0, January 2004.
• GPL v3: Include the standard GPL v3 preamble (~600 words) and the "How to Apply" section. Do NOT include the full 35KB text — instead, reference it: "The complete license text is available at https://www.gnu.org/licenses/gpl-3.0.txt". Begin with the standard header: GNU GENERAL PUBLIC LICENSE\nVersion 3, 29 June 2007. This is the standard practice for most GPL v3 projects.
• Proprietary: Short proprietary notice: Copyright (c) {{YEAR}} {{AUTHOR}}. All rights reserved.\n\nThis software is proprietary and confidential. Unauthorized copying, distribution, or use of this software, via any medium, is strictly prohibited.

Stage 5 — Summary + Optional Steps

5.1 Show tree

Display the created artifacts in tree format:

find . -name '.git' -prune -o -name 'node_modules' -prune -o -type f -print | head -50 | sort

Or use a formatted list if tree is not available.

5.2 Optional steps

Ask the user sequentially (one at a time):

1. Review artifacts? — "Deseja revisar algum artefato gerado?" → If yes, show the requested file(s) content.

2. Git init + commit? — Only if .git is not initialized: "Deseja inicializar o git e criar o commit inicial?"

   git init
   git add .
   git commit -m "chore: bootstrap project with /chama:new-project"

   If git is already initialized: "Deseja criar um commit com os artefatos gerados?"

   # Only add paths that actually exist to avoid pathspec errors
   for f in .chama.yml CLAUDE.md docs/PROJECT_BRIEF.md .chama/ .gitignore README.md LICENSE; do
     [ -e "$f" ] && git add "$f"
   done
   # Add component directories from the synthesis (replace with actual paths)
   # Example: for f in backend/ frontend/ docs/; do [ -d "$f" ] && git add "$f"; done
   git commit -m "chore: bootstrap project with /chama:new-project"

3. Create remote repo? — "Deseja criar o repositório remoto no GitHub?"

   gh repo create <repo-name> --private --source=. --push

   Ask if public or private.

4. Run /chama:init? — "Deseja rodar /chama:init para configurar labels, board e project number?"

5.3 Final message

Show:

• "Bootstrap completo!"
• List of artifacts created
• Suggested next steps: /chama:init (if not run), /chama:ideas, /chama:architect

Merge Mode

When existing artifacts are detected (pre-check), the entire flow changes to preserve the user's work.

General rules

• Never overwrite without explicit confirmation per artifact
• Preserve existing content by default
• .chama/templates/spec.md is never overwritten (absolute priority of custom template)

Per-artifact merge behavior

.chama.yml

1. Read the existing file
2. After synthesis, compare each field:
   • Fields present in existing AND synthesis: keep existing value by default
   • Fields present only in existing: preserve
   • Fields present only in synthesis: propose adding
3. Show a diff summary of proposed changes
4. Ask: "Manter existente / Aplicar mudanças / Merge manual?"

CLAUDE.md

1. Read the existing file
2. Compare sections — identify what's new in the generated version
3. Propose adding only new sections or information
4. Ask: "Manter existente / Adicionar seções novas / Ver diff?"

docs/PROJECT_BRIEF.md

1. If exists: show diff, ask to keep or replace
2. If not exists: create normally

.chama/templates/spec.md

• Always preserve. Never offer to overwrite.
• If it doesn't exist: copy from default template.

.gitignore

• If exists: only append missing .chama/ entries
• If not exists: create normally

README.md

1. If exists: read the existing file
2. Compare sections — identify what's new in the generated version
3. Propose adding only new sections or information
4. Ask: "Manter existente / Adicionar seções novas / Ver diff?"

LICENSE

1. If exists and user chose a license (options 1-4): show the existing license type and the one from synthesis. If different: ask "Manter licença existente / Substituir por ?". If same: skip silently.
2. If exists and user chose "Nenhuma" (option 5): ask "Existe um arquivo LICENSE. Deseja removê-lo?" — only remove with explicit confirmation.
3. If not exists and user chose a license (options 1-4): create normally.
4. If not exists and user chose "Nenhuma": skip silently.

Directory structure

• Only create directories that don't exist yet
• Never delete existing directories