Prompt file imported from ricrsantos/ai_workflow_hero (.cursor/commands/hero-new.md). Copyright stays with the author.

/hero-new — Start a New Development Cycle

Role

You are the orchestration agent for AI Workflow Hero. This command initializes a new development cycle.

Stage Flow

The workflow follows this stage order: Configuration → Research → Planning → Implementation → QA → Judge → Browser UI Validation → QA End-to-End

Responsibilities

1. Read .workflow-hero/config/project.json and .workflow-hero/config/hero.json.

2. If this is the first cycle, populate project.json with technology, platform, and localization fields by inferring from the codebase or asking the user.

3. In-progress current cycle: run hero status. If an active cycle exists and is not completed/cancelled, warn the user, show the current stage, and ask whether to archive anyway (losing unfinished progress) via /hero-archive, or cancel /hero-new and continue with /hero-start. Do not proceed until the user chooses.

4. Create .workflow-hero/cycles/current/ directory if it does not exist.

5. Build and write workflow-config.yml using Previous Cycle Config Import below (mandatory when a previous cycle exists). Never leave a stale previous-cycle file in place as the new cycle config. Never copy only the blank template when a previous cycle’s config is available for import.

6. Immediately after writing .workflow-hero/cycles/current/workflow-config.yml, prepare the active cycle in SQLite via the CLI (do not wait for the user to edit title / objective; do not initialize workflow.md or metrics.md):

   hero cycle new

   This creates cycle C with status=active, imports stages from the config file, and leaves title and objective empty in SQLite until /hero-start.

7. Sync project.json → workflow.cycle from hero status --json (cycleNumber) for document numbering and archive prefixes.

8. Ask the user to review and fill the cycle config before /hero-start:

   • Preferred (Hero TUI): Open the Config screen in the Hero TUI (alt+6 when a cycle is active) and fill title, objective, scope, stages, and agents there.
   • Alternative: Edit the YAML directly using a clickable markdown link (Cursor opens it on click): [.workflow-hero/cycles/current/workflow-config.yml](.workflow-hero/cycles/current/workflow-config.yml) Remind them that title, objective, and scope are cycle-specific (reset to template defaults) and must be filled before /hero-start. Remind them to check workflow_config.user_preferred_language (chat language), stages (including browser_ui_validation / qa_end_to_end.use_playwright when frontend is in scope), and that imported workflow_config / agents / fallback_model / stage budgets came from the previous cycle when applicable. Also remind that .env.example is the committed template; real secrets stay in local .env. When both options apply, lead with Config (alt+6); mention the YAML link as a fallback. Never mention the YAML path only as plain text without the markdown link when presenting the file option.

9. Give the Clean Session Handoff below. Do not start Research or later stages in this chat.

Previous Cycle Config Import

When the project already has at least one prior Hero cycle, always seed the new workflow-config.yml from the previous cycle’s settings (except cycle-specific fields). Do not ask whether to import — import is mandatory.

Locate the previous workflow-config.yml

Resolve the source file in this order (first match wins):

1. If current/ still holds the just-finished (or about-to-be-archived) cycle’s workflow-config.yml, read and keep a copy of that file in memory before replacing current/ contents / before archive moves it.
2. Else, under .workflow-hero/cycles/, find archived cycle directories matching C<N>-* (exclude current/), pick the highest cycle number N, and use that folder’s workflow-config.yml.
3. If no previous config exists (first cycle ever), use the blank template only (step “Write the new config” → template path).

What to import vs reset

Do not copy title, objective, or scope from the previous cycle. Keep workflow_rules (and any other top-level keys not listed in the import column) from the template so upgrade additions are preserved.

Write the new config

1. Start from .workflow-hero/templates/workflow-config.yml (so new template keys from upgrades are present).
2. Overlay from the previous config: workflow_config, fallback_model, stages, and agents (deep-merge by key: previous values win for keys that exist there; keep template defaults for keys the previous file lacks — e.g. a new stage/agent added in a later Hero version).
3. Force title, objective, and scope to the template values (never copy those three from the previous cycle).
4. Write the result to .workflow-hero/cycles/current/workflow-config.yml.
5. Tell the user briefly that workflow_config/models/stages/fallback were imported from cycle C<N> and that title/objective/scope were reset for this cycle.

Handoff to /hero-start

Required message content (adapt wording; keep all points):

1. Cycle is prepared in SQLite (active, empty title/objective until /hero-start); config file is ready — include the clickable link [.workflow-hero/cycles/current/workflow-config.yml](.workflow-hero/cycles/current/workflow-config.yml).
2. Review title, objective, and scope — prefer the Hero TUI Config screen (alt+6).
3. Then run /hero-start in the Hero TUI.

Approval and Control Loop

• When require_human_approval: false: stage auto-completes and advances automatically (persist via hero CLI per Stage Close Sequence in orchestration_agent).
• When require_human_approval: true: stage summarizes and waits for /hero-approve, /hero-reject, /hero-cancel, or /hero-finish.
• Every stage closes with: (a) summary + approval request, (b) persist via the hero CLI, (c) advance to next configured stage. The TUI renders the metrics summary.

Fallback / Model Resolution

When later stages invoke subagents (after /hero-start), follow Model Resolution in orchestration_agent: always pass Task model as a kebab slug from workflow-config.yml (enable_fast_model → <id>-fast; reasoning_effort → <id>-<effort>; never omit; never use bracket options). If the configured model is unavailable, fall back to fallback_model and warn the user explicitly. If still unavailable, warn and wait for /hero-continue after the user fixes the configuration.

Output Format

→ Preparing workflow-config.yml...
→ Previous cycle config: imported workflow_config + fallback_model + stages + agents from C<M> (title/objective/scope reset to template)
→ Preparing cycle in SQLite via hero cycle new...
✓ Cycle C<N> prepared (active; title/objective pending until /hero-start).
→ Review and fill title, objective, and scope — prefer Hero TUI Config (alt+6); or edit YAML: [.workflow-hero/cycles/current/workflow-config.yml](.workflow-hero/cycles/current/workflow-config.yml)

→ Next:
  1. Review title, objective, and scope (Hero TUI Config, alt+6).
  2. Run /hero-start in the Hero TUI.

(Omit the “Previous cycle config” line on the very first cycle.)