dppdppd/rpm/init-rpm

/init-rpm — Full Instructions

Project setup and verification. First run creates rpm context for a project. Repeat runs verify that an existing rpm setup matches the latest expected layout and apply safe migrations.

Run once per project, or run again after installing rpm in a new agent runtime such as Codex. On repeat runs, do not re-ask first-run project context questions unless a required canonical file is missing and the answer cannot be inferred from existing files. If docs/rpm/context.md already exists, read it and augment — do not overwrite. Merge in missing sections only.

If any docs/rpm/ content already exists, treat this as an rpm migration/update, not a brand-new install. Preserve existing rpm files, create only missing canonical files (context.md, past/log.md, present/status.md, future/tasks.org, future/done.org, reviews/), and migrate legacy names when present:

• docs/rpm/FUTURE.org or docs/rpm/future/FUTURE.org -> docs/rpm/future/tasks.org
• docs/rpm/PRESENT.md or docs/rpm/present/PRESENT.md -> docs/rpm/present/status.md
• docs/rpm/RPM-LOG.md or docs/rpm/past/RPM-LOG.md -> docs/rpm/past/log.md
• docs/rpm/RPM.md -> docs/rpm/context.md

Narrate as you go. At each phase, tell the user what's about to happen in one short sentence before doing it — users should never be surprised by what /init-rpm creates or writes.

Phase 0: Introduce

Before running anything, detect whether this is a first run:

• If docs/rpm/ does not exist, use the first-run introduction below.
• If any docs/rpm/ content exists, this is a repeat run. Use the

verification introduction below, then follow Repeat-run verification mode.

First-run wording (adapt freely):

## /init-rpm — rpm first-run setup
 
I'll set up rpm (Relentless Project Manager) for this project. Here's
what I'm about to do:
 
1. Detect the project — language, tests, existing docs
2. Ask 1–3 questions I can't answer from the codebase
3. Create `docs/rpm/` scaffolding (context, trackers, past/future/reviews)
4. Create an agent instructions file if one is missing
5. Ask once for runtime permissions if the active agent supports them
6. Summarize what was created
 
Starting with detection.

Do NOT wait for confirmation — this is informative, not gating. Proceed immediately to Phase 1.

Repeat-run wording (adapt freely):

## /init-rpm — rpm setup verification
 
I found existing rpm state. I won't re-bootstrap this project or ask
first-run questions. I'll verify it against the latest rpm layout,
apply safe migrations for missing canonical files or legacy names, and
ask before changing agent guidance.
 
Starting with verification.

Do NOT wait for confirmation — this is informative, not gating.

Repeat-run verification mode

Run this mode when docs/rpm/ exists, docs/rpm/context.md exists, or any legacy rpm file exists (docs/rpm/RPM.md, docs/rpm/FUTURE.org, docs/rpm/PRESENT.md, docs/rpm/RPM-LOG.md).

1. Scan current state. Run the Phase 1 detector and read existing

docs/rpm/context.md, docs/rpm/present/status.md, docs/rpm/future/tasks.org, docs/rpm/future/done.org, and docs/rpm/past/log.md only when they exist.

1. Verify canonical rpm files. Create only missing canonical

files/directories:

• docs/rpm/context.md
• docs/rpm/past/log.md
• docs/rpm/present/status.md
• docs/rpm/future/tasks.org
• docs/rpm/future/done.org
• docs/rpm/reviews/

1. Apply safe legacy migrations. Move legacy names listed above

to the canonical paths only when the canonical target is missing. If both old and new paths exist, do not overwrite; report the old path as leftover legacy state.

1. Repair stale configs. Run the unified repair pass — see

the Phase 4a: Repair stale configs section below. It brings .gitignore and AGENTS.md in line with the current rpm layout (wildcard ignore rule + # include: directive for Codex).

1. Verify agent guidance layout. If CLAUDE.md exists and

AGENTS.md is missing or CLAUDE.md appears to contain general project guidance, ask the Claude guidance migration question from Phase 4. Do not move guidance without confirmation.

1. Verify runtime-specific permissions. Run Phase 6 checks, but

only apply permission changes for runtimes that support them.

1. Verify current-session activation. Ensure

docs/rpm/~rpm-session-start exists for the current session when the active runtime uses rpm lifecycle hooks.

1. Summarize and stop. Print:

``` ## /init-rpm verification complete

Verified: {list} Created: {list or "nothing"} Migrated: {list or "nothing"} Repaired: {list or "nothing"} Needs attention: {list or "nothing"} ```

Do not continue into the first-run Phase 2 question flow after repeat verification mode completes.

Phase 1: Detect Project State

Say to user: "Scanning the project…"

!bash "${CLAUDE_SKILL_DIR}/scripts/detect.sh"

Classify silently (do NOT ask the user):

• GREENFIELD: Empty or near-empty directory
• EXISTING: Has source code, build system, tests
• HAS_AGENT_INSTRUCTIONS: Already has AGENTS.md, CLAUDE.md,

.cursorrules, or another project-level agent instructions file

Phase 2: Gather Project Context

Say to user: "A few quick questions I can't answer from the code:"

Ask the user ONLY these questions (skip any answerable from codebase). Ask one at a time — each question ends its response, and you wait for the answer before asking the next. Never stack multiple questions in a single response.

1. What is this project? (one sentence)
2. What's the tech stack? (or confirm what was detected)
3. What's the team size? (solo / small 2-5 / medium 5-10 / large 10+)

Do NOT ask more than 3 questions.

Phase 3: Create rpm Infrastructure

Say to user: "Creating the rpm scaffolding under docs/rpm/ — context.md, past/log.md, reviews/ directory."

Create or update these files:

3a. docs/rpm/context.md — project-local rpm context

Injected into every session via the SessionStart hook. Keep it under 30 lines — this is hot context, not documentation.

# {Project Name} — rpm Context
 
Injected at session start. Keep under 30 lines.
 
## Project Summary
{One paragraph: what, tech stack, stage, team size, key constraints}
 
## Key Files
| What | Where |
|------|-------|
{Table of important files discovered in Phase 1}
 
## Focus Areas for Review
{Project-specific dimensions to evaluate, adapted from what was
discovered. E.g., for a clean-room project: compliance checks.
For a startup: velocity vs quality tradeoffs.}
 
## Prior Findings
See `docs/rpm/past/log.md` Audit History.

3b. docs/rpm/past/log.md — append-only history

# rpm Log — {project name}
 
Append-only history of audits, reviews, and sessions.
Referenced from `docs/rpm/context.md` when needed.
 
## Audit History
 
## Sessions Reviewed
 
## Notes

3c. docs/rpm/reviews/ — plan file directory

mkdir -p docs/rpm/reviews

Phase 4: Scaffold Missing Project Infrastructure

Say to user: "Checking for missing project files (agent instructions, spec template, trackers) and creating only what isn't already there."

For each item below, check if it exists first. Only create what's missing. Never overwrite existing files.

Agent instructions file and Claude guidance migration

Target 60-120 lines for greenfield, up to 150 for existing projects. If an agent instructions file already exists, augment it only when a short rpm section is clearly missing; never overwrite it.

Default general-purpose target file:

• Codex: AGENTS.md
• opencode: AGENTS.md
• Unknown/generic runtime: AGENTS.md
• Claude Code: use AGENTS.md for general project/agent guidance

and keep CLAUDE.md only for Claude Code-exclusive directives.

If CLAUDE.md exists, do not silently leave general guidance trapped there. Tell the user:

I found `CLAUDE.md`. rpm works across Claude Code, Codex, and
opencode, so I want to move guidance that is not Claude-specific into
`AGENTS.md` and leave `CLAUDE.md` for Claude Code-only directives.
 
QUESTION: Move general guidance from `CLAUDE.md` to `AGENTS.md` now?
(`yes` / `no`)

If the user says yes:

1. Read CLAUDE.md and classify each section:

• General guidance: project summary, commands, architecture,

workflow, testing, guardrails, coding conventions, repository paths, domain notes, rpm process.

• Claude-exclusive guidance: Claude Code tool names, Claude

permissions, Claude hook behavior, Claude native tasks, Claude-specific slash-command mechanics, .claude/ settings, model-specific Claude instructions.

1. Create or update AGENTS.md with the general guidance. Preserve

existing AGENTS.md content and merge without duplication.

1. Rewrite CLAUDE.md so it keeps only Claude-exclusive directives

and includes this policy near the top:

```markdown # Claude Code Directives

General project and agent guidance belongs in AGENTS.md by default. Keep this file limited to Claude Code-exclusive directives: Claude-specific tools, hooks, permissions, native task behavior, and slash-command mechanics.

Claude Code should read AGENTS.md first, then apply the Claude-only directives below. ```

1. If there is no Claude-exclusive guidance, leave CLAUDE.md as the

policy stub above plus a short pointer to AGENTS.md.

If the user says no, preserve CLAUDE.md exactly as-is. Still create AGENTS.md if missing, using the template below, so future general guidance has a runtime-neutral home.

If only AGENTS.md exists, update it directly. If neither exists, create AGENTS.md from the template below. Do not create CLAUDE.md unless Claude Code-exclusive guidance exists or the project already had CLAUDE.md.

When creating a new AGENTS.md, keep the # include: directive at the very top of the file. It points to a transient session-context file written by the rpm SessionStart hook (docs/rpm/~rpm-context.md, deleted by /session-end). Codex runtimes that don't capture SessionStart stdout pick the context up through this include; Claude Code already receives the same content via the hook itself, so the line is harmless there.

When augmenting an existing AGENTS.md, add this # include: line near the top if it's missing — without it, the SessionStart context won't reach Codex agents in this project.

# include: docs/rpm/~rpm-context.md
 
# Project: {name}
 
{One-sentence description}
 
## Commands
-Build: `{build_cmd}`
-Test all: `{test_cmd}`
-Test single: `{test_single_cmd}`
-Lint: `{lint_cmd}`
-Dev server: `{dev_cmd}`
 
## Architecture
{2-5 bullet points with explicit paths}
 
## Workflow
Spec -> Approve -> Build -> Verify -> Checkpoint.
 
-Create specs before coding: `/spec {feature-name}`
-Run `{build_cmd} && {test_cmd} && {lint_cmd}` after every task
-Commit after every deliverable, one task at a time
-Stop at human checkpoints — present results
-**Plan before coding.** Get approval before writing code.
 
## Testing
-Write tests alongside code, not just after
-Test files: `{test_dir}`
-Focus on behavior and edge cases, not snapshots
-ALWAYS run `{test_cmd}` after changes
 
## Guardrails
-3 attempts max to fix a failing issue, then STOP and report
-Same error twice → change strategy
-Ask before: adding dependencies, architecture decisions, deviating from spec

Spec template (if no spec workflow exists)

Create docs/spec/_template.md:

# Spec: {Feature Name}
 
**Status:** DRAFT | APPROVED | IMPLEMENTED | DEPRECATED
**Date:** {date}
 
## Background
## Requirements
## Design
## Tasks
## Acceptance Criteria
## Human Checkpoint
## Out of Scope

Present tracker (if none exists)

Create docs/rpm/present/status.md for current project state: