gsd-pi 2.41.0 → 2.42.0-dev.eedc83f

package/src/resources/skills/create-workflow/references/feature-patterns.md

@@ -0,0 +1,128 @@
+<feature_patterns>
+Advanced workflow features: `context_from`, `iterate`, and `params`. Each section includes a complete YAML example.
+
+**Feature 1: `context_from` — Context Chaining**
+
+Injects artifacts from prior steps as context when the current step runs. The value is an array of step IDs.
+
+```yaml
+version: 1
+name: research-and-synthesize
+steps:
+  - id: gather
+    name: Gather sources
+    prompt: "Find and summarize the top 5 sources on the topic."
+    produces:
+      - sources.md
+
+  - id: analyze
+    name: Analyze sources
+    prompt: "Analyze the gathered sources for key themes."
+    requires:
+      - gather
+    context_from:
+      - gather
+    produces:
+      - analysis.md
+
+  - id: synthesize
+    name: Write synthesis
+    prompt: "Synthesize the analysis into a coherent report."
+    requires:
+      - analyze
+    context_from:
+      - gather
+      - analyze
+    produces:
+      - report.md
+```
+
+How it works:
+- `context_from: [gather]` means the engine includes artifacts from the `gather` step when executing `analyze`.
+- You can reference multiple prior steps: `context_from: [gather, analyze]`.
+- The referenced steps must exist in the workflow (they are validated as step IDs).
+- `context_from` does not imply a dependency — if you want the step to wait, also add the ID to `requires`.
+
+**Feature 2: `iterate` — Fan-Out Iteration**
+
+Reads an artifact, applies a regex pattern, and creates one sub-execution per match. The capture group extracts the iteration variable.
+
+```yaml
+version: 1
+name: file-by-file-review
+steps:
+  - id: inventory
+    name: List files to review
+    prompt: "List all TypeScript files in src/ that need review, one per line."
+    produces:
+      - file-list.txt
+
+  - id: review
+    name: Review each file
+    prompt: "Review the file for code quality issues."
+    requires:
+      - inventory
+    iterate:
+      source: file-list.txt
+      pattern: "^(.+\\.ts)$"
+    produces:
+      - reviews/
+```
+
+How it works:
+- `source`: Path to an artifact (relative to the run directory). Must not contain `..`.
+- `pattern`: A regex string applied with the global flag. Must contain at least one capture group `(...)`.
+- The engine reads the source artifact, applies the pattern, and creates one execution per match.
+- Each capture group match becomes available as the iteration variable.
+- The regex is validated at definition-load time — invalid regex or missing capture groups are rejected.
+
+Pattern requirements:
+- Must be a valid JavaScript regex.
+- Must contain at least one non-lookahead capture group: `(...)` not `(?:...)`.
+- Example valid patterns: `^(.+)$`, `- (.+\.ts)`, `\[(.+?)\]`.
+
+**Feature 3: `params` — Parameterized Workflows**
+
+Define default parameter values at the top level. Use `{{ key }}` placeholders in step prompts. CLI overrides take precedence.
+
+```yaml
+version: 1
+name: blog-post
+description: Generate a blog post on a configurable topic.
+params:
+  topic: "AI in healthcare"
+  audience: "technical professionals"
+  word_count: "1500"
+steps:
+  - id: outline
+    name: Create outline
+    prompt: "Create a detailed outline for a blog post about {{ topic }} targeting {{ audience }}."
+    produces:
+      - outline.md
+
+  - id: draft
+    name: Write draft
+    prompt: "Write a {{ word_count }}-word blog post about {{ topic }} for {{ audience }} based on the outline."
+    requires:
+      - outline
+    context_from:
+      - outline
+    produces:
+      - draft.md
+    verify:
+      policy: content-heuristic
+      minSize: 500
+```
+
+How it works:
+- `params` is a top-level object mapping string keys to string default values.
+- `{{ key }}` in any step prompt is replaced with the corresponding param value.
+- Merge order: definition `params` (defaults) ← CLI overrides (win).
+- After substitution, any remaining `{{ key }}` that has no value causes an error — all placeholders must resolve.
+- Parameter values must not contain `..` (path traversal guard).
+- Keys in `{{ }}` match `\w+` (letters, digits, underscore).
+
+Common usage:
+- Make workflows reusable across different topics, projects, or configurations.
+- Users override defaults at run time: `/gsd workflow run blog-post topic="Rust performance"`.
+</feature_patterns>

package/src/resources/skills/create-workflow/references/verification-policies.md

@@ -0,0 +1,76 @@
+<verification_policies>
+The `verify` field on a step defines how the engine validates the step's output. It must be an object with a `policy` field set to one of four values.
+
+**Policy 1: `content-heuristic`**
+
+Checks the artifact content against size and pattern criteria. All sub-fields are optional.
+
+```yaml
+verify:
+  policy: content-heuristic
+  minSize: 500          # optional — minimum byte size of the artifact
+  pattern: "## Summary" # optional — string pattern that must appear in the artifact
+```
+
+Fields:
+- `policy`: `"content-heuristic"` (required)
+- `minSize`: number (optional) — minimum artifact size in bytes
+- `pattern`: string (optional) — text pattern to match in the artifact content
+
+Use when: You want a lightweight sanity check that the step produced substantive output.
+
+**Policy 2: `shell-command`**
+
+Runs a shell command to verify the step's output. The command's exit code determines pass/fail.
+
+```yaml
+verify:
+  policy: shell-command
+  command: "test -f output/report.md && wc -l output/report.md | awk '{print ($1 > 10)}'"
+```
+
+Fields:
+- `policy`: `"shell-command"` (required)
+- `command`: string (required, non-empty) — shell command to execute
+
+Use when: You need programmatic verification — file existence, test suite execution, linting, compilation, etc.
+
+**Policy 3: `prompt-verify`**
+
+Sends a verification prompt to an LLM to evaluate the step's output.
+
+```yaml
+verify:
+  policy: prompt-verify
+  prompt: "Review the generated API documentation. Does it cover all endpoints with request/response examples? Answer PASS or FAIL with reasoning."
+```
+
+Fields:
+- `policy`: `"prompt-verify"` (required)
+- `prompt`: string (required, non-empty) — the verification prompt sent to the LLM
+
+Use when: Verification requires judgment that can't be expressed as a shell command — quality assessment, completeness review, style conformance.
+
+**Policy 4: `human-review`**
+
+Pauses execution and waits for a human to approve or reject the step's output.
+
+```yaml
+verify:
+  policy: human-review
+```
+
+Fields:
+- `policy`: `"human-review"` (required)
+- No additional fields.
+
+Use when: The step produces work that requires human judgment — design decisions, public-facing content, security-sensitive changes.
+
+**Validation Details:**
+
+The engine validates the `verify` object at definition-load time:
+- `policy` must be one of the four strings above. Any other value is rejected.
+- `shell-command` requires a non-empty `command` field. Missing or empty `command` is rejected.
+- `prompt-verify` requires a non-empty `prompt` field. Missing or empty `prompt` is rejected.
+- `content-heuristic` and `human-review` have no required sub-fields beyond `policy`.
+</verification_policies>

package/src/resources/skills/create-workflow/references/yaml-schema-v1.md

@@ -0,0 +1,46 @@
+<schema_reference>
+V1 Workflow Definition Schema — complete field-by-field reference extracted from `definition-loader.ts`.
+
+**Top-Level Fields:**
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `version` | number | **yes** | — | Must be exactly `1`. |
+| `name` | string | **yes** | — | Non-empty workflow name. |
+| `description` | string | no | `undefined` | Optional human-readable description. |
+| `params` | object | no | `undefined` | Key-value map of parameter defaults. Values must be strings. Used for `{{ key }}` substitution in step prompts. |
+| `steps` | array | **yes** | — | Non-empty array of step objects. |
+
+**Step Fields:**
+
+| Field | Type | Required | Default | Description |
+|-------|------|----------|---------|-------------|
+| `id` | string | **yes** | — | Unique identifier within the workflow. Must be non-empty. No two steps can share an ID. |
+| `name` | string | **yes** | — | Human-readable step name. Must be non-empty. |
+| `prompt` | string | **yes** | — | The prompt dispatched for this step. Must be non-empty. Supports `{{ key }}` parameter placeholders. |
+| `requires` | string[] | no | `[]` | IDs of steps that must complete before this step runs. Alternative name: `depends_on`. |
+| `depends_on` | string[] | no | `[]` | Alias for `requires`. If both are present, `requires` takes precedence. |
+| `produces` | string[] | no | `[]` | Artifact paths produced by this step (relative to run directory). Paths must not contain `..`. |
+| `context_from` | string[] | no | `undefined` | Step IDs whose artifacts are injected as context when this step runs. |
+| `verify` | object | no | `undefined` | Verification policy for this step. See verification-policies.md for details. |
+| `iterate` | object | no | `undefined` | Fan-out iteration config. See feature-patterns.md for details. |
+
+**Validation Rules:**
+
+1. `version` must be exactly `1` (number, not string).
+2. `name` must be a non-empty string.
+3. `steps` must be a non-empty array of objects.
+4. Each step must have non-empty `id`, `name`, and `prompt`.
+5. Step IDs must be unique — duplicates are rejected.
+6. Dependencies must reference existing step IDs — dangling references are rejected.
+7. A step cannot depend on itself.
+8. The dependency graph must be acyclic — cycles are detected and rejected.
+9. `produces` paths and `iterate.source` must not contain `..` (path traversal guard).
+10. Unknown top-level or step-level fields are silently accepted for forward compatibility.
+
+**Type Notes:**
+
+- `requires` / `depends_on`: The engine reads `requires` first. If absent, it falls back to `depends_on`. Both must be arrays of strings if present.
+- `params` values must be strings. During substitution, each `{{ key }}` in a step prompt is replaced with the merged param value (definition defaults ← CLI overrides). Any unresolved placeholder after substitution causes an error.
+- Parameter values and `produces` paths are guarded against path traversal (`..` is rejected).
+</schema_reference>

package/src/resources/skills/create-workflow/templates/blog-post-pipeline.yaml

@@ -0,0 +1,60 @@
+# Example: Blog Post Pipeline
+# Demonstrates: context chaining (context_from), parameters (params),
+# and content-heuristic verification across a 3-step linear chain.
+
+version: 1
+name: blog-post-pipeline
+description: >-
+  Research a topic, create an outline, and draft a blog post.
+  Uses params for topic/audience, context_from for chaining,
+  and content-heuristic verification at every step.
+
+params:
+  topic: "AI"
+  audience: "developers"
+
+steps:
+  - id: research
+    name: Research the topic
+    prompt: >-
+      Research the topic "{{ topic }}" for an audience of {{ audience }}.
+      Write detailed findings including key trends, important facts,
+      and relevant examples. Save the results to research.md.
+    requires: []
+    produces:
+      - research.md
+    verify:
+      policy: content-heuristic
+      minSize: 200
+
+  - id: outline
+    name: Create an outline
+    prompt: >-
+      Using the research findings, create a structured blog post outline
+      targeting {{ audience }}. Include section headings, key points
+      for each section, and a logical flow. Save to outline.md.
+    requires:
+      - research
+    context_from:
+      - research
+    produces:
+      - outline.md
+    verify:
+      policy: content-heuristic
+
+  - id: draft
+    name: Write the draft
+    prompt: >-
+      Write a complete blog post draft following the outline.
+      The post should be engaging for {{ audience }}, cover all
+      outlined sections, and include a compelling introduction
+      and conclusion. Save to draft.md.
+    requires:
+      - outline
+    context_from:
+      - outline
+    produces:
+      - draft.md
+    verify:
+      policy: content-heuristic
+      minSize: 500

package/src/resources/skills/create-workflow/templates/code-audit.yaml

@@ -0,0 +1,60 @@
+# Example: Code Audit
+# Demonstrates: iterate (fan-out over file list), shell-command verification,
+# prompt-verify, and content-heuristic across a 3-step workflow.
+
+version: 1
+name: code-audit
+description: >-
+  Inventory TypeScript files, audit each one for quality issues,
+  and produce a consolidated report. Uses iterate to fan-out
+  audits across discovered files.
+
+steps:
+  - id: inventory
+    name: Inventory source files
+    prompt: >-
+      List all TypeScript source files in the project that should
+      be audited. Write one file path per line as a Markdown list
+      item (e.g. "- src/index.ts"). Save the list to inventory.md.
+    requires: []
+    produces:
+      - inventory.md
+    verify:
+      policy: content-heuristic
+
+  - id: audit-file
+    name: Audit individual file
+    prompt: >-
+      Review the file for code quality issues including unused imports,
+      missing error handling, type safety gaps, and potential bugs.
+      Document each finding with the line number and a recommended fix.
+      Append results to audit-results.md.
+    requires:
+      - inventory
+    context_from:
+      - inventory
+    produces:
+      - audit-results.md
+    iterate:
+      source: inventory.md
+      pattern: "^- (.+\\.ts)$"
+    verify:
+      policy: shell-command
+      command: "test -f audit-results.md"
+
+  - id: report
+    name: Compile audit report
+    prompt: >-
+      Compile all individual file audit results into a single
+      comprehensive audit report. Group findings by severity
+      (critical, warning, info), include summary statistics,
+      and provide prioritized recommendations. Save to audit-report.md.
+    requires:
+      - audit-file
+    context_from:
+      - audit-file
+    produces:
+      - audit-report.md
+    verify:
+      policy: prompt-verify
+      prompt: "Does the report cover all audited files and group findings by severity? Answer PASS or FAIL."

package/src/resources/skills/create-workflow/templates/release-checklist.yaml

@@ -0,0 +1,66 @@
+# Example: Release Checklist
+# Demonstrates: diamond dependency pattern (version-bump and test-suite
+# both depend on changelog, publish depends on both), shell-command
+# verification, and human-review policy.
+
+version: 1
+name: release-checklist
+description: >-
+  Prepare a software release: generate changelog, bump version,
+  run tests, and publish release notes. Uses a diamond dependency
+  pattern where publish waits for both version-bump and test-suite.
+
+steps:
+  - id: changelog
+    name: Generate changelog
+    prompt: >-
+      Review recent commits and generate a changelog draft.
+      Group changes by category (features, fixes, breaking changes).
+      Follow Keep a Changelog format. Save to CHANGELOG-draft.md.
+    requires: []
+    produces:
+      - CHANGELOG-draft.md
+    verify:
+      policy: content-heuristic
+
+  - id: version-bump
+    name: Bump version number
+    prompt: >-
+      Based on the changelog, determine the appropriate semver bump
+      (major, minor, or patch). Write the new version number to
+      version.txt as a single line (e.g. "1.2.3").
+    requires:
+      - changelog
+    produces:
+      - version.txt
+    verify:
+      policy: shell-command
+      command: "grep -E '^[0-9]+\\.[0-9]+\\.[0-9]+$' version.txt"
+
+  - id: test-suite
+    name: Run test suite
+    prompt: >-
+      Run the full test suite and capture results. Include test
+      counts (passed, failed, skipped), execution time, and any
+      failure details. Save results to test-results.md.
+    requires:
+      - changelog
+    produces:
+      - test-results.md
+    verify:
+      policy: shell-command
+      command: "test -f test-results.md"
+
+  - id: publish
+    name: Publish release
+    prompt: >-
+      Compile the final release notes combining the changelog,
+      version number, and test results. Format for GitHub Releases
+      with proper Markdown. Save to release-notes.md.
+    requires:
+      - version-bump
+      - test-suite
+    produces:
+      - release-notes.md
+    verify:
+      policy: human-review

package/src/resources/skills/create-workflow/templates/workflow-definition.yaml

@@ -0,0 +1,32 @@
+version: 1
+name: my-workflow
+# description: A brief description of what this workflow accomplishes.
+
+# params:
+#   topic: "default value"
+#   target: "another default"
+
+steps:
+  - id: step-one
+    name: First step
+    prompt: "Describe what this step should accomplish."
+    # requires: []
+    produces:
+      - output.md
+    # context_from:
+    #   - some-prior-step
+    # verify:
+    #   policy: content-heuristic
+    #   minSize: 100
+    #   pattern: "## Summary"
+    # verify:
+    #   policy: shell-command
+    #   command: "test -f output.md"
+    # verify:
+    #   policy: prompt-verify
+    #   prompt: "Does the output meet quality standards? Answer PASS or FAIL."
+    # verify:
+    #   policy: human-review
+    # iterate:
+    #   source: file-list.txt
+    #   pattern: "^(.+)$"

package/src/resources/skills/create-workflow/workflows/create-from-scratch.md

@@ -0,0 +1,104 @@
+<workflow>
+Guide the user through creating a workflow definition from scratch. Follow these phases in order.
+
+<required_reading>
+Before starting, read these references so you can answer schema questions accurately:
+- `../references/yaml-schema-v1.md` — all fields, types, and constraints
+- `../references/verification-policies.md` — the four verify policies
+- `../references/feature-patterns.md` — context_from, iterate, params patterns
+</required_reading>
+
+<phase name="purpose">
+Ask the user:
+- "What does this workflow accomplish? Give me a one-sentence description."
+- "What should the workflow be named?" (suggest a kebab-case name based on their description)
+
+Record: `name`, `description`.
+</phase>
+
+<phase name="steps">
+Ask the user:
+- "What are the main steps? List them in order. For each step, give a short name and what it should do."
+
+For each step the user describes:
+1. Generate an `id` (lowercase, short, descriptive — e.g., `gather`, `analyze`, `write-draft`).
+2. Confirm the `name` (human-readable).
+3. Write the `prompt` — this is the instruction the engine dispatches. It should be detailed enough for an LLM to execute independently.
+4. Ask: "Does this step depend on any previous steps?" → populate `requires`.
+5. Ask: "What files or artifacts does this step produce?" → populate `produces`.
+</phase>
+
+<phase name="verification">
+For each step, ask:
+- "How should we verify this step's output?"
+  - **No verification needed** → omit `verify`
+  - **Check that the output exists and has content** → `content-heuristic`
+  - **Run a shell command to validate** → `shell-command` (ask for the command)
+  - **Have an LLM review the output** → `prompt-verify` (ask for the verification prompt)
+  - **Require human approval** → `human-review`
+
+Refer to `../references/verification-policies.md` for the exact YAML structure of each policy.
+</phase>
+
+<phase name="context_chaining">
+Ask:
+- "Should any step receive artifacts from earlier steps as context?"
+
+If yes, for each such step:
+- Ask which prior steps to pull context from → populate `context_from`.
+- Remind the user: `context_from` does not imply a dependency. If the step should wait for the context source, it must also list it in `requires`.
+</phase>
+
+<phase name="parameters">
+Ask:
+- "Should any values in this workflow be configurable at run time? (e.g., a topic, a target directory, a language)"
+
+If yes:
+- Define each parameter with a default value in top-level `params`.
+- Replace hardcoded values in step prompts with `{{ key }}` placeholders.
+- Explain: "Users can override these when running the workflow."
+</phase>
+
+<phase name="iteration">
+Ask:
+- "Does any step need to fan out — running once per item in a list? (e.g., review each file, process each section)"
+
+If yes:
+- Identify the source artifact (the list to iterate over).
+- Define the `pattern` regex with a capture group to extract each item.
+- Set `iterate.source` and `iterate.pattern` on the step.
+- Refer to `../references/feature-patterns.md` for examples.
+</phase>
+
+<phase name="assemble">
+Assemble the complete YAML definition:
+
+1. Start with `version: 1`.
+2. Add `name` and `description`.
+3. Add `params` if any were defined.
+4. Add `steps` in dependency order.
+5. For each step, include all configured fields in this order: `id`, `name`, `prompt`, `requires`, `produces`, `context_from`, `verify`, `iterate`.
+6. Use 2-space indentation.
+
+Show the complete YAML to the user for review.
+
+Ask: "Does this look correct? Any changes?"
+
+Apply any requested changes.
+</phase>
+
+<phase name="write">
+Write the file to `.gsd/workflow-defs/<name>.yaml`.
+
+Tell the user:
+- "Definition saved to `.gsd/workflow-defs/<name>.yaml`."
+- "Run `/gsd workflow validate <name>` to check it against the schema."
+- "Run `/gsd workflow run <name>` to execute it."
+</phase>
+
+<success_criteria>
+- A valid YAML file exists at `.gsd/workflow-defs/<name>.yaml`
+- The definition passes `validateDefinition()` from `definition-loader.ts`
+- The user has reviewed and approved the definition
+</success_criteria>
+</workflow>

package/src/resources/skills/create-workflow/workflows/create-from-template.md

@@ -0,0 +1,72 @@
+<workflow>
+Guide the user through creating a workflow definition by customizing an existing template.
+
+<required_reading>
+Before starting, read these references for schema details:
+- `../references/yaml-schema-v1.md` — all fields, types, and constraints
+- `../references/verification-policies.md` — the four verify policies
+- `../references/feature-patterns.md` — context_from, iterate, params patterns
+</required_reading>
+
+<phase name="choose_template">
+List the available templates in `templates/`:
+
+1. **workflow-definition.yaml** — Blank scaffold with all fields shown as comments. Best for: starting with the full schema visible.
+2. **blog-post-pipeline.yaml** — Linear 3-step chain with `params` (topic, audience) and `content-heuristic` verification. Best for: workflows with sequential steps and configurable inputs.
+3. **code-audit.yaml** — 3 steps using `iterate` to fan out over a file list, with `shell-command` verification. Best for: workflows that process each item in a list.
+4. **release-checklist.yaml** — 4 steps with diamond dependencies and `human-review` verification. Best for: workflows with branching/merging dependency graphs.
+
+Ask: "Which template would you like to start from?"
+
+Read the chosen template file from `templates/`.
+</phase>
+
+<phase name="understand">
+Show the user the template contents and explain:
+- What each step does
+- How the dependencies flow
+- What features it demonstrates (params, context_from, iterate, verify)
+
+Ask: "What do you want this workflow to do instead? I'll help you adapt the template."
+</phase>
+
+<phase name="customize">
+Based on the user's goal, walk through customization:
+
+1. **Rename**: Change `name` and `description` to match the new purpose.
+2. **Adjust steps**: Add, remove, or modify steps. For each change:
+   - Update `id` and `name` to reflect the new purpose.
+   - Rewrite `prompt` for the new task.
+   - Update `requires` to reflect new dependency order.
+   - Update `produces` for new artifact paths.
+3. **Modify params**: Add or remove parameters. Update `{{ key }}` placeholders in prompts to match.
+4. **Change verification**: Switch verify policies or adjust policy-specific fields.
+5. **Add/remove features**: Add `context_from`, `iterate`, or `params` if the new workflow needs them.
+
+Show the modified YAML after each round of changes. Ask: "Any more changes?"
+</phase>
+
+<phase name="validate_and_write">
+Once the user approves:
+
+1. Review the YAML for common issues:
+   - All step IDs are unique.
+   - All `requires` references point to existing step IDs.
+   - No circular dependencies.
+   - All `{{ key }}` placeholders have corresponding `params` entries.
+   - No `..` in `produces` paths or `iterate.source`.
+
+2. Write to `.gsd/workflow-defs/<name>.yaml`.
+
+3. Tell the user:
+   - "Definition saved to `.gsd/workflow-defs/<name>.yaml`."
+   - "Run `/gsd workflow validate <name>` to check it against the schema."
+   - "Run `/gsd workflow run <name>` to execute it."
+</phase>
+
+<success_criteria>
+- A valid YAML file exists at `.gsd/workflow-defs/<name>.yaml`
+- The definition is a meaningful customization of the template, not a copy
+- The user has reviewed and approved the definition
+</success_criteria>
+</workflow>