ccsetup 1.2.0 → 1.2.1

package/template/.codex/skills/prd/SKILL.md

@@ -0,0 +1,343 @@
+---
+name: prd
+description: "Generate a Product Requirements Document (PRD) for a new feature. Use when planning a feature, starting a new project, or when asked to create a PRD. Triggers on: create a prd, write prd for, plan this feature, requirements for, spec out."
+---
+
+# PRD Generator
+
+Create detailed Product Requirements Documents that are clear, actionable, and grounded in the actual codebase.
+
+---
+
+## The Job
+
+1. **Scan the codebase** to understand tech stack, architecture, and existing patterns
+2. Receive a feature description from the user
+3. Ask 3-5 **codebase-informed** clarifying questions (with lettered options)
+4. Generate a structured PRD that references real files, components, and patterns
+5. Save to `tasks/prd-[feature-name].md`
+
+**Important:** Do NOT start implementing. Just create the PRD.
+
+---
+
+## Step 1: Codebase Reconnaissance
+
+Before asking the user anything, silently scan the project using Codex tools:
+
+### Detect Tech Stack
+Use Glob and Read to find and inspect:
+- `package.json`, `tsconfig.json`, `next.config.*` (Node/TypeScript/Next.js)
+- `requirements.txt`, `pyproject.toml`, `setup.py` (Python)
+- `go.mod` (Go)
+- `Cargo.toml` (Rust)
+- `Gemfile` (Ruby)
+- `composer.json` (PHP)
+
+Record: language, framework, package manager, key dependencies.
+
+### Detect Quality Checks
+From the config files found above, identify:
+- **Typecheck**: `tsconfig.json` exists → "Typecheck passes"
+- **Linter**: `eslint`, `biome`, `ruff`, `golangci-lint` in deps or config → "Lint passes"
+- **Test framework**: `jest`, `vitest`, `pytest`, `go test` → "Tests pass"
+- **Build**: check `scripts` in package.json for `build`, `check`, etc.
+
+These become the **default quality criteria** appended to every user story.
+
+### Scan Architecture
+Use Glob to map the project structure:
+- `src/**/*.{ts,tsx,js,jsx,py,go,rs}` — source file layout
+- `**/schema.prisma`, `**/migrations/**`, `**/models/**` — database layer
+- `**/api/**`, `**/routes/**`, `**/app/**/route.*` — API endpoints
+- `**/components/**` — UI components
+- `**/hooks/**`, `**/utils/**`, `**/lib/**` — shared utilities
+
+### Read Project Context
+- Read `AGENTS.md` (root and any nested) for project instructions and conventions
+- Read existing PRDs in `tasks/prd-*.md` for format consistency
+- Read `docs/ROADMAP.md` if it exists for current priorities
+
+### Build Context Summary
+Compile findings into an internal context block (do not show to user):
+```
+Tech: [framework] + [language] + [key deps]
+Quality: [typecheck] [lint] [test] [build commands]
+DB: [ORM/schema location]
+API: [routing pattern, e.g., "Next.js App Router at app/api/"]
+UI: [component library, e.g., "shadcn/ui in src/components/ui/"]
+Existing patterns: [key files and conventions discovered]
+```
+
+---
+
+## Step 2: Clarifying Questions
+
+Ask only critical questions where the initial prompt is ambiguous. **Tailor questions to what you found in the codebase** — don't ask about tech stack if you already know it.
+
+Focus on:
+
+- **Problem/Goal:** What problem does this solve?
+- **Core Functionality:** What are the key actions?
+- **Scope/Boundaries:** What should it NOT do?
+- **Success Criteria:** How do we know it's done?
+
+### Format Questions Like This:
+
+```
+1. What is the primary goal of this feature?
+   A. Improve user onboarding experience
+   B. Increase user retention
+   C. Reduce support burden
+   D. Other: [please specify]
+
+2. Who is the target user?
+   A. New users only
+   B. Existing users only
+   C. All users
+   D. Admin users only
+
+3. What is the scope?
+   A. Minimal viable version
+   B. Full-featured implementation
+   C. Just the backend/API
+   D. Just the UI
+```
+
+This lets users respond with "1A, 2C, 3B" for quick iteration.
+
+### Codebase-Informed Questions
+
+If your scan revealed relevant context, weave it into the questions:
+
+- Found a database schema → "I see you have a `users` table with [fields]. Should this feature extend that table or create a new one?"
+- Found existing components → "You already have a `DataTable` component in `src/components/ui/`. Should this feature reuse it?"
+- Found API patterns → "Your API routes follow [pattern]. Should this feature add new routes under the same structure?"
+
+Skip questions the codebase already answers. If the tech stack is clear, don't ask "What framework are you using?"
+
+---
+
+## Step 3: PRD Structure
+
+Generate the PRD with these sections:
+
+### 1. Introduction/Overview
+Brief description of the feature and the problem it solves.
+
+### 2. Tech Context
+Auto-generated from your codebase scan. Include:
+- **Stack:** Language, framework, key dependencies
+- **Quality gates:** Which checks apply (typecheck, lint, test, build)
+- **Relevant existing code:** File paths and patterns the feature should build on
+
+This section helps implementers (human or AI) understand the codebase without re-scanning.
+
+### 3. Goals
+Specific, measurable objectives (bullet list).
+
+### 4. User Stories
+Each story needs:
+- **Title:** Short descriptive name
+- **Description:** "As a [user], I want [feature] so that [benefit]"
+- **Acceptance Criteria:** Verifiable checklist of what "done" means
+
+Each story should be small enough to implement in one focused session.
+
+**Format:**
+```markdown
+### US-001: [Title]
+**Description:** As a [user], I want [feature] so that [benefit].
+
+**Acceptance Criteria:**
+- [ ] Specific verifiable criterion
+- [ ] Another criterion
+- [ ] {auto-detected quality checks from Step 1}
+- [ ] **[UI stories only]** Verify in browser using dev-browser skill
+```
+
+**Important:**
+- Acceptance criteria must be verifiable, not vague. "Works correctly" is bad. "Button shows confirmation dialog before deleting" is good.
+- **For any story with UI changes:** Always include "Verify in browser using dev-browser skill" as acceptance criteria.
+- **Quality criteria are auto-appended** based on Step 1 detection. Do not hardcode "Typecheck passes" — use whatever the project actually has.
+- **Reference real file paths** when a story modifies or extends existing code (e.g., "Add column to schema in `prisma/schema.prisma`").
+
+### 5. Functional Requirements
+Numbered list of specific functionalities:
+- "FR-1: The system must allow users to..."
+- "FR-2: When a user clicks X, the system must..."
+
+Be explicit and unambiguous.
+
+### 6. Non-Goals (Out of Scope)
+What this feature will NOT include. Critical for managing scope.
+
+### 7. Design Considerations (Optional)
+- UI/UX requirements
+- Link to mockups if available
+- **Existing components to reuse** (reference actual paths found in scan, e.g., "`src/components/ui/DataTable.tsx`")
+
+### 8. Technical Considerations
+- Known constraints or dependencies
+- Integration points with existing systems (reference actual files/modules)
+- Performance requirements
+- **Dependency order:** Which stories must be completed before others (schema → backend → UI)
+
+### 9. Success Metrics
+How will success be measured?
+- "Reduce time to complete X by 50%"
+- "Increase conversion rate by 10%"
+
+### 10. Open Questions
+Remaining questions or areas needing clarification.
+
+---
+
+## Writing for AI Agents and Junior Developers
+
+The PRD reader may be a junior developer or an autonomous AI agent (like Ralph). Therefore:
+
+- Be explicit and unambiguous
+- Reference actual file paths, not abstract descriptions
+- Provide enough detail to understand purpose and core logic
+- Number requirements for easy reference
+- Use concrete examples where helpful
+- Include the quality gates the project actually uses, not generic ones
+
+---
+
+## Output
+
+- **Format:** Markdown (`.md`)
+- **Location:** `tasks/`
+- **Filename:** `prd-[feature-name].md` (kebab-case)
+
+---
+
+## Example PRD
+
+```markdown
+# PRD: Task Priority System
+
+## Introduction
+
+Add priority levels to tasks so users can focus on what matters most. Tasks can be marked as high, medium, or low priority, with visual indicators and filtering to help users manage their workload effectively.
+
+## Tech Context
+
+- **Stack:** Next.js 14 (App Router) + TypeScript + Tailwind CSS
+- **DB:** Prisma with PostgreSQL (`prisma/schema.prisma`)
+- **UI:** shadcn/ui components in `src/components/ui/`
+- **Quality gates:** Typecheck (`tsc --noEmit`), Lint (`eslint`), Tests (`vitest`)
+- **Relevant code:**
+  - Task model: `prisma/schema.prisma` (Task table)
+  - Task list component: `src/components/TaskList.tsx`
+  - Task card component: `src/components/TaskCard.tsx`
+  - Existing badge component: `src/components/ui/Badge.tsx`
+  - API routes: `src/app/api/tasks/`
+
+## Goals
+
+- Allow assigning priority (high/medium/low) to any task
+- Provide clear visual differentiation between priority levels
+- Enable filtering and sorting by priority
+- Default new tasks to medium priority
+
+## User Stories
+
+### US-001: Add priority field to database
+**Description:** As a developer, I need to store task priority so it persists across sessions.
+
+**Acceptance Criteria:**
+- [ ] Add `priority` enum ('high' | 'medium' | 'low', default 'medium') to Task model in `prisma/schema.prisma`
+- [ ] Generate and run migration successfully
+- [ ] Typecheck passes
+- [ ] Lint passes
+
+### US-002: Display priority indicator on task cards
+**Description:** As a user, I want to see task priority at a glance so I know what needs attention first.
+
+**Acceptance Criteria:**
+- [ ] Extend `src/components/TaskCard.tsx` to show priority using existing `Badge` component from `src/components/ui/Badge.tsx`
+- [ ] Badge colors: red=high, yellow=medium, gray=low
+- [ ] Priority visible without hovering or clicking
+- [ ] Typecheck passes
+- [ ] Lint passes
+- [ ] Verify in browser using dev-browser skill
+
+### US-003: Add priority selector to task edit
+**Description:** As a user, I want to change a task's priority when editing it.
+
+**Acceptance Criteria:**
+- [ ] Priority dropdown in task edit modal using shadcn `Select` component
+- [ ] Shows current priority as selected
+- [ ] Saves via existing PATCH `/api/tasks/[id]` route
+- [ ] Typecheck passes
+- [ ] Lint passes
+- [ ] Verify in browser using dev-browser skill
+
+### US-004: Filter tasks by priority
+**Description:** As a user, I want to filter the task list to see only high-priority items when I'm focused.
+
+**Acceptance Criteria:**
+- [ ] Add filter dropdown to `src/components/TaskList.tsx` with options: All | High | Medium | Low
+- [ ] Filter persists in URL search params
+- [ ] Empty state message when no tasks match filter
+- [ ] Typecheck passes
+- [ ] Lint passes
+- [ ] Tests pass
+- [ ] Verify in browser using dev-browser skill
+
+## Functional Requirements
+
+- FR-1: Add `priority` field to Task model in `prisma/schema.prisma` ('high' | 'medium' | 'low', default 'medium')
+- FR-2: Display colored priority badge on each task card via `Badge` component
+- FR-3: Include priority selector in task edit modal using shadcn `Select`
+- FR-4: Add priority filter dropdown to `TaskList` header
+- FR-5: Sort by priority within each status column (high → medium → low)
+
+## Non-Goals
+
+- No priority-based notifications or reminders
+- No automatic priority assignment based on due date
+- No priority inheritance for subtasks
+
+## Design Considerations
+
+- Reuse existing `src/components/ui/Badge.tsx` with color variants
+- Use shadcn `Select` for the filter and edit dropdowns (already in project deps)
+
+## Technical Considerations
+
+- Filter state managed via URL search params (Next.js `useSearchParams`)
+- Priority stored in database, not computed
+- **Dependency order:** US-001 (schema) → US-002 (display) → US-003 (edit) → US-004 (filter)
+
+## Success Metrics
+
+- Users can change priority in under 2 clicks
+- High-priority tasks immediately visible at top of lists
+- No regression in task list performance
+
+## Open Questions
+
+- Should priority affect task ordering within a column?
+- Should we add keyboard shortcuts for priority changes?
+```
+
+---
+
+## Checklist
+
+Before saving the PRD:
+
+- [ ] Ran codebase reconnaissance (Step 1)
+- [ ] Tech Context section reflects actual project stack and quality gates
+- [ ] Asked codebase-informed clarifying questions with lettered options
+- [ ] Incorporated user's answers
+- [ ] User stories reference real file paths where applicable
+- [ ] User stories are small and specific (one focused session each)
+- [ ] Quality criteria match what the project actually uses (not hardcoded)
+- [ ] Functional requirements are numbered and unambiguous
+- [ ] Non-goals section defines clear boundaries
+- [ ] Saved to `tasks/prd-[feature-name].md`

package/template/.codex/skills/ralph/SKILL.md

@@ -0,0 +1,339 @@
+---
+name: ralph
+description: "Convert PRDs to prd.json format for the Ralph autonomous agent system. Use when you have an existing PRD and need to convert it to Ralph's JSON format. Triggers on: convert this prd, turn this into ralph format, create prd.json from this, ralph json."
+---
+
+# Ralph PRD Converter
+
+Converts existing PRDs to the prd.json format that Ralph uses for autonomous execution. Scans the codebase to populate quality checks, file hints, and story notes automatically.
+
+---
+
+## The Job
+
+1. **Scan the codebase** to detect quality commands and relevant file paths
+2. Read the PRD (markdown file or text) — check for a Tech Context section first
+3. Convert to `scripts/ralph/prd.json` with codebase-informed stories
+4. Initialize `scripts/ralph/progress.txt` if it doesn't exist
+
+**Important:** Do NOT start implementing. Just create the prd.json.
+
+---
+
+## Step 1: Codebase Reconnaissance
+
+Before converting, silently scan the project using Codex tools.
+
+### If PRD has a Tech Context section
+The improved `/prd` skill generates a Tech Context section with stack, quality gates, and relevant file paths. If present, use it directly — no need to re-scan.
+
+### If PRD has no Tech Context section
+Scan manually:
+
+**Detect quality commands** — Read `package.json` scripts, config files, Makefiles:
+- Look for: `typecheck`, `tsc`, `check-types` → record the exact script (e.g., `npm run typecheck`)
+- Look for: `lint`, `eslint`, `biome check` → record exact script (e.g., `npm run lint`)
+- Look for: `test`, `vitest`, `jest`, `pytest` → record exact script (e.g., `npm test`)
+- Look for: `build` → record exact script (e.g., `npm run build`)
+
+**Scan relevant files** — Use Glob to find files related to each user story:
+- Database: `**/schema.prisma`, `**/models/**`, `**/migrations/**`
+- API: `**/api/**`, `**/routes/**`, `**/app/**/route.*`
+- Components: `**/components/**`
+- Utilities: `**/hooks/**`, `**/utils/**`, `**/lib/**`
+
+These become `notes` on each story — giving Ralph file-level hints for where to work.
+
+---
+
+## Step 2: Output Format
+
+```json
+{
+  "project": "[Project Name]",
+  "branchName": "ralph/[feature-name-kebab-case]",
+  "description": "[Feature description from PRD title/intro]",
+  "qualityChecks": {
+    "typecheck": "npm run typecheck",
+    "lint": "npm run lint",
+    "test": "npm test",
+    "build": "npm run build"
+  },
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Criterion 1",
+        "Criterion 2",
+        "Typecheck passes",
+        "Lint passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "Relevant files: prisma/schema.prisma, src/app/api/tasks/route.ts"
+    }
+  ]
+}
+```
+
+### The `qualityChecks` field
+
+This is **new and critical**. It tells Ralph the exact commands to run, so each iteration doesn't have to guess. Only include checks that actually exist in the project:
+
+```json
+"qualityChecks": {
+  "typecheck": "npm run typecheck",
+  "lint": "npm run lint"
+}
+```
+
+If a project has no typecheck, don't include it. If it uses `make check`, use that. Be exact.
+
+### The `notes` field
+
+Pre-populate with **file hints** from your codebase scan — relevant files the story will likely touch or extend:
+
+```
+"notes": "Relevant files: prisma/schema.prisma (Task model), src/components/TaskCard.tsx (extend with badge)"
+```
+
+This gives each Ralph iteration a head start instead of scanning the codebase from scratch.
+
+---
+
+## Story Size: The Number One Rule
+
+**Each story must be completable in ONE Ralph iteration (one context window).**
+
+Ralph spawns a fresh instance per iteration with no memory of previous work. If a story is too big, the LLM runs out of context before finishing and produces broken code.
+
+### Right-sized stories:
+- Add a database column and migration
+- Add a UI component to an existing page
+- Update a server action with new logic
+- Add a filter dropdown to a list
+
+### Too big (split these):
+- "Build the entire dashboard" — Split into: schema, queries, UI components, filters
+- "Add authentication" — Split into: schema, middleware, login UI, session handling
+- "Refactor the API" — Split into one story per endpoint or pattern
+
+**Rule of thumb:** If you cannot describe the change in 2-3 sentences, it is too big.
+
+---
+
+## Story Ordering: Dependencies First
+
+Stories execute in priority order. Earlier stories must not depend on later ones.
+
+**Correct order:**
+1. Schema/database changes (migrations)
+2. Server actions / backend logic
+3. UI components that use the backend
+4. Dashboard/summary views that aggregate data
+
+**Wrong order:**
+1. UI component (depends on schema that does not exist yet)
+2. Schema change
+
+---
+
+## Acceptance Criteria: Must Be Verifiable
+
+Each criterion must be something Ralph can CHECK, not something vague.
+
+### Good criteria (verifiable):
+- "Add `status` column to tasks table with default 'pending'"
+- "Filter dropdown has options: All, Active, Completed"
+- "Clicking delete shows confirmation dialog"
+
+### Bad criteria (vague):
+- "Works correctly"
+- "User can do X easily"
+- "Good UX"
+- "Handles edge cases"
+
+### Quality criteria — use what the project actually has
+
+Append the quality checks detected in Step 1. Examples:
+
+- Project has typecheck + lint → append `"Typecheck passes"`, `"Lint passes"`
+- Project has only tests → append `"Tests pass"`
+- Project has a build step → append `"Build passes"`
+
+Do **not** hardcode "Typecheck passes" if the project has no typecheck.
+
+### For stories that change UI, also include:
+```
+"Verify in browser using dev-browser skill"
+```
+
+---
+
+## Conversion Rules
+
+1. **Each user story becomes one JSON entry**
+2. **IDs**: Sequential (US-001, US-002, etc.)
+3. **Priority**: Based on dependency order, then document order
+4. **All stories**: `passes: false`
+5. **notes**: Pre-populate with relevant file paths from codebase scan
+6. **branchName**: Derive from feature name, kebab-case, prefixed with `ralph/`
+7. **qualityChecks**: Populated from detected project commands (Step 1)
+8. **Quality criteria on stories**: Match what `qualityChecks` contains
+
+---
+
+## Splitting Large PRDs
+
+If a PRD has big features, split them:
+
+**Original:**
+> "Add user notification system"
+
+**Split into:**
+1. US-001: Add notifications table to database
+2. US-002: Create notification service for sending notifications
+3. US-003: Add notification bell icon to header
+4. US-004: Create notification dropdown panel
+5. US-005: Add mark-as-read functionality
+6. US-006: Add notification preferences page
+
+Each is one focused change that can be completed and verified independently.
+
+---
+
+## Example
+
+**Input PRD with Tech Context:**
+```markdown
+# PRD: Task Status Feature
+
+## Tech Context
+- **Stack:** Next.js 14 (App Router) + TypeScript + Tailwind CSS
+- **DB:** Prisma with PostgreSQL (`prisma/schema.prisma`)
+- **UI:** shadcn/ui in `src/components/ui/`
+- **Quality gates:** Typecheck (`tsc --noEmit`), Lint (`eslint`), Tests (`vitest`)
+- **Relevant code:**
+  - Task model: `prisma/schema.prisma`
+  - Task list: `src/components/TaskList.tsx`
+  - Task card: `src/components/TaskCard.tsx`
+  - Badge: `src/components/ui/Badge.tsx`
+  - API: `src/app/api/tasks/`
+
+## User Stories
+### US-001: Add status field to database ...
+### US-002: Display status badge on task cards ...
+### US-003: Add status toggle ...
+### US-004: Filter tasks by status ...
+```
+
+**Output prd.json:**
+```json
+{
+  "project": "TaskApp",
+  "branchName": "ralph/task-status",
+  "description": "Task Status Feature - Track task progress with status indicators",
+  "qualityChecks": {
+    "typecheck": "npx tsc --noEmit",
+    "lint": "npm run lint",
+    "test": "npx vitest run"
+  },
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "Add status field to tasks table",
+      "description": "As a developer, I need to store task status in the database.",
+      "acceptanceCriteria": [
+        "Add status column: 'pending' | 'in_progress' | 'done' (default 'pending')",
+        "Generate and run migration successfully",
+        "Typecheck passes",
+        "Lint passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": "Relevant files: prisma/schema.prisma (Task model)"
+    },
+    {
+      "id": "US-002",
+      "title": "Display status badge on task cards",
+      "description": "As a user, I want to see task status at a glance.",
+      "acceptanceCriteria": [
+        "Each task card shows colored status badge",
+        "Badge colors: gray=pending, blue=in_progress, green=done",
+        "Typecheck passes",
+        "Lint passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 2,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskCard.tsx (extend), src/components/ui/Badge.tsx (reuse with color variants)"
+    },
+    {
+      "id": "US-003",
+      "title": "Add status toggle to task list rows",
+      "description": "As a user, I want to change task status directly from the list.",
+      "acceptanceCriteria": [
+        "Each row has status dropdown or toggle",
+        "Changing status saves immediately via PATCH /api/tasks/[id]",
+        "UI updates without page refresh",
+        "Typecheck passes",
+        "Lint passes",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 3,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskList.tsx, src/app/api/tasks/[id]/route.ts"
+    },
+    {
+      "id": "US-004",
+      "title": "Filter tasks by status",
+      "description": "As a user, I want to filter the list to see only certain statuses.",
+      "acceptanceCriteria": [
+        "Filter dropdown: All | Pending | In Progress | Done",
+        "Filter persists in URL params",
+        "Typecheck passes",
+        "Lint passes",
+        "Tests pass",
+        "Verify in browser using dev-browser skill"
+      ],
+      "priority": 4,
+      "passes": false,
+      "notes": "Relevant files: src/components/TaskList.tsx (add filter dropdown)"
+    }
+  ]
+}
+```
+
+---
+
+## Archiving Previous Runs
+
+**Before writing a new prd.json, check if there is an existing one from a different feature:**
+
+1. Read the current `prd.json` if it exists
+2. Check if `branchName` differs from the new feature's branch name
+3. If different AND `progress.txt` has content beyond the header:
+   - Create archive folder: `archive/YYYY-MM-DD-feature-name/`
+   - Copy current `prd.json` and `progress.txt` to archive
+   - Reset `progress.txt` with fresh header
+
+**The ralph.sh script handles this automatically** when you run it, but if you are manually updating prd.json between runs, archive first.
+
+---
+
+## Checklist Before Saving
+
+Before writing prd.json, verify:
+
+- [ ] Ran codebase reconnaissance or read PRD's Tech Context (Step 1)
+- [ ] `qualityChecks` populated with exact commands from the project
+- [ ] **Previous run archived** (if prd.json exists with different branchName, archive it first)
+- [ ] Each story is completable in one iteration (small enough)
+- [ ] Stories are ordered by dependency (schema → backend → UI)
+- [ ] Story quality criteria match what `qualityChecks` contains (not hardcoded)
+- [ ] UI stories have "Verify in browser using dev-browser skill" as criterion
+- [ ] Acceptance criteria are verifiable (not vague)
+- [ ] Story `notes` pre-populated with relevant file paths
+- [ ] No story depends on a later story