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: <VI-KEY> → a VI-level ARD.
• create-ard: <VI-KEY> <Epic-KEY> → 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 <VI> = jira_key, <EPIC> = 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/<VI>-<vslug>/; Epic-level → specifications/<VI>-<vslug>/<EPIC>-<eslug>/. 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/<VI>-<vslug>/ — resolve its actual name on the ref first: git -C "$SPECS_PATH" ls-tree --name-only "origin/<default>" "specifications/<VI>-<vslug>/" filtered to <VI>_*.md, falling back to the derived <VI>_<vslug>.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 <default> for <VI> — architecting from the Jira export at <path>. 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 <root> (retrieval: …) or OFF (<reason>) — 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:

model_routing:
  classification: MODERATE | SIGNIFICANT | HIGH-RISK   # architecture; SIGNIFICANT common for cross-repo VIs
  reason: <one-line>
  current_model: <the model this orchestrator/grill is running under>
  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: <true if a §2 Opus model resolved, else false>
  notes: <any §2/§2.1 fallback or degradation>

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/<VI>-<vslug>/ — glob <VI>_*.md and use the file whose frontmatter is issue_type: ValueIncrement (canonical <VI>_<slug>.md) when present (authored source); else dispatch jira-reader to read it from the export:

→ task(agent_type: "dev-workflows:jira-reader", model: <detection_model — §2.1 detection chain>):

"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: <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 <dir> 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 <X>?"

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: <detection_model — §2.1 detection chain>):

   "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> (VI-level) or <EPIC> (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 <EPIC>-<area>_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_model — §2 Opus chain>):

"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/<VI>-<vslug> or ard/<EPIC>-<eslug> from it, matching today's branch names); deliverable_paths = the ARD file(s); title: <VI|EPIC> 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: <VI> (then create them in Jira + re-import) (PE) (Recommended)", "Author a VI-level spec — specify: <VI> (PE)", "Stop here", "Other… (describe)"]; else offer specify: <VI> (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: <VI> <Epic> (PE) (Recommended)", "Hand to Dev — design: <VI> <Epic> (Dev)", "Stop here", "Other… (describe)"]. Epic fan-out — repeat this ARD for a sibling Epic: create-ard: <VI> <another-Epic>. 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: <VI> / specify: <VI> <Epic>) or Dev (design: <VI> <Epic>), 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 <VI-ID>-<slug>-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 <VI-ID>-<slug>-pa. Guidance only, never auto-run.

1. Invoke impl-maintenance (agent_type: "dev-workflows:impl-maintenance", model: <detection_model — §2.1 detection chain>) 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 <VI-dir>/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 <KEY> 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.