From 07d271712fc2d073658eaad29cdff72309aaa4a4 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 6 Aug 2026 12:11:43 -0400 Subject: [PATCH 01/10] Decouple cross-workflow artifact dependencies and publish clarifications MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Enforce the principle that .artifacts/{workflow-name}/ is each workflow's private state by eliminating all cross-workflow artifact reads. - Move config.json from .artifacts/prd/config.json to .artifacts/config.json (workspace-level config, not owned by any workflow) - Design workflow reads PRD and clarifications from the docs repo instead of .artifacts/prd/ — finds PRD by searching for the issue key - Feature sizing in decompose reads from Jira directly instead of .artifacts/prd/ or .artifacts/sizing/ - Eliminate design's read of prd's publish-metadata.json — derive release/feature from the docs repo directory structure - Publish clarifications.md alongside prd.md in the docs repo so [Clarify: R1.Q2] tags reference a durable, published artifact - Restructure clarification log format for human readability: Answer, Impact, and Decision as separate headings instead of bold-inline; locked decisions inline with their Q&A entry as #### Decision (D{N}) - Document artifact isolation as constraint #7 in AGENTS.md Assisted-by: Claude Opus 4.6 (1M) --- AGENTS.md | 1 + design/README.md | 2 +- design/SKILL.md | 2 +- design/skills/controller.md | 10 +++--- design/skills/decompose.md | 16 +++------ design/skills/draft.md | 14 ++++---- design/skills/ingest.md | 63 ++++++++++++++++---------------- design/skills/publish.md | 33 +++++++++-------- design/skills/research.md | 6 ++-- design/skills/respond.md | 12 ++++--- design/skills/revise.md | 9 ++--- design/skills/sync.md | 4 +-- e2e/SKILL.md | 2 +- e2e/skills/ingest.md | 14 +++----- implement/SKILL.md | 2 +- implement/skills/ingest.md | 14 +++----- prd/GUIDE.md | 2 +- prd/SKILL.md | 2 +- prd/skills/clarify.md | 72 ++++++++++++++++++++++++++----------- prd/skills/controller.md | 4 +-- prd/skills/publish.md | 32 ++++++++++++----- prd/skills/respond.md | 11 +++--- prd/skills/revise.md | 2 +- 23 files changed, 186 insertions(+), 143 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 8b1c10e..6c360f6 100644 --- a/AGENTS.md +++ b/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 diff --git a/design/README.md b/design/README.md index f55156e..6f611e9 100644 --- a/design/README.md +++ b/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 diff --git a/design/SKILL.md b/design/SKILL.md index 91b1e65..fd4b7a0 100644 --- a/design/SKILL.md +++ b/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 diff --git a/design/skills/controller.md b/design/skills/controller.md index a2e443f..f44377b 100644 --- a/design/skills/controller.md +++ b/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 { diff --git a/design/skills/decompose.md b/design/skills/decompose.md index ca6db10..d92dbf7 100644 --- a/design/skills/decompose.md +++ b/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,9 @@ 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 neither + field is set on the Feature issue, skip this check. 2. Verify that the epic sizes are collectively plausible given the Feature's overall size. @@ -684,8 +679,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`, diff --git a/design/skills/draft.md b/design/skills/draft.md index 9af2797..0875758 100644 --- a/design/skills/draft.md +++ b/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. diff --git a/design/skills/ingest.md b/design/skills/ingest.md index ea277c2..85ff22d 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -56,48 +56,46 @@ 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. +#### 3a: 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`. If the config does not +exist, ask the user for the docs repo local path and remote, validate them, +and write `.artifacts/config.json`. -Note any locked decisions — these are binding constraints for the design. +#### 3b: Find the PRD in the Docs Repo -### Step 3a: Locate Published PRD (Fallback) +Search the docs repo for a directory whose name contains `{issue-key}`: -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: +```bash +find "{docs_repo_path}" -type d -name "*{issue-key}*" +``` + +If exactly one matching directory is found (e.g., +`v2.1/delta-updates-EDM-4867`), read `prd.md` from that directory. + +If multiple matches are found, present them to the user and ask which one +contains the current PRD. + +If no match is found, ask the user for the path to the PRD. + +#### 3c: Read Clarifications -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}` +If `clarifications.md` exists in the same docs repo directory as the PRD, +read it. Note any locked decisions — these are binding constraints for the +design. -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). +If no clarifications file exists, the PRD itself should reflect all locked +decisions in its final form. -**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. +#### 3d: 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 +154,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 diff --git a/design/skills/publish.md b/design/skills/publish.md index 1c5e52c..d160a59 100644 --- a/design/skills/publish.md +++ b/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: @@ -51,11 +51,7 @@ correct values. 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 +Write `.artifacts/config.json` with the validated `docs_repo_path` and `docs_repo_remote`. ### Step 3: Pre-Flight Checks @@ -86,19 +82,28 @@ 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}*" +``` + +If exactly one matching directory is found (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 are found, 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 +307,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 diff --git a/design/skills/research.md b/design/skills/research.md index 02c2a4a..cd2fe91 100644 --- a/design/skills/research.md +++ b/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) diff --git a/design/skills/respond.md b/design/skills/respond.md index bce59b5..65fb683 100644 --- a/design/skills/respond.md +++ b/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 diff --git a/design/skills/revise.md b/design/skills/revise.md index a51f187..03d4d7b 100644 --- a/design/skills/revise.md +++ b/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: diff --git a/design/skills/sync.md b/design/skills/sync.md index 7877c85..f1bf31c 100644 --- a/design/skills/sync.md +++ b/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. diff --git a/e2e/SKILL.md b/e2e/SKILL.md index 0f662bd..fa6a2b8 100644 --- a/e2e/SKILL.md +++ b/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 diff --git a/e2e/skills/ingest.md b/e2e/skills/ingest.md index 5874bc5..c6b64e2 100644 --- a/e2e/skills/ingest.md +++ b/e2e/skills/ingest.md @@ -98,9 +98,9 @@ design workflows. Fetch them from there. #### 5a: Resolve the Docs Repo -Check for an existing docs repo configuration at `.artifacts/prd/config.json`. -This config is project-level and shared across workflows (prd, design, -implement, e2e) — a prior workflow run may have already created it. +Check for an existing docs repo configuration at `.artifacts/config.json`. +This config is workspace-level and shared across all workflows — a prior +workflow run may have already created it. **If the config exists**, read it and validate: 1. Verify the path exists on the local filesystem @@ -115,12 +115,8 @@ If validation fails, inform the user and re-ask for the correct values. 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` (same format used by the prd and design workflows). +Write `.artifacts/config.json` with the validated `docs_repo_path` and +`docs_repo_remote` (workspace-level config shared across all workflows). #### 5b: Find the PRD and Design Document diff --git a/implement/SKILL.md b/implement/SKILL.md index 3bd0eb7..4d90980 100644 --- a/implement/SKILL.md +++ b/implement/SKILL.md @@ -1,6 +1,6 @@ --- name: implement -version: 0.5.0 +version: 0.6.0 description: >- Story-to-code workflow that takes a Jira Story, plans the implementation, writes contract-based tests and production code via TDD, validates against diff --git a/implement/skills/ingest.md b/implement/skills/ingest.md index e261a22..2056d6c 100644 --- a/implement/skills/ingest.md +++ b/implement/skills/ingest.md @@ -89,9 +89,9 @@ design workflows. Fetch them from there. #### 5a: Resolve the Docs Repo -Check for an existing docs repo configuration at `.artifacts/prd/config.json`. -This config is project-level and shared across workflows (prd, design, -implement, e2e) — a prior workflow run may have already created it. +Check for an existing docs repo configuration at `.artifacts/config.json`. +This config is workspace-level and shared across all workflows — a prior +workflow run may have already created it. **If the config exists**, read it and validate: 1. Verify the path exists on the local filesystem @@ -106,12 +106,8 @@ If validation fails, inform the user and re-ask for the correct values. 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` (same format used by the prd and design workflows). +Write `.artifacts/config.json` with the validated `docs_repo_path` and +`docs_repo_remote` (workspace-level config shared across all workflows). #### 5b: Find the PRD and Design Document diff --git a/prd/GUIDE.md b/prd/GUIDE.md index da938d6..f747da6 100644 --- a/prd/GUIDE.md +++ b/prd/GUIDE.md @@ -87,7 +87,7 @@ You can run `/prd:revise` as many times as needed. Each round updates the same a The workflow copies the PRD to a docs repository and creates a **draft** GitHub PR. It asks you to confirm the details first: base branch, release name, feature slug, and branch name. -On first use, it asks for your docs repo location and saves the configuration to `.artifacts/prd/config.json`. Subsequent PRDs reuse this configuration without asking again. +On first use, it asks for your docs repo location and saves the configuration to `.artifacts/config.json`. Subsequent runs (including other workflows like `/design`) reuse this configuration without asking again. The PR is always created as a draft. It includes a description with a link to the Jira issue, a summary of what the PRD covers, and guidance for reviewers on what to focus on. diff --git a/prd/SKILL.md b/prd/SKILL.md index 438b577..ebcf668 100644 --- a/prd/SKILL.md +++ b/prd/SKILL.md @@ -1,6 +1,6 @@ --- name: prd -version: 0.7.1 +version: 0.8.0 description: >- Requirements-to-PRD workflow that ingests requirements from Jira, clarifies ambiguities through iterative Q&A, drafts a Product Requirements Document, diff --git a/prd/skills/clarify.md b/prd/skills/clarify.md index 78aa649..0d738d1 100644 --- a/prd/skills/clarify.md +++ b/prd/skills/clarify.md @@ -99,14 +99,19 @@ deliverables exclude e2e tests." The feature still includes work that *uses* the dependency; it just doesn't *deliver* the dependency itself. When the user makes a definitive choice (e.g., "TCP only, no UDP" or -"we'll use Postgres, not SQLite"), record it as a locked decision in -the clarification log's "Locked Decisions" section. These are binding -constraints — `/draft` must reflect them exactly. Not every answer is -a locked decision; only record clear, scope-affecting choices. +"we'll use Postgres, not SQLite"), record it as a locked decision by +adding a `#### Decision (D{N})` section to that Q&A entry. These are +binding constraints — `/draft` must reflect them exactly. Not every +answer is a locked decision; only record clear, scope-affecting choices. ### Step 4: Update Clarification Log -After each round, write or update `.artifacts/prd/{issue-key}/02-clarifications.md`: +After each round, write or update `.artifacts/prd/{issue-key}/02-clarifications.md`. + +This file is published alongside the PRD in the docs repo (by `/publish`), +so it must be readable by humans — not just parseable by AI. Each field +(Answer, Impact, Decision) gets its own heading. Never collapse multiple +fields into a single paragraph. ```markdown # Clarification Log — {issue-key} @@ -119,33 +124,60 @@ After each round, write or update `.artifacts/prd/{issue-key}/02-clarifications. ## Round 1 — {topic area} -### R1.Q1: {question} -**Answer:** {user's response} -**Impact:** {how this affects the PRD} +### R1.Q1: {short title} -### R1.Q2: {question} -**Answer:** {user's response} -**Impact:** {how this affects the PRD} +{Full question with enough context to be self-contained.} -## Round 2 — {topic area} +#### Answer + +{User's response.} + +#### Impact + +{How this affects the PRD.} + +#### Decision (D1) + +{Decision text — only present when this Q&A produced a locked decision. +Omit this section entirely for questions that did not result in a locked +decision.} + +--- + +### R1.Q2: {short title} -### R2.Q1: {question} -**Answer:** {user's response} -**Impact:** {how this affects the PRD} +{question} -## Locked Decisions +#### Answer -Decisions the user made definitively during clarification. These are -binding constraints for `/draft` — the PRD must reflect them exactly. +{answer} -- **D1:** {decision} `[Clarify: R{N}.Q{M}]` -- **D2:** {decision} `[Clarify: R{N}.Q{M}]` +#### Impact + +{impact} + +--- + +## Round 2 — {topic area} + +### R2.Q1: {short title} + +... + +--- ## Remaining Gaps - {Any gaps that are still unresolved, if applicable} ``` +**Formatting rules:** +- Answer, Impact, and Decision are each `####` headings, never bold-inline +- Use `---` horizontal rules between Q&A entries for visual separation +- Decision sections carry the D-number parenthetically: `#### Decision (D3)` +- Omit the Decision section for questions that did not produce a locked decision +- D-numbers are assigned sequentially across all rounds (D1, D2, ... D{N}) + ### Step 5: Check Exit Criteria After each round, evaluate whether clarification is sufficient: diff --git a/prd/skills/controller.md b/prd/skills/controller.md index 1d31afd..c9ec3a2 100644 --- a/prd/skills/controller.md +++ b/prd/skills/controller.md @@ -51,8 +51,8 @@ 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 PRDs for this source repo): +The docs repo location is stored in `.artifacts/config.json` (shared +across all workflows for this source repo): ```json { diff --git a/prd/skills/publish.md b/prd/skills/publish.md index 8c7def8..71054fe 100644 --- a/prd/skills/publish.md +++ b/prd/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: @@ -51,11 +51,7 @@ correct values. 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 +Write `.artifacts/config.json` with the validated `docs_repo_path` and `docs_repo_remote`. ### Step 3: Pre-Flight Checks @@ -154,6 +150,25 @@ Read and follow `../../_shared/recipes/render-provenance-footer.md` with git -C "{docs_repo_path}" add "{release}/{feature}/prd.md" ``` +If `.artifacts/prd/{issue-key}/02-clarifications.md` exists, publish it +alongside the PRD: + +```bash +cp ".artifacts/prd/{issue-key}/02-clarifications.md" "{docs_repo_path}/{release}/{feature}/clarifications.md" +``` + +```bash +git -C "{docs_repo_path}" add "{release}/{feature}/clarifications.md" +``` + +If clarifications were published, use: + +```bash +git -C "{docs_repo_path}" commit -m "Add PRD and clarifications for {issue-key}: {title}" +``` + +Otherwise: + ```bash git -C "{docs_repo_path}" commit -m "Add PRD for {issue-key}: {title}" ``` @@ -187,7 +202,7 @@ Prepare the PR description and save it to `.artifacts/prd/{issue-key}/04-pr-desc - Approve when the PRD accurately reflects the agreed requirements ``` -Determine `{owner}/{repo}` from the `docs_repo_remote` in `.artifacts/prd/config.json` +Determine `{owner}/{repo}` from the `docs_repo_remote` in `.artifacts/config.json` (e.g., `git@github.com:org/planning-docs.git` → `org/planning-docs`), then create the draft PR. If `{issue-key}` is a Jira key, prefix the title with it (`{issue-key}: PRD - {title}`); otherwise use `PRD: {title}`. @@ -221,9 +236,10 @@ Present: ## Output -- `.artifacts/prd/config.json` (created on first run, reused on subsequent runs) +- `.artifacts/config.json` (workspace-level config, created if it didn't exist) - `.artifacts/prd/{issue-key}/publish-metadata.json` - PRD committed and pushed to feature branch in the docs repo +- Clarifications committed alongside PRD (if `02-clarifications.md` exists) - Draft PR created against the docs repo - `.artifacts/prd/{issue-key}/04-pr-description.md` diff --git a/prd/skills/respond.md b/prd/skills/respond.md index 8e9541d..026d279 100644 --- a/prd/skills/respond.md +++ b/prd/skills/respond.md @@ -34,7 +34,7 @@ with `WORKFLOW=prd`, `TEMPLATE_FILE=prd.md`. Per that recipe's "Using the Resolved Files" guidance, treat the examples below (e.g., "NFR-3", "non-goal") 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/prd/{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 @@ -122,9 +122,10 @@ last workflow phase, read and follow `ISSUE_KEY={issue-key}` before applying changes. **Check locked decisions:** Before applying any PRD 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 +direct edit or an open question resolution — read the locked decisions +from `.artifacts/prd/{issue-key}/02-clarifications.md` (if it exists). +Locked decisions appear as `#### Decision (D{N})` sections within Q&A +entries. If a requested change contradicts a locked decision, flag the conflict to the user rather than applying the change — locked decisions are binding and cannot be overridden without explicit user approval. @@ -195,7 +196,7 @@ runs don't re-ask, then proceed with the docs repo update. If they cannot provide it, skip the docs repo update. Copy the updated artifact to the docs repo and commit. All git operations use -the docs repo path from `.artifacts/prd/config.json`. +the docs repo path from `.artifacts/config.json`. Fetch the latest state from the remote and verify the working tree is clean: diff --git a/prd/skills/revise.md b/prd/skills/revise.md index 2155848..94694be 100644 --- a/prd/skills/revise.md +++ b/prd/skills/revise.md @@ -78,7 +78,7 @@ Read and follow `../../_shared/recipes/capture-provenance-event.md` with `WORKFLOW=prd`, `ISSUE_KEY={issue-key}`, `PHASE=revise`, `AUTHORING_MODE=skill`. -Read `.artifacts/prd/config.json` to get the docs repo path and +Read `.artifacts/config.json` to get the docs repo path and `.artifacts/prd/{issue-key}/publish-metadata.json` to get `{prd-file-path}` and `{branch-name}` (from the `branch` field). If either file doesn't exist, skip the remaining steps — the PRD hasn't been From 54846274a2e347169b08440db02faa1d62afa842 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 6 Aug 2026 13:45:02 -0400 Subject: [PATCH 02/10] Address PR review feedback: validate config, Jira errors, and prd.md presence MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - design/skills/ingest.md: Validate existing .artifacts/config.json before use (path exists, is git repo, remote matches) — same checks as publish - design/skills/ingest.md: Filter find matches to directories containing prd.md before using them - design/skills/decompose.md: Distinguish Jira lookup failures from unset fields in sizing check — report errors, only skip on successful read with no size set Assisted-by: Claude Opus 4.6 (1M) --- design/skills/decompose.md | 7 +++++-- design/skills/ingest.md | 27 +++++++++++++++++++-------- 2 files changed, 24 insertions(+), 10 deletions(-) diff --git a/design/skills/decompose.md b/design/skills/decompose.md index d92dbf7..643c787 100644 --- a/design/skills/decompose.md +++ b/design/skills/decompose.md @@ -350,8 +350,11 @@ renumbering existing ones. After sizing all epics, verify plausibility: 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 neither - field is set on the Feature issue, skip this check. + 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. diff --git a/design/skills/ingest.md b/design/skills/ingest.md index 85ff22d..d636963 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -61,9 +61,17 @@ there — do not read from `.artifacts/prd/`. #### 3a: Resolve the Docs Repo -Read `.artifacts/config.json` for `docs_repo_path`. If the config does not -exist, ask the user for the docs repo local path and remote, validate them, -and write `.artifacts/config.json`. +Read `.artifacts/config.json` for `docs_repo_path` and `docs_repo_remote`. + +**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` + +If any validation fails, inform the user and re-ask for the correct values. + +**If the config does not exist**, ask the user for the docs repo local path +and remote, validate them, and write `.artifacts/config.json`. #### 3b: Find the PRD in the Docs Repo @@ -73,13 +81,16 @@ Search the docs repo for a directory whose name contains `{issue-key}`: find "{docs_repo_path}" -type d -name "*{issue-key}*" ``` -If exactly one matching directory is found (e.g., -`v2.1/delta-updates-EDM-4867`), read `prd.md` from that directory. +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 matches are found, present them to the user and ask which one -contains the current PRD. +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, ask the user for the path to the PRD. +If no match is found (or no matches contain `prd.md`), ask the user for +the path to the PRD. #### 3c: Read Clarifications From ade24c38626f358a753f430ff6e587244ac7b912 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 6 Aug 2026 14:15:53 -0400 Subject: [PATCH 03/10] Fix stale config creation docs in prd controller prd/skills/controller.md still said config was created by /publish only. Updated to match design controller: created by whichever workflow's /publish or /ingest phase runs first. Assisted-by: Claude Opus 4.6 (1M) --- prd/skills/controller.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/prd/skills/controller.md b/prd/skills/controller.md index c9ec3a2..56c1394 100644 --- a/prd/skills/controller.md +++ b/prd/skills/controller.md @@ -61,9 +61,10 @@ across all workflows for this source repo): } ``` -This config is created by `/publish` the first time it runs. On subsequent -runs, `/publish` validates that the path exists and the remote matches. If -validation fails, it re-asks the user. +This config is created by whichever workflow's `/publish` or `/ingest` +phase runs first. On subsequent runs, phases that need the config validate +that the path exists and the remote matches. If validation fails, they +re-ask the user. `/revise` and `/respond` also read this config when they need to update the published copy in the docs repo. From 728537a5890f8c456bf5703505dc94521683669b Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 6 Aug 2026 14:20:51 -0400 Subject: [PATCH 04/10] Persist corrected config after validation failure in design ingest When existing .artifacts/config.json fails validation, the re-asked values are now written back to config.json so downstream workflows don't re-encounter the stale values. Assisted-by: Claude Opus 4.6 (1M) --- design/skills/ingest.md | 1 + 1 file changed, 1 insertion(+) diff --git a/design/skills/ingest.md b/design/skills/ingest.md index d636963..d2af321 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -69,6 +69,7 @@ Read `.artifacts/config.json` for `docs_repo_path` and `docs_repo_remote`. 3. Verify the remote URL matches the configured `docs_repo_remote` If any validation fails, inform the user and re-ask for the correct values. +Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user for the docs repo local path and remote, validate them, and write `.artifacts/config.json`. From 5bcc40c69239cc6cddddd7d4bd605bc5c84d2be8 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 6 Aug 2026 15:27:54 -0400 Subject: [PATCH 05/10] Remove lettered sub-step labels from design ingest Step 3 3a/3b/3c/3d were sequential operations, not conditional branches. Converted to unnumbered headings under Step 3 per the project convention that lettered sub-steps are reserved for conditional branches only. Assisted-by: Claude Opus 4.6 (1M) --- design/skills/ingest.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/design/skills/ingest.md b/design/skills/ingest.md index d2af321..061696b 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -59,7 +59,7 @@ for the diff in Step 6a. The published PRD in the docs repo is the authoritative source. Locate it there — do not read from `.artifacts/prd/`. -#### 3a: Resolve the Docs Repo +#### Resolve the Docs Repo Read `.artifacts/config.json` for `docs_repo_path` and `docs_repo_remote`. @@ -74,7 +74,7 @@ Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user for the docs repo local path and remote, validate them, and write `.artifacts/config.json`. -#### 3b: Find the PRD in the Docs Repo +#### Find the PRD in the Docs Repo Search the docs repo for a directory whose name contains `{issue-key}`: @@ -93,7 +93,7 @@ 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. -#### 3c: Read Clarifications +#### Read Clarifications If `clarifications.md` exists in the same docs repo directory as the PRD, read it. Note any locked decisions — these are binding constraints for the @@ -102,7 +102,7 @@ design. If no clarifications file exists, the PRD itself should reflect all locked decisions in its final form. -#### 3d: Record the Resolved Paths +#### Record the Resolved Paths Record the resolved PRD path (and clarifications path, if found) in `.artifacts/design/{issue-key}/01-context.md` (in the PRD Summary section) From 3d461ae09bcd788c7ec3a87928f023eb3cdd6797 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Thu, 6 Aug 2026 15:36:00 -0400 Subject: [PATCH 06/10] Validate fallback PRD path and resolve clarifications from PRD directory MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Verify user-provided PRD path exists and is readable before recording - Look for clarifications.md in the directory containing the resolved PRD, not specifically the docs repo directory — supports fallback paths outside the docs repo Assisted-by: Claude Opus 4.6 (1M) --- design/skills/ingest.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/design/skills/ingest.md b/design/skills/ingest.md index 061696b..f7cb1c9 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -91,11 +91,12 @@ 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. +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 same docs repo directory as the PRD, +If `clarifications.md` exists in the directory containing the resolved PRD, read it. Note any locked decisions — these are binding constraints for the design. From 6f44d5c40e9b5485cb8ce4d1cfed6c87ef4a8ed1 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Fri, 7 Aug 2026 09:36:33 -0400 Subject: [PATCH 07/10] Write corrected config values back in all validation paths design/skills/ingest.md had the write-back but the same validate-and-re-ask pattern in design/publish, prd/publish, implement/ingest, and e2e/ingest did not persist corrected values. A stale config would cause repeated re-prompts on every invocation from any workflow. Assisted-by: Claude Opus 4.6 (1M) --- design/skills/publish.md | 2 +- e2e/skills/ingest.md | 1 + implement/skills/ingest.md | 1 + prd/skills/publish.md | 2 +- 4 files changed, 4 insertions(+), 2 deletions(-) diff --git a/design/skills/publish.md b/design/skills/publish.md index d160a59..f8702ef 100644 --- a/design/skills/publish.md +++ b/design/skills/publish.md @@ -40,7 +40,7 @@ Check for an existing docs repo configuration at `.artifacts/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. Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user: diff --git a/e2e/skills/ingest.md b/e2e/skills/ingest.md index c6b64e2..2062c8a 100644 --- a/e2e/skills/ingest.md +++ b/e2e/skills/ingest.md @@ -107,6 +107,7 @@ workflow run may have already created it. 2. Verify the directory is a git repository If validation fails, inform the user and re-ask for the correct values. +Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user: - **Docs repo local path:** Where is the planning docs repo checked out? diff --git a/implement/skills/ingest.md b/implement/skills/ingest.md index 2056d6c..73598f6 100644 --- a/implement/skills/ingest.md +++ b/implement/skills/ingest.md @@ -98,6 +98,7 @@ workflow run may have already created it. 2. Verify the directory is a git repository If validation fails, inform the user and re-ask for the correct values. +Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user: - **Docs repo local path:** Where is the planning docs repo checked out? diff --git a/prd/skills/publish.md b/prd/skills/publish.md index 71054fe..d3c494c 100644 --- a/prd/skills/publish.md +++ b/prd/skills/publish.md @@ -40,7 +40,7 @@ Check for an existing docs repo configuration at `.artifacts/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. Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user: From 8f33faba8fcebdd1b2669520cd24f8353cbad9bd Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Fri, 7 Aug 2026 09:46:53 -0400 Subject: [PATCH 08/10] Filter publish find by prd.md presence; add remote validation to e2e/implement - design/skills/publish.md: Filter find matches to directories containing prd.md before extracting release/feature defaults (matching ingest.md) - e2e/skills/ingest.md: Add remote URL validation to config check (matching prd/design publish validation) - implement/skills/ingest.md: Same remote URL validation addition Assisted-by: Claude Opus 4.6 (1M) --- design/skills/publish.md | 8 +++++--- e2e/skills/ingest.md | 3 ++- implement/skills/ingest.md | 3 ++- 3 files changed, 9 insertions(+), 5 deletions(-) diff --git a/design/skills/publish.md b/design/skills/publish.md index f8702ef..66d3340 100644 --- a/design/skills/publish.md +++ b/design/skills/publish.md @@ -89,11 +89,13 @@ Search the docs repo for a published PRD directory containing find "{docs_repo_path}" -type d -name "*{issue-key}*" ``` -If exactly one matching directory is found (e.g., +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 are found, present -them to the user and ask which one to use. +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`) diff --git a/e2e/skills/ingest.md b/e2e/skills/ingest.md index 2062c8a..3377cbf 100644 --- a/e2e/skills/ingest.md +++ b/e2e/skills/ingest.md @@ -105,8 +105,9 @@ workflow run may have already created it. **If the config exists**, read it and validate: 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` -If validation fails, inform the user and re-ask for the correct values. +If any validation fails, inform the user and re-ask for the correct values. Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user: diff --git a/implement/skills/ingest.md b/implement/skills/ingest.md index 73598f6..a7ef820 100644 --- a/implement/skills/ingest.md +++ b/implement/skills/ingest.md @@ -96,8 +96,9 @@ workflow run may have already created it. **If the config exists**, read it and validate: 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` -If validation fails, inform the user and re-ask for the correct values. +If any validation fails, inform the user and re-ask for the correct values. Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user: From 3a3af3a74613ebef536b8701c2108eec29922052 Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Fri, 7 Aug 2026 09:57:33 -0400 Subject: [PATCH 09/10] Normalize tilde in docs_repo_path before persisting to config All five config-writing paths now resolve ~ to the user's home directory before saving to .artifacts/config.json, ensuring the stored path is absolute and works correctly in quoted shell commands. Assisted-by: Claude Opus 4.6 (1M) --- design/skills/ingest.md | 3 ++- design/skills/publish.md | 7 +++---- e2e/skills/ingest.md | 8 ++++---- implement/skills/ingest.md | 8 ++++---- prd/skills/publish.md | 7 +++---- 5 files changed, 16 insertions(+), 17 deletions(-) diff --git a/design/skills/ingest.md b/design/skills/ingest.md index f7cb1c9..65882f4 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -72,7 +72,8 @@ If any validation fails, inform the user and re-ask for the correct values. Update `.artifacts/config.json` with the corrected values. **If the config does not exist**, ask the user for the docs repo local path -and remote, validate them, and write `.artifacts/config.json`. +and remote, validate them. Resolve `~` to the user's home directory so +the stored path is absolute. Write `.artifacts/config.json`. #### Find the PRD in the Docs Repo diff --git a/design/skills/publish.md b/design/skills/publish.md index 66d3340..2e92280 100644 --- a/design/skills/publish.md +++ b/design/skills/publish.md @@ -49,10 +49,9 @@ correct values. Update `.artifacts/config.json` with the corrected 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: - -Write `.artifacts/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 diff --git a/e2e/skills/ingest.md b/e2e/skills/ingest.md index 3377cbf..0f34a1b 100644 --- a/e2e/skills/ingest.md +++ b/e2e/skills/ingest.md @@ -115,10 +115,10 @@ Update `.artifacts/config.json` with the corrected values. - **Docs repo remote:** Run `git -C "{docs_repo_path}" remote get-url origin` and confirm with the user -Validate the path and remote, then save the config: - -Write `.artifacts/config.json` with the validated `docs_repo_path` and -`docs_repo_remote` (workspace-level config shared across all workflows). +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` (workspace-level config +shared across all workflows). #### 5b: Find the PRD and Design Document diff --git a/implement/skills/ingest.md b/implement/skills/ingest.md index a7ef820..5b0e001 100644 --- a/implement/skills/ingest.md +++ b/implement/skills/ingest.md @@ -106,10 +106,10 @@ Update `.artifacts/config.json` with the corrected values. - **Docs repo remote:** Run `git -C "{docs_repo_path}" remote get-url origin` and confirm with the user -Validate the path and remote, then save the config: - -Write `.artifacts/config.json` with the validated `docs_repo_path` and -`docs_repo_remote` (workspace-level config shared across all workflows). +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` (workspace-level config +shared across all workflows). #### 5b: Find the PRD and Design Document diff --git a/prd/skills/publish.md b/prd/skills/publish.md index d3c494c..4923f38 100644 --- a/prd/skills/publish.md +++ b/prd/skills/publish.md @@ -49,10 +49,9 @@ correct values. Update `.artifacts/config.json` with the corrected 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: - -Write `.artifacts/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 From 51b1767d0ff0171b8f7f4124f7b76b22aa298b4e Mon Sep 17 00:00:00 2001 From: Andy Dalton Date: Fri, 7 Aug 2026 10:00:55 -0400 Subject: [PATCH 10/10] Also normalize tilde on config re-ask paths The previous commit added tilde resolution to new-config writes but missed the re-ask-on-validation-failure paths. All five files now resolve ~ before saving corrected values too. Assisted-by: Claude Opus 4.6 (1M) --- design/skills/ingest.md | 3 ++- design/skills/publish.md | 3 ++- e2e/skills/ingest.md | 3 ++- implement/skills/ingest.md | 3 ++- prd/skills/publish.md | 3 ++- 5 files changed, 10 insertions(+), 5 deletions(-) diff --git a/design/skills/ingest.md b/design/skills/ingest.md index 65882f4..c8c8949 100644 --- a/design/skills/ingest.md +++ b/design/skills/ingest.md @@ -69,7 +69,8 @@ Read `.artifacts/config.json` for `docs_repo_path` and `docs_repo_remote`. 3. Verify the remote URL matches the configured `docs_repo_remote` If any validation fails, inform the user and re-ask for the correct values. -Update `.artifacts/config.json` with the corrected 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 for the docs repo local path and remote, validate them. Resolve `~` to the user's home directory so diff --git a/design/skills/publish.md b/design/skills/publish.md index 2e92280..8b9a2c2 100644 --- a/design/skills/publish.md +++ b/design/skills/publish.md @@ -40,7 +40,8 @@ Check for an existing docs repo configuration at `.artifacts/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. Update `.artifacts/config.json` with the corrected 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: diff --git a/e2e/skills/ingest.md b/e2e/skills/ingest.md index 0f34a1b..bf04654 100644 --- a/e2e/skills/ingest.md +++ b/e2e/skills/ingest.md @@ -108,7 +108,8 @@ workflow run may have already created it. 3. Verify the remote URL matches the configured `docs_repo_remote` If any validation fails, inform the user and re-ask for the correct values. -Update `.artifacts/config.json` with the corrected 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: - **Docs repo local path:** Where is the planning docs repo checked out? diff --git a/implement/skills/ingest.md b/implement/skills/ingest.md index 5b0e001..163f492 100644 --- a/implement/skills/ingest.md +++ b/implement/skills/ingest.md @@ -99,7 +99,8 @@ workflow run may have already created it. 3. Verify the remote URL matches the configured `docs_repo_remote` If any validation fails, inform the user and re-ask for the correct values. -Update `.artifacts/config.json` with the corrected 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: - **Docs repo local path:** Where is the planning docs repo checked out? diff --git a/prd/skills/publish.md b/prd/skills/publish.md index 4923f38..1223748 100644 --- a/prd/skills/publish.md +++ b/prd/skills/publish.md @@ -40,7 +40,8 @@ Check for an existing docs repo configuration at `.artifacts/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. Update `.artifacts/config.json` with the corrected 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: