@exaudeus/workrail 3.27.0 → 3.29.0

package/docs/migration/v0.1.0.md

@@ -0,0 +1,147 @@
+# Migration Guide: v0.0.1 to v0.1.0
+
+This guide helps you migrate your workflows from Workrail v0.0.1 to v0.1.0, which introduces loop support and schema versioning.
+
+## What's New in v0.1.0
+
+### Major Features
+- **Loop Support**: Four types of loops (while, until, for, forEach)
+- **Schema Versioning**: Explicit version field for workflows
+- **Migration Tool**: Automated migration command
+
+### Breaking Changes
+None - v0.1.0 is fully backward compatible with v0.0.1 workflows.
+
+## Automatic Migration
+
+The easiest way to migrate is using the CLI tool:
+
+```bash
+# Migrate a single workflow
+workrail migrate my-workflow.json
+
+# Preview changes without modifying files
+workrail migrate my-workflow.json --dry-run
+
+# Create a backup of the original
+workrail migrate my-workflow.json --backup
+
+# Save to a different file
+workrail migrate my-workflow.json --output my-workflow-v0.1.0.json
+```
+
+## Manual Migration
+
+If you prefer to migrate manually:
+
+### 1. Add Version Field
+
+Add the `version` field to your workflow:
+
+```json
+{
+  "id": "my-workflow",
+  "name": "My Workflow",
+  "description": "Does something useful",
+  "version": "0.1.0",  // Add this line
+  "steps": [...]
+}
+```
+
+### 2. Identify Loop Patterns
+
+Look for repetitive steps that could be replaced with loops:
+
+#### Before (v0.0.1):
+```json
+{
+  "steps": [
+    {
+      "id": "check-status-1",
+      "title": "Check Status (Attempt 1)",
+      "prompt": "Check if the operation is complete"
+    },
+    {
+      "id": "check-status-2", 
+      "title": "Check Status (Attempt 2)",
+      "prompt": "Check if the operation is complete"
+    },
+    {
+      "id": "check-status-3",
+      "title": "Check Status (Attempt 3)",
+      "prompt": "Check if the operation is complete"
+    }
+  ]
+}
+```
+
+#### After (v0.1.0):
+```json
+{
+  "steps": [
+    {
+      "id": "check-status-loop",
+      "type": "loop",
+      "title": "Check Status Until Complete",
+      "loop": {
+        "type": "for",
+        "count": 3,
+        "maxIterations": 3,
+        "iterationVar": "attempt"
+      },
+      "body": "check-status"
+    },
+    {
+      "id": "check-status",
+      "title": "Check Status",
+      "prompt": "Check if the operation is complete (Attempt {{attempt}})"
+    }
+  ]
+}
+```
+
+## Common Patterns to Migrate
+
+### Polling Pattern
+Look for: Multiple steps checking status repeatedly  
+Replace with: `while` loop with condition
+
+### Retry Pattern  
+Look for: Duplicate steps with "retry" or "attempt" in the name  
+Replace with: `for` loop with fixed count
+
+### Batch Processing
+Look for: Steps like "Process item 1", "Process item 2", etc.  
+Replace with: `forEach` loop over items
+
+### Search Pattern
+Look for: Sequential checks across multiple sources  
+Replace with: `until` loop with found condition
+
+## Validation
+
+After migration, validate your workflows:
+
+```bash
+workrail validate my-workflow.json
+```
+
+## Getting Help
+
+- See [Loop Documentation](../features/loops.md) for detailed loop syntax
+- Check [examples](../../workflows/examples/loops/) for working loop patterns
+- Run `workrail migrate --help` for CLI options
+
+## FAQ
+
+**Q: Do I have to migrate to v0.1.0?**  
+A: No, v0.0.1 workflows continue to work. Migration is optional but recommended for new features.
+
+**Q: Can I mix v0.0.1 and v0.1.0 workflows?**  
+A: Yes, Workrail handles both versions transparently.
+
+**Q: What if migration fails?**  
+A: The tool validates workflows before saving. Use `--dry-run` to preview changes safely.
+
+**Q: How do I know which version my workflow uses?**  
+A: Check for the `version` field. If missing, it's v0.0.1. The migrate tool also reports versions. 

package/docs/naming-conventions.md

@@ -0,0 +1,45 @@
+# Naming Conventions – Workflow Orchestration System
+
+> **Status:** Adopted – Phase 3 completion
+
+This document records the agreed-upon naming conventions and the result of the initial audit performed in Phase 3 of the refactor roadmap.
+
+---
+
+## 1  Coding-Symbol Conventions
+
+| Element                        | Convention            | Example                          |
+|--------------------------------|-----------------------|----------------------------------|
+| Classes / Types / Interfaces   | `PascalCase`          | `FileWorkflowStorage`            |
+| Functions & Variables          | `camelCase`           | `getWorkflowById()`              |
+| Constants (module scoped)      | `UPPER_SNAKE_CASE`    | `WORKFLOW_SCHEMA_PATH`           |
+| Enum members                   | `UPPER_SNAKE_CASE`    | `WORKFLOW_NOT_FOUND`             |
+| Error Classes                  | Suffix `Error`        | `WorkflowNotFoundError`          |
+
+## 2  File & Directory Names
+
+* **Files:** `snake_case` with `.ts` extension (e.g., `workflow_get.ts`).
+* **Directories:** `kebab-case` or lower-case single word (e.g., `workflow/`).
+
+Rationale: File names remain friendlier on case-insensitive file systems; underscores map 1-to-1 with existing tool names.
+
+## 3  Public API / JSON-RPC Methods
+
+* Tool method names follow `snake_case` as defined in the MCP spec (e.g., `workflow_list`).
+
+## 4  Audit Result (2025-07-10)
+
+The entire `src/` tree was inspected. Findings:
+
+| Category           | Issues Found | Resolution |
+|--------------------|--------------|------------|
+| File names         | **0**        | –          |
+| Export identifiers | **0**        | –          |
+| Enum / Const names | **0**        | –          |
+
+Conclusion: Codebase already adheres to the conventions above. No renames were required.
+
+## 5  Future Enforcement
+
+* ESLint rule set to be extended with `@typescript-eslint/naming-convention` to automatically enforce the table above.
+* Pull-request template updated to reference this document (TBD). 

package/docs/planning/README.md

@@ -0,0 +1,104 @@
+# Planning System
+
+This is the **general planning home** for WorkRail.
+
+Use it to capture ideas quickly, curate roadmap direction, and promote concrete work into execution-ready tickets without forcing every thought into a full implementation plan too early.
+
+## Planning layers
+
+### `docs/ideas/`
+
+Use for:
+
+- raw ideas
+- feature thoughts
+- open questions
+- design seeds
+- things worth remembering before they are prioritized
+
+This is the **official dumpground** for product and system ideas.
+
+### `docs/roadmap/`
+
+Use for:
+
+- curated direction
+- now / next / later views
+- major bets
+- cross-cutting product themes
+
+Roadmap docs should stay **selective**. Not every idea belongs here.
+
+### `docs/tickets/`
+
+Use for:
+
+- execution-ready work
+- scoped problems
+- acceptance criteria
+- clear non-goals
+- risks or follow-ups
+
+If an item is ready to build, it should probably become a ticket.
+
+## Graduation path
+
+Default flow:
+
+1. `ideas` — capture it fast
+2. `roadmap` — decide if it matters strategically
+3. `tickets` — define the work clearly enough to execute
+
+Not every idea must become a roadmap item.  
+Not every roadmap item must become a ticket immediately.
+
+## Status ownership
+
+**Status lives in exactly two places**: `docs/roadmap/open-work-inventory.md` and `docs/roadmap/now-next-later.md`.
+
+Plan docs in `docs/plans/` describe **design and intent** -- not current status. When work ships, update the roadmap docs, not the plan doc. Plan docs that carry their own status blocks create a second source of truth that drifts.
+
+## Rules of thumb
+
+- **Idea**: "This might be valuable."
+- **Roadmap item**: "We likely want this."
+- **Ticket**: "We understand this well enough to build."
+
+## Docs vs GitHub
+
+Use **docs** for:
+
+- ideas
+- design
+- roadmap thinking
+- synthesis
+- long-form reasoning
+
+Use **GitHub issues** for:
+
+- concrete execution-ready work
+- bugs with enough detail to investigate
+- chores or features that are scoped clearly enough to do
+
+Use **pull requests** for:
+
+- the implementation record
+- review
+- closure of execution work
+
+Do not move all design/idea material into GitHub.  
+GitHub should primarily track **work**, while docs remain the home for **thinking**.
+
+## Existing planning docs
+
+Existing feature-specific plans in `docs/plans/` still matter. Treat them as **focused initiative plans**, not as the general inbox for new thoughts.
+
+## Starting points
+
+- `docs/ideas/backlog.md`
+- `docs/roadmap/now-next-later.md`
+- `docs/roadmap/open-work-inventory.md`
+- `docs/roadmap/legacy-planning-status.md`
+- `docs/planning/docs-taxonomy-and-migration-plan.md`
+- `docs/tickets/README.md`
+- `docs/tickets/next-up.md`

package/docs/planning/github-ticketing-playbook.md

@@ -0,0 +1,195 @@
+# GitHub Ticketing Playbook
+
+This is the **Phase 1 operating playbook** for the single-dev, agent-assisted GitHub workflow.
+
+It is intentionally lightweight and follows the current design in `docs/plans/agent-managed-ticketing-design.md`.
+
+## Current model
+
+- ideas live first in `docs/ideas/backlog.md`
+- GitHub issues track concrete work
+- labels stay minimal
+- the developer chooses what becomes active
+- agents help when explicitly pointed at a ticket
+
+## Phase 1 labels
+
+### Type
+
+- `feature`
+- `bug`
+- `chore`
+
+### State
+
+- `next`
+- `active`
+- `blocked`
+
+### Label application note
+
+The single GitHub issue form captures **work type**, but GitHub does not automatically map that dropdown to labels.
+
+In Phase 1, apply labels manually after issue creation or with the CLI.
+
+## One-time setup checklist
+
+When enabling this workflow in a repo, make sure these are in place:
+
+- create the Phase 1 labels
+- verify `.github/ISSUE_TEMPLATE/work-item.yml` exists
+- verify `.github/pull_request_template.md` exists
+- verify the team knows `docs/ideas/backlog.md` is still the home for fuzzy ideas
+
+## Phase 1 issue shape
+
+Every issue intended for execution should contain:
+
+- **Problem**
+- **Goal**
+- **Acceptance criteria**
+- **Verification**
+- **Non-goals**
+- **Context**
+
+Optional when an agent may execute it later:
+
+- **Agent execution note**
+
+## When to create an issue
+
+Create a GitHub issue when:
+
+- it is a real candidate for near- or medium-term work
+- it is a confirmed bug with enough detail to investigate
+- it is important follow-up discovered during active implementation
+- you explicitly want it tracked in GitHub
+
+Keep it in `docs/ideas/backlog.md` instead when it is still fuzzy or speculative.
+
+## When something is `next`
+
+An issue is ready for `next` when:
+
+- the problem is understandable
+- the goal is understandable
+- acceptance criteria exist
+- verification exists
+- non-goals exist
+- no unresolved decision blocks normal execution
+
+## When something is `blocked`
+
+If you add `blocked`, add a short comment that says:
+
+- what is blocked
+- the kind of block: `decision`, `dependency`, `context`, or `external/tooling`
+- the next thing needed to unblock it
+
+## Closure rule
+
+Close an issue only when:
+
+- a PR landed and the acceptance criteria were actually satisfied
+- it was intentionally closed with a clear no-code resolution
+- it was superseded by another explicitly linked issue
+
+Before closure:
+
+- verify acceptance criteria
+- verify the verification step actually happened
+- confirm scope did not silently expand past the non-goals
+
+Default rule:
+
+- the developer closes issues by default
+- an agent may close only when closure is clearly mechanical and verification is explicit
+
+## Minimal CLI flow
+
+### Create an issue
+
+```bash
+gh issue create
+```
+
+### Add labels to an issue
+
+```bash
+gh issue edit <number> --add-label feature,next
+```
+
+### List open issues
+
+```bash
+gh issue list
+```
+
+### View one issue
+
+```bash
+gh issue view <number>
+```
+
+### Comment on progress or blockers
+
+```bash
+gh issue comment <number> --body "Blocked on dependency. Kind: dependency. Next needed: merge #123."
+```
+
+### Open a PR
+
+```bash
+gh pr create
+```
+
+## How to hand an issue to an agent
+
+In Phase 1, the developer chooses the issue and explicitly hands it to the agent.
+
+### Suggested prompt
+
+Use something like:
+
+> Work GitHub issue `#129`. Read the issue first, follow its acceptance criteria and non-goals, make the code changes, run the relevant verification, and open a PR that references the issue.
+
+### Expected flow
+
+1. Pick the issue you want worked
+2. Have the agent read the issue
+3. Mark it `active` when work actually begins
+4. Agent implements the change
+5. Agent reports blockers in the issue if needed
+6. Agent opens a PR that references the issue
+7. Close the issue after the PR lands and verification is explicit
+
+### If the issue becomes blocked
+
+Add a short comment that says:
+
+- what is blocked
+- the kind of block: `decision`, `dependency`, `context`, or `external/tooling`
+- the next thing needed to unblock it
+
+### Phase 1 reminder
+
+Agents do **not** pick backlog work on their own in this mode.  
+They help when you explicitly point them at a ticket.
+
+### Create the Phase 1 labels (one-time setup)
+
+```bash
+gh label create feature --color 0e8a16 --description "New capability or user-visible improvement"
+gh label create bug --color d73a4a --description "Something is wrong"
+gh label create chore --color 6f42c1 --description "Maintenance or repo upkeep"
+gh label create next --color 1d76db --description "Good candidate for upcoming work"
+gh label create active --color fbca04 --description "Currently being worked"
+gh label create blocked --color b60205 --description "Cannot proceed until something changes"
+```
+
+## Practical defaults
+
+- keep `next` small
+- usually keep only one `active` issue
+- use labels for status, not long status prose
+- use issue bodies for the real contract

package/docs/plans/README.md

@@ -0,0 +1,24 @@
+# Initiative Plans
+
+Use this directory for **active initiative-specific plan and design docs**.
+
+Good fits:
+
+- canonical roadmap/status doc for one initiative
+- canonical design doc for one initiative
+- focused live initiative plans that are still relevant
+
+Do **not** use this directory for:
+
+- general planning system docs
+- cross-cutting roadmap prioritization
+- raw ideas
+- old duplicated entrypoints that should no longer be treated as current truth
+
+## Rule of thumb
+
+- `docs/plans/` = initiative-specific canon
+- `docs/roadmap/` = cross-cutting priority and status views
+- `docs/planning/` = meta-docs about how planning works
+
+If a doc cluster grows, prefer consolidating it into **one roadmap doc + one design doc** rather than letting many overlapping entrypoints accumulate.