Enhance spec process journal

skills/sldd-00-process-overview-and-navigation-guide/SKILL.md

@@ -29,6 +29,69 @@ No implementation prompts (steps 04-05) before intent and design (steps 01-03) a
 
 For existing codebases, use **sldd-99-existing-codebase-understanding-and-context-summary** after step 01 and before step 02 to ground all design decisions in the current architecture and conventions. Skip for greenfield projects.
 
+## SPEC.md — Process journal
+
+Each skill in the SLDD process can save its output to a `SPEC.md` file that serves as the single source of truth for the entire feature development lifecycle.
+
+### File location
+
+```
+<user-chosen-dir>/<feature-slug>/SPEC.md
+```
+
+Example: `docs/specs/add-user-auth/SPEC.md`
+
+The feature slug is derived from the feature name and confirmed by the user at creation time. The slug-per-directory structure allows multiple features to coexist under the same specs root without collision.
+
+### File structure
+
+```markdown
+# SPEC: <feature name>
+
+## Progress
+
+- [ ] Step 01 — Product Intent Specification
+- [ ] Step 99 — Existing Codebase Context (optional)
+- [ ] Step 02 — High-Level Technical Design
+- [ ] Step 03 — Low-Level Design and Version Policy
+- [ ] Step 04 — Tests (written and confirmed failing)
+- [ ] Step 05 — Implementation (all tests passing)
+- [ ] Step 06 — Verification Report
+
+---
+
+## Step 01 — Product Intent Specification
+
+<output from sldd-01>
+
+---
+```
+
+Each skill appends its section and marks its checklist item `[x]`. The Progress checklist is the canonical record of which steps are complete.
+
+### Save behavior (all skills)
+
+At the end of every skill output, the agent asks: **"Save this output to SPEC.md? (yes/no)"**
+
+- **If yes and no SPEC.md exists yet:** ask for the specs directory and suggest a slug derived from the feature name (user confirms or edits). Create `<dir>/<slug>/SPEC.md` with the Progress checklist header and the step's section.
+- **If yes and SPEC.md already exists:** ask for the path to the existing SPEC.md. Append the step's section and mark `[x]` in the Progress checklist.
+- **If no:** continue without saving.
+
+### Resume behavior (all skills)
+
+Every skill accepts an optional `SPEC.md` input at initialization:
+
+```
+SPEC.md (optional): <path to existing SPEC.md, or leave blank to start fresh>
+```
+
+When a path is provided:
+1. Read the file and check the Progress checklist to identify completed steps.
+2. Extract relevant prior sections as pre-populated context for the current step.
+3. Announce: `"Resuming SLDD process. Steps complete: [list]. Continuing with Step XX."`
+
+If the user provides a specs **root directory** instead of a full path, the skill lists all `*/SPEC.md` files found under it and asks which feature to resume.
+
 ## Credit
 
 Based on Loiane Groner's article: https://loiane.com/2026/03/vibe-coding-with-specs-driven-feedback-loops/

skills/sldd-01-product-intent-specification/SKILL.md

@@ -13,6 +13,16 @@ You are a product engineering assistant. You are helping a team prepare specific
 
 Feature idea: <provide feature idea>
 
+SPEC.md (optional): <provide path to an existing SPEC.md to resume the process, or leave blank to start fresh>
+
+**SPEC.md resume behavior:**
+If a SPEC.md path is provided:
+1. Read the file and check the Progress checklist to identify which steps are already complete.
+2. Extract any existing section content to use as prior context.
+3. Announce: "Resuming SLDD process. Steps complete: [list]. Continuing with Step 01."
+If the user provides a specs root directory instead of a full path, list all `*/SPEC.md` files found under it and ask which feature to resume.
+If no SPEC.md is provided, proceed normally.
+
 **Objective:**
 Produce a one-page product intent specification that aligns engineering and product teams on scope, success criteria, and constraints for this feature.
 
@@ -34,3 +44,11 @@ Deliver exactly these six sections in this order:
 5) Risks and assumptions (potential blockers or dependencies)
 6) Acceptance criteria in Given/When/Then format
    - Include happy path, validation/failure cases, and at least one edge case per criterion
+
+**After delivering the output:**
+First, check whether file writes are currently allowed (i.e. whether you are NOT in plan mode / read-only mode):
+- If file writes are FORBIDDEN (plan mode is active): tell the user explicitly — "I am in plan mode and cannot write files right now. To save this spec to SPEC.md, switch to build/execution mode and I will create it immediately." Do NOT ask the save question yet. Stop here.
+- If file writes are ALLOWED: ask the user "Save this output to SPEC.md? (yes/no)"
+- If yes and no SPEC.md exists yet: ask "Which directory should I use for specs?" (e.g. `docs/specs`), then suggest a slug derived from the feature name (e.g. `add-user-auth`) and ask the user to confirm or edit it. Create `<dir>/<slug>/SPEC.md` with the Progress checklist header (all steps unchecked) and the Step 01 section, marking Step 01 as `[x]`.
+- If yes and a SPEC.md already exists: ask for the path to the existing SPEC.md, then append the `## Step 01 — Product Intent Specification` section and mark `[x]` next to Step 01 in the Progress checklist.
+- If no: continue without saving.

skills/sldd-02-high-level-technical-design/SKILL.md

@@ -13,6 +13,17 @@ You are a senior software architect designing solutions. You have reviewed the p
 
 Intent spec: <provide the approved product intent specification>
 
+SPEC.md (optional): <provide path to an existing SPEC.md to load prior context, or leave blank>
+
+**SPEC.md resume behavior:**
+If a SPEC.md path is provided:
+1. Read the file and check the Progress checklist to identify which steps are already complete.
+2. If Step 01 is marked complete, extract its section as the intent spec — no need to paste it manually.
+3. If Step 99 is marked complete, include the codebase context as additional input.
+4. Announce: "Resuming SLDD process. Steps complete: [list]. Continuing with Step 02."
+If the user provides a specs root directory instead of a full path, list all `*/SPEC.md` files found under it and ask which feature to resume.
+If no SPEC.md is provided, proceed normally.
+
 **Objective:**
 Produce a high-level technical design that translates the product intent into architecture and system boundaries, without implementation details or code.
 
@@ -35,3 +46,11 @@ Deliver exactly these sections in this order:
 - High-level test scenario map (happy path, failure paths, and edge-case families)
 
 Do not generate implementation code or tests. Do not write code in any language.
+
+**After delivering the output:**
+First, check whether file writes are currently allowed (i.e. whether you are NOT in plan mode / read-only mode):
+- If file writes are FORBIDDEN (plan mode is active): tell the user explicitly — "I am in plan mode and cannot write files right now. To save this spec to SPEC.md, switch to build/execution mode and I will create it immediately." Do NOT ask the save question yet. Stop here.
+- If file writes are ALLOWED: ask the user "Save this output to SPEC.md? (yes/no)"
+- If yes and no SPEC.md exists yet: ask "Which directory should I use for specs?" (e.g. `docs/specs`), then suggest a slug derived from the feature name and ask the user to confirm or edit it. Create `<dir>/<slug>/SPEC.md` with the Progress checklist header (all steps unchecked) and the Step 02 section, marking Step 02 as `[x]`.
+- If yes and a SPEC.md already exists: ask for the path to the existing SPEC.md, then append the `## Step 02 — High-Level Technical Design` section and mark `[x]` next to Step 02 in the Progress checklist.
+- If no: continue without saving.

skills/sldd-03-low-level-design-and-version-policy/SKILL.md

@@ -13,6 +13,18 @@ You are a staff engineer preparing an implementation plan. You have the high-lev
 
 High-level design: <provide the approved high-level technical design>
 
+SPEC.md (optional): <provide path to an existing SPEC.md to load prior context, or leave blank>
+
+**SPEC.md resume behavior:**
+If a SPEC.md path is provided:
+1. Read the file and check the Progress checklist to identify which steps are already complete.
+2. If Step 02 is marked complete, extract its section as the high-level design — no need to paste it manually.
+3. If Step 01 is marked complete, extract it as additional intent context.
+4. If Step 99 is marked complete, include the codebase context as additional input.
+5. Announce: "Resuming SLDD process. Steps complete: [list]. Continuing with Step 03."
+If the user provides a specs root directory instead of a full path, list all `*/SPEC.md` files found under it and ask which feature to resume.
+If no SPEC.md is provided, proceed normally.
+
 **Objective:**
 Produce a detailed low-level design and implementation plan that specifies what to build, version constraints, and test strategy — enabling unambiguous work assignments.
 
@@ -41,3 +53,11 @@ Version policy requirements must include:
 After delivering the low-level design, produce a detailed ordered implementation plan listing every task (components, endpoints, data models, migrations, tests, configuration) as discrete sequenced steps small enough to evaluate individually. This plan is the checklist the team agrees on before any implementation prompt is sent.
 
 Gate: present the high-level and low-level designs for review before any code is generated. Do not skip the review gate because AI can generate code quickly.
+
+**After delivering the output:**
+First, check whether file writes are currently allowed (i.e. whether you are NOT in plan mode / read-only mode):
+- If file writes are FORBIDDEN (plan mode is active): tell the user explicitly — "I am in plan mode and cannot write files right now. To save this spec to SPEC.md, switch to build/execution mode and I will create it immediately." Do NOT ask the save question yet. Stop here.
+- If file writes are ALLOWED: ask the user "Save this output to SPEC.md? (yes/no)"
+- If yes and no SPEC.md exists yet: ask "Which directory should I use for specs?" (e.g. `docs/specs`), then suggest a slug derived from the feature name and ask the user to confirm or edit it. Create `<dir>/<slug>/SPEC.md` with the Progress checklist header (all steps unchecked) and the Step 03 section, marking Step 03 as `[x]`.
+- If yes and a SPEC.md already exists: ask for the path to the existing SPEC.md, then append the `## Step 03 — Low-Level Design and Version Policy` section and mark `[x]` next to Step 03 in the Progress checklist.
+- If no: continue without saving.

skills/sldd-04-tests-first-driven-by-acceptance-criteria/SKILL.md

@@ -15,14 +15,30 @@ Low-level design: <provide the approved low-level design>
 
 Acceptance criteria: <provide the acceptance criteria from the product intent specification>
 
+SPEC.md (optional): <provide path to an existing SPEC.md to load prior context, or leave blank>
+
+**SPEC.md resume behavior:**
+If a SPEC.md path is provided:
+1. Read the file and check the Progress checklist to identify which steps are already complete.
+2. If Step 03 is marked complete, extract its section as the low-level design — no need to paste it manually.
+3. If Step 01 is marked complete, extract the acceptance criteria from its section — no need to paste them manually.
+4. If Step 99 is marked complete, include the codebase context (test framework, conventions) as additional input.
+5. Announce: "Resuming SLDD process. Steps complete: [list]. Continuing with Step 04."
+If the user provides a specs root directory instead of a full path, list all `*/SPEC.md` files found under it and ask which feature to resume.
+If no SPEC.md is provided, proceed normally.
+
 **Objective:**
 Write test files that directly correspond to the acceptance criteria and test scenarios. These tests will drive implementation. Do not write production code yet.
 
 **Audience:**
 Engineers who will run these tests immediately and implement code to make them pass.
 
+**Before writing any tests:**
+Check whether an `AGENTS.md` file exists at the project root. If it references a testing guideline file (e.g. `TESTING-GUIDELINE.adoc`), read it and apply all conventions found there to every test written. Conventions typically cover: test framework, assertion library, naming patterns, test structure (AAA), soft assertions, exception testing style, and coverage requirements.
+If no guideline is found, fall back to the conventions of existing test files in the project as the baseline.
+
 **Style:**
-Test code in the project's native test framework. One test per clearly named scenario. Include brief comments explaining what each test validates.
+Test code in the project's native test framework. One test per clearly named scenario. Include brief comments explaining what each test validates. Naming, structure, and assertion style must follow the project's testing guideline if one exists.
 
 **Tone:**
 Explicit. Each test must map to one acceptance criterion. Leave no ambiguity about what passes or fails.
@@ -35,3 +51,9 @@ Deliver:
 - Commands to run the test suite
 
 Imperative: Write tests only. Do not write any production code. Do not implement any features. Your output is test files only.
+
+**After delivering the output:**
+Ask the user: "Save this output to SPEC.md? (yes/no)"
+- If yes and no SPEC.md exists yet: ask "Which directory should I use for specs?" (e.g. `docs/specs`), then suggest a slug derived from the feature name and ask the user to confirm or edit it. Create `<dir>/<slug>/SPEC.md` with the Progress checklist header (all steps unchecked) and the Step 04 section (listing test files written and the commands to run them), marking Step 04 as `[x]`.
+- If yes and a SPEC.md already exists: ask for the path to the existing SPEC.md, then append the `## Step 04 — Tests` section (listing test files written and run commands) and mark `[x]` next to Step 04 in the Progress checklist.
+- If no: continue without saving.

skills/sldd-05-minimal-implementation-to-pass-existing-tests/SKILL.md

@@ -15,12 +15,27 @@ Low-level design: <provide the approved low-level design>
 
 Existing failing tests: <provide the test files or reference their location>
 
+SPEC.md (optional): <provide path to an existing SPEC.md to load prior context, or leave blank>
+
+**SPEC.md resume behavior:**
+If a SPEC.md path is provided:
+1. Read the file and check the Progress checklist to identify which steps are already complete.
+2. If Step 03 is marked complete, extract its section as the low-level design — no need to paste it manually.
+3. If Step 04 is marked complete, extract the test file locations and run commands from its section — no need to provide them manually.
+4. If Step 99 is marked complete, include the codebase context (language, conventions, architecture) as additional input.
+5. Announce: "Resuming SLDD process. Steps complete: [list]. Continuing with Step 05."
+If the user provides a specs root directory instead of a full path, list all `*/SPEC.md` files found under it and ask which feature to resume.
+If no SPEC.md is provided, proceed normally.
+
 **Objective:**
 Implement only the production code required to make all existing tests pass. Do not add features not covered by tests. Do not refactor unless tests fail.
 
 **Audience:**
 Engineers and code reviewers verifying that implementation matches the low-level design and test intentions.
 
+**Before writing any production code:**
+Check whether an `AGENTS.md` file exists at the project root. If it references a testing guideline file, read it. Do NOT write or modify test files in this step — tests are already written and must remain untouched. Ensure all production code follows the existing architecture and code style conventions of the project.
+
 **Style:**
 Production code written in the project's native language. Follow existing code style and architecture conventions. Keep implementation focused and minimal.
 
@@ -36,3 +51,9 @@ Deliver:
 - Expected test output summary (show which tests now pass)
 
 Imperative: Do not modify the tests. Do not add features. Do not refactor. If the low-level design seems wrong, propose a design amendment instead of changing architecture.
+
+**After delivering the output:**
+Ask the user: "Save this output to SPEC.md? (yes/no)"
+- If yes and no SPEC.md exists yet: ask "Which directory should I use for specs?" (e.g. `docs/specs`), then suggest a slug derived from the feature name and ask the user to confirm or edit it. Create `<dir>/<slug>/SPEC.md` with the Progress checklist header (all steps unchecked) and the Step 05 section (listing production files written, test run commands, and the assumptions checklist), marking Step 05 as `[x]`.
+- If yes and a SPEC.md already exists: ask for the path to the existing SPEC.md, then append the `## Step 05 — Implementation` section (production files, run commands, assumptions checklist) and mark `[x]` next to Step 05 in the Progress checklist.
+- If no: continue without saving.

skills/sldd-06-verification-and-feedback-report/SKILL.md

@@ -15,6 +15,18 @@ Spec: <provide the approved low-level design and product intent specification>
 
 Implementation summary: <provide the implementation output or reference files>
 
+SPEC.md (optional): <provide path to an existing SPEC.md to load prior context, or leave blank>
+
+**SPEC.md resume behavior:**
+If a SPEC.md path is provided:
+1. Read the file and check the Progress checklist to identify which steps are already complete.
+2. If Step 01 is marked complete, extract its section as the product intent spec (problem statement, acceptance criteria) — no need to paste it manually.
+3. If Step 03 is marked complete, extract its section as the low-level design to audit against — no need to paste it manually.
+4. If Step 05 is marked complete, extract the implementation summary (production files, run commands, assumptions) from its section — no need to provide it manually.
+5. Announce: "Resuming SLDD process. Steps complete: [list]. Continuing with Step 06."
+If the user provides a specs root directory instead of a full path, list all `*/SPEC.md` files found under it and ask which feature to resume.
+If no SPEC.md is provided, proceed normally.
+
 **Objective:**
 Produce a gap report that compares the implementation against the spec and identifies what matches, what is missing, what risks remain, and whether the work is production-ready.
 
@@ -28,9 +40,18 @@ Structured report with matrices, lists, and clear status indicators (met/partial
 Critical and honest. Flag every gap and risk. Provide actionable remediation steps. Give a clear yes/no on production readiness.
 
 **Response:**
+Before auditing, check whether an `AGENTS.md` file exists at the project root. If it references a testing guideline file, read it and use it as the baseline for test convention compliance checks.
+
 Deliver exactly these sections in this order:
 1) Compliance matrix (spec requirement → implementation status: met/partial/missing)
 2) Version and dependency validation (are versions correct and supported?)
-3) Risk list by severity (high/medium/low)
-4) Suggested remediation steps (how to fix gaps before release)
-5) Decision: ready for production? yes/no and why. If no, list the top 3 blockers.
+3) Test convention compliance: verify that test files follow the project's testing guideline (from `AGENTS.md` if present). Flag any tests that violate naming conventions, assertion style, soft assertion usage, AAA structure, or exception testing patterns.
+4) Risk list by severity (high/medium/low)
+5) Suggested remediation steps (how to fix gaps before release)
+6) Decision: ready for production? yes/no and why. If no, list the top 3 blockers.
+
+**After delivering the output:**
+Ask the user: "Save this output to SPEC.md? (yes/no)"
+- If yes and no SPEC.md exists yet: ask "Which directory should I use for specs?" (e.g. `docs/specs`), then suggest a slug derived from the feature name and ask the user to confirm or edit it. Create `<dir>/<slug>/SPEC.md` with the Progress checklist header (all steps unchecked) and the Step 06 section (full gap report and go/no-go decision), marking Step 06 as `[x]`.
+- If yes and a SPEC.md already exists: ask for the path to the existing SPEC.md, then append the `## Step 06 — Verification Report` section (full gap report and go/no-go decision) and mark `[x]` next to Step 06 in the Progress checklist.
+- If no: continue without saving.