gsd-pi 2.41.0-dev.cac69f9 → 2.42.0-dev.97e9e30

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>