# Dia Migration > > - **Type:** Skill - **Install:** `agentstack add skill-pssah4-digital-innovation-agents-dia-migration` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [pssah4](https://agentstack.voostack.com/s/pssah4) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [pssah4](https://github.com/pssah4) - **Source:** https://github.com/pssah4/digital-innovation-agents/tree/main/skills/dia-migration - **Website:** https://pssah4.github.io/digital-innovation-agents/ ## Install ```sh agentstack add skill-pssah4-digital-innovation-agents-dia-migration ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # DIA Migration Convenience wrapper that brings an **existing DIA repo** to current conventions. Not a brownfield onboarding skill -- for that, use `/reverse-engineering`, which contains the same migration mechanics plus a full code-walk for missing artefacts. Designed for two starting states: - **DIA v1 -> current**: artefacts use the old patterns (FEATURE-NNNN, ADR-NNN, status in frontmatter, fixes under context/, archive/ folders, 20_bugs.md, numeric-prefixed context files). - **Older V-Model variant -> current**: same DIA layout idea but inconsistent prefixes or per-cycle handoffs. For **brownfield without V-Model artefacts** (code exists, no `_devprocess/` directory): the answer is `/reverse-engineering`. That skill detects pre-existing partial artefacts, runs the same migration scripts as Phase -1.5, then walks the code to produce the missing artefacts. Do not start with `/dia-migration` for brownfield -- you would only get the migration step without the artefact-bootstrap from code. The skill is **idempotent**. Running it on an already-current repo performs the consistency check and exits without changes. ## MANDATORY Pre-Phase 0: Branch check (cross-cutting operation) Migration is a cross-cutting maintenance operation, not a V-Model phase. It does not target a backlog item; it touches many artefacts across the repo. Therefore migration runs on a dedicated branch and does not set V-Model phase tags. Branch convention: `chore/dia-migration-`. Check at start (full rules: `skills/project-conventions/references/team-workflow.md`): 1. If on `main` / `master` / `dev`: refuse, AskUserQuestion to create `chore/dia-migration-` and switch. 2. If on the expected migration branch (or any other `chore/*` / `feature/*` branch the user explicitly confirms): silent continue. 3. If on a different branch: AskUserQuestion to switch to the migration branch (recommended) or stay (only when consciously bundling migration with other work, which is discouraged). GitHub integration: migration does NOT create a per-item issue or draft PR. The migration commits go in as a single chore PR (`chore/dia-migration-` -> `dev`). The user opens that PR manually after Phase 7 completes. Phase tags: migration does NOT set V-Model phase tags (`/ba-done` etc. are reserved for backlog items). It does write progress markers via per-phase commits with the message prefix `chore(dia-migration): phase -- ` so the history is reviewable. State stored in `.git/dia-active-skill` so subsequent invocations of the migration loop stay silent if everything matches. ## Shared tooling This skill orchestrates the scripts under `tools/migration/` in the DIA repo: | Script | Phase | Purpose | |---------------------------------|-------|----------------------------------------------------------| | `tools/migration/detect_state.py` | 0 | Inventory the repo, classify v1/v2/mixed. | | `tools/migration/strip_frontmatter_status.py` | 2a | Remove `status:` / `phase:` from YAML frontmatter. | | `tools/migration/strip_body_status.py` | 2b | Remove body-level `**Status:**` / `> **Status**:` lines. | | `tools/migration/migrate_naming.py` | 3 | Rename ID schemas (FEATURE-NNNN -> FEAT-EE-FF, etc.). | | `tools/migration/flatten_analysis.py` | 4 | Flatten analysis/ to BA / EXPLORE / RESEARCH / AUDIT. | | `tools/migration/build_backlog.py` | 5 | Regenerate BACKLOG.md from artefact scan. | | `tools/migration/migrate_skill_names.py` | 6 | Rewrite `/business-analyse` -> `/business-analysis`, `/v-model-workflow` -> `/dia-guide`. | | `tools/migration/migrate_status_vocabulary.py` | 5b | Rewrite BACKLOG status values to the GitHub-aligned vocabulary. | `/reverse-engineering` reuses the same scripts under Phase -1.5. Both skills share the canonical implementation; this one wraps it with a phase-by-phase confirmation loop, the other one runs them silently as part of the backwards walk. ## Writing style Every artifact this skill writes follows the rules in `skills/project-conventions/SKILL.md` under "Writing style for every artifact". No em dashes, no AI vocabulary, no negative parallelisms, sentence case in headings. ## When to invoke User says: - "migrate this project to DIA v2" - "upgrade my V-Model setup" - "restructure the backlog" - "clean up artifact frontmatter" - "convert FEATURE-NNNN to FEAT-NN-NN" Or: another skill (typically `/dia-guide` on first run against a non-conforming repo) calls `/dia-migration` to bring the structure in line before continuing. ## Safety contract The skill operates on a feature branch. It does not push, it does not touch source code, and it does not delete user-authored content without explicit confirmation. Concrete rules: 1. Branch check at start. Refuse to run on `main`, `master`, or `dev`. The user must create a migration branch first (`git checkout -b feature/dia-migration` is the typical name). 2. Source code under `src/` (or the project's code root) is only edited to add `src/ARCHITECTURE.map` and optional `src/{module}/README.md` files. JSDoc headers in `.ts`/`.js` files are NOT auto-written. The skill proposes a list and asks. 3. Files outside `_devprocess/` and `src/` are not touched. 4. Deletes are listed before execution. `archive/` folders, the legacy `20_bugs.md`, and superseded handoff files are removed only after the user sees the list. 5. If git status is dirty at start, the skill stops and asks the user to commit or stash first. Mid-migration commits on a clean tree are encouraged so each phase is reversible. ## Phases The skill walks seven phases. Each phase is independently re-runnable. If a phase fails, the next one is not started. ### Phase 0: Detection and plan Inventory the repo and classify it. Outputs a one-page plan for user review. - Detect project root convention: `_devprocess/`, `docs/`, or none. - Scan for old vs. new patterns: - filename pattern `FEATURE-NNNN` (4-digit) -> v1 - filename pattern `FEAT-NN-NN` -> v2 - presence of `_devprocess/context/fixes/` -> v1 - presence of `_devprocess/requirements/fixes/` -> v2 - presence of `_devprocess/context/20_bugs.md` -> v1 - presence of any `archive/` directory under `_devprocess/` -> v1 - frontmatter `status:` or `phase:` fields -> v1 - body-level `**Status:**` headers in artifacts -> v1 - presence of `_devprocess/requirements/epics/EPIC-*-ba.md` (legacy mini-BA next to the EPIC) -> v1, must move to `analysis/BA-EPIC-{nn}-{slug}.md` in Phase 4 - Count each finding. - Decide migration scope: - all v2 patterns, no findings -> exit with green report - mixed -> run all phases (each is idempotent) - brownfield (no `_devprocess/` and no `docs/`) -> hand off to `/reverse-engineering` first, then continue here The plan is saved as a Markdown report at `_devprocess/context/HANDOFFS.md` under a new entry `dia-migration plan {date}` and printed for the user. ### Phase 1: Foundation Create the layers that DIA v2 requires regardless of starting state. 1. `_devprocess/rules/` with `technical.md` (always), `design.md` (only if the project has UI surface), `domain.md` (always). Seeded from `skills/architecture/templates/RULES-*-TEMPLATE.md`. If files already exist, leave them in place but check the line budget (max 500 lines total). 2. `src/ARCHITECTURE.map` seeded from `skills/architecture/templates/ARCHITECTURE-MAP-TEMPLATE.md`. If a map already exists, validate it; otherwise scan `src/` for entry-point candidates (large files containing `class`, `interface`, `Manager`, `Service`, `Registry`, `Pipeline` in their names) and propose initial rows. The user confirms before writing. 3. `_devprocess/requirements/{epics,features,fixes,improvements,handoff}/` directories. Move existing `_devprocess/context/fixes/` to `_devprocess/requirements/fixes/` and same for `improvements/`. Legacy `EPIC-{nn}-ba.md` files inside `_devprocess/requirements/epics/` are moved to `_devprocess/analysis/BA-EPIC-{nn}-{slug}.md` (slug from the sibling EPIC file). The legacy mini-BA convention is dropped. 4. `_devprocess/analysis/` flattened: `analysis/security/AUDIT-*` moves to `analysis/` root, `archive/` deleted (with the file list shown to the user first). 5. `_devprocess/context/20_bugs.md` deleted. The backlog regenerated in Phase 5 carries the FIX status. ### Phase 2: Bulk frontmatter and body status cleanup Every artifact under `_devprocess/requirements/`, `architecture/`, `implementation/plans/`, `context/fixes/`, `context/improvements/` gets two passes: 1. **Frontmatter pass**: remove `status:`, `phase:`, `last_updated:`, `last-updated:`, `lastUpdated:` lines from the YAML frontmatter. Multi-line values are removed entirely. 2. **Body header pass**: in the first 25 lines after the frontmatter, remove lines matching `**Status:** X`, `> **Status:** X`, `Status: Implemented`, `Status: Akzeptiert`, etc. Also `**Last Updated:** ...` and German equivalents. Run via `tools/migration/strip_frontmatter_status.py` and `tools/migration/strip_body_status.py` (both live under `tools/migration/` in the DIA repo). After this phase, the repo's status truth lives ONLY in the backlog. ### Phase 3: Filename migration to DIA v2 ID schemas Renames artifact files and updates all cross-references in `.md`-files plus `src/ARCHITECTURE.map`. Idempotent. | Old pattern | New pattern | Notes | |--------------------------|----------------------------|----------------------------------------| | `EPIC-NNN-{slug}.md` | `EPIC-{nn}-{slug}.md` | strip leading zero, fits in 2 digits | | `FEATURE-NNNN-{slug}.md` | `FEAT-{ee}-{ff}-{slug}.md` | prefix change FEATURE -> FEAT, hyphen split | | `FEATURE-NNN-{slug}.md` | `FEAT-{ee}-{ff}-{slug}.md` | legacy 3-digit (e.g. FEATURE-400) gets normalized | | `FIX-{eeff}-{nn}-{slug}.md` | `FIX-{ee}-{ff}-{nn}-{slug}.md` | hyphen split for clarity | | `IMP-{eeff}-{nn}-{slug}.md` | `IMP-{ee}-{ff}-{nn}-{slug}.md` | analog | | `ADR-NNN-{slug}.md` | `ADR-{nn}-{slug}.md` | strip leading zero | | `PLAN-NNN-{slug}.md` | `PLAN-{nn}-{slug}.md` | strip leading zero | | `BA-{slug}.md` (project, no item ref) | `BA-{PROJECT}.md` | Singleton Project-BA, slug becomes project shortname | | `BA-NNN-{slug}.md` (legacy item-BA) | `BA-EPIC-{nn}-{slug}.md` | Legacy generic BA-NNN promoted to Item-BA-Epic if it carries epic-level discovery; otherwise renamed to `BA-{PROJECT}.md` (asks user once) | | `EPIC-{nn}-ba.md` (legacy mini) | `BA-EPIC-{nn}-{slug}.md` | move from `requirements/epics/` to `analysis/`; slug carried over from sibling EPIC file | | `EXPLORE-NNN-{slug}.md` | `EXPLORE-{nn}-{slug}.md` | strip leading zero | | `RESEARCH-NNN-{slug}.md` | `RESEARCH-{nn}-{slug}.md` | strip leading zero | | handoff files | `architect-handoff-FEAT-{ee}-{ff}.md`, `plan-context-FEAT-{ee}-{ff}.md` | per active feature stream | Run via `tools/migration/migrate_naming.py`. The script does two passes: first the file renames, then a global text replacement of references using the rename map. A second sweep catches body references to IDs that do not have a corresponding file (e.g. an EPIC-023 mentioned in prose but never created). When the file count exceeds 99 in any class, the script suggests extending that class to 3-digit (e.g. `EPIC-100`). The user confirms before applying. Until then, 2-digit is the default. The append-only `_devprocess/context/HANDOFFS.md` is exempt from the body sweep. Historical entries keep their original IDs as audit-trail records. ### Phase 4: analysis/ flattening to four prefixes plus sources/ Reduces the analysis/ directory to four flat prefixes (`BA-`, `EXPLORE-`, `RESEARCH-`, `AUDIT-`) at the root, plus a single `sources/` subfolder for user-provided source documents. The BA prefix has five accepted shapes after the migration. All five sit flat in `analysis/`. None live next to the EPIC artefact: - `BA-{PROJECT}.md` (singleton Project-BA) - `BA-EPIC-{nn}-{slug}.md` (Item-BA per epic) - `BA-FEAT-{ee}-{ff}-{slug}.md` (Item-BA per feature) - `BA-IMP-{ee}-{ff}-{nn}-{slug}.md` (Item-BA per improvement, optional) - `BA-FIX-{ee}-{ff}-{nn}-{slug}.md` (Item-BA per fix, optional) Legacy mini-BAs at `_devprocess/requirements/epics/EPIC-{nn}-ba.md` move to `analysis/BA-EPIC-{nn}-{slug}.md`, with `{slug}` carried over from the sibling EPIC file. The `EPIC-{nn}-ba.md` file is removed after the move. - `CODEBASE-NNN`, `DESIGN-NNN`, `SECURITY-NNN`, `SPIKE-NNN`, `FINDING-`, `ROOT-CAUSE-`, `GAP-ANALYSE-`, `SOLUTION-PROPOSAL-`, `SCAFFOLD-`, `MOBILE-`, `STANDALONE-`, `TEMPLATE-`, `REVIEW-`, `ANALYSIS-`, `HANDOFF-` -> renamed to `RESEARCH-NN-{originalprefix-slug}`, preserving the old prefix in the slug for traceability. - `analysis/security/AUDIT-*.md` -> moved to `analysis/AUDIT-*.md` (flat). - `analysis/security/` and `analysis/archive/` directories deleted (archive content has typically been replaced by the backlog). - `analysis/SOURCE-*` (any extension) -> moved to `analysis/sources/SOURCE-*`. This is the only subfolder that survives the flatten because user-provided sources are not engineered artefacts and benefit from a clean separation. - External content (blog posts, reddit posts) -> moved to `_devprocess/articles/` if present. Run via `tools/migration/flatten_analysis.py`. ### Phase 5: Backlog regeneration Build `_devprocess/context/BACKLOG.md` from scratch by scanning all artifacts. The new backlog is the single source of truth for status, phase, claim, and Refs. - One row per Feature, Fix, Improvement, ADR, Plan. - Epics are section headers, not rows. - The Title column holds the bare title only, never an id prefix. A detail file whose H1 is `# IMP-01-01-08: ensureColumn ...` produces Title `ensureColumn ...`, not `IMP-01-01-08: ensureColumn ...` (the id already lives in the first column; `flow.py` would otherwise emit a doubled `IMP-01-01-08: IMP-01-01-08: ...` issue title). `build_backlog.py` strips the prefix for every type at one choke point; do not hand-write prefixed titles either. - Status defaults from heuristics: - Features in epics 01-22 (or whatever ranges the user marks as "shipped") default to Done/Released. - Features in active epics default to Active/Building. - ADRs default to Accepted/Released for old ADRs and Accepted/Building for new ones (cutoff: numeric ID >= `last_shipped_adr + 1`, asked from the user once). - PLANs default to Draft/Building. - The Refs column is populated from frontmatter `epic:`, `adr-refs:`, `feature-refs:`, `related:`, `supersedes:`, `superseded-by:`, `ba-ref:`. - For every EPIC and FEAT artefact whose ID has a matching `analysis/BA-EPIC-*` or `analysis/BA-FEAT-*` file (after Phase 4), the script writes `ba-ref:` into the artefact frontmatter so the promotion link is restored. - A pre-existing `BACKLOG.md` is overwritten only after the user confirms (the script saves the previous version under `BACKLOG.md.preMigration` for one-step rollback). Run via `tools/migration/build_backlog.py`. The script is parameterized through a small YAML config that the user can edit before the run (epic cutoffs, status overrides for known exceptions). ### Phase 5b: Status vocabulary alignment After Phase 5 produces a fresh `BACKLOG.md`, this short phase brings the Status column from the legacy DIA vocabulary into the GitHub- aligned vocabulary so `flow.py sync-status` can mirror 1:1 without translation. Mapping: | Old (DIA legacy) | New (GitHub-aligned) | |------------------|----------------------| | `Planned` | `Ready` … ## Source & license This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [pssah4](https://github.com/pssah4) - **Source:** [pssah4/digital-innovation-agents](https://github.com/pssah4/digital-innovation-agents) - **License:** MIT - **Homepage:** https://pssah4.github.io/digital-innovation-agents/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-pssah4-digital-innovation-agents-dia-migration - Seller: https://agentstack.voostack.com/s/pssah4 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.