ccsetup 1.1.1 → 1.2.1

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

package/template/AGENTS.md

@@ -0,0 +1,43 @@
+# Codex Project Instructions
+
+## Project Overview
+
+[Brief description of your project goes here]
+
+## Primary Working Files
+
+- `AGENTS.md` — project-specific guidance for Codex
+- `.codex/skills/` — project-local Codex skills for this project (`prd`, `ralph`, `codex-review`)
+- `docs/codex-setup.md` — Codex setup notes for this repo
+- `docs/ROADMAP.md` — project goals and status
+- `tickets/` — task tracking
+- `plans/` — implementation and architecture plans
+
+## Working Expectations
+
+- Read this file before making changes.
+- Check `docs/ROADMAP.md` and relevant tickets before starting non-trivial work.
+- Prefer small, reviewable changes.
+- Run the project quality checks before finishing.
+
+## Repo Workflow
+
+- Use plans in `plans/` for larger features.
+- Track implementation work in `tickets/`.
+- Use `scripts/codex-review/codex-review.sh` when you want a second-opinion review from Codex CLI.
+- Use `scripts/ralph/ralph.sh --tool codex` for Ralph runs through Codex CLI.
+
+## Codex Skills
+
+This project ships project-local Codex skills in `.codex/skills/`, mirroring the Claude skill set:
+
+- `prd`
+- `ralph`
+- `codex-review`
+
+Keep these skills in the repository alongside `AGENTS.md` and the project docs.
+
+## Project Conventions
+
+- Update this file when you discover project-wide rules that future Codex sessions should know.
+- Keep project-specific conventions here, and put reusable workflow guidance into project-local skills.

package/template/CLAUDE.md

@@ -15,9 +15,14 @@
 ```
 .
 ├── CLAUDE.md          # This file - project instructions for Claude
-├── .claude/           # Claude Code configuration (auto-generated)
-│   └── agents/        # Project-specific agent overrides
-├── agents/            # Custom agents for specialized tasks
+├── .claude/
+│   ├── agents/        # 8 core agents (backend, blockchain, checker, coder, frontend, planner, researcher, shadcn)
+│   ├── skills/        # /prd, /ralph, and /codex-review slash commands
+│   └── hooks/         # Workflow selector and codex-review hooks
+├── agents/            # Documentation only — see .claude/agents/ for active agents
+├── scripts/
+│   ├── ralph/         # Autonomous agent loop (ralph.sh + Claude/Codex instructions)
+│   └── codex-review/  # Codex CLI review script (plans, implementations, code changes)
 ├── docs/              # Project documentation
 ├── plans/             # Project plans and architectural documents
 └── tickets/           # Task tickets and issues
@@ -58,24 +63,60 @@
 
 ## Agents
 
-See @agents/README.md for available agents and their purposes
+8 core agents are pre-installed in `.claude/agents/`. See @agents/README.md for the full list and instructions for adding custom agents.
+
+## Skills (Slash Commands)
+
+- **/prd** — Scans the codebase, then generates a structured PRD with real file paths and auto-detected quality criteria. Saves to `tasks/prd-[feature-name].md`.
+- **/ralph** — Converts a PRD into `scripts/ralph/prd.json` for autonomous execution with quality checks and file hints per story.
+- **/codex-review** — Reviews plans, validates implementations against plans, or reviews code changes. Auto-detects what to review based on context. Iterates up to 3 times.
+- **/secops** — **NEVER install packages without running this first.** Scans dependencies for vulnerabilities using OSV Scanner. Use before any `pip`, `npm`, `cargo`, `gem`, or other package manager install.
+
+## Ralph — Autonomous Agent Loop
+
+Ralph implements user stories from a PRD one at a time in a loop, with subagent verification after each story.
+
+```bash
+./scripts/ralph/ralph.sh                          # Default: 10 iterations with Claude Code
+./scripts/ralph/ralph.sh --tool claude            # Use Claude Code explicitly
+./scripts/ralph/ralph.sh --tool codex             # Use Codex CLI
+./scripts/ralph/ralph.sh --tool claude --model opus 20  # Specify model + iterations
+```
+
+Typical workflow: `/prd` → `/ralph` → `./scripts/ralph/ralph.sh`
+
+Prerequisites: `jq` plus the CLI for whichever runner you use (`claude` by default, or `codex` for `--tool codex`).
 
 ## Agent Orchestration
 
-After adding the agents you want to in `./claude/agents` folder, setup the workflow for Claude code to follow
+See @docs/agent-orchestration.md for detailed workflow patterns on how to chain agents effectively.
+
+## Workflow Selector Hook (Optional)
+
+An optional hook that suggests agent workflows based on your prompt. Claude will ask before applying.
+
+To activate after installation:
+```bash
+export CCSETUP_WORKFLOW=1
+```
+
+When unset, the hook is inactive and Claude uses its default behavior. Install the hook with `npx ccsetup --install-hooks`.
+
+## Codex Review Hook (Optional)
+
+An optional hook that suggests running `/codex-review` when a plan file is modified or code changes are detected. Triggers on the `Stop` event.
+
+To activate:
+```bash
+export CCSETUP_CODEX_REVIEW=1
+```
+
+When unset, the hook is inactive and produces no output.
 
 ## Tickets
 
 See @tickets/README.md for ticket format and management approach
 
-### Ticket Management
-- **Ticket List**: Maintain @tickets/ticket-list.md as a centralized index of all tickets
-- **Update ticket-list.md** whenever you:
-  - Create a new ticket (add to appropriate priority section)
-  - Change ticket status (update emoji and move if completed)
-  - Complete a ticket (move to completed section with date)
-- **Status Emojis**: 🔴 Todo | 🟡 In Progress | 🟢 Done | 🔵 Blocked | ⚫ Cancelled
-
 ## Plans
 
 See @plans/README.md for planning documents and architectural decisions
@@ -88,15 +129,94 @@ See @plans/README.md for planning documents and architectural decisions
 
 ## Important Instructions
 
-Before starting any task:
-
-1. **Confirm understanding**: Always confirm you understand the request and outline your plan before proceeding
-2. **Ask clarifying questions**: Never make assumptions - ask questions when requirements are unclear
-3. **Create planning documents**: Before implementing any code or features, create a markdown file documenting the approach
-4. **Use plans directory**: When discussing ideas or next steps, create timestamped files in the plans directory (e.g., `plans/next-steps-YYYY-MM-DD-HH-MM-SS.md`) to maintain a record of decisions
-5. **No code comments**: Never add comments to any code you write - code should be self-documenting
-6. **Maintain ticket list**: Always update @tickets/ticket-list.md when creating, updating, or completing tickets to maintain a clear project overview
+- Ask clarifying questions when requirements are unclear
+- Self-documenting code — no code comments
+- For complex features, consider creating a plan document in `/plans` before implementing
 
 ## Additional Notes
 
 [Any other important information for Claude to know about this project]
+
+---
+
+# 🔒 CRITICAL SECURITY - OSV-Scanner Requirement
+
+> **MANDATORY SECOPS POLICY**: All dependency installations MUST be scanned with `osv-scanner` BEFORE installation. **NEVER install packages without scanning first. No exceptions.**
+
+### Security Workflow - ALWAYS Follow This Order
+
+**BEFORE installing ANY dependencies:**
+
+1. **Query the OSV API to check the package before installing:**
+
+   ```bash
+   curl -s -X POST "https://api.osv.dev/v1/query" \
+     -H "Content-Type: application/json" \
+     -d '{"package": {"name": "PACKAGE_NAME", "ecosystem": "ECOSYSTEM"}, "version": "VERSION"}'
+   ```
+
+   | Package Manager | Ecosystem |
+   |---|---|
+   | pip | `PyPI` |
+   | npm/yarn/pnpm | `npm` |
+   | cargo | `crates.io` |
+   | go get | `Go` |
+   | gem | `RubyGems` |
+   | composer | `Packagist` |
+   | nuget | `NuGet` |
+   | maven | `Maven` |
+
+   - Empty `{}` = no known vulnerabilities → proceed
+   - Response contains `vulns` = **STOP**. Report to user, suggest safe version.
+
+2. **Prepare the lockfile for scanning:**
+
+   ```bash
+   osv-scanner scan -r .
+
+   # Or specific lockfile:
+   osv-scanner scan -L requirements.txt
+   osv-scanner scan -L package-lock.json
+   osv-scanner scan -L Cargo.lock
+   osv-scanner scan -L go.sum
+   ```
+
+3. **Review the scan results:**
+
+   - ❌ **If vulnerabilities are found:** STOP - Do NOT install. Report findings to the user and discuss mitigation options.
+   - ✅ **If scan is clean:** Proceed with installation.
+
+4. **Only after clean scan, install dependencies.**
+
+5. **After installation, rescan the entire project:**
+
+   ```bash
+   osv-scanner scan -r .
+   ```
+
+### Critical Rules
+
+1. **NEVER bypass osv-scanner** - This is a security requirement, not a suggestion
+2. **NEVER install packages without scanning first** - No exceptions
+3. **NEVER ignore osv-scanner warnings** - Always report vulnerabilities to the user
+4. **ALWAYS rescan after installation** - Verify the installed state is secure
+
+### Reporting Format
+
+When vulnerabilities are found, present them clearly and block installation:
+
+```
+⚠️ Found 2 vulnerabilities — installation blocked pending review:
+
+CRITICAL: lodash@4.17.20
+  - GHSA-35jh-r3h4-6jhm: Prototype Pollution
+  - Fix: upgrade to 4.17.21
+
+HIGH: axios@0.21.1
+  - CVE-2021-3749: SSRF
+  - Fix: upgrade to 0.21.2
+
+Upgrade affected packages?
+```
+
+Use `/secops` for the full workflow including lockfile generation and vulnerability ignoring.

package/template/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+## Development Workflow
+
+1. **Task Planning**
+   - Study the existing codebase and understand the current state
+   - Use the **planner** agent to break down complex problems and create implementation roadmaps
+   - Create a plan document in the `/plans` directory for complex features
+   - Update `ROADMAP.md` to include the new task under Development
+   - Priority tasks should be inserted after the last completed task
+
+2. **Ticket Creation**
+   - Study the existing codebase and understand the current state
+   - Create a new ticket file in the `/tickets` directory
+   - Name format: `TICKET-XXX-description.md` (e.g., `TICKET-001-user-auth.md`)
+   - Include high-level specifications, relevant files, acceptance criteria, and implementation steps
+   - Refer to last completed ticket in the `/tickets` directory for examples
+   - Note that completed tickets show checked boxes and summary of changes
+   - For new tickets, use empty checkboxes and no summary section
+
+3. **Task Implementation**
+   - Use the **coder** agent for implementing features, fixing bugs, and optimizing code
+   - Follow the specifications in the ticket file
+   - Implement features and functionality following project conventions
+   - Update step progress within the ticket file after each step
+   - Stop after completing each step and wait for further instructions
+
+4. **Quality Assurance**
+   - Use the **checker** agent for testing, security analysis, and code review
+   - Verify all acceptance criteria are met
+   - Run tests and ensure code quality standards
+   - Document any issues found and their resolutions
+
+5. **Roadmap Updates**
+   - Mark completed tasks with ✅ in the roadmap
+   - Add reference to the ticket file (e.g., `See: /tickets/TICKET-001-user-auth.md`)
+   - Update related plan documents if applicable