@fiftth/fiftth-cli 1.0.1 → 1.1.1

package/.fiftthnexus/skills/env-implement-prompt.md

@@ -0,0 +1,65 @@
+# TASK
+
+Fix issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}
+
+<issue>
+
+!`gh issue view {{ISSUE_NUMBER}}`
+
+</issue>
+
+Only work on the issue specified.
+
+Work on branch {{BRANCH}}. Make commits, run tests, and close the issue when done.
+
+# CONTEXT
+
+Here are the last 2 commits:
+
+<recent-commits>
+
+!`git log -n 2 --format="%H%n%ad%n%B---" --date=short`
+
+</recent-commits>
+
+# EXPLORATION
+
+Explore the repo and fill your context window with relevant information that will allow you to complete the task.
+
+Pay extra attention to test files that touch the relevant parts of the code.
+
+# EXECUTION
+
+If applicable, use RGR to complete the task.
+
+## Scope Discipline
+
+- Change only the files directly required to complete the issue.
+- Before editing a file, confirm it is required by the issue.
+
+1. RED: write one test
+2. GREEN: write the implementation to pass that test
+3. REPEAT until done
+4. REFACTOR the code
+
+# COMMIT
+
+Make a git commit. The commit message must:
+
+1. Start with `RALPH:` prefix
+2. Include task completed + PRD reference
+3. Key decisions made
+4. Files changed
+5. Blockers or notes for next iteration
+
+Keep it concise.
+
+# THE ISSUE
+Do not close the issue - this will be done later.
+
+Once complete, output <promise>COMPLETE</promise>.
+
+# FINAL RULES
+
+ONLY WORK ON A SINGLE TASK.
+DO NOT MODIFY UNRELATED FILES.

package/.fiftthnexus/skills/env-plan-prompt.md

@@ -0,0 +1,33 @@
+# ISSUES
+
+Here are the open issues in the repo:
+
+<issues-json>
+
+!`gh issue list --state open --label ai-running-orchestrator --json number,title,body,labels,comments --jq '[.[] | {number, title, body, labels: [.labels[].name], comments: [.comments[].body]}]'`
+
+</issues-json>
+
+# TASK
+
+Analyze the open issues and build a dependency graph. For each issue, determine whether it **blocks** or **is blocked by** any other open issue.
+
+An issue B is **blocked by** issue A if:
+
+- B requires code or infrastructure that A introduces
+- B and A modify overlapping files or modules, making concurrent work likely to produce merge conflicts
+- B's requirements depend on a decision or API shape that A will establish
+
+An issue is **unblocked** if it has zero blocking dependencies on other open issues.
+
+For each unblocked issue, assign a branch name using the format `fiftth/PRD-{parent-prd-number}`. If there is no parent PRD number available, use `fiftth/PRD-{number}` as a fallback.
+
+# OUTPUT
+
+Output your plan as a JSON object wrapped in `<plan>` tags:
+
+<plan>
+{"issues": [{"number": 42, "title": "Fix auth bug", "branch": "fiftth/PRD-42"}]}
+</plan>
+
+Include only unblocked issues. If every issue is blocked, include the single highest-priority candidate (the one with the fewest or weakest dependencies).

package/.fiftthnexus/skills/env-review-prompt.md

@@ -0,0 +1,61 @@
+# TASK
+
+Review the code changes on branch {{BRANCH}} for issue #{{ISSUE_NUMBER}}: {{ISSUE_TITLE}}
+
+You are doing a lightweight final review pass on an implementation that already happened.
+Your job is to catch a concrete blocker quickly, not to reopen the whole task.
+
+# CONTEXT
+
+<issue>
+
+!`gh issue view {{ISSUE_NUMBER}}`
+
+</issue>
+
+
+# SCOPE GUARDRAILS
+
+- Review only the files already present in the diff, plus tests that are directly needed to validate those changes.
+- Do not perform opportunistic cleanup, formatting, renames, broad refactors, or second-pass feature work.
+- Prefer a fast stop over exhaustive analysis when the diff already looks sound.
+
+# REVIEW PROCESS
+
+## 1. Inspect only the changed code paths
+
+Read the diff carefully. Focus on concrete correctness risks in the changed paths: fragile logic, unchecked assumptions, missing guards, incorrect conditionals, or missing test coverage that can be demonstrated quickly.
+
+## 2. Run targeted validation
+
+Run only the smallest validation needed for confidence in the changed paths. Prefer targeted tests or a focused build command over broad exploratory work.
+
+## 3. Fix only concrete blockers
+
+If you can show a concrete bug, missing guard, or missing focused test, fix it.
+If you cannot demonstrate a real problem quickly, do not widen the scope.
+
+## 4. Keep the pass small
+
+This review stage is not a second implementation stage.
+Avoid exhaustive audits, broad maintainability rewrites, or speculative edge-case hunts.
+
+## 5. Apply project standards
+
+Follow the established coding standards in the project.
+
+## 6. Preserve functionality
+
+Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
+Never widen the scope of the branch by editing unrelated modules.
+
+# EXECUTION
+
+1. Inspect the diff and the surrounding code needed to understand it.
+2. Run targeted validation for the risky changed paths.
+3. If you make a follow-up fix, keep it small and commit once with a message starting with `RALPH: Review -`.
+4. If no concrete blocker is found, stop without making extra edits.
+
+If the code is already sound, do nothing.
+
+Once complete, output <promise>COMPLETE</promise>.

package/.fiftthnexus/skills/grill-me.md

@@ -0,0 +1,9 @@
+---
+name: grill-me
+description: Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".
+---
+
+Interview me relentlessly about every aspect of this plan until we reach a shared understanding.
+Walk down each branch of the design tree resolving dependencies between decisions one by one.
+If a question can be answered by exploring the codebase, explore the codebase instead.
+For each question, provide your recommended answer. Only implement after user request.

package/.fiftthnexus/skills/prd-to-issues.md

@@ -0,0 +1,150 @@
+---
+name: prd-to-issues
+description: Break a PRD into independently-grabbable GitHub issues with priority labels and dependency metadata, ready for the Copilot orchestrator. Use when user wants to convert a PRD to issues, create implementation tickets, or break down a PRD into work items.
+---
+
+# PRD to Issues
+
+Break a PRD into independently-grabbable GitHub issues using vertical slices (tracer bullets).
+Issues are created **ready for the orchestrator** — with priority labels, dependency metadata, and the ai-running-orchestrator label.
+
+This workflow is repository-scoped. If a task spans multiple repositories, run it once per repository against that repository's PRD.
+This workflow must not create child issues in a repository that does not match the task and repository metadata of the selected PRD.
+
+## Process
+
+### 1. Locate the PRD
+
+Ask the user for the PRD GitHub issue number (or URL).
+If the PRD is not already in your context window, fetch it with gh issue view <number> (with comments).
+
+### 1.5 Validate repository scope
+
+Extract the `task-id` and `repository` metadata from the PRD body.
+Run `fiftth planning-context <TASK_ID> --json` from the current repository.
+If the command reports `repositoryMatch: false`, or if `currentRepository` does not equal the PRD `repository` metadata, stop immediately and tell the user to switch to the correct repository before creating child issues.
+
+### 2. Explore the codebase (optional)
+
+If you have not already explored the codebase, do so to understand the current state of the code.
+
+### 3. Draft vertical slices
+
+Break the PRD into **tracer bullet** issues.
+Each issue is a thin vertical slice that cuts through ALL integration layers end-to-end, NOT a horizontal slice of one layer.
+
+Slices may be 'HITL' or 'AFK'. HITL slices require human interaction, such as an architectural decision or a design review.
+AFK slices can be implemented and merged without human interaction. Prefer AFK over HITL where possible.
+
+<vertical-slice-rules>
+- Each slice delivers a narrow but COMPLETE path through every layer (schema, API, UI, tests)
+- A completed slice is demoable or verifiable on its own
+- Prefer many thin slices over few thick ones
+</vertical-slice-rules>
+
+### 4. Assign priority to each slice
+
+Assign a priority to each slice based on execution order and criticality:
+
+<priority-rules>
+- **P0-critical**: Foundation slices that everything else depends on (schema changes, core API). These MUST be done first.
+- **P1-high**: Core feature slices that deliver the primary value. Depend on P0 but can run in parallel with each other.
+- **P2-medium**: Enhancement slices that improve the feature but aren't essential for the first pass.
+- **P3-low**: Polish, edge cases, nice-to-haves. Can be done last or deferred.
+</priority-rules>
+
+The priority assignment must reflect the **natural execution order**: if slice B depends on slice A, then A must have equal or higher priority than B.
+
+### 5. Quiz the user
+
+Present the proposed breakdown as a numbered list. For each slice, show:
+- **Title**: short descriptive name
+- **Type**: HITL / AFK
+- **Priority**: P0 / P1 / P2 / P3
+- **Blocked by**: which other slices (if any) must complete first
+- **User stories covered**: which user stories from the PRD this addresses
+
+Ask the user:
+- Does the granularity feel right? (too coarse / too fine)
+- Are the dependency relationships correct?
+- Are the priorities correct? (Do they reflect the right execution order?)
+- Should any slices be merged or split further?
+- Are the correct slices marked as HITL and AFK?
+
+Iterate until the user approves the breakdown.
+
+### 6. Create the GitHub issues
+
+For each approved slice, create a GitHub issue using gh issue create.
+**Create issues in dependency order** (blockers first) so you can reference real issue numbers in the "Blocked by" field.
+
+For each issue, use the following command format:
+
+```bash
+gh issue create \
+  --title "<title>" \
+  --label "ai-running-orchestrator" \
+  --label "<priority-label>" \
+  --body "<body>"
+```
+
+Where <priority-label> is one of: P0-critical, P1-high, P2-medium, P3-low.
+Use the issue body template below.
+
+<issue-template>
+## Parent PRD
+#<prd-issue-number>
+
+## Task Metadata
+task-id: <TASK_ID>
+repository: <OWNER/REPO>
+
+## What to build
+A concise description of this vertical slice. Describe the end-to-end behavior, not layer-by-layer implementation.
+Reference specific sections of the parent PRD rather than duplicating content.
+
+## Acceptance criteria
+- [ ] Criterion 1
+- [ ] Criterion 2
+- [ ] Criterion 3
+
+## Dependencies
+depends-on: #<issue-number>
+depends-on: #<issue-number>
+
+Or "None — can start immediately" if no blockers.
+
+## User stories addressed
+Reference by number from the parent PRD:
+- User story 3
+- User story 7
+
+## Type
+AFK / HITL
+</issue-template>
+
+### Important rules for issue creation
+
+1. Every issue MUST have the ai-running-orchestrator label — this is how the orchestrator finds them.
+2. Every issue MUST have exactly ONE priority label (P0-critical, P1-high, P2-medium, or P3-low).
+3. Dependencies MUST use the exact format depends-on: #<number> — this is what the orchestrator parses.
+4. Every child issue MUST include the same task metadata as the parent PRD in the issue body.
+5. Create issues in dependency order so you can reference real issue numbers.
+6. Do NOT close or modify the parent PRD issue.
+7. HITL issues should NOT get the ai-running-orchestrator label — the orchestrator only assigns AFK work to Copilot. Instead, label HITL issues with just the priority label so they are tracked but not auto-assigned.
+
+### After creation
+
+Once all issues are created, print a summary table:
+
+| # | Title | Priority | Blocked By | Type |
+|---|-------|----------|------------|------|
+| #42 | Add user schema | P0-critical | None | AFK |
+| #43 | Create API endpoint | P1-high | #42 | AFK |
+| #44 | Build UI form | P1-high | #42 | AFK |
+| #45 | Design review | P1-high | None | HITL |
+
+Tell the user:
+- "All AFK issues have been labeled with ai-running-orchestrator and are ready for the orchestrator."
+- "Run the orchestrator to start: npx tsx custom-agents/actions/orchestrator.ts"
+- "Or trigger it from GitHub Actions: Actions → Copilot Parallel Orchestrator → Run workflow"

package/.fiftthnexus/skills/write-prd.md

@@ -0,0 +1,70 @@
+---
+name: write-a-prd
+description: Create a PRD through user interview, codebase exploration, and module design, then submit as a GitHub issue. Use when user wants to write a PRD, create a product requirements document, or plan a new feature.
+---
+
+This skill will be invoked when the user wants to create a PRD. You may skip steps if you don't consider them necessary.
+
+This workflow is repository-scoped. If a task spans multiple repositories, create one PRD per repository in the repository currently being analyzed.
+This workflow must never create a PRD in a repository that is not linked to the selected Fiftth task.
+When you create the PRD issue, add the `dev-report` label.
+
+1. Ask the user for a long, detailed description of the problem they want to solve and any potential ideas for solutions.
+2. Ask which Fiftth task the user wants to work on. If they do not provide a task id directly, ask them to choose the task first.
+3. Before exploring or drafting the PRD, run `fiftth planning-context <TASK_ID> --json` from the current repository.
+4. Read the command output and verify that `repositoryMatch` is `true`.
+5. If `repositoryMatch` is `false`, stop immediately. Tell the user that the current repository does not belong to the selected task, list the repositories returned by the command, and do not create a PRD issue in the current repository.
+6. If `repositoryMatch` is `true`, use the `currentRepository` returned by the command as the repository metadata for the PRD and continue.
+7. Explore the repo to verify thir assertions and understand the current state of the codebase.
+8. Interview the user relentlessly about every aspect of this plan until you reach a shared understanding. Walk down each branch of the design tree, resolving dependencies between decisions one-by-one.
+9. Sketch out the major modules you will need to build or modify to complete the implementation. Actively look for opportunities to extract deep modules that can be tested in isolation. A deep module (as opposed to a shallow module) is one which encapsulates a lot of functionality in a simple, testable interface which rarely changes. Check with the user that these modules match their expectations. Check with the user which modules they want tests written for.
+10. Once you have a complete understanding of the problem and solution, use the template below to write the PRD. The PRD should be submitted as a GitHub issue.
+
+<prd-title-issue>PRD[<TASK_ID>]: <RESUMED_DESCRIPTION></prd-title-issue>
+
+<prd-template>
+## Task Metadata
+task-id: <TASK_ID>
+repository: <OWNER/REPO>
+
+## Problem Statement
+The problem that the user is facing, from the user's perspective.
+
+## Solution
+The solution to the problem, from the user's perspective.
+
+## User Stories
+A LONG, numbered list of user stories. Each user story should be in the format of:
+
+1. As an <actor>, I want a <feature>, so that <benefit>
+
+<user-story-example>
+1. As a mobile bank customer, I want to see balance on my accounts, so that I can make better informed decisions about my spending
+</user-story-example>
+
+This list of user stories should be extremely extensive and cover all aspects of the feature.
+
+## Implementation Decisions
+A list of implementation decisions that were made. This can include:
+- The modules that will be built/modified
+- The interfaces of those modules that will be modified
+- Technical clarifications from the developer
+- Architectural decisions
+- Schema changes
+- API contracts
+- Specific interactions
+
+Do NOT include specific file paths or code snippets. They may end up being outdated very quickly.
+
+## Testing Decisions
+A list of testing decisions that were made. Include:
+- A description of what makes a good test (only test external behavior, not implementation details)
+- Which modules will be tested
+- Prior art for the tests (i.e. similar types of tests in the codebase)
+
+## Out of Scope
+A description of the things that are out of scope for this PRD.
+
+## Further Notes
+Any further notes about the feature.
+</prd-template>