chore(docs, rfd): Implement the JP RFD process and tooling (#397)

Introduce the Request for Discussion (RFD) process to formalize design
proposals and architectural decisions. This change adds the initial set
of process documents, templates, and automation to manage the lifecycle
of design documents from draft to implementation.

The process is built around a Git-based workflow where proposals are
submitted as markdown files in `docs/rfd/`, reviewed via pull requests,
and tracked through a defined set of statuses.

New documentation:
- `001-jp-rfd-process.md`: Core process definition and lifecycle.
- `002-using-llms.md`: Guidelines for responsible LLM usage.
- `003-jp-assisted-rfds.md`: Design for JP-assisted RFD writing.

Automation and Tooling:
- Added `just rfd-draft` to create new proposals from templates.
- Added `just rfd-supersede` to manage document relationships.
- Introduced the `rfd` skill for JP to act as a drafting partner.

The `rfd` skill enables JP to assist contributors by suggesting
structure, researching codebase context, and proposing targeted edits
while maintaining the principle of human authorship and responsibility.

---------

Signed-off-by: Jean Mertz <git@jeanmertz.com>

Author: JeanMertz

.jp/config/knowledge/conventional-commit.toml

@@ -162,6 +162,9 @@ items = [
     For the `jp_llm` crate, add an additional provider-specific scope when relevant (e.g. `ollama` \
     or `anthropic`).\
     """,
+    """\
+    For any RFD/ADR-related changes, add the scope `rfd`.\
+    """,
 ]
 
 [[assistant.instructions]]

.jp/config/skill/rfd.toml

@@ -0,0 +1,107 @@
+extends = [
+    "../skill/read-files.toml",
+    "../skill/project-discourse.toml",
+]
+
+[conversation]
+attachments = [
+    "file://docs/rfd/001-jp-rfd-process.md",
+]
+
+[conversation.tools]
+rfd_draft = { enable = true, run = "ask" }
+fs_modify_file = { enable = true, run = "ask" }
+
+[[assistant.system_prompt_sections]]
+tag = "rfd_skill"
+title = "Skill: RFD Writing"
+content = """\
+You have been given the RFD writing skill. You are an expert at helping \
+contributors write Requests for Discussion (RFDs) for the JP project.
+
+Your role is **collaborator, not author**. The user writes the RFD. You \
+help them write a better one. This means:
+
+- Pointing out gaps in reasoning or missing sections
+- Suggesting structure when asked
+- Finding relevant code, docs, or prior RFDs to reference
+- Drafting sections that the user will rewrite in their own voice
+- Asking clarifying questions to sharpen the proposal
+
+You do NOT:
+
+- Write entire RFDs from scratch unprompted
+- Generate filler prose to pad out sections
+- Add sections the user hasn't asked about without flagging them first
+- Use sycophantic language about the quality of the draft
+
+**RFD 001** is attached to this conversation. It describes the RFD \
+process, templates, lifecycle, and writing style guidelines. Treat it \
+as the authoritative reference for all RFD conventions.
+
+`rfd_draft` is available to create new RFD drafts of the specified \
+variant (rfd or adr) and the given title.
+
+`fs_modify_file` is available but runs in confirmation mode — the user \
+sees a diff and approves or rejects each edit. Make targeted, minimal \
+changes rather than rewriting entire sections.\
+"""
+
+[[assistant.system_prompt_sections]]
+tag = "rfd_skill"
+title = "RFD Collaboration Workflow"
+content = """\
+1. **Understand intent**: Before suggesting structure, ask what the \
+contributor is trying to propose. Understand the problem before jumping \
+to solutions.
+
+2. **Research context**: Use `fs_grep_files`, `fs_read_file`, and \
+`fs_list_files` to find relevant code, existing architecture docs, and \
+prior RFDs. Use `github_issues` and `github_pulls` to find related \
+discussions.
+
+3. **Suggest structure**: Based on the topic, suggest which RFD style \
+(rfd or adr) fits best, and which sections are most important. Not \
+every RFD needs every section.
+
+4. **Review drafts**: When reviewing draft text, focus on clarity, \
+completeness, and consistency with the project's conventions. Flag \
+missing sections, unclear motivation, or unsupported claims.
+
+5. **Draft on request**: When asked to draft a section, produce content \
+the contributor can edit. Keep the voice direct and factual. Avoid \
+hedging language and filler.
+
+6. **Apply edits**: When the contributor asks you to apply changes to \
+an RFD, use `fs_modify_file` to make targeted edits. The user will be \
+asked to confirm each modification before it is applied.\
+"""
+
+[[assistant.system_prompt_sections]]
+tag = "rfd_skill"
+title = "RFD Quality Checks"
+content = """\
+When reviewing an RFD draft, evaluate against these questions:
+
+- Does the Summary convey the proposal in 1-3 sentences?
+- Does the Motivation explain why, not just what?
+- Does the Design start with user-facing behavior before internals?
+- Are Alternatives actually explored, or just listed?
+- Are Non-Goals explicitly stated where readers might have wrong expectations?
+- Are Risks honest about what could go wrong?
+- Is the Implementation Plan broken into mergeable phases?\
+"""
+
+[[assistant.system_prompt_sections]]
+tag = "rfd_skill"
+title = "RFD Writing Style"
+content = """\
+- Use present tense: "This RFD describes..." not "This RFD was created \
+to describe..."
+- Be direct. No hedging: "it seems", "probably", "it might be worth \
+considering."
+- Keep it short. If an RFD exceeds ~2000 words, suggest splitting into \
+smaller proposals.
+- Use concrete examples. A code snippet or data flow diagram is worth a \
+paragraph of abstraction.\
+"""

.jp/mcp/tools/rfd/draft.toml

@@ -0,0 +1,25 @@
+[conversation.tools.rfd_draft]
+enable = false
+run = "ask"
+source = "local"
+command = "just rfd-draft {{tool.arguments.variant}} {{tool.arguments.title}}"
+description = "Create a new RFD document."
+
+[conversation.tools.rfd_draft.style]
+inline_results = "full"
+results_file_link = "off"
+parameters = "function_call"
+
+[conversation.tools.rfd_draft.parameters.variant]
+description = "RFD variant to create."
+required = true
+type = "string"
+enum = [
+    "rfd",
+    "adr",
+]
+
+[conversation.tools.rfd_draft.parameters.title]
+description = "Title of the RFD."
+required = true
+type = "string"

docs/.vitepress/config.mts

@@ -8,6 +8,7 @@ export default defineConfig({
     title: "Jean-Pierre",
     description: "An LLM-based Programming Assistant",
     cleanUrls: true,
+    srcExclude: ['rfd/**/*'],
     themeConfig: {
         outline: {
             level: [2, 3]

docs/rfd/000-adr-template.md

@@ -0,0 +1,36 @@
+<!--
+  This template is a starting point, not a constraint. Delete sections that
+  don't apply, add sections that do, or restructure entirely. The only
+  requirement is the metadata header (Status, Authors, Date).
+-->
+
+# RFD NNN: TITLE
+
+- **Status**: Draft
+- **Authors**: AUTHOR
+- **Date**: DATE
+
+## Summary
+
+One to three sentences stating the decision. A reader should understand what
+was decided without reading further.
+
+## Context
+
+The forces at play: technical constraints, project needs, team experience,
+existing patterns. State facts, not opinions. What makes this decision
+necessary now?
+
+## Decision
+
+State the decision clearly. "We will use X" or "We will adopt Y." Be
+specific enough to act on.
+
+## Consequences
+
+What follows from this decision — positive, negative, and neutral. What
+becomes easier? What becomes harder? What trade-offs are we accepting?
+
+## References
+
+Links to related RFDs, issues, documentation, or external resources.

docs/rfd/000-rfd-template.md

@@ -0,0 +1,75 @@
+<!--
+  This template is a starting point, not a constraint. Delete sections that
+  don't apply, add sections that do, or restructure entirely. The only
+  requirement is the metadata header (Status, Authors, Date).
+-->
+
+# RFD NNN: TITLE
+
+- **Status**: Draft
+- **Authors**: AUTHOR
+- **Date**: DATE
+
+## Summary
+
+One to three sentences describing what this RFD proposes. A reader should be
+able to understand the gist without reading further.
+
+## Motivation
+
+Why is this change needed? What problem does it solve? What happens if we do
+nothing? Start with "why" before "how."
+
+## Design
+
+The core of the RFD. Describe the proposed solution in enough detail that
+someone familiar with the codebase could implement it. Use diagrams, code
+snippets, and examples where they help.
+
+Start with what the user or caller sees — the external behavior, API, or
+experience — before describing internals.
+
+Structure this section however makes sense for the topic. Common subsections
+include: Overview, Design Goals, Architecture, Data Flow, API Changes,
+Configuration Changes.
+
+Every section can be brief. A one-sentence Alternatives section is better than
+no Alternatives section.
+
+## Drawbacks
+
+What are the known costs of this approach? What does the project give up by
+adopting it? Argue honestly against your own proposal.
+
+## Alternatives
+
+What other approaches were considered? Why were they rejected? This section is
+important — it shows the reader that the solution space was explored and gives
+future readers context for the decision.
+
+## Non-Goals
+
+What this RFD explicitly does not aim to achieve, even though a reader might
+expect it to. This keeps the discussion focused and signals awareness of the
+broader picture.
+
+## Risks and Open Questions
+
+What could go wrong? What don't we know yet? What needs to be validated during
+implementation? It's better to surface uncertainty explicitly than to pretend it
+doesn't exist.
+
+## Implementation Plan
+
+How will this be implemented? Break the work into phases or steps. This section
+bridges the gap between design and execution.
+
+For each phase, briefly describe:
+
+- What it includes
+- What it depends on
+- Whether it can be reviewed and merged independently
+
+## References
+
+Links to related RFDs, issues, documentation, or external resources.