Workflow commands

Entry point and getting-started guide. Run this if you don't know which command to use — it explains effectum in 60 seconds and points you to the right next step.

• Overview of the effectum workflow in plain language
• Detects your current project state and recommends a starting point
• Links to /next for smart routing after you're oriented
• Safe to run at any time — read-only, no side effects

Alias for /effectum. Use /help or /effectum interchangeably — both run the getting-started guide and orientation flow.

• Identical to /effectum — same output, same behavior
• Use whichever feels more natural to you
• Recommended alias for quick orientation in any session

Reads your project state and recommends exactly one action. The smart router that keeps you moving forward without having to remember the full workflow.

• Reads CLAUDE.md, git log, loop-state.json, and PRD status
• Recommends one specific command with a one-line reason
• Never overwhelming — one recommendation, always actionable
• Re-run at any time when you're not sure what to do next

Reads your specification, explores the existing codebase, and creates a detailed implementation plan. Surfaces risks, asks clarifying questions, and identifies the right order of operations.

• Analyzes PRD acceptance criteria, data model, and API design
• Creates step-by-step implementation plan with dependencies
• Identifies risks and open questions
• Waits for your explicit approval before writing any code

Enforces test-driven development. Writes a failing test, implements the minimum code to pass it, then refactors. Repeats for each acceptance criterion.

• RED: write a failing test for the next AC
• GREEN: implement minimum code to pass
• REFACTOR: improve without changing behavior
• Targets 80%+ coverage on new code

Runs all 8 quality gates in sequence and reports pass/fail for each. These are requirements, not suggestions. A feature is not done until all gates pass.

• Build (0 errors), Types (0 errors), Lint (0 warnings)
• Tests (all pass, 80%+ coverage)
• Security (no OWASP vulnerabilities)
• Debug logs (0 console.log), Type safety (no any/as), File size (max 300 lines)

Security audit and architecture validation. Reviews every change for OWASP vulnerabilities, code quality violations, architecture rule breaches, and common mistakes.

• OWASP Top 10 vulnerability scanning
• Architecture and design pattern validation
• RLS policy completeness check (Supabase)
• Rates findings: Critical, Warning, Info

Generates and runs end-to-end tests using Playwright. Tests real user flows through browser automation — page loads, navigation, form submissions, and critical journeys.

• Auto-generates Playwright test scripts
• Tests critical user journeys end-to-end
• Captures screenshots and traces on failure
• Uses accessibility-tree selectors for stability

Reads build error output, identifies root causes, and applies targeted fixes. Works incrementally — fixes one error at a time, rebuilds, and repeats.

• Reads full error messages and stack traces
• Identifies root cause before attempting fixes
• Applies targeted changes, not broad rewrites
• Rebuilds after each fix to verify

Removes dead code, unused imports, and unnecessary complexity. Runs tests before and after every change to ensure nothing breaks.

• Identifies unused exports, imports, and variables
• Consolidates similar functions
• Improves naming without changing behavior
• Tests before and after every change

The most powerful feature. Claude works autonomously — writing code, running tests, fixing errors — until every quality gate passes and your completion promise is 100% true. (internally: /ralph-loop)

• Iterates: read spec → check state → implement → verify → repeat
• Stuck detection: stops on 2 consecutive identical errors
• Status report at 80% of max iterations
• Only outputs completion promise when genuinely true

Stops an active autonomous build session. Use when you want to take over manually, change direction, or if the loop is not converging. (internally: /cancel-ralph)

• Immediately stops the autonomous loop
• Preserves all work done so far
• Git history shows every iteration
• Resume with a new /run if needed

Creates a git restore point with a descriptive tag. Use before /run, risky changes, or experiments so you can always roll back. (internally: /checkpoint)

• Creates a tagged git commit as restore point
• Descriptive tag for easy identification
• Roll back with a single git command
• Zero cost — just a commit and tag

Reads all loop artifacts — HANDOFF.md, STUCK.md, loop-state.json, effectum-metrics.json, git log — and outputs a structured failure diagnosis. (internally: /forensics)

• Classifies failure mode: stuck, context budget, build error, or unknown
• Reads loop-state.json for last known iteration state
• Cross-references effectum-metrics.json for historical patterns
• Outputs FORENSICS-YYYY-MM-DD.md with recommended next steps

Creates agent teams for parallel complex feature development. Spawns independent Claude instances that work on separate workstreams simultaneously.

• Spawns parallel teammates for independent workstreams
• Each teammate inherits all hooks and guardrails
• Teammates communicate via mailbox and shared task list
• Merges results when all workstreams complete

Start a new guided specification from scratch. Claude asks adaptive questions until it fully understands what you want to build.

• Adaptive questioning based on your domain and complexity
• Guided discovery for vague or unclear requirements
• Produces a structured PRD with acceptance criteria and data model
• Supports both workshop mode (12–15 questions) and quick entry

Fast one-shot spec from clear requirements. Best when you already know exactly what you want to build.

• Generates a complete PRD from a one-liner or short description
• Skips discovery questions — goes straight to spec output
• Same structured format as effect:prd:new
• Best for well-understood features with clear scope

Deep-dive into a specific area of your spec. Explore edge cases, data models, or API design in detail before writing code.

• Focuses on one section of an existing PRD
• Surfaces edge cases and implicit assumptions
• Updates the PRD with insights from the discussion
• Useful before effect:dev:plan on complex features

Split large projects into smaller, independently buildable PRDs. Each sub-PRD is self-contained with its own acceptance criteria.

• Analyzes scope and identifies natural split points
• Creates sub-PRDs with no cross-dependencies where possible
• Generates a dependency graph for sequencing
• Each sub-PRD is independently runnable with effect:dev:run (or /ralph-loop)

Quality check before handing off to implementation. Flags missing acceptance criteria, vague goals, and incomplete data models.

• Checks every AC has a matching test
• Flags vague goals that can't be verified
• Validates data model completeness and RLS policies
• Confirms completion promise is 100% verifiable

Safely update an existing PRD in-place. Tracks changes semantically and triggers a delta handoff so implementation stays in sync.

• Detects and records what changed vs the previous version
• Updates PRD hash and version in frontmatter
• Triggers delta handoff to flag affected acceptance criteria
• Safe for specs already in progress — preserves completion state

Export a finished spec to the target project. Copies the PRD file and prepares it for effect:dev:plan in the implementation project.

• Copies PRD from workshop to target project
• Validates PRD is complete before export
• Sets status to 'ready' in frontmatter
• Outputs the effect:dev:plan command to run next

View all projects and their current progress. Shows which specs are draft, ready, in progress, or complete.

• Lists all projects under workshop/projects/
• Shows PRD count and status per project
• Highlights stalled or incomplete specs
• Quick overview before starting a new build session

Continue working on a previous specification. Loads context and picks up where you left off.

• Reads the current PRD state and git log
• Summarizes what's done and what remains
• Identifies the next logical step
• Works with any PRD in any status

Render PRD dependencies as an interactive HTML map. Dark/light theme, direction toggle, and SVG export built in.

• Generates an interactive HTML file from PRD frontmatter
• Supports dark/light theme and direction toggle
• SVG export for documentation
• Detects cycles and orphaned PRDs

Generate a handoff prompt for a completed PRD. Use to start a new Claude session focused on one specific feature.

• Extracts the essential context from a PRD
• Formats as a ready-to-paste Claude session opener
• Includes acceptance criteria and completion promise
• Optimized for minimal context burn

Runs 6 parallel agents to analyze an existing codebase — dependencies, structure, patterns, environment, tests, and docs — then generates a complete CLAUDE.md and PRDs.

• 6 parallel agents: Stack, Architecture, API, Database, Frontend, Test
• Auto-generates CLAUDE.md from analysis results
• Creates PRDs from existing code and architecture
• Works on any codebase, any language

Review onboarded PRDs for cross-PRD consistency, duplicates, and best practices. Runs automatically as part of /onboard but can be run standalone.

• 6 checks: completeness, duplicates, naming, data model, API, status
• Supports --fix flag to automatically apply suggested fixes
• Supports --strict flag to treat warnings as failures
• Safe to run on any project with onboarded PRDs

Spawns 4 parallel agents (ArchitectureMapper, StackMapper, QualityMapper, IntegrationMapper) to produce 7 structured knowledge documents. (internally: /map-codebase)

• 4 agents run in parallel: ArchitectureMapper, StackMapper, QualityMapper, IntegrationMapper
• Produces 7 docs: ARCHITECTURE.md, STACK.md, STRUCTURE.md, CONVENTIONS.md, TESTING.md, CONCERNS.md, INTEGRATIONS.md
• All output written to knowledge/codebase/
• Use before /onboard on complex legacy codebases

Create the complete directory structure and template files for a new project in the PRD Workshop. Replaces /workshop:init with a cleaner namespace.

• Creates workshop/projects/{slug}/ with standard layout
• Generates project README and initial PRD directory
• Validates slug format before creating
• Run before effect:prd:new on new workshop projects

Archive a completed or abandoned project by moving it to workshop/archive/. Replaces /workshop:archive with a cleaner namespace.

• Moves project from workshop/projects/ to workshop/archive/
• Checks readiness before archiving (no in-progress PRDs)
• Preserves full history — nothing is deleted
• Can be listed and referenced after archiving

Interactive 7-question interview to populate the sentinel block in CLAUDE.md with project-specific context. Replaces /effectum:init with a cleaner namespace.

• Asks about domain, key entities, auth, architecture, conventions, tech debt
• Writes ONLY inside the sentinel block markers
• Survives effectum update — custom content preserved
• Run once on new projects, re-run after major pivots

Generates a structured DESIGN.md for frontend-heavy projects. Detects existing design signals (Tailwind, shadcn, CSS vars), asks 3–5 lightweight questions, and produces a visual source of truth for UI work.

• Reads current PRD and scans for Tailwind, shadcn, CSS variables
• Asks 3–5 questions: color palette, typography feel, UI complexity
• Generates DESIGN.md with 7 sections: colors, typography, components, layout, interactions, constraints
• Reduces UI rework by making design decisions explicit before implementation

Reconfigures an existing effectum installation. Change stack, update guardrails, or adjust settings without starting from scratch.

• Switch or update your stack preset
• Regenerate CLAUDE.md with new options
• Update guardrails and quality gates
• Preserves existing customizations where possible