@hanzlaa/rcode 2.1.0

package/rihal/skills/actions/3-solutioning/rihal-generate-project-context/steps/step-03-complete.md

@@ -0,0 +1,278 @@
+# Step 3: Context Completion & Finalization
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+- 🛑 NEVER generate content without user input
+- ✅ ALWAYS treat this as collaborative completion between technical peers
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- 💬 FOCUS on finalizing a lean, LLM-optimized project context
+- 🎯 ENSURE all critical rules are captured and actionable
+- ⚠️ ABSOLUTELY NO TIME ESTIMATES - AI development speed has fundamentally changed
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Show your analysis before taking any action
+- 📝 Review and optimize content for LLM context efficiency
+- 📖 Update frontmatter with completion status
+- 🚫 NO MORE STEPS - this is the final step
+
+## CONTEXT BOUNDARIES:
+
+- All rule categories from step-2 are complete
+- Technology stack and versions are documented
+- Focus on final review, optimization, and completion
+- Ensure the context file is ready for AI agent consumption
+
+## YOUR TASK:
+
+Complete the project context file, optimize it for LLM efficiency, and provide guidance for usage and maintenance.
+
+## COMPLETION SEQUENCE:
+
+### 1. Review Complete Context File
+
+Read the entire project context file and analyze:
+
+**Content Analysis:**
+
+- Total length and readability for LLMs
+- Clarity and specificity of rules
+- Coverage of all critical areas
+- Actionability of each rule
+
+**Structure Analysis:**
+
+- Logical organization of sections
+- Consistency of formatting
+- Absence of redundant or obvious information
+- Optimization for quick scanning
+
+### 2. Optimize for LLM Context
+
+Ensure the file is lean and efficient:
+
+**Content Optimization:**
+
+- Remove any redundant rules or obvious information
+- Combine related rules into concise bullet points
+- Use specific, actionable language
+- Ensure each rule provides unique value
+
+**Formatting Optimization:**
+
+- Use consistent markdown formatting
+- Implement clear section hierarchy
+- Ensure scannability with strategic use of bolding
+- Maintain readability while maximizing information density
+
+### 3. Final Content Structure
+
+Ensure the final structure follows this optimized format:
+
+```markdown
+# Project Context for AI Agents
+
+_This file contains critical rules and patterns that AI agents must follow when implementing code in this project. Focus on unobvious details that agents might otherwise miss._
+
+---
+
+## Technology Stack & Versions
+
+{{concise_technology_list}}
+
+## Critical Implementation Rules
+
+### Language-Specific Rules
+
+{{specific_language_rules}}
+
+### Framework-Specific Rules
+
+{{framework_patterns}}
+
+### Testing Rules
+
+{{testing_requirements}}
+
+### Code Quality & Style Rules
+
+{{style_and_quality_patterns}}
+
+### Development Workflow Rules
+
+{{workflow_patterns}}
+
+### Critical Don't-Miss Rules
+
+{{anti_patterns_and_edge_cases}}
+
+---
+
+## Usage Guidelines
+
+**For AI Agents:**
+
+- Read this file before implementing any code
+- Follow ALL rules exactly as documented
+- When in doubt, prefer the more restrictive option
+- Update this file if new patterns emerge
+
+**For Humans:**
+
+- Keep this file lean and focused on agent needs
+- Update when technology stack changes
+- Review quarterly for outdated rules
+- Remove rules that become obvious over time
+
+Last Updated: {{date}}
+```
+
+### 4. Present Completion Summary
+
+Based on user skill level, present the completion:
+
+**Expert Mode:**
+"Project context complete. Optimized for LLM consumption with {{rule_count}} critical rules across {{section_count}} sections.
+
+File saved to: `{output_folder}/project-context.md`
+
+Ready for AI agent integration."
+
+**Intermediate Mode:**
+"Your project context is complete and optimized for AI agents!
+
+**What we created:**
+
+- {{rule_count}} critical implementation rules
+- Technology stack with exact versions
+- Framework-specific patterns and conventions
+- Testing and quality guidelines
+- Workflow and anti-pattern rules
+
+**Key benefits:**
+
+- AI agents will implement consistently with your standards
+- Reduced context switching and implementation errors
+- Clear guidance for unobvious project requirements
+
+**Next steps:**
+
+- AI agents should read this file before implementing
+- Update as your project evolves
+- Review periodically for optimization"
+
+**Beginner Mode:**
+"Excellent! Your project context guide is ready! 🎉
+
+**What this does:**
+Think of this as a 'rules of the road' guide for AI agents working on your project. It ensures they all follow the same patterns and avoid common mistakes.
+
+**What's included:**
+
+- Exact technology versions to use
+- Critical coding rules they might miss
+- Testing and quality standards
+- Workflow patterns to follow
+
+**How AI agents use it:**
+They read this file before writing any code, ensuring everything they create follows your project's standards perfectly.
+
+Your project context is saved and ready to help agents implement consistently!"
+
+### 5. Final File Updates
+
+Update the project context file with completion information:
+
+**Frontmatter Update:**
+
+```yaml
+---
+project_name: '{{project_name}}'
+user_name: '{{user_name}}'
+date: '{{date}}'
+sections_completed:
+  ['technology_stack', 'language_rules', 'framework_rules', 'testing_rules', 'quality_rules', 'workflow_rules', 'anti_patterns']
+status: 'complete'
+rule_count: { { total_rules } }
+optimized_for_llm: true
+---
+```
+
+**Add Usage Section:**
+Append the usage guidelines from step 3 to complete the document.
+
+### 6. Completion Validation
+
+Final checks before completion:
+
+**Content Validation:**
+✅ All critical technology versions documented
+✅ Language-specific rules are specific and actionable
+✅ Framework rules cover project conventions
+✅ Testing rules ensure consistency
+✅ Code quality rules maintain standards
+✅ Workflow rules prevent conflicts
+✅ Anti-pattern rules prevent common mistakes
+
+**Format Validation:**
+✅ Content is lean and optimized for LLMs
+✅ Structure is logical and scannable
+✅ No redundant or obvious information
+✅ Consistent formatting throughout
+
+### 7. Completion Message
+
+Present final completion to user:
+
+"✅ **Project Context Generation Complete!**
+
+Your optimized project context file is ready at:
+`{output_folder}/project-context.md`
+
+**📊 Context Summary:**
+
+- {{rule_count}} critical rules for AI agents
+- {{section_count}} comprehensive sections
+- Optimized for LLM context efficiency
+- Ready for immediate agent integration
+
+**🎯 Key Benefits:**
+
+- Consistent implementation across all AI agents
+- Reduced common mistakes and edge cases
+- Clear guidance for project-specific patterns
+- Minimal LLM context usage
+
+**📋 Next Steps:**
+
+1. AI agents will automatically read this file when implementing
+2. Update this file when your technology stack or patterns evolve
+3. Review quarterly to optimize and remove outdated rules
+
+Your project context will help ensure high-quality, consistent implementation across all development work. Great work capturing your project's critical implementation requirements!"
+
+## SUCCESS METRICS:
+
+✅ Complete project context file with all critical rules
+✅ Content optimized for LLM context efficiency
+✅ All technology versions and patterns documented
+✅ File structure is logical and scannable
+✅ Usage guidelines included for agents and humans
+✅ Frontmatter properly updated with completion status
+✅ User provided with clear next steps and benefits
+
+## FAILURE MODES:
+
+❌ Final content is too verbose for LLM consumption
+❌ Missing critical implementation rules or patterns
+❌ Not optimizing content for agent readability
+❌ Not providing clear usage guidelines
+❌ Frontmatter not properly updated
+❌ Not validating file completion before ending
+
+## WORKFLOW COMPLETE:
+
+This is the final step of the Generate Project Context workflow. The user now has a comprehensive, optimized project context file that will ensure consistent, high-quality implementation across all AI agents working on the project.
+
+The project context file serves as the critical "rules of the road" that agents need to implement code consistently with the project's standards and patterns.

package/rihal/skills/actions/3-solutioning/rihal-generate-project-context/workflow.md

@@ -0,0 +1,43 @@
+# Generate Project Context Workflow
+
+**Goal:** Create a concise, optimized `project-context.md` file containing critical rules, patterns, and guidelines that AI agents must follow when implementing code. This file focuses on unobvious details that LLMs need to be reminded of.
+
+**Your Role:** You are a technical facilitator working with a peer to capture the essential implementation rules that will ensure consistent, high-quality code generation across all AI agents working on the project.
+
+---
+
+## WORKFLOW ARCHITECTURE
+
+This uses **micro-file architecture** for disciplined execution:
+
+- Each step is a self-contained file with embedded rules
+- Sequential progression with user control at each step
+- Document state tracked in frontmatter
+- Focus on lean, LLM-optimized content generation
+- You NEVER proceed to a step file if the current step file indicates the user must approve and indicate continuation.
+
+---
+
+## INITIALIZATION
+
+### Configuration Loading
+
+Load config from `{project-root}/.rihal/config.json` and resolve:
+
+- `project_name`, `output_folder`, `user_name`
+- `communication_language`, `document_output_language`, `user_skill_level`
+- `date` as system-generated current datetime
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Paths
+
+- `output_file` = `{output_folder}/project-context.md`
+
+---
+
+## EXECUTION
+
+Load and execute `./steps/step-01-discover.md` to begin the workflow.
+
+**Note:** Input document discovery and initialization protocols are handled in step-01-discover.md.

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rihal-checkpoint-preview
+description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".'
+---
+
+## Workflow
+
+
+# Checkpoint Review Workflow
+
+**Goal:** Guide a human through reviewing a change — from purpose and context into details.
+
+You are assisting the user in reviewing a change.
+
+## Global Step Rules (apply to every step)
+
+- **Path:line format** — Every code reference must use CWD-relative `path:line` format (no leading `/`) so it is clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
+- **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections.
+- **Language** — Speak in `{communication_language}`. Write any file output in `{document_output_language}`.
+
+## INITIALIZATION
+
+Load and read full config from `{project-root}/.rihal/config.yaml` and resolve:
+
+- `implementation_artifacts`
+- `planning_artifacts`
+- `communication_language`
+- `document_output_language`
+
+## FIRST STEP
+
+Read fully and follow `./step-01-orientation.md` to begin.
+
+## Output Format
+
+- 5-step walkthrough output inline in conversation (orientation → walkthrough → detail → testing → wrapup)
+- Each step front-loaded (entire step in one message, no drip-feed, no mid-step questions)
+- All code references use CWD-relative `path:line` format
+- Trail artifact generated per `./generate-trail.md` at end
+
+## Examples
+
+### Happy Path
+**Input:** `/rihal:checkpoint-preview` after a feature branch is complete
+**Expected:** 5-step human review session with clear focus on what matters, testing recommendations, wrapup decision.
+
+### Edge Case: No changes to review
+**Expected:** Exit early, suggest the user make changes first.

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/generate-trail.md

@@ -0,0 +1,38 @@
+# Generate Review Trail
+
+Generate a review trail from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.
+
+## Follow Global Step Rules in SKILL.md
+
+## INSTRUCTIONS
+
+1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats in step-01).
+2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. If total file content exceeds ~50k tokens, read only the files with the largest diff hunks in full and use hunks for the rest.
+3. If a spec exists, use its Intent section to anchor concern identification.
+4. Identify 2–5 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings.
+5. For each concern, select 1–4 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes.
+6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types).
+7. Format each stop using `path:line` per the global step rules:
+
+```
+**{Concern name}**
+
+- {one-line framing, ≤15 words}
+  `src/path/to/file.ts:42`
+```
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+## PRESENT
+
+Output after the orientation:
+
+```
+I built a review trail for this {change_type} (no author-produced trail was found):
+
+{generated trail}
+```
+
+The generated trail serves as the Suggested Review Order for subsequent steps. Set `review_mode` to `full-trail` — a trail now exists, so all downstream steps should treat it as one.
+
+If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable."

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/step-01-orientation.md

@@ -0,0 +1,105 @@
+# Step 1: Orientation
+
+Display: `[Orientation] → Walkthrough → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+## FIND THE CHANGE
+
+The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the change is identified:
+
+1. **Explicit argument**
+   Did the user pass a PR, commit SHA, branch, or spec file this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Spec file, commit, or branch → use directly.
+
+2. **Recent conversation**
+   Do the last few messages reveal what change the user wants reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Use the same routing as above.
+
+3. **Sprint tracking**
+   Check for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - Exactly one → suggest it and confirm with the user.
+   - Multiple → present as numbered options.
+   - None → fall through.
+
+4. **Current git state**
+   Check current branch and HEAD. Confirm: "I see HEAD is `<short-sha>` on `<branch>` — is this the change you want to review?"
+
+5. **Ask**
+   If none of the above identified a change, ask:
+   - What changed and why?
+   - Which commit, branch, or PR should I look at?
+   - Do you have a spec, bug report, or anything else that explains what this change is supposed to do?
+
+   If after 3 exchanges you still can't identify a change, HALT.
+
+Never ask extra questions beyond what the cascade prescribes. If a step above already identified the change, skip the remaining steps.
+
+## ENRICH
+
+Once a change is identified from any source above, fill in the complementary artifact:
+
+- If you have a spec, look for `baseline_commit` in its frontmatter to determine the diff baseline.
+- If you have a commit or branch, check `{implementation_artifacts}` for a spec whose `baseline_commit` is an ancestor of that commit/branch (i.e., the spec describes work done on top of that baseline).
+- If you found both a spec and a commit/branch, use both.
+
+## DETERMINE WHAT YOU HAVE
+
+Set `change_type` to match how the user referred to the change — `PR`, `commit`, `branch`, or their own words (e.g. `auth refactor`). Default to `change` if ambiguous.
+
+Set `review_mode` — pick the first match:
+
+1. **`full-trail`** — ENRICH found a spec with a `## Suggested Review Order` section. Intent source: spec's Intent section.
+2. **`spec-only`** — ENRICH found a spec but it has no Suggested Review Order. Intent source: spec's Intent section.
+3. **`bare-commit`** — no spec found. Intent source: commit message. If the commit message is terse (under 10 words), scan the diff for the primary change pattern and draft a one-sentence intent. Flag it as `[inferred]` in the output so the user can correct it.
+
+## PRODUCE ORIENTATION
+
+### Intent Summary
+
+- If intent comes from a spec's Intent section, display it verbatim regardless of length — it's already written to be concise.
+- For other sources (commit messages, bug reports, user description): if ≤200 tokens, display verbatim. If longer, distill to ≤200 tokens. Link to the full source when one exists (e.g. a file path or URL).
+- Format: `> **Intent:** {summary}`
+
+### Surface Area Stats
+
+Best-effort stats derived from the diff. Try these baselines in order:
+
+1. `baseline_commit` from the spec's frontmatter.
+2. Branch merge-base against `main` (or the default branch).
+3. `HEAD~1..HEAD` (latest commit only — tell the user).
+4. If git is unavailable or all of the above fail, skip stats and note: "Could not compute stats."
+
+Use `git diff --stat` and `git diff --numstat` for file-level counts, and scan the full diff content for the richer metrics.
+
+Display as:
+
+```
+N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces
+```
+
+- **Files changed**: count from `git diff --stat`.
+- **Modules touched**: distinct top-level directories with changes (from `--stat` file paths).
+- **Lines of logic**: added/modified lines excluding blanks, imports, formatting. Scan diff content; `~` because approximate.
+- **Boundary crossings**: changes spanning more than one top-level module. `0` if single module.
+- **New public interfaces**: new exports, endpoints, public methods found in the diff. `0` if none.
+
+Omit any metric you cannot compute rather than guessing.
+
+### Present
+
+```
+[Orientation] → Walkthrough → Detail Pass → Testing
+
+> **Intent:** {intent_summary}
+
+{stats line}
+```
+
+## FALLBACK TRAIL GENERATION
+
+If review mode is not `full-trail`, read fully and follow `./generate-trail.md` to build one from the diff. Then return here and continue to NEXT. If trail generation fails (e.g., git unavailable), the original review mode is preserved — step-02 handles this with its non-trail path.
+
+## NEXT
+
+Read fully and follow `./step-02-walkthrough.md`

package/rihal/skills/actions/4-implementation/rihal-checkpoint-preview/step-02-walkthrough.md

@@ -0,0 +1,89 @@
+# Step 2: Walkthrough
+
+Display: `Orientation → [Walkthrough] → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- Organize by **concern**, not by file. A concern is a cohesive design intent — e.g., "input validation," "state management," "API contract." One file may appear under multiple concerns; one concern may span multiple files.
+- The walkthrough activates **design judgment**, not correctness checking. Frame each concern as "here's what this change does and why" — the human evaluates whether it's the right approach for the system.
+
+## BUILD THE WALKTHROUGH
+
+### Identify Concerns
+
+**With Suggested Review Order** (`full-trail` mode — the normal path, including when step-01 generated a trail):
+
+1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback).
+2. Resolve each stop to a file in the current repo. Output in `path:line` format per the standing rule.
+3. Read the diff to understand what each stop actually does.
+4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes.
+
+**Without Suggested Review Order** (fallback when trail generation failed, e.g., git unavailable):
+
+1. Get the diff against the appropriate baseline (same rules as step 1).
+2. Identify concerns by reading the diff for cohesive design intents:
+   - Functional groupings — what user-facing behavior does each cluster of changes support?
+   - Architectural layers — does the change cross boundaries (API → service → data)?
+   - Design decisions — where did the author choose between alternatives?
+3. For each concern, identify the key code locations as `path:line` stops.
+
+### Order for Comprehension
+
+Sequence concerns top-down: start with the highest-level intent (the "what and why"), then drill into supporting implementation. Within each concern, order stops so each one builds on the previous. The reader should never encounter a reference to something they haven't seen yet.
+
+If the change has a natural entry point (e.g., a new public API, a config change, a UI entry point), lead with it.
+
+### Write Each Concern
+
+For each concern, produce:
+
+1. **Heading** — a short phrase naming the design intent (not a file name, not a module name).
+2. **Why** — 1–2 sentences: what problem this concern addresses, why this approach was chosen over alternatives. If the spec documents rejected alternatives, reference them here.
+3. **Stops** — each stop on its own line: `path:line` followed by a brief phrase (not a sentence) describing what this location does for the concern. Keep framing under 15 words per stop.
+
+Target 2–5 concerns for a typical change. A single-concern change is fine — don't invent groupings. A change with more than 7 concerns is a signal the scope may be too large, but present it anyway.
+
+## PRESENT
+
+Output the full walkthrough as a single message with this structure:
+
+```
+Orientation → [Walkthrough] → Detail Pass → Testing
+```
+
+Then each concern group using this format:
+
+```
+### {Concern Heading}
+
+{Why — 1–2 sentences}
+
+- `path:line` — {brief framing}
+- `path:line` — {brief framing}
+- ...
+```
+
+End the message with:
+
+```
+---
+
+Take your time — click through the stops, read the diff, trace the logic. While you are reviewing, you can:
+- "run advanced elicitation on the error handling"
+- "party mode on whether this schema migration is safe"
+- or just ask anything
+
+When you're ready, say **next** and I'll surface the highest-risk spots.
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## NEXT
+
+Default: read fully and follow `./step-03-detail-pass.md`