Decouple cross-workflow artifact dependencies and publish clarifications

AGENTS.md

@@ -85,6 +85,7 @@ Critical for symlink resolution:
 4. **No auto-advance in attended mode**: Workflows wait for user input between phases unless an explicit unattended mode is documented for that workflow
 5. **Artifact persistence**: All significant outputs saved to `.artifacts/{workflow-name}/{context}/`
 6. **Read-only reviews**: skill-reviewer never modifies target skill files during review
+7. **Artifact isolation**: `.artifacts/{workflow-name}/` is each workflow's private state. Other workflows must never read from or write to another workflow's artifact directory. The shared interfaces between workflows are: Jira (canonical source for issue data), published docs repo files (PRDs, designs, testplans), and workspace-level config at `.artifacts/config.json`
 
 ## Workflow Versioning
 

design/README.md

@@ -45,7 +45,7 @@ graph TD
 
 ```text
 /ingest EDM-2324
-  → reads PRD from .artifacts/prd/EDM-2324/03-prd.md
+  → finds and reads PRD from the docs repo
   → explores affected codebase areas
   → writes .artifacts/design/EDM-2324/01-context.md
 

design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: design
-version: 0.7.1
+version: 0.8.0
 description: >-
   Design-and-decompose workflow that takes a PRD, researches the problem space,
   drafts a technical design document, decomposes work into Jira-ready epics and

design/skills/controller.md

@@ -66,12 +66,12 @@ the source repo (this directory should be gitignored in the source repo):
 
 ### Docs repo configuration
 
-The docs repo location is stored in `.artifacts/prd/config.json` (shared
-across all workflows for this source repo). This config is created by the
-PRD workflow's `/publish` phase the first time it runs.
+The docs repo location is stored in `.artifacts/config.json` (workspace-level
+config shared across all workflows for this source repo). This config is
+created by whichever workflow's `/publish` or `/ingest` phase runs first.
 
-If the config doesn't exist when `/publish` is invoked, the design workflow
-creates it following the same format:
+If the config doesn't exist when a phase needs it, the workflow prompts for
+the docs repo location and creates it:
 
 ```json
 {

design/skills/decompose.md

@@ -34,8 +34,7 @@ Read these files:
 1. `.artifacts/design/{issue-key}/03-design.md` (design document)
 2. `.artifacts/design/{issue-key}/01-context.md` (architectural context)
 3. `.artifacts/design/{issue-key}/02-research.md` (if exists — research findings and integration constraints)
-4. The PRD — use the path recorded in `01-context.md`'s PRD Summary section,
-   falling back to `.artifacts/prd/{issue-key}/03-prd.md`
+4. The PRD — use the path recorded in `01-context.md`'s PRD Summary section
 
 If the design document doesn't exist, tell the user that `/draft` should be
 run first.
@@ -350,13 +349,12 @@ renumbering existing ones.
 
 After sizing all epics, verify plausibility:
 
-1. Read the Feature's Size from `.artifacts/prd/{issue-key}/01-requirements.md`
-   (the Size field captured during PRD ingest) or from
-   `.artifacts/sizing/{issue-key}/02-assessment.md` (if the sizing
-   workflow was run in single-Feature mode). If neither exists, skip this
-   check. Note: batch-mode sizing stores assessments under a version slug
-   (e.g., `.artifacts/sizing/1-3-0/`), not per-Feature — batch assessments
-   are not automatically found by this lookup.
+1. Read the Feature's Size from the Jira Feature issue (`{issue-key}`).
+   Check the Size field (or Story Points, if Size is not set). If the
+   Jira lookup fails (authentication error, network failure, issue not
+   found), stop and report the error — do not skip silently. Skip this
+   check only if the issue was retrieved successfully and neither field
+   is set.
 
 2. Verify that the epic sizes are collectively plausible given the
    Feature's overall size.
@@ -684,8 +682,7 @@ format, and severity definitions.
 subagent for independence. Load it with:
 
 - The decomposition review protocol (`../decomposition-review.md`)
-- The PRD (use the path from `01-context.md`'s PRD Summary, falling back to
-  `.artifacts/prd/{issue-key}/03-prd.md`)
+- The PRD (use the path from `01-context.md`'s PRD Summary section)
 - All decomposition artifacts: `04-epics.md`, all
   `05-stories/epic-{N}-{slug}.md` files, all
   `05-stories/epic-{N}/story-{NN}-{slug}.md` files, `06-coverage.md`,

design/skills/draft.md

@@ -38,9 +38,9 @@ with `WORKFLOW=design`, `TEMPLATE_FILE=design.md`.
 Read these files in order:
 1. `.artifacts/design/{issue-key}/01-context.md` (architectural context)
 2. `.artifacts/design/{issue-key}/02-research.md` (if exists — design research findings)
-3. The PRD — use the path recorded in `01-context.md`'s PRD Summary section.
-   If not recorded there, fall back to `.artifacts/prd/{issue-key}/03-prd.md`
-4. `.artifacts/prd/{issue-key}/02-clarifications.md` (if exists — for locked decisions)
+3. The PRD — use the path recorded in `01-context.md`'s PRD Summary section
+4. Clarifications — use the path recorded in `01-context.md`'s PRD Summary
+   section (if it lists a clarifications path). Read for locked decisions.
 5. The design document template (from Step 1)
 6. The section guidance (from Step 1)
 
@@ -141,15 +141,15 @@ Before self-review, systematically verify that nothing was lost between
 source material and design document:
 
 1. **Requirements coverage:** Re-read the PRD (use the path from
-   `01-context.md`'s PRD Summary, falling back to
-   `.artifacts/prd/{issue-key}/03-prd.md`). For each functional
+   `01-context.md`'s PRD Summary section). For each functional
    requirement (FR-1, FR-2, ...) and non-functional requirement (NFR-1,
    NFR-2, ...), confirm it is addressed in the design document. If a
    requirement has no corresponding design element, either add it or
    note the gap in the Open Questions section with a reason.
 
-2. **Clarification incorporation:** Re-read `02-clarifications.md` (if
-   it exists). For each answered question, confirm the answer is reflected
+2. **Clarification incorporation:** Re-read the clarifications file (use
+   the path from `01-context.md`'s PRD Summary section, if one was
+   recorded). For each answered question, confirm the answer is reflected
    in the design. Pay particular attention to answers that added
    constraints or changed scope — these may affect architectural decisions
    even if they weren't recorded as formal locked decisions.

design/skills/ingest.md

@@ -56,48 +56,61 @@ for the diff in Step 6a.
 
 ### Step 3: Read the PRD
 
-Locate and read the PRD. Check in this order:
-1. `.artifacts/prd/{issue-key}/03-prd.md` (local PRD artifact from same session)
-2. Published PRD in the docs repo (see Step 3a below)
-3. A path provided by the user
+The published PRD in the docs repo is the authoritative source. Locate it
+there — do not read from `.artifacts/prd/`.
 
-If no PRD is found, tell the user and ask for the location. A PRD is the
-primary input to the design workflow.
+#### Resolve the Docs Repo
 
-Also read the clarification log if it exists:
-`.artifacts/prd/{issue-key}/02-clarifications.md`
+Read `.artifacts/config.json` for `docs_repo_path` and `docs_repo_remote`.
 
-Note any locked decisions — these are binding constraints for the design.
+**If the config exists**, validate it:
+1. Verify the path exists on the local filesystem
+2. Verify the directory is a git repository
+3. Verify the remote URL matches the configured `docs_repo_remote`
 
-### Step 3a: Locate Published PRD (Fallback)
+If any validation fails, inform the user and re-ask for the correct values.
+Resolve `~` to an absolute path before saving. Update
+`.artifacts/config.json` with the corrected values.
 
-If the local artifact (`.artifacts/prd/{issue-key}/03-prd.md`) does not
-exist — e.g., the PRD was created in a prior session, on another machine, or
-by someone else — look for the published PRD in the docs repo:
+**If the config does not exist**, ask the user for the docs repo local path
+and remote, validate them. Resolve `~` to the user's home directory so
+the stored path is absolute. Write `.artifacts/config.json`.
 
-1. Read `.artifacts/prd/config.json` to find `docs_repo_path`
-2. If config exists, read `.artifacts/prd/{issue-key}/publish-metadata.json`
-   to find `prd_file_path` (the relative path within the docs repo)
-3. Read the PRD from `{docs_repo_path}/{prd_file_path}`
+#### Find the PRD in the Docs Repo
 
-If the resolved path does not exist on disk (e.g., the docs repo is not
-cloned locally), or if no config or publish metadata exists, fall through
-to the next option in Step 3 (a path provided by the user).
+Search the docs repo for a directory whose name contains `{issue-key}`:
 
-**Note on clarification logs:** The clarification log
-(`.artifacts/prd/{issue-key}/02-clarifications.md`) is not published to
-the docs repo and only exists locally. If the PRD was created in a prior
-session and `.artifacts/` was cleaned up, locked decisions from the
-clarification log will not be available. The PRD itself should reflect all
-locked decisions in its final form, but if the user knows locked decisions
-exist that aren't captured in the PRD, ask them to provide the
-clarification log path.
+```bash
+find "{docs_repo_path}" -type d -name "*{issue-key}*"
+```
+
+Filter matches to directories that contain a `prd.md` file.
+
+If exactly one matching directory contains `prd.md` (e.g.,
+`v2.1/delta-updates-EDM-4867/prd.md`), read it.
+
+If multiple matching directories contain `prd.md`, present them to the
+user and ask which one contains the current PRD.
+
+If no match is found (or no matches contain `prd.md`), ask the user for
+the path to the PRD. Verify that the file exists and is readable, then
+read it before continuing.
+
+#### Read Clarifications
+
+If `clarifications.md` exists in the directory containing the resolved PRD,
+read it. Note any locked decisions — these are binding constraints for the
+design.
+
+If no clarifications file exists, the PRD itself should reflect all locked
+decisions in its final form.
+
+#### Record the Resolved Paths
 
-Once the PRD is found, record its resolved path in
+Record the resolved PRD path (and clarifications path, if found) in
 `.artifacts/design/{issue-key}/01-context.md` (in the PRD Summary section)
-so that downstream phases (`/draft`, `/research`, `/decompose`) can read it directly from
-the authoritative location rather than relying on a local copy that could
-diverge.
+so that downstream phases (`/draft`, `/research`, `/decompose`) can read
+them directly without repeating the lookup.
 
 ### Step 4: Read Project Configuration
 
@@ -156,6 +169,7 @@ If this is a first invocation, write
 - **Feature:** {title}
 - **Jira:** {issue-key}
 - **PRD:** {resolved PRD path}
+- **Clarifications:** {resolved clarifications path, or "None published"}
 
 ### Key Requirements
 

design/skills/publish.md

@@ -31,7 +31,7 @@ If the file doesn't exist, tell the user that `/draft` should be run first.
 
 ### Step 2: Resolve Docs Repo
 
-Check for an existing docs repo configuration at `.artifacts/prd/config.json`.
+Check for an existing docs repo configuration at `.artifacts/config.json`.
 
 **If the config exists**, read it and validate:
 
@@ -40,7 +40,8 @@ Check for an existing docs repo configuration at `.artifacts/prd/config.json`.
 3. Verify the remote URL matches the configured `docs_repo_remote`
 
 If any validation fails, inform the user what failed and re-ask for the
-correct values.
+correct values. Resolve `~` to an absolute path before saving. Update
+`.artifacts/config.json` with the corrected values.
 
 **If the config does not exist**, ask the user:
 
@@ -49,14 +50,9 @@ correct values.
 - **Docs repo remote:** Run `git -C "{docs_repo_path}" remote get-url origin`
   and confirm the result with the user before proceeding
 
-Validate the path and remote, then save the config:
-
-```bash
-mkdir -p .artifacts/prd
-```
-
-Write `.artifacts/prd/config.json` with the validated `docs_repo_path` and
-`docs_repo_remote`.
+Validate the path and remote. Resolve `~` to the user's home directory
+so the stored path is absolute. Write `.artifacts/config.json` with the
+validated `docs_repo_path` and `docs_repo_remote`.
 
 ### Step 3: Pre-Flight Checks
 
@@ -86,19 +82,30 @@ Provenance at publish time:
 - Only if the user explicitly declines provenance, pass `ALLOW_MISSING=yes` to strip
   the footer and record `provenance_kind: declined` (no human-readable block).
 
-Check for PRD publish metadata at
-`.artifacts/prd/{issue-key}/publish-metadata.json`. If it exists, read
-the `release` and `feature` values and propose them as defaults below.
+Search the docs repo for a published PRD directory containing
+`{issue-key}`:
+
+```bash
+find "{docs_repo_path}" -type d -name "*{issue-key}*"
+```
+
+Filter matches to directories that contain a `prd.md` file.
+
+If exactly one matching directory contains `prd.md` (e.g.,
+`v2.1/delta-updates-EDM-4867`), parse the path to extract `release` (first
+path component under the docs repo root) and `feature` (second component)
+and propose them as defaults below. If multiple matches contain `prd.md`,
+present them to the user and ask which one to use.
 
 Confirm with the user:
 - **Base branch:** Which branch should the PR target? (usually `main`)
 - **Release:** Which release is this for? (e.g., `v2.1`, `2026-Q2`).
-  If PRD publish metadata exists, propose its `release` value as the
-  default. Otherwise, if the Jira issue has a fix version, suggest that.
+  If a PRD directory was found, propose the extracted `release` value as
+  the default. Otherwise, if the Jira issue has a fix version, suggest that.
 - **Feature:** A short, lowercase, hyphenated slug for the feature
   directory, with the Jira issue key appended (e.g., `port-mappings-EDM-1471`).
-  If PRD publish metadata exists, propose its `feature` value as the
-  default. Otherwise, suggest a slug derived from the Jira issue summary
+  If a PRD directory was found, propose the extracted `feature` value as
+  the default. Otherwise, suggest a slug derived from the Jira issue summary
   with the issue key appended. Ask for **just the slug**, not a full path.
 - **Branch name:** Propose `design/{issue-key}` and let the user override.
   Use the confirmed value as `{branch-name}` in all subsequent steps.
@@ -302,7 +309,7 @@ Present:
 
 ## Output
 
-- `.artifacts/prd/config.json` (created if it didn't exist)
+- `.artifacts/config.json` (workspace-level config, created if it didn't exist)
 - `.artifacts/design/{issue-key}/publish-metadata.json`
 - Design document committed and pushed to feature branch in the docs repo
 - Draft PR created against the docs repo

design/skills/research.md

@@ -66,9 +66,9 @@ If `01-context.md` does not exist, tell the user that `/ingest` should be
 run first and stop.
 
 Also read the PRD for the full requirements — use the path recorded in
-`01-context.md`'s PRD Summary section, falling back to
-`.artifacts/prd/{issue-key}/03-prd.md`. Read
-`.artifacts/prd/{issue-key}/02-clarifications.md` for any locked decisions.
+`01-context.md`'s PRD Summary section. Read the clarifications file (use
+the path from `01-context.md`'s PRD Summary section, if one was recorded)
+for any locked decisions.
 
 #### Step 1a: Check for Prior Research (Re-invocation)
 

design/skills/respond.md

@@ -34,7 +34,7 @@ with `WORKFLOW=design`, `TEMPLATE_FILE=design.md`. Per that recipe's
 "Using the Resolved Files" guidance, treat the section-number examples
 below (e.g., "§4.1") as illustrations of the built-in template only.
 
-Read `.artifacts/prd/config.json` to get the docs repo path and
+Read `.artifacts/config.json` to get the docs repo path and
 `.artifacts/design/{issue-key}/publish-metadata.json` to get the PR
 number, file path, and `{branch-name}` (from the `branch` field). If
 either file doesn't exist, tell the user that
@@ -130,10 +130,12 @@ since the last workflow phase, read and follow
 `ISSUE_KEY={issue-key}` before applying changes.
 
 **Check locked decisions:** Before applying any design document change —
-whether a direct edit or an open question resolution — read the "Locked
-Decisions" section of `.artifacts/prd/{issue-key}/02-clarifications.md`
-(if it exists). If a requested change contradicts a locked decision, flag
-the conflict rather than applying the change.
+whether a direct edit or an open question resolution — read the locked
+decisions from the clarifications file (use the path from
+`.artifacts/design/{issue-key}/01-context.md`'s PRD Summary section, if
+one was recorded). Locked decisions appear as `#### Decision (D{N})`
+sections within Q&A entries. If a requested change contradicts a locked
+decision, flag the conflict rather than applying the change.
 
 #### Resolving open questions
 

design/skills/revise.md

@@ -37,7 +37,8 @@ below (e.g., "Section 4.3") as illustrations of the built-in template only.
 Determine which artifacts exist and read them:
 - `.artifacts/design/{issue-key}/01-context.md` (requirements context with FR/NFR IDs)
 - `.artifacts/design/{issue-key}/02-research.md` (if exists — research findings)
-- `.artifacts/prd/{issue-key}/02-clarifications.md` (if exists — locked decisions)
+- Clarifications — use the path from `01-context.md`'s PRD Summary section
+  (if one was recorded) — for locked decisions
 - `.artifacts/design/{issue-key}/03-design.md` (design document)
 - `.artifacts/design/{issue-key}/04-epics.md` (epic metadata, if exists)
 - `.artifacts/design/{issue-key}/05-stories/` (epic and story files, if exist)
@@ -110,8 +111,8 @@ After applying changes, verify:
 - Do the architectural decisions still support all PRD requirements?
 - Does the data model still align with the API changes?
 - Are alternatives still relevant, or do they need updating?
-- Do any changes contradict a locked decision from `02-clarifications.md`?
-  If so, flag the conflict — locked decisions are binding.
+- Do any changes contradict a locked decision from the clarifications file
+  (loaded in Step 1)? If so, flag the conflict — locked decisions are binding.
 - If `02-research.md` exists, do any changes contradict research findings
   or integration constraints? If the revision switches to an approach the
   research evaluated unfavorably, flag the conflict and explain the tradeoff.
@@ -163,7 +164,7 @@ If `03-design.md` was updated, read and follow
 
 If the design document was published, also update the docs repo copy.
 Check for `.artifacts/design/{issue-key}/publish-metadata.json` and
-`.artifacts/prd/config.json`. If either file does not exist, skip the
+`.artifacts/config.json`. If either file does not exist, skip the
 docs repo update steps — the design has not been published yet.
 
 If both exist:

design/skills/sync.md

@@ -637,7 +637,7 @@ published copy's Story field with Jira keys so downstream workflows
 can filter by Jira key.
 
 **Skip this step entirely if any of these are true:**
-- `.artifacts/prd/config.json` does not exist
+- `.artifacts/config.json` does not exist
 - `.artifacts/design/{issue-key}/publish-metadata.json` does not exist
 - `publish-metadata.json` does not contain a `testplan_file_path` field
 - `.artifacts/design/{issue-key}/07-testplan.md` does not exist
@@ -658,7 +658,7 @@ can filter by Jira key.
 
 **Write the resolved testplan to the docs repo:**
 
-Read `.artifacts/prd/config.json` to get the docs repo path. Read
+Read `.artifacts/config.json` to get the docs repo path. Read
 `publish-metadata.json` to get the `testplan_file_path` and the
 `branch` field. If `branch` is missing or empty, stop and report the
 error — publish-metadata.json is incomplete.

e2e/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: e2e
-version: 0.4.0
+version: 0.5.0
 description: >-
   Story-to-e2e-test workflow that takes a Jira [QE] Story, discovers the
   project's e2e testing infrastructure, plans test scenarios, writes e2e