rpi-kit 1.4.1 → 2.0.0

package/commands/rpi/archive.md

@@ -0,0 +1,149 @@
+---
+name: rpi:archive
+description: Merge delta specs into main specs and clean up the feature directory.
+argument-hint: "<feature-name>"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - Agent
+---
+
+# /rpi:archive — Archive Feature
+
+Merge the feature's delta specs into the main `rpi/specs/` directory, preserve any solutions worth saving, and delete the feature directory. History is preserved in git.
+
+---
+
+## Step 1: Load config and validate
+
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `folder`: `rpi/features`
+   - `specs_dir`: `rpi/specs`
+   - `solutions_dir`: `rpi/solutions`
+2. Parse `$ARGUMENTS` to extract `{slug}`.
+3. Validate `rpi/features/{slug}/` exists. If not:
+   ```
+   Feature '{slug}' not found. Nothing to archive.
+   ```
+   Stop.
+
+## Step 2: Validate review verdict
+
+1. Read `rpi/features/{slug}/implement/IMPLEMENT.md`.
+2. Look for a `## Review` section with a verdict of `PASS` or `PASS with concerns`.
+3. If verdict is `FAIL`:
+   ```
+   Review verdict is FAIL for '{slug}'.
+   Fix the issues and re-run: /rpi:review {slug}
+   Cannot archive a feature that hasn't passed review.
+   ```
+   Stop.
+4. If no review section or verdict is found:
+   ```
+   No review verdict found for '{slug}'.
+   Run /rpi:review {slug} before archiving.
+   ```
+   Stop.
+
+## Step 3: Read delta contents
+
+1. Scan `rpi/features/{slug}/delta/ADDED/` for all files — store as `$ADDED_FILES`.
+2. Scan `rpi/features/{slug}/delta/MODIFIED/` for all files — store as `$MODIFIED_FILES`.
+3. Scan `rpi/features/{slug}/delta/REMOVED/` for all files — store as `$REMOVED_FILES`.
+4. Read the contents of each file found.
+
+If all three directories are empty:
+```
+No delta specs found for '{slug}'. Skipping specs merge.
+```
+Proceed to Step 5.
+
+## Step 4: Launch Nexus to merge delta into specs
+
+Use the Agent tool to launch Nexus for the merge:
+
+```
+You are Nexus. Merge the delta specs for feature '{slug}' into the main specs directory.
+
+## ADDED Files (copy to rpi/specs/)
+{for each file in $ADDED_FILES: filename and full contents}
+
+## MODIFIED Files (apply changes to existing rpi/specs/ files)
+{for each file in $MODIFIED_FILES: filename, delta contents, and current contents of the target spec file in rpi/specs/}
+
+## REMOVED Files (delete from rpi/specs/)
+{for each file in $REMOVED_FILES: filename}
+
+Your task:
+1. For each ADDED file: determine the correct path under rpi/specs/ and write the file there.
+   - Use the file's content as-is. Preserve the directory structure (e.g. delta/ADDED/auth/oauth.md → rpi/specs/auth/oauth.md).
+2. For each MODIFIED file: read the current spec at rpi/specs/{path}, apply the changes from the delta version.
+   - The delta file contains the updated version of the spec. Merge it intelligently:
+   - Preserve any sections in the original that aren't addressed by the delta
+   - Update sections that the delta modifies
+   - Add new sections from the delta
+3. For each REMOVED file: note the path under rpi/specs/ that should be deleted.
+
+Output format:
+## Merge Plan
+### Files to Write
+- {path}: {action: created | updated} — {brief description}
+
+### Files to Delete
+- {path} — {reason}
+
+### Warnings
+- {any conflicts or issues detected}
+(or "No warnings.")
+```
+
+Store the output as `$NEXUS_MERGE`.
+
+After Nexus responds, execute the merge plan:
+1. **ADDED**: Write each file to `rpi/specs/{path}` (create directories as needed).
+2. **MODIFIED**: Write the merged content to `rpi/specs/{path}`.
+3. **REMOVED**: Delete the files from `rpi/specs/`.
+
+## Step 5: Check for solutions worth saving
+
+1. Read `rpi/features/{slug}/implement/IMPLEMENT.md` for the review section.
+2. If the review flagged solutions saved to `rpi/solutions/`:
+   - Verify each referenced solution file exists in `rpi/solutions/`.
+   - If any are missing, warn:
+     ```
+     Warning: Solution '{path}' referenced in review but not found.
+     ```
+
+## Step 6: Delete feature directory
+
+Remove the entire feature directory:
+
+```bash
+rm -rf rpi/features/{slug}
+```
+
+## Step 7: Commit
+
+Stage all changes and commit:
+
+```bash
+git add -A
+git commit -m "chore: archive {slug} — delta merged, feature complete"
+```
+
+## Step 8: Output summary
+
+```
+Archive complete: {slug}
+
+Specs merged:
+- Added: {N} files
+- Modified: {N} files
+- Removed: {N} files
+
+Feature directory deleted: rpi/features/{slug}/
+History preserved in git.
+```

package/commands/rpi/docs.md

@@ -1,7 +1,7 @@
 ---
 name: rpi:docs
-description: Generate code documentation from implementation artifacts. Adds inline docs, updates README, generates API docs, and creates changelog entry. Final step in the RPI pipeline.
-argument-hint: "<feature-slug> [--skip-inline] [--skip-readme] [--skip-changelog]"
+description: Quill generates and updates documentation based on the implementation.
+argument-hint: "<feature-name>"
 allowed-tools:
   - Read
   - Write
@@ -10,188 +10,126 @@ allowed-tools:
   - Glob
   - Grep
   - Agent
-  - AskUserQuestion
 ---
 
-<objective>
-Generate documentation for a completed feature using all RPI artifacts as source. Adds inline code documentation, updates project README if needed, generates API docs for new endpoints, and creates a changelog entry.
-</objective>
+# /rpi:docs — Docs Phase
 
-<process>
+Quill reads all feature artifacts and generates documentation: README updates, changelog entries, API docs, and inline comments where non-obvious.
 
-## 1. Load config and parse arguments
-
-Read `.rpi.yaml` for folder path. Also read `profile` and `models` keys.
-Parse `$ARGUMENTS`:
-- First argument: `{feature-slug}` (required)
-- `--skip-inline`: skip adding inline code documentation
-- `--skip-readme`: skip README updates
-- `--skip-changelog`: skip changelog entry
-
-## 1b. Resolve model
-
-Resolve the model for the `review` phase following the Model Resolution Algorithm in the rpi-workflow skill. Store as `{resolved_model}`. If a model is resolved, output the status message before agent spawns.
-
-## 2. Validate prerequisites
-
-Verify the feature has passed review. Read `{folder}/{feature-slug}/implement/IMPLEMENT.md`.
-
-Check for review verdict:
-- If verdict is PASS → proceed
-- If verdict is FAIL → error:
-  ```
-  Feature has not passed review. Run /rpi:review {feature-slug} first.
-  ```
-- If IMPLEMENT.md doesn't exist → error:
-  ```
-  Implementation not found. Run /rpi:implement {feature-slug} first.
-  ```
-
-## 3. Gather all artifacts
-
-Read all feature artifacts for context:
-- `{folder}/{feature-slug}/REQUEST.md` — what was requested
-- `{folder}/{feature-slug}/research/RESEARCH.md` — decisions and trade-offs
-- `{folder}/{feature-slug}/plan/eng.md` — technical spec (APIs, models, architecture)
-- `{folder}/{feature-slug}/plan/pm.md` — acceptance criteria (if exists)
-- `{folder}/{feature-slug}/plan/PLAN.md` — task list with files
-- `{folder}/{feature-slug}/implement/IMPLEMENT.md` — what was actually built, deviations
-
-## 4. Identify documentation targets
-
-From IMPLEMENT.md and PLAN.md, collect:
-- All files created or modified
-- New public functions, classes, types, and exports
-- New API endpoints or routes
-- New configuration options or environment variables
-- Deviations from the plan (may need extra documentation)
-
-Use Glob and Grep to read the actual implemented files and identify what needs documentation.
-
-## 5. Launch parallel documentation agents
-
-Use the Agent tool to launch applicable agents concurrently. If a model was resolved in Step 1b, include `model: "{resolved_model}"` in each Agent tool call.
+---
 
-### Agent 1: Inline Documentation (unless --skip-inline)
+## Step 1: Load config and validate
+
+1. Read `.rpi.yaml` for config. Apply defaults if missing:
+   - `folder`: `rpi/features`
+   - `context_file`: `rpi/context.md`
+   - `commit_style`: `conventional`
+2. Parse `$ARGUMENTS` to extract `{slug}`.
+3. Validate `rpi/features/{slug}/implement/IMPLEMENT.md` exists. If not:
+   ```
+   IMPLEMENT.md not found for '{slug}'. Run /rpi:implement {slug} first.
+   ```
+   Stop.
+
+## Step 2: Validate review verdict
+
+1. Look for a review verdict in `rpi/features/{slug}/implement/IMPLEMENT.md`.
+2. The verdict appears in a `## Review` section as `PASS` or `PASS with concerns`.
+3. If verdict is `FAIL`:
+   ```
+   Review verdict is FAIL for '{slug}'.
+   Fix the issues identified in IMPLEMENT.md and re-run: /rpi:review {slug}
+   ```
+   Stop.
+4. If no review verdict is found:
+   ```
+   No review verdict found for '{slug}'. Run /rpi:review {slug} first.
+   ```
+   Stop.
+
+## Step 3: Gather context
+
+1. Read `rpi/features/{slug}/REQUEST.md` — store as `$REQUEST`.
+2. Read `rpi/features/{slug}/plan/PLAN.md` — store as `$PLAN`.
+3. Read `rpi/features/{slug}/implement/IMPLEMENT.md` — store as `$IMPLEMENT`.
+4. Read `rpi/context.md` (project context) if it exists — store as `$CONTEXT`.
+5. Scan `rpi/features/{slug}/delta/` for all files in ADDED/, MODIFIED/, and REMOVED/ — store as `$DELTA_CONTENTS`.
+6. Read `README.md` from the project root if it exists — store as `$CURRENT_README`.
+7. Read `CHANGELOG.md` from the project root if it exists — store as `$CURRENT_CHANGELOG`.
+
+## Step 4: Launch Quill
+
+Launch Quill agent with this prompt:
 
 ```
-You are documenting code for a completed feature.
-
-Read these artifacts for context:
-- {folder}/{feature-slug}/plan/eng.md
-- {folder}/{feature-slug}/implement/IMPLEMENT.md
-
-Then read each implemented file listed in IMPLEMENT.md.
-
-Add inline documentation ONLY where it adds value:
-1. Public functions/methods: brief JSDoc/docstring with params and return type
-2. Complex logic: short comment explaining WHY, not WHAT
-3. Non-obvious design decisions: reference the trade-off from eng.md
-4. New types/interfaces: brief description of purpose
+You are Quill. Generate and update documentation for feature: {slug}
+
+## Request
+{$REQUEST}
+
+## Plan
+{$PLAN}
+
+## Implementation
+{$IMPLEMENT}
+
+## Delta Specs
+{$DELTA_CONTENTS}
+
+## Project Context
+{$CONTEXT}
+
+## Current README
+{$CURRENT_README or "No README.md found."}
+
+## Current CHANGELOG
+{$CURRENT_CHANGELOG or "No CHANGELOG.md found."}
+
+Your task:
+1. Update README.md with new feature documentation (if the feature adds user-facing behavior or public API)
+   - Add a section or update an existing section — don't rewrite the entire README
+   - Include usage examples with concrete values
+   - If the feature is internal/refactoring only, skip README updates
+2. Write a changelog entry in conventional format
+   - Use the appropriate category: Added, Changed, Fixed, Removed
+   - Reference the feature slug
+   - If CHANGELOG.md exists, prepend the new entry under the correct version
+   - If CHANGELOG.md doesn't exist, create it with a header and the first entry
+3. Add API docs for new public interfaces
+   - Document exported functions, classes, or endpoints introduced by this feature
+   - Include parameter types, return types, and one usage example per interface
+   - Write docs where the project convention places them (JSDoc, docstrings, doc comments, or separate files)
+4. Add inline comments only where the code is non-obvious
+   - Explain WHY, not WHAT
+   - Focus on: non-obvious business rules, workarounds, performance tradeoffs, external API quirks
+   - Do NOT add comments that restate the code
 
 Rules:
-- Do NOT add obvious comments ("// returns the user" on a getUser function)
-- Do NOT document private/internal helpers unless logic is non-trivial
-- Match the project's existing documentation style and conventions
-- If the project has no inline docs convention, use minimal JSDoc/docstrings only on public APIs
-- Do NOT modify any behavior — documentation only
+- Keep docs DRY — don't repeat what the code already says
+- Match existing documentation style and tone
+- Use concrete examples, not abstract descriptions
+- If the code says WHAT, the docs should say WHY
 ```
 
-### Agent 2: API Documentation (if new endpoints exist)
+Store the output as `$QUILL_OUTPUT`.
 
-```
-You are generating API documentation for new endpoints.
+## Step 5: Commit documentation changes
 
-Read these artifacts:
-- {folder}/{feature-slug}/plan/eng.md (API design section)
-- {folder}/{feature-slug}/implement/IMPLEMENT.md
+1. Stage all documentation files changed by Quill:
+   ```bash
+   git add -A
+   ```
+2. Commit with a conventional message:
+   ```bash
+   git commit -m "docs({slug}): update documentation for {slug}"
+   ```
 
-Find all new API endpoints/routes in the implemented files using Grep.
+## Step 6: Output summary
 
-For each endpoint, document:
-- Method and path
-- Request parameters/body with types
-- Response format with types
-- Error responses
-- Authentication requirements
-- Example request/response
-
-Check if the project has an existing API docs file or pattern (e.g., docs/api.md, swagger/openapi spec, README API section). If yes, extend it. If no, create `{folder}/{feature-slug}/implement/API.md`.
-
-Use the format that matches existing project conventions.
 ```
+Documentation complete: {slug}
 
-### Agent 3: README & Changelog (unless both skipped)
+{$QUILL_OUTPUT summary — list of files updated and what changed}
 
+Next: /rpi:archive {slug}
 ```
-You are updating project documentation for a completed feature.
-
-Read these artifacts:
-- {folder}/{feature-slug}/REQUEST.md (feature summary)
-- {folder}/{feature-slug}/implement/IMPLEMENT.md (what was built, deviations)
-- {folder}/{feature-slug}/plan/eng.md (new dependencies, config)
-
-Tasks:
-
-1. README update (unless --skip-readme):
-   - Read the project's existing README.md
-   - Determine if the feature needs to be mentioned (new user-facing capability, new config, new dependency)
-   - If yes, add a concise entry in the appropriate section
-   - If the feature is purely internal/refactor, skip README update
-   - Do NOT rewrite the README — only add what's necessary
-
-2. Changelog entry (unless --skip-changelog):
-   - Check if CHANGELOG.md exists. If not, create it with Keep a Changelog format
-   - Add an entry under [Unreleased]:
-     - Added: new features
-     - Changed: modifications to existing features
-     - Fixed: bug fixes
-   - Keep entries concise — one line per change
-   - Reference the feature slug for traceability
-```
-
-## 6. Write DOCS.md summary
-
-After all agents complete, write `{folder}/{feature-slug}/implement/DOCS.md`:
-
-```markdown
-# Documentation: {Feature Title}
-
-Generated: {timestamp}
-
-## Inline Documentation
-- Files documented: {N}
-- Public APIs documented: {list}
-{Or: "Skipped (--skip-inline)"}
-
-## API Documentation
-- New endpoints: {N}
-- Docs location: {path}
-{Or: "No new endpoints"}
-
-## README
-- Updated: yes/no
-- Changes: {brief description}
-{Or: "Skipped (--skip-readme)"}
-
-## Changelog
-- Entry added: yes/no
-- Section: Added/Changed/Fixed
-{Or: "Skipped (--skip-changelog)"}
-```
-
-## 7. Present result
-
-Output:
-```
-Documentation complete for {feature-slug}:
-- Inline docs: {N} files documented
-- API docs: {endpoint count or "none"}
-- README: {updated or skipped}
-- Changelog: {entry added or skipped}
-
-Feature {feature-slug} is fully complete.
-All artifacts: {folder}/{feature-slug}/
-```
-
-</process>