rpd

name	rpd
metadata	{"version":"2.1.10","repository":"https://github.com/yysun/rpd"}
description	Use this skill for software development tasks that should follow the RPD workflow: requirements, architecture planning, implementation, debugging, tests, E2E checks, code review, commits, done docs, or worktrees. Trigger on natural-language requests for those workflow stages, or when any of these keywords appears with command-like intent: RPD, REQ, AP, AR, SS, DF, DD, ET, TT, CR, VR, GC, WT, !!. The keyword must be surrounded by message boundaries, punctuation, or whitespace. Match examples like `REQ`, `REQ:`, `REQ-`, `REQ,`, `REQ -`, and `'REQ'`. Match middle or end forms like `please REQ: add login` or `ship it SS`. Do not match when a letter, digit, or underscore touches the keyword. Ignore keywords inside fenced code blocks or inline code spans.

RPD - Requirements, Planning, and Development Workflow

A concise software development workflow with automatic architecture and code review loops.

Core Principles

• Truthful execution: only claim tests/build/lint ran if they actually ran.
• Think before coding: understand the problem, plan the approach, and consider edge cases before writing code.
• Simplicity first: use the minimum code that solves the problem.
• Surgical changes: avoid refactors or additions unrelated to the task.
• Goal-directed: define success criteria for each task and verify the code meets them.
• Ask when blocked: ask targeted questions.
• Independent review: use clean-context independent subagents for CR and VR, and for AR when architecture risk requires it; preserve the same review contract when delegation is unavailable.

Command Gate

RPD command keywords are authoritative execution gates.

• Finding or loading this skill is not approval to code.
• When the user invokes REQ, AP, AR, DD, WT, or !!, do only that command's allowed work.
• Documentation-only commands must not edit source code, tests, configs, dependencies, generated artifacts, or build files.
• Implement code only when the active command is SS, DF, VR, or RPD has reached its SS stage.
• For natural-language development requests without an explicit implementation command, create or update REQ and AP first, then stop unless the user has invoked SS, DF, VR, or RPD.
• If a command gate conflicts with the default agent behavior to keep working autonomously, the command gate wins.

Conventions

• {name}: short kebab-case story slug.
• Derive {name} from the requirement when missing.
• Keep {name} short, descriptive, and unique.
• Announce derived {name} and continue without asking for confirmation unless multiple plausible slugs exist, the slug would collide with an unrelated existing story, or the requirement is too ambiguous to name safely.
• Ask for slug clarification only when ambiguity would create the wrong doc path or attach work to the wrong story.
• Reuse {name} across REQ, AP, SS, DD, ET, VR, !!, WT, and RPD.
• {yyyy}/{mm}/{dd}: the doc creation date.
• Later updates edit the existing dated doc.
• Current story: the most recently created or modified REQ doc, unless the user specifies otherwise.
• Auto-chaining: SS and DF run required verification, then auto-run CR.
• Completion loop: VR verifies the requirement against code behavior, tests, and docs. If incomplete, refine AP, run SS, CR, TT, ET when applicable, update docs, then rerun VR.
• REQ, AP, DD, and !! are documentation-only.
• WT and !! are out-of-band.
• Never auto-chain WT or !! from another command.
• Large changes: auto-run REQ then AP when either is missing.
• Review loop: AR fixes high-priority requirement, plan, and E2E spec issues before implementation; CR fixes high-priority code issues after implementation.
• Rerun review until no major flaws remain.
• Architecture gate: AP and RPD must not enter SS until AR has explicitly passed.
• Loop blockers: stop when scoped progress stalls.
• Report unrelated, pre-existing, flaky, or ambiguous failures.
• Ask before switching to another workflow.
• Verification detection: inspect project scripts, task runners, lockfiles, build/test configs, CI workflows, Makefiles, existing docs, and nearby package manifests before asking the user.
• Prefer the narrowest unambiguous verification command that matches the command stage and changed files.
• Ask before running verification only after local inspection cannot identify a command or finds multiple plausible commands with materially different scope or side effects.

File Comment Blocks

• Add a top comment block to each edited source file.
• Summarize features, implementation notes, and recent changes.
• Create the block before editing when missing.
• Update the block after changing the file.
• Applies to SS, DF, VR, and RPD once it reaches its SS stage.
• Does not apply to docs under .docs/.

Independent Review Delegation

• Before AR, CR, or VR, check whether the current runtime exposes subagent spawning, has capacity, and permits delegation. Do not infer support from the model name.
• Before deciding how to run AR, have the primary agent perform the AR checklist as a preflight and fix obvious requirement, plan, and E2E spec flaws.
• Treat AR as low-risk only when all of these are true: the plan follows an existing architecture pattern; stays within one component or subsystem; changes no public API, schema, persistence, migration, authentication, security, privacy, external integration or dependency contract, infrastructure, deployment, concurrency, performance, availability, or reliability behavior; is readily reversible; and has unambiguous acceptance criteria and implementation boundaries.
• Record the low-risk classification criterion by criterion with concrete repository evidence in the AR result. If any criterion lacks evidence or is uncertain or debatable, treat AR as non-low-risk.
• The primary agent may complete low-risk AR itself. Otherwise, require independent AR when delegation is available. Require independent CR and VR whenever delegation is available.
• For an independent review, use a subagent that did not author the artifacts under review. Start it with no inherited authoring conversation when the runtime supports that option; otherwise pass the smallest task-local context the runtime permits. Do not use full-history inheritance.
• If the runtime cannot start a reviewer with either no inherited authoring history or a minimal task-local context, treat independent delegation as unavailable and run the primary-agent fallback.
• Give the reviewer only the raw artifacts needed for its command: the applicable REQ, AP, E2E spec, stable diff or implementation paths, verification evidence, and command-specific checklist. Do not pass the author's conclusions, suspected flaws, intended fixes, or claims that the work should pass.
• Require the reviewer to reconstruct its judgment from those artifacts, work read-only, and return every material finding in priority order without a findings cap. For VR, require the acceptance-criteria evidence matrix in addition to the findings. Run the review only after the relevant artifacts form a stable snapshot.
• Use runtime-enforced read-only tools when supported. Otherwise record the reviewed snapshot and Git-visible worktree state, instruct the reviewer not to edit, and verify both are unchanged afterward. If they changed, invalidate the review and stop for safe primary-agent recovery before rerunning it.
• Keep AR, CR, and VR as serial gates. Do not let a reviewer inspect files while another agent is mutating them.
• The primary agent owns edits, fixes, tests, documentation updates, completion loops, and the final pass decision. Rerun the independent review after material changes, including fixes for blocking findings, but not solely for editorial corrections. If a blocking finding cannot be resolved, stop and report the blocker instead of reviewing the unchanged snapshot again. Prefer fresh reviewer context when capacity permits.
• If subagents are unavailable, run the same checklist in the primary agent and produce the same required output. Delegation changes review independence, not the pass criteria.

Command Keywords

• REQ: Create or update requirements in .docs/reqs/{yyyy}/{mm}/{dd}/req-{name}.md.
  • Focus on WHAT, not HOW, not optimization.
  • Required sections:
    • ## Problem: the user-visible or system-visible problem and why it matters.
    • ## Requirement: the behavior, contract, or outcome that must become true.
    • ## Acceptance Criteria: checkbox criteria that can be verified by code behavior, tests, docs, or observable output.
    • ## Constraints: compatibility, data, UX, performance, security, migration, or operational constraints.
    • ## Non-Goals: tempting but out-of-scope work, including unnecessary feature flags, fallback modes, and compatibility layers.
    • ## Open Questions: only questions that block correct planning; omit the section when none exist.
  • Acceptance criteria must be specific enough for VR to judge complete or incomplete.
  • Do not include implementation steps, file-level plans, or speculative architecture.
  • Create or update only the requirement doc.
  • Do not implement code.
  • Do not modify tests, configs, or non-REQ docs.
• AP: Create architecture/implementation plan in .docs/plans/{yyyy}/{mm}/{dd}/plan-{name}.md.
  • Plans must be detailed, phased, and ordered by dependency.
  • Do not create a shallow four-item checklist; expand the work into the real implementation sequence.
  • Required sections:
    • ## Goal: one or two sentences tying the plan back to the REQ. State what must become true, not what the agent intends to try.
    • ## Current Context: relevant files, entry points, constraints, existing behavior, and known unknowns discovered during AP inspection.
    • ## Decisions: architecture choices, rejected alternatives, tradeoffs, compatibility decisions, and non-goals. Explicitly reject unnecessary feature flags, environment variables, fallback modes, and compatibility layers unless required by the REQ.
    • ## Phased Tasks: markdown checkbox tasks grouped under numbered phase headings. These tasks are for the AI agent to execute, not for a human project tracker.
    • ## Validation: build, typecheck, unit, integration, E2E, manual checks, and expected evidence. Include exact commands or observable outputs the agent must report.
    • ## Rollback / Risk: risky areas, migration/data concerns, compatibility concerns, cleanup concerns, and rollback strategy when relevant.
  • Phased task template:
    • ### Phase 1 - Discovery and scope lock
    • - [ ] Inspect <specific files/modules> to confirm <specific assumption, dependency, boundary, or current behavior>.
    • - [ ] Identify <specific legacy path/fallback/flag/compatibility behavior> that must be preserved, changed, or removed according to the REQ.
    • - [ ] Record <specific non-goals/rejected alternatives> so the implementation does not introduce out-of-scope behavior.
    • ### Phase 2 - Foundation changes
    • - [ ] Update <specific component/module/API/schema/type/config> so <required behavior or contract> is represented directly.
    • - [ ] Remove or simplify <specific obsolete path/option/env var/fallback> so the new behavior is not hidden behind unnecessary compatibility.
    • - [ ] Update <specific validation/error handling/loading path> so invalid or unsupported states fail clearly.
    • ### Phase 3 - Feature implementation
    • - [ ] Implement <specific behavior> in <specific place>, preserving <specific constraint or invariant>.
    • - [ ] Wire <specific integration point/call path/artifact generation step> so <expected end-to-end behavior>.
    • - [ ] Confirm <specific rejected alternative or non-goal> was not introduced during implementation.
    • ### Phase 4 - Tests and verification wiring
    • - [ ] Add or update <specific tests/specs/evals> for <acceptance point, edge case, or failure mode>.
    • - [ ] Run <specific command> and record <expected evidence/output>.
    • - [ ] Verify <specific cleanup/removal/absence condition> so stale behavior cannot silently remain.
    • ### Phase 5 - Documentation and status
    • - [ ] Update <specific docs/examples/status artifacts> with <exact new behavior, command, or contract>.
    • - [ ] Record final evidence showing <REQ requirement> is satisfied.
    • - [ ] Mark completed tasks complete only after the corresponding change or evidence exists.
  • Add, remove, rename, or split phases to match the story; keep the sequence logical from investigation through validation.
  • ## Phased Tasks rules:
    • Every task must start with - [ ].
    • Every task must name a specific file, module, API, schema, command, test, artifact, or behavior.
    • Every task must describe an observable state change or verification action.
    • Do not use vague tasks such as - [ ] Improve implementation, - [ ] Update tests, or - [ ] Clean up code.
    • Do not mark a task complete unless the agent has performed the work and, where applicable, recorded evidence.
    • Prefer tasks that produce a durable repository change or a concrete verification result.
    • Keep phases in logical execution order: discover, decide, change foundation, implement, verify, document.
  • Every phase must have enough tasks that SS can execute without rediscovering the whole design.
  • Call out dependencies between phases when order is not obvious.
  • Do not use prose-only task lists.
  • Mermaid is optional and usually unnecessary; use it only when a diagram makes dependencies, data flow, state transitions, or system boundaries clearer than concise text.
  • Do not add Mermaid for simple task sequences, prose decoration, or plans that are already clear as phased checkboxes.
  • Decide whether the story needs E2E coverage.
  • Create E2E specs for user-facing flows.
  • Create E2E specs for auth, routing, payments, or data entry.
  • Create E2E specs for cross-system integrations.
  • Create E2E specs for regression-prone critical paths.
  • Skip E2E specs for pure internals unless requested.
  • If needed, create or update .docs/tests/test-{name}.md.
  • Write E2E specs as human-readable scenarios.
  • Do not run tests during AP.
  • Automatically run AR after updating the plan.
  • Do not enter SS until AR has explicitly passed.
• AR: Review architecture and assumptions.
  • Can be manually triggered.
  • Run the primary-agent preflight, classify the plan using the low-risk criteria, and follow the Independent Review Delegation rules. Use a read-only independent subagent unless every low-risk condition is satisfied or delegation is unavailable.
  • Review for blocking flaws before implementation, not style preferences.
  • Check that the REQ is testable, the AP covers every acceptance criterion, phases are dependency-ordered, validation evidence is explicit, E2E coverage is correctly included or excluded, and risks/non-goals are handled.
  • Challenge unnecessary feature flags, environment variables, fallback modes, compatibility layers, broad refactors, and vague validation.
  • Provide options and tradeoffs only when a real architecture choice remains.
  • Review REQ, AP, and any E2E spec together.
  • Fix blocking requirement, plan, or E2E spec flaws by updating existing docs in place.
  • Do not pass AR with unresolved blocking questions, missing validation, or a plan that SS cannot execute directly.
  • Do not create a separate review doc.
  • Report either AR passed: no blocking architecture flaws or AR fixed: <summary>; rerun result passed.
  • Apply the review loop.
• SS: Implement step-by-step from the plan.
  • Read the current REQ, AP, and optional E2E spec before editing code.
  • Execute AP tasks in order unless a discovered constraint makes the order wrong.
  • If implementation requires a material plan change, update the AP task list before or alongside the code change and keep the scope tied to the REQ.
  • Update plan progress (- [x]) as tasks complete.
  • Mark a task complete only after the code/docs/test change or verification evidence exists.
  • Do not silently add unplanned features, compatibility layers, fallback modes, environment variables, or broad refactors.
  • Treat SS as approval to implement.
  • Do not ask for a second approval.
  • Run relevant compile/build/typecheck after changes.
  • Report the exact verification command and result.
  • Fix compile/build/typecheck failures before review.
  • Auto-run CR* after verification passes.
• DF: Diagnose and fix root cause.
  • Think harder to find the root cause.
  • Reproduce or localize the failure before changing code when practical.
  • Explain the issue clearly: symptom, root cause, affected path, and why the fix addresses it.
  • Provide fix options when useful.
  • Prefer the smallest fix that removes the cause instead of masking the symptom.
  • Add or update a regression test when the project has a clear test location.
  • Automatically run TT to confirm the fix, then CR*.
• TT: Run unit tests and fix failures.
  • Detect the unit test command from the project.
  • Ask before running tests when unclear.
  • Stop at the first failure when the runner supports it.
  • Record the exact failing test, error, suspected cause, fix, and rerun result.
  • Fix the root cause of that failure.
  • Do not skip, delete, weaken, or rename tests to force a pass unless the REQ explicitly changes the expected behavior.
  • Rerun unit tests after each fix.
  • Repeat until all unit tests pass.
• CR: Review uncommitted changes with git.
  • Can be manually triggered.
  • Use the Independent Review Delegation rules; when available, have a read-only independent subagent review the stable diff and return prioritized findings to the primary agent.
  • Review the diff against the REQ, AP, and E2E spec, not just local code style.
  • Check scope control, architecture, correctness, edge cases, performance, maintainability, security, migrations, compatibility, test coverage, and stale docs.
  • Prioritize findings by impact; ignore cosmetic churn unless it hides a real defect.
  • Fix high-priority findings.
  • Rerun CR after fixes.
  • Continue until no major flaws remain.
  • After CR changes code, run scoped verification when clear.
  • Report unrelated or pre-existing failures.
  • Do not convert CR into TT.
• VR: Verify the requirement is fully implemented in both code and docs.
  • Use the Independent Review Delegation rules; when available, have a read-only independent subagent build the acceptance-criteria evidence matrix. The primary agent owns all follow-up edits and the completion loop.
  • Compare the current REQ doc, AP doc, optional E2E spec, implementation code, user-facing behavior, and latest verification results.
  • Decide whether each requirement acceptance point is implemented in code, covered by appropriate tests or E2E checks, reflected in the relevant RPD docs, and free of known blocking review issues.
  • Produce an acceptance-criteria matrix with complete, incomplete, or blocked status and concrete evidence for each item.
  • Update the REQ acceptance-criteria checkboxes during VR. Change - [ ] to - [x] only when concrete evidence proves that criterion complete; leave incomplete or blocked criteria unchecked.
  • Change - [x] back to - [ ] whenever current implementation, test, documentation, or review evidence no longer supports the criterion. Never preserve a stale checkmark.
  • Treat the checkbox as recorded status, not proof. Keep the evidence in the VR matrix and do not weaken or rewrite a criterion merely to check it off.
  • Do not pass VR until every acceptance criterion in the REQ is checked and supported by evidence appropriate to that criterion.
  • Treat stale, contradictory, or incomplete REQ/AP/test/done docs as incomplete work, not as a documentation-only cleanup.
  • Do not treat passing tests as proof of completion when requirements are visibly unmet.
  • Do not pass VR when planned cleanup/removal work, E2E coverage, docs, or review fixes are missing.
  • If complete, report the evidence and either stop for standalone VR or continue the parent RPD sequence.
  • If incomplete, update the existing AP doc with the missing code, test, and documentation work.
  • If missing work changes E2E coverage, update or create .docs/tests/test-{name}.md.
  • If requirement text is stale or contradictory, update the existing REQ doc before continuing.
  • Run SS to implement the refined plan.
  • Run CR* after implementation.
  • Run TT.
  • Run ET when a matching E2E spec exists or when the refined plan adds one.
  • Update plan progress and any affected RPD docs after code/test changes.
  • After completion-loop fixes, update the REQ checkboxes from the new evidence before rerunning the final VR decision.
  • Rerun VR after TT and ET complete.
  • Repeat until the requirement is complete or a loop blocker is reached.
  • Apply loop blocker rules when progress stalls, failures are unrelated, or the requirement is ambiguous.
• GC: Commit changes with a clear conventional commit message.
  • Do not run CR automatically.
  • Use the latest relevant verification for intended changes.
  • If verification is unknown, ask or run scoped verification.
  • If verification is stale, ask or run scoped verification.
  • Report verification status before committing.
  • If CR changes code, rerun relevant verification.
  • If failures are unrelated or pre-existing, report them.
  • Ask before committing with unrelated or pre-existing failures.
  • Inspect git status before staging.
  • Stop when unrelated or ambiguous changes are present.
  • Stage only files that belong to the current story; never sweep in unrelated work because it is convenient.
  • Commit message must reflect the user-visible or system-visible change, not the workflow stage.
  • Report the final commit hash.
• ET: Run E2E tests.
  • If a path is provided after ET, run that single test file.
  • Otherwise use .docs/tests/test-{name}.md.
  • Ask for a path when no matching spec exists.
  • Do not generate a new spec during ET.
  • For markdown specs, execute the scenarios with available tools.
  • For executable specs, detect the E2E test command.
  • Ask before running E2E tests when unclear.
  • Stop at the first E2E failure when possible.
  • Record the scenario, step, observed result, expected result, fix, and rerun evidence.
  • Fix the root cause of that failure.
  • Do not rewrite the E2E spec during ET except to correct stale wording after behavior is verified.
  • Rerun E2E tests after each fix.
  • Repeat until all targeted E2E tests pass.
• DD: Document completed work in .docs/done/{yyyy}/{mm}/{dd}/{name}.md.
  • Can be invoked as a single-word DD message.
  • Run after work is committed or a feature is complete; do not fire mid-stream.
  • Write a short PR-style completion summary.
  • Keep it concise: roughly 5-12 bullets total.
  • Required sections:
    • ## Summary: what changed and why it matters.
    • ## Verification: commands, tests, E2E checks, and reviews actually run.
    • ## Notes: follow-ups, risks, non-goals, skipped checks, or unrelated failures when real.
  • Do not duplicate the full REQ, AP, test spec, or changelog.
  • Do not claim verification that did not run.
  • Mention unresolved risks, skipped checks, or unrelated failures only when they are real and specific.
• WT: Create a new git worktree for the current story.
  • Inspect git status before moving docs.
  • Do not move unrelated docs or untracked artifacts into the worktree.
  • Move matching REQ and AP docs into the new worktree.
  • Move the existing test spec when present.
  • Move files instead of copying them.
  • Canonical command: git worktree add ../{project folder}.worktrees/feature-{name} -b feature/{name} {base}.
  • Use this when planning is done in one checkout but implementation should continue in another.
• !!: Update relevant docs from the latest user message.
  • Treat the latest user message as a requirement change, clarification, or scope correction.
  • Reconcile contradictions across REQ, AP, and test specs instead of appending stale text.
  • Update current REQ docs in place.
  • Update current AP docs in place.
  • Apply the AP E2E criteria to new requirement changes.
  • Create .docs/tests/test-{name}.md if E2E coverage is now needed.
  • Update the current test spec when present.
  • Record new non-goals, removed scope, changed validation, and affected phases when the clarification changes implementation direction.
  • Do not implement code; documentation only.
• RPD: Run the full end-to-end workflow from a requirement input.
  • Accept a requirement description as input.
  • Example: RPD add OAuth login.
  • Treat RPD as approval to run the full sequence without human approval between stages.
  • Pause only for clarification, blockers, destructive actions, or external writes.
  • Derive {name} when missing.
  • Announce derived {name} and continue unless slug ambiguity would attach work to the wrong story.
  • Sequence: REQ → AP → AR* → SS(+CR*) → TT → ET? → VR* → DD → GC.
  • * means review loop.
  • For VR*, * means completion loop.
  • ? means only if test spec exists.
  • AP creates E2E specs when needed.
  • AR reviews REQ, AP, and any E2E spec before implementation.
  • RPD must not enter SS until AR has fixed blocking doc/spec flaws and explicitly passed.
  • Inside RPD, SS still runs compile/build/typecheck.
  • Inside RPD, SS still fixes verification failures.
  • Inside RPD, SS still auto-runs CR*.
  • RPD continues to TT after SS completes.
  • RPD runs VR before DD so completion is checked against the original requirement, not only tests.
  • May be entered mid-sequence.
  • Example: RPD from SS.
  • Mid-sequence entry uses RPD skip rules, not standalone command rules.
  • Skip a stage only when its artifact is fresh, matches the current {name} and requirement, and is not contradicted by newer user messages, code changes, or docs.
  • Do not skip REQ when acceptance criteria are missing, stale, ambiguous, or tied to a different story.
  • Do not skip AP when the plan lacks current phased tasks, validation evidence, E2E coverage decision, or risk/non-goal handling.
  • Skip a gated stage only when its gate passed after the latest matching artifact update.
  • If freshness or matching is uncertain, update or rerun the stage instead of skipping it.

Documentation Structure

.docs/
├── reqs/{yyyy}/{mm}/{dd}/req-{name}.md
├── plans/{yyyy}/{mm}/{dd}/plan-{name}.md
├── tests/test-{name}.md  # optional existing E2E spec
└── done/{yyyy}/{mm}/{dd}/{name}.md