@trailstep/create-flows 0.3.0 → 0.3.2

package/README.md

@@ -1,20 +1,65 @@
 # @trailstep/create-flows
 
-`@trailstep/create-flows` is a public package of reusable, general-purpose TrailStep workflows.
+`@trailstep/create-flows` is a public package of reusable, general-purpose TrailStep workflows. It demonstrates how TrailStep's small step model can grow into larger, long-horizon coding workflows with focused agent sessions, typed handoffs, review loops, and retryable boundaries.
 
-## Install
+## Workflows
+
+- `grillItAway`: default registered id `grill-it-away`; starts interactively by asking clarifying questions, then runs the implementation pipeline.
+- `takeItAway`: default registered id `take-it-away`; starts from an already-organic conversation, ticket, or feature request, then runs the implementation pipeline.
+
+Both workflows end with a typed output containing implementation status, feature/implementation document paths, completed story count, completed story titles, and a summary.
+
+## Recommended setup
+
+Install the TrailStep CLI if you do not already have it, then use the interactive setup from your project root:
 
 ```bash
-pnpm add @trailstep/create-flows @trailstep/authoring
-pnpm add -D @trailstep/cli
+npm install --global @trailstep/cli
+trailstep init
+trailstep add @trailstep/create-flows@latest
 ```
 
-## Workflows
+Choose **project** scope, install the TrailStep usage skill, select the workflows you want, and add project skills when prompted. Project skills let supported coding agents discover and run the workflows from the agent UI.
+
+<details>
+<summary>Scriptable setup</summary>
+
+```bash
+# Initialize config and install the packaged TrailStep usage skill.
+trailstep init --scope project --install-skill
+
+# Preview without installing, registering, or writing skills.
+trailstep add @trailstep/create-flows@latest --scope project --workflow "*" --project-skill --dry-run
+
+# Install/register both workflows and generate project skills.
+trailstep add @trailstep/create-flows@latest --scope project --workflow "*" --project-skill --yes
+```
+
+</details>
+
+Run registered workflows directly if you prefer the CLI:
+
+```bash
+trailstep project/grill-it-away
+trailstep project/take-it-away --input-file feature-request.json
+trailstep retry project/take-it-away <runName>
+```
+
+## Which workflow should I use?
+
+### `grill-it-away`
+
+Use this when you have an idea but not a complete feature request. The first step is interactive: the grilling agent asks questions until it can produce the normalized `take-it-away` input.
+
+```text
+rough idea --> interactive grill step --> { conversation } --> implementation pipeline
+```
+
+### `take-it-away`
 
-- `takeItAway`: turns an existing conversation or feature request into reviewed planning and story-by-story delivery.
-- `grillItAway`: starts with an interactive conversation and then runs the same implementation pipeline.
+Use this when you already have enough context in a conversation, ticket, issue, or feature request. It skips the interactive grill step and starts the implementation pipeline directly.
 
-## Usage
+Input is a JSON object:
 
 ```json
 {
@@ -22,11 +67,66 @@ pnpm add -D @trailstep/cli
 }
 ```
 
+## Step architecture
+
+The two workflows share the same implementation pipeline after initial intake:
+
+```mermaid
+flowchart TD
+  A[grill-it-away interactive intake] --> C[create-feature-doc]
+  B[take-it-away conversation input] --> C
+  C --> D[create-or-improve-implementation-doc]
+  D --> E[review-implementation-doc]
+  E -->|needs work| D
+  E -->|passes| F[split-implementation-stories]
+  F --> G[implement-story]
+  G --> H[review-story-implementation]
+  H -->|needs work| G
+  H -->|passes| I[commit-reviewed-story / mark complete]
+  I --> J{more stories?}
+  J -->|yes| G
+  J -->|no| K[done]
+```
+
+The important TrailStep pattern is not the specific feature methodology; it is the architecture:
+
+- each stage is a focused step with its own prompt and agent role
+- each step passes structured output to the next step
+- planning and implementation have review loops
+- stories are split so implementation work happens one story at a time
+- failed runs can be retried through TrailStep instead of restarting the entire conversation
+
+## Agent roles
+
+The workflows declare role defaults so TrailStep can target different kinds of agent work:
+
+- **grillingAgent**: clarifies vague requests interactively.
+- **featureWriter**: turns the request/conversation into a standalone feature document.
+- **planner**: creates or improves an architecture-aware implementation plan.
+- **reviewer**: reviews implementation docs and story diffs.
+- **implementer**: implements one story at a time.
+
+## Safety notes
+
+These workflows are intended to change the current project when they reach implementation steps. Review your working tree before and after runs.
+
+By default, the `commit-reviewed-story` step marks reviewed stories complete without creating commits. Automatic story commits are enabled only when `TRAILSTEP_STORY_COMMIT_MODE` is set to `1`, `true`, `enabled`, or `worktree`.
+
+Generated run artifacts live under `.trailstep/runs` by default. Inspect them when needed, but do not edit them to recover workflow state; use `trailstep continue` or `trailstep retry`.
+
+## Direct package install
+
+If you want to import the workflows from TypeScript or run bundle refs directly after installing them yourself, install the package and its peer dependency:
+
+```bash
+npm install @trailstep/create-flows @trailstep/authoring
+```
+
+Then direct bundle refs use manifest names:
+
 ```bash
-trailstep add @trailstep/create-flows#takeItAway
 trailstep @trailstep/create-flows#takeItAway --input-file feature-request.json
 trailstep @trailstep/create-flows#grillItAway
-trailstep retry @trailstep/create-flows#takeItAway <runName>
 ```
 
-Generated run artifacts live under `.trailstep/runs`; inspect them, but do not edit them to recover workflow state.
+Use the equivalent install command for your package manager if you use `pnpm`, `yarn`, or `bun`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trailstep/create-flows",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Public reusable general-purpose TrailStep workflows.",
   "license": "Apache-2.0",
   "type": "module",
@@ -30,15 +30,15 @@
     }
   },
   "dependencies": {
-    "@trailstep/authoring": "0.1.0"
+    "@trailstep/authoring": "0.1.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.1.1",
-    "@types/node": "^26.1.1",
+    "@biomejs/biome": "^2.5.8",
+    "@types/node": "^26.2.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@trailstep/core": "0.1.0"
+    "@trailstep/core": "0.1.1"
   },
   "publishConfig": {
     "access": "public"
@@ -49,7 +49,7 @@
     "LICENSE"
   ],
   "peerDependencies": {
-    "@trailstep/authoring": "^0.1.0"
+    "@trailstep/authoring": "^0.1.2"
   },
   "scripts": {
     "build": "tsup src/index.ts --format esm --dts --sourcemap --clean --loader .md=text",