openspec-stack-init 1.0.0

package/README.md

@@ -0,0 +1,104 @@
+# openspec-stack-init
+
+> Initialize OpenSpec + Beads + claude-mem + skills in any project — one command.
+
+## Usage
+
+```bash
+# Current directory
+npx openspec-stack-init
+
+# Specific project path
+npx openspec-stack-init ./my-project
+npx openspec-stack-init /absolute/path/to/project
+
+# Preview without making changes
+npx openspec-stack-init --dry-run
+npx openspec-stack-init ./my-project --dry-run
+```
+
+## What it installs
+
+| Tool | What it does | Non-interactive flag used |
+|---|---|---|
+| **OpenSpec** | Spec-driven development | `openspec init --tools claude --profile expanded --force` |
+| **Beads** | Git-backed issue tracker / agent memory | `bd init --quiet` + `bd setup claude` |
+| **claude-mem** | Automatic session memory via hooks | `claude plugin marketplace add` + `claude plugin install` |
+| **openspec-to-beads** | Syncs OpenSpec tasks.md → Beads issues | `npx @smithery/cli skill add` |
+| **/migrate-to-openspec** | Brownfield migration skill | Copied to `.claude/skills/migrate-to-openspec/` |
+
+## Prerequisites
+
+> ⚠️ **This package does NOT install the tools below for you.**
+> It only wires them together in your project.
+> Make sure all of the following are installed before running `npx openspec-stack-init`.
+
+| Tool | Install instructions |
+|---|---|
+| **OpenSpec** | [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) |
+| **Beads** | [INSTALLING.md](https://github.com/steveyegge/beads/blob/main/docs/INSTALLING.md) |
+| **claude-mem** | [github.com/thedotmack/claude-mem](https://github.com/thedotmack/claude-mem) |
+| **Claude Code** | `npm install -g @anthropic-ai/claude-code` |
+| **Node.js** | [nodejs.org](https://nodejs.org) (v18+) |
+
+Each tool has multiple installation options — pick whichever works best for your environment.
+
+## Platform support
+
+Works on **macOS**, **Windows**, and **Linux** — it's a Node.js script, no bash required.
+
+Requires Node.js 18+.
+
+## After running
+
+### Step 1 — Initialize Claude Code in your project
+
+Open Claude Code in the project directory and run:
+
+```
+/init
+```
+
+This creates `CLAUDE.md` — Claude Code's project-level memory file. It also
+ensures the `.claude/` folder is fully recognized by Claude Code. Run this
+**before** using any skills or slash commands.
+
+> **Note:** `openspec-stack-init` already creates `.claude/skills/` so the
+> installed skills will be found automatically. But without `CLAUDE.md`
+> (generated by `/init`), Claude Code has no project context to work with.
+
+### Step 2 — Brownfield project
+
+Run inside Claude Code:
+
+```
+/migrate-to-openspec
+```
+
+This scans the codebase using 4 parallel scout agents and auto-generates all
+OpenSpec files: `config.yaml`, architecture specs, feature specs, and active
+changes from TODOs/FIXMEs. See `openspec/MIGRATION_REPORT.md` for a summary
+of what was created and what needs human review.
+
+### Step 2 — Greenfield project
+
+Skip `/migrate-to-openspec`. Instead:
+
+1. Edit `openspec/config.yaml` — describe your planned stack and conventions
+2. Run `/opsx:propose <feature>` to start your first spec
+
+## Local development / run without publishing
+
+```bash
+git clone <this-repo>
+cd openspec-stack-init
+npm install
+node src/index.js ./target-project
+```
+
+## Publish to npm (optional)
+
+```bash
+npm publish --access public
+# Then anyone can run: npx openspec-stack-init
+```

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "openspec-stack-init",
+  "version": "1.0.0",
+  "description": "Initialize OpenSpec + Beads + claude-mem + skills in any project",
+  "author": {
+    "name": "VirtualMaestro",
+    "email": "virtualmaestro@gmail.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/VirtualMaestro/openspec-stack-init.git"
+  },
+  "homepage": "https://github.com/VirtualMaestro/openspec-stack-init#readme",
+  "bugs": {
+    "url": "https://github.com/VirtualMaestro/openspec-stack-init/issues"
+  },
+  "bin": {
+    "openspec-stack-init": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "execa": "^8.0.1",
+    "ora": "^8.0.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": ["openspec", "beads", "claude-mem", "claude-code", "ai-stack"],
+  "license": "MIT"
+}

package/skills/migrate-to-openspec/SKILL.md

@@ -0,0 +1,560 @@
+---
+name: migrate-to-openspec
+description: >
+  Brownfield migration skill. Scans an existing project and automatically
+  generates a complete OpenSpec baseline: config.yaml, architecture specs,
+  feature specs, and active changes from TODOs. Also optimizes CLAUDE.md by
+  removing references to docs now absorbed into OpenSpec. Invoke manually for
+  brownfield projects only. NOT for greenfield.
+disable-model-invocation: true
+allowed-tools: Bash, Glob, Grep, Read, Write, Task
+---
+
+# /migrate-to-openspec — Brownfield Migration to OpenSpec
+
+You are performing a **one-time brownfield migration** of an existing project into
+OpenSpec format. Your job is to scan the codebase automatically and generate all
+OpenSpec files from scratch. The user will review and adjust the results afterward.
+
+## Pre-flight checks
+
+Before doing anything else, verify the environment:
+
+```bash
+# 1. OpenSpec must be initialized
+openspec status --json 2>&1 || echo "NOT_INITIALIZED"
+
+# 2. Check what already exists
+ls openspec/specs/ 2>/dev/null | wc -l
+ls openspec/changes/ 2>/dev/null | wc -l
+```
+
+If OpenSpec is not initialized, stop and tell the user:
+> OpenSpec is not initialized. Run `openspec init --tools claude --profile expanded --force` first, then run `/migrate-to-openspec` again.
+
+If `openspec/specs/` already contains files, warn the user:
+> ⚠️  OpenSpec specs already exist. This migration will ADD to existing specs, not overwrite them. Proceed? (y/N)
+
+Wait for confirmation before continuing.
+
+---
+
+## Migration Strategy: Multi-Agent Phases
+
+This migration uses **4 parallel scout agents** (via Task tool) to scan the
+codebase simultaneously, then a synthesis phase to write all OpenSpec files.
+
+**Do not start synthesis until all 4 scout agents have returned results.**
+
+Announce to the user:
+> Starting brownfield migration. Spawning 4 scout agents to analyze the project in parallel. This may take a few minutes...
+
+---
+
+## Phase 1: Spawn Scout Agents (parallel, via Task tool)
+
+Spawn all 4 agents simultaneously using the Task tool:
+
+### Scout Agent 1 — Project Structure & Tech Stack
+
+Task prompt:
+```
+You are a read-only scout agent. Scan this project and return a structured report.
+Do NOT modify any files.
+
+Collect ALL of the following:
+
+1. PROJECT OVERVIEW
+   - Primary language(s) and versions (check *.csproj, package.json, go.mod, Cargo.toml, etc.)
+   - Framework/engine (Unity, React, Django, etc.) and version
+   - Project type (game, web app, library, CLI, etc.)
+   - Top-level folder structure (2 levels deep)
+   - Entry points (main files, startup scenes, index files)
+   - Build system (Makefile, cmake, gradle, Unity build settings, etc.)
+
+2. ARCHITECTURE PATTERNS
+   - Identify dominant patterns: MVC, MVVM, HMVC, ECS, layered, microservices, etc.
+   - Key abstractions: what are the main classes/modules/systems?
+   - Dependency direction: what depends on what?
+   - Data flow: how does data move through the system?
+   - Read up to 20 key source files to understand the architecture.
+     Focus on: base classes, interfaces, managers, controllers, core systems.
+
+3. EXTERNAL DEPENDENCIES
+   - Third-party libraries/packages (from lock files and manifests)
+   - External APIs or services used
+   - Database or persistence layer
+
+4. TEST COVERAGE
+   - Does a test folder exist? What framework?
+   - Rough estimate: are there many, some, or no tests?
+
+5. BUILD & CI
+   - CI config files (.github/workflows, .gitlab-ci.yml, etc.)
+   - Scripts in package.json or Makefile
+
+Return your findings as a structured markdown report under these exact headings:
+## TECH_STACK
+## ARCHITECTURE
+## DEPENDENCIES
+## TESTING
+## BUILD_CI
+```
+
+### Scout Agent 2 — Existing Documentation & CLAUDE.md Audit
+
+Task prompt:
+```
+You are a read-only scout agent. Find and extract ALL existing documentation,
+and perform a full audit of CLAUDE.md. Do NOT modify any files.
+
+PART A — DOCUMENTATION HARVEST
+
+Search for and read:
+1. README.md, README.*, CONTRIBUTING.md, ARCHITECTURE.md, DESIGN.md
+2. Any /docs, /documentation, /wiki, /specs, /.notes folder
+3. Any existing proposals, design docs, ADRs (Architecture Decision Records)
+4. CHANGELOG.md or HISTORY.md
+5. Any .md files in root or subdirectories (sample up to 30 files)
+6. Comments at the top of key source files that describe the module purpose
+7. Any openspec/ folder content that already exists
+
+For each document found, extract:
+- Its PURPOSE (what does it describe?)
+- Key REQUIREMENTS or CONSTRAINTS mentioned
+- DECISIONS already made
+- FUTURE PLANS mentioned
+
+PART B — CLAUDE.md AUDIT
+
+Read CLAUDE.md carefully (if it exists). For every file reference, link, or
+"read this document" instruction found inside CLAUDE.md:
+
+1. Note the referenced file path
+2. Check if that file actually exists on disk
+3. Estimate the token cost: is it a large doc (>200 lines) or small?
+4. Classify the reference as one of:
+   - ESSENTIAL: Claude genuinely needs this every session (e.g. project conventions,
+     critical architecture rules, active task lists)
+   - REDUNDANT_AFTER_MIGRATION: this doc's knowledge will be fully covered by
+     OpenSpec specs and config.yaml after migration
+   - STALE: file does not exist on disk or is clearly outdated
+   - UNCLEAR: cannot determine without more context
+
+Return your findings as a structured markdown report under these exact headings:
+## EXISTING_DOCS (list of files found with one-line summary each)
+## EXTRACTED_REQUIREMENTS (bulleted list of concrete requirements found)
+## ARCHITECTURAL_DECISIONS (decisions already made, from ADRs or docs)
+## FUTURE_PLANS (things mentioned as planned/upcoming/TODO in documentation)
+## RAW_EXCERPTS (paste the most important 3-5 paragraphs from docs verbatim)
+## CLAUDE_MD_AUDIT
+### Current references in CLAUDE.md:
+- <file path> | <classification> | <token cost estimate> | <reason>
+### Estimated token waste per session (sum of REDUNDANT + STALE docs):
+<N> lines / approx <N> tokens loaded unnecessarily every session
+```
+
+### Scout Agent 3 — Technical Debt & Active Work
+
+Task prompt:
+```
+You are a read-only scout agent. Find ALL signals of active work and technical debt.
+Do NOT modify any files.
+
+1. SEARCH FOR DEBT MARKERS
+   Run these searches across all source files:
+   - grep -rn "TODO" --include="*.cs" --include="*.ts" --include="*.js" --include="*.py" --include="*.dart" --include="*.go" --include="*.rs" --include="*.lua" . | head -200
+   - grep -rn "FIXME\|HACK\|BUG\|BROKEN\|WORKAROUND\|TEMPORARY\|TEMP\b" --include="*.cs" --include="*.ts" --include="*.js" --include="*.py" --include="*.dart" --include="*.go" --include="*.rs" --include="*.lua" . | head -200
+   - grep -rn "DEPRECATED\|OBSOLETE\|REMOVE\|DELETE ME\|REFACTOR" --include="*.cs" --include="*.ts" --include="*.js" --include="*.py" --include="*.dart" --include="*.go" --include="*.rs" --include="*.lua" . | head -100
+   - Adapt file extensions to the actual tech stack of this project.
+
+2. CLASSIFY EACH ITEM into one of:
+   - FEATURE: something new to build
+   - BUG: known bug
+   - DEBT: refactoring needed
+   - QUESTION: unresolved design question
+   - PERF: performance issue
+   - DEPRECATION: legacy code to remove
+
+3. FIND GIT SIGNALS
+   - git log --oneline -50 (recent commits to understand current focus)
+   - git diff --name-only HEAD~10 (recently changed files)
+   - git stash list (any stashed work?)
+
+4. FIND INCOMPLETE WORK
+   - Partially implemented features (stub files, empty methods, "not implemented" exceptions)
+   - Files with many commented-out blocks
+
+Return your findings as a structured markdown report under these headings:
+## DEBT_SUMMARY (count by category: X features, Y bugs, Z debt items, etc.)
+## FEATURES (list: "filename:line - description")
+## BUGS (list: "filename:line - description")
+## DEBT (list: "filename:line - description")
+## QUESTIONS (list: "filename:line - description")
+## PERF (list: "filename:line - description")
+## DEPRECATIONS (list: "filename:line - description")
+## GIT_SIGNALS (what recent commits reveal about current priorities)
+```
+
+### Scout Agent 4 — Module Boundaries & Feature Map
+
+Task prompt:
+```
+You are a read-only scout agent. Map the features and modules of this project.
+Do NOT modify any files.
+
+1. IDENTIFY ALL FEATURES/SYSTEMS
+   Walk through the entire source code and identify discrete features, systems,
+   or capabilities. A "feature" is something a user or another system can do.
+   Examples for a game: "card combat", "deck building", "matchmaking", "save system"
+   Examples for a web app: "user auth", "payment processing", "notifications"
+
+   Read enough files in each module to understand what it does.
+
+2. FOR EACH FEATURE/SYSTEM, document:
+   - Name (short, kebab-case)
+   - Purpose (1 sentence)
+   - Key files (list main files)
+   - Status: COMPLETE | IN_PROGRESS | BROKEN | PARTIAL | PLANNED
+   - Stability: STABLE | UNSTABLE | LEGACY | EXPERIMENTAL
+   - Dependencies on other features
+
+3. IDENTIFY CROSS-CUTTING CONCERNS
+   - Logging, error handling, configuration, authentication patterns
+   - Any shared utilities or base classes used everywhere
+
+Return your findings as a structured markdown report under these headings:
+## FEATURE_MAP (one entry per feature in format below)
+### Feature: <n>
+- Purpose: ...
+- Files: ...
+- Status: ...
+- Stability: ...
+- Depends on: ...
+
+## CROSS_CUTTING_CONCERNS
+## SUGGESTED_SPEC_GROUPS (how to group features into spec files)
+```
+
+---
+
+## Phase 2: Synthesize Results
+
+After all 4 agents return, you now have complete information about the project.
+Proceed to write all OpenSpec files. **Do not ask the user for input during this phase.**
+Write everything based on what the agents discovered.
+
+---
+
+## Phase 3: Write `openspec/config.yaml`
+
+Generate `openspec/config.yaml` from the combined scout reports.
+
+Use this structure (fill in all fields from discovered data — do NOT leave placeholders):
+
+```yaml
+# OpenSpec Project Config — auto-generated by /migrate-to-openspec
+# Review and adjust as needed.
+
+schema: spec-driven
+
+context: |
+  Project: <name from structure scan>
+  Type: <game / web app / library / etc.>
+
+  Tech stack:
+  <list discovered languages, frameworks, versions>
+
+  Architecture: <describe the pattern found, e.g. "HMVC with ECS for combat systems">
+
+  Key systems:
+  <bullet list of major features/systems found>
+
+  External dependencies:
+  <key libraries/services found>
+
+  Testing: <what was found — none / unit tests / integration tests / etc.>
+
+  Conventions discovered:
+  <naming patterns, folder conventions, coding style observed in codebase>
+
+  Known constraints:
+  <things the agents discovered that constrain development>
+
+rules:
+  proposal:
+    - Always describe impact on existing systems
+    - Reference the spec file(s) being modified
+  specs:
+    - Use Given/When/Then format for all scenarios
+    - Each Requirement must have at least one Scenario
+  design:
+    - Must reference at least one existing file by path
+    - Must describe impact on other systems
+  tasks:
+    - Keep each task scoped to 1-3 files maximum
+    - Order tasks so earlier ones never depend on later ones
+```
+
+Write to `openspec/config.yaml`.
+
+---
+
+## Phase 4: Write Architecture Spec
+
+Based on Scout Agent 1 and 4 findings, write `openspec/specs/architecture/spec.md`.
+
+Use the template from `templates/architecture-spec.md` (in this skill's folder).
+Adapt it fully — use real names, real file paths, real patterns found by the agents.
+
+---
+
+## Phase 5: Write Feature Specs
+
+For each feature/system identified by Scout Agent 4 with status COMPLETE or STABLE,
+write a spec file at `openspec/specs/<feature-name>/spec.md`.
+
+Use the template from `templates/feature-spec.md` (in this skill's folder).
+
+**Priority order for writing specs:**
+1. Core/foundational systems first (things many other features depend on)
+2. User-facing features second
+3. Infrastructure/tooling last
+
+Limit to the **10 most important** features on first pass.
+Note at the top of each spec file: `# Auto-generated — review for accuracy`
+
+---
+
+## Phase 6: Create OpenSpec Changes for Active Work
+
+For each item in Scout Agent 3's FEATURES and BUGS lists that represents
+**unfinished or planned work**, create an OpenSpec change.
+
+For each such item:
+
+1. Create `openspec/changes/<kebab-name>/`
+2. Write `proposal.md`:
+
+```markdown
+# Proposal: <title>
+# Auto-generated from: <filename>:<line> — review and refine as needed.
+
+## Why
+<Describe what the TODO/FIXME says needs to be done>
+
+Discovered in: `<file path>:<line number>`
+Original comment: `<exact text of the TODO/FIXME>`
+
+## What Changes
+<List the files or systems likely affected>
+
+## Impact
+<What breaks or changes if this isn't done vs. if it is done>
+
+## Rollback
+<How to undo this change if it goes wrong>
+```
+
+3. Write `tasks.md` with a single starter task:
+
+```markdown
+# Tasks
+
+## 1. Implementation
+- [ ] 1.1 Implement: <short description>
+  - Files: `<filename>`
+  - Details: <from the TODO comment>
+```
+
+**Limit**: Create at most **20 changes** on first pass. If there are more,
+create a summary file at `openspec/changes/_backlog.md` listing all remaining items.
+
+> **Note on Beads sync:** Do NOT create Beads issues manually here.
+> After migration is complete, use the `/openspec-to-beads` skill to sync
+> all OpenSpec changes to Beads in one step. It was installed by
+> `openspec-stack-init` and handles this automatically.
+
+---
+
+## Phase 7: Optimize CLAUDE.md
+
+This phase eliminates token waste in future sessions. Every doc reference in
+CLAUDE.md that is now covered by OpenSpec gets loaded into context on every
+single session start — even though the knowledge already lives in openspec/specs/
+and openspec/config.yaml. This phase removes that redundancy.
+
+### Step 1 — Read CLAUDE.md
+
+```bash
+cat CLAUDE.md 2>/dev/null || echo "NO_CLAUDE_MD"
+```
+
+If CLAUDE.md does not exist, skip this phase and note it in the report.
+
+### Step 2 — Determine what to remove
+
+Using the `## CLAUDE_MD_AUDIT` from Scout Agent 2, build two lists:
+
+**REMOVE** (references that are now redundant):
+- All references classified as **REDUNDANT_AFTER_MIGRATION**
+  — their knowledge is now in `openspec/specs/` and `openspec/config.yaml`
+- All references classified as **STALE**
+  — files that do not exist on disk
+
+**KEEP** (do not touch):
+- All references classified as **ESSENTIAL**
+- All references classified as **UNCLEAR** (when in doubt, keep)
+- Any content that is NOT a doc reference (inline conventions, tool config, etc.)
+- Any blocks marked with OpenSpec's own managed markers
+
+### Step 3 — Back up and rewrite
+
+```bash
+cp CLAUDE.md CLAUDE.md.pre-migration
+```
+
+Rewrite CLAUDE.md: keep all ESSENTIAL content intact, remove REDUNDANT and STALE
+doc references, and add this single replacement block where the removed references
+were:
+
+```markdown
+## Project Knowledge Base
+
+Architecture, requirements, and active work are maintained in OpenSpec.
+See: openspec/specs/ (source of truth) and openspec/changes/ (active work).
+Project context is injected automatically via openspec/config.yaml.
+```
+
+### Step 4 — Safety rules
+
+- Do NOT delete CLAUDE.md — only edit it
+- Do NOT remove OpenSpec managed blocks (marked with OpenSpec markers)
+- Do NOT remove git hooks, tool configurations, or coding conventions
+- If uncertain about any reference — keep it
+
+---
+
+## Phase 8: Write Migration Report
+
+Write `openspec/MIGRATION_REPORT.md`:
+
+```markdown
+# OpenSpec Migration Report
+Generated: <date>
+By: /migrate-to-openspec skill
+
+## What Was Created
+
+### config.yaml
+<one-line summary of what was put in context>
+
+### Specs Created (<N> total)
+<list of specs/*/spec.md with one-line description each>
+
+### Changes Created (<N> total)
+<list of changes/*/proposal.md with source location each>
+
+### Backlog
+<N remaining items in changes/_backlog.md — review manually>
+
+---
+
+## CLAUDE.md Optimization
+
+### Token savings
+Before: ~<N> tokens loaded per session (all referenced docs)
+After:  ~<N> tokens loaded per session (essential only)
+Saved:  ~<N> tokens per session
+
+### References removed (<N> total)
+| File | Classification | Reason |
+|---|---|---|
+| <path> | REDUNDANT_AFTER_MIGRATION | Covered by openspec/specs/<n>/spec.md |
+| <path> | STALE | File does not exist on disk |
+
+### Docs now covered by OpenSpec (safe to archive)
+These files were removed from CLAUDE.md because their knowledge is now in OpenSpec.
+The files themselves have NOT been deleted. You may archive or delete them at
+your discretion once you have verified the corresponding specs are accurate.
+
+| File | Was used for | Now covered by |
+|---|---|---|
+| <path> | <original purpose> | openspec/specs/<n>/spec.md |
+
+Original CLAUDE.md backed up to: `CLAUDE.md.pre-migration`
+
+---
+
+## What Needs Human Review
+
+1. **config.yaml** — Verify the `context:` block is accurate.
+   Check: architecture description, tech stack versions, key constraints.
+
+2. **Architecture spec** — Verify patterns match your intent, not just current code.
+
+3. **Feature specs** — Describe current behavior. Use OpenSpec changes for
+   anything that should change in the future.
+
+4. **Changes from TODOs** — Some may be outdated or already fixed.
+   Review openspec/changes/ and delete irrelevant ones.
+
+5. **CLAUDE.md** — Review the optimized version. Restore from
+   `CLAUDE.md.pre-migration` if anything essential was removed by mistake.
+
+---
+
+## Items NOT Migrated (require manual work)
+
+<list anything the agents found but could not classify automatically>
+
+---
+
+## Suggested Next Steps
+
+1. Review this report carefully, especially the CLAUDE.md optimization section
+2. Run `/openspec-to-beads` — sync all OpenSpec changes to Beads issues
+3. Run `/opsx:explore` — let Claude validate the migration made sense
+4. Pick one change from openspec/changes/ and run `/opsx:apply <n>`
+```
+
+---
+
+## Final Announcement
+
+Tell the user:
+
+> ✅ Migration complete! Here's what was done:
+>
+> - `openspec/config.yaml` — project context injected into every future spec
+> - `openspec/specs/` — <N> architecture and feature specs
+> - `openspec/changes/` — <N> active changes from TODOs/FIXMEs
+> - `CLAUDE.md` — optimized: <N> redundant doc references removed (~<N> tokens saved per session)
+> - `CLAUDE.md.pre-migration` — backup of original
+> - `openspec/MIGRATION_REPORT.md` — full summary, token savings, docs to archive
+>
+> **Recommended next steps:**
+> 1. Read `openspec/MIGRATION_REPORT.md`
+> 2. Run `/openspec-to-beads` to sync changes → Beads issues
+> 3. Run `/opsx:explore` to validate the baseline
+
+---
+
+## Error Handling
+
+If any phase fails, do NOT stop the migration. Log the error to
+`openspec/MIGRATION_REPORT.md` under a `## Errors` section and continue
+with remaining phases. Partial output is better than no output.
+
+If a scout agent returns empty or incomplete results, proceed with
+whatever data is available and note the gap in the report.
+
+**Phase 7 (CLAUDE.md) is the most sensitive phase** — it modifies a file
+that affects every future Claude Code session. If anything goes wrong:
+
+```bash
+cp CLAUDE.md.pre-migration CLAUDE.md
+```
+
+Note the failure in the report and ask the user to optimize CLAUDE.md manually
+using the `## CLAUDE_MD_AUDIT` section as a guide.

package/skills/migrate-to-openspec/templates/architecture-spec.md

@@ -0,0 +1,38 @@
+# Architecture Specification
+# Auto-generated by /migrate-to-openspec — review for accuracy.
+
+## Requirement: Folder Structure
+The system SHALL maintain the established folder conventions.
+
+### Scenario: New source file added
+- GIVEN a developer adds a new source file
+- WHEN placing it in the project
+- THEN it SHALL be placed in the appropriate module folder
+- AND it SHALL follow the naming convention established in existing files
+
+## Requirement: Dependency Direction
+The system SHALL enforce unidirectional dependencies between layers.
+
+### Scenario: Cross-layer dependency
+- GIVEN module A depends on module B
+- WHEN B is in a lower layer than A
+- THEN this dependency is valid
+- AND the reverse dependency SHALL NOT exist
+
+## Requirement: Tech Stack Stability
+The system SHALL not introduce new languages, runtimes, or major frameworks
+without an explicit architectural decision.
+
+### Scenario: Adding a new tool
+- GIVEN a new tool is proposed
+- WHEN evaluating it
+- THEN a proposal MUST be created in openspec/changes/
+- AND alternatives MUST be documented
+
+## Requirement: Naming Conventions
+The system SHALL follow established naming patterns throughout the codebase.
+
+### Scenario: Naming a new type
+- GIVEN a developer creates a new class, file, or component
+- WHEN choosing its name
+- THEN it SHALL follow the convention established in similar existing types

package/skills/migrate-to-openspec/templates/feature-spec.md

@@ -0,0 +1,40 @@
+# Feature Spec: <Feature Name>
+# Auto-generated by /migrate-to-openspec — review for accuracy.
+#
+# Status at time of migration: <COMPLETE | IN_PROGRESS | PARTIAL>
+# Key files: <list main files for this feature>
+
+## Requirement: Core Behavior
+The system SHALL <describe what this feature does at a high level>.
+
+### Scenario: Happy path
+- GIVEN <initial state>
+- WHEN <trigger>
+- THEN <expected outcome>
+- AND <additional outcome>
+
+### Scenario: Error case
+- GIVEN <state where error can occur>
+- WHEN <trigger>
+- THEN <error is handled gracefully>
+- AND <system returns to stable state>
+
+## Requirement: <Second Requirement>
+The system SHALL <describe second requirement>.
+
+### Scenario: <Name>
+- GIVEN ...
+- WHEN ...
+- THEN ...
+
+## Requirement: Performance
+The system SHALL complete <operation> within <N>ms under normal load.
+
+### Scenario: Acceptable load
+- GIVEN <N> concurrent <operations>
+- WHEN <trigger>
+- THEN response time SHALL be under <N>ms
+
+## Notes
+- <Any caveats, known limitations, or implementation notes discovered during migration>
+- <References to related specs>

package/src/index.js

@@ -0,0 +1,352 @@
+#!/usr/bin/env node
+
+// openspec-stack-init — cross-platform initializer for:
+// OpenSpec + Beads + claude-mem + openspec-to-beads skill + brownfield-baseline skill
+//
+// Usage:
+//   npx openspec-stack-init                  — current directory
+//   npx openspec-stack-init ./my-project     — specific path
+//   npx openspec-stack-init --dry-run        — preview without executing
+
+import { execSync, spawnSync } from "child_process";
+import { existsSync, mkdirSync, writeFileSync, appendFileSync, readFileSync } from "fs";
+import { resolve, basename, join } from "path";
+import { platform } from "os";
+import process from "process";
+
+// ─── Minimal inline styling (avoids requiring chalk to be pre-installed) ─────
+const c = {
+  reset:   "\x1b[0m",
+  bold:    "\x1b[1m",
+  red:     "\x1b[31m",
+  green:   "\x1b[32m",
+  yellow:  "\x1b[33m",
+  blue:    "\x1b[34m",
+  cyan:    "\x1b[36m",
+};
+
+const log = {
+  info:    (msg) => console.log(`${c.blue}[INFO]${c.reset} ${msg}`),
+  ok:      (msg) => console.log(`${c.green}[ OK ]${c.reset} ${msg}`),
+  warn:    (msg) => console.log(`${c.yellow}[WARN]${c.reset} ${msg}`),
+  skip:    (msg) => console.log(`${c.yellow}[SKIP]${c.reset} ${msg}`),
+  error:   (msg) => console.error(`${c.red}[ERR ]${c.reset} ${msg}`),
+  step:    (msg) => console.log(`\n${c.bold}${c.cyan}══> ${msg}${c.reset}`),
+  section: (msg) => console.log(`${c.bold}${msg}${c.reset}`),
+};
+
+// ─── Args ────────────────────────────────────────────────────────────────────
+const args = process.argv.slice(2);
+const DRY_RUN = args.includes("--dry-run") || args.includes("-n");
+const targetArg = args.find((a) => !a.startsWith("--") && !a.startsWith("-"));
+const TARGET_DIR = resolve(targetArg || process.cwd());
+const PROJECT_NAME = basename(TARGET_DIR);
+const IS_WINDOWS = platform() === "win32";
+
+// ─── Utilities ───────────────────────────────────────────────────────────────
+
+/** Run a shell command, return true on success */
+function run(cmd, opts = {}) {
+  if (DRY_RUN) {
+    log.info(`[DRY RUN] ${cmd}`);
+    return true;
+  }
+  try {
+    execSync(cmd, {
+      cwd: TARGET_DIR,
+      stdio: opts.silent ? "pipe" : "inherit",
+      shell: true,
+      ...opts,
+    });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+/** Check if a CLI tool is available in PATH */
+function hasCmd(cmd) {
+  const check = IS_WINDOWS ? `where ${cmd}` : `command -v ${cmd}`;
+  try {
+    execSync(check, { stdio: "pipe", shell: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Write file only if it doesn't exist (or DRY_RUN) */
+function writeIfMissing(filePath, content, description) {
+  const full = join(TARGET_DIR, filePath);
+  if (existsSync(full)) {
+    log.skip(`${filePath} already exists`);
+    return;
+  }
+  if (DRY_RUN) {
+    log.info(`[DRY RUN] Would create: ${filePath}`);
+    return;
+  }
+  mkdirSync(join(TARGET_DIR, filePath.split("/").slice(0, -1).join("/")), { recursive: true });
+  writeFileSync(full, content, "utf8");
+  log.ok(`Created ${filePath}${description ? ` — ${description}` : ""}`);
+}
+
+/** Append to .gitignore if entry is missing */
+function gitignoreAdd(entry, comment) {
+  const gitignorePath = join(TARGET_DIR, ".gitignore");
+  if (!existsSync(gitignorePath)) {
+    if (!DRY_RUN) writeFileSync(gitignorePath, "", "utf8");
+  }
+  const content = existsSync(gitignorePath) ? readFileSync(gitignorePath, "utf8") : "";
+  if (content.includes(entry)) return;
+  if (DRY_RUN) {
+    log.info(`[DRY RUN] Would add to .gitignore: ${entry}`);
+    return;
+  }
+  appendFileSync(gitignorePath, `\n# ${comment}\n${entry}\n`, "utf8");
+  log.info(`  .gitignore ← ${entry}`);
+}
+
+// ─── Banner ───────────────────────────────────────────────────────────────────
+console.log(`
+${c.bold}╔══════════════════════════════════════════╗
+║         AI Stack Init  v1.0              ║
+║  OpenSpec + Beads + claude-mem + skills  ║
+╚══════════════════════════════════════════╝${c.reset}
+  Project : ${c.cyan}${PROJECT_NAME}${c.reset}
+  Path    : ${c.cyan}${TARGET_DIR}${c.reset}
+  Mode    : ${DRY_RUN ? c.yellow + "DRY RUN (no changes)" + c.reset : c.green + "LIVE" + c.reset}
+`);
+
+if (!existsSync(TARGET_DIR)) {
+  log.error(`Directory not found: ${TARGET_DIR}`);
+  process.exit(1);
+}
+
+// ─── 1. Dependency check ──────────────────────────────────────────────────────
+log.step("Checking required tools");
+
+const deps = [
+  { cmd: "openspec", install: "npm install -g @fission-ai/openspec@latest" },
+  { cmd: "bd",       install: "brew install beads  OR  go install github.com/steveyegge/beads/cmd/bd@latest" },
+  { cmd: "claude",   install: "npm install -g @anthropic-ai/claude-code" },
+  { cmd: "npx",      install: "Node.js  (https://nodejs.org)" },
+];
+
+let missing = false;
+for (const { cmd, install } of deps) {
+  if (hasCmd(cmd)) {
+    log.ok(cmd);
+  } else {
+    log.warn(`${cmd} not found — install: ${install}`);
+    missing = true;
+  }
+}
+
+if (missing && !DRY_RUN) {
+  console.log();
+  log.warn("Some tools are missing. Continuing anyway — affected steps will be skipped.");
+}
+
+// ─── 2. OpenSpec init ─────────────────────────────────────────────────────────
+log.step("OpenSpec — init");
+
+if (existsSync(join(TARGET_DIR, "openspec"))) {
+  log.skip("openspec/ already exists");
+} else if (hasCmd("openspec")) {
+  // --tools claude   : select Claude Code without interactive prompt
+  // --profile expanded: enable all workflow commands (new, ff, verify, sync, etc.)
+  // --force          : skip all remaining prompts, auto-cleanup legacy files
+  const ok = run("openspec init --tools claude --profile expanded --force");
+  if (ok) {
+    log.ok("OpenSpec initialized (expanded profile, Claude tools)");
+  } else {
+    // Fallback: openspec init may not support --force on older versions
+    log.warn("Non-interactive init failed — trying interactive...");
+    log.warn("Run manually: openspec init --tools claude --profile expanded");
+  }
+} else {
+  log.warn("openspec not found — skipping");
+}
+
+// ─── 3. OpenSpec config.yaml ──────────────────────────────────────────────────
+log.step("OpenSpec — config.yaml");
+
+writeIfMissing(
+  "openspec/config.yaml",
+  `# OpenSpec Project Config — ${PROJECT_NAME}
+# This context is injected into every artifact (proposal, specs, design, tasks)
+
+schema: spec-driven
+
+context: |
+  Project: ${PROJECT_NAME}
+
+  # TODO: fill in your actual stack and conventions
+  # Tech stack: Unity 2022, C#, Flutter backend
+  # Architecture: HMVC
+  # Testing: NUnit
+  # Key constraints: legacy codebase, brownfield migration
+
+rules:
+  proposal:
+    - Always include a rollback plan for legacy code changes
+    - List all affected modules
+  specs:
+    - Use Given/When/Then format for scenarios
+  design:
+    - Respect existing legacy constraints
+  tasks:
+    - Keep tasks atomic (max 2-3 files per task)
+    - After all tasks complete, run /opsx:verify
+`,
+  "fill in 'context' with your project details"
+);
+
+// ─── 4. Beads init ────────────────────────────────────────────────────────────
+log.step("Beads — init");
+
+const beadsInitialized =
+  existsSync(join(TARGET_DIR, ".beads")) ||
+  existsSync(join(TARGET_DIR, "beads.jsonl")) ||
+  existsSync(join(TARGET_DIR, "issues.jsonl"));
+
+if (beadsInitialized) {
+  log.skip("Beads already initialized");
+} else if (hasCmd("bd")) {
+  // --quiet: non-interactive, no prompts, no spinner
+  const ok = run("bd init --quiet");
+  if (ok) log.ok("Beads initialized (quiet mode)");
+  else log.warn("bd init failed — run manually: bd init --quiet");
+} else {
+  log.warn("bd not found — skipping Beads init");
+}
+
+// bd setup claude: installs SessionStart + PreCompact hooks for Claude Code
+// This is idempotent — safe to run even if already set up
+log.step("Beads — Claude Code integration");
+
+if (hasCmd("bd")) {
+  const ok = run("bd setup claude");
+  if (ok) log.ok("Beads hooks installed for Claude Code (SessionStart + PreCompact)");
+  else log.warn("bd setup claude failed — run manually: bd setup claude");
+} else {
+  log.warn("bd not found — skipping Claude Code integration");
+}
+
+// ─── 5. claude-mem plugin ─────────────────────────────────────────────────────
+log.step("claude-mem — plugin install");
+
+// claude plugin marketplace add / install are native CLI commands in Claude Code 2.x
+// They work without entering the REPL (confirmed in official docs)
+if (hasCmd("claude")) {
+  log.info("Adding marketplace: thedotmack/claude-mem");
+  // marketplace add is idempotent — if already added, it updates
+  run("claude plugin marketplace add thedotmack/claude-mem", { silent: true });
+
+  log.info("Installing plugin: claude-mem");
+  const ok = run("claude plugin install claude-mem", { silent: true });
+
+  if (ok) {
+    log.ok("claude-mem installed via native claude plugin CLI");
+  } else {
+    log.warn("claude plugin CLI failed. Install manually inside Claude Code:");
+    log.warn("  /plugin marketplace add thedotmack/claude-mem");
+    log.warn("  /plugin install claude-mem");
+  }
+} else {
+  log.warn("claude not found — install claude-mem manually:");
+  log.warn("  /plugin marketplace add thedotmack/claude-mem");
+  log.warn("  /plugin install claude-mem");
+}
+
+// ─── 6. Skill: openspec-to-beads ─────────────────────────────────────────────
+log.step("Skill — openspec-to-beads");
+
+// npx @smithery/cli skill add is non-interactive
+const smitheryOk = run(
+  "npx @smithery/cli@latest skill add lucastamoios/openspec-to-beads --agent claude-code"
+);
+if (smitheryOk) {
+  log.ok("Skill openspec-to-beads installed");
+} else {
+  log.warn("Skill install failed — run manually:");
+  log.warn("  npx @smithery/cli@latest skill add lucastamoios/openspec-to-beads --agent claude-code");
+}
+
+// ─── 7. Skill: migrate-to-openspec ───────────────────────────────────────────
+log.step("Skill — /migrate-to-openspec (brownfield migration)");
+
+// The skill files are bundled alongside this script in ../skills/
+import { fileURLToPath } from "url";
+import { dirname, join as pathJoin } from "path";
+import { cpSync } from "fs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const skillSrc = pathJoin(__dirname, "..", "skills", "migrate-to-openspec");
+const skillDst = join(TARGET_DIR, ".claude", "skills", "migrate-to-openspec");
+
+if (existsSync(skillDst)) {
+  log.skip(".claude/skills/migrate-to-openspec/ already exists");
+} else if (existsSync(skillSrc)) {
+  if (!DRY_RUN) {
+    mkdirSync(join(TARGET_DIR, ".claude", "skills"), { recursive: true });
+    cpSync(skillSrc, skillDst, { recursive: true });
+    log.ok("Skill /migrate-to-openspec installed → .claude/skills/migrate-to-openspec/");
+  } else {
+    log.info("[DRY RUN] Would install: .claude/skills/migrate-to-openspec/");
+  }
+} else {
+  log.warn("Skill source not found — skipping migrate-to-openspec");
+}
+
+log.info("  Usage: run /migrate-to-openspec in Claude Code on a brownfield project");
+log.info("  This skill uses 4 parallel scout agents + writes all OpenSpec files automatically");
+
+// ─── 8. .gitignore ────────────────────────────────────────────────────────────
+log.step("Updating .gitignore");
+
+// NOTE: beads.jsonl and issues.jsonl are intentionally committed to git (that's the feature)
+// Only ignore local SQLite cache and claude-mem local data
+gitignoreAdd(".beads-cache/",  "Beads local SQLite cache (not needed in git)");
+gitignoreAdd(".claude-mem/",   "claude-mem local session data");
+
+log.ok(".gitignore updated");
+
+// ─── 9. Summary ───────────────────────────────────────────────────────────────
+console.log(`
+${c.bold}${c.green}╔══════════════════════════════════════════╗
+║          Setup Complete!                 ║
+╚══════════════════════════════════════════╝${c.reset}
+
+${c.bold}What was done:${c.reset}
+  ${c.green}✓${c.reset} OpenSpec           → openspec/ + expanded profile + Claude tools
+  ${c.green}✓${c.reset} openspec/config.yaml → auto-filled by /migrate-to-openspec
+  ${c.green}✓${c.reset} Beads              → initialized (--quiet) + Claude Code hooks
+  ${c.green}✓${c.reset} claude-mem         → plugin installed via native claude CLI
+  ${c.green}✓${c.reset} openspec-to-beads  → skill installed via Smithery
+  ${c.green}✓${c.reset} /migrate-to-openspec → .claude/skills/migrate-to-openspec/
+
+${c.bold}Next steps — ${c.cyan}BROWNFIELD${c.reset} project:${c.reset}
+  1. Restart Claude Code
+  2. ${c.cyan}/migrate-to-openspec${c.reset} — scans project + fills all OpenSpec files automatically
+  3. Review ${c.cyan}openspec/MIGRATION_REPORT.md${c.reset}
+  4. ${c.cyan}bd ready${c.reset} — see task list in Beads
+
+${c.bold}Next steps — ${c.cyan}GREENFIELD${c.reset} project:${c.reset}
+  1. Edit ${c.cyan}openspec/config.yaml${c.reset} — describe your planned stack
+  2. Restart Claude Code
+  3. ${c.cyan}/opsx:propose <feature>${c.reset} — start first feature
+
+${c.bold}Key commands:${c.reset}
+  ${c.cyan}bd ready${c.reset}              unblocked tasks right now
+  ${c.cyan}bd create "..."${c.reset}       create a Beads issue
+  ${c.cyan}openspec list${c.reset}         active OpenSpec changes
+  ${c.cyan}/opsx:explore${c.reset}         explore codebase
+  ${c.cyan}/opsx:new <name>${c.reset}      new change
+  ${c.cyan}/opsx:ff${c.reset}              generate all artifacts at once
+  ${c.cyan}/opsx:apply${c.reset}           implement tasks
+  ${c.cyan}/opsx:verify${c.reset}          verify implementation vs specs
+  ${c.cyan}/opsx:archive${c.reset}         archive change → specs/
+`);