ai-spector 0.9.18 → 0.9.21

package/scaffold/cursor/skills/ai-spector/references/help.md

@@ -60,6 +60,7 @@ Use `nextStepId` from Step 1. Cross-check Step 2 findings against the symptom ta
 |-------------------------|--------------|-------------|
 | No git remote / clone fails | `git-connected` | Connect Bitbucket repo in Writer → Project Settings → Git |
 | Missing `.docops/docops.config.json` | `docops-init` | Writer Settings → Docops → Initialize, or `npx ai-spector docops init` |
+| `docops init` / `migrate --repair` CLI fails | `docops-init` | Manual gap-fill: `.docops/guide/guides/DOCOPS_MANUAL_FALLBACK.md` (or monorepo bootstrap guide); then `docops status` |
 | Skills not routing / agent ignores ai-spector | `local-adapter-ready` | Enable all `.cursor/skills/ai-spector*` skills; reload MCP servers |
 | Docs in wrong folder / legacy layout | `legacy-aligned` | Layout transform: [runbook.md — Adopt](runbook.md#adopt). Include comments, review, prototype in adopt plan or copy per MIGRATION.md |
 | Custom / non-standard template | `legacy-aligned` | Pause adopt — guide full gated [template-import](../../ai-spector-generate/references/runbook.md#template-import) workflow, then re-run adopt scan |

package/scaffold/cursor/skills/ai-spector/references/runbook.md

@@ -1,6 +1,6 @@
 # Core Operations — Agent Runbook
 
-Consolidated runbook for: setup, upgrade, adopt, check, docops, course, and work sessions.
+Consolidated runbook for: setup, upgrade, check, docops, course, and work sessions.
 
 **Path semantics:** refer to `kari-writer/contracts/CONTRACT.md` — do not load or link to `.docops/guide/`.
 
@@ -61,7 +61,7 @@ Tell the user:
 
 Bump `ai-spector` package, refresh scaffold, backfill config, verify hooks and MCP.
 
-**Related but different:** setup (greenfield init); adopt (migrate misplaced docs).
+**Related but different:** setup (greenfield init); migrate existing project (self-service docops section below).
 
 ### Phase 0 — Preflight
 
@@ -129,83 +129,48 @@ Remind user: Cmd+Shift+P → "Reload MCP Servers" after scaffold sync.
 
 ---
 
-## Adopt
+## Migrate existing project (self-service)
 
-Migrate existing filled-in docs from legacy layouts into canonical paths.
+Bring filled-in docs into the Writer contract **without** automated file moves.
 
-**Not for:** greenfield init (setup), empty template import (ai-spector-generate), or full doc generation.
+**Read first:** `.docops/guide/MIGRATION.md` and `.docops/guide/guides/PROJECT_LAYOUT.md`
 
-### Phase 0 — Confirm candidate
+**Hard rule:** Prefer editing `docTypes.*.path` in `.docops/docops.config.json` to point at folders that already hold your markdown.
 
-```bash
-npx ai-spector check --json
-# MCP: workspace_check({})
-```
-
-Read `errors[]` / `warnings[]` — STRUCT-003/004 and layout failures expected before adopt.
-
-Tell the user: init appears done; which doc paths look non-canonical. Ask: "Proceed with adopt scan?"
-
-Create work session:
-
-```json
-work_create({ "kind": "adopt", "workflow": "adopt", "trigger": "<user's phrase>" })
-```
-
-### Phase 1 — Adopt scan
-
-```bash
-npx ai-spector adopt scan --json
-# MCP: adopt_scan({})
-```
-
-Parse `candidates[]` — each has `from`, `to`, `docType`, `confidence`. Note `classifiedAs: "custom"` (needs template import first — pause adopt, open `ai-spector-generate`, then start new adopt task).
-
-Ask clarifying questions from `scan.questions[]` until all have answers.
-
-### Phase 2 — Plan
+### Phase 0 — Assess
 
 ```bash
-npx ai-spector adopt plan --json
-# MCP: adopt_plan({})
+npx ai-spector docops status --json
+npx ai-spector docops layout --prompt
+npx ai-spector docops check --prompt
 ```
 
-Show mapping table to user. Ask: "Approve this adopt plan?" — wait for yes → `work_approve_plan({ workId })`.
+### Phase 1 — Configure paths
 
-### Phase 3 — Apply
+Edit `.docops/docops.config.json`:
 
-```bash
-npx ai-spector adopt apply --json
-# dry run first: npx ai-spector adopt apply --dry-run --json
-```
+- `docTypes.srs.path`, `basicDesign.path`, `detailDesign.path` (repo-root-relative, e.g. `docs/srs`)
+- `languages`, `primaryLanguage`, `internalLanguage`, `clientLanguage`
+- `docTypes.*.templatesPath` under `.docops/templates/`
 
-On `dry-run` clean → re-run without `--dry-run`.
+Customize template markdown under `.docops/templates/{srs,basic-design,detail-design}/` if needed.
 
-### Phase 4 — Bootstrap
+### Phase 2 — Repair contract
 
 ```bash
-npx ai-spector adopt bootstrap --json
-# MCP: adopt_bootstrap({})
+npx ai-spector docops migrate --repair --json
+npx ai-spector index
+npx ai-spector docops registry sync
 ```
 
-Indexes the migrated docs.
-
-### Phase 5 — Validate
+### Phase 3 — Verify
 
 ```bash
-npx ai-spector adopt validate --sync --json
-# MCP: adopt_validate({ sync: true })
-```
-
-`ready: true` → complete. Otherwise fix remaining issues.
-
-### Phase 6 — Complete
-
-```
-work_complete({ workId, summary: "Adopted N docs from legacy paths" })
+npx ai-spector docops check --json
+npx ai-spector lifecycle sync --json
 ```
 
-**Forbidden:** `work_approve_plan` before plan shown; `adopt_apply` before plan approval; template-import nested inside adopt task.
+`docops check` → `valid: true` and `writerReady: true` → done.
 
 ---
 
@@ -287,7 +252,18 @@ Splits `docflow.config.json` into `.docops/docops.config.json` + `.ai-spector/en
 npx ai-spector docops migrate --repair --json
 ```
 
-Fills missing capability files; patches config gaps (including short `docTypes.*.path` values).
+Fills missing capability files; patches config gaps (including short `docTypes.*.path` values, missing `detailDesign` / `otherDocument`, and empty `.docops/templates/detail-design/`).
+
+### Phase 3b — Manual fallback (CLI failed)
+
+When init/migrate/repair exits non-zero or bootstrap bundle is missing — **after user approves workaround** per [cli-failures.md](cli-failures.md):
+
+1. Read **`.docops/guide/guides/DOCOPS_MANUAL_FALLBACK.md`** in the target repo (committed by Writer setup), or **`kari-writer/contracts/bootstrap/docs/guides/DOCOPS_MANUAL_FALLBACK.md`** in the monorepo.
+2. Patch `docops.config.json` — merge missing `detailDesign` + `otherDocument` (`enabled: false`).
+3. Copy scaffold + templates from bootstrap bundle — **never overwrite** existing files.
+4. Verify with `npx ai-spector docops status --json` when CLI works again.
+
+Same rules as repair; agents finish the task in git when the script cannot.
 
 ### Lifecycle sync
 
@@ -350,7 +326,7 @@ After opening the lesson, ask: "Which part would you like to try in this project
 
 ## Work Sessions
 
-Resume, pause, list, or route active work sessions (`kind: generate`, `change`, `adopt`, `migrate`).
+Resume, pause, list, or route active work sessions (`kind: generate`, `change`, `migrate`).
 
 Work sessions replace the former `task_*` concept — use `work_*` MCP tools.
 
@@ -371,8 +347,7 @@ work_get({ workId })
 
 Route by `kind`:
 - `generate` / `change` → `ai-spector-generate`
-- `adopt` → stay in this skill (Adopt section)
-- `migrate` → stay in this skill (Docops section)
+- `migrate` → stay in this skill (Docops / Migrate existing project)
 
 ### Lifecycle MCP tools
 

package/scaffold/claude/.claude/workflows/adopt.md

@@ -1,14 +0,0 @@
-# Adopt (migrate existing docs)
-
-**Workflow trigger:** activate **`ai-spector-adopt`**.
-
-Read `.claude/skills/ai-spector-adopt/skill.md` and `references/runbook.md`.
-
-## Gates
-
-1. `workspace_check` → `adopt_scan` (Gate 1)
-2. `adopt_plan` → user **approve plan** (Gate 2)
-3. `adopt_apply` → user confirms bootstrap (Gate 3) → `adopt_bootstrap`
-4. `adopt_validate` → user **migration complete** → `adopt_setup_mark migration.complete` (Gate 4)
-
-**Forbidden:** `adopt_apply` before plan approved; `task_approve_plan` is **not** adopt plan approval.

package/scaffold/cursor/commands/adopt.md

@@ -1,14 +0,0 @@
-# Adopt (migrate existing docs)
-
-**Routing override:** activate **`ai-spector-adopt`**.
-
-Read `.cursor/skills/ai-spector-adopt/SKILL.md` and `references/runbook.md`.
-
-## Gates
-
-1. `workspace_check` → `adopt_scan` (Gate 1)
-2. `adopt_plan` → user **approve plan** (Gate 2)
-3. `adopt_apply` → user confirms bootstrap (Gate 3) → `adopt_bootstrap`
-4. `adopt_validate` → user **migration complete** → `adopt_setup_mark migration.complete` (Gate 4)
-
-**Forbidden:** `adopt_apply` before plan approved; `task_approve_plan` is **not** adopt plan approval.