tzachbon/smart-ralph

# Communication Style

## Core Rule

**Be extremely concise. Sacrifice grammar for concision.**

## Why

- Plans shouldn't be novels
- Terminal reads bottom-up
- Scanning > reading
- Less tokens = faster, cheaper

## Output Rules

# Delegation Principle

## Core Rule

**YOU MUST NEVER IMPLEMENT ANYTHING YOURSELF**

The main agent (you) is a **coordinator**, not an implementer.

## Your ONLY Role

1. Parse user input, determine intent
2. Read state files for context
3. **Delegate ALL work to subagents via Task tool**
4. Report results to user

# Smart Ralph

Core skill for all Ralph plugins. Defines common arguments, execution modes, and shared behaviors.

## Common Arguments

All Ralph commands support these standard arguments:

| Argument | Short | Description | Default |
|----------|-------|-------------|---------|
| `--quick` | `-q` | Skip interactive phases, auto-generate artifacts, start execution immediately | false |
| `--commit` | `-c` | Commit and push spec/feature files after generation | true (normal), false (quick) |
| `--no-commit` | | Explicitly disable committing files | - |
| `--max-task-iterations` | `-m` | Max retries per failed task before stopping | 5 |

# SpecKit Workflow

The SpecKit methodology is a constitution-driven approach to feature development. It ensures consistency across features by grounding all decisions in project principles.

## Core Philosophy

**Constitution First**: Every feature is designed against the project's constitution - a living document of principles, constraints, and standards.

**Governance Over Convention**: Rather than implicit patterns, SpecKit makes governance explicit through:
- Constitution principles (MUST, SHOULD, MAY)
- Feature specifications tied to principles
- Quality checklists as "unit tests for requirements"
- Consistency analysis across artifacts

# Codex interview framework

Run every normal-mode `start`, `triage`, `research`, `requirements`, `design`, and `tasks` phase through `references/algorithm.md` and `references/domain-modeling.md`.

## Completion criterion

Delegate only after all of these conditions hold for one identity tuple:

- `phase`, `interviewId`, `discoveryRevision`, and `contextDigest` match in state and in the delegation packet.
- The selected skill manifest has status `complete` or `partial_warned`.
- The phase interview has status `complete` or `skipped` after explicit final approval.
- `phase_gate.py check-delegation` succeeds.

## Hard-transition invariant

# Ralph Specum

Use this as the primary Codex surface for Ralph Specum. It carries the full reusable workflow and can handle the entire command surface directly when helper skills are not installed.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill: take the directory containing `SKILL.md`, then its parent `skills` directory, then the next parent. Never derive the plugin root from the project working directory.

## Read These References

- `"$RALPH_CODEX_PLUGIN_ROOT/references/workflow.md"` for the phase flow, branch and worktree behavior, quick mode, and command routing
- `"$RALPH_CODEX_PLUGIN_ROOT/references/state-contract.md"` for `.ralph-state.json`, `.progress.md`, commit rules, and resume semantics
- `"$RALPH_CODEX_PLUGIN_ROOT/references/path-resolution.md"` for `specs_dirs`, `.current-spec`, ambiguity handling, and default directory behavior
- `"$RALPH_CODEX_PLUGIN_ROOT/references/parity-matrix.md"` for Claude-to-Codex feature translation and command mapping
- `"$RALPH_CODEX_PLUGIN_ROOT/references/prototype-coordinator.md"` for direct, suggested, resume, quick, cancel, and prototype handoff behavior
- `"$RALPH_CODEX_PLUGIN_ROOT/skills/interview-framework-codex/SKILL.md"` and its required algorithm and domain-modeling references for every normal-mode phase interview

# Ralph Specum Cancel

Use this to stop execution safely and optionally remove a spec. Safe cancel preserves the spec and every prototype source path.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Resolve the target by explicit path, exact name, or `.current-spec`
- Treat a missing `activePrototypes` field as an empty map
- Publish reviewed immutable cancellation evidence before removing active state
- Confirm the exact local target before any deletion
- Never delete a remote branch or perform another remote action
- Do not guess on ambiguous names

# Ralph Specum Design

You are a **coordinator, not an architect** -- delegate ALL work to an `architect-reviewer` sub-agent.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Resolve the active spec by explicit path, exact name, or `.current-spec`
- Require `requirements.md`
- Merge state fields only
- Keep the Ralph disk contract unchanged

## Action

# Ralph Specum Feedback

Use this to capture product feedback or bug reports for Ralph Specum.

## Action

1. Summarize the issue, request, or missing behavior.
2. Gather the minimum reproducible context, affected files, commands, environment details, and whether the issue is on the Codex package or Claude plugin surface.
3. If `gh` is available and the user wants submission, create a GitHub issue.
4. If `gh` is unavailable or the user only wants a draft, produce a ready-to-paste issue body and the repository issue URL.

## Output

Keep the report concrete. Include expected behavior, actual behavior, reproduction steps, and any relevant state files or logs.

# Ralph Specum Help

Use this to explain the Ralph Specum surface in Codex.

## Cover

- Primary skill: `$ralph-specum`
- Helper skills: `$ralph-specum-start`, `$ralph-specum-triage`, `$ralph-specum-research`, `$ralph-specum-requirements`, `$ralph-specum-design`, `$ralph-specum-tasks`, `$ralph-specum-prototype`, `$ralph-specum-implement`, `$ralph-specum-status`, `$ralph-specum-switch`, `$ralph-specum-cancel`, `$ralph-specum-index`, `$ralph-specum-refactor`, `$ralph-specum-feedback`, `$ralph-specum-help`
- Normal flow: start goal grill, approval, research, artifact approval, requirements grill, approval, design grill, approval, tasks grill, approval, implement
- Large effort flow: triage, then start each unblocked spec
- Quick mode: only exact `--quick` bypasses interview questions; exact `--interactive` clears it. Discovery, skill loads, and artifact write gates still run
- Disk contract: `./specs` or configured roots, `.current-spec`, optional `.current-epic`, per-spec markdown files, `.ralph-state.json`

## Optional Prototype Overlay

# Ralph Specum Implement

You are a **coordinator, not an executor** -- delegate each task to a `spec-executor` sub-agent.

## Contract

- Resolve the active spec by explicit path, exact name, or `.current-spec`
- Require `tasks.md`
- Recompute task counts from disk before execution
- Merge state fields only
- Reconcile prototype records before dispatch and block only dependent work
- Remove `.ralph-state.json` only when all tasks are complete, verified, and `activePrototypes` is empty

## Action

# Ralph Specum Index

Use this to generate searchable index specs for an existing codebase.

## Contract

- Index output lives under `specs/.index/`
- Use stable Ralph templates for `index.md`, component specs, and external specs
- Keep component and external entries deterministic and easy to diff

## Action

1. Parse the user scope such as path, types, excludes, quick mode, dry run, or force.
2. Scan the requested code areas for controllers, services, models, helpers, migrations, or comparable project structures.

# Ralph Specum Prototype

Coordinate one optional prototype overlay. Delegate source work to a child agent and keep the main Ralph phase unchanged until the recorded handoff.

## Load the contract

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill: take the directory containing `SKILL.md`, then its parent `skills` directory, then the next parent. Never derive the plugin root from the project working directory.

Read `../../references/prototype-coordinator.md` from this skill directory completely before any prototype mutation. Treat it as the source of truth for direct, suggested, resume, quick, cancel, isolation, review, publication, and handoff behavior.

## Route the request

1. Resolve an explicit path, exact spec name, or `.current-spec` with `"$RALPH_CODEX_PLUGIN_ROOT/scripts/resolve_spec_paths.py"`. Use only the returned `basePath`, `specRoot`, settings, and warnings.
2. Parse one mode: direct by default, suggested with a return phase, resume by ID, quick, or cancel by ID.

# Ralph Specum Refactor

You are a **coordinator, not a refactor specialist** -- delegate spec revision to a `refactor-specialist` sub-agent.

## Contract

- Resolve the active spec by explicit path, exact name, or `.current-spec`
- Review files in order: `requirements.md`, `design.md`, `tasks.md`
- Cascade downstream updates when upstream content changes
- Reconcile `activePrototypes` and preserve unrelated refactor work

## Action

1. Resolve the target spec.

# Ralph Specum Requirements

You are a **coordinator, not a product manager** -- delegate ALL work to a `product-manager` sub-agent.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Resolve the active spec by explicit path, exact name, or `.current-spec`
- Require the spec directory to exist
- Merge state fields only
- Keep the Ralph disk contract unchanged

## Action

# Ralph Specum Research

You are a **coordinator, not a researcher** -- delegate ALL work to a `research-analyst` sub-agent.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Resolve the active spec by explicit path, exact name, or `.current-spec`
- Respect `.claude/ralph-specum.local.md` when present
- Default specs root is `./specs`
- Keep the canonical Ralph file names
- Merge state fields only

# Ralph Specum Start

Use this for the `start` and `new` entrypoints.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Read `.claude/ralph-specum.local.md` when present
- Default specs root is `./specs`
- Keep `.current-spec` in the default specs root
- Keep the standard Ralph files stable
- Merge `.ralph-state.json`. Do not replace the full object

# Ralph Specum Status

Use this to report Ralph state across configured spec roots.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Read `.claude/ralph-specum.local.md` when present
- Default specs root is `./specs`
- `.current-spec` lives in the default specs root
- Hidden directories do not count as specs

## Action

# Ralph Specum Switch

Use this to switch the active spec.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Read `.claude/ralph-specum.local.md` when present
- Parse `specs_dirs` from frontmatter to discover all spec roots
- Treat the first `specs_dirs` entry as the default root
- Default specs root is `./specs`
- `.current-spec` lives in the default specs root
- Do not guess on ambiguous names

# Ralph Specum Tasks

You are a **coordinator, not a task planner** -- delegate ALL work to a `task-planner` sub-agent.

Derive `RALPH_CODEX_PLUGIN_ROOT` from this loaded skill by resolving two parent directories from the `SKILL.md` directory. Never derive it from the project working directory.

## Contract

- Resolve the active spec by explicit path, exact name, or `.current-spec`
- Require `requirements.md` and `design.md`
- Merge state fields only
- Keep the Ralph disk contract unchanged

## Action

# Ralph Specum Triage

You are a **coordinator, not a triage analyst** -- delegate decomposition work to a `triage-analyst` sub-agent.

## Contract

- Epic data lives under `specs/_epics/<epic-name>/`
- Track the active epic in `specs/.current-epic`
- Do not guess on ambiguous epic or spec names
- Triage produces a plan for multiple specs. It does not implement them

## Action

1. Parse exact `--quick` and exact `--interactive` tokens before routing. Reject both together, `-q`, variants, and natural-language substitutes.

# Communication Style

Be extremely concise. Sacrifice grammar for concision.

## Rationale

- Plans should not be novels
- Terminal reads bottom-up
- Scanning beats reading
- Fewer tokens = faster, cheaper

## Output Rules

### 1. Brevity First

# Interview Framework

Treat every normal-mode interview governed by this framework as a grill. Run the approval-gated interview for `start`, `triage`, `research`, `requirements`, `design`, and `tasks`. Treat this skill and its references as the single source of truth for interview behavior. Phase commands supply exploration territory and artifact context; they do not redefine the algorithm.

Quick mode bypasses interview questions only. It still requires current discovery, contract loading, bypass receipts, delegation checks, and artifact-agent load parity.

## Entry Contract

Before each new or resumed interview:

1. Complete the applicable skill discovery pass from `${CLAUDE_PLUGIN_ROOT}/references/normal-mode-gates.md`.
2. Reload this entire `SKILL.md`, `references/algorithm.md`, `references/domain-modeling.md`, every selected skill body, and every selected skill resource required for the current work. Load `references/examples.md` only when an example is needed.
3. Record the load manifest with `phase_gate.py record-skill-load`.
4. Begin or resume the interview with the matching phase, interview ID, discovery revision, and context digest.

# Reality Verification

For fix goals: reproduce the failure BEFORE work, verify resolution AFTER.

## Goal Detection

Classify user goals to determine if diagnosis is needed. See `references/goal-detection-patterns.md` for detailed patterns.

**Quick reference:**
- Fix indicators: fix, repair, resolve, debug, patch, broken, failing, error, bug
- Add indicators: add, create, build, implement, new
- Conflict resolution: If both present, treat as Fix

## Command Mapping

# Smart Ralph

Core skill for all Ralph plugins. Defines common arguments, execution modes, shared behaviors, and coordinator delegation rules.

## Common Arguments

All Ralph commands support these standard arguments:

| Argument | Short | Description | Default |
|----------|-------|-------------|---------|
| `--quick` | | Exact token that enables persistent non-interactive generation | false |
| `--interactive` | | Exact token that clears persistent quick mode | - |
| `--commit` | `-c` | Commit spec/feature files locally after generation | true (normal), false (quick) |
| `--no-commit` | | Explicitly disable committing files | - |

# Spec Workflow

Spec-driven development transforms feature requests into structured specs through sequential phases, then executes them task-by-task.

## Decision Tree: Where to Start

| Situation | Command |
|-----------|---------|
| New feature, want guidance | `/ralph-specum:start <name> <goal>` |
| New feature, skip interviews | `/ralph-specum:start <name> <goal> --quick` |
| Large feature needing decomposition | `/ralph-specum:triage <goal>` |
| Resume existing spec | `/ralph-specum:start` (auto-detects) |
| Jump to specific phase | `/ralph-specum:<phase>` |