setup

setup

Execute once completely per repository. Other engineering skills run .agents/scripts/precheck.mjs to determine whether setup has been done; if missing, stop and do not run this skill on their behalf.

The project category and repository structure are written in .agents/docs/PROJECT.md, do not write them into the root AGENTS.md. The business/technical architecture and tech stack are written by this skill into .agents/docs/ARCHITECTURE.md(code category only). The bad smell baseline is copied verbatim from the skill package template as .agents/docs/SMELLS.md(code category only).

Unified tool definitions

交互式提问 and other engineering skills' shared conventions are in common.md。

Completion criteria

After writing, run node .agents/scripts/precheck.mjs: if FAIL, fill in the missing items until PASS. The check items are based on that script.

Already completed and the user just said setup: tell them it is already completed, use the 交互式提问 tool to ask whether to go into "update mode".

Workflow

1. Determine the working directory

Target root directory = current workspace / git root directory. If ambiguous, you must confirm:

• The user specified a subdirectory
• Multiple git roots
• Multiple independently deliverable packages in a monorepo

Do not write files before confirming. Afterward all paths are relative to that root directory.

2. Directories and gitignore

• Create .agents/docs/、.agents/cooking/(an empty directory is fine, do not write a README)
• Create .agents/scripts/, copy the entire <engineering>/setup/scripts/ directoryto .agents/scripts/（<engineering> = this skill package directory). It contains three scripts: precheck / spec-files / cooking, and two root AGENTS templates. precheck reads templates from the same directory at runtime; none of them can be missing
• .gitignore Append .agents/cooking/(skip if already present)
• If .gitignore ignores the entire .agents/: change it to ignore only cooking;.agents/docs/ and .agents/scripts/ must be committable
• For the template see templates.md

3. Classify, write PROJECT.md

According to classify.md: for existing projects infer first; for new projects, if the category can be determined from the description, do not ask for the category again. Write .agents/docs/PROJECT.md, for the template see templates.md. Keep only the category, organizational structure, (full-stack only) architecture form, and a one-sentence "what it is".

For new project determination see new-project.md。

4. Overwrite the root AGENTS.md

Copy files with shell according to category:cp .agents/scripts/root-agents-code.md AGENTS.md or cp .agents/scripts/root-agents-non-code.md AGENTS.md(for source files see root-agents-code.md / root-agents-non-code.md). Do not hand-type the required lines. Short notes, process chapters, and writing project-specific cases as body text are prohibited.

• None: copy directly
• Exists and is very long: for code category move tech stack → ARCHITECTURE.md, development preferences → DEV-STANDARDS.md, directories/modules → CODE-MAP.md; migrate as much of the original text as can be matched. Then handle according to the next item
• Exists and is already an index: after copying the template, append the custom .agents/docs/ rows from the original table back to the end of the table (only those that are not PROJECT.md / ARCHITECTURE.md / DEV-STANDARDS.md / SMELLS.md / CODE-MAP.md count as custom). Discard short notes and process chapters. Modifying the text of the template's required lines is prohibited

User global rules (for example personal AGENTS.md) must not be copied into this repository's docs.

5. Write the remaining docs

Non-code: do not write ARCHITECTURE.md、DEV-STANDARDS.md、CODE-MAP.md、SMELLS.md. When changing from code to non-code, only change the AGENTS index; do not force deletion of those old files on disk.

Code category: first according to interview.md After multiple rounds of clarification, then follow templates.md to write:

File	Existing project	New project
ARCHITECTURE.md	Infer a draft from the code, use interviews to fill gaps and contradictions	Write based on the user's answers
DEV-STANDARDS.md	Infer from eslint/prettier/test directories/existing code; delete sections with no basis; still ask about things that must be decided by a human	Write based on the user's answers
CODE-MAP.md	Scan the actual directories; only ask when unsure how to split modules	Write the planned directories according to the organizational structure, confirm the module split; if directories have not been created yet, mark them as "planned"
SMELLS.md	From smells.md copy verbatim; if it already exists, overwrite it with the current template	Same as left. Do not rewrite, append, or delete items based on the project

For when to change CODE-MAP, see code-map-update.md. For aligning existing documents, see persistent-docs.md。.agents/docs After the existing files, it is updated by sync-docs .

6. Report

List the paths written, one sentence per file. Do not write the process tutorial into AGENTS.md. Reminder: the process is optional; skills do not trigger automatically by default;.agents/docs If outdated, run sync-docs; if scripts / root AGENTS.md drift, run update mode again.

After the report in step 6 of the workflow, and after update mode ends normally: use 交互式提问 to ask whether to add a layer of acceptance assurance for coding (token and effort costs will increase significantly). If no or skipped: do not generate acceptance files, do not run on behalf of acceptance. If yes: only prompt to explicitly invoke acceptance. Do not write the acceptance interview into interview.md, and do not generate it in setup .agents/docs/ACCEPTANCE.md。

Update mode

When docs already exist and the user wants to refresh the foundation, or when precheck is missing items:

Change	Do
Code/non-code switch	Switch to the corresponding AGENTS template; fill in the missing code-type docs according to step 5. Switching from code to non-code does not force deletion of the old code-type docs
.agents/scripts/ Any script / template is missing or inconsistent with the skill package	From <engineering>/setup/scripts/ copy the entire directory as an overwrite
AGENTS.md It is mixed with short notes, process chapters, or is missing lines required by the template	Rebuild the required lines according to step 4, preserving user-appended .agents/docs/ index lines
Required code-type docs are missing	Fill them in according to step 5
.agents/docs/ Existing document content is outdated	Have the user run sync-docs, do not modify it here

Prohibited: delete cooking/ in-progress features in the root directory, write the full specification back into the root directory AGENTS.md. After it ends normally, execute the acceptance assurance inquiry above.