setup-project

name

setup-project

description

Scaffold or update per-repo configuration for engineering skills: issue tracker convention, triage label vocabulary, domain doc layout, and multi-repo coordination. Run before first use of story, review, or any skill that creates issues or reads domain docs. Re-run when project structure changes (new repo added, tracker switched, docs reorganized). Trigger words: setup, initialize, initialise, configure skills, issue tracker setup, new project, update config, project changed, 添加仓库, 配置变更.

Setup Project

🥷 Configure the repo so skills know where to read and write.

Scaffold the per-repo configuration that the engineering skills assume:

• Project structure — single repo, monorepo (multiple packages in one repo), or multi-repo (multiple related repos)
• Issue tracker — where issues live (GitHub, GitLab, local markdown, or other)
• Triage labels — the strings used for the five canonical triage roles
• Domain docs — where CONTEXT.md, ADRs, PRDs, and the research index live; how consumer skills find them across repos
• Documentation language — the language skills should write human-facing output in (PRDs, ADRs, CONTEXT, Issues, comments), so output is readable for the team regardless of who triggers the skill

This is a prompt-driven skill, not a deterministic script. Explore, present what you found, confirm with the user, then write.

Can be re-run. If docs/agents/ already exists, read current config first, detect what changed since last setup, present only the sections that need updating, and rewrite affected files. The user can also use this to switch issue trackers, add/remove repos from the map, or reorganize domain docs.

Relationship to the Entry Protocol

This skill creates the configuration that the Skill Entry Protocol reads at the start of every consumer skill. Without this setup, consumer skills fall back to default paths and guesses.

Config file	Entry Protocol Step	What it tells the consumer skill
docs/agents/domain.md	Step 1	Actual paths for CONTEXT.md, PRDs, ADRs, and docs/research/INDEX.md
docs/agents/issue-tracker.md	Step 1	Issue tracker type and CLI conventions
docs/agents/triage-labels.md	Step 1	Label vocabulary mapping for the five canonical triage roles
docs/agents/language.md	Step 1	Language for all human-facing prose (PRDs, ADRs, CONTEXT, Issues, comments)
docs/agents/repo-map.md	Step 2 (if exists)	Multi-repo structure — which repos exist, which owns the primary issue tracker

This is not a consumer skill — it is the foundation that consumer skills depend on. The Entry Protocol's "If missing" degradation paths ensure skills still work without setup-project, but with reduced precision.

Outcome Contract

• Outcome: docs/agents/ directory with issue-tracker, triage-labels, domain docs, documentation language, and (for multi-repo) repo-map; ## Agent skills block in AGENTS.md. On re-run: conformance sweep results — naming, language, and format audit of existing doc files.
• Done when: User confirms configuration, all files written, AGENTS.md updated
• Evidence: docs/agents/issue-tracker.md, docs/agents/triage-labels.md, docs/agents/domain.md, docs/agents/language.md; docs/agents/repo-map.md (multi-repo only)
• Output: Summary of configuration, next step to use engineering skills

Process Summary

Step 1: Explore — detect current repo state (remote, AGENTS.md, existing docs/agents/, workspace/monorepo structure). If docs/agents/ exists, read all current config files to understand existing setup.

Step 2: Detect project structure — single repo, monorepo, or multi-repo. Ask the user if detection is uncertain or if there are related repos not visible in this clone. If config already exists, compare detected structure against repo-map.md to find what changed.

Step 3: Present findings — show detected defaults (project structure, issue tracker, triage labels, domain layout, documentation language). If updating, show a diff of what changed vs current config.

Step 4: Ask for overrides — present the full detected configuration as a draft; ask if anything needs changing. If the user wants to change something, walk through that section one at a time. Sections: A (Issue Tracker), B (Triage Labels), C (Domain Docs), D (Documentation Language). If everything looks good, proceed.

Step 4a (Re-run only): Conformance sweep — After config overrides are confirmed, scan docs/prd/, docs/adr/, docs/research/ for files that don't match the new settings. Group findings by naming, language, format, and metadata. For naming violations suggest rename; for language flag and suggest /write; for format/metadata report only. Confirm with user before acting. See REFERENCE.md Conformance Sweep.

Step 5: Confirm — show the complete draft of all files to be written (AGENTS.md block + each docs/agents/ file). If updating, show only files that changed.

Step 6: Write — edit AGENTS.md, create or update docs/agents/*.md files. When writing domain.md, scan docs/prd/, docs/adr/, docs/research/ first and use actual filenames in the file tree, not template placeholders (see REFERENCE.md domain.md template note). Update in-place, never append duplicates.

Step 7: Done — list skills now configured, suggest next step

See REFERENCE.md for seed templates and detailed steps.

Gotchas

What happened	Rule
Assumed GitHub without checking remote	Step 1: Run git remote -v first
Missed monorepo/multi-repo structure	Step 2: Check for workspace files, subprojects, sibling repos
Monorepo: only configured root, missed packages	Step 6: Create per-package docs/agents/ dirs in monorepo
Multi-repo: no coordination between repos	Step 6: Create repo-map.md linking repos to skill domains
Asked all decisions at once	Step 4: Present detected defaults, ask for overrides
Created AGENTS.md when CLAUDE.md (or neither) exists	Step 6: Edit the file that exists; don't silently default to AGENTS.md
Duplicated existing ## Agent skills block	Step 6: Update in-place, don't append
Wrote files without user confirmation	Step 5: Show full draft before writing
Re-run: overwrote unchanged sections / missed drift	Step 1-2: Read existing config, compare structure against repo-map.md, only update what changed
Re-run: language change undetected / per-package out of sync	Step 4D / Step 6: Compare existing config against current state on re-run
Re-run: domain.md shows template examples, not actual files	Step 6: scan docs/prd/ docs/adr/ docs/research/ for real filenames before writing domain.md
Re-run: renamed PRDs not updated in referencing files	After renaming, scan docs/adr/ and CONTEXT.md for references to old name; suggest update
Re-run: language change didn't reach existing docs	Language Audit: flag files in wrong language, recommend /write — don't auto-translate
Re-run: format drift not detected	Format Audit: compare each file's section structure against its FORMAT spec
Migration: orphaned files after structure change (e.g. single→monorepo)	Step 2: Detect drift, present migration path, clean up with confirmation

Output

First run:

Setup complete.

Configuration:
- Project structure: <single / monorepo / multi-repo>
- Issue tracker: <GitHub / GitLab / Local / Other>
- Triage labels: <defaults / customised>
- Domain docs: <single-context / multi-context>
- Documentation language: <English / Chinese / Other>

Updated files:
- AGENTS.md — added ## Agent skills block
- docs/agents/issue-tracker.md — created
- docs/agents/triage-labels.md — created
- docs/agents/domain.md — created
- docs/agents/language.md — created
- docs/agents/repo-map.md — created (multi-repo only)

Skills now configured: think, research, have-a-try, grill, story, tdd, review, debug, improve-architecture, write

Next: Start using skills. Run /think to brainstorm a feature, /research for technical investigation, or /debug to investigate a bug.

Re-run (config update):

Config updated.

Changes:
- <what changed, e.g., "Switched issue tracker from GitHub to GitLab">
- <what changed, e.g., "Language changed from Chinese to English">

Updated files:
- docs/agents/<file>.md — updated (changed: <sections>)
- <... other files ...>

Conformance sweep:
- ✅ Naming: all files conform
- ⚠️ Language: 1 file in wrong language (suggest /write)
- ✅ Format: all files comply

Done with 1 finding, 0 fixed (requires /write).

Next: Re-run affected skills if config change affects their behavior (e.g., after language change, re-run /write on flagged docs).