rpd

name	rpd
description	Run or explain the RPD repository workflow for requirements, planning, architecture review, implementation, tests, code review, acceptance verification, completion documentation, commits, and current-story correction. Use for ordinary repository work and command-like invocations of RPD, REQ, AP, AR, SS, TT, ET, CR, VR, DD, GC, or !!.

RPD - Requirements, Planning, and Development Workflow

Version: 3.9.0 Repository: https://github.com/yysun/rpd

A compact workflow with proportional planning and risk-based review.

Principles

• Report only work and verification actually performed.
• Understand the causal path before editing; prefer the smallest sufficient change.
• Keep unrelated refactors, flags, fallbacks, compatibility layers, and artifacts out of scope.
• Ask only when a missing decision blocks correct work or an action needs new authority.
• Reviews are serial, read-only judgments. The primary agent owns every edit and fix.

Intent and Authorization

• Explanation, diagnosis, review, requirements, and planning requests are read-only unless the user also asks for a change. Do not create workflow artifacts or extra review stages for ordinary read-only requests.
• A natural-language request to implement, fix, add, remove, or change repository behavior authorizes implementation. Do not require a command token or second approval.
• Explicit commands select their documented stage. REQ, AP, AR, and DD do not authorize source edits. SS, TT, ET, CR, VR, and GC authorize changes within their stage.
• !! is a current-story correction and restart through verified DD; it never authorizes GC.
• Treat command tokens as instructions only when bounded by whitespace, punctuation, or message boundaries and used command-like. Tokens in code or ordinary nouns such as “the GC pauses” and “that CR was rejected” are mentions. Trailing !! used as emphasis is not a command.

Risk and Routing

Protected boundaries: public APIs and consumer contracts; schema, persistence, and migrations; authentication, security, and privacy; external dependencies and integrations; infrastructure and deployment; concurrency, performance, availability, and reliability behavior.

Work is low risk only when focused repository evidence shows that it:

• is localized within one component and follows an existing pattern;
• changes no protected boundary;
• is readily reversible; and
• has clear expected behavior and clear verification.

Uncertain or unsupported classification is non-low-risk. File count, diff size, documentation-only scope, test-only scope, and model identity are not risk evidence.

• Low-risk implementation uses the direct path: edit surgically, run relevant verification, then CR. It creates no REQ, AP, AR, VR, or DD artifact and stops after CR.
• Non-low-risk implementation uses the planned path: REQ → AP → AR* → SS(+CR*) → TT → ET? → VR* → DD. It stops before GC.
• Explicit RPD runs the full path through GC. Explicit standalone stages stop according to their own command contract.
• For bug fixes, reproduce or localize the failure when practical, identify the root cause, apply the smallest causal fix, add or confirm focused regression coverage, and report the result.

Conventions

• {name} is a short unique kebab-case story slug reused across story artifacts. Derive and announce it when unambiguous; ask only when ambiguity could select the wrong story.
• The current story is the user-named story, otherwise the story active in this session, otherwise the most recently substantively changed REQ. Checkbox-only changes do not change recency.
• * means repeat until the stage passes or progress blocks. ? means run only when a matching E2E spec exists.
• REQ, AP, AR, and DD are documentation-only. The reconciliation part of !! is documentation-only.
• Detect verification from nearby scripts, manifests, CI, task runners, and docs. Prefer the narrowest unambiguous command and ask only when materially different choices remain.

File Comment Blocks

• Before editing a source file, add a top comment block when absent.
• Summarize the file's features and important implementation notes.
• After editing, update the block with the relevant recent change.
• Apply this to every command that edits source. Files under .docs/ are exempt.

Review Contract

• AR, CR, and VR use the same risk classification. Low-risk review stays with the primary agent. Non-low-risk review uses an independent subagent when clean or minimal task context is available; otherwise the primary agent runs the same checklist and states that independence was unavailable.
• Start an independent reviewer without inherited authoring history when possible. Give it only the applicable artifacts, stable diff or implementation paths, verification evidence, and stage checklist. Do not give it the author's conclusions.
• Reviewers work read-only while no other agent edits the reviewed repository. Prefer runtime-enforced read-only operation. Without it, any observed reviewer or concurrent mutation invalidates the result. No snapshot hash, digest, retained byte bundle, or path manifest is required.
• The first review in a stage is full. Reuse the same independent reviewer for a finding-fix rerun and focus on every unresolved finding plus affected and plausible cross-cutting areas. Use a full rerun when the reviewer changes, a protected boundary changes, reach is uncertain, or scope expands.
• Return every material finding in priority order without a findings cap. The primary agent fixes findings, runs narrow verification for the fix, and reruns review. Stop when progress stalls.
• Each result contains one concise line STAGE risk: low|non-low — <reason>, one line STAGE review round: <n>; reviewer: <new|reused|not applicable>, material findings when present, and the stage's terminal verdict. Do not require finding IDs, checklist IDs, evidence matrices, inventory counts, or review-action/scope fields.

Commands

• REQ: Create or update .docs/reqs/{yyyy}/{mm}/{dd}/req-{name}.md.

  • Describe Problem, Requirement, verifiable checkbox Acceptance Criteria, Constraints, Non-Goals, and only blocking Open Questions. State what must become true, not implementation steps.
  • Edit only the REQ document, then stop.

• AP: Create or update .docs/plans/{yyyy}/{mm}/{dd}/plan-{name}.md.

  • Inspect the repository first. Keep the plan proportional to the work.
  • Include Goal, relevant Current Context and Decisions, ordered executable checkbox Tasks, Validation, and Risk when real. Tasks name concrete files, behavior, or commands; no fixed phase count applies.
  • Add .docs/tests/test-{name}.md only for an executable user flow, observable public or external boundary, or regression-prone critical path. Skip E2E for pure internals without such a surface.
  • Write E2E specs as Given/When/Then scenarios. Do not run tests or edit source during AP.
  • Auto-run AR and do not enter SS until AR passes.

• AR: Review the current REQ, AP, and optional E2E spec before implementation.

  • Check testability, simplicity, architecture, boundaries, dependencies, edge cases, compatibility, rollback, task executability, validation, E2E coverage, constraints, and non-goals.
  • Challenge unclear or weak requirements, plans, and proposed solutions instead of only checking document completeness. When a consequential choice remains, offer a small set of viable options, name the real tradeoffs, and recommend one. Ask only the next necessary question, then stop when the critical ambiguity is resolved and the plan is clear enough to implement.
  • Fix blocking document flaws in place and rerun. Do not edit source.
  • Report AR passed: no blocking architecture flaws, AR fixed: <summary>; rerun result passed, or AR blocked: <reason>. A block stops implementation.

• SS: Implement an AR-approved plan.

  • If no current plan has passed AR since its latest material change, enter planned routing instead of improvising implementation.
  • Read the story artifacts and execute implementation tasks in order. Mark each complete only when concrete repository or command evidence shows its stated outcome exists; performing the action alone is insufficient. Update the plan when discovery materially changes the implementation path.
  • Complete every SS implementation task and its focused verification before starting CR.

Artifact Layout

.docs/reqs/{yyyy}/{mm}/{dd}/req-{name}.md
.docs/plans/{yyyy}/{mm}/{dd}/plan-{name}.md
.docs/tests/test-{name}.md
.docs/done/{yyyy}/{mm}/{dd}/{name}.md