# Create Ard > Architecture-authoring workflow (Product Architect phase, sub-project 3 of the VI-creation flow). Grounds on the mounted implementation repos (architect-driven discovery — no PRs) and authors an ARD for a VI (create-ard: ) or an Epic (create-ard: , inheriting the VI-level ARD), against _shared/ard-format.md, gated by the Opus ard-reviewer, written to $SPECS_PATH/specifications/-/. Optional; scoped; product-architecture level (no code writing). Introduces the pa role. Activated when the user prompt starts with "create-ard:". - Skill: `ihudak/create-ard` (Agent Skill) - Install (CLI): `npx skillmds@latest add ihudak/create-ard` - Raw SKILL.md: https://api.skillmd.com/api/skills/ihudak/create-ard/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: ihudak (https://skillmd.com/u/ihudak) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ihudak/create-ard --- Author an Architecture Requirements/Decision Document for the Jira item: the argument (text following the `create-ard:` trigger) `create-ard:` is **sub-project 3 of the VI-creation flow** — the **Product Architect (PA)** phase. It grounds on the mounted implementation repos and authors an **ARD** that establishes the architecture invariants the downstream (`specify:`, `design:`, `implement:`) will later inherit. The ARD is **optional** (a simple VI may not need one) and **scoped** via the two-key grammar: - `create-ard: ` → a **VI-level** ARD. - `create-ard: ` → an **Epic-level** ARD (inherits the VI-level ARD read-only). It authors architecture only — no code writing; grounding is **architect-driven** (there are no PRs at this stage). Zero Jira API. --- ## Phase 0 — Resolve input 1. **Resolve the Jira input** via `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/jira-input-resolution.md` against the argument (text following the `create-ard:` trigger) → `jira_key` (the VI), `focus_key` (the Epic, or `null`), `jira_export_root`, `source`. Define `` = `jira_key`, `` = `focus_key`. 2. **`$SPECS_PATH` (required).** If unset, stop naming `SPECS_PATH` (`choices: ["Set SPECS_PATH (enter the path)", "Cancel"]`). 3. **Feature folder.** VI-level → `specifications/-/`; Epic-level → `specifications/-/-/`. Honor an existing dir matched by key-number (tolerate `-`/`_` drift). Auto-created on first write. 4. **Prior ARD.** If the target `*_ARD.md` exists → Phase 1 offers refine-vs-fresh. 5. **Optionality advisory.** Gauge size — the VI's user-story count / scope breadth / number of candidate repos. For a small, single-repo VI, note "an ARD may be optional here" and offer `choices: ["Author the ARD anyway", "Stop — no ARD needed", "Other… (describe)"]`. `create-ard:` is **cwd-agnostic**; it reads the VI/Epic and scans repos under `$REPOS_PATH`. **Specs-repo preflight.** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` and execute its `specs-preflight` entry point (§3) inline: flush any leftover session artifacts from an earlier run, retry an artifact commit that failed to push, and settle the branch. Prompt-free and silent when the specs repo is clean and on its default branch. If a guard fires, emit its §5 notice; if it returns `specs_git: blocked` (§3.3 G0), carry that flag for the whole run — the terminal `commit-artifacts` step skips on it. **Gate the VI.** Execute `require-on-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §3) against the VI file in `specifications/-/` — **resolve its actual name on the ref first**: `git -C "$SPECS_PATH" ls-tree --name-only "origin/" "specifications/-/"` filtered to `_*.md`, falling back to the derived `_.md` only when that listing is empty. A human-adjusted slug is a supported state — `create-vi:` and this skill's own Phase 2 reader both locate the VI by glob plus frontmatter, and the feature folder is matched by key-number for the same reason — so gating an exact derived filename would report `absent` for a VI that is present, and would let a slug-drifted file on a plugin branch escape the rows D/E stop entirely. Map its §3.7 return value by `stopped` first, never by `on_main` alone. Any stopping state → stop per §4.4. Otherwise (`stopped: false`): on `pass`/`pass_amending`, read the authored VI in Phase 2 as today; on `absent`, the existing `jira-reader` fallback applies — but report it: *"No authored VI on `` for `` — architecting from the Jira export at ``. If a VI exists on a branch, this run would have stopped; it does not, so none does."*; on `unmanaged`, behave exactly as before this feature — reachable here even after step 2's own `$SPECS_PATH` check, since that check only rejects an unset value, never an invalid path or a non-git directory. --- ## Phase 1 — Configure Use `choices` arrays; the last choice is always `"Other… (describe)"`. 1. **Confirm** the scope (VI-level vs Epic-level) and the feature folder. - Show the `docs grounding:` line in the form `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/docs-grounding.md` resolved — `ON (retrieval: …)` or `OFF ()` — verbatim, including any index-build, staleness, or shadowing clause it carries (off switch: --no-docs). 2. **Refine vs fresh** (only if a prior `*_ARD.md` exists): `choices: ["Refine the existing ARD (Recommended)", "Start fresh — overwrite", "Cancel", "Other… (describe)"]`. 3. **Repos search base (`$REPOS_PATH`).** Read `${REPOS_PATH:-/workspace}` (may be colon-separated): `choices: ["Use $REPOS_PATH (default /workspace) (Recommended)", "Use a different path (you'll be prompted)", "Cancel", "Other… (describe)"]`. 4. **Repo refresh policy** (governs Phase 3's `code-scanner`): `choices: ["fetch + pull default branch (Recommended)", "fetch only", "no refresh", "Other… (describe)"]`. --- ## Phase 1.5 — Classify + model routing Load and follow the model-routing policy at `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/model-routing.md`, then record: ```yaml model_routing: classification: MODERATE | SIGNIFICANT | HIGH-RISK # architecture; SIGNIFICANT common for cross-repo VIs reason: current_model: detection_model: <§2.1 detection chain: claude-sonnet-4.6, fallback claude-sonnet-4.5/gpt-5.4> # jira-reader, code-scanner, impl-maintenance review_model: <§2 Opus chain> # ard-reviewer (caller-pinned; recorded) authoring_model: <= current_model> # the interactive grill + ARD authoring (session model, not a delegated subagent) opus_available: notes: ``` **Tiered HARD model gate (like `design:`):** for `SIGNIFICANT` / `HIGH-RISK`, require an Opus session — if `opus_available` is false, stop: `choices: ["I'll relaunch create-ard: on Opus (Recommended)", "Override — proceed on the current model (logged in the final report)", "Cancel", "Other… (describe)"]`. For `SIMPLE`/`MODERATE`, degradation is advisory (record in `notes`). --- ## Phase 2 — Read the VI (+ Epic, + inherited ARD) Read the VI from `$SPECS_PATH/specifications/-/` — glob `_*.md` and use the file whose frontmatter is `issue_type: ValueIncrement` (canonical `_.md`) when present (authored source); else dispatch `jira-reader` to read it from the export: → task(agent_type: "dev-workflows:jira-reader", model: ``): > "Return the structured handoff for this brief: > > jira_export_root: [resolved jira_export_root] > jira_key: [ for a VI-level run, for an Epic-level run] > depth: vi-only (VI-level) | full (Epic-level, scoped to focus_key)" For an **Epic-level** run always dispatch `jira-reader` this way (`depth: full`, scoped to `focus_key`) for the Epic's scope — the authored-VI-file check above only applies VI-level. Resolve any VI-level ARD via `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/ard-resolution.md` (`vi: `, `epic: null`, `$SPECS_PATH`). On `status: found`, load its `AD#N` invariants to **inherit read-only**. On `status: unmerged`, **stop**, naming the returned `branch` and any `pr`. On `status: none`, proceed unchanged — there is no VI-level ARD to inherit. Extract the problem/goal/scope frame + capability themes — the raw material for grounding + the grill. --- ## Phase 3 — Architect-driven grounding (no PRs) There are no PRs at ARD time, so repos are **architect-driven**, not PR-derived: 1. **Cheap discovery.** List the top-level directories under each `$REPOS_PATH` entry (`ls`). Optionally attach each dir's one-line identity — `timeout 5 git -C remote get-url origin 2>/dev/null` (slug) or its README first heading. Do **not** deep-scan to guess relevance. 2. **Propose + ask.** From the VI/Epic themes, propose a `theme → repo` mapping against those dirs, and **ask the architect to confirm / correct / add**. For any requirement that maps to no obvious repo, **ask outright**: "which repo covers ``?" 3. **Missing repo → consolidated mount-or-descope gate:** `choices: ["Mount now & re-scan", "Ground only the confirmed-mounted set (record the rest as open questions)", "Specify an absolute path for this repo", "Cancel", "Other… (describe)"]`. 4. **Ground the confirmed set.** Spawn `code-scanner` in batches of up to 4 concurrent agents per task message on the confirmed repos (wait for each batch), scoped by the themes: → task(agent_type: "dev-workflows:code-scanner", model: ``): > "repo_path: > repo_url_slug: > capability_themes: [themes] > context: | > [3–5 sentences: the VI/Epic goal, what the ARD must ground] > search_hints: { symbols: […], paths: […], keywords: […] } > refresh: { switch_to_default_branch: [per Phase 1], pull: [per Phase 1] }" Store the per-repo as-is findings (`file:line`). Descoped/unmounted repos become Open questions. **Per-repo scanner status.** Wait for each batch. Handle each returned status before continuing: - `OK` / `PARTIAL` / `EMPTY` — use the result. `PARTIAL` and `EMPTY` are data, not failures. - `REPO_MISSING` — escalate per the `Repo missing (after resolution)` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md`. - `DIRTY_TREE` — escalate per the `Dirty working tree` rule in the same file. - `REFRESH_BLOCKED` — escalate per the `Refresh blocked` rule in the same file. - `prep.read_only: true` — not a failure. The scan ran at `prep.scanned_ref`. Escalate per the `Read-only mount — ref stale or diverged` rule **only** when `prep.ref_committed_at` is more than 14 days old or `prep.head_divergence.ahead > 0`; otherwise proceed silently and cite evidence at `prep.scanned_ref`. A repo the user skips is dropped from the confirmed set and named in the Phase 6 handoff; it never silently disappears. 5. **Documentation grounding (optional).** Run `resolve-docs-grounding create-ard` per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/docs-grounding.md`. When `docs_grounding: ON`, `dispatch-docs-grounder` with `feature_summary` = the VI/Epic goal + capability themes, `jira_key` = `` (VI-level) or `` (Epic-level), `themes` = the confirmed themes. Carry the digest into the Phase 4 grill with **grill-rank** consumption (documented analogs and building-block altitude/permissions are strong ARD grounding). When OFF, skip silently. --- ## Phase 4 — Author via grill **Interview technique (grilling — embedded; no runtime dependency).** Conduct a **relentless** interview per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/grilling-technique.md` — **rounds** rhythm (per that file's `## Rhythm`): map the design tree, ask the whole settled frontier as one numbered round, recompute from the answers, repeat to an empty frontier. Recommend each answer, explore the Phase 3 grounding findings / the VI to self-answer (fact-vs-decision), and clear the confirmation gate before writing each section. Author the ARD live against `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/ard-format.md`, applying the no-hard-wrap prose convention in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/prose-formatting.md`, at the resolved altitude: Context → Grounding findings (cite `file:line`) → Architecture decisions (`AD#N`: Binds/Prevents/Rule) → Cross-repo/component approach → Stack & invariants → Edge cases & risks → Open questions → Deferred. At Epic level, list inherited VI-level ADs read-only and never contradict them; VI level stays at invariants/frame (no per-repo detailed solutions). **Per-area split.** If (Epic level) the confirmed grounding spans separable areas in one repo (e.g. `server/` backend + `ui/` frontend), grill: `choices: ["One combined ARD (Recommended)", "One ARD per area (backend / frontend / …)", "Other… (describe)"]`. On per-area, author one `-_ARD.md` per area (each with its own `area:` frontmatter). --- ## Phase 4.5 — Structural pre-lint Before the review gate, run the deterministic checks in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/pre-lint.md` against the drafted `*_ARD.md`: the **Universal checks**, the **Jira-key collision** check (run on the ARD body below the frontmatter), and the **ARD** block (incl. that every `### [AD#N]` carries `**Binds:**` / `**Prevents:**` / `**Rule:**`). Surface every finding; inline-fix the mechanical ones (renumber a duplicate `[AD#N]`, delete a stray placeholder token); leave content gaps for the grill/author. **Advisory** — never blocks; proceed to Phase 5 once findings are surfaced. `ard-reviewer` remains the gate. ## Phase 5 — Review gate Dispatch `ard-reviewer` (Opus, caller-pinned; recorded as `review_model`): → task(agent_type: "dev-workflows:ard-reviewer", model: ``): > "Review the ARD: > > ARD path: [absolute path to the *_ARD.md] > Scope: [vi | epic]" On `BLOCK`, fix the BLOCKER findings inline (the orchestrator/grill edits the ARD — no delegated writer) and re-review **once**; if still `BLOCK`, escalate per the `Review verdict BLOCK` rule in `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/escalation-rules.md`. `PASS` / `PASS WITH RECOMMENDATIONS` → proceed. Cap: one fix cycle + one re-review. (For a per-area split, review each area ARD.) --- ## Phase 6 — Handoff Write the ARD file(s) into the feature folder. Then **offer** (commit-when-asked — never automatic), presenting `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §4.3's choice array verbatim: `choices: ["Branch + commit + push + open PR to main (Recommended)", "Just write the files — I'll handle git (the next phase will stop until this is on main)", "Cancel"]`. On the first choice, execute `handoff-to-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §2) with `prefix: ard`; `feature_folder` as resolved in Phase 0 (the VI dir for a VI-level ARD, the Epic subfolder for an Epic-level ARD — §2.2 derives `ard/-` or `ard/-` from it, matching today's branch names); `deliverable_paths` = the ARD file(s); `title: Add architecture requirements document`; and `body_facts` = the ARD scope (VI/Epic, any per-area split), the grounded/descoped repos, the `AD#N` count, the open-question count, and the `ard-reviewer` verdict. Emit its §4.1 outcome line in the Final report. --- ## Phase 7 — Next-step offer (adaptive) - **VI-level ARD:** if the VI has 0 Epics → `choices: ["Hand to a Product Engineer — epics: (then create them in Jira + re-import) (PE) (Recommended)", "Author a VI-level spec — specify: (PE)", "Stop here", "Other… (describe)"]`; else offer `specify: ` (PE). *(No `design:` — no Epics yet.)* Either way, `specify:` won't treat this ARD as available until the pull request above is merged — until then it architects without it, same as if none existed. - **Epic-level ARD:** `choices: ["Author the spec — specify: (PE) (Recommended)", "Hand to Dev — design: (Dev)", "Stop here", "Other… (describe)"]`. **Epic fan-out** — repeat this ARD for a sibling Epic: `create-ard: `. Both `specify:` and `design:` wait the same way — this ARD is invisible to them until its pull request above is merged. Guidance only — never auto-invokes another command. Per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/next-phase-offer.md`. ### Context hygiene The resume pointer is written in the terminal maintenance phase (Phase 8), per `session-hygiene.md` §1. The next step hands off from PA to PE/Dev, so: - **Handing to PE (`epics: ` / `specify: `) or Dev (`design: `), even yourself?** → run **`/clear`** for a clean slate; the ARD is on disk. - Continuing to draft more ARD areas yourself right now? → **`/compact`** is fine. - Consider **`/rename --pa`** so you can find this session later. Guidance only — see `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md`. --- ## Phase 8 — Session maintenance & feedback Terminal phase — runs after Phase 7, NEVER interrupts an earlier phase. **Capture-at-block invariant.** If an EARLIER phase **halts on a plugin / skill / command / reference gap**, `emit-block` (per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/feedback-emission.md`) at that halt **before** escalating. NEVER `emit-block` for an environment / user halt (unset `$SPECS_PATH`, missing key, no-ARD-needed, unmounted-repo descope, cancellation) or a review BLOCK. **Session-hygiene invariant.** End Phase 7 with a `### Context hygiene` block per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md` — prepare-first (the `resume.md` write runs later, as step 3 of this terminal phase, per `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md` §1 — this block prints the guidance only), then a PA→PE/Dev handoff suggestion (`/clear`) + `/rename --pa`. Guidance only, never auto-run. 1. **Invoke `impl-maintenance`** (agent_type: "dev-workflows:impl-maintenance", model: ``) with a compact handoff: command `create-ard:`; what was authored (ARD scope + grounded repos); key events (grounding gaps/descopes, BLOCK reviews — or 'none'); workarounds; the `ard-reviewer` verdict; test result N/A; project root = the feature folder. 2. **Persist plugin feedback (automatic).** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/feedback-emission.md` and call its `emit-auto` entry point (§6) with the report, `command: create-ard:`, the run's `jira_key`, `source`, and `plugin_version` (read from `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/.plugin/plugin.json`). Surface the persisted path (or "no plugin-facing signal — nothing persisted"). 3. **Write the resume pointer.** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/session-hygiene.md` §1 and write/overwrite `/dev-workflows/resume.md` now — after the feedback entry above, so the pointer reflects the completed run, and before the commit step below, so it is included in it. Redact per §1. Silent; the printed `### Context hygiene` guidance already appeared in the report. 4. **Commit session artifacts (terminal).** Cite `~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` and execute its `commit-artifacts` entry point (§4) inline — the LAST action of the run. It stages ONLY the §2.1 bounded artifact paths inside `$SPECS_PATH`, commits ` Add dev-workflows session artifacts (create-ard:)` with no `Co-Authored-By` trailer, and pushes to the branch this run's handoff phase created (§4.1). It NEVER touches a code repo, a docs repo, the vault, or the current working directory; NEVER force-pushes; NEVER fails the run; and skips entirely when the run carries `specs_git: blocked` (§3.3 G0), re-emitting that notice. Hold its §6 outcome line for the Final report. ADDITIVE — this phase NEVER fails the run, NEVER commits the deliverable (git for the deliverable is offered only in Phase 6; the terminal step above commits only the bounded session-artifact paths in `$SPECS_PATH`), and NEVER writes into a code/docs repo or the current working directory; no user name is ever written. --- ## Final report Report: the ARD path(s) + scope (VI/Epic, any per-area split); the grounded repos + any descoped/ungrounded ones; `AD#N` count; open-question count; the `ard-reviewer` verdict; the `Phase handoff:` outcome line from `handoff-to-main` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/phase-handoff.md` §4.1); resolved model routing (+ any Opus gate/degradation); the feedback path; the `Specs repo:` outcome line from `commit-artifacts` (`~/.copilot/installed-plugins/ihudak-copilot-plugins/dev-workflows/skills/_shared/specs-repo-git.md` §6), with any guard notice repeated in full; and the adaptive next-step recommendation.