# Documentation Bc Ccn Generator

> >-

- **Type:** Skill
- **Install:** `agentstack add skill-fernandoartalf-al-copilot-skills-collection-documentation-bc-ccn-generator`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [fernandoartalf](https://agentstack.voostack.com/s/fernandoartalf)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [fernandoartalf](https://github.com/fernandoartalf)
- **Source:** https://github.com/fernandoartalf/AL-Copilot-Skills-Collection/tree/main/skills/documentation-bc-ccn-generator
- **Website:** https://alcopilotskills.com/

## Install

```sh
agentstack add skill-fernandoartalf-al-copilot-skills-collection-documentation-bc-ccn-generator
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Documentation: BC CCN Generator

Generate a Business Central **Change Control Note (CCN)** under `docs/ccn/` (English) or `docs/-ccn/` (any other supported language) as the single stakeholder-facing artefact that consolidates an approved user story, technical spec, architecture document, and feasibility analysis into one consistent markdown file. The file is designed to be fed downstream into the `md-to-docx-converter` skill using a single CCN-specific Word template that works across all languages.

## When to use

The user has at least an approved user story (`US-NNN`) and a draft/approved spec (`SPEC-NNN`); optionally also `ARCH-NNN` and `ANALYSIS-NNN`. They want a single document — in any language — that summarises the change for sign-off and that converts cleanly to Word later.

## Language model (CRITICAL)

The CCN supports any BCP-47 language code (`en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, etc.). To keep the downstream JSON extraction keys used by `md-to-docx-converter` byte-stable across languages, the document is split into two layers:

| Layer | Language | Examples |
|---|---|---|
| **Structural layer** (NEVER translated) | English / canonical | YAML frontmatter keys (`id`, `title`, `customer`, `dsd_ticket`, `user_story`, `spec`, `architecture`, `analysis`, `recommendation`, `related_docs`); all H1/H2/H3 section headings (`## 1. Header`, `## 2. Business context (from US-NNN)`, `### 2.1 Who`, …); §1 Header **field labels** (`CCN ID`, `Customer`, `DSD ticket`, `BC environment`, `Prepared by`, `Date`, `Status`, `Recommendation`, …); table **column headers** in §2.6, §3.2, §3.7, §4.1, §4.3, §4.5, §5.3, §6.1, §6.2, §6.3, §7, §10; diagram marker attributes (``); decision tokens (`GO`, `CONDITIONAL-GO`, `NO-GO`); the verdict heading `### ****`. |
| **Content layer** (translated to target language) | Target language | All prose paragraphs, blockquote text, numbered/bulleted item content, table **cell values**, SWOT body text, risk descriptions/mitigations, advisory items, the leading blockquote under the H1, the approval checkbox labels (`☐ Approved`, etc., translated as words but keeping the `☐` symbol). |

Why: the converter slugifies H2/H3 headings into JSON keys (e.g. `1Header`, `2ContextoDeNegocio…` in the legacy bilingual run). Keeping headings canonical-English guarantees a single `field-map.json` and a single Word template work for any language.

## Default output location

- `language = en` → `docs/ccn/` (default).
- Any other language → `docs/-ccn/` where `` is the lowercase BCP-47 primary subtag (e.g. `docs/es-ccn/`, `docs/fr-ccn/`, `docs/de-ccn/`). Create the folder if it does not exist.

Do not ask the user where to save the file beyond confirming the language.

## Workflow

Follow these steps in order. Do not skip the source validation step (Step 1), the interview step (Step 3), or the diagram marker step (Step 6).

### Step 1 — Identify and validate the source artefacts

1. If the user did not specify a US/SPEC ID, list files in `openspec/userstories/` (or `openspec/user-stories/`) and `openspec/specs/` and ask which feature to consolidate via `vscode_askQuestions`.
2. Read the user story and capture: `id` (US-NNN), `title`, `status`, `module`, `ProductOwner`, `approved_date`, the role / want / so-that triplet, business context, functional scope, acceptance criteria, Out-of-Scope, Future Enhancements, Open Questions.
3. Read the technical spec and capture: `id` (SPEC-NNN), `title`, `module`, `prefix`, `id_range`, design principles, AL object inventory, No. Series setup, API surface, localisation notes, Open-Questions resolutions, phase overview.
4. If `openspec/architecture/ARCH-NNN-.architecture.md` exists, read it and capture: `id` (ARCH-NNN), ADR summary table, logical component view (ASCII / mermaid), cross-cutting concerns table, legacy coexistence statement, known constraints (`C-N`).
5. If `openspec/analysis/ANALYSIS-NNN-.analysis.md` exists, read it and capture: `id` (ANALYSIS-NNN), change summary, per-phase effort hours (Optimistic / Expected / Pessimistic), contingency line, cost table, SWOT, risk register (`R-NN`), verdict (GO / CONDITIONAL-GO / NO-GO).
6. If any of US / SPEC are missing, abort with a clear error. ARCH and ANALYSIS are optional — when absent, the corresponding sections are produced from the spec only and an explicit `> _Architecture document not yet available — section derived from SPEC only._` blockquote is inserted.

### Step 2 — Allocate the next CCN ID

1. List files in the chosen output folder matching `CCN-*.md`.
2. Parse the highest existing numeric ID and increment by 1; format as `CCN-NNN` (zero-padded to 3 digits).
3. If the folder does not exist or is empty, start at `CCN-001`.
4. If the allocated filename would collide, re-increment until free. Never overwrite.

### Step 3 — Interview the user

Ask the four questions below in **a single `vscode_askQuestions` call** (one block, four entries) before drafting. All four questions are mandatory.

1. **`language`** — BCP-47 primary subtag. Default `en`. Accept any of `en`, `es`, `fr`, `de`, `it`, `pt`, `nl`, `ca`, `eu`, `gl`, `pl`, `da`, `sv`, `no`, `fi`, `cs`, `el`, `ja`, `zh`. If the user provides a non-listed code, accept it but warn that terminology has not been pre-validated. Drives ONLY (a) the output folder (`docs/ccn/` for `en`, `docs/-ccn/` otherwise) and (b) the natural-language content of paragraphs, list items, and table cell values. It MUST NOT change any section heading, frontmatter key, §1 field label, table column header, diagram marker, or verdict token — those remain canonical English per the §Language model table above.
2. **`include_costs`** — `yes` / `no`. If `no`, all monetary figures, EUR/h rates, and the §5 Cost table from ANALYSIS are omitted. The §6 Time table is preserved (hours only) unless `include_hours` is also `no`. If `yes`, the §5 Cost table is included using the rate recorded in ANALYSIS.
3. **`include_hours`** — `yes` / `no`. If `no`, all hour figures and calendar-duration tables are omitted; §6 is replaced by a one-line "Effort and duration intentionally omitted from this version." statement. If `yes`, include the §6 Time table.
4. **`scenarios`** — multi-select from `Optimistic`, `Expected`, `Pessimistic`, `Neutral`. Pre-validate that the chosen scenarios exist in ANALYSIS. If ANALYSIS only reports a single neutral estimate (as in CCN-001), accept only `Neutral` and warn the user that the other scenarios are not available. Default selection: `Expected` + `Neutral` (when both exist), otherwise whatever ANALYSIS provides.

If `include_costs = yes` and `include_hours = no`, abort with an explanatory error — costs cannot be reported without their underlying hour basis.

If ANALYSIS is missing entirely, force `include_costs = no` and `include_hours = no` and inform the user that §5 and §6 will be omitted because the analysis source is unavailable.

### Step 4 — Resolve cross-document references

1. Compute `` from the user-story title: lowercase, ASCII-fold (diacritics stripped), non-alphanumerics replaced by hyphens, hyphens collapsed.
2. Build the relative-path links that will appear in the document body and frontmatter `related_docs`:
   - `../../openspec/userstories/US-NNN-.story.md`
   - `../../openspec/specs/SPEC-NNN-.spec.md`
   - `../../openspec/architecture/ARCH-NNN-.architecture.md` (omit if missing)
   - `../../openspec/analysis/ANALYSIS-NNN-.analysis.md` (omit if missing)
3. Verify each path exists on disk. A missing link is a hard error unless the artefact was already marked optional (ARCH / ANALYSIS).

### Step 5 — Build the section content

Follow the section order and rules below. **Section headings, IDs, and ordering MUST be byte-stable** so the same Word template placeholder set keeps working release after release. Source citations are mandatory.

Section headings are **always** in canonical English regardless of `language`. Translate only the body content (prose, list items, table cell values).

| §  | Canonical heading (always English)             | Source            |
|----|------------------------------------------------|-------------------|
| 1  | Header                                          | SPEC + USER + ANALYSIS frontmatter |
| 2  | Business context (from US-NNN)                  | USER §Business Context, §Functional Scope, §AC, §Out-of-Scope, §Future Enhancements |
| 3  | Proposed solution (from SPEC-NNN)               | SPEC §Design Principles, §Object Inventory, §No. Series, §API, §Localisation, §Phase Overview |
| 4  | Architecture solution (from ARCH-NNN)           | ARCH §ADRs, §Component View, §Cross-cutting, §Coexistence, §Constraints |
| 5  | Feasibility analysis (from ANALYSIS-NNN)        | ANALYSIS §Change Summary, §SWOT, §Risk Register, §OQ Status |
| 6  | Time estimate                                   | ANALYSIS §Effort (filtered by `scenarios`) |
| 7  | Testing setup (planned)                         | SPEC §Phase Overview + ANALYSIS §Test Strategy |
| 8  | Testing steps (acceptance, executed by Customer)  | USER §AC translated into manual steps |
| 9  | Recommendation                                  | ANALYSIS §Verdict + §Non-blocking advisories |
| 10 | Approvals                                        | Empty 3-row table (PO, Tech Lead, PM) |

Rules:

- **§1 Header table MUST have one row per field with bold labels in canonical English** (`| **Field** | Value |`), so the downstream `md-to-docx-converter` skill's metadata extraction works. The label set is fixed: `CCN ID`, `Title`, `Customer`, `DSD ticket`, `BC environment`, `BC version baseline`, `Extension affected`, `Source user story`, `Source spec`, `Architecture`, `Analysis`, `Prepared by`, `Date`, `Status`, `Recommendation`. Field labels are NEVER translated — even when `language ≠ en` — because the converter keys off them.
- **§1 values MUST be plain text** (and MAY be in the target language for human-readable fields such as `Customer` notes; identifiers like `CCN-001`, `US-001`, `SPEC-001`, dates, version numbers, and the `GO`/`CONDITIONAL-GO`/`NO-GO` token MUST stay verbatim). No markdown links, no backticks, no em-dashes. This guarantees clean substitution into the Word template.
- **§2 §3 §4 §5** are derived sections — copy the *prose and tables*, never the AL source code. Strip any ```al blocks from the source documents.
- **§4 §6 §7** MUST cite their source document at the top of the section as a leading sentence (e.g. _"Drawn from [ARCH-001](...)."_).
- **§6 Time estimate** content is shaped by the interview:
  - `include_hours = no` → render only the line: `_Effort and duration intentionally omitted from this version of the document._`
  - `include_hours = yes` and `include_costs = no` → render the effort-per-phase table and calendar duration table, but strip any EUR / cost columns.
  - `include_hours = yes` and `include_costs = yes` → render the effort table, calendar table, **and** a cost-per-scenario table at the chosen `scenarios`. State the EUR/h rate from ANALYSIS verbatim.
  - When more than one scenario is selected, render side-by-side columns (one column per scenario) on the effort and cost tables. When only one scenario is selected, use a single value column.
- **§9 Recommendation** verdict heading MUST match the ANALYSIS verdict verbatim (`**GO**`, `**CONDITIONAL-GO**`, or `**NO-GO**`).
- **§10 Approvals** table is always rendered as an empty 3-row table. The closing blockquote MUST reference `openspec/plans/` as the place where phase plans are flipped from `not-started` to `approved`.

### Step 6 — Mark diagrams for downstream conversion

Every block that the docx converter will render as a Mermaid diagram MUST be surrounded by an explicit HTML comment marker pair so the converter recognises it. Use exactly these markers and nothing else:

```

... optional ASCII fallback kept verbatim for the markdown reader ...
```mermaid

```

```

Mandatory rules for every marker block:

1. **A ```mermaid fenced block is REQUIRED inside the markers.** It is the only source the `md-to-docx-converter` can render into a PNG; without it the converter will fall back to plain text. Author the Mermaid syntax yourself — do NOT rely on the converter to regenerate Mermaid from ASCII art.
2. The Mermaid source must be **valid for the declared `type`** (e.g. `type="flowchart"` requires a `flowchart` / `graph` diagram; `type="erDiagram"` requires an `erDiagram` diagram).
3. The optional ASCII art kept above the ```mermaid fence is for human readability of the raw markdown only. The converter ignores it.
4. `name` must be **unique within the CCN** and kebab-cased.
5. Do NOT nest a marker block inside another fenced code block (` ```text `, ` ```` ` ``` ` ```` `, …). The converter only matches markers at body level.

Apply markers to **at least** these diagrams when their source document supplies them:

| Source | Block | Suggested `type` | Suggested `name` |
|---|---|---|---|
| ARCH §4.2 (logical component view) | ASCII / fenced block in §4 of the CCN | `flowchart` | `component-view` |
| ARCH §6.1 (entity-relationship overview) | If present, inserted into §4 of the CCN | `erDiagram` | `entity-relationship` |
| SPEC / ARCH (status lifecycle) | Forward-only Status transition, inserted into §3 or §4 | `stateDiagram` | `status-lifecycle` |
| ARCH §5 (key runtime flow) | Each flow inserted into §4 of the CCN | `sequenceDiagram` | `flow-` |

Do not auto-convert pre-existing ASCII art into Mermaid blindly — understand the source diagram first, then write a hand-crafted Mermaid block that reflects it. Keep the ASCII above the ```mermaid fence so the raw markdown remains readable for reviewers. If a diagrammable block is not present in any source document, do not invent it.

When the CCN is later passed through the `md-to-docx-converter` skill, each marker block is replaced in the JSON body by a `{{DIAGRAM:}}` token, the captured Mermaid source is stored under the JSON `_diagrams` key, and the token is rendered as an inline PNG image (via the Mermaid CLI `mmdc`) in the generated `.docx`. A missing or invalid Mermaid block degrades to a labelled text block in the docx but does not abort the conversion.

### Step 7 — Build the filename

Format: `CCN-NNN-.md`

- `` is the lowercase ASCII-folded title from Step 4.
- Validate against `^CCN-\d{3}-[a-z0-9]+(-[a-z0-9]+)*\.md$` before writing.

### Step 8 — Write the CCN document

Create the file at `/` using the template in `references/ccn-template.md`. The file MUST contain, in this exact order:

1. YAML frontmatter — **keys are ALWAYS in canonical English regardless of `language`**; only free-text values (e.g. `title`, `prepared_by`) may be in the target language. Identifier values (`id`, `user_story`, `spec`, `architecture`, `analysis`, `recommendation`), enum values (`status: Pending Approval`), and the `version` number MUST stay verbatim:
   ```yaml
   ---
   id: CCN-NNN
   title: Change Control Note — 
   version: 1.0
   status: Pending Approval
   customer: 
   dsd_ticket: TBD
   user_story: US-NNN
   spec: SPEC-NNN
   architecture: ARCH-NNN  # omit key entirely if ARCH not present
   analysis: ANALYSIS-NNN  # omit key entirely if ANALYSIS not present
   prepared_by: 
   date: 
   recommendation: 
   related_docs:
     - openspec/userstories/US-NNN-.story.md
     - openspec/specs/SPEC-NNN-.spec.md
     # add architecture / analysis lines only if those files exist
   ---
   ```
2. `# CCN-NNN — ` H1.
3. A leading blockquote summarising the CCN purpose and linking to US / SPEC / ARCH / ANALYSIS, plus an explicit one-line statement of which monetary / hour data is included or excluded (echoes the Step 3 interview answer).
4. Sections §1–§10 in the exact order from the table in Step 5. **All H2/H3 section headings remain in canonical English regardless of `language`.** Only the prose paragraphs, list item text, and table-cell values inside each section are translated to the target language.

### Step 9 — Confirm and report

A

…

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [fernandoartalf](https://github.com/fernandoartalf)
- **Source:** [fernandoartalf/AL-Copilot-Skills-Collection](https://github.com/fernandoartalf/AL-Copilot-Skills-Collection)
- **License:** MIT
- **Homepage:** https://alcopilotskills.com/

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-fernandoartalf-al-copilot-skills-collection-documentation-bc-ccn-generator
- Seller: https://agentstack.voostack.com/s/fernandoartalf
- 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%.