project-bootstrap
bootstrap, audit, document, or standardize a coding project or existing repository. use for new-project foundations, repository structure, prefilled engineering documents, agents.md, architecture and build specifications, test-driven development setup, ci and quality-gate planning, first vertical-slice definition, repository adoption, command detection, documentation drift checks, or preparing a codebase for ai-assisted development. preserve existing conventions by default and use the companion loop-orchestrator skill for bounded implementation cycles.
- License 许可
- MIT
- 最近更新
- 2026-09-22
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- project-bootstrap
- description
- bootstrap, audit, document, or standardize a coding project or existing repository. use for new-project foundations, repository structure, prefilled engineering documents, agents.md, architecture and build specifications, test-driven development setup, ci and quality-gate planning, first vertical-slice definition, repository adoption, command detection, documentation drift checks, or preparing a codebase for ai-assisted development. preserve existing conventions by default and use the companion loop-orchestrator skill for bounded implementation cycles.
02 资源文件 42
- 参考文档agents/openai.yaml109 B
- 资产文件assets/project-docs/.github/ISSUE_TEMPLATE/bug_report.md.tpl584 B
- 资产文件assets/project-docs/.github/pull_request_template.md.tpl795 B
- 资产文件assets/project-docs/AGENTS.md.tpl3.4 KB
- 资产文件assets/project-docs/CHANGELOG.md.tpl329 B
- 资产文件assets/project-docs/CONTRIBUTING.md.tpl963 B
- 资产文件assets/project-docs/docs/ACCESSIBILITY.md.tpl673 B
- 资产文件assets/project-docs/docs/API.md.tpl739 B
- 资产文件assets/project-docs/docs/ARCHITECTURE.md.tpl2.2 KB
- 资产文件assets/project-docs/docs/BACKUP_RECOVERY.md.tpl670 B
- 资产文件assets/project-docs/docs/BUILD_LOG.md.tpl1.3 KB
- 资产文件assets/project-docs/docs/BUILD_SPEC.md.tpl2.2 KB
- 资产文件assets/project-docs/docs/DATABASE.md.tpl680 B
- 资产文件assets/project-docs/docs/DECISIONS.md.tpl1.5 KB
- 资产文件assets/project-docs/docs/DEPLOYMENT.md.tpl1004 B
- 资产文件assets/project-docs/docs/ENGINEERING_DIARY.md.tpl958 B
- 资产文件assets/project-docs/docs/ERROR_LOG.md.tpl866 B
- 资产文件assets/project-docs/docs/LOOP_ENGINEERING.md.tpl2.2 KB
- 资产文件assets/project-docs/docs/OBSERVABILITY.md.tpl737 B
- 资产文件assets/project-docs/docs/OPERATIONS.md.tpl536 B
- 资产文件assets/project-docs/docs/PERFORMANCE.md.tpl738 B
- 资产文件assets/project-docs/docs/PRD.md.tpl2.4 KB
- 资产文件assets/project-docs/docs/RELEASE_PROCESS.md.tpl1.0 KB
- 资产文件assets/project-docs/docs/ROADMAP.md.tpl1.7 KB
- 资产文件assets/project-docs/docs/SECURITY.md.tpl1.3 KB
- 资产文件assets/project-docs/docs/TESTING.md.tpl1.8 KB
- 资产文件assets/project-docs/README.md.tpl1.8 KB
- 许可证LICENSE1.0 KB
- 参考文档README.md10.7 KB
- 参考文档references/cli.md3.1 KB
- 参考文档references/document-profiles.md1.7 KB
- 参考文档references/existing-repo-adoption.md1.9 KB
- 参考文档references/loop-orchestrator-integration.md1.7 KB
- 参考文档references/quality-gates.md1.7 KB
- 参考文档references/repository-signals.md1.3 KB
- 脚本scripts/audit_repository.py11.2 KB
- 脚本scripts/project_common.py18.5 KB
- 脚本scripts/scaffold_project.py13.6 KB
- 脚本scripts/test_audit_repository.py4.0 KB
- 脚本scripts/test_scaffold_project.py12.3 KB
- 脚本scripts/test_validate_project.py5.1 KB
- 脚本scripts/validate_project.py8.0 KB
03 SKILL.md 正文
Project Bootstrap
Create a truthful, proportional, testable engineering foundation. Prefer executable commands and maintained source-of-truth files over a documentation museum.
Responsibility split
Use two layers deliberately:
- Reasoning layer: inspect the request and repository, resolve scope, classify evidence, customize files, and apply surgical updates.
- Deterministic layer: use bundled scripts for scaffolding, repository auditing, and repeatable validation.
Do not describe a deterministic script as understanding the whole architecture. Do not skip repository reasoning merely because a script produced a clean report.
Read references/document-profiles.md to select the document set. Read references/existing-repo-adoption.md before changing a non-empty repository. Read references/quality-gates.md for TDD and Definition of Done. Read references/cli.md before running scripts. Read references/loop-orchestrator-integration.md when implementation should continue through bounded loops.
Operating principles
- Preserve existing code, docs, formatting, terminology, and architecture unless the user explicitly approves replacement.
- Infer facts from manifests, lockfiles, CI, tests, source, deployment configuration, and current operations before prose.
- Mark unresolved decisions as
Not yet decided; never invent commands, environments, compliance requirements, or deployment facts. - Use the smallest profile that adequately controls project risk.
- Build one complete vertical slice before expanding horizontally.
- Write or update the failing test first for behavioral changes.
- For documentation, configuration, CI, or schema work, run the smallest relevant validator first instead of inventing meaningless unit tests.
- Run targeted checks before broader checks. Refactor only while relevant checks remain green.
- Record verified outcomes and significant root causes.
- Do not ask questions already answered by the request or repository evidence.
Decide the workflow
- Determine repository mode:
- Empty or not yet created: use New project workflow.
- Any existing source, manifest, documentation, or history: use Existing repository workflow.
- Select a profile:
prototype: experiment, proof of concept, or short-lived demo.standard: maintained app, service, library, learning product, or internal tool. Use by default.production: customer-facing, revenue-critical, regulated, or operationally sensitive system.
- Select a layout:
generic,web-app,api-service,library, ormonorepo.
- Determine whether the user wants files created, a plan only, or an existing repository changed.
- Establish the first vertical slice and its acceptance criteria.
- Decide whether to hand execution to Loop Orchestrator.
New project workflow
- Capture the project name, problem, users, outcome, success criteria, non-goals, constraints, stack, data sensitivity, deployment target, and first vertical slice.
- Resolve low-risk omissions with conservative defaults. Keep high-impact unknowns explicit.
- Run the scaffolder:
python scripts/scaffold_project.py \
--target /path/to/project \
--name "Project Name" \
--summary "One-sentence outcome" \
--users "Primary users" \
--profile standard \
--layout web-app \
--mode new
- Replace generic baseline statements with project-specific evidence. Remove irrelevant sections.
- Create only stack-appropriate package, formatter, linter, type-checker, test, environment, and CI configuration. Do not play framework roulette.
- Define the first slice across interface, validation, authorization, business logic, persistence, feedback, logging, and automated tests.
- Run the doctor:
python scripts/validate_project.py --target /path/to/project --profile standard
- Record actual validation outcomes in
docs/BUILD_LOG.md. - Initialize a bounded Loop Orchestrator objective when implementation continues.
Existing repository workflow
Never bootstrap an existing repository as though it were empty.
Inspect
- Inspect the root tree, manifests, lockfiles, source, tests, CI, environment examples, database and deployment configuration, current docs, and recent Git history when available.
- Run the deterministic audit:
python scripts/audit_repository.py \
--target /path/to/repository \
--profile standard
- Verify audit findings against executable evidence. Treat heuristic
validresults as candidates for preservation, not proof of correctness. - Classify each expected artifact as:
valid: accurate and useful; preservestale: patch inaccurate sections onlymissing: createconflicting: record the conflict and choose the least disruptive resolution
Plan
- Separate proposed actions into
create,patch,preserve,skip, andblocked. - Preview missing-file generation:
python scripts/scaffold_project.py \
--target /path/to/repository \
--name "Repository Name" \
--profile standard \
--mode existing \
--dry-run
- Do not combine documentation adoption with unrelated framework swaps, mass renames, or repo-wide formatting.
Apply
- Run the scaffolder without
--dry-runto create missing files only. - Use
--forceonly for explicitly approved files. Use--refresh-managedonly when generated hashes prove a file remains unmodified since generation. - Patch stale documents surgically while preserving useful structure, voice, and repository-specific guidance.
- Add characterization tests before changing unclear legacy behavior.
- Introduce quality gates incrementally and keep local commands aligned with CI.
- Run the doctor and produce an adoption report with evidence, changes, preserved files, unresolved conflicts, risks, and the next three actions.
Prefilled foundation
Depending on profile, generate substantive starting files such as:
README.md,AGENTS.md,CHANGELOG.md, andCONTRIBUTING.md- PRD, architecture, build specification, roadmap, testing, security, deployment, decisions, build log, error log, and loop-engineering guidance
- production API, database, observability, operations, performance, accessibility, backup, recovery, and release documents
- pull-request and bug-report templates
.project-bootstrap.jsonplus generator metadata under.project-bootstrap/
Templates are baselines, not sacred text. Delete irrelevant sections and deepen the parts that control real risk.
AGENTS.md requirements
Keep agent guidance operational. Include:
- mission, users, non-goals, and source-of-truth order
- verified setup and validation commands
- repository map and architecture boundaries
- test-first or validator-first loop rules
- small-change, preservation, and rollback rules
- security, data, and secret handling
- documentation update rules
- Definition of Done
- instructions for build, error, and loop logs
For an existing repository, merge these rules into current guidance rather than replacing useful local knowledge.
Quality and evidence rules
Use these statuses only:
passed: the command ran successfullyfailed: the command ran and failed; include the causeblocked: a required dependency or environment was unavailablenot applicable: the gate does not apply; include the reason
Never report an unexecuted check as passing. Never turn coverage percentage into a substitute for risk-based tests.
Loop Orchestrator handoff
Use the companion Loop Orchestrator Skill when the foundation is ready and one bounded objective should be executed. Provide:
- one objective
- explicit acceptance criteria
- a test or validator command
- an iteration budget
- known constraints and blockers
- the first hypothesis or inspection target
Stop and return to Project Bootstrap when the loop reveals a new architectural decision, missing source-of-truth document, or scope change.
Output contract
Deliver working files or a precise patch, not advice alone. Finish with:
- mode, profile, and layout
- files created, patched, preserved, skipped, and blocked
- detected stack, commands, and supporting evidence
- first vertical slice and acceptance criteria
- validation results with honest statuses
- unresolved decisions and risks
- Loop Orchestrator handoff or the next three executable actions
When the user requests only a plan, provide the proposed tree, documents, sequence, and acceptance criteria without pretending files were created.
04 同仓库更多 Skills
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
openai-docs
Use when the user asks how to build with OpenAI products or APIs, asks about Codex itself or choosing Codex surfaces, needs up-to-date official documentation with citations, help choosing the latest model for a use case, or model upgrade and prompt-upgrade guidance; use OpenAI docs MCP tools for non-Codex docs questions, use the Codex manual helper first for broad Codex self-knowledge, and restrict fallback browsing to official OpenAI domains.
imagegen
Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output should be a bitmap asset rather than repo-native code or vector. Do not use when the task is better handled by editing existing SVG/vector/code-native assets, extending an established icon or logo system, or building the visual directly in HTML/CSS/canvas.
sleek
Modern minimalist aesthetic with clean lines, intentional color palette, subtle interactions, and consistent spacing.
screenshot
Use when the user explicitly asks for a desktop or system screenshot (full screen, specific app or window, or a pixel region), or when tool-specific capture capabilities are unavailable and an OS-level capture is needed.