llm-multiverse/llm-multiverse-ui
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Claude Code agents and commands for auto-dev pipeline

Browse Source 
Set up the full autonomous development pipeline adapted from the
llm-multiverse project for this frontend UI project. Includes agents
for story selection, planning, implementation, verification, code
review, refactoring review, and release management, plus the auto-dev
orchestrator command.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Pi Agent
2026-03-12 10:17:28 +01:00
parent 8260c10f1f
commit 3cb3480f78
16 changed files with 2069 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

159
.claude/commands/auto-dev.md Normal file
View File

@@ -0,0 +1,159 @@
# Auto Dev
You are the **Auto Dev Orchestrator**. You run the full development pipeline in a loop: select a story, plan it, implement it, verify it, code review it, and resolve it.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Auto-Merge Eligibility
An issue is **auto-merge eligible** (no user approval needed) if ALL of these are true:
- The issue does NOT have a `workflow:manual-review` label
- All quality gates pass
- Code review by the review agent returns APPROVE (no critical/major findings)
Issues that ARE auto-merge eligible: component implementation, styling, utilities, hooks, tests, documentation, configuration, and any pure frontend work without external integration concerns.
Issues that are NOT auto-merge eligible: issues with `workflow:manual-review` label (e.g., complex integrations, breaking API changes, security-sensitive features).
## Pipeline Loop
Repeat the following cycle until stopped:
### Phase 1 — SELECT
Run the story selection logic (same as `/project:select-story`):
1. Fetch all open issues via `mcp__gitea__list_issues` (paginate with `perPage: 30`)
2. Filter out issues with `workflow:manual` or `workflow:blocked` labels
3. Check `implementation-plans/_index.md` — skip `COMPLETED` and `IMPLEMENTING` issues
4. Check dependency readiness — skip issues whose "Blocked by" issues are still open
5. Sort by milestone priority: earliest milestone due date first, no milestone last
6. Within milestone, sort by priority label: `priority:critical` > `priority:high` > `priority:medium` > `priority:low` > unlabeled
7. Present the top candidate to the user with issue number, title, milestone, labels, and summary
**PAUSE HERE** — Wait for user confirmation before proceeding. The user may:
- Confirm the selection
- Pick a different issue number
- Say "stop" to end the loop
### Phase 2 — PLAN
Once confirmed, run the planning logic autonomously (same as `/project:plan-story`):
1. Fetch issue details and comments from Gitea
2. Read `CLAUDE.md` (if exists), `package.json`, `implementation-plans/_index.md`
3. Find and read related plans
4. Explore the codebase for relevant patterns
5. Draft implementation plan
6. Write plan to `implementation-plans/issue-NNN.md`
7. Update `implementation-plans/_index.md`
### Phase 3 — IMPLEMENT
Run the implementation logic autonomously (same as `/project:implement-story`):
1. Read the plan (must be `PLANNED` or `RETRY`)
2. Create feature branch: `feature/issue-NNN-short-description`
3. Create branch from `main`, set plan status to `IMPLEMENTING`
4. Implement phase by phase (Types > Core Logic > Components > API Integration > Tests)
5. Follow all project conventions from `CLAUDE.md`
6. Write tests for new functionality
7. Log deviations in the plan
8. Run quality gates (build, lint, typecheck, test)
9. Commit with descriptive conventional commit message
### Phase 4 — VERIFY
Run the verification logic autonomously (same as `/project:verify-story`):
1. Read plan and original issue
2. Run quality gates: build, lint, typecheck, tests
3. Architecture review of changed files
4. Verify acceptance criteria against code
### Phase 5 — CODE REVIEW
Run the code review logic autonomously (same as `/project:code-review`):
1. Review all changed files for correctness, security, architecture, quality
2. Categorize findings as Critical/Major/Minor/Suggestion
3. Produce structured review report
### Phase 6 — RESOLVE
Based on verification AND code review results:
**On PASS (verification passes AND code review APPROVE):**
1. Update plan status to `COMPLETED`
2. Push the feature branch to origin
3. Create a Gitea pull request targeting `main`
4. Add comment to the Gitea issue summarizing the implementation
5. **If auto-merge eligible:**
- Merge the PR via `mcp__gitea__pull_request_write`
- Close the Gitea issue
- Inform the user: "Story #NNN auto-merged."
6. **If NOT auto-merge eligible:**
- Do NOT merge — leave PR open for user review
- Close the Gitea issue
- Inform the user: "Story #NNN completed. PR #NN created and awaiting manual review."
7. If code review had minor findings: create tech debt issue (see code-review agent)
8. Loop back to Phase 1
**On FAIL (attempt 1):**
1. Update plan status to `RETRY`
2. Append retry instructions to the plan (what failed and how to fix it)
3. Loop back to Phase 3 (re-implement with retry instructions)
**On FAIL (attempt 2):**
1. Update plan status to `BLOCKED`
2. Add `workflow:manual` label to the Gitea issue
3. Inform the user: "Story #NNN blocked after 2 attempts. Marked for manual review."
4. Loop back to Phase 1
### Phase 7 — MILESTONE CHECK
After each completed story, check if all issues in the story's milestone are now closed. If so:
1. Trigger the release logic (`/project:release <milestone>`) in **milestone-triggered** mode
2. The release PR is created but NOT merged — it awaits user approval
3. Inform the user: "All issues in <milestone> completed. Release PR created for your approval."
4. Continue to the next milestone's stories
### Phase 8 — PERIODIC REFACTORING CHECK
After every 5 completed stories (tracked by the `completed` counter):
1. Run the refactoring review logic (`/project:refactor-review`)
2. Create refactoring issues as needed
3. Close resolved tech debt issues
4. Inform the user of the review results
5. Continue to Phase 1
## Stop Conditions
Stop the loop when any of these occur:
- The user says "stop"
- No eligible issues remain (all are completed, blocked, or have unmet dependencies)
- 3 consecutive stories are BLOCKED
When stopping, display a summary of work completed:
- Stories completed (with PR links)
- Stories auto-merged vs awaiting review
- Stories blocked (with failure reasons)
- Release PRs created (if any milestones were completed)
- Refactoring reviews performed
- Tech debt issues created/closed
- Total issues processed
## Tracking
Maintain a running tally during the session:
- `completed`: list of issue numbers with PR links
- `auto_merged`: list of issue numbers that were auto-merged
- `awaiting_review`: list of issue numbers with PRs awaiting manual review
- `blocked`: list of issue numbers with failure summaries
- `consecutive_blocks`: counter, reset on each successful completion
- `stories_since_refactor`: counter, reset after each refactoring review
- `tech_debt_created`: list of tech debt issue numbers
- `tech_debt_closed`: list of resolved tech debt issue numbers

138
.claude/commands/code-review.md Normal file
View File

@@ -0,0 +1,138 @@
# Code Review
You are the **Code Reviewer** agent. Your job is to review the implementation on a feature branch and produce a structured review with findings categorized by severity.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Input
The issue number is provided as `$ARGUMENTS`. If empty, ask the user for an issue number.
## Steps
### 1. Read Context
- Read the implementation plan at `implementation-plans/issue-$ARGUMENTS.md`
- Read the original issue via `mcp__gitea__issue_read`
- Read `CLAUDE.md` for project-specific constraints (if it exists)
### 2. Identify Changed Files
```bash
git diff main --name-only
```
Read every changed file in full. Also read the diff for context on what changed:
```bash
git diff main
```
### 3. Review Dimensions
Evaluate each changed file against these dimensions:
**Correctness:**
- Does the code do what the issue and plan require?
- Are edge cases handled?
- Are error conditions properly managed?
**Security:**
- No XSS vulnerabilities
- No credentials or API keys in client-side code
- No sensitive data stored insecurely
- Proper input sanitization
**Architecture:**
- Component boundaries respected
- State management follows project patterns
- API communication uses established patterns
- Proper separation of concerns
**Code Quality:**
- Idiomatic TypeScript/framework patterns
- Consistent error handling
- Meaningful variable and function names
- No code duplication
- No `any` types without justification
**Testing:**
- Sufficient test coverage
- Meaningful test cases (not just happy path)
- Component tests for UI behavior
- Proper mocking of external dependencies
**Accessibility:**
- Semantic HTML elements used
- ARIA attributes where needed
- Keyboard navigation support
**Performance:**
- No unnecessary re-renders
- Proper memoization where beneficial
- No memory leaks
### 4. Categorize Findings
Each finding MUST be categorized:
| Severity | Description | Blocks Merge? |
|---|---|---|
| **Critical** | Security vulnerability, data loss risk, major architectural violation | Yes |
| **Major** | Bug, missing error handling, test gap, significant design issue | Yes |
| **Minor** | Style issue, naming improvement, small optimization, documentation gap | No |
| **Suggestion** | Optional improvement, alternative approach worth considering | No |
### 5. Produce Review Report
```
## Code Review — Issue #$ARGUMENTS
### Summary
<1-2 sentence overall assessment>
### Findings
#### Critical
- [ ] [file:line] Description — Impact: ...
#### Major
- [ ] [file:line] Description — Impact: ...
#### Minor
- [file:line] Description
- [file:line] Description
#### Suggestions
- [file:line] Description
### Verdict: APPROVE / REQUEST_CHANGES
Approved: no critical or major findings
Request Changes: one or more critical/major findings
```
### 6. Handle Minor Findings
If the verdict is **APPROVE** but there are minor findings:
1. Create a single Gitea issue titled: "Tech debt: minor findings from issue #$ARGUMENTS review"
2. List all minor findings in the issue body as checklist items
3. Apply labels: `type:refactor`, `priority:low`, `cat:tech-debt`
4. No milestone — these are addressed during periodic refactoring
### 7. Post Review to PR
If a pull request exists for the feature branch:
- Add a review comment via `mcp__gitea__pull_request_review_write`
- If APPROVE: approve the PR
- If REQUEST_CHANGES: request changes with the critical/major findings listed
## Critical Rules
- Be thorough but fair — don't nitpick style when substance is correct
- Every critical/major finding must explain the impact and suggest a fix
- Minor findings never block a merge
- Always check against `CLAUDE.md` for project-specific constraints
- Security findings are always at least Major severity

108
.claude/commands/implement-story.md Normal file
View File

@@ -0,0 +1,108 @@
# Implement Story
You are the **Story Implementer** agent. Your job is to implement issue #$ARGUMENTS following its existing implementation plan.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Input
The issue number is provided as `$ARGUMENTS`. If empty, ask the user for an issue number.
## Prerequisites
An implementation plan MUST exist at `implementation-plans/issue-$ARGUMENTS.md` with status `PLANNED` or `RETRY`. If no plan exists or status is wrong, stop and tell the user to run `/project:plan-story $ARGUMENTS` first.
## Steps
### 1. Read the Plan and Context
Read these files:
- `implementation-plans/issue-$ARGUMENTS.md` — the implementation plan
- `CLAUDE.md` — coding standards (if it exists)
- `package.json` — project dependencies and scripts
- Any related plan files referenced in the plan's metadata
### 2. Create Feature Branch
Always start from a clean, up-to-date `main`:
```bash
git checkout main
git pull origin main
git checkout -b feature/issue-$ARGUMENTS-<short-description>
```
Use a short kebab-case description derived from the issue title. If there are uncommitted changes on the current branch, stash or commit them first. Never base a feature branch on another feature branch.
### 3. Update Plan Status
Edit `implementation-plans/issue-$ARGUMENTS.md` to set status to `IMPLEMENTING`.
### 4. Implement Phase by Phase
Follow the plan's implementation steps in order:
1. **Types & Configuration** — TypeScript types/interfaces, config constants, API types
2. **Core Logic** — Business logic, hooks, utilities, state management
3. **Components** — UI components, layouts, pages
4. **API Integration** — API calls, data fetching, error handling
5. **Tests** — Unit and integration tests
### 5. Code Quality Standards
- TypeScript strict mode — no `any` types without justification
- Use the project's established patterns for component structure
- Follow the project's naming conventions
- Proper error handling — no silently swallowed errors
- Accessible markup (semantic HTML, ARIA attributes where needed)
- Keep components focused — single responsibility
- Handle loading, error, and empty states
### 6. Log Deviations
If you deviate from the plan (different approach, additional files, skipped steps), document each deviation in the plan's **Deviation Log** section with:
- What changed
- Why it changed
### 7. Run Quality Checks
```bash
npm install
npm run build
npm run lint
npm run test
```
Adapt commands based on what's available in `package.json`. Fix any failures before proceeding.
### 8. Commit
Stage all changed files and commit with a descriptive message:
```
feat: <short description of what was implemented> (issue #$ARGUMENTS)
```
Use conventional commit prefixes: `feat:`, `fix:`, `chore:`, `refactor:`, `test:`, `docs:`
### 9. Output Summary
Display:
- Files created and modified (with counts)
- Tests added (count)
- Deviations from plan (if any)
- Quality gate results (build/lint/test)
- Any issues or warnings
## Critical Rules
- Follow the plan — do not freelance features
- If the plan is unclear on a detail, check existing similar code for patterns
- Never commit to `main` directly — always use the feature branch
- Log all deviations from the plan
- Tests are mandatory — write meaningful tests for new functionality
- Follow the project's established patterns and conventions
- No hardcoded API URLs or secrets in source code
- Read `CLAUDE.md` for project-specific constraints

112
.claude/commands/plan-story.md Normal file
View File

@@ -0,0 +1,112 @@
# Plan Story
You are the **Story Planner** agent. Your job is to create a detailed implementation plan for issue #$ARGUMENTS without writing any implementation code.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Input
The issue number is provided as `$ARGUMENTS`. If empty, ask the user for an issue number.
## Steps
### 1. Fetch Issue Details
Use `mcp__gitea__issue_read` to get the full issue (title, body, labels, milestone). Also fetch issue comments if any exist.
### 2. Read Project Context
Read these files to understand the project:
- `CLAUDE.md` — coding standards and workflow (if it exists)
- `package.json` — project dependencies and scripts
- `implementation-plans/_index.md` — existing plans index (if it exists)
### 3. Determine Technology Stack
From the project files, determine:
- **Framework:** React, Vue, Svelte, etc. (check package.json)
- **Language:** TypeScript or JavaScript
- **Build tool:** Vite, Next.js, Webpack, etc.
- **Styling:** CSS Modules, Tailwind, styled-components, etc.
- **State management:** Redux, Zustand, Pinia, etc.
- **Testing:** Vitest, Jest, Playwright, Cypress, etc.
### 4. Find Related Plans
From the index (if it exists), identify plans that share:
- The same feature area or component
- Overlapping affected files
- Dependency relationships (blocked-by / blocks)
Read those related plan files to understand prior decisions and patterns.
### 5. Explore the Codebase
Based on the issue's scope, explore relevant code:
- Use Glob to find files in affected directories
- Use Grep to find existing patterns, interfaces, types, and components
- Use Read to examine specific files mentioned in the issue or related plans
- Find similar implemented features to follow their patterns
### 6. Draft the Implementation Plan
The plan MUST include:
**Metadata:**
- Issue link, number, title
- Milestone and labels
- Status: `PLANNED`
- Technology (framework, language)
- Related plan references
- Blocked-by references
**Acceptance Criteria:**
- Copy directly from the issue body
**Architecture Analysis:**
- Which components/pages are affected
- Which API endpoints are involved
- Which state/stores are affected
- Dependencies on other features
- Existing patterns to follow (with file references)
**Implementation Steps (phase by phase):**
1. **Types & Configuration** — TypeScript types/interfaces, config constants, API types
2. **Core Logic** — Business logic, hooks, utilities, state management
3. **Components** — UI components, layouts, pages
4. **API Integration** — API calls, data fetching, error handling
5. **Tests** — Unit tests, component tests, E2E tests
**Files to Create/Modify:**
- Explicit file paths with a one-line purpose for each
**Risks and Edge Cases:**
- Potential issues and mitigation strategies
**Important:** Include type definitions, component signatures, and hook interfaces in the plan, but do NOT write actual implementation code.
### 7. Write the Plan File
Write the plan to `implementation-plans/issue-$ARGUMENTS.md`.
### 8. Update the Index
Create or update `implementation-plans/_index.md`:
- Add the new plan to the master table
- Add cross-references in the appropriate feature area section
### 9. Output
Display the completed plan for review.
## Critical Rules
- Do NOT write implementation code — only the plan
- DO include type definitions, component signatures, and hook interfaces
- DO reference existing patterns with file paths and line numbers
- DO identify all files that need to be created or modified
- Follow the 5-phase implementation order (Types > Core Logic > Components > API Integration > Tests)
- Read `CLAUDE.md` for project-specific architectural constraints

137
.claude/commands/refactor-review.md Normal file
View File

@@ -0,0 +1,137 @@
# Refactor Review
You are the **Refactoring Reviewer** agent. Your job is to review the entire project for code quality, modularity, and maintainability, then create actionable refactoring issues.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Trigger
This command is triggered:
- Periodically (every ~5 completed stories) by the auto-dev pipeline
- Manually by the user via `/project:refactor-review`
## Steps
### 1. Read Project Context
- Read `CLAUDE.md` for coding standards (if exists)
- Read `implementation-plans/_index.md` for completed work overview
- Read `package.json` for project dependencies
### 2. Survey the Codebase
Explore all source directories:
- Use Glob to find all source files (`src/**/*.ts`, `src/**/*.tsx`, `src/**/*.css`, `src/**/*.vue`, `src/**/*.svelte`, etc.)
- Use Grep to find patterns of concern (see checklist below)
- Read key files to understand current state
### 3. Review Checklist
Evaluate the project against these dimensions:
**Code Duplication:**
- Shared logic duplicated across components instead of extracted to hooks/utilities
- Similar UI patterns that should be abstracted into shared components
- Repeated API call patterns that should use a shared data fetching layer
**Modularity:**
- Components longer than ~100 lines that should be split
- Components with too many responsibilities
- Tight coupling between feature modules
- Missing abstractions
**Consistency:**
- Inconsistent error handling patterns
- Inconsistent state management approaches
- Inconsistent API call patterns
- Naming convention violations
- Inconsistent styling approaches
**Architecture Drift:**
- Components bypassing the established API layer
- State management inconsistencies
- Routing pattern violations
**Dependency Health:**
- Unused dependencies in package.json
- Outdated dependencies with known vulnerabilities
- Lock file hygiene
**Test Quality:**
- Tests that only test happy paths
- Missing component tests for interactive features
- Test code duplication
**Accessibility:**
- Missing ARIA attributes on interactive elements
- Missing keyboard navigation
- Missing alt text on images
### 4. Prioritize Findings
Categorize each finding:
| Priority | Description |
|---|---|
| **High** | Architecture drift, security concern, significant duplication, accessibility blockers |
| **Medium** | Modularity issues, inconsistencies, test quality gaps |
| **Low** | Style issues, minor duplication, documentation gaps |
### 5. Create Refactoring Issues
For each finding (or group of related findings), create a Gitea issue:
- **Title:** `Refactor: <concise description>`
- **Labels:** `type:refactor`, `priority:<high/medium/low>`, plus relevant `cat:*` labels
- **Milestone:** None
- **Body:** Include:
- What the problem is
- Where it occurs (file paths)
- Why it matters
- Suggested approach for fixing it
Group related small findings into a single issue rather than creating many tiny issues.
### 6. Close Resolved Tech Debt
Check existing open issues with `type:refactor` and `priority:low` labels. If any have been addressed by recent implementations, close them with a comment explaining they were resolved.
### 7. Output Summary
```
## Refactoring Review Summary
### Project Health: GOOD / NEEDS_ATTENTION / CONCERNING
### Statistics
- Directories reviewed: N
- Source files scanned: N
- Issues created: N (H high, M medium, L low)
- Tech debt issues closed: N
### Key Findings
1. <Most important finding>
2. <Second most important finding>
3. <Third most important finding>
### Issues Created
- #NN: <title> (priority)
### Tech Debt Closed
- #NN: <title> (resolved by recent changes)
### Recommendations
- <Top-level recommendation for next development cycle>
```
## Critical Rules
- Focus on structural issues, not cosmetic ones
- Group related findings — don't create issue spam
- Always check against `CLAUDE.md` for architecture drift
- Close tech debt issues that have been organically resolved
- Be constructive — every finding should include a suggested fix
- Don't recommend over-engineering — the right abstraction is the minimal one

107
.claude/commands/release.md Normal file
View File

@@ -0,0 +1,107 @@
# Release
You are the **Release Manager** agent. Your job is to create a release when a milestone is fully completed.
## Trigger Rules
This agent is invoked in two contexts:
1. **Manual request** — The user explicitly asks for a release. Merge the release PR yourself and proceed.
2. **Milestone completion** — All issues in a milestone are completed (triggered from auto-dev). Create the release PR but do NOT merge it. Inform the user the PR is ready for manual approval.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Input
`$ARGUMENTS` should be the milestone name or version (e.g., `mvp`, `0.1.0`). If empty, ask the user.
## Steps
### 1. Pre-flight Checks
1. Ensure the working tree is clean (`git status` shows no changes)
2. Fetch latest from origin: `git fetch origin`
3. Verify all issues in the milestone are closed:
- Use `mcp__gitea__list_issues` filtered by milestone
- If any issues are still open, list them and stop
4. Run quality gates on `main`:
```bash
git checkout main && git pull origin main
npm install
npm run build
npm run lint
npm run test
```
If any gate fails, stop and inform the user.
### 2. Create Release Branch
```bash
git checkout -b release/<milestone-slug> main
```
### 3. Update Version/Changelog
- Bump version in `package.json`
- Collect all merged PR descriptions for this milestone into a changelog entry
- Commit:
```
chore: prepare release for <milestone-name>
```
### 4. Create Release PR
Push the release branch and create a Gitea PR:
- **Title:** `Release: <milestone-name>`
- **Head:** `release/<milestone-slug>`
- **Base:** `main`
- **Body:** Summary of all issues completed in the milestone, with links
If **milestone-triggered:** STOP here. Inform the user the release PR is ready.
If **manually requested:** Proceed to merge.
### 5. Merge and Tag
1. Merge the PR via `mcp__gitea__pull_request_write` with `merge_style: "merge"`
2. Pull updated main:
```bash
git checkout main && git pull origin main
```
3. Create a tag:
```bash
git tag <milestone-slug>
git push origin <milestone-slug>
```
### 6. Create Gitea Release
Use `mcp__gitea__create_release`:
- **tag_name:** `<milestone-slug>`
- **target:** `main`
- **title:** `<milestone-name>`
- **body:** Release notes listing all completed issues
### 7. Close the Milestone
Use `mcp__gitea__milestone_write` to set the milestone state to `closed`.
### 8. Output Summary
Display:
- Milestone name and version
- PR number and merge status
- Tag created
- Issues included (count and list)
- Link to the Gitea release page
- Next milestone to work on
## Critical Rules
- Never force-push to main
- Always go through a PR — never merge directly
- Always run quality gates before releasing
- The tag must be on the main branch
- Close the milestone after release

60
.claude/commands/select-story.md Normal file
View File

@@ -0,0 +1,60 @@
# Select Story
You are the **Story Selector** agent. Your job is to find the highest-priority open issue from the llm-multiverse-ui Gitea backlog and present it to the user for confirmation.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Steps
### 1. Fetch Open Issues
Use `mcp__gitea__list_issues` to fetch all open issues. Paginate with `perPage: 30` until no more results. Collect all issues.
### 2. Filter Out Ineligible Issues
Remove any issue that has:
- Label `workflow:manual`
- Label `workflow:blocked`
### 3. Check Existing Plans
Read `implementation-plans/_index.md` if it exists. Skip any issue whose plan status is `COMPLETED` or `IMPLEMENTING`.
### 4. Check Dependency Readiness
For each candidate issue, read its body and look for a "Blocked by" section. If any blocking issue is still open (not closed), the candidate is **not ready** — skip it.
### 5. Sort by Priority
Sort remaining issues using this priority order:
**Milestone priority (earliest milestone first):**
- Sort by milestone due date (earliest first)
- Issues with no milestone come last
**Within the same milestone, sort by priority label:**
1. `priority:critical`
2. `priority:high`
3. `priority:medium`
4. `priority:low`
5. No priority label
### 6. Present the Top Candidate
Display the highest-priority issue with:
- Issue number and title
- Milestone name
- All labels
- Issue body summary (first ~200 chars)
- Blocked-by status (all dependencies satisfied)
- Link to the issue
### 7. Ask for Confirmation
Ask the user: "Shall I proceed to plan this story, or would you like to pick a different one?"
- If confirmed: tell the user to run `/project:plan-story <issue#>` or proceed inline if called from auto-dev.
- If the user picks a different issue number: present that issue's details and confirm again.

146
.claude/commands/verify-story.md Normal file
View File

@@ -0,0 +1,146 @@
# Verify Story
You are the **Story Verifier** agent. Your job is to verify the implementation of issue #$ARGUMENTS against its plan and quality standards.
## Gitea Connection
- **Owner:** `llm-multiverse`
- **Repo:** `llm-multiverse-ui`
## Input
The issue number is provided as `$ARGUMENTS`. If empty, ask the user for an issue number.
## Steps
### 1. Read Plan and Issue
- Read `implementation-plans/issue-$ARGUMENTS.md` for the plan
- Use `mcp__gitea__issue_read` to fetch the original issue (acceptance criteria)
### 2. Determine Technology Stack
Check `package.json` and the plan to know which quality gates to run.
### 3. Run Quality Gates
Run each gate and record pass/fail:
Gate 1 — Build:
```bash
npm run build
```
Gate 2 — Lint:
```bash
npm run lint
```
Gate 3 — Type Check:
```bash
npm run typecheck # or npx tsc --noEmit
```
Gate 4 — Tests:
```bash
npm run test
```
Gate 5 — Format (if available):
```bash
npm run format:check # or npx prettier --check .
```
Adapt commands based on what's available in `package.json`.
### 4. Architecture Review
Review all files changed in this branch (use `git diff main --name-only` to get the list). For each changed file, verify:
**General:**
- [ ] No hardcoded credentials, API keys, or secrets
- [ ] No `TODO` or `FIXME` left unresolved (unless documented in plan)
- [ ] Consistent error handling patterns
- [ ] No `console.log` left in production code
**TypeScript:**
- [ ] No `any` types without justification
- [ ] Proper type narrowing and null checks
- [ ] Interfaces/types exported where needed
**Components:**
- [ ] Proper prop typing
- [ ] Loading, error, and empty states handled
- [ ] Accessible markup (semantic HTML, ARIA)
- [ ] Responsive design considered
**Security:**
- [ ] No XSS vulnerabilities
- [ ] User input properly sanitized
- [ ] API tokens/secrets not in client-side code
### 5. Acceptance Criteria Verification
For each acceptance criterion from the issue:
- Check the code to verify the criterion is met
- Note which file(s) satisfy each criterion
- Mark each criterion as PASS or FAIL with explanation
### 6. Determine Result
**PASS** if ALL of the following are true:
- All quality gates pass
- No architecture violations found (major/critical)
- All acceptance criteria are met
**FAIL** if ANY gate fails or any acceptance criterion is not met.
### 7a. On PASS
1. Update plan status to `COMPLETED` in `implementation-plans/issue-$ARGUMENTS.md`
2. Update `implementation-plans/_index.md` status to `COMPLETED`
3. Push the feature branch:
```bash
git push -u origin <branch-name>
```
4. Create a Gitea pull request using `mcp__gitea__pull_request_write` with:
- Title: the issue title
- Body: implementation summary, link to plan file, files changed, test results
- Base: `main`
- Head: the feature branch name
5. Add a comment to the Gitea issue summarizing what was implemented
6. Close the Gitea issue
### 7b. On FAIL
1. Update plan status to `RETRY` in `implementation-plans/issue-$ARGUMENTS.md`
2. Append a **Retry Instructions** section to the plan with:
- Which quality gates failed and why
- Which acceptance criteria were not met
- Specific instructions for fixing each failure
3. Update `implementation-plans/_index.md` status to `RETRY`
4. Output the specific failures clearly
### 8. Output Verification Report
Display a structured report:
```
## Verification Report — Issue #$ARGUMENTS
### Quality Gates
- Build: PASS/FAIL
- Lint: PASS/FAIL
- Type Check: PASS/FAIL
- Tests: PASS/FAIL (X passed, Y failed)
- Format: PASS/FAIL
### Architecture Review
- Violations found: (list or "None")
### Acceptance Criteria
- [x] Criterion 1 — PASS (Component.tsx:42)
- [ ] Criterion 2 — FAIL (reason)
### Result: PASS / FAIL
```