rpd

name: rpd version: 2.1.7 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.

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

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