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.

2. 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/

3. 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.

4. 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).

5. 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.

6. Verify runtime-specific permissions. Run Phase 6 checks, but only apply permission changes for runtimes that support them.

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

8. 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.

2. Create or update AGENTS.md with the general guidance. Preserve existing AGENTS.md content and merge without duplication.

3. Rewrite CLAUDE.md so it keeps only Claude-exclusive directives and includes this policy near the top:

   # 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.
   

4. 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:

# {Project Name} — Present State

## Project Status
- **Current phase**: {phase}
- **Last updated**: {date}

## Completed Work
## Active Specs
## Known Issues

Past directory (if none exists)

Create docs/rpm/past/ for daily session logs (YYYY-MM-DD.md files written by /session-end).

Future tracker (if none exists)

Create docs/rpm/future/tasks.org:

#+TITLE: {Project Name} Future
#+TODO: TODO IN-PROGRESS BLOCKED WATCH | DONE

* {Current Phase}
** TODO {first task} [[file:YYYY-MM-DD-slug.md]]
   :PROPERTIES:
   :ID: {slug}
   :END:

WATCH is for entries that are observe-only / deferred until a trigger condition appears. /next treats WATCH as closed for task-selection purposes: it skips WATCH the same way it skips DONE. Use it instead of TODO when a follow-up should remain visible in the backlog without triggering a worker dispatch.

Format rule (enforce from day one): each entry is the heading line (with [[file:...]] link) plus the standard :PROPERTIES: / :ID: / :END: drawer. Body content (anything outside the drawer) caps at 3 lines and is usually empty — all task details live in the detail file at future/<date>-<slug>.md. The drawer doesn't count toward the 3-line body budget; add :BLOCKED_BY: <other-slug> inside it when there's a dependency on another task.

Never inline bullet lists, prose, or implementation notes in your rpm backlog. The full rule lives in plugin/skills/backlog/SKILL.md.

Also create docs/rpm/future/done.org (archive for closed entries swept out of tasks.org by /session-end):

#+TITLE: {Project Name} Archive
#+TODO: TODO IN-PROGRESS BLOCKED | DONE CANCELLED

Closed entries swept from tasks.org by session-end. Newest first.

Phase 4a: Repair stale configs (gitignore wildcard + AGENTS.md include)

Say to user: "Checking .gitignore and AGENTS.md against the current rpm layout."

Both fresh bootstraps and repeat runs reach this phase. Two stale-config gaps appear in projects bootstrapped before today's layout:

1. .gitignore wildcard. rpm scatters transient session-state under docs/rpm/~rpm-*. The current convention is one wildcard line that covers all of them. Older bootstraps either had no .gitignore entry at all or accumulated one explicit line per transient file.

2. AGENTS.md include directive. Codex (and any other runtime that doesn't capture SessionStart stdout) picks up rpm session context through a top-of-file # include: docs/rpm/~rpm-context.md line in AGENTS.md. Older bootstraps wrote AGENTS.md without the line, so the SessionStart hook's file write isn't visible to the LLM.

Run the repair helper to detect and fix both in one pass:

bash "${CLAUDE_SKILL_DIR}/scripts/repair.sh" --check

The helper prints a structured report. Use the report to decide what to do, then re-run without --check (or with --auto-yes for fully non-interactive repair) to apply the changes the user has approved.

The repair helper is safe to run on any project, including those already migrated — it's idempotent and reports wildcard=present / agents_md=include_present when there's nothing to do.

Handling the report

The helper emits two sections — === gitignore === and === agents_md === — each followed by key=value lines.

gitignore section

If action=offer_collapse appears, surface this one-line offer with the listed lines:

Found N explicit docs/rpm/~rpm-* entries in .gitignore. These are all
covered by the docs/rpm/~rpm-* wildcard the helper just added.

  {list of explicit_line= values, one per line}

QUESTION: Collapse these N lines into the wildcard? (`yes` / `no`)

On yes, re-run with --auto-yes (or --gitignore-only --auto-yes if you don't want to re-prompt the AGENTS.md decision). On no, leave them in place — they're redundant but harmless, and the helper will offer again on the next repeat run.

agents_md section

If action=offer_prepend appears, surface this offer:

AGENTS.md is missing the rpm context include directive
(`# include: docs/rpm/~rpm-context.md`). Without it, the SessionStart
hook's context file isn't picked up by Codex agents in this project.

QUESTION: Prepend the include line to AGENTS.md? (`yes` / `no`)

On yes, re-run with --auto-yes (or --agents-only --auto-yes). The helper preserves all existing AGENTS.md content verbatim and places the include directive immediately after any YAML frontmatter. On no, leave AGENTS.md unchanged — the helper will offer again on the next repeat run.

Repair invocation flow

1. Run repair.sh --check and read the structured report.

2. For each action=offer_* line, surface the offer to the user.

3. If both offers are accepted, run repair.sh --auto-yes once.

4. If only one is accepted, run repair.sh --gitignore-only --auto-yes or repair.sh --agents-only --auto-yes as appropriate.

5. If neither is accepted, skip the apply step — the helper has already added non-destructive defaults (wildcard ignore line, newly created .gitignore) during the dry-run; only the destructive/opt-in operations (collapse explicit lines, prepend AGENTS.md include) are gated by user consent.

   Note: in --check mode, the helper makes no writes — so if you want the non-destructive defaults applied without prompting for the opt-in operations, run it without --check and without --auto-yes; the wildcard append / .gitignore create happens, but explicit-line collapse and AGENTS.md prepend are skipped.

If the active runtime is non-interactive (worker subagent, automated pipeline), default both offers to no and report them under Needs attention in the verification summary.

Phase 5: Adapt for Team Size

Say to user: "Tuning the scaffolding for your team size."

Solo/Small: Use template as-is. Single agent with spec workflow.

Medium (5-10): Consider adding agent roles when a single agent demonstrably struggles. Cap at 4. Communicate via typed artifacts.

Large (10+): Module ownership, git worktrees for parallel agent isolation.

Phase 6: Permissions

Say to user: "Checking whether this runtime needs an rpm permissions entry."

rpm hooks and skills frequently read/write files under docs/rpm/. Some runtimes support project-local allowlists; others use sandbox or approval policy outside the project.

Only perform the .claude permissions edit when running under Claude Code or when .claude/settings.local.json / .claude/settings.json already exists. Do not create .claude/ for Codex, opencode, or an unknown runtime.

For Claude Code: check whether Read(./docs/rpm/**) and Edit(./docs/rpm/**) already appear in .claude/settings.local.json (or .claude/settings.json). If they do, skip this phase silently.

If not, ask:

Grant rpm read/write access to docs/rpm/?
This lets hooks and skills manage session files, daily logs, and
trackers without per-file permission prompts.
(y/n)

If yes: read .claude/settings.local.json (create if missing), merge Read(./docs/rpm/**) and Edit(./docs/rpm/**) into permissions.allow, and write the file back. Do not overwrite existing entries.

For Codex, opencode, and unknown runtimes: do not prompt for this permission. Continue to Phase 7.

Phase 7: Create All Files

Say to user: "Writing the scaffolding now."

Create all files from Phase 3 and Phase 4 that do not already exist. Do NOT prompt the user to select which files to create — all are required for the plugin to function.

Then activate hooks for the current session when supported. The runtime startup hook may already have run before docs/rpm/ existed and exited without writing ~rpm-session-start — so lifecycle hooks can be gated off until the next session. Write the marker now so hooks activate immediately in runtimes that use the rpm marker, no restart needed:

SID="${CLAUDE_CODE_SESSION_ID:-${CODEX_SESSION_ID:-${OPENCODE_SESSION_ID:-unknown}}}"
cat > docs/rpm/~rpm-session-start <<EOF
---
session_id: $SID
started: $(date -Iseconds)
task: (unassigned)
---
EOF

After the marker is written, proceed to Phase 8.

Phase 8: Present and Confirm

Print the completion summary exactly like this (fill in the created files list):

## /init-rpm complete

Created: {list of created files}

Next steps:
- rpm is active in this session already — hooks will fire as you work
  where the active runtime exposes lifecycle hooks
- `/backlog add <description>` — add entries to your rpm backlog
- `/audit project` — run a full consultant review when you want
  outside perspective on code, architecture, and competitive positioning

To de-rpm this project later: delete `docs/rpm/`. The plugin hooks
exit silently when that directory is missing, so nothing else needs
changing.

Scaling Notes

• Agent instructions too long/stale -> Split into root + per-service files
• Tasks parallelizable -> Multi-agent with git worktrees
• Context bottleneck -> Three-tier knowledge with MCP retrieval

Cost awareness: Multi-agent = 4-220x more tokens. Monitor weekly.