AGENT SKILL

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

  1. 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
  2. Execute the current phase

    Get phase-specific instructions:

    openspec bootstrap instructions [phase] --json
    

    Phase: init

    openspec bootstrap init --mode full
    

    Creates workspace at openspec/bootstrap/ with scope configuration. Supported upgrade paths:

    • specs-based -> full
    • raw -> full
    • raw -> opsx-first
    • formal-opsx -> refresh Use opsx-first only for raw repositories when you want the formal OPSX bundle plus a README-only specs starter now, and full behavior specs later. Use refresh only 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 --restart only when a completed retained workspace already exists and you want a fresh run; it snapshots the old openspec/bootstrap/ into openspec/bootstrap-history/ first.

    Phase: scan

    • Read package.json, README, OpenSpec config, openspec/specs/
    • Scan source code for structural boundaries
    • Write openspec/bootstrap/evidence.yaml with 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 status to track per-domain progress
    • Run openspec bootstrap validate after all domains mapped

    Phase: review

    • Validate regenerates review.md and candidate OPSX files from current evidence.yaml and domain-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 -y
    

    Re-validates all upstream gates before writing.

    • opsx-first: writes the formal OPSX three-file bundle plus only openspec/specs/README.md
    • full on raw: writes the formal OPSX bundle plus one validated spec per mapped capability
    • full on specs-based: preserves existing specs, adds only missing capability specs, and fails fast on target-path conflicts
    • refresh on formal-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 --json
    

    For 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 into openspec/bootstrap-history/.

  3. After each phase action

    • Run openspec bootstrap validate to verify gate conditions
    • Run openspec bootstrap status to confirm phase advancement
    • Continue to next phase

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