project-to-variant
Convert an existing standalone project into an official variant template. Use when: a proven project should become a reusable template for future projects.
- License 许可
- AGPL-3.0
- 最近更新
- 2026-11-14
- Stars
- ★ 25
- Forks
- 9
01 前言 Front Matter
- name
- project-to-variant
- owner
- scaffolding-expert
- scope
- workspace
- status
- active
- version
- 1.3.0
- metadata
- { "type": "scaffolding", "triggers": [ "convert project to variant", "create variant from project", "project to template", "promote project to variant" ] }
- relates_to
- [ { "type": "composes_with", "skill": "promote-variant" } ]
- description
- Convert an existing standalone project into an official variant template. Use when: a proven project should become a reusable template for future projects.
- last_reviewed
- 1794096000000
03 SKILL.md 正文
Project to Variant
Converts an existing standalone project into an official co-* variant template.
When to Use
- An existing project has proven domain-specific patterns worth reusing
- 3+ custom agents or 2+ custom skills have been developed
- The project is expected to spawn 3+ future projects
- The project has been tested in 2+ engagements and is stable
Script
Script: scripts/project-to-variant.ts
Usage: bun scripts/project-to-variant.ts --source <project-path> --target <variant-name> [--dry-run] [--force] [--design-doc <path>] [--threshold-files <n>] [--threshold-dirs <n>]
Arguments
| Argument | Required | Description |
|---|---|---|
--source <path> |
Yes | Path to the existing project (e.g., Projects/co-legal) |
--target <name> |
Yes | Variant name, must match ^co-[a-z][a-z0-9-]{1,30}$ (e.g., co-legal) |
--dry-run |
No | Preview without writing files |
--force |
No | Proceed even if the complexity routing check recommends the Full L2 Pipeline instead |
--design-doc <path> |
No | Auto-register this spec via spec-register.ts (can't be auto-discovered) |
--threshold-files <n> |
No | Override the variant-unique-file-count routing threshold (default 40) |
--threshold-dirs <n> |
No | Override the large-domain-dir-count routing threshold (default 3) |
What It Does
- Diffs the project against
templates/common/ - Keeps only variant-unique files
- Skips
.git/,node_modules/,memory/ - Complexity routing check: if the project diverges significantly from
templates/common/(more than--threshold-filesvariant-unique files, or more than--threshold-dirsdomain directories with >15 files each that don't exist intemplates/common/), it prints a recommendation to use the Full L2 Pipeline instead and aborts unless--forceis passed — this automates the judgment call that used to live only in this doc's prose (see Alternative below) - Generates
variant.jsonif not present - Runs
validate-templates.tsfor verification - Regenerates
templates/<target>/AGENTS.mdviaregenerate-agents-md.ts(mechanical — always run, not gated on judgment) - Registers the spec via
spec-register.tsif--design-docwas passed - Outputs a manual review checklist for the remaining judgment-based items only (
pm.mdoverride review,CLAUDE.md/GEMINI.mdnarrative context, country-profile review items)
Country Profiles and Country-Scoped Skills
When the source project carries country assets, the conversion handles them as follows:
docs/countries/ACTIVE.mdis excluded - it records this project's country selection (project state), not reusable template knowledgedocs/countries/<CODE>.mdprofiles are carried into the template - they are durable jurisdiction knowledge (statutes, regulators, formats)- The
country_configkey invariant.jsonis preserved, keepingsupportedin sync with the carried profiles - Country-scoped skills (all six
k-*skills - see thecountry_scoped_assetsregistry indocs/workspace-schema.json) are never copied into the variant: they already live intemplates/common/skills/and deploy only to matching-country projects at scaffold time
When reviewing the output, confirm country_config.supported matches exactly the profiles carried into templates/<target>/docs/countries/. The full L2 pipeline (l3-to-variant-pipeline.ts) applies the same rules. See ADR-0057 for the full mechanism.
Step-by-Step Procedure
- Evaluate suitability: ≥3 domain agents, ≥2 skills, ≥3 expected future projects
- Prepare: Remove
node_modules/,.env,memory/,CHANGELOG.md - Run conversion:
bun scripts/project-to-variant.ts --source <project-path> --target <variant-name> --design-doc <path-to-design-doc> - Verify:
bun scripts/validate-templates.ts - Review variant.json: Check agents, skills, script_manifest, and
country_config(if country profiles were carried) - Complete the printed manual checklist:
pm.mdoverrides andCLAUDE.md/GEMINI.mdnarrative context — everything else is now automated
Alternative: Full L2 Pipeline
The script itself recommends this automatically when the complexity routing check trips (see step 4 above). For a more thorough conversion with ADR-referenced review, anti-swelling checks, and platform-parity enforcement:
cp -r <project-path> Projects/<variant-name>/
cd Projects/<variant-name>/ && git init && git add -A && git commit -m "initial"
cd <workspace-root>
bun scripts/l3-to-variant-pipeline.ts --l3-path Projects/<variant-name>/ --name <variant-name> --type <collaboration|consulting|lecture> --description "<one-line description>" --auto-fix-agents-md --auto-fix-pm-md
Since l3-to-variant-pipeline.ts v1.21.2, --auto-fix-agents-md / --auto-fix-pm-md let the pipeline regenerate the variant AGENTS.md from the L3 roster, and generate-variant.ts ≥ 1.12.0 materializes domain skills into all three skill roots, preserves agent lifecycle frontmatter, and re-applies VARIANT-INJECT markers — the manual post-run fixes this path used to require are automated.
See Also
04 同仓库更多 Skills
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.
i18n-layout
Text layout and encoding guidance: character encoding (UTF-8, legacy Korean code pages, BOM hazards), line endings, RTL/bidi handling, and script-specific font selection (Hangul focus). Use when: encoding is corrupted or mojibake appears, an RTL locale must render correctly, fonts must be chosen for a script, or CRLF/BOM issues surface.