openspec-bootstrap-opsx
Bootstrap OPSX architecture map from existing codebase using a structured five-phase workflow (init → scan → map → review → promote).
- License 许可
- MIT
- 所属仓库
- cp-yu/edera
- 最近更新
- 2026-06-23
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- name
- openspec-bootstrap-opsx
- license
- MIT
- metadata
- { "author": "openspec", "version": "2.0", "generatedBy": "1.4.1-cpyu.1" }
- description
- Bootstrap OPSX architecture map from existing codebase using a structured five-phase workflow (init → scan → map → review → promote).
- compatibility
- Requires openspec CLI.
03 SKILL.md 正文
Bootstrap the OPSX architecture map from the existing codebase.
This is a structured, multi-phase workflow. Each phase produces intermediate artifacts in openspec/bootstrap/ before writing formal OPSX files.
Treat openspec/config.yaml as the source of truth for authoring policy, but consume its compiled projection semantics: prose-bearing bootstrap artifacts follow the projected documentation language policy, while canonical headings, IDs, schema keys, paths, and commands stay unchanged.
Input: No argument required. Scope hints (folders, domain names) are passed to init.
Steps
-
Determine current phase
openspec bootstrap status --json- If no workspace exists, start with init
- If workspace exists and is in progress, resume from the current phase
- If workspace exists and is completed, restart explicitly with
openspec bootstrap init --mode refresh --restart
-
Execute the current phase
Get phase-specific instructions:
openspec bootstrap instructions [phase] --jsonPhase: init
openspec bootstrap init --mode fullCreates workspace at
openspec/bootstrap/with scope configuration. Supported upgrade paths:specs-based -> fullraw -> fullraw -> opsx-firstformal-opsx -> refreshUseopsx-firstonly forrawrepositories when you want the formal OPSX bundle plus a README-only specs starter now, and full behavior specs later. Userefreshonly for repositories that already have the formal OPSX bundle and need a delta-first refresh that merges reviewed changes back into the existing formal files. Use--restartonly when a completed retained workspace already exists and you want a fresh run; it snapshots the oldopenspec/bootstrap/intoopenspec/bootstrap-history/first.
Phase: scan
- Read
package.json,README, OpenSpec config,openspec/specs/ - Scan source code for structural boundaries
- Write
openspec/bootstrap/evidence.yamlwith candidate domains:domains: - id: dom.cli confidence: high sources: [code:src/cli/, spec:openspec/specs/cli/] intent: CLI entry point and command routing
- Run `openspec bootstrap validate` to verify gates - In `refresh`, treat the current formal OPSX bundle as the baseline and use git diff only to narrow scan scope when a stored anchor commit is still reachable **Phase: map** - For each domain in evidence.yaml, create `openspec/bootstrap/domain-map/<domain-id>.yaml`: ```yaml domain: id: dom.cli type: domain intent: CLI entry point and command routing status: active capabilities: - id: cap.cli.init type: capability intent: Initialize OpenSpec in a project status: active relations: - from: cap.cli.init to: dom.cli type: contains code_refs: - id: cap.cli.init refs: - path: src/core/init.ts line_start: 1- Map incrementally — one domain at a time
- Run
openspec bootstrap statusto track per-domain progress - Run
openspec bootstrap validateafter all domains mapped
Phase: review
- Validate regenerates review.md and candidate OPSX files from current
evidence.yamlanddomain-map/*.yaml - Review each domain checkbox in review.md
- In
refresh, review the delta summary against the current formal OPSX baseline instead of re-approving the whole model - Check all validation checkboxes
- If evidence or domain maps change, rerun validate and re-approve the regenerated review
- Low-confidence domains appear first for priority review
Phase: promote
openspec bootstrap promote -yRe-validates all upstream gates before writing.
opsx-first: writes the formal OPSX three-file bundle plus onlyopenspec/specs/README.mdfullonraw: writes the formal OPSX bundle plus one validated spec per mapped capabilityfullonspecs-based: preserves existing specs, adds only missing capability specs, and fails fast on target-path conflictsrefreshonformal-opsx: merges the reviewed delta into the existing formal OPSX bundle, preserves existing specs, adds only missing specs for newly added capabilities, and fails fast on conflicts Promote also runs the programmatic spec frontmatter backfill. After promote, run:
openspec bootstrap backfill-specs --jsonFor unmatched specs, spawn a subagent to read the spec content and OPSX capability intents, return semantic matches, then write the returned frontmatter mappings; report any specs that still have no match. Retains the bootstrap workspace on success for audit history. Start the next refresh run with
openspec bootstrap init --mode refresh --restart, which snapshots the retained workspace intoopenspec/bootstrap-history/. -
After each phase action
- Run
openspec bootstrap validateto verify gate conditions - Run
openspec bootstrap statusto confirm phase advancement - Continue to next phase
- Run
Evidence Guidelines
- Use repository evidence only — do not fabricate
- Attach confidence levels: high (multiple sources), medium (single source), low (inferred)
- Prefer fewer domains with solid evidence over exhaustive noise
- Each domain should map to a clear architectural boundary
Mapping Guidelines
- Capability IDs follow
cap.<domain>.<action>convention - Code references must point to existing files
- Relations capture structural ownership (contains) and runtime dependencies (depends_on)
- Mark uncertain mappings for review attention
Guardrails
- Do NOT write directly to formal OPSX files — use the bootstrap workspace
- Do NOT fabricate code references
- Do NOT skip the review phase
- Do NOT treat stale review.md checkboxes as approval after evidence or mappings change
- Keep the graph small enough to audit in one sitting
04 同仓库更多 Skills
openspec-snack
Quick code-first sync: generate or update proposal + specs + simplified design from git diff when the code is already written. Use after iterative coding to back-fill specs and OPSX delta without redoing propose→apply. Does not generate tasks.md.
openspec-reviewer
Internal clean-context Phase 1 verification reviewer. Judges implementation completeness, correctness, coherence, and cleanliness by reading files from changeName, changeDir, and projectRoot. Never accesses conversation history.
openspec-propose
Propose a new change with all artifacts generated in one step. Use when the user wants to quickly describe what they want to build and get a complete proposal with design, specs, and tasks ready for implementation.
openspec-optimizer
Internal clean-context Phase 2 optimization proposer. Analyzes implementation files and outputs behavior-preserving Search/Replace blocks. Never modifies files directly. Reads failedDirections to avoid repeating broken strategies.
openspec-impact-sweeper
Generate a lightweight OPSX-grounded JSON impact report for one project concept. Use from explore before scope or proposal readiness claims.
openspec-explore
Enter explore mode - a thinking partner for exploring ideas, investigating problems, and clarifying requirements. Use when the user wants to think through something before or during a change.